Merge pull request #155 from FlowmemoryAI/agent/production-l1-ops

[production-l1] ops implementation snapshot

Author: FlowmemoryAI

docs/FLOWCHAIN_OPERATOR_CHECKLIST.md

@@ -35,10 +35,13 @@ Second-computer readiness check:
 
 ```powershell
 npm run flowchain:prereq
+npm run flowchain:doctor
 npm run flowchain:init
-npm run flowchain:start
+npm run flowchain:node:start -- -MaxBlocks 3 -Wait
+npm run flowchain:node:status
 npm run flowchain:demo
 npm run flowchain:export
+npm run flowchain:production-l1:e2e
 ```
 
 Run `npm run flowchain:full-smoke` when the machine has the full prerequisite set,
@@ -48,6 +51,7 @@ Capped owner pilot preflight:
 
 ```powershell
 npm run flowchain:real-value-pilot:ops
+npm run flowchain:bridge:live:check
 ```
 
 Do not run live pilot actions until the owner has reviewed
@@ -164,6 +168,7 @@ Run before handoff when dependencies are installed:
 ```powershell
 npm run flowchain:smoke
 npm run flowchain:full-smoke
+npm run flowchain:production-l1:e2e
 git diff --check
 ```
 

docs/FLOWCHAIN_SECOND_COMPUTER_SETUP.md

@@ -210,14 +210,20 @@ The final package should provide these root-level commands or documented
 equivalents:
 
 ```powershell
+npm install
+npm install --prefix apps/dashboard
+npm install --prefix crypto
 npm run flowchain:prereq
+npm run flowchain:doctor
 npm run flowchain:init
-npm run flowchain:start
-npm run flowchain:stop
+npm run flowchain:node:start
+npm run flowchain:node:status
+npm run flowchain:node:stop
 npm run flowchain:demo
 npm run flowchain:smoke
 npm run flowchain:full-smoke
 npm run flowchain:product-e2e
+npm run flowchain:production-l1:e2e
 npm run flowchain:real-value-pilot:ops
 npm run flowchain:real-value-pilot:emergency-stop
 npm run flowchain:real-value-pilot:export
@@ -237,6 +243,10 @@ Current status:
 | `npm run flowchain:smoke` | Implemented for current private/local surfaces | Runs service tests, crypto validation, launch candidate, devnet tests, control-plane smoke, deterministic replay, dashboard build, hardware fixture, unsafe-claim scan, and no-secret export scan. |
 | `npm run flowchain:full-smoke` | Implemented acceptance gate | Wraps smoke, wallet CLI sign/verify, full-smoke report, no-secret scan, and `git diff --check`. |
 | `npm run flowchain:product-e2e` | Implemented product testnet gate | Wraps the full smoke and proves local account funding, token launch, DEX pool/liquidity/swap receipts, bridge-test records, control-plane product queries, workbench product surfaces, and no-secret API boundaries. |
+| `npm run flowchain:production-l1:e2e` | Implemented private/local ops wrapper gate | Runs prereq, init, bounded node start/status, wallet, transfer, product, token/DEX, bridge mock, live-readiness refusal, control-plane smoke, dashboard build, export/import, restart recovery, no-secret scan, unsafe-claim scan, and evidence export. |
+| `npm run flowchain:bridge:live:check` | Implemented fail-closed readiness check | Checks Base `8453` readiness only when env names are present; prints names, never values, and broadcasts nothing. |
+| `npm run flowchain:emergency:stop-local` | Implemented emergency local stop wrapper | Requests node stop and prints/manualizes local service stop commands. |
+| `npm run flowchain:emergency:export-evidence` | Implemented secret-scanned evidence export | Writes an ignored local evidence bundle under `devnet/local/production-l1-e2e/evidence/`. |
 | `npm run flowchain:real-value-pilot:ops` | Branch-local dry-run pilot ops proof | Parser-checks pilot scripts, proves dry-run needs no RPC or keys, verifies missing live env refusal, checks emergency-stop dry-run, and writes sanitized evidence export. |
 | `npm run flowchain:real-value-pilot:emergency-stop` | Branch-local guarded pause wrapper | Routes to the live `Pause` action after explicit acknowledgement, Base `8453` chain check, cap check, lockbox address check, and owner key check. |
 | `npm run flowchain:real-value-pilot:export` | Branch-local pilot evidence exporter | Writes a sanitized ignored bundle excluding Git metadata, dependency folders, build targets, local vaults, private-key files, and env files. |
@@ -346,3 +356,36 @@ This setup guide is complete for the HQ/Ops wrapper layer and current
 private/local acceptance gate. The next evidence step is running
 `npm run flowchain:full-smoke` on a clean second computer and recording the
 generated report.
+
+## Current Final Wrapper Path
+
+For the latest ops wrapper proof, use:
+
+```powershell
+npm install
+npm install --prefix apps/dashboard
+npm install --prefix crypto
+npm run flowchain:production-l1:e2e
+```
+
+The command writes:
+
+```text
+devnet/local/production-l1-e2e/flowchain-production-l1-e2e-report.json
+devnet/local/production-l1-e2e/flowchain-production-l1-e2e-summary.md
+devnet/local/production-l1-e2e/evidence/flowchain-production-l1-evidence.zip
+```
+
+For a no-GitHub-login transfer to a second computer, run:
+
+```powershell
+npm run flowchain:second-computer:bundle
+```
+
+Then move the generated zip from `devnet/local/second-computer/` to the second
+machine, extract it, install dependencies, and run:
+
+```powershell
+npm run flowchain:second-computer:verify
+npm run flowchain:production-l1:e2e
+```

docs/FLOWCHAIN_TROUBLESHOOTING.md

@@ -38,6 +38,7 @@ From the repo root:
 
 ```powershell
 npm run flowchain:prereq
+npm run flowchain:doctor
 ```
 
 If that fails, fix the missing prerequisite before running init, demo, smoke,
@@ -64,6 +65,12 @@ or workbench commands.
 | Cargo cannot overwrite a Windows `.exe` under `target` | A running node, old test process, or stale shell is locking Cargo build output. | Run `npm run flowchain:node:stop`, close old PowerShell windows, and retry. If the lock remains, reboot before deleting ignored local build output. |
 | Existing state blocks init | `devnet/local/state.json` already exists. | Run `npm run flowchain:demo`, or force reset with `powershell -NoProfile -ExecutionPolicy Bypass -File infra/scripts/flowchain-init.ps1 -Force`. |
 | Import refuses to overwrite state | Import protects existing local state by default. | Run `npm run flowchain:import -- --BundlePath <zip> -Force`. |
+| Final wrapper says dashboard dependencies are missing | Dashboard package dependencies have not been installed. | Run `npm install --prefix apps/dashboard`. |
+| Final wrapper says crypto package dependencies are missing | Crypto package dependencies have not been installed. | Run `npm install --prefix crypto`. |
+| Final wrapper reports live readiness `blocked` | Live Base pilot env values are intentionally absent. | Run `npm run flowchain:bridge:live:check` after setting the required env names locally. |
+| Final wrapper reports missing strict live proof commands | Contracts, bridge, or runtime proof commands have not merged yet. | Read `devnet/local/production-l1-e2e/flowchain-production-l1-e2e-report.json` and the owner rows for issues #133, #138, and #134. |
+| Evidence export refuses a path | The export stage found an excluded or secret-shaped file. | Move env, vault, key, seed phrase, mnemonic, RPC credential, API key, or webhook files outside the evidence source and rerun `npm run flowchain:emergency:export-evidence`. |
+| Import root mismatch | Restored state does not match the exported root. | Rerun `npm run flowchain:export`, import to a fresh state path, and inspect `devnet/local/production-l1-e2e/export-import-root-compare.json`. |
 
 ## Clean Local Reset
 
@@ -186,6 +193,17 @@ npm run flowchain:real-value-pilot:ops
 | Pause or resume cannot broadcast | `cast` is missing, the owner key is missing, or the key is not the lockbox owner. | Install Foundry, verify `$env:FLOWCHAIN_BASE8453_DEPLOYER_PRIVATE_KEY` in the local shell, and rerun the action. |
 | Evidence export refuses a file | The evidence directory contains an env file, local vault, private-key file, build output, or secret-named path. | Move that file outside the evidence directory and rerun `npm run flowchain:real-value-pilot:export`. |
 
+Current ops readiness check:
+
+```powershell
+npm run flowchain:bridge:live:check
+```
+
+This command refuses missing acknowledgement, missing RPC URL, wrong Base chain
+ID, missing or malformed lockbox, missing token address when token mode requires
+one, missing or oversized caps, unsafe confirmation depth, and broad block
+ranges. It prints env names only.
+
 ## Smoke Evidence
 
 After a successful smoke run, check:

docs/agent-runs/production-l1-ops/BACKUP_RESTORE_PROOF.md

@@ -0,0 +1,24 @@
+# Backup Restore Proof
+
+Commands:
+
+```powershell
+npm run flowchain:export
+npm run flowchain:import -- --BundlePath devnet/local/export/flowchain-local-state.zip -StatePath devnet/local/production-l1-e2e/imported-state.json -Force
+npm run flowchain:restart:verify
+```
+
+Latest comparison:
+
+```text
+Original state root: 0x21be07858c24cc2ecb99fd5d2d0240aa251e13a0910455397855a993b549db6d
+Imported state root: 0x21be07858c24cc2ecb99fd5d2d0240aa251e13a0910455397855a993b549db6d
+Status: passed
+```
+
+Evidence:
+
+- `devnet/local/export/flowchain-local-state.zip`
+- `devnet/local/production-l1-e2e/export-import-root-compare.json`
+- `devnet/local/node-smoke/one-node-smoke-report.json`
+

docs/agent-runs/production-l1-ops/BASE_PILOT_GATE_PROOF.md

@@ -0,0 +1,51 @@
+# Base Pilot Gate Proof
+
+Readiness command:
+
+```powershell
+npm run flowchain:bridge:live:check
+```
+
+Latest readiness status:
+
+```text
+status: blocked
+baseChainId: 8453
+broadcasts: false
+printsEnvValues: false
+```
+
+Missing env names:
+
+- `FLOWCHAIN_PILOT_OPERATOR_ACK`
+- `FLOWCHAIN_BASE8453_RPC_URL`
+- `FLOWCHAIN_BASE8453_LOCKBOX_ADDRESS`
+- `FLOWCHAIN_BASE8453_FROM_BLOCK`
+- `FLOWCHAIN_BASE8453_TO_BLOCK`
+- `FLOWCHAIN_PILOT_MAX_DEPOSIT_WEI`
+- `FLOWCHAIN_PILOT_TOTAL_CAP_WEI`
+- `FLOWCHAIN_BASE8453_CONFIRMATION_DEPTH`
+
+Optional token-mode env names:
+
+- `FLOWCHAIN_BASE8453_TOKEN_MODE`
+- `FLOWCHAIN_BASE8453_SUPPORTED_TOKEN`
+
+Refusal rules implemented:
+
+- Missing acknowledgement blocks readiness.
+- Missing RPC URL blocks readiness.
+- Wrong `eth_chainId` fails readiness; expected Base `8453`.
+- Missing or malformed lockbox address blocks or fails readiness.
+- Token mode requires a supported token address.
+- Missing, zero, negative, or oversized caps fail readiness.
+- Missing or unsafe confirmation depth blocks or fails readiness.
+- Broad block ranges fail readiness.
+- The check never prints live env values.
+
+Strict live pilot proof remains incomplete until these commands exist:
+
+- `npm run flowchain:real-value-pilot:contracts`
+- `npm run flowchain:real-value-pilot:bridge`
+- `npm run flowchain:real-value-pilot:runtime`
+

docs/agent-runs/production-l1-ops/CHECKLIST.md

@@ -0,0 +1,15 @@
+# Private/Local Ops Wrapper Checklist
+
+- [x] Read `AGENTS.md`.
+- [x] Read `docs/START_HERE.md`.
+- [x] Read `docs/FLOWMEMORY_HQ_CONTEXT.md`.
+- [x] Read `docs/CURRENT_STATE.md`.
+- [x] Read FlowChain second-computer, troubleshooting, and operator docs.
+- [x] Read Rootflow, Flow Memory, and launch acceptance docs.
+- [x] Inventory existing scripts and root commands.
+- [x] Add missing tracking and proof docs.
+- [x] Add final `flowchain:production-l1:e2e` command with explicit non-production boundaries.
+- [x] Add command aliases for install, lifecycle, wallet, bridge, dashboard, storage, and emergency paths.
+- [x] Add parser checks for changed PowerShell scripts.
+- [x] Run required gates and record reports.
+- [x] Write handoff.

docs/agent-runs/production-l1-ops/COMMAND_MATRIX.md

@@ -0,0 +1,46 @@
+# Command Matrix
+
+Boundary: `flowchain:production-l1:e2e` is a private/local ops wrapper command. It does not claim production readiness or live-funds readiness.
+
+| Command | Owner | Subsystem | Latest status | Evidence |
+| --- | --- | --- | --- | --- |
+| `npm run flowchain:prereq` | installer | install/prereq | passed | final report step `Prerequisite check` |
+| `npm run flowchain:doctor` | ops | install/config/status | passed | `devnet/local/doctor/flowchain-doctor-report.json` |
+| `npm run flowchain:init` | runtime/storage | local state | passed | final report step `Initialize local state` |
+| `npm run flowchain:second-computer:bundle` | ops | offline bundle | command exists | `infra/scripts/flowchain-second-computer-bundle.ps1` |
+| `npm run flowchain:second-computer:verify` | ops | second computer | command exists | `infra/scripts/flowchain-second-computer-verify.ps1` |
+| `npm run flowchain:node:start` | runtime | node lifecycle | passed in bounded mode | final report step `Node start bounded` |
+| `npm run flowchain:node:stop` | runtime | node lifecycle | command exists | existing stop wrapper |
+| `npm run flowchain:node:status` | runtime | node lifecycle | passed | final report step `Node status` |
+| `npm run flowchain:node:restart` | runtime | node lifecycle | command exists | `infra/scripts/flowchain-node-restart.ps1` |
+| `npm run flowchain:node:logs` | runtime/ops | observability | command exists | `infra/scripts/flowchain-node-logs.ps1` |
+| `npm run flowchain:wallet:e2e` | wallet/crypto | wallet | passed | `devnet/local/production-l1-e2e/wallet-e2e-report.json` |
+| `npm run flowchain:wallet:transfer:e2e` | wallet/runtime | transfer | passed | `devnet/local/production-l1-e2e/wallet-transfer/wallet-transfer-e2e-report.json` |
+| `npm run flowchain:product:e2e` | runtime/product | product flow | passed with `-SkipFullSmoke` after baseline | `devnet/local/product-e2e/flowchain-product-e2e-report.json` |
+| `npm run flowchain:dex:e2e` | runtime/token-dex | token/DEX | passed | `devnet/local/production-l1-e2e/dex/dex-e2e-report.json` |
+| `npm run flowchain:bridge:mock:e2e` | bridge-relayer | mock bridge | passed | final report step `Bridge mock pilot E2E` |
+| `npm run flowchain:bridge:live:check` | bridge/ops | Base 8453 readiness | blocked on env | `devnet/local/production-l1-e2e/bridge-live-readiness-report.json` |
+| `npm run flowchain:bridge:evidence:export` | ops/security | evidence | passed through emergency alias | `devnet/local/production-l1-e2e/evidence/flowchain-production-l1-evidence-export-report.json` |
+| `npm run flowchain:bridge:emergency-stop` | bridge/ops | emergency | command exists | guarded pause wrapper |
+| `npm run flowchain:control-plane:smoke` | control-plane | RPC/API | passed | final report step `Control-plane smoke` |
+| `npm run flowchain:dashboard:build` | dashboard | workbench | passed | final report step `Dashboard build` |
+| `npm run flowchain:dashboard:verify` | dashboard | workbench | command exists | build-backed verification |
+| `npm run flowchain:export` | storage | backup/export | passed | final report step `Export local state` |
+| `npm run flowchain:import` | storage | restore/import | passed | final report step `Import local state` |
+| `npm run flowchain:restart:verify` | runtime/storage | restart recovery | passed | `devnet/local/node-smoke/one-node-smoke-report.json` |
+| `npm run flowchain:l1:e2e` | integration | full local gate | passed | `devnet/local/full-smoke/flowchain-full-smoke-report.json` |
+| `npm run flowchain:l1-e2e` | integration | compatibility alias | passed | explicit verification run passed |
+| `npm run flowchain:real-value-pilot:e2e` | HQ/ops + subsystem owners | live pilot proof | incomplete by design | missing contracts, bridge-relayer, and runtime proof commands |
+| `npm run flowchain:production-l1:e2e` | ops | final wrapper | passed with live blockers | `devnet/local/production-l1-e2e/flowchain-production-l1-e2e-report.json` |
+| `npm run flowchain:no-secret:scan` | security | secret hygiene | passed | `devnet/local/production-l1-e2e/no-secret-scan-report.json` |
+| `npm run flowchain:emergency:stop-local` | ops | emergency | command exists | stop-node plus port stop plan |
+| `npm run flowchain:emergency:pause-bridge` | bridge/ops | emergency | command exists | guarded Base 8453 pause wrapper |
+| `npm run flowchain:emergency:export-evidence` | ops/security | emergency/evidence | passed | evidence export report |
+| `npm run flowchain:emergency:print-recovery` | ops | emergency/recovery | command exists | recovery report script |
+
+Missing strict live-pilot proof commands:
+
+- `flowchain:real-value-pilot:contracts`, owner `contracts`, reason: chain ID, lockbox, caps, pause, release/recovery, and replay proof; GitHub issue #133.
+- `flowchain:real-value-pilot:bridge`, owner `bridge-relayer`, reason: Base observation, deterministic credit, duplicate handling, and withdrawal/release evidence; GitHub issue #138.
+- `flowchain:real-value-pilot:runtime`, owner `chain-runtime`, reason: credit-once, restart, export/import preservation; GitHub issue #134.
+

docs/agent-runs/production-l1-ops/EMERGENCY_DRILL_PROOF.md

@@ -0,0 +1,28 @@
+# Emergency Drill Proof
+
+Drill command set:
+
+```powershell
+npm run flowchain:emergency:stop-local
+npm run flowchain:bridge:emergency-stop
+npm run flowchain:emergency:export-evidence
+npm run flowchain:emergency:print-recovery
+```
+
+Local stop behavior:
+
+- Requests the local node stop file through the runtime wrapper.
+- Lists control-plane/dashboard process stop commands for ports `8787` and `5173`.
+- Can stop known port processes when the underlying script is run with `-StopKnownPorts`.
+
+Bridge pause behavior:
+
+- Routes through `flowchain-real-value-pilot-emergency-stop.ps1`.
+- Live mode requires Base 8453 env, acknowledgement, caps, lockbox, and owner key.
+- Dry-run mode is covered by `npm run flowchain:real-value-pilot:ops`.
+
+Evidence:
+
+- Final evidence export passed.
+- Recovery commands are printed by `npm run flowchain:emergency:print-recovery`.
+

docs/agent-runs/production-l1-ops/EMERGENCY_PROOF.md

@@ -0,0 +1,27 @@
+# Emergency Proof
+
+Emergency command family:
+
+```powershell
+npm run flowchain:emergency:stop-local
+npm run flowchain:bridge:emergency-stop
+npm run flowchain:emergency:pause-bridge
+npm run flowchain:emergency:export-evidence
+npm run flowchain:emergency:print-recovery
+```
+
+What each command does:
+
+- `flowchain:emergency:stop-local`: requests local node stop and prints/manualizes control-plane and dashboard port stop commands unless `-StopKnownPorts` is explicitly passed to the script.
+- `flowchain:bridge:emergency-stop`: routes to the guarded Base 8453 pause action.
+- `flowchain:emergency:pause-bridge`: same guarded pause path.
+- `flowchain:emergency:export-evidence`: writes a secret-scanned evidence bundle.
+- `flowchain:emergency:print-recovery`: writes and prints recovery commands.
+
+Latest evidence export:
+
+```text
+Bundle: devnet/local/production-l1-e2e/evidence/flowchain-production-l1-evidence.zip
+Status: passed
+SHA256: 45295F89EDAAA1BFDCE7EE4A1E16AF285554CD12B2166682F456A353333B79FD
+```

docs/agent-runs/production-l1-ops/EXPERIMENTS.md

@@ -0,0 +1,15 @@
+# Private/Local Ops Wrapper Experiments
+
+This file records commands run while building the `flowchain:production-l1:e2e` ops wrapper. The wrapper is a private/local gate and does not claim production readiness.
+
+| Time | Command | Result | Notes |
+| --- | --- | --- | --- |
+| 2026-05-14 | `npm install`; `npm install --prefix apps/dashboard`; `npm install --prefix crypto` | passed | Installed local dependencies needed for strict smoke and dashboard build. |
+| 2026-05-14 | PowerShell parser checks for changed scripts | passed | Parser checked new/changed ops scripts. |
+| 2026-05-14 | `npm run flowchain:wallet:transfer:e2e` | passed | Local test-unit transfer recorded in devnet state. |
+| 2026-05-14 | `npm run flowchain:dex:e2e` | passed | Product smoke proved token and DEX records. |
+| 2026-05-14 | `npm run flowchain:production-l1:e2e` | passed with live blockers | Mock path passed; live Base pilot blocked on env and missing proof commands. |
+| 2026-05-14 | `npm run flowchain:l1-e2e` | passed | Explicit compatibility alias verification. |
+| 2026-05-14 | `npm run flowchain:real-value-pilot:e2e` | incomplete | Strict live pilot gate blocked by missing contracts, bridge, and runtime proof commands. |
+| 2026-05-14 | `node infra/scripts/check-unsafe-claims.mjs` | passed | Claim scan clean. |
+| 2026-05-14 | `git diff --check` | passed | Whitespace check clean. |