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

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## 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
+  mirror files through `channel recover-workspace --publish-workspace-mirror --leader-account <ACCOUNT> --output <PATH>`.
+
 ## 2.3.4 - 2026-05-29
 
 - Removed the implicit wallet proof context recovery path so proof-backed wallet commands require

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
 ```
@@ -236,10 +258,10 @@ older CLI and does not contain `wallet-index.metadata.json` plus `epochs/<epoch-
 Channel leaders can optionally register a workspace mirror server so users can bootstrap recovery
 from a signed checkpoint and download only the local-to-checkpoint delta when a local recovery index
 already exists. The channel leader can build the static mirror files with
-`channel publish-workspace-mirror` and then deploy the output directory to the registered mirror
-host. If the existing mirror manifest is unreadable or invalid, the leader can use
-`channel publish-workspace-mirror --force` to write a full checkpoint without trusting that remote
-manifest as a delta base. The CLI protocol is documented at
+`channel recover-workspace --publish-workspace-mirror --leader-account <ACCOUNT> --output <PATH>` after
+recovering the channel workspace, and then deploy the output directory to the registered mirror host.
+If the existing mirror manifest is unreadable or invalid, add `--force` to write a full checkpoint
+without trusting that remote manifest as a delta base. The CLI protocol is documented at
 https://github.com/tokamak-network/Tokamak-zk-EVM-contracts/blob/main/docs/dapps/private-state/channel-workspace-mirror-protocol.md.
 
 Back up a local wallet with:
@@ -491,137 +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 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/commands/channel.mjs

@@ -4,14 +4,12 @@ import {
   assertGetChannelArgs,
   assertJoinChannelArgs,
   assertProviderChainIdMatchesNetwork,
-  assertPublishWorkspaceMirrorArgs,
   assertRecoverWorkspaceArgs,
   assertSetWorkspaceMirrorArgs,
   handleChannelCreate,
   handleExitChannel,
   handleGetChannel,
   handleJoinChannel,
-  handlePublishChannelWorkspaceMirror,
   handleSetChannelWorkspaceMirror,
   handleWorkspaceInit,
   loadExplicitCommandRuntime,
@@ -40,11 +38,6 @@ export const channelCommands = Object.freeze({
     const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
     await handleSetChannelWorkspaceMirror({ args, network, provider });
   },
-  "channel-publish-workspace-mirror": async (args) => {
-    assertPublishWorkspaceMirrorArgs(args);
-    const { network, provider } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });
-    await handlePublishChannelWorkspaceMirror({ args, network, provider });
-  },
   "channel-join": async (args) => {
     assertJoinChannelArgs(args);
     const { network, provider, rpcUrl } = loadExplicitCommandRuntime(args, { prepareArtifacts: true });

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

@@ -55,6 +55,15 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     valueLabel: "<NAME>",
     option: "--account",
   },
+  leaderAccount: {
+    label: "Channel Leader Account",
+    type: "text",
+    placeholder: "leader-account",
+    valueLabel: "<ACCOUNT>",
+    hint: "Required with --publish-workspace-mirror. Signs the workspace mirror manifest and must match the on-chain channel leader.",
+    option: "--leader-account",
+    optional: true,
+  },
   txSubmitter: {
     label: "Transaction Submitter",
     type: "text",
@@ -212,6 +221,13 @@ export const PRIVATE_STATE_CLI_FIELD_CATALOG = Object.freeze({
     option: "--output-raw",
     optional: true,
   },
+  publishWorkspaceMirror: {
+    label: "Publish Workspace Mirror",
+    type: "checkbox",
+    hint: "After channel recovery, write the registered workspace mirror manifest, checkpoint, and any delta bundle.",
+    option: "--publish-workspace-mirror",
+    optional: true,
+  },
   source: {
     label: "Recovery Source",
     type: "select",
@@ -330,7 +346,11 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     fields: ["network", "channelName", "account", "wallet"],
     optionalFields: ["network", "channelName", "account", "wallet"],
     usage: "optional --network, --channel-name, --account, and --wallet",
-    help: ["Does not accept --rpc-url and never writes RPC configuration", "Recommends bridge deposits only after a wallet is joined and needs channel liquidity"],
+    help: [
+      "Does not accept --rpc-url and never writes RPC configuration",
+      "Recommends bridge deposits only after a wallet is joined and needs channel liquidity",
+      "Channel leaders publish workspace mirror files through channel recover-workspace --publish-workspace-mirror, not a standalone publish command",
+    ],
   },
   {
     id: "help-observer",
@@ -405,8 +425,9 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     display: "channel recover-workspace",
     description: "Rebuild the local channel workspace from bridge state.",
     installMode: "read-only",
-    fields: ["channelName", "network", "source", "fromGenesis", "outputRaw"],
-    usage: "--channel-name, --network, optional --source, optional --from-genesis, optional --output-raw",
+    fields: ["channelName", "network", "source", "fromGenesis", "outputRaw", "publishWorkspaceMirror", "leaderAccount", "output", "force"],
+    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",
       "--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",
@@ -416,6 +437,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "Use --source rpc --from-genesis to ignore the recovery index and 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",
+      "--publish-workspace-mirror requires --leader-account <ACCOUNT> and --output <PATH>; the leader account signs the mirror manifest and must match the on-chain channel leader",
+      "--force with --publish-workspace-mirror ignores an unreadable or invalid existing mirror manifest and publishes a full checkpoint without a delta",
+      "Workspace mirror publishing does not upload files to a remote server; deploy the output directory to the registered mirror host",
       "Prints RPC log scan progress while rebuilding the workspace",
     ],
   },
@@ -431,20 +456,6 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
       "The URL points to a server implementing the private-state channel workspace mirror protocol",
     ],
   },
-  {
-    id: "channel-publish-workspace-mirror",
-    display: "channel publish-workspace-mirror",
-    description: "Build static workspace mirror files for the registered mirror URL.",
-    installMode: "read-only",
-    fields: ["channelName", "network", "account", "output", "force"],
-    usage: "--channel-name, --network, --account, --output, optional --force",
-    help: [
-      "Requires the local channel workspace to be current and ahead of the registered mirror checkpoint",
-      "--force ignores an unreadable or invalid existing mirror manifest and publishes a full checkpoint without a delta",
-      "Writes manifest.json, checkpoint.zip, and any needed delta bundle under the workspace mirror static path",
-      "Does not upload files to a remote server; deploy the output directory to the registered HTTPS mirror host",
-    ],
-  },
   {
     id: "channel-get-meta",
     display: "channel get-meta",

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 {
@@ -729,6 +730,8 @@ async function handleWorkspaceInit({ args, network, provider }) {
     workspaceDir,
     workspace,
     currentSnapshot,
+    blockInfo,
+    contractCodes,
     cleanRebuildBackup,
     rpcCallHistory,
   } = await syncChannelWorkspace({
@@ -746,6 +749,24 @@ async function handleWorkspaceInit({ args, network, provider }) {
     progressAction: "channel recover-workspace",
   });
 
+  const publishedWorkspaceMirror = args.publishWorkspaceMirror === true
+    ? await publishChannelWorkspaceMirrorFromRecoveredWorkspace({
+      args,
+      network,
+      provider,
+      bridgeResources,
+      channelName,
+      local: {
+        workspace,
+        stateSnapshot: currentSnapshot,
+        blockInfo,
+        contractCodes,
+        recoveryLastScannedBlock: workspace.recoveryLastScannedBlock,
+        recoveryRootVectorHash: workspace.recoveryRootVectorHash,
+      },
+    })
+    : null;
+
   printJson({
     action: "channel recover-workspace",
     source: workspace.recoverySource ?? recoverySource,
@@ -764,6 +785,7 @@ async function handleWorkspaceInit({ args, network, provider }) {
     recoveryScanRange: workspace.recoveryScanRange,
     rpcCallHistory,
     workspaceMirror: workspace.workspaceMirror ?? null,
+    publishedWorkspaceMirror,
   });
 }
 
@@ -875,12 +897,17 @@ async function handleSetChannelWorkspaceMirror({ args, network, provider }) {
   });
 }
 
-async function handlePublishChannelWorkspaceMirror({ args, network, provider }) {
-  const channelName = requireArg(args.channelName, "--channel-name");
+async function publishChannelWorkspaceMirrorFromRecoveredWorkspace({
+  args,
+  network,
+  provider,
+  bridgeResources,
+  channelName,
+  local,
+}) {
   const outputRoot = path.resolve(String(requireArg(args.output, "--output")));
   const force = args.force === true;
-  const signer = requireL1Signer(args, provider);
-  const bridgeResources = loadBridgeResources({ chainId: network.chainId });
+  const { signer, account: leaderAccount } = requireLeaderSigner(args, provider);
   const { bridgeDeployment, bridgeAbiManifest } = bridgeResources;
   const bridgeCore = new Contract(
     bridgeDeployment.bridgeCore,
@@ -906,13 +933,6 @@ async function handlePublishChannelWorkspaceMirror({ args, network, provider })
     channelId,
   });
 
-  const local = await loadPublishableLocalWorkspaceMirrorCheckpoint({
-    channelName,
-    network,
-    provider,
-    bridgeResources,
-    channelInfo,
-  });
   const remote = await readRemoteWorkspaceMirrorCheckpoint({
     manifestUrl,
     chainId: network.chainId,
@@ -927,9 +947,9 @@ async function handlePublishChannelWorkspaceMirror({ args, network, provider })
   expect(
     !remote.exists || Number(local.recoveryLastScannedBlock) > Number(remote.recoveryLastScannedBlock),
     [
-      `Local workspace recovery index ${local.recoveryLastScannedBlock} is not ahead of the registered mirror`,
+      `Recovered workspace index ${local.recoveryLastScannedBlock} is not ahead of the registered mirror`,
       `checkpoint ${remote.exists ? remote.recoveryLastScannedBlock : "<missing>"}.`,
-      "Run channel recover-workspace first if the local workspace is stale.",
+      "No newer workspace mirror checkpoint can be published.",
     ].join(" "),
   );
 
@@ -1023,11 +1043,13 @@ async function handlePublishChannelWorkspaceMirror({ args, network, provider })
   };
   writeJson(publishTarget.manifestPath, manifest);
 
-  printJson({
-    action: "channel publish-workspace-mirror",
+  return {
+    action: "channel recover-workspace publish-workspace-mirror",
     channelName,
     channelId: channelId.toString(),
     force,
+    leaderAccount,
+    leader: getAddress(signer.address),
     outputRoot,
     mirrorDir,
     manifestPath: publishTarget.manifestPath,
@@ -1053,7 +1075,7 @@ async function handlePublishChannelWorkspaceMirror({ args, network, provider })
       sizeBytes: checkpointBundle.bytes.length,
     },
     deltaBundles,
-  });
+  };
 }
 
 function resolveWorkspaceRecoverySource(args) {
@@ -1084,84 +1106,6 @@ async function readChannelWorkspaceMirror({ bridgeCore, channelId }) {
   return String(await bridgeCore.getChannelWorkspaceMirror(channelId));
 }
 
-async function loadPublishableLocalWorkspaceMirrorCheckpoint({
-  channelName,
-  network,
-  provider,
-  bridgeResources,
-  channelInfo,
-}) {
-  const workspaceDir = channelWorkspacePath(networkNameFromChainId(network.chainId), channelName);
-  const existingArtifacts = loadExistingWorkspaceArtifacts(workspaceDir);
-  const workspace = existingArtifacts.workspace;
-  expect(workspace, `Local channel workspace is missing at ${channelWorkspaceConfigPath(workspaceDir)}.`);
-  const stateSnapshot = existingArtifacts.stateSnapshot;
-  expect(stateSnapshot, `Local channel state snapshot is missing under ${channelWorkspaceCurrentPath(workspaceDir)}.`);
-  expect(existingArtifacts.blockInfo, `Local channel block_info.json is missing under ${channelWorkspaceCurrentPath(workspaceDir)}.`);
-  expect(existingArtifacts.contractCodes, `Local channel contract_codes.json is missing under ${channelWorkspaceCurrentPath(workspaceDir)}.`);
-  const channelManager = new Contract(
-    channelInfo.manager,
-    bridgeResources.bridgeAbiManifest.contracts.channelManager.abi,
-    provider,
-  );
-  const [
-    currentRootVectorHash,
-    genesisBlockNumber,
-    latestBlock,
-    managedStorageAddresses,
-  ] = await Promise.all([
-    channelManager.currentRootVectorHash(),
-    channelManager.genesisBlockNumber(),
-    provider.getBlockNumber(),
-    channelManager.getManagedStorageAddresses(),
-  ]);
-  const normalizedManagedStorageAddresses = normalizedAddressVector(managedStorageAddresses);
-  const recoveryIndex = getUsableWorkspaceRecoveryIndex({
-    existingArtifacts,
-    genesisBlockNumber: Number(genesisBlockNumber),
-    latestBlock,
-    managedStorageAddresses: normalizedManagedStorageAddresses,
-  });
-  expect(
-    recoveryIndex,
-    [
-      "Local channel workspace does not contain a usable recovery index.",
-      `Run channel recover-workspace --channel-name ${channelName} --network ${networkNameFromChainId(network.chainId)} first.`,
-    ].join(" "),
-  );
-  expect(
-    canReuseLocalWorkspaceSnapshot({
-      existingArtifacts,
-      currentRootVectorHash,
-      managedStorageAddresses: normalizedManagedStorageAddresses,
-    }),
-    [
-      "Local channel workspace is stale relative to the on-chain channel state.",
-      `Run channel recover-workspace --channel-name ${channelName} --network ${networkNameFromChainId(network.chainId)} first.`,
-    ].join(" "),
-  );
-  expect(Number(workspace.chainId) === Number(network.chainId), "Local workspace chainId does not match --network.");
-  expect(ethers.toBigInt(workspace.channelId) === ethers.toBigInt(deriveChannelIdFromName(channelName)), "Local workspace channelId mismatch.");
-  expect(String(workspace.channelName) === channelName, "Local workspace channelName mismatch.");
-  expect(
-    ethers.toBigInt(getAddress(workspace.channelManager)) === ethers.toBigInt(getAddress(channelInfo.manager)),
-    "Local workspace channelManager mismatch.",
-  );
-  expect(
-    ethers.toBigInt(getAddress(workspace.bridgeTokenVault)) === ethers.toBigInt(getAddress(channelInfo.bridgeTokenVault)),
-    "Local workspace bridgeTokenVault mismatch.",
-  );
-
-  return {
-    workspace,
-    stateSnapshot,
-    blockInfo: existingArtifacts.blockInfo,
-    contractCodes: existingArtifacts.contractCodes,
-    recoveryLastScannedBlock: recoveryIndex.nextBlock,
-    recoveryRootVectorHash: recoveryIndex.recoveryRootVectorHash,
-  };
-}
-
 async function readRemoteWorkspaceMirrorCheckpoint({
   manifestUrl,
   chainId,
@@ -3661,6 +3605,7 @@ async function handleGuide({ args }) {
     why: null,
     candidateCommands: [],
     privacyTip: "For wallet mint-notes, wallet transfer-notes, and wallet redeem-notes, add --tx-submitter <ACCOUNT> to let a separate local L1 account submit executeChannelTransaction and pay gas.",
+    mirrorTip: "Channel leaders refresh mirror files with channel recover-workspace --publish-workspace-mirror --leader-account <ACCOUNT> --output <PATH>; the standalone channel publish-workspace-mirror command is no longer available.",
   };
 
   guide.state.local = inspectGuideLocalState(args);
@@ -4911,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)),
@@ -7755,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());
@@ -8425,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,
@@ -9764,6 +9768,19 @@ function requireL1Signer(args, provider) {
   return new Wallet(resolvePrivateKeySource(args), provider);
 }
 
+function requireLeaderSigner(args, provider) {
+  const networkName = requireNetworkName(args);
+  const account = String(requireArg(args.leaderAccount, "--leader-account")).trim();
+  expect(account.length > 0, "--leader-account requires a local account name.");
+  return {
+    signer: new Wallet(
+      normalizePrivateKey(readSecretFile(accountPrivateKeyPath(networkName, account), "--leader-account")),
+      provider,
+    ),
+    account,
+  };
+}
+
 function resolveTxSubmitterSigner({ args, ownerSigner, provider }) {
   if (args.txSubmitter === undefined) {
     expect(
@@ -10453,9 +10470,25 @@ function assertRecoverWorkspaceArgs(args) {
   const source = resolveWorkspaceRecoverySource(args);
   assertBooleanFlag(args, "fromGenesis", "channel recover-workspace option --from-genesis");
   assertBooleanFlag(args, "outputRaw", "channel recover-workspace option --output-raw");
+  assertBooleanFlag(args, "publishWorkspaceMirror", "channel recover-workspace option --publish-workspace-mirror");
+  assertBooleanFlag(args, "force", "channel recover-workspace option --force");
   if (args.outputRaw === true && source !== "rpc") {
     throw new Error("channel recover-workspace option --output-raw requires --source rpc.");
   }
+  if (args.publishWorkspaceMirror === true) {
+    requireArg(args.leaderAccount, "--leader-account");
+    requireArg(args.output, "--output");
+  } else {
+    if (args.leaderAccount !== undefined) {
+      throw new Error("channel recover-workspace option --leader-account requires --publish-workspace-mirror.");
+    }
+    if (args.output !== undefined) {
+      throw new Error("channel recover-workspace option --output requires --publish-workspace-mirror.");
+    }
+    if (args.force !== undefined) {
+      throw new Error("channel recover-workspace option --force requires --publish-workspace-mirror.");
+    }
+  }
 }
 
 function assertGetChannelArgs(args) {
@@ -10467,12 +10500,6 @@ function assertSetWorkspaceMirrorArgs(args) {
   requireWorkspaceMirrorUrl(args.url);
 }
 
-function assertPublishWorkspaceMirrorArgs(args) {
-  assertAllowedCommandSchema(args, "channel-publish-workspace-mirror");
-  requireArg(args.output, "--output");
-  assertBooleanFlag(args, "force", "channel publish-workspace-mirror option --force");
-}
-
 function assertDepositBridgeArgs(args) {
   assertAllowedCommandSchema(args, "account-deposit-bridge");
   assertActionImpactArg(args, "account deposit-bridge");
@@ -11369,6 +11396,11 @@ function printGuideHumanResult(guide) {
     "Privacy Tip",
     formatHumanValue(guide.privacyTip),
   );
+  lines.push(
+    "",
+    "Mirror Tip",
+    formatHumanValue(guide.mirrorTip),
+  );
   console.log(lines.join("\n"));
 }
 
@@ -11718,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
@@ -11774,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}`);
   }
@@ -11847,7 +11890,6 @@ export {
   assertRecoverWorkspaceArgs,
   assertGetChannelArgs,
   assertSetWorkspaceMirrorArgs,
-  assertPublishWorkspaceMirrorArgs,
   assertDepositBridgeArgs,
   assertWithdrawBridgeArgs,
   assertAccountGetBridgeFundArgs,
@@ -11881,7 +11923,6 @@ export {
   handleWorkspaceInit,
   handleGetChannel,
   handleSetChannelWorkspaceMirror,
-  handlePublishChannelWorkspaceMirror,
   handleDepositBridge,
   handleWithdrawBridge,
   handleAccountGetBridgeFund,

package/package.json

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