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

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 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
 ```
@@ -491,140 +513,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,146 @@
+# 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, 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.
+- 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/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 {
@@ -4855,9 +4856,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 +7707,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 +8379,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 +11750,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
@@ -11746,6 +11806,17 @@ function buildRecoveryHints(error, args = {}) {
     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 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}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "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",