@tokamak-private-dapps/private-state-cli 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 1.0.2 - 2026-05-06
+
+- Added `update`, which checks npm registry for the latest private-state CLI package and updates
+  global npm installs when a newer version exists.
+- Kept repository checkouts and non-global installs read-only during `update`; those modes print
+  the exact `npm install -g @tokamak-private-dapps/private-state-cli@latest` command instead.
+- Reused runtime-management output parsing helpers for `update` and `uninstall` instead of
+  duplicating npm JSON and ANSI-output handling in the CLI entrypoint.
 - Added `transaction-fees`, which reads packaged measured gas data from `assets/tx-fees.json`,
   combines it with live RPC fee data and live ETH/USD pricing, and prints a per-command ETH/USD
   fee table.
@@ -15,6 +23,12 @@
   guiding new users through `join-channel`.
 - Added RPC log scan progress output to `recover-workspace` and `recover-wallet`, with progress
   routed to stderr in `--json` mode so machine-readable command results stay valid.
+- Added `recover-wallet --from-genesis` and removed implicit genesis replay fallback from
+  `recover-workspace` and `recover-wallet`; both commands now require a usable recovery index
+  unless the user explicitly requests `--from-genesis`.
+- Changed `get-my-wallet-meta`, `get-my-channel-fund`, and `get-my-notes` to use indexed
+  recovery only before reading channel state, with `get-my-notes` also validating the wallet
+  note-receive recovery index before scanning delivery logs.
 - Unified wallet command workspace refresh through the same recovery-indexed path used by
   `recover-workspace`, and shared received-note recovery through the wallet's
   `noteReceiveLastScannedBlock` index.

package/README.md

@@ -57,6 +57,16 @@ Print only the installed CLI package version with:
 private-state-cli --version
 ```
 
+Check npm registry for a newer CLI package and update a global npm install when possible:
+
+```bash
+private-state-cli update
+```
+
+`update` keeps `--version` suitable for scripts by using a separate command for registry checks. If the CLI is running
+from a repository checkout or npm does not report a global install, it does not edit local source files; it prints the
+recommended `npm install -g @tokamak-private-dapps/private-state-cli@latest` command instead.
+
 Remove all local private-state CLI data with:
 
 ```bash
@@ -86,6 +96,24 @@ A common private-state flow is:
 
 Use `private-state-cli --help` for the full command list and required options.
 
+Workspace recovery commands use the saved recovery index by default. If the local workspace is missing, corrupted, or
+does not contain a usable index, `recover-workspace` and `recover-wallet` stop with an explicit error instead of
+silently replaying logs from channel genesis. Use `--from-genesis` only when you intentionally want to rebuild from the
+channel creation block:
+
+```bash
+private-state-cli recover-workspace --channel-name <CHANNEL> --network mainnet --from-genesis
+private-state-cli recover-wallet --channel-name <CHANNEL> --network mainnet --account <ACCOUNT> --from-genesis
+```
+
+`create-channel` is the exception: after the channel is created on-chain, the CLI initializes that new local workspace
+by replaying from the channel's genesis block because no prior recovery index can exist for a new channel.
+
+Wallet getter commands that need channel state, including `get-my-wallet-meta`, `get-my-channel-fund`, and
+`get-my-notes`, follow the same indexed recovery rule before reading local or on-chain state. `get-my-notes` also uses
+the wallet's saved note-receive scan index for encrypted note delivery logs. If either index is unusable, the command
+stops and asks the user to run the appropriate recovery command with `--from-genesis`.
+
 Estimate live transaction costs before sending commands with:
 
 ```bash
@@ -205,6 +233,9 @@ Operating rules:
     `<channelName>-<l1Address>`.
   - The network RPC URL is the endpoint used to read and write chain state. It can be supplied once with `--rpc-url`
     on a bridge-facing command, after which the CLI saves it under the selected network.
+  - 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.
 - 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, Infura, 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

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

@@ -167,6 +167,16 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     fields: [],
     usage: "no options",
   },
+  {
+    id: "update",
+    description: "Check npm registry for the latest private-state CLI package and update global installs when possible.",
+    fields: ["json"],
+    usage: "optional --json",
+    help: [
+      "Global npm installs are updated with npm install -g when a newer registry version exists",
+      "Repository checkouts and non-global installs print the required update command instead of modifying source files",
+    ],
+  },
   {
     id: "doctor",
     description: "Check private-state CLI package versions, runtime install state, Docker mode, CUDA mode, and deployment artifacts.",
@@ -207,7 +217,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Create a bridge channel and initialize its workspace.",
     fields: ["channelName", "joinToll", "network", "account", "rpcUrl"],
     usage: "--channel-name, --join-toll, --network, --account, and optional --rpc-url",
-    help: ["Prints the immutable policy snapshot before sending the transaction"],
+    help: [
+      "Prints the immutable policy snapshot before sending the transaction",
+      "Initializes the local channel workspace by replaying channel logs from channel genesis",
+    ],
   },
   {
     id: "recover-workspace",
@@ -216,6 +229,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     usage: "--channel-name, --network, optional --from-genesis, and optional --rpc-url",
     help: [
       "By default, resumes RPC log scanning from the workspace recovery index when available",
+      "Fails instead of falling back to genesis when no usable recovery index exists",
       "Use --from-genesis to ignore the recovery index and replay logs from channel genesis",
       "Prints RPC log scan progress while rebuilding the workspace",
     ],
@@ -247,11 +261,14 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
   {
     id: "recover-wallet",
     description: "Rebuild a recoverable local wallet from on-chain channel state.",
-    fields: ["channelName", "network", "account", "rpcUrl"],
-    usage: "--channel-name, --network, --account, and optional --rpc-url",
+    fields: ["channelName", "network", "account", "fromGenesis", "rpcUrl"],
+    usage: "--channel-name, --network, --account, optional --from-genesis, and optional --rpc-url",
     help: [
       "Requires the protected wallet-local secret imported during join-channel to exist at the canonical secret path",
       "Does not create or recover the wallet secret itself",
+      "By default, resumes RPC log scanning from the workspace recovery index when available",
+      "Fails instead of falling back to genesis when no usable recovery index exists",
+      "Use --from-genesis to ignore the recovery index and replay channel logs from channel genesis",
       "Prints RPC log scan progress while rebuilding channel state and received-note state",
     ],
   },
@@ -270,6 +287,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Check whether a wallet matches the on-chain channel registration.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
+    help: ["Refreshes channel state through the workspace recovery index before reading registration metadata"],
   },
   {
     id: "get-my-l1-address",
@@ -301,6 +319,7 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Read the current channel L2 accounting balance.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
+    help: ["Refreshes channel state through the workspace recovery index before reading the L2 accounting balance"],
   },
   {
     id: "exit-channel",
@@ -334,6 +353,10 @@ export const PRIVATE_STATE_CLI_COMMANDS = Object.freeze([
     description: "Show the wallet's tracked note state and refresh received notes.",
     fields: ["wallet", "network"],
     usage: "--wallet and --network",
+    help: [
+      "Refreshes channel state through the workspace recovery index before reading notes",
+      "Refreshes received-note logs through the wallet note recovery index",
+    ],
   },
 ]);
 

package/lib/private-state-runtime-management.mjs

@@ -1300,9 +1300,11 @@ export {
   installGroth16RuntimeForPrivateState,
   installPrivateStateCliArtifacts,
   writePrivateStateCliInstallManifest,
+  parseJsonReport,
   resolveArtifactCacheBaseRoot,
   privateStateCliArtifactPaths,
   inspectGroth16Runtime,
+  stripAnsi,
   resolveActiveGroth16ProverRuntime,
   resolveActiveTokamakCliInvocation,
   readTokamakCliPackageReport,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokamak-private-dapps/private-state-cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Command-line client for the Tokamak private-state DApp.",
   "license": "MIT OR Apache-2.0",
   "author": "Tokamak Network",

package/private-state-bridge-cli.mjs

@@ -68,6 +68,7 @@ import {
   installPrivateStateCliArtifacts,
   installTokamakCliRuntimeForPrivateState,
   inspectGroth16Runtime,
+  parseJsonReport,
   printDoctorHumanReport,
   privateStateCliArtifactPaths,
   readTokamakCliPackageReport,
@@ -77,6 +78,7 @@ import {
   resolveArtifactCacheBaseRoot,
   resolvePrivateStateInstallRuntimeVersions,
   resolveTokamakCliResourceDirForRuntimeRoot,
+  stripAnsi,
   writePrivateStateCliInstallManifest,
 } from "./lib/private-state-runtime-management.mjs";
 import {
@@ -127,6 +129,7 @@ const secretRoot = path.resolve(os.homedir(), "tokamak-private-channels", "secre
 const flatDeploymentArtifactPathsByChainId = new Map();
 const PRIVATE_STATE_UNINSTALL_CONFIRMATION =
   "I understand that the wallet secrets deleted due to this decision cannot be recovered";
+const PRIVATE_STATE_CLI_PACKAGE_NAME = privateStateCliPackageJson.name;
 const GROTH16_PACKAGE_NAME = "@tokamak-private-dapps/groth16";
 const TOKAMAK_ZKEVM_CLI_PACKAGE_NAME = "@tokamak-zk-evm/cli";
 let jsonOutputRequested = false;
@@ -338,6 +341,12 @@ async function main() {
     return;
   }
 
+  if (args.command === "update") {
+    assertUpdateArgs(args);
+    await handleUpdate();
+    return;
+  }
+
   if (args.command === "doctor") {
     assertDoctorArgs(args);
     await handleDoctor({ args });
@@ -525,6 +534,8 @@ async function handleChannelCreate({ args, network, provider }) {
     provider,
     bridgeResources,
     persist: true,
+    fromGenesis: true,
+    progressAction: "create-channel",
   });
 
   printJson({
@@ -822,6 +833,13 @@ async function initializeChannelWorkspace({
       managedStorageAddresses,
     })
     : null;
+  if (useWorkspaceRecoveryIndex && !fromGenesis && !localSnapshotReusable && !recoveryIndex) {
+    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 recover-workspace --from-genesis or recover-wallet --from-genesis to rebuild from channel genesis.",
+    ].join(" "));
+  }
   const reconstruction = localSnapshotReusable
     ? {
       currentSnapshot: existingArtifacts.stateSnapshot,
@@ -993,6 +1011,7 @@ async function handleRecoverWallet({ args, network, provider, rpcUrl }) {
     persist: true,
     allowExistingWorkspaceSync: true,
     useWorkspaceRecoveryIndex: true,
+    fromGenesis: args.fromGenesis === true,
     progressAction: "recover-wallet",
   });
   const context = {
@@ -1423,31 +1442,44 @@ function assertSafeManagedRoot(rootPath, label) {
   }
 }
 
-function uninstallGlobalPrivateStateCliPackage() {
-  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
-  const list = runCaptured(npmCommand, ["ls", "-g", "@tokamak-private-dapps/private-state-cli", "--depth=0", "--json"]);
-  if (list.status !== 0) {
-    const listReport = parseJsonReport(list.stdout);
+function npmCommandName() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function inspectGlobalPrivateStateCliPackage() {
+  const list = runCaptured(npmCommandName(), ["ls", "-g", PRIVATE_STATE_CLI_PACKAGE_NAME, "--depth=0", "--json"]);
+  const report = parseJsonReport(list.stdout);
+  const packageReport = report?.dependencies?.[PRIVATE_STATE_CLI_PACKAGE_NAME] ?? null;
+  const installed = Boolean(packageReport);
+  if (!installed) {
     const missing = /empty|missing|not found|not installed/iu.test(`${list.stdout}\n${list.stderr}`);
     return {
-      attempted: false,
       installed: false,
-      reason: missing || listReport ? "global package is not installed" : "unable to inspect global npm package",
+      version: null,
       status: list.status,
+      reason: missing || report ? "global package is not installed" : "unable to inspect global npm package",
       stderr: stripAnsi(list.stderr).trim(),
     };
   }
-  const report = parseJsonReport(list.stdout);
-  const installed = Boolean(report?.dependencies?.["@tokamak-private-dapps/private-state-cli"]);
-  if (!installed) {
+  return {
+    installed: true,
+    version: packageReport.version ?? null,
+    status: list.status,
+  };
+}
+
+function uninstallGlobalPrivateStateCliPackage() {
+  const inspection = inspectGlobalPrivateStateCliPackage();
+  if (!inspection.installed) {
     return {
       attempted: false,
       installed: false,
-      reason: "global package is not installed",
-      status: list.status,
+      reason: inspection.reason,
+      status: inspection.status,
+      stderr: inspection.stderr,
     };
   }
-  const uninstall = runCaptured(npmCommand, ["uninstall", "-g", "@tokamak-private-dapps/private-state-cli"]);
+  const uninstall = runCaptured(npmCommandName(), ["uninstall", "-g", PRIVATE_STATE_CLI_PACKAGE_NAME]);
   return {
     attempted: true,
     installed: true,
@@ -1458,6 +1490,106 @@ function uninstallGlobalPrivateStateCliPackage() {
   };
 }
 
+async function handleUpdate() {
+  const currentVersion = privateStateCliPackageJson.version;
+  const latestVersion = await fetchLatestPrivateStateCliVersion();
+  const registryComparison = compareSemver(currentVersion, latestVersion);
+  const globalPackage = inspectGlobalPrivateStateCliPackage();
+  const runningFromRepositoryCheckout = isRepositoryCliPackageRoot(privateStateCliPackageRoot);
+  const updateAvailable = registryComparison < 0;
+
+  const result = {
+    action: "update",
+    packageName: PRIVATE_STATE_CLI_PACKAGE_NAME,
+    currentVersion,
+    latestVersion,
+    updateAvailable,
+    registryState: registryComparison > 0 ? "local-version-ahead-of-registry" : "normal",
+    runningFromRepositoryCheckout,
+    globalPackage,
+    attempted: false,
+    updated: false,
+    command: `npm install -g ${PRIVATE_STATE_CLI_PACKAGE_NAME}@latest`,
+  };
+
+  if (!updateAvailable) {
+    printJson(result);
+    return;
+  }
+
+  if (runningFromRepositoryCheckout) {
+    printJson({
+      ...result,
+      reason: "running from a repository checkout; update the checkout with git/npm instead of mutating source files",
+    });
+    return;
+  }
+
+  if (!globalPackage.installed) {
+    printJson({
+      ...result,
+      reason: "global npm package is not installed; install or update the CLI with the printed command",
+    });
+    return;
+  }
+
+  const install = runCaptured(npmCommandName(), ["install", "-g", `${PRIVATE_STATE_CLI_PACKAGE_NAME}@latest`]);
+  if (install.status !== 0) {
+    throw new Error([
+      `Unable to update ${PRIVATE_STATE_CLI_PACKAGE_NAME} to ${latestVersion}.`,
+      stripAnsi(install.stderr || install.stdout).trim(),
+    ].filter(Boolean).join(" "));
+  }
+  printJson({
+    ...result,
+    attempted: true,
+    updated: true,
+    installedVersion: latestVersion,
+    stdout: stripAnsi(install.stdout).trim(),
+    stderr: stripAnsi(install.stderr).trim(),
+  });
+}
+
+async function fetchLatestPrivateStateCliVersion() {
+  const url = `https://registry.npmjs.org/${encodeURIComponent(PRIVATE_STATE_CLI_PACKAGE_NAME)}/latest`;
+  const response = await fetch(url, {
+    redirect: "follow",
+    signal: typeof globalThis.AbortSignal?.timeout === "function" ? globalThis.AbortSignal.timeout(10_000) : undefined,
+  });
+  if (!response.ok) {
+    throw new Error(`Unable to fetch ${PRIVATE_STATE_CLI_PACKAGE_NAME} latest version from npm registry: HTTP ${response.status}.`);
+  }
+  const metadata = await response.json();
+  const version = metadata?.version;
+  if (typeof version !== "string" || version.trim() === "") {
+    throw new Error(`npm registry response for ${PRIVATE_STATE_CLI_PACKAGE_NAME} did not include a version.`);
+  }
+  return version;
+}
+
+function compareSemver(left, right) {
+  const parse = (value) => String(value).split("-", 1)[0].split(".").map((part) => {
+    const parsed = Number.parseInt(part, 10);
+    return Number.isFinite(parsed) ? parsed : 0;
+  });
+  const leftParts = parse(left);
+  const rightParts = parse(right);
+  const length = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0; index < length; index += 1) {
+    const delta = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
+    if (delta !== 0) {
+      return delta < 0 ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+function isRepositoryCliPackageRoot(packageRoot) {
+  const segments = path.resolve(packageRoot).split(path.sep);
+  const suffix = ["packages", "apps", "private-state", "cli"];
+  return suffix.every((segment, index) => segments[segments.length - suffix.length + index] === segment);
+}
+
 async function handleDoctor({ args }) {
   const report = buildDoctorReport({ probeGpu: args.gpu === true });
   if (isJsonOutputRequested()) {
@@ -2129,8 +2261,8 @@ function applyGuideNextAction(guide) {
   }
   if (guide.selectors.channelName && guide.state.channel?.onchain?.exists && !guide.state.channel?.local?.workspaceExists) {
     setGuideNextAction(guide, {
-      command: `recover-workspace --channel-name ${guide.selectors.channelName} --network ${guide.selectors.network}`,
-      why: "The channel exists on-chain, but the local channel workspace has not been recovered yet.",
+      command: `recover-workspace --channel-name ${guide.selectors.channelName} --network ${guide.selectors.network} --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.",
     });
     return;
   }
@@ -2269,21 +2401,24 @@ function redactRpcUrl(rpcUrl) {
 
 async function handleGetMyWalletMeta({ args, provider }) {
   const { wallet, walletMetadata } = loadUnlockedWalletWithMetadata(args);
-  const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
-  const context = await loadChannelContext({
-    args,
-    networkName: walletMetadata.network,
+  const contextResult = await loadPreferredWalletChannelContext({
+    walletContext: wallet,
     provider,
+    progressAction: "get-my-wallet-meta",
+  });
+  const context = contextResult.context;
+  const {
+    signer,
+    l2Identity,
+    registration,
+    expectedStorageKey,
+    matchesWallet,
+  } = await loadWalletChannelRegistrationState({
     walletContext: wallet,
+    context,
+    provider,
   });
 
-  const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
-  const expectedStorageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
-  const matchesWallet = registration.exists
-    && ethers.toBigInt(getAddress(registration.l2Address)) === ethers.toBigInt(getAddress(l2Identity.l2Address))
-    && ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
-      === ethers.toBigInt(normalizeBytes32Hex(expectedStorageKey));
-
   printJson({
     action: "get-my-wallet-meta",
     wallet: wallet.walletName,
@@ -2301,31 +2436,23 @@ async function handleGetMyWalletMeta({ args, provider }) {
 }
 
 async function loadWalletChannelFundState({ walletContext, provider, progressAction = null }) {
-  const { signer, l2Identity } = restoreWalletParticipant(walletContext, provider);
   const contextResult = await loadPreferredWalletChannelContext({
     walletContext,
     provider,
     progressAction,
   });
   const context = contextResult.context;
-  const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
-  expect(
-    registration.exists,
-    cliError(
-      CLI_ERROR_CODES.MISSING_CHANNEL_REGISTRATION,
-      `No channelTokenVault registration exists for ${signer.address}. Run join-channel first.`,
-    ),
-  );
-  const expectedStorageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
-  expect(
-    ethers.toBigInt(getAddress(registration.l2Address)) === ethers.toBigInt(getAddress(l2Identity.l2Address)),
-    "The local wallet L2 address does not match the registered channel L2 address.",
-  );
-  expect(
-    ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
-      === ethers.toBigInt(normalizeBytes32Hex(expectedStorageKey)),
-    "The local wallet L2 storage key does not match the registered channelTokenVault key.",
-  );
+  const {
+    signer,
+    l2Identity,
+    registration,
+    expectedStorageKey,
+  } = await loadWalletChannelRegistrationState({
+    walletContext,
+    context,
+    provider,
+    requireRegistration: true,
+  });
 
   const stateManager = await buildStateManager(context.currentSnapshot, context.contractCodes);
   const channelDeposit = await currentStorageBigInt(
@@ -2344,6 +2471,43 @@ async function loadWalletChannelFundState({ walletContext, provider, progressAct
   };
 }
 
+async function loadWalletChannelRegistrationState({
+  walletContext,
+  context,
+  provider,
+  requireRegistration = false,
+}) {
+  const { signer, l2Identity } = restoreWalletParticipant(walletContext, provider);
+  const registration = await context.channelManager.getChannelTokenVaultRegistration(signer.address);
+  const expectedStorageKey = deriveLiquidBalanceStorageKey(l2Identity.l2Address, context.workspace.liquidBalancesSlot);
+  const matchesWallet = registration.exists
+    && ethers.toBigInt(getAddress(registration.l2Address)) === ethers.toBigInt(getAddress(l2Identity.l2Address))
+    && ethers.toBigInt(normalizeBytes32Hex(registration.channelTokenVaultKey))
+      === ethers.toBigInt(normalizeBytes32Hex(expectedStorageKey));
+
+  if (requireRegistration) {
+    expect(
+      registration.exists,
+      cliError(
+        CLI_ERROR_CODES.MISSING_CHANNEL_REGISTRATION,
+        `No channelTokenVault registration exists for ${signer.address}. Run join-channel first.`,
+      ),
+    );
+    expect(
+      matchesWallet,
+      "The local wallet L2 address or storage key does not match the registered channelTokenVault state.",
+    );
+  }
+
+  return {
+    signer,
+    l2Identity,
+    registration,
+    expectedStorageKey,
+    matchesWallet,
+  };
+}
+
 async function handleGetMyChannelFund({ args, provider }) {
   const { wallet, walletMetadata } = loadUnlockedWalletWithMetadata(args);
   const {
@@ -2353,7 +2517,11 @@ async function handleGetMyChannelFund({ args, provider }) {
     registration,
     expectedStorageKey,
     channelFund,
-  } = await loadWalletChannelFundState({ walletContext: wallet, provider });
+  } = await loadWalletChannelFundState({
+    walletContext: wallet,
+    provider,
+    progressAction: "get-my-channel-fund",
+  });
 
   printJson({
     action: "get-my-channel-fund",
@@ -2376,9 +2544,9 @@ async function handleGetMyChannelFund({ args, provider }) {
 }
 
 async function handleJoinChannel({ args, network, provider, rpcUrl }) {
-  const context = await loadChannelContext({
+  const context = await loadJoinChannelContext({
     args,
-    networkName: network.name,
+    network,
     provider,
   });
   const signer = requireL1Signer(args, provider);
@@ -3323,11 +3491,12 @@ async function recoverDeliveredNotesFromEventLogs({
   noteReceivePrivateKey,
   progressAction = null,
 }) {
-  const scanStartBlock = Math.max(
-    Number(walletContext.wallet.noteReceiveLastScannedBlock),
-    Number(context.workspace.genesisBlockNumber),
-  );
   const latestBlock = await provider.getBlockNumber();
+  const scanStartBlock = requireUsableWalletNoteReceiveRecoveryIndex({
+    walletContext,
+    context,
+    latestBlock,
+  });
   const scanRange = {
     fromBlock: scanStartBlock,
     toBlock: latestBlock,
@@ -3431,6 +3600,23 @@ async function recoverDeliveredNotesFromEventLogs({
   };
 }
 
+function requireUsableWalletNoteReceiveRecoveryIndex({ walletContext, context, latestBlock }) {
+  const nextBlock = Number(walletContext.wallet.noteReceiveLastScannedBlock);
+  const genesisBlockNumber = Number(context.workspace.genesisBlockNumber);
+  if (
+    !Number.isInteger(nextBlock)
+    || nextBlock < genesisBlockNumber
+    || nextBlock > Number(latestBlock) + 1
+  ) {
+    throw new Error([
+      `Wallet note recovery index is missing or unusable for wallet ${walletContext.walletName}.`,
+      `Expected noteReceiveLastScannedBlock to be an integer between ${genesisBlockNumber} and ${Number(latestBlock) + 1}.`,
+      "Run recover-wallet --from-genesis to rebuild wallet note state from channel genesis.",
+    ].join(" "));
+  }
+  return nextBlock;
+}
+
 function extractEncryptedNoteValueFromBridgeLog(log) {
   if (!Array.isArray(log?.topics) || log.topics.length !== 1) {
     return null;
@@ -4191,24 +4377,10 @@ async function loadWorkspaceContext(workspaceName, networkName, provider) {
   };
 }
 
-async function loadChannelContext({ args, networkName, provider, walletContext = null }) {
+async function loadJoinChannelContext({ args, network, provider }) {
   const chainId = Number((await provider.getNetwork()).chainId);
-  const resolvedNetworkName = networkName ?? networkNameFromChainId(chainId);
-  const channelName = args.channelName ?? walletContext?.wallet.channelName;
-  if (args.channelName && walletContext) {
-    expect(
-      args.channelName === walletContext.wallet.channelName,
-      [
-        `The provided --channel-name (${args.channelName}) does not match the wallet channel`,
-        `(${walletContext.wallet.channelName}).`,
-      ].join(" "),
-    );
-  }
-  if (!channelName) {
-    throw new Error(
-      "Missing channel selector. Provide either --channel-name or --wallet bound to a channel.",
-    );
-  }
+  const resolvedNetworkName = network?.name ?? networkNameFromChainId(chainId);
+  const channelName = requireArg(args.channelName, "--channel-name");
 
   const bridgeResources = loadBridgeResources({ chainId });
   const initialized = await initializeChannelWorkspace({
@@ -5953,6 +6125,10 @@ function assertUninstallArgs(args) {
   assertAllowedCommandSchema(args, "uninstall");
 }
 
+function assertUpdateArgs(args) {
+  assertAllowedCommandSchema(args, "update");
+}
+
 function assertDoctorArgs(args) {
   assertAllowedCommandSchema(args, "doctor");
   if (args.gpu !== undefined && args.gpu !== true) {
@@ -6051,6 +6227,9 @@ function assertExplicitSignerCommandArgs(args, commandName) {
 
 function assertRecoverWalletArgs(args) {
   assertExplicitSignerCommandArgs(args, "recover-wallet");
+  if (args.fromGenesis !== undefined && args.fromGenesis !== true) {
+    throw new Error("recover-wallet option --from-genesis does not accept a value.");
+  }
 }
 
 function assertJoinChannelArgs(args) {
@@ -6577,6 +6756,7 @@ function loadWalletCommandRuntime(args) {
 const HUMAN_RESULT_RENDERERS = Object.freeze({
   guide: printGuideHumanResult,
   "transaction-fees": printTransactionFeesHumanResult,
+  update: printUpdateHumanResult,
 });
 
 function normalizePrivateKey(value) {
@@ -6668,6 +6848,35 @@ function printTransactionFeesHumanResult(report) {
   console.log(lines.join("\n"));
 }
 
+function printUpdateHumanResult(report) {
+  const lines = [
+    "Private-State CLI Update",
+    `Package: ${formatHumanValue(report.packageName)}`,
+    `Current version: ${formatHumanValue(report.currentVersion)}`,
+    `Latest registry version: ${formatHumanValue(report.latestVersion)}`,
+  ];
+  if (report.registryState === "local-version-ahead-of-registry") {
+    lines.push("Status: local version is newer than the npm registry latest tag.");
+  } else if (!report.updateAvailable) {
+    lines.push("Status: up to date.");
+  } else if (report.updated) {
+    lines.push("Status: updated global npm install.");
+  } else {
+    lines.push(
+      "Status: update available.",
+      `Reason: ${formatHumanValue(report.reason)}`,
+      `Command: ${formatHumanValue(report.command)}`,
+    );
+  }
+  lines.push(
+    `Global install: ${report.globalPackage?.installed ? `yes (${formatHumanValue(report.globalPackage.version)})` : "no"}`,
+    `Repository checkout: ${report.runningFromRepositoryCheckout ? "yes" : "no"}`,
+    "",
+    "Run with --json to inspect the full update report.",
+  );
+  console.log(lines.join("\n"));
+}
+
 function formatHumanTable(headers, rows) {
   const values = [headers, ...rows].map((row) => row.map((value) => String(value ?? "")));
   const widths = headers.map((_header, columnIndex) =>
@@ -6888,6 +7097,15 @@ function buildRecoveryHints(error, args = {}) {
     hints.push(`private-state-cli guide --network ${networkName} --channel-name ${channelName}`);
   }
 
+  if (message.includes("Workspace recovery index is missing or unusable")) {
+    hints.push(`private-state-cli recover-workspace --channel-name ${channelName} --network ${networkName} --from-genesis`);
+    hints.push(`private-state-cli recover-wallet --channel-name ${channelName} --network ${networkName} --account ${accountName} --from-genesis`);
+  }
+
+  if (message.includes("Wallet note recovery index is missing or unusable")) {
+    hints.push(`private-state-cli recover-wallet --channel-name ${channelName} --network ${networkName} --account ${accountName} --from-genesis`);
+  }
+
   if (message.includes("Missing channel selector")) {
     hints.push(`private-state-cli list-local-wallets --network ${networkName}`);
     hints.push(`private-state-cli guide --network ${networkName} --channel-name <CHANNEL> --wallet <WALLET>`);