@tokamak-private-dapps/private-state-cli 2.4.0 → 2.4.2

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## Unreleased
 
+## 2.4.2 - 2026-05-30
+
+- Changed channel workspace recovery guidance so CLI help, guide output, agent instructions, and documentation direct
+  users to registered workspace mirrors before explicit RPC genesis rebuilds.
+
+## 2.4.1 - 2026-05-30
+
+- Classified `UnexpectedCurrentRootVector()` submit reverts as stale channel-root failures with recovery hints that
+  tell agents to refresh workspace state, re-check affected wallet state, and regenerate the original intended proof
+  without changing command semantics.
+- Moved LLM-agent operating guidance from the CLI README into package-shipped `agents.md`.
+- Generalized the CLI README's LLM-agent summary to refer to error-response policy instead of naming one revert.
+- Added private-state CLI install prerequisites to the README while delegating Tokamak zk-EVM CLI prerequisites to that
+  package's README.
+
 ## 2.4.0 - 2026-05-29
 
 - Removed the standalone `channel publish-workspace-mirror` command. Channel leaders now publish

package/README.md

@@ -47,6 +47,28 @@ UTC.
 
 ## Install
 
+### Prerequisites
+
+Before installing this package, prepare the private-state CLI prerequisites:
+
+- Node.js 18 or newer and npm for installing and running `private-state-cli`.
+- Outbound HTTPS access to the npm registry, the public private-state deployment artifact index, and the public
+  Groth16 CRS archive source.
+- A writable home-directory workspace under `~/tokamak-private-channels/` for private-state artifacts, Groth16
+  workspace files, account secrets, wallet key files, channel workspaces, and proof outputs.
+- For `private-state-cli install --read-only`, no proof runtime prerequisites are needed because read-only mode installs
+  only public bridge and private-state DApp artifacts.
+- For `private-state-cli install --include-local-artifacts`, run the command from a repository or deployment workspace
+  that contains the local `deployment/` artifacts you intentionally want to install.
+- For `private-state-cli install --docker`, the private-state Groth16 Docker path requires Docker to be installed and
+  running. The Groth16 Docker path is supported on Linux hosts and Windows hosts with Docker Desktop; macOS hosts should
+  use the native Groth16 path.
+
+Full `private-state-cli install` also installs and invokes `@tokamak-zk-evm/cli`. The operating-system, native build
+toolchain, Docker, CUDA, and network prerequisites for the Tokamak zk-EVM CLI are intentionally not duplicated here.
+Read the [`@tokamak-zk-evm/cli` README](https://github.com/tokamak-network/Tokamak-zk-EVM/tree/main/packages/cli#readme)
+before running full install, especially when using `--docker` or a GPU-enabled host.
+
 ```bash
 npm install -g @tokamak-private-dapps/private-state-cli
 ```
@@ -177,7 +199,14 @@ unless the user explicitly understands the compliance implications. Prefer a sel
 
 Workspace recovery commands use saved recovery indexes by default. If the local channel workspace is missing,
 corrupted, or does not contain a usable index, `channel recover-workspace` stops with an explicit error instead of
-silently replaying logs from channel genesis. Use `channel recover-workspace --source rpc --from-genesis` only when
+silently replaying logs from channel genesis. When the channel has a registered workspace mirror, recover from the
+mirror first:
+
+```bash
+private-state-cli channel recover-workspace --channel-name <CHANNEL> --network mainnet --source mirror
+```
+
+Use `channel recover-workspace --source rpc --from-genesis` only when no compatible workspace mirror is available and
 you intentionally want to rebuild channel workspace state from the channel creation block:
 
 ```bash
@@ -204,9 +233,9 @@ existing history, while `--from-genesis` overwrites it with one full genesis-to-
 by replaying from the channel's genesis block because no prior recovery index can exist for a new channel.
 
 `channel join` refreshes stale channel workspace state through the saved recovery index before submitting the
-registration transaction. For a channel that was created elsewhere, run `channel recover-workspace --source rpc --from-genesis`
-once before joining, or recover from a registered workspace mirror; later joins and wallet commands resume from the
-saved index instead of silently replaying from genesis.
+registration transaction. For a channel that was created elsewhere, recover from a registered workspace mirror first.
+Use `channel recover-workspace --source rpc --from-genesis` only when no compatible mirror is available; later joins
+and wallet commands resume from the saved index instead of silently replaying from genesis.
 
 Wallet commands that need channel state, including `wallet recover-workspace`, `wallet get-meta`,
 `wallet get-channel-fund`, and `wallet get-notes`, refresh stale local channel workspaces through saved recovery
@@ -491,140 +520,9 @@ possible.
 
 ## LLM Agent Guidance
 
-You may act as an interactive guide for users who do not understand this CLI or the private-state DApp. Assume the
-user wants to use confidential channel-local notes while keeping L1 bridge deposits and withdrawals transparent.
-Translate the user's intent into safe, step-by-step CLI actions.
-
-Primary goal: help the user safely use private-state note workflows: self-custody L1 funding, channel-local note
-creation, note transfer, note recovery, and user-controlled disclosure where supported. Present this
-as privacy-preserving note semantics for the current `private-state` DApp, not as invisible
-activity or as a bridge-wide disclosure rule for every DApp.
-
-Operating rules:
-
-- Do not ask the user to reveal raw private keys or wallet secrets in chat. Use `account import --private-key-file`
-  once, then use `--account` for L1 signing commands. Wallet viewing and spending authority is imported separately
-  with `wallet import viewing-key` and `wallet import spending-key`.
-- Treat `private key file`, `account`, `wallet secret`, `wallet`, `network RPC URL`, and `channel policy` as
-  new concepts unless the user has already demonstrated that they understand them. Define each term before using it
-  in an instruction.
-- Explain local-secret handling in plain language:
-  - A private key file is a local file that contains the user's L1 wallet private key. The CLI reads it once during
-    `account import` and stores a protected local account secret.
-  - An account is the local nickname created by `account import`. After import, signing commands should use
-    `--account <NAME>` instead of asking for the raw key again.
-  - A wallet secret source file is a separate high-entropy local secret chosen by the user for this private-state
-    wallet. It is not the L1 private key. `channel join` reads it once for channel-bound spending-key derivation and
-    does not persist it in the wallet workspace.
-  - A wallet is the local private-state metadata set created during `channel join`. Its deterministic name is
-    `<channelName>-<l1Address>`. The wallet backup tracks encrypted note state, while viewing and spending authority
-    are stored in separate protected key files.
-  - A viewing key decrypts encrypted note-delivery events for the registered note-receive public key. A spending key is
-    the channel-bound L2 private key used to authorize note use. Do not describe either key as interchangeable with the
-    other.
-  - The network RPC URL is the endpoint used to read and write chain state. It must be configured once with
-    `private-state-cli set rpc --network <NETWORK> --rpc-url <URL> --provider <PROVIDER>`, or with explicit
-    `--log-requests-per-second` and `--block-range-cap` values when the provider is not built in.
-  - A workspace recovery index is the saved block pointer and state-root hash that lets the CLI resume log scanning
-    without replaying the channel from its creation block. If it is missing, explain `--from-genesis` before using it
-    because genesis replay can take much longer.
-- Before guiding a user to run `channel recover-workspace --source rpc --from-genesis`, explain that RPC genesis
-  recovery can be very slow because it scans channel logs from the creation block. If a channel workspace mirror is
-  available, try mirror-based recovery first, and use RPC genesis replay only when mirror recovery is unavailable or
-  unsuitable.
-- When the user asks about gas use, transaction fees, transaction cost, or USD cost for private-state CLI commands, run
-  `private-state-cli help transaction-fees --network <NETWORK> --json` and answer from the returned `rows`. If the
-  network is unclear, ask which network to use. Do not tell the user to ask the developer unless the command fails after
-  following the CLI's printed corrective guidance.
-- When `channel recover-workspace` or `wallet recover-workspace` is unexpectedly slow, first inspect the RPC provider
-  configured by `set rpc`. Explain that recovery speed is dominated by `eth_getLogs` block range cap and log request
-  rate. Suggest re-running `set rpc` with a provider that supports a larger block range cap, such as Ankr or Chainnodes
-  when appropriate, or with explicit `--log-requests-per-second` and `--block-range-cap` values from the provider's
-  documentation.
-- When a channel leader needs to refresh workspace mirror files, guide them to run
-  `channel recover-workspace --publish-workspace-mirror --leader-account <ACCOUNT> --output <PATH>`. The standalone
-  `channel publish-workspace-mirror` command is no longer available.
-- When a CLI command fails, read the error message and any printed `Try:` hints first. Prefer the corrective action
-  suggested by the CLI before inventing a different recovery sequence.
-- When the user does not have a network RPC URL yet, explain that they need an Ethereum JSON-RPC endpoint for the
-  selected network. They can obtain one from an infrastructure provider such as Alchemy, Ankr, Chainstack, Chainnodes,
-  QuickNode, or from their own node. Ask the user to create or select the endpoint in that provider's UI, then paste only
-  the endpoint URL into `private-state-cli set rpc`; do not ask for provider account passwords, API dashboards, seed
-  phrases, private keys, or wallet secrets.
-- When a user wants to join a channel, do not jump straight to `channel join`. Walk them through:
-  1. choose the network and channel name
-  2. run `private-state-cli install`
-  3. run `private-state-cli help doctor`
-  4. obtain or confirm a network RPC URL for the selected network
-  5. run `set rpc --network <NETWORK> --rpc-url <URL> --provider <PROVIDER>`, or use explicit scan limits for an
-     unlisted provider
-  6. prepare a private key source file locally, without pasting the key into chat
-  7. run `account import --account <NAME> --network <NETWORK> --private-key-file <PATH>`
-  8. prepare a wallet secret source file locally, for example with `openssl rand -hex 32 > ./wallet-secret.txt`
-  9. inspect the channel with `channel get-meta` if it already exists, or create it with `channel create` if the user is
-     the channel creator
-  10. explain the immutable policy warning and that the join toll is paid directly from the L1 wallet, not bridge-deposited balance
-  11. run `channel join --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH> --acknowledge-action-impact`
-- Before executing any command for a user that requires an `--acknowledge-*` option, strongly warn the user in plain
-  language about what that acknowledgement means and ask for explicit confirmation. Do not add
-  `--acknowledge-action-impact` or `--acknowledge-full-note-plaintext-export` on the user's behalf until they confirm.
-  For `--acknowledge-action-impact`, explain the command's public/private action-impact summary. For
-  `--acknowledge-full-note-plaintext-export`, explain that all locally known note plaintext will be written into the
-  exported ZIP.
-- Before asking the user to create a file, explain what will be inside that file, who should be able to read it, and
-  whether losing it prevents wallet recovery.
-- Prefer testnet examples unless the user explicitly asks for mainnet.
-- Before any proof-backed or bridge-facing workflow, ask the user to run `private-state-cli help doctor` and inspect
-  whether the runtime, Docker mode, CUDA/GPU probes, Groth16 runtime, and deployment artifacts are healthy.
-- Use `private-state-cli wallet list` to discover local wallet names instead of asking the user to inspect
-  filesystem paths manually.
-- Use `private-state-cli account get-l1-address --account <ACCOUNT> --network <NETWORK>` to derive the L1 address
-  for a local account when wallet ownership needs to be identified.
-- Use `private-state-cli wallet get-meta --wallet <WALLET> --network <NETWORK>` to inspect
-  local wallet metadata and on-chain channel registration state.
-- Use `private-state-cli account get-bridge-fund` and `private-state-cli wallet get-channel-fund` to check balances before
-  telling the user to move funds.
-- Explain that wallet names are local CLI identifiers, while confidential note transfers use notes owned by L2 addresses
-  registered in the channel.
-- Explain `--tx-submitter <ACCOUNT>` when the user wants a separate L1 transaction submitter for `wallet mint-notes`,
-  `wallet transfer-notes`, or `wallet redeem-notes`: the wallet owner still proves note ownership, but another imported
-  local L1 account can submit the on-chain `executeChannelTransaction` and pay gas.
-- Before guiding a user through `channel create` or `channel join`, explain that channel policy is immutable after
-  creation and that joining a channel means accepting its current verifier, DApp metadata, function layout, managed
-  storage vector, and refund policy.
-- Do not present one fixed command sequence as universally correct. Some flows start from an existing channel or wallet,
-  while others require creating or joining a channel first.
-- When the user asks for a transfer, first determine whether the sender has minted notes available. If not, guide them
-  through joining or recovering the channel wallet, funding the bridge for channel liquidity, depositing into the channel, and minting notes.
-- When generating commands, use placeholders for secrets and explicit values for public fields. Show one command at a
-  time unless the user asks for a batch.
-
-Suggested interaction flow:
-
-1. Identify the target network, usually `sepolia` for testing.
-2. Identify whether a channel already exists.
-3. Identify the sender and recipient wallets or local account names.
-4. Run `help doctor`.
-5. Run `wallet list` and relevant metadata or balance checks.
-6. If needed, guide the user through `channel create`, `channel join`, `account deposit-bridge`, `wallet deposit-channel`, and
-   `wallet mint-notes`.
-7. For a confidential note transfer, select available note IDs from `wallet get-notes`, find the recipient L2 address from
-   `wallet get-meta`, then build `wallet transfer-notes` with JSON arrays for `--note-ids`, `--recipients`, and `--amounts`.
-8. After transfer, guide the recipient to run `wallet get-notes`; it refreshes received notes from the saved recovery index when the delta fits the 7,200-block pre-command budget. If the index is missing or too far behind, explain `wallet recover-workspace`.
-
-Example onboarding explanation for `channel join`:
-
-> First we need two different local secrets. Your L1 private key proves which Ethereum account pays gas and signs
-> bridge transactions. We import it once into a local account nickname, so later commands can say `--account alice`
-> instead of handling the raw key again. Separately, the wallet secret source derives the channel-bound spending key
-> during `channel join`. It is not sent on-chain, it is not the same as your L1 private key, and the CLI does not store
-> it in the wallet workspace. A wallet backup restores encrypted tracking state; the viewing key restores note
-> readability; the spending key restores note spendability.
-
-Example style: if the user says, "ADDR6 sends 10 tokens privately to ADDR8", do not assume the required note exists.
-First ask or check which channel and network to use, whether ADDR6 and ADDR8 are already joined, what the local wallet
-names are, and whether ADDR6 has an unused note worth exactly 10 or notes that sum to 10. Then provide the next concrete
-command.
+LLM agents that guide users through this CLI should read [`agents.md`](agents.md) before suggesting or running
+commands. That file contains the agent-specific operating rules, including secret-handling boundaries, onboarding
+sequence, acknowledgement handling, recovery behavior, and error-response policy.
 
 ## Artifacts
 

package/agents.md

@@ -0,0 +1,147 @@
+# private-state CLI Agent Instructions
+
+These instructions are for LLM agents that guide users through the `private-state-cli` package.
+
+You may act as an interactive guide for users who do not understand this CLI or the private-state DApp. Assume the
+user wants to use confidential channel-local notes while keeping L1 bridge deposits and withdrawals transparent.
+Translate the user's intent into safe, step-by-step CLI actions.
+
+Primary goal: help the user safely use private-state note workflows: self-custody L1 funding, channel-local note
+creation, note transfer, note recovery, and user-controlled disclosure where supported. Present this
+as privacy-preserving note semantics for the current `private-state` DApp, not as invisible
+activity or as a bridge-wide disclosure rule for every DApp.
+
+## Operating Rules
+
+- Do not ask the user to reveal raw private keys or wallet secrets in chat. Use `account import --private-key-file`
+  once, then use `--account` for L1 signing commands. Wallet viewing and spending authority is imported separately
+  with `wallet import viewing-key` and `wallet import spending-key`.
+- Treat `private key file`, `account`, `wallet secret`, `wallet`, `network RPC URL`, and `channel policy` as
+  new concepts unless the user has already demonstrated that they understand them. Define each term before using it
+  in an instruction.
+- Explain local-secret handling in plain language:
+  - A private key file is a local file that contains the user's L1 wallet private key. The CLI reads it once during
+    `account import` and stores a protected local account secret.
+  - An account is the local nickname created by `account import`. After import, signing commands should use
+    `--account <NAME>` instead of asking for the raw key again.
+  - A wallet secret source file is a separate high-entropy local secret chosen by the user for this private-state
+    wallet. It is not the L1 private key. `channel join` reads it once for channel-bound spending-key derivation and
+    does not persist it in the wallet workspace.
+  - A wallet is the local private-state metadata set created during `channel join`. Its deterministic name is
+    `<channelName>-<l1Address>`. The wallet backup tracks encrypted note state, while viewing and spending authority
+    are stored in separate protected key files.
+  - A viewing key decrypts encrypted note-delivery events for the registered note-receive public key. A spending key is
+    the channel-bound L2 private key used to authorize note use. Do not describe either key as interchangeable with the
+    other.
+  - The network RPC URL is the endpoint used to read and write chain state. It must be configured once with
+    `private-state-cli set rpc --network <NETWORK> --rpc-url <URL> --provider <PROVIDER>`, or with explicit
+    `--log-requests-per-second` and `--block-range-cap` values when the provider is not built in.
+  - A workspace recovery index is the saved block pointer and state-root hash that lets the CLI resume log scanning
+    without replaying the channel from its creation block. If it is missing, check whether the channel has a registered
+    workspace mirror before explaining or using `--from-genesis`, because genesis replay can take much longer.
+- Before guiding a user to run `channel recover-workspace --source rpc --from-genesis`, explain that RPC genesis
+  recovery can be very slow because it scans channel logs from the creation block. Run or suggest
+  `channel get-meta --channel-name <CHANNEL> --network <NETWORK>` first; if `workspaceMirror` is set, try
+  `channel recover-workspace --channel-name <CHANNEL> --network <NETWORK> --source mirror`. Use RPC genesis replay only
+  when no compatible workspace mirror is available.
+- When the user asks about gas use, transaction fees, transaction cost, or USD cost for private-state CLI commands, run
+  `private-state-cli help transaction-fees --network <NETWORK> --json` and answer from the returned `rows`. If the
+  network is unclear, ask which network to use. Do not tell the user to ask the developer unless the command fails after
+  following the CLI's printed corrective guidance.
+- When `channel recover-workspace` or `wallet recover-workspace` is unexpectedly slow, first inspect the RPC provider
+  configured by `set rpc`. Explain that recovery speed is dominated by `eth_getLogs` block range cap and log request
+  rate. Suggest re-running `set rpc` with a provider that supports a larger block range cap, such as Ankr or Chainnodes
+  when appropriate, or with explicit `--log-requests-per-second` and `--block-range-cap` values from the provider's
+  documentation.
+- When a channel leader needs to refresh workspace mirror files, guide them to run
+  `channel recover-workspace --publish-workspace-mirror --leader-account <ACCOUNT> --output <PATH>`. The standalone
+  `channel publish-workspace-mirror` command is no longer available.
+- When a CLI command fails, read the error message and any printed `Try:` hints first. Prefer the corrective action
+  suggested by the CLI before inventing a different recovery sequence.
+- Treat `UnexpectedCurrentRootVector()` as a stale channel-root or stale-proof failure, not as evidence that the
+  command shape is wrong. Do not recover by changing recipients, changing amounts, changing note counts, changing
+  function arity, or splitting one intended transfer into multiple transfers. Refresh the channel workspace, re-check
+  affected wallet state such as notes and balances, then rerun the user's original intended command so the CLI
+  regenerates a proof from the fresh snapshot. If the original notes or balances are no longer usable after refresh,
+  ask the user to choose a new plan instead of silently substituting one.
+- When the user does not have a network RPC URL yet, explain that they need an Ethereum JSON-RPC endpoint for the
+  selected network. They can obtain one from an infrastructure provider such as Alchemy, Ankr, Chainstack, Chainnodes,
+  QuickNode, or from their own node. Ask the user to create or select the endpoint in that provider's UI, then paste only
+  the endpoint URL into `private-state-cli set rpc`; do not ask for provider account passwords, API dashboards, seed
+  phrases, private keys, or wallet secrets.
+- When a user wants to join a channel, do not jump straight to `channel join`. Walk them through:
+  1. choose the network and channel name
+  2. run `private-state-cli install`
+  3. run `private-state-cli help doctor`
+  4. obtain or confirm a network RPC URL for the selected network
+  5. run `set rpc --network <NETWORK> --rpc-url <URL> --provider <PROVIDER>`, or use explicit scan limits for an
+     unlisted provider
+  6. prepare a private key source file locally, without pasting the key into chat
+  7. run `account import --account <NAME> --network <NETWORK> --private-key-file <PATH>`
+  8. prepare a wallet secret source file locally, for example with `openssl rand -hex 32 > ./wallet-secret.txt`
+  9. inspect the channel with `channel get-meta` if it already exists, or create it with `channel create` if the user is
+     the channel creator
+  10. explain the immutable policy warning and that the join toll is paid directly from the L1 wallet, not bridge-deposited balance
+  11. run `channel join --channel-name <CHANNEL> --network <NETWORK> --account <ACCOUNT> --wallet-secret-path <PATH> --acknowledge-action-impact`
+- Before executing any command for a user that requires an `--acknowledge-*` option, strongly warn the user in plain
+  language about what that acknowledgement means and ask for explicit confirmation. Do not add
+  `--acknowledge-action-impact` or `--acknowledge-full-note-plaintext-export` on the user's behalf until they confirm.
+  For `--acknowledge-action-impact`, explain the command's public/private action-impact summary. For
+  `--acknowledge-full-note-plaintext-export`, explain that all locally known note plaintext will be written into the
+  exported ZIP.
+- Before asking the user to create a file, explain what will be inside that file, who should be able to read it, and
+  whether losing it prevents wallet recovery.
+- Prefer testnet examples unless the user explicitly asks for mainnet.
+- Before any proof-backed or bridge-facing workflow, ask the user to run `private-state-cli help doctor` and inspect
+  whether the runtime, Docker mode, CUDA/GPU probes, Groth16 runtime, and deployment artifacts are healthy.
+- Use `private-state-cli wallet list` to discover local wallet names instead of asking the user to inspect
+  filesystem paths manually.
+- Use `private-state-cli account get-l1-address --account <ACCOUNT> --network <NETWORK>` to derive the L1 address
+  for a local account when wallet ownership needs to be identified.
+- Use `private-state-cli wallet get-meta --wallet <WALLET> --network <NETWORK>` to inspect
+  local wallet metadata and on-chain channel registration state.
+- Use `private-state-cli account get-bridge-fund` and `private-state-cli wallet get-channel-fund` to check balances before
+  telling the user to move funds.
+- Explain that wallet names are local CLI identifiers, while confidential note transfers use notes owned by L2 addresses
+  registered in the channel.
+- Explain `--tx-submitter <ACCOUNT>` when the user wants a separate L1 transaction submitter for `wallet mint-notes`,
+  `wallet transfer-notes`, or `wallet redeem-notes`: the wallet owner still proves note ownership, but another imported
+  local L1 account can submit the on-chain `executeChannelTransaction` and pay gas.
+- Before guiding a user through `channel create` or `channel join`, explain that channel policy is immutable after
+  creation and that joining a channel means accepting its current verifier, DApp metadata, function layout, managed
+  storage vector, and refund policy.
+- Do not present one fixed command sequence as universally correct. Some flows start from an existing channel or wallet,
+  while others require creating or joining a channel first.
+- When the user asks for a transfer, first determine whether the sender has minted notes available. If not, guide them
+  through joining or recovering the channel wallet, funding the bridge for channel liquidity, depositing into the channel, and minting notes.
+- When generating commands, use placeholders for secrets and explicit values for public fields. Show one command at a
+  time unless the user asks for a batch.
+
+## Suggested Interaction Flow
+
+1. Identify the target network, usually `sepolia` for testing.
+2. Identify whether a channel already exists.
+3. Identify the sender and recipient wallets or local account names.
+4. Run `help doctor`.
+5. Run `wallet list` and relevant metadata or balance checks.
+6. If needed, guide the user through `channel create`, `channel join`, `account deposit-bridge`, `wallet deposit-channel`, and
+   `wallet mint-notes`.
+7. For a confidential note transfer, select available note IDs from `wallet get-notes`, find the recipient L2 address from
+   `wallet get-meta`, then build `wallet transfer-notes` with JSON arrays for `--note-ids`, `--recipients`, and `--amounts`.
+8. After transfer, guide the recipient to run `wallet get-notes`; it refreshes received notes from the saved recovery index when the delta fits the 7,200-block pre-command budget. If the index is missing or too far behind, explain `wallet recover-workspace`.
+
+## Example Onboarding Explanation For `channel join`
+
+> First we need two different local secrets. Your L1 private key proves which Ethereum account pays gas and signs
+> bridge transactions. We import it once into a local account nickname, so later commands can say `--account alice`
+> instead of handling the raw key again. Separately, the wallet secret source derives the channel-bound spending key
+> during `channel join`. It is not sent on-chain, it is not the same as your L1 private key, and the CLI does not store
+> it in the wallet workspace. A wallet backup restores encrypted tracking state; the viewing key restores note
+> readability; the spending key restores note spendability.
+
+## Example Style
+
+If the user says, "ADDR6 sends 10 tokens privately to ADDR8", do not assume the required note exists.
+First ask or check which channel and network to use, whether ADDR6 and ADDR8 are already joined, what the local wallet
+names are, and whether ADDR6 has an unused note worth exactly 10 or notes that sum to 10. Then provide the next concrete
+command.

package/lib/private-state-cli-command-registry.mjs

@@ -210,7 +210,7 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
   fromGenesis: {
     label: "Scan From Genesis",
     type: "checkbox",
-    hint: "Requires --source rpc. Ignore the local recovery index and replay channel logs from genesis.",
+    hint: "Requires --source rpc. Use only when no compatible workspace mirror is available and a full genesis replay is intentional.",
     option: "--from-genesis",
     optional: true,
   },
@@ -233,7 +233,7 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     type: "select",
     options: ["rpc", "mirror"],
     valueLabel: "<rpc|mirror>",
-    hint: "Optional. Defaults to rpc. mirror validates the channel leader's checkpoint manifest and downloads only the needed checkpoint or delta bundle before RPC delta replay.",
+    hint: "Use mirror first when a channel workspace mirror is registered. If omitted, the CLI uses rpc and resumes from the local recovery index when available.",
     option: "--source",
     optional: true,
   },
@@ -429,12 +429,13 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     optionalFields: ["source", "fromGenesis", "outputRaw", "publishWorkspaceMirror", "leaderAccount", "output", "force"],
     usage: "--channel-name, --network, optional --source, optional --from-genesis, optional --output-raw, optional --publish-workspace-mirror with --leader-account and --output, optional --force",
     help: [
-      "By default, --source rpc resumes RPC log scanning from the workspace recovery index when available",
+      "When a channel workspace mirror is registered, try --source mirror before an explicit RPC genesis rebuild",
       "--source mirror validates the channel leader's registered checkpoint manifest, downloads only the needed checkpoint or delta bundle, and then replays RPC logs to latest",
+      "If --source is omitted, the CLI uses rpc and resumes RPC log scanning from the workspace recovery index when available",
       "RPC recovery writes a usable channel workspace checkpoint after each RPC log chunk, so interrupted runs can resume from the last completed chunk",
       "Mirror recovery uses a matching delta bundle when available; otherwise a newer verified full checkpoint replaces the local checkpoint before RPC catch-up",
       "Fails instead of falling back to genesis when no usable recovery index exists",
-      "Use --source rpc --from-genesis to ignore the recovery index and replay logs from channel genesis",
+      "Use --source rpc --from-genesis only when no compatible workspace mirror is available and you intentionally want to replay logs from channel genesis",
       "--output-raw with --source rpc appends raw JSON-RPC request and response history to method-specific JSON files under the channel workspace rpcCallHistory directory; eth_getLogs is split by event",
       "--from-genesis moves the existing local channel workspace to workspace-rebuild-backups before writing the current-format workspace; local secrets are preserved",
       "--publish-workspace-mirror writes manifest.json, checkpoint.zip, and any needed delta bundle after recovery",
@@ -524,7 +525,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "--channel-name, --network, --account, --wallet-secret-path, --acknowledge-action-impact",
     help: [
       "Refreshes the local channel workspace through the saved recovery index before joining when the scan fits the 7,200-block pre-command budget",
-      "Fails instead of replaying from genesis; run channel recover-workspace --source rpc --from-genesis when a genesis rebuild is required",
+      "Fails instead of replaying from genesis; recover from a registered workspace mirror first, and use channel recover-workspace --source rpc --from-genesis only when no compatible mirror is available",
       "--wallet-secret-path is read once for channel-bound L2 spending-key derivation and is not stored in the wallet workspace",
       "Pays any join toll directly from the L1 wallet, not from bridge-deposited balance",
       "Prints the immutable policy snapshot before first registration",

package/lib/runtime.mjs

@@ -165,6 +165,7 @@ const CLI_ERROR_CODES = Object.freeze({
   MISSING_DEPLOYMENT_ARTIFACTS: "MISSING_DEPLOYMENT_ARTIFACTS",
   MISSING_CHANNEL_REGISTRATION: "MISSING_CHANNEL_REGISTRATION",
   STALE_WORKSPACE: "STALE_WORKSPACE",
+  STALE_CHANNEL_ROOT: "STALE_CHANNEL_ROOT",
 });
 
 class PrivateStateCliError extends Error {
@@ -2060,7 +2061,8 @@ async function syncChannelWorkspace({
     throw new Error([
       `Workspace recovery index is missing or unusable for channel ${channelName} on ${networkNameFromChainId(network.chainId)}.`,
       "The CLI will not fall back to replaying channel logs from genesis unless explicitly requested.",
-      "Run channel recover-workspace first to refresh the local channel workspace.",
+      `If a workspace mirror is registered, run channel recover-workspace --channel-name ${channelName} --network ${networkNameFromChainId(network.chainId)} --source mirror first.`,
+      `Use channel recover-workspace --channel-name ${channelName} --network ${networkNameFromChainId(network.chainId)} --source rpc --from-genesis only when no compatible mirror is available.`,
     ].join(" "));
   }
   const workspaceBase = {
@@ -3872,12 +3874,14 @@ async function inspectGuideChannel({ channelName, network, provider, artifactsIn
         bridgeResources.bridgeAbiManifest.contracts.channelManager.abi,
         provider,
       );
-      const [joinToll, refundSchedule] = await Promise.all([
+      const [joinToll, refundSchedule, workspaceMirror] = await Promise.all([
         channelManager.joinToll(),
         readChannelRefundSchedule(channelManager),
+        readChannelWorkspaceMirror({ bridgeCore, channelId }),
       ]);
       result.onchain.joinTollBaseUnits = joinToll.toString();
       result.onchain.refundSchedule = refundSchedule;
+      result.onchain.workspaceMirror = workspaceMirror;
     }
   } catch (error) {
     result.error = error.message;
@@ -4053,9 +4057,19 @@ function applyGuideNextAction(guide) {
     return;
   }
   if (guide.selectors.channelName && guide.state.channel?.onchain?.exists && !guide.state.channel?.local?.workspaceExists) {
+    const workspaceMirror = typeof guide.state.channel.onchain.workspaceMirror === "string"
+      ? guide.state.channel.onchain.workspaceMirror.trim()
+      : "";
+    if (workspaceMirror) {
+      setGuideNextAction(guide, {
+        command: `channel recover-workspace --channel-name ${guide.selectors.channelName} --network ${guide.selectors.network} --source mirror`,
+        why: "The channel has a registered workspace mirror. Use mirror recovery before considering an explicit RPC genesis rebuild.",
+      });
+      return;
+    }
     setGuideNextAction(guide, {
       command: `channel recover-workspace --channel-name ${guide.selectors.channelName} --network ${guide.selectors.network} --source rpc --from-genesis`,
-      why: "The channel exists on-chain, but the local channel workspace has not been recovered yet, so there is no local recovery index to resume from.",
+      why: "The channel exists on-chain, but the local channel workspace has not been recovered yet and no workspace mirror is registered. RPC genesis rebuild is the remaining explicit bootstrap path.",
     });
     return;
   }
@@ -4855,9 +4869,16 @@ async function handleGrothVaultMove({ args, provider, direction }) {
   const methodName = direction === "deposit" ? "depositToChannelVault" : "withdrawFromChannelVault";
   await assertWorkspaceAlignedWithChain(context);
   emitProgress(operationName, "submitting");
-  const receipt = await waitForReceipt(
-    await bridgeTokenVault[methodName](ethers.toBigInt(context.workspace.channelId), transition.proof, transition.update),
-  );
+  const receipt = await submitProofBackedRootUpdate({
+    context,
+    walletName: walletContext.walletName,
+    operationName,
+    submit: () => bridgeTokenVault[methodName](
+      ethers.toBigInt(context.workspace.channelId),
+      transition.proof,
+      transition.update,
+    ),
+  });
   const onchainRootVectorHash = normalizeBytes32Hex(await context.channelManager.currentRootVectorHash());
   expect(
     onchainRootVectorHash === normalizeBytes32Hex(hashRootVector(transition.nextSnapshot.stateRoots)),
@@ -7699,10 +7720,12 @@ async function executeWalletTemplateSend({
 
   await assertWorkspaceAlignedWithChain(context);
   emitProgress(operationName, "submitting");
-  const receipt =
-    await waitForReceipt(
-      await context.channelManager.connect(txSubmitter).executeChannelTransaction(payload, functionProof),
-    );
+  const receipt = await submitProofBackedRootUpdate({
+    context,
+    walletName: wallet.walletName,
+    operationName,
+    submit: () => context.channelManager.connect(txSubmitter).executeChannelTransaction(payload, functionProof),
+  });
   await waitForProviderBlockAtLeast(provider, receipt.blockNumber, { action: operationName });
 
   const onchainRootVectorHash = normalizeBytes32Hex(await context.channelManager.currentRootVectorHash());
@@ -8369,6 +8392,56 @@ function isContractError(error, contractInterface, errorName) {
   return false;
 }
 
+function isUnexpectedCurrentRootVectorError(error, context) {
+  if (isContractError(error, context.channelManager.interface, "UnexpectedCurrentRootVector")) {
+    return true;
+  }
+  return String(error?.message ?? error).includes("UnexpectedCurrentRootVector");
+}
+
+async function submitProofBackedRootUpdate({
+  context,
+  walletName,
+  operationName,
+  submit,
+}) {
+  try {
+    return await waitForReceipt(await submit());
+  } catch (error) {
+    if (isUnexpectedCurrentRootVectorError(error, context)) {
+      throw staleChannelRootError({
+        cause: error,
+        context,
+        walletName,
+        operationName,
+      });
+    }
+    throw error;
+  }
+}
+
+function staleChannelRootError({
+  cause,
+  context,
+  walletName,
+  operationName,
+}) {
+  const message = [
+    `${operationName} failed because the submitted proof was generated for an older channel root.`,
+    "The rejected proof cannot be reused.",
+    "Do not change recipients, amounts, note counts, function arity, or split the command as recovery.",
+    "Refresh the channel workspace, re-check affected wallet state when the command uses notes, then rerun the original intended command so the CLI regenerates a proof from a fresh snapshot.",
+  ].join(" ");
+  const error = cliError(CLI_ERROR_CODES.STALE_CHANNEL_ROOT, message, { cause });
+  error.channelName = context.workspace.channelName;
+  error.networkName = context.workspace.network;
+  error.walletName = walletName;
+  error.retryPolicy = "recover_workspace_then_regenerate_proof";
+  error.semanticMutationAllowed = false;
+  error.reuseProofAllowed = false;
+  return error;
+}
+
 function extractContractErrorDataCandidates(error) {
   return [
     error?.data,
@@ -11690,16 +11763,16 @@ function buildRecoveryHints(error, args = {}) {
   const hints = [];
   const networkName = typeof args.network === "string" && args.network.length > 0
     ? args.network
-    : "<NETWORK>";
+    : error?.networkName ?? "<NETWORK>";
   const channelName = typeof args.channelName === "string" && args.channelName.length > 0
     ? args.channelName
-    : "<CHANNEL>";
+    : error?.channelName ?? "<CHANNEL>";
   const accountName = typeof args.account === "string" && args.account.length > 0
     ? args.account
     : "<ACCOUNT>";
   const walletName = typeof args.wallet === "string" && args.wallet.length > 0
     ? args.wallet
-    : extractUnknownWalletName(message) ?? "<WALLET>";
+    : error?.walletName ?? extractUnknownWalletName(message) ?? "<WALLET>";
 
   if (
     error?.code === CLI_ERROR_CODES.MISSING_RPC_URL
@@ -11742,12 +11815,29 @@ function buildRecoveryHints(error, args = {}) {
   }
 
   if (error?.code === CLI_ERROR_CODES.STALE_WORKSPACE) {
-    hints.push(`private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`private-state-cli channel get-meta --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`if workspaceMirror is set: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName} --source mirror`);
+    hints.push(`otherwise use indexed RPC recovery: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName}`);
     hints.push(`private-state-cli help guide --network ${networkName} --channel-name ${channelName}`);
   }
 
+  if (
+    error?.code === CLI_ERROR_CODES.STALE_CHANNEL_ROOT
+    || message.includes("UnexpectedCurrentRootVector")
+  ) {
+    hints.push(`private-state-cli channel get-meta --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`if workspaceMirror is set: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName} --source mirror`);
+    hints.push(`otherwise use indexed RPC recovery: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName}`);
+    if (walletName !== "<WALLET>") {
+      hints.push(`private-state-cli wallet get-notes --wallet ${walletName} --network ${networkName}`);
+    }
+    hints.push("rerun the original proof-backed command unchanged so the CLI regenerates a fresh proof");
+  }
+
   if (message.includes("Workspace recovery index is missing or unusable")) {
-    hints.push(`private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`private-state-cli channel get-meta --channel-name ${channelName} --network ${networkName}`);
+    hints.push(`if workspaceMirror is set: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName} --source mirror`);
+    hints.push(`only if no compatible workspace mirror is available: private-state-cli channel recover-workspace --channel-name ${channelName} --network ${networkName} --source rpc --from-genesis`);
   }
 
   if (message.includes("Wallet note recovery index is missing or unusable")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",
@@ -26,6 +26,7 @@
   },
   "files": [
     "README.md",
+    "agents.md",
     "CHANGELOG.md",
     "LICENSE",
     "private-state-bridge-cli.mjs",