@tokamak-private-dapps/private-state-cli 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.3 - 2026-04-28
+
+- Installed the Groth16 runtime during `private-state-cli --install` and reported Groth16 readiness from `--doctor`.
+- Added live NVIDIA and Docker GPU probes to `--doctor`, with a hard failure when live Docker GPU readiness does not match the recorded Tokamak CLI metadata.
+- Renamed `get-my-address` to `get-my-wallet-meta`, added `get-my-l1-address`, and added `list-local-wallets`.
+- Documented the private-state CLI helper commands, common flow examples, and LLM agent guidance.
+
+## 0.1.2 - 2026-04-28
+
+- Added `private-state-cli --doctor` to report CLI and install-time dependency versions through `tokamak-l2js`.
+- Reported Tokamak zk-EVM runtime install mode, Docker mode, and CUDA runtime metadata.
+
 ## 0.1.1 - 2026-04-28
 
 - Updated channel balance proof generation to use the fixed Groth16 runtime workspace proof paths.

package/README.md

@@ -8,7 +8,8 @@ Command-line client for the Tokamak private-state DApp.
 npm install -g @tokamak-private-dapps/private-state-cli
 ```
 
-Install the local Tokamak zk-EVM runtime workspace and public private-state deployment artifacts:
+Install the local Tokamak zk-EVM runtime workspace, Groth16 runtime workspace, and public private-state deployment
+artifacts:
 
 ```bash
 private-state-cli --install
@@ -27,9 +28,15 @@ Run the CLI with:
 private-state-cli <command> ...
 ```
 
+Check the installed package and runtime state with:
+
+```bash
+private-state-cli --doctor
+```
+
 ## Commands
 
-The normal private-state flow is:
+A common private-state flow is:
 
 1. `create-channel`
 2. `deposit-bridge`
@@ -44,6 +51,24 @@ The normal private-state flow is:
 
 Use `private-state-cli --help` for the full command list and required options.
 
+`private-state-cli --doctor` reports the CLI package version, dependency versions recorded by the last
+`private-state-cli --install`, current dependency versions through `tokamak-l2js`, and Tokamak zk-EVM runtime
+install mode, Docker mode, CUDA runtime metadata, live `nvidia-smi` and Docker GPU probe results, and Groth16
+runtime health. The doctor check fails when the Tokamak Docker `useGpus` metadata does not match the live GPU probes.
+
+Local helper commands:
+
+```bash
+private-state-cli list-local-wallets --network sepolia --channel-name cuda
+private-state-cli get-my-wallet-meta --wallet <WALLET_NAME> --password <PASSWORD> --network sepolia
+private-state-cli get-my-l1-address --private-key <HEX>
+```
+
+`list-local-wallets` reads only the local workspace and prints saved wallet names that can be reused with `--wallet`.
+`get-my-wallet-meta` opens an encrypted local wallet and reports the stored L1/L2 identity metadata plus the current
+on-chain channel registration match state. `get-my-l1-address` is a simple offline helper that derives the L1 address
+for a private key.
+
 ## Workspace
 
 The CLI stores user workspaces under:
@@ -54,6 +79,57 @@ The CLI stores user workspaces under:
 
 Wallet data is encrypted with the password supplied to `join-channel` or `recover-wallet`.
 
+## 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 only knows that the DApp is a way to send funds privately. Translate the user's intent into safe, step-by-step CLI
+actions.
+
+Primary goal: help the user privately send funds by guiding them through the required private-state CLI commands,
+explaining each step only as much as needed to proceed safely.
+
+Operating rules:
+
+- Do not ask the user to reveal raw private keys in chat. Use environment variable placeholders such as `$ADDR6`,
+  `$CREATOR`, or `$PRIVATE_STATE_TEST_PK`.
+- 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 --doctor` and inspect
+  whether the runtime, Docker mode, CUDA/GPU probes, Groth16 runtime, and deployment artifacts are healthy.
+- Use `private-state-cli list-local-wallets` to discover local wallet names instead of asking the user to inspect
+  filesystem paths manually.
+- Use `private-state-cli get-my-l1-address --private-key "$KEY_ENV"` to derive the L1 address for a private-key
+  environment variable when wallet ownership needs to be identified.
+- Use `private-state-cli get-my-wallet-meta --wallet <WALLET> --password <PASSWORD> --network <NETWORK>` to inspect
+  local wallet metadata and on-chain channel registration state.
+- Use `private-state-cli get-my-bridge-fund` and `private-state-cli get-my-channel-fund` to check balances before
+  telling the user to move funds.
+- Explain that wallet names are local CLI identifiers, while private transfers use notes owned by L2 addresses
+  registered in the channel.
+- 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 funding the bridge, joining or recovering the channel wallet, 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 private-key environment variables.
+4. Run `--doctor`.
+5. Run `list-local-wallets` and relevant metadata or balance checks.
+6. If needed, guide the user through `create-channel`, `deposit-bridge`, `join-channel`, `deposit-channel`, and
+   `mint-notes`.
+7. For a private transfer, select available note IDs from `get-my-notes`, find the recipient L2 address from
+   `get-my-wallet-meta`, then build `transfer-notes`.
+8. After transfer, guide the recipient to run `get-my-notes` to recover received notes from event logs.
+
+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.
+
 ## Artifacts
 
 Proof-backed commands require installed bridge, DApp, and Groth16 artifacts. Run `private-state-cli --install` before
@@ -71,7 +147,8 @@ Release order matters for npm publication. `@tokamak-private-dapps/common-librar
 ### What does this package install?
 
 It installs the `private-state-cli` terminal command and the local files needed by that command.
-It does not install bridge contracts, app contracts, or local deployment outputs.
+It does not install bridge contracts, app contracts, or local deployment outputs. The `private-state-cli --install`
+command provisions the local Tokamak zk-EVM and Groth16 runtime workspaces used by proof-backed commands.
 
 ### When should I run `private-state-cli --install`?
 

package/cli-assistant.html

@@ -528,7 +528,9 @@
         { id: "get-my-bridge-fund", description: "Read the current bridge-vault balance.", fields: ["network", "privateKey", "alchemyApiKey"] },
         { id: "join-channel", description: "Bind the caller to a channel-specific L2 identity.", fields: ["channelName", "password", "network", "privateKey", "alchemyApiKey"] },
         { id: "recover-wallet", description: "Rebuild the recoverable portion of a wallet.", fields: ["channelName", "password", "network", "privateKey", "alchemyApiKey"] },
-        { id: "get-my-address", description: "Check whether a saved wallet matches on-chain registration.", fields: ["wallet", "password", "network"] },
+        { id: "get-my-wallet-meta", description: "Check whether a saved wallet matches on-chain registration.", fields: ["wallet", "password", "network"] },
+        { id: "get-my-l1-address", description: "Derive the L1 address for a private key.", fields: ["privateKey"] },
+        { id: "list-local-wallets", description: "List saved local wallet names that can be reused with --wallet.", fields: ["network", "channelName"] },
         { id: "deposit-channel", description: "Move bridged funds into the channel L2 accounting balance.", fields: ["wallet", "password", "network", "amount"] },
         { id: "withdraw-channel", description: "Move channel L2 balance back into the shared bridge vault.", fields: ["wallet", "password", "network", "amount"] },
         { id: "get-my-channel-fund", description: "Read the current channel L2 accounting balance.", fields: ["wallet", "password", "network"] },

package/package.json

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

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 import {
   createCipheriv,
   createDecipheriv,
@@ -46,6 +47,7 @@ import { deriveRpcUrl, resolveCliNetwork } from "@tokamak-private-dapps/common-l
 import {
   buildTokamakCliInvocation,
   resolveTokamakBlockInputConfig,
+  resolveTokamakCliPackageRoot,
   resolveTokamakCliResourceDir,
   resolveTokamakCliRuntimeRoot,
 } from "@tokamak-private-dapps/common-library/tokamak-runtime-paths";
@@ -80,12 +82,16 @@ import {
   walletNameForChannelAndAddress,
 } from "./lib/private-state-cli-shared.mjs";
 
+const require = createRequire(import.meta.url);
 const defaultCommandCwd = process.cwd();
+const privateStateCliPackageRoot = path.dirname(require.resolve("./package.json"));
 const workspaceRoot = path.resolve(os.homedir(), "tokamak-private-channels", "workspace");
 const tokamakCliInvocation = buildTokamakCliInvocation();
 const tokamakCliCommand = tokamakCliInvocation.command;
 const tokamakCliBaseArgs = tokamakCliInvocation.args;
 const flatDeploymentArtifactPathsByChainId = new Map();
+const DOCKER_CUDA_PROBE_IMAGE = "nvidia/cuda:12.2.0-base-ubuntu22.04";
+const DOCTOR_GPU_PROBE_TIMEOUT_MS = 120000;
 
 const abiCoder = AbiCoder.defaultAbiCoder();
 const erc20MetadataAbi = [
@@ -221,6 +227,24 @@ async function main() {
     return;
   }
 
+  if (args.command === "--doctor") {
+    assertDoctorArgs(args);
+    await handleDoctor({ args });
+    return;
+  }
+
+  if (args.command === "get-my-l1-address") {
+    assertGetMyL1AddressArgs(args);
+    handleGetMyL1Address({ args });
+    return;
+  }
+
+  if (args.command === "list-local-wallets") {
+    assertListLocalWalletsArgs(args);
+    handleListLocalWallets({ args });
+    return;
+  }
+
   const walletCommandHandlers = {
     "mint-notes": {
       assert: assertMintNotesArgs,
@@ -246,9 +270,9 @@ async function main() {
       assert: (parsedArgs) => assertWalletChannelMoveArgs(parsedArgs, "withdraw-channel"),
       run: ({ provider }) => handleGrothVaultMove({ args, provider, direction: "withdraw" }),
     },
-    "get-my-address": {
-      assert: assertGetMyAddressArgs,
-      run: ({ provider }) => handleGetMyAddress({ args, provider }),
+    "get-my-wallet-meta": {
+      assert: assertGetMyWalletMetaArgs,
+      run: ({ provider }) => handleGetMyWalletMeta({ args, provider }),
     },
     "get-my-channel-fund": {
       assert: assertGetMyChannelFundArgs,
@@ -932,15 +956,26 @@ async function handleInstallZkEvm({ args }) {
   }
   run(tokamakCliCommand, installArgs);
   const tokamakRuntimeRoot = resolveTokamakCliRuntimeRoot();
+  const groth16Runtime = installGroth16RuntimeForPrivateState({
+    docker: Boolean(args.docker),
+  });
   const localDeploymentBaseRoot = args.includeLocalArtifacts ? process.cwd() : null;
   const deploymentArtifacts = await installPrivateStateCliArtifacts({
     dappName: PRIVATE_STATE_DAPP_LABEL,
     localDeploymentBaseRoot,
   });
+  const installManifest = writePrivateStateCliInstallManifest({
+    dockerRequested: Boolean(args.docker),
+    includeLocalArtifacts: Boolean(args.includeLocalArtifacts),
+    localDeploymentBaseRoot,
+    deploymentArtifacts,
+    groth16Runtime,
+  });
   printJson({
     action: "install",
     tokamakCli: tokamakCliBaseArgs[0],
     runtimeRoot: tokamakRuntimeRoot,
+    groth16Runtime,
     docker: Boolean(args.docker),
     includeLocalArtifacts: Boolean(args.includeLocalArtifacts),
     localDeploymentBaseRoot,
@@ -953,6 +988,7 @@ async function handleInstallZkEvm({ args }) {
       dappTimestamp: entry.dappTimestamp,
       artifactDir: entry.artifactDir,
     })),
+    installManifestPath: installManifest.manifestPath,
   });
 }
 
@@ -972,7 +1008,46 @@ async function handleUninstallZkEvm() {
   });
 }
 
-async function handleGetMyAddress({ args, provider }) {
+async function handleDoctor() {
+  const report = buildDoctorReport();
+  printJson(report);
+  if (!report.ok) {
+    process.exitCode = 1;
+  }
+}
+
+function handleGetMyL1Address({ args }) {
+  const privateKey = normalizePrivateKey(requireArg(args.privateKey, "--private-key"));
+  const signer = new Wallet(privateKey);
+  printJson({
+    action: "get-my-l1-address",
+    l1Address: signer.address,
+  });
+}
+
+function handleListLocalWallets({ args }) {
+  const networkFilter = args.network ? requireNetworkName(args) : null;
+  if (networkFilter) {
+    resolveCliNetwork(networkFilter);
+  }
+  const channelFilter = args.channelName ? slugifyPathComponent(requireArg(args.channelName, "--channel-name")) : null;
+  const wallets = listLocalWallets({
+    networkFilter,
+    channelFilter,
+  });
+
+  printJson({
+    action: "list-local-wallets",
+    workspaceRoot,
+    filters: {
+      network: networkFilter,
+      channelName: args.channelName ?? null,
+    },
+    wallets,
+  });
+}
+
+async function handleGetMyWalletMeta({ args, provider }) {
   const { wallet, walletMetadata } = loadUnlockedWalletWithMetadata(args);
   const { signer, l2Identity } = restoreWalletParticipant(wallet, provider);
   const context = await loadChannelContext({
@@ -990,7 +1065,7 @@ async function handleGetMyAddress({ args, provider }) {
       === ethers.toBigInt(normalizeBytes32Hex(expectedStorageKey));
 
   printJson({
-    action: "get-my-address",
+    action: "get-my-wallet-meta",
     wallet: wallet.walletName,
     network: walletMetadata.network,
     channelName: walletMetadata.channelName,
@@ -4217,6 +4292,10 @@ function parseArgs(argv) {
     parsed.command = "--install";
     parsed.positional = ["--install"];
   }
+  if (!parsed.command && parsed.doctor === true) {
+    parsed.command = "--doctor";
+    parsed.positional = ["--doctor"];
+  }
   return parsed;
 }
 
@@ -4348,6 +4427,48 @@ function resolveWalletPathCandidates(walletName) {
   return candidates;
 }
 
+function listLocalWallets({ networkFilter = null, channelFilter = null } = {}) {
+  if (!fs.existsSync(workspaceRoot)) {
+    return [];
+  }
+
+  const wallets = [];
+  for (const networkEntry of fs.readdirSync(workspaceRoot, { withFileTypes: true })) {
+    if (!networkEntry.isDirectory() || (networkFilter && networkEntry.name !== slugifyPathComponent(networkFilter))) {
+      continue;
+    }
+    const networkDir = path.join(workspaceRoot, networkEntry.name);
+    for (const channelEntry of fs.readdirSync(networkDir, { withFileTypes: true })) {
+      if (!channelEntry.isDirectory() || (channelFilter && channelEntry.name !== channelFilter)) {
+        continue;
+      }
+      const walletsDir = path.join(networkDir, channelEntry.name, "wallets");
+      if (!fs.existsSync(walletsDir)) {
+        continue;
+      }
+      for (const walletEntry of fs.readdirSync(walletsDir, { withFileTypes: true })) {
+        if (!walletEntry.isDirectory()) {
+          continue;
+        }
+        const walletDir = path.join(walletsDir, walletEntry.name);
+        wallets.push({
+          wallet: walletEntry.name,
+          network: networkEntry.name,
+          channelName: channelEntry.name,
+          walletDir,
+          metadataPath: walletMetadataPath(walletDir),
+          hasMetadata: fs.existsSync(walletMetadataPath(walletDir)),
+          hasEncryptedWallet: walletConfigExists(walletDir),
+        });
+      }
+    }
+  }
+  return wallets.sort((left, right) =>
+    [left.network, left.channelName, left.wallet].join("\0")
+      .localeCompare([right.network, right.channelName, right.wallet].join("\0")),
+  );
+}
+
 function channelDataPath(workspaceDir) {
   return workspaceChannelDir(workspaceDir);
 }
@@ -4421,6 +4542,10 @@ function assertUninstallZkEvmArgs(args) {
   assertAllowedCommandKeys(args, "uninstall-zk-evm", new Set(["command", "positional"]), "no options");
 }
 
+function assertDoctorArgs(args) {
+  assertAllowedCommandKeys(args, "--doctor", new Set(["command", "positional", "doctor"]), "no options");
+}
+
 function assertMintNotesArgs(args) {
   requireArg(args.amounts, "--amounts");
   assertWalletPasswordArgs(args, "mint-notes", ["amounts"], "--wallet, --password, --network, and --amounts");
@@ -4533,8 +4658,33 @@ function assertJoinChannelArgs(args) {
   assertExplicitSignerPasswordCommandArgs(args, "join-channel");
 }
 
-function assertGetMyAddressArgs(args) {
-  assertWalletPasswordArgs(args, "get-my-address", [], "--wallet, --password, and --network");
+function assertGetMyWalletMetaArgs(args) {
+  assertWalletPasswordArgs(args, "get-my-wallet-meta", [], "--wallet, --password, and --network");
+}
+
+function assertGetMyL1AddressArgs(args) {
+  requireArg(args.privateKey, "--private-key");
+  assertAllowedCommandKeys(
+    args,
+    "get-my-l1-address",
+    new Set(["command", "positional", "privateKey"]),
+    "--private-key",
+  );
+}
+
+function assertListLocalWalletsArgs(args) {
+  if (args.network !== undefined) {
+    requireNetworkName(args);
+  }
+  if (args.channelName !== undefined) {
+    requireArg(args.channelName, "--channel-name");
+  }
+  assertAllowedCommandKeys(
+    args,
+    "list-local-wallets",
+    new Set(["command", "positional", "network", "channelName"]),
+    "optional --network and --channel-name",
+  );
 }
 
 function assertWithdrawBridgeArgs(args) {
@@ -4596,13 +4746,16 @@ function printHelp() {
   console.log(`
 Commands:
   --install [--docker] [--include-local-artifacts]
-      Install the Tokamak zk-EVM CLI runtime workspace and private-state deployment artifacts
-      Use --docker on Linux to forward tokamak-cli --install --docker
+      Install the Tokamak zk-EVM CLI runtime, Groth16 runtime, and private-state deployment artifacts
+      Use --docker on Linux to forward Docker mode to the Tokamak zk-EVM and Groth16 runtimes
       Use --include-local-artifacts to also install local deployment/ artifacts from the current working directory
 
   uninstall-zk-evm
       Remove the Tokamak zk-EVM CLI runtime workspace
 
+  --doctor
+      Check private-state CLI package versions, runtime install state, Docker mode, CUDA mode, and deployment artifacts
+
   create-channel --channel-name <NAME> --join-fee <TOKENS> --network <NAME> --private-key <HEX> --alchemy-api-key <KEY>
       Create a bridge channel and initialize its workspace
 
@@ -4624,9 +4777,15 @@ Commands:
   join-channel --channel-name <NAME> --password <PASSWORD> --network <NAME> --private-key <HEX> --alchemy-api-key <KEY>
       Pay the channel join fee and bind a wallet to a channel-specific L2 identity
 
-  get-my-address --wallet <NAME> --password <PASSWORD> --network <NAME>
+  get-my-wallet-meta --wallet <NAME> --password <PASSWORD> --network <NAME>
       Check whether a wallet matches the on-chain channel registration
 
+  get-my-l1-address --private-key <HEX>
+      Derive the L1 address for a private key
+
+  list-local-wallets [--network <NAME>] [--channel-name <NAME>]
+      List saved local wallet names that can be reused with --wallet
+
   deposit-channel --wallet <NAME> --password <PASSWORD> --network <NAME> --amount <TOKENS>
       Move bridged funds into the channel L2 accounting balance
 
@@ -4882,6 +5041,396 @@ function privateStateCliArtifactPaths(cacheBaseRoot = resolveArtifactCacheBaseRo
   };
 }
 
+function privateStateCliInstallManifestPath(cacheBaseRoot = resolveArtifactCacheBaseRoot()) {
+  return path.join(privateStateCliArtifactRoot(cacheBaseRoot), "install-manifest.json");
+}
+
+function writePrivateStateCliInstallManifest({
+  dockerRequested,
+  includeLocalArtifacts,
+  localDeploymentBaseRoot,
+  deploymentArtifacts,
+  groth16Runtime,
+}) {
+  const manifestPath = privateStateCliInstallManifestPath(deploymentArtifacts.cacheBaseRoot);
+  const manifest = {
+    installedAt: new Date().toISOString(),
+    package: summarizePackageReport(readPackageReport({
+      name: "@tokamak-private-dapps/private-state-cli",
+      packageJsonPath: path.join(privateStateCliPackageRoot, "package.json"),
+    })),
+    dependencies: collectDependencyPackageReports().map(summarizePackageReport),
+    install: {
+      dockerRequested,
+      includeLocalArtifacts,
+      localDeploymentBaseRoot,
+      artifactCacheRoot: deploymentArtifacts.cacheBaseRoot,
+      groth16Runtime,
+      installedDeploymentArtifacts: deploymentArtifacts.installed.map((entry) => ({
+        chainId: entry.chainId,
+        source: entry.source,
+        bridgeTimestamp: entry.bridgeTimestamp,
+        dappTimestamp: entry.dappTimestamp,
+      })),
+    },
+  };
+  writeJson(manifestPath, manifest);
+  return { manifestPath, manifest };
+}
+
+function summarizePackageReport(report) {
+  return {
+    name: report.name,
+    version: report.version,
+  };
+}
+
+function buildDoctorReport() {
+  const cacheBaseRoot = resolveArtifactCacheBaseRoot();
+  const installManifestPath = privateStateCliInstallManifestPath(cacheBaseRoot);
+  const installManifest = readJsonIfExists(installManifestPath);
+  const dependencyReports = collectDependencyPackageReports(installManifest);
+  const tokamakCli = inspectTokamakCliRuntime();
+  const groth16Runtime = inspectGroth16Runtime();
+  const gpuDockerReadiness = inspectGpuDockerReadiness(tokamakCli);
+  const checks = [
+    {
+      name: "dependency package versions",
+      ok: dependencyReports.every((entry) => entry.ok),
+      details: dependencyReports.map((entry) => ({
+        name: entry.name,
+        currentVersion: entry.version,
+        installVersion: entry.installVersion,
+        ok: entry.ok,
+        error: entry.error,
+      })),
+    },
+    {
+      name: "tokamak zk-evm runtime",
+      ok: tokamakCli.installed,
+      details: {
+        doctorStatus: tokamakCli.doctor.status,
+        runtimeRoot: tokamakCli.runtimeRoot,
+        installations: tokamakCli.installations.map(({ platform, installMode, packageVersion, docker }) => ({
+          platform,
+          installMode,
+          packageVersion,
+          dockerEnvironment: docker?.dockerEnvironment ?? null,
+          useGpus: docker?.useGpus ?? null,
+        })),
+      },
+    },
+    {
+      name: "tokamak docker gpu readiness",
+      ok: gpuDockerReadiness.ok,
+      details: {
+        expectedUseGpus: gpuDockerReadiness.expectedUseGpus,
+        liveUseGpus: gpuDockerReadiness.liveUseGpus,
+        mismatch: gpuDockerReadiness.mismatch,
+        mismatchError: gpuDockerReadiness.mismatchError,
+        hostNvidiaSmi: summarizeProbeResult(gpuDockerReadiness.hostNvidiaSmi),
+        dockerNvidiaSmi: summarizeProbeResult(gpuDockerReadiness.dockerNvidiaSmi),
+      },
+    },
+    {
+      name: "groth16 runtime",
+      ok: groth16Runtime.installed,
+      details: {
+        packageRoot: groth16Runtime.packageRoot,
+        workspaceRoot: groth16Runtime.workspaceRoot,
+        doctorStatus: groth16Runtime.doctor.status,
+        checks: groth16Runtime.checks,
+      },
+    },
+  ];
+
+  return {
+    action: "doctor",
+    ok: checks.every((check) => check.ok),
+    generatedAt: new Date().toISOString(),
+    package: readPackageReport({
+      name: "@tokamak-private-dapps/private-state-cli",
+      packageJsonPath: path.join(privateStateCliPackageRoot, "package.json"),
+    }),
+    installManifest: {
+      path: installManifestPath,
+      exists: Boolean(installManifest),
+      installedAt: installManifest?.installedAt ?? null,
+      dockerRequested: installManifest?.install?.dockerRequested ?? null,
+      includeLocalArtifacts: installManifest?.install?.includeLocalArtifacts ?? null,
+    },
+    dependencies: dependencyReports,
+    tokamakCli,
+    groth16Runtime,
+    gpuDockerReadiness,
+    checks,
+  };
+}
+
+function installGroth16RuntimeForPrivateState({ docker }) {
+  const packageRoot = resolveGroth16PackageRoot();
+  const entryPath = resolveGroth16CliEntryPath(packageRoot);
+  const args = [entryPath, "--install"];
+  if (docker) {
+    args.push("--docker");
+  }
+  run(process.execPath, args, { cwd: packageRoot });
+  const runtime = inspectGroth16Runtime();
+  expect(runtime.installed, "Groth16 runtime install completed, but tokamak-groth16 --doctor still reports an unhealthy runtime.");
+  return runtime;
+}
+
+function collectDependencyPackageReports(installManifest = null) {
+  const installVersions = new Map(
+    Array.isArray(installManifest?.dependencies)
+      ? installManifest.dependencies.map((entry) => [entry.name, entry.version])
+      : [],
+  );
+  const targets = [
+    {
+      name: "@tokamak-zk-evm/cli",
+      packageJsonPath: path.join(resolveTokamakCliPackageRoot(), "package.json"),
+    },
+    {
+      name: "@tokamak-private-dapps/groth16",
+      resolveTarget: "@tokamak-private-dapps/groth16/public-drive-crs",
+    },
+    {
+      name: "@tokamak-private-dapps/common-library",
+      resolveTarget: "@tokamak-private-dapps/common-library/artifact-cache",
+    },
+    { name: "tokamak-l2js", resolveTarget: "tokamak-l2js" },
+  ];
+
+  return targets.map((target) => {
+    const report = readPackageReport(target);
+    const installVersion = installVersions.get(report.name) ?? null;
+    return {
+      ...report,
+      installVersion,
+      ok: Boolean(report.version) && (installVersion === null || installVersion === report.version),
+    };
+  });
+}
+
+function readPackageReport({ name, packageJsonPath = null, resolveTarget = null }) {
+  try {
+    const resolvedPackageJsonPath = packageJsonPath
+      ? path.resolve(packageJsonPath)
+      : findPackageJsonForName(path.dirname(require.resolve(resolveTarget ?? name)), name);
+    const packageJson = readJson(resolvedPackageJsonPath);
+    return {
+      name: packageJson.name ?? name,
+      version: packageJson.version ?? null,
+      packageRoot: path.dirname(resolvedPackageJsonPath),
+      error: null,
+    };
+  } catch (error) {
+    return {
+      name,
+      version: null,
+      packageRoot: null,
+      error: error.message,
+      ok: false,
+    };
+  }
+}
+
+function findPackageJsonForName(startDir, expectedName) {
+  let current = path.resolve(startDir);
+  while (current !== path.dirname(current)) {
+    const candidate = path.join(current, "package.json");
+    if (fs.existsSync(candidate)) {
+      const packageJson = readJson(candidate);
+      if (packageJson.name === expectedName) {
+        return candidate;
+      }
+    }
+    current = path.dirname(current);
+  }
+  throw new Error(`Cannot locate package.json for ${expectedName} above ${startDir}.`);
+}
+
+function resolveGroth16PackageRoot() {
+  const publicDriveCrsPath = require.resolve("@tokamak-private-dapps/groth16/public-drive-crs");
+  return path.dirname(findPackageJsonForName(path.dirname(publicDriveCrsPath), "@tokamak-private-dapps/groth16"));
+}
+
+function resolveGroth16CliEntryPath(packageRoot = resolveGroth16PackageRoot()) {
+  return path.join(packageRoot, "cli", "tokamak-groth16-cli.mjs");
+}
+
+function inspectGroth16Runtime() {
+  const packageRoot = resolveGroth16PackageRoot();
+  const entryPath = resolveGroth16CliEntryPath(packageRoot);
+  const doctor = runCaptured(process.execPath, [entryPath, "--doctor", "--verbose"], { cwd: packageRoot });
+  const stdout = stripAnsi(doctor.stdout).trim();
+  const stderr = stripAnsi(doctor.stderr).trim();
+  const report = parseJsonReport(stdout);
+  return {
+    installed: doctor.status === 0 && report?.ok === true,
+    packageRoot,
+    workspaceRoot: report?.workspaceRoot ?? null,
+    checks: report?.checks ?? [],
+    doctor: {
+      status: doctor.status,
+      stdout,
+      stderr,
+    },
+  };
+}
+
+function inspectTokamakCliRuntime() {
+  const doctor = runCaptured(tokamakCliCommand, [...tokamakCliBaseArgs, "--doctor"], {
+    cwd: resolveTokamakCliPackageRoot(),
+  });
+  const doctorOutput = stripAnsi(`${doctor.stdout}${doctor.stderr}`);
+  const runtimeRoot = parseRuntimeRootFromTokamakDoctorOutput(doctorOutput);
+  const cacheRoot = resolveTokamakCliCacheRoot();
+  const installations = readTokamakCliInstallations(cacheRoot);
+  const dockerModeInstalled = installations.some((entry) => entry.installMode === "docker" || entry.docker);
+  const cudaCompatible = installations.some((entry) => entry.docker?.useGpus === true);
+
+  return {
+    installed: doctor.status === 0 || installations.length > 0,
+    packageRoot: resolveTokamakCliPackageRoot(),
+    cacheRoot,
+    runtimeRoot,
+    packageVersion: readPackageReport({
+      name: "@tokamak-zk-evm/cli",
+      packageJsonPath: path.join(resolveTokamakCliPackageRoot(), "package.json"),
+    }).version,
+    dockerModeInstalled,
+    cudaCompatible,
+    doctor: {
+      status: doctor.status,
+      stdout: stripAnsi(doctor.stdout).trim(),
+      stderr: stripAnsi(doctor.stderr).trim(),
+    },
+    installations,
+  };
+}
+
+function inspectGpuDockerReadiness(tokamakCli) {
+  const hostNvidiaSmi = runProbe("nvidia-smi", ["--query-gpu=name,driver_version", "--format=csv,noheader"]);
+  const dockerNvidiaSmi = runProbe("docker", [
+    "run",
+    "--rm",
+    "--gpus",
+    "all",
+    DOCKER_CUDA_PROBE_IMAGE,
+    "nvidia-smi",
+  ]);
+  const expectedUseGpus = Boolean(tokamakCli.cudaCompatible);
+  const liveUseGpus = hostNvidiaSmi.ok && dockerNvidiaSmi.ok;
+  const mismatch = expectedUseGpus !== liveUseGpus;
+  return {
+    ok: !mismatch,
+    expectedUseGpus,
+    liveUseGpus,
+    mismatch,
+    mismatchError: mismatch
+      ? [
+        "Tokamak CLI Docker GPU metadata does not match live NVIDIA/Docker GPU probes.",
+        `metadata useGpus=${expectedUseGpus}; live useGpus=${liveUseGpus}.`,
+      ].join(" ")
+      : null,
+    probeImage: DOCKER_CUDA_PROBE_IMAGE,
+    hostNvidiaSmi,
+    dockerNvidiaSmi,
+  };
+}
+
+function runProbe(command, args) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    timeout: DOCTOR_GPU_PROBE_TIMEOUT_MS,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return {
+    command,
+    args,
+    ok: !result.error && result.status === 0,
+    status: result.status,
+    signal: result.signal,
+    error: result.error ? result.error.message : null,
+    stdout: stripAnsi(result.stdout ?? "").trim(),
+    stderr: stripAnsi(result.stderr ?? "").trim(),
+    timedOut: result.error?.code === "ETIMEDOUT",
+  };
+}
+
+function summarizeProbeResult(result) {
+  return {
+    command: [result.command, ...result.args].join(" "),
+    ok: result.ok,
+    status: result.status,
+    signal: result.signal,
+    error: result.error,
+    timedOut: result.timedOut,
+    stdout: truncateText(result.stdout, 2000),
+    stderr: truncateText(result.stderr, 2000),
+  };
+}
+
+function truncateText(value, maxLength) {
+  const text = String(value ?? "");
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, maxLength)}...`;
+}
+
+function parseJsonReport(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+function resolveTokamakCliCacheRoot() {
+  return path.resolve(process.env.TOKAMAK_ZKEVM_CLI_CACHE_DIR ?? path.join(os.homedir(), ".tokamak-zk-evm"));
+}
+
+function readTokamakCliInstallations(cacheRoot) {
+  if (!fs.existsSync(cacheRoot)) {
+    return [];
+  }
+  return fs.readdirSync(cacheRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const platformDir = path.join(cacheRoot, entry.name);
+      const statePath = path.join(platformDir, "installation.json");
+      if (!fs.existsSync(statePath)) {
+        return null;
+      }
+      const state = readJsonIfExists(statePath);
+      const dockerBootstrapPath = path.join(platformDir, "docker", "bootstrap.json");
+      const docker = readJsonIfExists(dockerBootstrapPath);
+      return {
+        platform: entry.name,
+        statePath,
+        runtimeRoot: path.join(platformDir, "runtime"),
+        installMode: state?.installMode ?? (docker ? "docker" : null),
+        packageVersion: state?.packageVersion ?? docker?.packageVersion ?? null,
+        installedAt: state?.installedAt ?? null,
+        dockerBootstrapPath,
+        docker,
+      };
+    })
+    .filter(Boolean);
+}
+
+function parseRuntimeRootFromTokamakDoctorOutput(output) {
+  const match = String(output ?? "").match(/^\[ ok \] Runtime workspace:\s*(.+)$/m);
+  return match ? path.resolve(match[1].trim()) : null;
+}
+
+function stripAnsi(value) {
+  return String(value ?? "").replace(/\u001b\[[0-9;]*m/g, "");
+}
+
 async function installPrivateStateCliArtifacts({
   dappName,
   indexFileId = process.env.PRIVATE_STATE_DRIVE_ARTIFACT_INDEX_FILE_ID