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

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## 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

package/README.md

@@ -199,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
@@ -226,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

package/agents.md

@@ -37,12 +37,13 @@ activity or as a bridge-wide disclosure rule for every DApp.
     `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.
+    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. 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.
+  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

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

@@ -2061,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 = {
@@ -3873,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;
@@ -4054,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;
   }
@@ -11802,7 +11815,9 @@ 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}`);
   }
 
@@ -11810,7 +11825,9 @@ function buildRecoveryHints(error, args = {}) {
     error?.code === CLI_ERROR_CODES.STALE_CHANNEL_ROOT
     || message.includes("UnexpectedCurrentRootVector")
   ) {
-    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}`);
     if (walletName !== "<WALLET>") {
       hints.push(`private-state-cli wallet get-notes --wallet ${walletName} --network ${networkName}`);
     }
@@ -11818,7 +11835,9 @@ function buildRecoveryHints(error, args = {}) {
   }
 
   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.1",
+  "version": "2.4.2",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",