@openclawbrain/cli 0.4.11 → 0.4.12

package/README.md

@@ -2,16 +2,17 @@
 
 Operator CLI for OpenClawBrain. Use it with `@openclawbrain/openclaw`.
 
-The public install story is three commands to install or update, then one command to verify.
+The public install story is three commands to install or update, one command to verify, and one official proof command when you need a durable operator bundle.
 
 ```bash
 openclaw plugins install @openclawbrain/openclaw
 npx @openclawbrain/cli install --openclaw-home ~/.openclaw
 openclaw gateway restart
 npx @openclawbrain/cli status --openclaw-home ~/.openclaw --detailed
+npx @openclawbrain/cli proof --openclaw-home ~/.openclaw --skip-install --skip-restart
 ```
 
-The first three commands install or update OpenClawBrain. The last command verifies the selected OpenClaw home.
+The first three commands install or update OpenClawBrain. `status --detailed` is the quick verify surface. `proof` writes `summary.md`, `steps.json`, `verdict.json`, raw step logs, and proof pointers under one bundle directory.
 
 ## Common commands
 

package/dist/src/cli.js

@@ -24,6 +24,7 @@ import { buildTracedLearningBridgePayloadFromRuntime, buildTracedLearningStatusS
 import { discoverOpenClawSessionStores, loadOpenClawSessionIndex, readOpenClawSessionFile } from "./session-store.js";
 import { readOpenClawBrainProviderDefaults, readOpenClawBrainProviderConfig, readOpenClawBrainProviderConfigFromSources, resolveOpenClawBrainProviderDefaultsPath } from "./provider-config.js";
 import { formatOperatorLearningPathSummary } from "./status-learning-path.js";
+import { buildProofCommandForOpenClawHome, buildProofCommandHelpSection, captureOperatorProofBundle, formatOperatorProofResult, parseProofCliArgs } from "./proof-command.js";
 const OPENCLAWBRAIN_EMBEDDER_BASE_URL_ENV = "OPENCLAWBRAIN_EMBEDDER_BASE_URL";
 const OPENCLAWBRAIN_EMBEDDER_PROVIDER_ENV = "OPENCLAWBRAIN_EMBEDDER_PROVIDER";
 const OPENCLAWBRAIN_EMBEDDER_MODEL_ENV = "OPENCLAWBRAIN_EMBEDDER_MODEL";
@@ -466,6 +467,7 @@ function buildSetupDeletedMessage() {
     ].join(" ");
 }
 function operatorCliHelp() {
+    const proofHelp = buildProofCommandHelpSection();
     return [
         "Usage:",
         "  openclawbrain install [--openclaw-home <path>] [options]",
@@ -480,6 +482,7 @@ function operatorCliHelp() {
         "  openclawbrain scan --session <trace.json> --root <path> [options]",
         "  openclawbrain scan --live <event-export-path> --workspace <workspace.json> [options]",
         "  openclawbrain learn [--activation-root <path>|--openclaw-home <path>] [--json]",
+        proofHelp.usage,
         "  openclawbrain-ops <status|rollback> [--activation-root <path>|--openclaw-home <path>] [options]  # compatibility alias",
         "  openclawbrain-ops scan --session <trace.json> --root <path> [options]    # compatibility alias",
         "",
@@ -508,6 +511,7 @@ function operatorCliHelp() {
         "  --limit <N>                 Maximum number of history entries to show (default: 20, history only).",
         "  --scan-root <path>          Event-export scan root for watch mode (defaults to <activation-root>/event-exports).",
         "  --interval <seconds>        Polling interval for watch mode (default: 30).",
+        ...proofHelp.optionLines,
         "  --json                      Emit machine-readable JSON instead of text.",
         "  --help                      Show this help.",
         "",
@@ -516,17 +520,19 @@ function operatorCliHelp() {
         "  2. attach             openclawbrain attach --openclaw-home <path> [--activation-root <path>] — explicit reattach/manual hook path for known brain data; use install first",
         "  3. status             openclawbrain status --activation-root <path> — answer \"How's the brain?\" for that boundary",
         "  4. status --detailed  openclawbrain status --activation-root <path> --detailed — explain serve path, freshness, backlog, and failure mode",
-        "  5. watch              openclawbrain watch --activation-root <path> — run the foreground learning/watch loop",
-        "  6. daemon start       openclawbrain daemon start --activation-root <path> — keep watch running in the background on macOS",
-        "  7. daemon status      openclawbrain daemon status --activation-root <path> — inspect the background watch state",
-        "  8. detach             openclawbrain detach --openclaw-home <path> — remove the profile hookup only and keep brain data",
-        "  9. uninstall          openclawbrain uninstall --openclaw-home <path> --keep-data|--purge-data — remove the hookup and choose the data outcome explicitly",
+        proofHelp.lifecycle,
+        "  6. watch              openclawbrain watch --activation-root <path> — run the foreground learning/watch loop",
+        "  7. daemon start       openclawbrain daemon start --activation-root <path> — keep watch running in the background on macOS",
+        "  8. daemon status      openclawbrain daemon status --activation-root <path> — inspect the background watch state",
+        "  9. detach             openclawbrain detach --openclaw-home <path> — remove the profile hookup only and keep brain data",
+        "  10. uninstall         openclawbrain uninstall --openclaw-home <path> --keep-data|--purge-data — remove the hookup and choose the data outcome explicitly",
         "",
         "Advanced/operator surfaces:",
         "  context      preview the brain context that would be injected for a message",
         "  rollback     preview or apply active <- previous, active -> candidate pointer movement",
         "  scan         inspect one recorded session or live event export without claiming a daemon is running",
         "  learn        one-shot local-session learning pass against the resolved activation root",
+        proofHelp.advanced,
         "  status --teacher-snapshot keeps the current live-first / principal-priority / passive-backfill learner order visible when that snapshot exists",
         "  native package installs still need the openclawbrain CLI available because install/attach pin the activation root for that package copy",
         "  watch/daemon persist their operator snapshot at <activation-root>/watch/teacher-snapshot.json; --teacher-snapshot overrides the default path",
@@ -539,7 +545,8 @@ function operatorCliHelp() {
         "  attach: 0 on successful profile hookup/bootstrap, 1 on input/read failure.",
         "  detach: 0 on successful unhook, 1 on input/read failure.",
         "  uninstall: 0 on successful unhook/cleanup, 1 on input/read failure.",
-        "  scan: 0 on successful replay/scan, 1 on input/read failure."
+        "  scan: 0 on successful replay/scan, 1 on input/read failure.",
+        "  proof: 0 on successful bundle capture, 1 on input/read failure."
     ].join("\n");
 }
 function yesNo(value) {
@@ -1880,7 +1887,7 @@ function buildStatusNextStep(status, report, options) {
         return "Repair the runtime-load proof file before trusting attach truth again; status now knows the exact file that broke.";
     }
     if (options.installHook.state === "installed" && status.brainStatus.serveState === "serving_active_pack") {
-        return "Check the OpenClaw startup log for the `[openclawbrain] BRAIN LOADED` breadcrumb when you need live hook-load proof.";
+        return `Capture a durable proof bundle: \`${buildProofCommandForOpenClawHome(options.openclawHome)}\`.`;
     }
     if (report.learning.warningStates.includes("principal_live_backlog") ||
         report.learning.warningStates.includes("active_pack_behind_latest_principal")) {
@@ -2007,9 +2014,12 @@ export function parseOperatorCliArgs(argv) {
         args.shift();
         return parseDaemonArgs(args);
     }
-    if (args[0] === "status" || args[0] === "rollback" || args[0] === "scan" || args[0] === "attach" || args[0] === "install" || args[0] === "detach" || args[0] === "uninstall" || args[0] === "context" || args[0] === "history" || args[0] === "learn" || args[0] === "watch" || args[0] === "export" || args[0] === "import" || args[0] === "reset") {
+    if (args[0] === "status" || args[0] === "rollback" || args[0] === "scan" || args[0] === "attach" || args[0] === "install" || args[0] === "detach" || args[0] === "uninstall" || args[0] === "context" || args[0] === "history" || args[0] === "learn" || args[0] === "watch" || args[0] === "export" || args[0] === "import" || args[0] === "reset" || args[0] === "proof") {
         command = args.shift();
     }
+    if (command === "proof") {
+        return parseProofCliArgs(args);
+    }
     if (command === "learn") {
         for (let index = 0; index < args.length; index += 1) {
             const arg = args[index];
@@ -3389,6 +3399,7 @@ function runProfileHookAttachCommand(parsed) {
             ? null
             : `Confirm gateway after restart: ${brainFeedback.restart.gatewayStatusCommand}`,
         `Check status: ${buildInstallStatusCommand(parsed.activationRoot)}`,
+        `Capture proof: ${buildProofCommandForOpenClawHome(parsed.openclawHome)}`,
         `Check learner service: ${buildLearnerServiceStatusCommand(parsed.activationRoot)}`,
         embedderProvision !== null && embedderProvision.state === "skipped"
             ? `Provision default embedder later: ${buildInstallEmbedderProvisionCommand(embedderProvision.baseUrl, embedderProvision.model)}`
@@ -3537,6 +3548,7 @@ function runProfileHookAttachCommand(parsed) {
             console.log(`Gateway:    Confirm OpenClaw after restart: ${brainFeedback.restart.gatewayStatusCommand}`);
         }
         console.log(`Check:      ${buildInstallStatusCommand(parsed.activationRoot)}`);
+        console.log(`Proof:      ${buildProofCommandForOpenClawHome(parsed.openclawHome)}`);
         console.log(`Learner:    ${buildLearnerServiceStatusCommand(parsed.activationRoot)}`);
         if (embedderProvision !== null && embedderProvision.state === "skipped") {
             console.log(`Embedder:   ${buildInstallEmbedderProvisionCommand(embedderProvision.baseUrl, embedderProvision.model)}`);
@@ -5548,6 +5560,28 @@ function runResetCommand(parsed) {
     }
     return 0;
 }
+function runProofCommand(parsed) {
+    if (parsed.help) {
+        console.log(operatorCliHelp());
+        return 0;
+    }
+    const result = captureOperatorProofBundle({
+        openclawHome: parsed.openclawHome,
+        activationRoot: parsed.activationRoot,
+        outputDir: parsed.outputDir,
+        skipInstall: parsed.skipInstall,
+        skipRestart: parsed.skipRestart,
+        pluginId: parsed.pluginId,
+        timeoutMs: parsed.timeoutMs,
+    });
+    if (parsed.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(formatOperatorProofResult(result));
+    }
+    return 0;
+}
 export function runOperatorCli(argv = process.argv.slice(2)) {
     const parsed = parseOperatorCliArgs(argv);
     if (parsed.command === "context") {
@@ -5556,6 +5590,9 @@ export function runOperatorCli(argv = process.argv.slice(2)) {
     if (parsed.command === "reset") {
         return runResetCommand(parsed);
     }
+    if (parsed.command === "proof") {
+        return runProofCommand(parsed);
+    }
     if (parsed.help) {
         console.log(operatorCliHelp());
         return 0;

package/dist/src/daemon.d.ts

@@ -8,7 +8,7 @@
  * Commands:
  *   daemon start  — generate and load a launchd plist
  *   daemon stop   — unload the plist
- *   daemon status — show running/stopped + PID + last log lines
+ *   daemon status — show running/stopped + PID + launch command + last log lines
  *   daemon logs   — tail the daemon log file
  */
 type DaemonCommandRunner = (command: string) => string;
@@ -42,6 +42,11 @@ export interface ManagedLearnerServiceInspection {
     running: boolean;
     pid: number | null;
     configuredActivationRoot: string | null;
+    configuredProgramArguments: string[] | null;
+    configuredCommand: string | null;
+    configuredRuntimePath: string | null;
+    configuredRuntimePackageSpec: string | null;
+    configuredRuntimeLooksEphemeral: boolean | null;
     matchesRequestedActivationRoot: boolean | null;
     launchctlAvailable: boolean;
 }

package/dist/src/daemon.js

@@ -8,7 +8,7 @@
  * Commands:
  *   daemon start  — generate and load a launchd plist
  *   daemon stop   — unload the plist
- *   daemon status — show running/stopped + PID + last log lines
+ *   daemon status — show running/stopped + PID + launch command + last log lines
  *   daemon logs   — tail the daemon log file
  */
 import { execSync } from "node:child_process";
@@ -22,6 +22,8 @@ const LOG_ROOT_DIRNAME = "daemon";
 const DEFAULT_SCAN_ROOT_DIRNAME = "event-exports";
 const BASELINE_STATE_BASENAME = "baseline-state.json";
 const SCANNER_CHECKPOINT_BASENAME = ".openclawbrain-scanner-checkpoint.json";
+const CLI_PACKAGE_NAME = "@openclawbrain/cli";
+const CLI_BIN_NAME = "openclawbrain";
 const DEFAULT_DAEMON_COMMAND_RUNNER = (command) => execSync(command, {
     encoding: "utf8",
     stdio: "pipe",
@@ -62,15 +64,81 @@ export function buildDaemonServiceIdentity(activationRoot) {
 export function setDaemonCommandRunnerForTesting(runner) {
     daemonCommandRunner = runner ?? DEFAULT_DAEMON_COMMAND_RUNNER;
 }
-function getOpenclawbrainBinPath() {
+function readPackageMetadata(packageRoot) {
+    if (packageRoot === null) {
+        return null;
+    }
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        return null;
+    }
     try {
-        const resolved = daemonCommandRunner("which openclawbrain").trim();
-        return resolved.length > 0 ? resolved : null;
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        const name = typeof packageJson.name === "string" && packageJson.name.trim().length > 0
+            ? packageJson.name.trim()
+            : null;
+        const version = typeof packageJson.version === "string" && packageJson.version.trim().length > 0
+            ? packageJson.version.trim()
+            : null;
+        if (name === null) {
+            return null;
+        }
+        return { name, version };
     }
     catch {
         return null;
     }
 }
+function isCliScriptPath(filePath) {
+    const basename = path.basename(filePath);
+    return basename === "cli.js" || basename === "cli.cjs" || basename === "cli.mjs";
+}
+function isNodeExecutablePath(filePath) {
+    return /^node(?:\.exe)?$/i.test(path.basename(filePath));
+}
+function isNpxCachePath(filePath) {
+    const resolvedPath = safeRealpath(path.resolve(filePath));
+    return resolvedPath.split(path.sep).includes("_npx");
+}
+function formatCommandArgument(value) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : JSON.stringify(value);
+}
+function formatCommand(programArguments) {
+    return programArguments.map((argument) => formatCommandArgument(argument)).join(" ");
+}
+function escapePlistString(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+function unescapePlistString(value) {
+    return value
+        .replace(/&apos;/g, "'")
+        .replace(/&quot;/g, "\"")
+        .replace(/&gt;/g, ">")
+        .replace(/&lt;/g, "<")
+        .replace(/&amp;/g, "&");
+}
+function getCommandPaths(commandName) {
+    try {
+        return daemonCommandRunner(`which -a ${commandName}`)
+            .split("\n")
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0);
+    }
+    catch {
+        try {
+            const resolved = daemonCommandRunner(`command -v ${commandName}`).trim();
+            return resolved.length > 0 ? [resolved] : [];
+        }
+        catch {
+            return [];
+        }
+    }
+}
 function safeRealpath(filePath) {
     try {
         return realpathSync(filePath);
@@ -110,62 +178,129 @@ function resolveCliScriptCandidate(candidatePath) {
         return null;
     }
     const resolvedCandidate = safeRealpath(absoluteCandidate);
-    const basename = path.basename(resolvedCandidate);
-    if (basename !== "cli.js" && basename !== "cli.cjs" && basename !== "cli.mjs") {
+    if (!isCliScriptPath(resolvedCandidate)) {
         return null;
     }
     return resolvedCandidate;
 }
-function getOpenclawbrainCliScriptPath() {
+function resolveCliPackageRoot(startDir) {
+    const packageRoot = resolvePackageRoot(startDir);
+    const packageMetadata = readPackageMetadata(packageRoot);
+    if (packageMetadata?.name === CLI_PACKAGE_NAME) {
+        return packageRoot;
+    }
+    if (packageRoot !== null) {
+        const siblingCliRoot = path.join(path.dirname(packageRoot), "cli");
+        const siblingMetadata = readPackageMetadata(siblingCliRoot);
+        if (siblingMetadata?.name === CLI_PACKAGE_NAME) {
+            return siblingCliRoot;
+        }
+    }
+    return null;
+}
+function resolveDaemonPackageManagerLaunchSpec(moduleDir) {
+    const cliPackageRoot = resolveCliPackageRoot(moduleDir);
+    const cliPackageMetadata = readPackageMetadata(cliPackageRoot);
+    if (cliPackageMetadata === null) {
+        return null;
+    }
+    const npmPath = getCommandPaths("npm").find((candidate) => !isNpxCachePath(candidate)) ?? null;
+    if (npmPath === null) {
+        return null;
+    }
+    const packageSpec = cliPackageMetadata.version === null
+        ? CLI_PACKAGE_NAME
+        : `${CLI_PACKAGE_NAME}@${cliPackageMetadata.version}`;
+    return {
+        programArguments: [npmPath, "exec", "--yes", `--package=${packageSpec}`, "--", CLI_BIN_NAME],
+        runtimePath: npmPath,
+        runtimePackageSpec: packageSpec,
+    };
+}
+function getOpenclawbrainCliScriptPathCandidates() {
     const moduleFilePath = fileURLToPath(import.meta.url);
     const moduleDir = path.dirname(moduleFilePath);
     const packageRoot = resolvePackageRoot(moduleDir);
-    const candidates = [
+    return [
         process.argv[1],
         path.join(moduleDir, "cli.js"),
         packageRoot === null ? null : path.join(packageRoot, "dist", "src", "cli.js")
     ];
-    for (const candidate of candidates) {
-        const resolved = resolveCliScriptCandidate(candidate);
-        if (resolved !== null) {
-            return resolved;
-        }
+}
+function buildDaemonLaunchProgramArguments(serviceIdentity, programArguments) {
+    return [...programArguments, "watch", "--activation-root", serviceIdentity.requestedActivationRoot];
+}
+function describeDaemonProgramArguments(programArguments) {
+    if (programArguments === null || programArguments.length === 0) {
+        return {
+            configuredProgramArguments: null,
+            configuredCommand: null,
+            configuredRuntimePath: null,
+            configuredRuntimePackageSpec: null,
+            configuredRuntimeLooksEphemeral: null
+        };
     }
-    return null;
+    const runtimePath = programArguments.length >= 2 && isNodeExecutablePath(programArguments[0]) && isCliScriptPath(programArguments[1])
+        ? programArguments[1]
+        : programArguments[0];
+    const runtimePackageSpec = programArguments.find((argument) => argument.startsWith("--package="))?.slice("--package=".length) ?? null;
+    return {
+        configuredProgramArguments: programArguments,
+        configuredCommand: formatCommand(programArguments),
+        configuredRuntimePath: runtimePath,
+        configuredRuntimePackageSpec: runtimePackageSpec,
+        configuredRuntimeLooksEphemeral: runtimePath === null ? null : isNpxCachePath(runtimePath)
+    };
 }
 function resolveDaemonProgramArguments() {
-    const cliScriptPath = getOpenclawbrainCliScriptPath();
-    if (cliScriptPath !== null) {
-        return [process.execPath, cliScriptPath];
+    for (const candidate of getOpenclawbrainCliScriptPathCandidates()) {
+        const cliScriptPath = resolveCliScriptCandidate(candidate);
+        if (cliScriptPath !== null && !isNpxCachePath(cliScriptPath)) {
+            return {
+                programArguments: [process.execPath, cliScriptPath],
+                runtimePath: cliScriptPath,
+                runtimePackageSpec: null,
+            };
+        }
     }
-    const binPath = getOpenclawbrainBinPath();
-    if (binPath !== null) {
-        return [binPath];
+    const durableBinPath = getCommandPaths(CLI_BIN_NAME).find((candidate) => !isNpxCachePath(candidate)) ?? null;
+    if (durableBinPath !== null) {
+        return {
+            programArguments: [durableBinPath],
+            runtimePath: durableBinPath,
+            runtimePackageSpec: null,
+        };
+    }
+    const moduleFilePath = fileURLToPath(import.meta.url);
+    const moduleDir = path.dirname(moduleFilePath);
+    const packageManagerLaunchSpec = resolveDaemonPackageManagerLaunchSpec(moduleDir);
+    if (packageManagerLaunchSpec !== null) {
+        return packageManagerLaunchSpec;
     }
     return null;
 }
 function buildPlistXml(serviceIdentity, programArguments) {
     const logPath = serviceIdentity.logPath;
     const homeDir = getHomeDir();
-    const daemonProgramArguments = [...programArguments, "watch", "--activation-root", serviceIdentity.requestedActivationRoot]
-        .map((argument) => `    <string>${argument}</string>`)
+    const daemonProgramArguments = buildDaemonLaunchProgramArguments(serviceIdentity, programArguments)
+        .map((argument) => `    <string>${escapePlistString(argument)}</string>`)
         .join("\n");
     return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
   <key>Label</key>
-  <string>${serviceIdentity.label}</string>
+  <string>${escapePlistString(serviceIdentity.label)}</string>
   <key>ProgramArguments</key>
   <array>
 ${daemonProgramArguments}
   </array>
   <key>WorkingDirectory</key>
-  <string>${serviceIdentity.requestedActivationRoot}</string>
+  <string>${escapePlistString(serviceIdentity.requestedActivationRoot)}</string>
   <key>StandardOutPath</key>
-  <string>${logPath}</string>
+  <string>${escapePlistString(logPath)}</string>
   <key>StandardErrorPath</key>
-  <string>${logPath}</string>
+  <string>${escapePlistString(logPath)}</string>
   <key>KeepAlive</key>
   <true/>
   <key>RunAtLoad</key>
@@ -173,9 +308,9 @@ ${daemonProgramArguments}
   <key>EnvironmentVariables</key>
   <dict>
     <key>HOME</key>
-    <string>${homeDir}</string>
+    <string>${escapePlistString(homeDir)}</string>
     <key>PATH</key>
-    <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    <string>${escapePlistString("/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin")}</string>
   </dict>
 </dict>
 </plist>
@@ -235,6 +370,7 @@ function getLaunchctlInfo(label) {
 function inspectManagedLearnerServiceInternal(activationRoot) {
     const serviceIdentity = buildDaemonServiceIdentity(activationRoot);
     const configuredActivationRoot = readDaemonActivationRoot(serviceIdentity.plistPath);
+    const configuredProgramArguments = readDaemonProgramArguments(serviceIdentity.plistPath);
     const info = getLaunchctlInfo(serviceIdentity.label);
     return {
         requestedActivationRoot: serviceIdentity.requestedActivationRoot,
@@ -246,6 +382,7 @@ function inspectManagedLearnerServiceInternal(activationRoot) {
         running: info.running,
         pid: info.pid,
         configuredActivationRoot,
+        ...describeDaemonProgramArguments(configuredProgramArguments),
         matchesRequestedActivationRoot: configuredActivationRoot === null
             ? null
             : canonicalizeActivationRoot(configuredActivationRoot) === serviceIdentity.canonicalActivationRoot,
@@ -262,11 +399,11 @@ function startManagedLearnerService(activationRoot) {
             inspection: inspectionBeforeStart
         };
     }
-    const programArguments = resolveDaemonProgramArguments();
-    if (programArguments === null) {
+    const launchSpec = resolveDaemonProgramArguments();
+    if (launchSpec === null) {
         return {
             ok: false,
-            message: "Failed to resolve an OpenClawBrain CLI launch command.",
+            message: "Failed to resolve an OpenClawBrain CLI launch command without pinning an npx cache path.",
             inspection: inspectionBeforeStart
         };
     }
@@ -275,7 +412,7 @@ function startManagedLearnerService(activationRoot) {
         mkdirSync(launchAgentsDir, { recursive: true });
     }
     ensureLogDir(serviceIdentity.logPath);
-    const plistContent = buildPlistXml(serviceIdentity, programArguments);
+    const plistContent = buildPlistXml(serviceIdentity, launchSpec.programArguments);
     writeFileSync(inspectionBeforeStart.plistPath, plistContent, "utf8");
     const result = launchctlLoad(inspectionBeforeStart.plistPath);
     if (!result.ok && !inspectionBeforeStart.installed) {
@@ -347,7 +484,7 @@ export function ensureManagedLearnerServiceForActivationRoot(activationRoot) {
     }
     const reason = !inspection.launchctlAvailable
         ? "launchctl_unavailable"
-        : startResult.message === "Failed to resolve an OpenClawBrain CLI launch command."
+        : startResult.message === "Failed to resolve an OpenClawBrain CLI launch command without pinning an npx cache path."
             ? "launch_command_unavailable"
             : "launch_failed";
     return {
@@ -419,19 +556,39 @@ function readOptionalJsonFile(filePath) {
         return null;
     }
 }
-function readDaemonActivationRoot(plistPath) {
+function readDaemonProgramArguments(plistPath) {
     if (!existsSync(plistPath)) {
         return null;
     }
     try {
         const plist = readFileSync(plistPath, "utf8");
-        const match = plist.match(/<string>--activation-root<\/string>\s*<string>([^<]+)<\/string>/);
-        return match?.[1] ?? null;
+        const sectionMatch = plist.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/);
+        if (sectionMatch === null) {
+            return null;
+        }
+        const programArguments = [];
+        const stringPattern = /<string>([\s\S]*?)<\/string>/g;
+        let match = stringPattern.exec(sectionMatch[1]);
+        while (match !== null) {
+            programArguments.push(unescapePlistString(match[1]));
+            match = stringPattern.exec(sectionMatch[1]);
+        }
+        return programArguments.length > 0 ? programArguments : null;
     }
     catch {
         return null;
     }
 }
+function readDaemonActivationRoot(plistPath) {
+    const programArguments = readDaemonProgramArguments(plistPath);
+    if (programArguments !== null) {
+        const activationRootIndex = programArguments.indexOf("--activation-root");
+        if (activationRootIndex !== -1) {
+            return programArguments[activationRootIndex + 1] ?? null;
+        }
+    }
+    return null;
+}
 function getWatchStatePaths(activationRoot) {
     if (activationRoot === null) {
         return {
@@ -611,9 +768,9 @@ export function daemonStart(activationRoot, json) {
     const serviceIdentity = buildDaemonServiceIdentity(activationRoot);
     const plistPath = serviceIdentity.plistPath;
     const logPath = serviceIdentity.logPath;
-    const programArguments = resolveDaemonProgramArguments();
-    if (programArguments === null) {
-        const message = "Failed to resolve an OpenClawBrain CLI launch command. Install/build the local package or make `openclawbrain` available on PATH.";
+    const launchSpec = resolveDaemonProgramArguments();
+    if (launchSpec === null) {
+        const message = "Failed to resolve an OpenClawBrain CLI launch command without pinning an npx cache path. Install/build @openclawbrain/cli or use a durable repo/runtime checkout.";
         if (json) {
             console.log(JSON.stringify({
                 command: "daemon start",
@@ -630,6 +787,8 @@ export function daemonStart(activationRoot, json) {
         }
         return 1;
     }
+    const daemonProgramArguments = buildDaemonLaunchProgramArguments(serviceIdentity, launchSpec.programArguments);
+    const daemonLaunchDescription = describeDaemonProgramArguments(daemonProgramArguments);
     // Ensure LaunchAgents dir exists
     const launchAgentsDir = path.dirname(plistPath);
     if (!existsSync(launchAgentsDir)) {
@@ -637,7 +796,7 @@ export function daemonStart(activationRoot, json) {
     }
     ensureLogDir(logPath);
     // Write the plist
-    const plistContent = buildPlistXml(serviceIdentity, programArguments);
+    const plistContent = buildPlistXml(serviceIdentity, launchSpec.programArguments);
     writeFileSync(plistPath, plistContent, "utf8");
     // Load it
     const result = launchctlLoad(plistPath);
@@ -649,6 +808,7 @@ export function daemonStart(activationRoot, json) {
             logPath,
             activationRoot: serviceIdentity.requestedActivationRoot,
             serviceLabel: serviceIdentity.label,
+            ...daemonLaunchDescription,
             message: result.message,
         }, null, 2));
     }
@@ -659,6 +819,15 @@ export function daemonStart(activationRoot, json) {
             console.log(`  Plist: ${plistPath}`);
             console.log(`  Log:   ${logPath}`);
             console.log(`  Root:  ${serviceIdentity.requestedActivationRoot}`);
+            if (daemonLaunchDescription.configuredRuntimePath !== null) {
+                const runtimePackageSuffix = daemonLaunchDescription.configuredRuntimePackageSpec === null
+                    ? ""
+                    : ` (${daemonLaunchDescription.configuredRuntimePackageSpec})`;
+                console.log(`  Runtime: ${daemonLaunchDescription.configuredRuntimePath}${runtimePackageSuffix}`);
+            }
+            if (daemonLaunchDescription.configuredCommand !== null) {
+                console.log(`  Command: ${daemonLaunchDescription.configuredCommand}`);
+            }
         }
         else {
             console.error(`✗ ${result.message}`);
@@ -725,12 +894,14 @@ export function daemonStatus(activationRoot, json) {
     const info = getLaunchctlInfo(serviceIdentity.label);
     const lastLogLines = readLastLines(logPath, 5);
     const configuredActivationRoot = readDaemonActivationRoot(plistPath);
+    const configuredProgramArguments = readDaemonProgramArguments(plistPath);
     const requestedActivationRoot = serviceIdentity.requestedActivationRoot;
     const watchStatePaths = getWatchStatePaths(requestedActivationRoot);
     const watchState = readWatchStateSummary(requestedActivationRoot);
     const matchesRequestedActivationRoot = configuredActivationRoot === null
         ? null
         : canonicalizeActivationRoot(configuredActivationRoot) === serviceIdentity.canonicalActivationRoot;
+    const daemonLaunchDescription = describeDaemonProgramArguments(configuredProgramArguments);
     if (json) {
         console.log(JSON.stringify({
             command: "daemon status",
@@ -742,6 +913,7 @@ export function daemonStatus(activationRoot, json) {
             logPath,
             activationRoot: requestedActivationRoot,
             configuredActivationRoot,
+            ...daemonLaunchDescription,
             matchesRequestedActivationRoot,
             ...watchStatePaths,
             watchState,
@@ -766,6 +938,22 @@ export function daemonStatus(activationRoot, json) {
         if (matchesRequestedActivationRoot === false) {
             console.log("  Requested root does not match the installed daemon plist.");
         }
+        if (daemonLaunchDescription.configuredRuntimePath !== null) {
+            const runtimePackageSuffix = daemonLaunchDescription.configuredRuntimePackageSpec === null
+                ? ""
+                : ` (${daemonLaunchDescription.configuredRuntimePackageSpec})`;
+            const runtimeWarning = daemonLaunchDescription.configuredRuntimeLooksEphemeral ? " [ephemeral]" : "";
+            console.log(`  Runtime: ${daemonLaunchDescription.configuredRuntimePath}${runtimePackageSuffix}${runtimeWarning}`);
+        }
+        if (configuredProgramArguments !== null && configuredProgramArguments.length > 0) {
+            console.log(`  Program: ${configuredProgramArguments[0]}`);
+            if (configuredProgramArguments.length > 1) {
+                console.log(`  Args: ${configuredProgramArguments.slice(1).map((argument) => formatCommandArgument(argument)).join(" ")}`);
+            }
+        }
+        if (daemonLaunchDescription.configuredCommand !== null) {
+            console.log(`  Command: ${daemonLaunchDescription.configuredCommand}`);
+        }
         console.log(`  Log: ${logPath}`);
         if (watchState.scanRoot !== null) {
             console.log(`  Scan root: ${watchState.scanRoot}`);
@@ -904,7 +1092,7 @@ export function daemonHelp() {
         "Subcommands:",
         "  start   Generate a macOS launchd plist and start the daemon (runs openclawbrain watch).",
         "  stop    Stop the daemon and remove the launchd plist.",
-        "  status  Show whether the daemon is running, its PID, and recent log lines.",
+        "  status  Show whether the daemon is running, its PID, configured launch command, and recent log lines.",
         "  logs    Show the last 50 lines of the per-activation-root daemon log under ~/.openclawbrain/daemon/.",
         "",
         "Options:",

package/dist/src/proof-command.js

@@ -0,0 +1,654 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+export const DEFAULT_OPERATOR_PROOF_PLUGIN_ID = "openclawbrain";
+export const DEFAULT_OPERATOR_PROOF_TIMEOUT_MS = 120_000;
+
+function quoteShellArg(value) {
+    return `'${value.replace(/'/g, `"'"'`)}'`;
+}
+
+function normalizeOptionalCliString(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+
+function canonicalizeExistingProofPath(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    try {
+        return realpathSync(resolvedPath);
+    }
+    catch {
+        return resolvedPath;
+    }
+}
+
+function shellJoin(parts) {
+    return parts
+        .map((part) => {
+        if (/^[A-Za-z0-9_./:@=-]+$/.test(part)) {
+            return part;
+        }
+        return JSON.stringify(part);
+    })
+        .join(" ");
+}
+
+function timestampToken(date = new Date()) {
+    return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z").replace("T", "-");
+}
+
+function resolveProofOutputDir(options) {
+    if (options.outputDir !== null) {
+        return path.resolve(options.outputDir);
+    }
+    return path.resolve(options.cwd ?? process.cwd(), "artifacts", `operator-proof-${timestampToken()}`);
+}
+
+function writeText(filePath, text) {
+    mkdirSync(path.dirname(filePath), { recursive: true });
+    writeFileSync(filePath, text, "utf8");
+}
+
+function writeJson(filePath, value) {
+    writeText(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function buildCurrentCliInvocation(cliEntryPath = process.argv[1]) {
+    const normalizedEntryPath = normalizeOptionalCliString(cliEntryPath);
+    if (normalizedEntryPath === null) {
+        return {
+            command: "openclawbrain",
+            args: []
+        };
+    }
+    return {
+        command: process.execPath,
+        args: [path.resolve(normalizedEntryPath)]
+    };
+}
+
+function defaultRunCapture(command, args, options = {}) {
+    const startedAt = new Date();
+    const result = spawnSync(command, args, {
+        cwd: options.cwd ?? process.cwd(),
+        env: options.env ?? process.env,
+        encoding: "utf8",
+        timeout: options.timeoutMs,
+    });
+    const endedAt = new Date();
+    return {
+        label: options.label ?? command,
+        command,
+        argv: args,
+        shellCommand: shellJoin([command, ...args]),
+        startedAt: startedAt.toISOString(),
+        endedAt: endedAt.toISOString(),
+        durationMs: endedAt.getTime() - startedAt.getTime(),
+        exitCode: typeof result.status === "number" ? result.status : null,
+        signal: result.signal ?? null,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        error: result.error ? String(result.error) : null,
+    };
+}
+
+function summarizeCapture(step) {
+    let resultClass = "unknown";
+    if (step.exitCode === 0 && !step.error) {
+        resultClass = "success";
+    }
+    else if (step.signal === "SIGTERM" || step.signal === "SIGKILL") {
+        resultClass = "interrupted";
+    }
+    else if (step.error && /timed out/i.test(step.error)) {
+        resultClass = "timed_out";
+    }
+    else if (step.exitCode !== 0 || step.error) {
+        resultClass = "command_failed";
+    }
+    const captureState = step.exitCode === null && !step.stdout && !step.stderr
+        ? "missing"
+        : step.exitCode === null
+            ? "partial"
+            : "complete";
+    return { resultClass, captureState };
+}
+
+function writeStepBundle(bundleDir, stepId, capture) {
+    const stdoutName = `${stepId}.stdout.log`;
+    const stderrName = `${stepId}.stderr.log`;
+    writeText(path.join(bundleDir, stdoutName), capture.stdout);
+    writeText(path.join(bundleDir, stderrName), capture.stderr);
+    return { stdoutName, stderrName };
+}
+
+function extractGatewayLogPath(text) {
+    const match = text.match(/^File logs:\s+(.+)$/m);
+    return match ? match[1].trim() : null;
+}
+
+function extractActivationRoot(statusText, override) {
+    if (override !== null) {
+        return path.resolve(override);
+    }
+    const targetMatch = statusText.match(/^target\s+activation=([^\s]+)\s+/m);
+    if (targetMatch) {
+        return targetMatch[1].trim();
+    }
+    const hostMatch = statusText.match(/^host\s+runtime=[^\s]+\s+activation=([^\s]+)$/m);
+    if (hostMatch) {
+        return hostMatch[1].trim();
+    }
+    return path.join(homedir(), ".openclawbrain", "activation");
+}
+
+function readTextIfExists(filePath) {
+    if (filePath === null || !existsSync(filePath)) {
+        return null;
+    }
+    return readFileSync(filePath, "utf8");
+}
+
+function readJsonSnapshot(filePath) {
+    if (filePath === null) {
+        return {
+            path: null,
+            exists: false,
+            error: "proof path unresolved",
+            value: null
+        };
+    }
+    if (!existsSync(filePath)) {
+        return {
+            path: filePath,
+            exists: false,
+            error: null,
+            value: null
+        };
+    }
+    try {
+        return {
+            path: filePath,
+            exists: true,
+            error: null,
+            value: JSON.parse(readFileSync(filePath, "utf8"))
+        };
+    }
+    catch (error) {
+        return {
+            path: filePath,
+            exists: true,
+            error: error instanceof Error ? error.message : String(error),
+            value: null
+        };
+    }
+}
+
+function extractStartupBreadcrumbs(logText, bundleStartedAtIso) {
+    if (!logText) {
+        return { all: [], afterBundleStart: [] };
+    }
+    const bundleStartMs = Date.parse(bundleStartedAtIso);
+    const out = [];
+    for (const line of logText.split(/\r?\n/)) {
+        if (!line.includes("[openclawbrain] BRAIN LOADED") && !line.includes("[openclawbrain] BRAIN NOT YET LOADED")) {
+            continue;
+        }
+        let parsed = null;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            parsed = null;
+        }
+        const timestamp = parsed?._meta?.date ?? parsed?.time ?? null;
+        out.push({
+            line,
+            timestamp,
+            kind: line.includes("BRAIN LOADED") ? "loaded" : "not_yet_loaded",
+        });
+    }
+    return {
+        all: out,
+        afterBundleStart: out.filter((entry) => entry.timestamp && Date.parse(entry.timestamp) >= bundleStartMs),
+    };
+}
+
+function extractStatusSignals(statusText) {
+    return {
+        statusOk: /^STATUS ok$/m.test(statusText),
+        loadProofReady: /loadProof=status_probe_ready/.test(statusText),
+        runtimeProven: /attachTruth .*runtime=proven/.test(statusText),
+        pluginInstalled: /hook\s+install=installed/.test(statusText),
+        serveActivePack: /serve\s+state=serving_active_pack/.test(statusText),
+        routeFnAvailable: /routeFn\s+available=yes/.test(statusText),
+        proofPath: statusText.match(/proofPath=([^\s]+)/)?.[1] ?? null,
+    };
+}
+
+function hasPackagedHookSource(pluginInspectText) {
+    return /Source:\s+.*(?:@openclawbrain[\\/]+openclaw|openclawbrain)[\\/]+dist[\\/]+extension[\\/]+index\.js/m.test(pluginInspectText);
+}
+
+function buildVerdict({ steps, gatewayStatus, pluginInspect, statusSignals, breadcrumbs, runtimeLoadProofSnapshot, openclawHome }) {
+    const failedStep = steps.find((step) => step.resultClass !== "success" && step.skipped !== true);
+    if (failedStep) {
+        return {
+            verdict: "command_failed",
+            severity: "blocking",
+            why: `${failedStep.stepId} exited as ${failedStep.resultClass}`,
+        };
+    }
+    const gatewayHealthy = /Runtime:\s+running/m.test(gatewayStatus) && /RPC probe:\s+ok/m.test(gatewayStatus);
+    const pluginLoaded = /Status:\s+loaded/m.test(pluginInspect);
+    const packagedHookPath = hasPackagedHookSource(pluginInspect);
+    const breadcrumbLoaded = breadcrumbs.afterBundleStart.some((entry) => entry.kind === "loaded");
+    const runtimeProofMatched = Array.isArray(runtimeLoadProofSnapshot?.value?.profiles)
+        && runtimeLoadProofSnapshot.value.profiles.some((profile) => canonicalizeExistingProofPath(profile?.openclawHome ?? "") === canonicalizeExistingProofPath(openclawHome));
+    const missingProofs = [];
+    if (!gatewayHealthy)
+        missingProofs.push("gateway_health");
+    if (!pluginLoaded)
+        missingProofs.push("plugin_loaded");
+    if (!packagedHookPath)
+        missingProofs.push("packaged_hook_path");
+    if (!statusSignals.statusOk)
+        missingProofs.push("status_ok");
+    if (!statusSignals.loadProofReady)
+        missingProofs.push("load_proof");
+    if (!statusSignals.runtimeProven)
+        missingProofs.push("runtime_proven");
+    if (!statusSignals.serveActivePack)
+        missingProofs.push("serve_active_pack");
+    if (!statusSignals.routeFnAvailable)
+        missingProofs.push("route_fn");
+    if (!breadcrumbLoaded)
+        missingProofs.push("startup_breadcrumb");
+    if (!runtimeProofMatched)
+        missingProofs.push("runtime_load_proof_record");
+    if (missingProofs.length === 0) {
+        return {
+            verdict: "success_and_proven",
+            severity: "none",
+            why: "install, restart, gateway health, plugin load, startup breadcrumb, runtime-load-proof record, and detailed status all aligned",
+        };
+    }
+    const blocking = missingProofs.some((item) => [
+        "gateway_health",
+        "plugin_loaded",
+        "packaged_hook_path",
+        "status_ok",
+        "load_proof",
+        "runtime_proven",
+        "serve_active_pack",
+        "route_fn",
+    ].includes(item));
+    return {
+        verdict: blocking ? "degraded_or_failed_proof" : "success_but_proof_incomplete",
+        severity: blocking ? "blocking" : "degraded",
+        why: `missing or conflicting proofs: ${missingProofs.join(", ")}`,
+        missingProofs,
+    };
+}
+
+function buildSummary({ options, steps, verdict, gatewayStatusText, pluginInspectText, statusSignals, breadcrumbs, runtimeLoadProofSnapshot }) {
+    const passed = [];
+    const missing = [];
+    if (steps.find((step) => step.stepId === "01-install")?.resultClass === "success") {
+        passed.push("install command succeeded");
+    }
+    if (steps.find((step) => step.stepId === "02-restart")?.skipped === true || steps.find((step) => step.stepId === "02-restart")?.resultClass === "success") {
+        passed.push("restart step completed or was intentionally skipped");
+    }
+    if (/Runtime:\s+running/m.test(gatewayStatusText) && /RPC probe:\s+ok/m.test(gatewayStatusText)) {
+        passed.push("gateway status showed runtime running and RPC probe ok");
+    }
+    if (/Status:\s+loaded/m.test(pluginInspectText)) {
+        passed.push("plugin inspect showed OpenClawBrain loaded");
+    }
+    if (statusSignals.statusOk) {
+        passed.push("detailed status returned STATUS ok");
+    }
+    if (statusSignals.loadProofReady) {
+        passed.push("detailed status reported loadProof=status_probe_ready");
+    }
+    if (statusSignals.serveActivePack) {
+        passed.push("detailed status reported serve state=serving_active_pack");
+    }
+    if (statusSignals.routeFnAvailable) {
+        passed.push("detailed status reported routeFn available=yes");
+    }
+    if (breadcrumbs.afterBundleStart.some((entry) => entry.kind === "loaded")) {
+        passed.push("startup log contained a post-bundle [openclawbrain] BRAIN LOADED breadcrumb");
+    }
+    if (!statusSignals.loadProofReady)
+        missing.push("detailed status did not prove hook load");
+    if (!breadcrumbs.afterBundleStart.some((entry) => entry.kind === "loaded"))
+        missing.push("no post-bundle startup breadcrumb was found");
+    if (runtimeLoadProofSnapshot.path === null)
+        missing.push("runtime-load-proof path could not be resolved");
+    if (runtimeLoadProofSnapshot.error !== null)
+        missing.push(`runtime-load-proof snapshot was unreadable: ${runtimeLoadProofSnapshot.error}`);
+    const lines = [
+        "# OpenClawBrain operator proof summary",
+        "",
+        `- openclaw home: \`${options.openclawHome}\``,
+        `- bundle verdict: **${verdict.verdict}**`,
+        `- severity: **${verdict.severity}**`,
+        `- why: ${verdict.why}`,
+        "",
+        "## Passed",
+        ...passed.map((item) => `- ${item}`),
+        "",
+        "## Missing / incomplete",
+        ...(missing.length === 0 ? ["- none"] : missing.map((item) => `- ${item}`)),
+        "",
+        "## Step ledger",
+        ...steps.map((step) => `- ${step.stepId}: ${step.skipped ? "skipped" : `${step.resultClass} (${step.captureState})`} - ${step.summary}`),
+    ];
+    if (runtimeLoadProofSnapshot.path !== null) {
+        lines.push("", "## Runtime proof file", `- ${runtimeLoadProofSnapshot.path}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+
+function readOpenClawProfileName(openclawHome) {
+    try {
+        const openclawJsonPath = path.join(openclawHome, "openclaw.json");
+        if (!existsSync(openclawJsonPath)) {
+            return null;
+        }
+        const parsed = JSON.parse(readFileSync(openclawJsonPath, "utf8"));
+        return normalizeOptionalCliString(parsed?.profile);
+    }
+    catch {
+        return null;
+    }
+}
+
+function buildGatewayArgs(action, profileName) {
+    return profileName === null
+        ? ["gateway", action]
+        : ["gateway", action, "--profile", profileName];
+}
+
+export function buildProofCommandForOpenClawHome(openclawHome) {
+    return `openclawbrain proof --openclaw-home ${quoteShellArg(path.resolve(openclawHome))}`;
+}
+
+export function buildProofCommandHelpSection() {
+    return {
+        usage: "  openclawbrain proof --openclaw-home <path> [options]",
+        optionLines: [
+            "  --output-dir <path>         Bundle directory for proof artifacts (proof only). Defaults to ./artifacts/operator-proof-<timestamp>.",
+            "  --skip-install              Capture proof without rerunning install first (proof only).",
+            "  --skip-restart              Capture proof without restarting OpenClaw first (proof only).",
+            `  --plugin-id <id>            Plugin id for \`openclaw plugins inspect\` (proof only; default: ${DEFAULT_OPERATOR_PROOF_PLUGIN_ID}).`,
+            `  --timeout-ms <ms>           Per-step timeout in ms for proof capture (proof only; default: ${DEFAULT_OPERATOR_PROOF_TIMEOUT_MS}).`,
+        ],
+        lifecycle: "  5. proof              openclawbrain proof --openclaw-home <path> - capture one durable operator proof bundle after install/restart/status",
+        advanced: "  proof        capture one durable operator proof bundle with step logs, startup breadcrumbs, and a runtime-load-proof snapshot",
+    };
+}
+
+export function parseProofCliArgs(argv, options = {}) {
+    const existsSyncImpl = options.existsSyncImpl ?? existsSync;
+    let openclawHome = null;
+    let activationRoot = null;
+    let outputDir = null;
+    let skipInstall = false;
+    let skipRestart = false;
+    let pluginId = DEFAULT_OPERATOR_PROOF_PLUGIN_ID;
+    let timeoutMs = DEFAULT_OPERATOR_PROOF_TIMEOUT_MS;
+    let json = false;
+    let help = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "--help" || arg === "-h") {
+            help = true;
+            continue;
+        }
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--skip-install") {
+            skipInstall = true;
+            continue;
+        }
+        if (arg === "--skip-restart") {
+            skipRestart = true;
+            continue;
+        }
+        if (arg === "--openclaw-home") {
+            const next = argv[index + 1];
+            if (next === undefined) {
+                throw new Error("--openclaw-home requires a value");
+            }
+            openclawHome = next;
+            index += 1;
+            continue;
+        }
+        if (arg === "--activation-root") {
+            const next = argv[index + 1];
+            if (next === undefined) {
+                throw new Error("--activation-root requires a value");
+            }
+            activationRoot = next;
+            index += 1;
+            continue;
+        }
+        if (arg === "--output-dir") {
+            const next = argv[index + 1];
+            if (next === undefined) {
+                throw new Error("--output-dir requires a value");
+            }
+            outputDir = next;
+            index += 1;
+            continue;
+        }
+        if (arg === "--plugin-id") {
+            const next = argv[index + 1];
+            if (next === undefined) {
+                throw new Error("--plugin-id requires a value");
+            }
+            pluginId = next;
+            index += 1;
+            continue;
+        }
+        if (arg === "--timeout-ms") {
+            const next = argv[index + 1];
+            if (next === undefined) {
+                throw new Error("--timeout-ms requires a value");
+            }
+            const parsed = Number.parseInt(next, 10);
+            if (!Number.isInteger(parsed) || parsed < 1) {
+                throw new Error("--timeout-ms must be a positive integer");
+            }
+            timeoutMs = parsed;
+            index += 1;
+            continue;
+        }
+        throw new Error(`unknown argument for proof: ${arg}`);
+    }
+    if (help) {
+        return {
+            command: "proof",
+            openclawHome: "",
+            activationRoot: null,
+            outputDir: null,
+            skipInstall,
+            skipRestart,
+            pluginId,
+            timeoutMs,
+            json,
+            help
+        };
+    }
+    if (openclawHome === null) {
+        throw new Error("proof requires --openclaw-home <path>");
+    }
+    const resolvedOpenClawHome = path.resolve(openclawHome);
+    if (!existsSyncImpl(resolvedOpenClawHome)) {
+        throw new Error(`--openclaw-home directory does not exist: ${resolvedOpenClawHome}`);
+    }
+    return {
+        command: "proof",
+        openclawHome: resolvedOpenClawHome,
+        activationRoot: activationRoot === null ? null : path.resolve(activationRoot),
+        outputDir: outputDir === null ? null : path.resolve(outputDir),
+        skipInstall,
+        skipRestart,
+        pluginId,
+        timeoutMs,
+        json,
+        help
+    };
+}
+
+export function captureOperatorProofBundle(options) {
+    const cliInvocation = options.cliInvocation ?? buildCurrentCliInvocation();
+    const runCapture = options.runCapture ?? defaultRunCapture;
+    const bundleStartedAt = new Date().toISOString();
+    const bundleDir = resolveProofOutputDir(options);
+    mkdirSync(bundleDir, { recursive: true });
+    const steps = [];
+    const gatewayProfile = readOpenClawProfileName(options.openclawHome);
+    function addStep(stepId, label, command, args, { skipped = false } = {}) {
+        if (skipped) {
+            steps.push({
+                stepId,
+                label,
+                shellCommand: shellJoin([command, ...args]),
+                skipped: true,
+                captureState: "complete",
+                resultClass: "success",
+                summary: "step intentionally skipped",
+                stdoutPath: null,
+                stderrPath: null,
+            });
+            return { stdout: "", stderr: "", exitCode: 0, signal: null, error: null };
+        }
+        const capture = runCapture(command, args, {
+            label,
+            cwd: options.cwd ?? process.cwd(),
+            env: options.env ?? process.env,
+            timeoutMs: options.timeoutMs,
+        });
+        const { stdoutName, stderrName } = writeStepBundle(bundleDir, stepId, capture);
+        const summary = summarizeCapture(capture);
+        steps.push({
+            stepId,
+            label,
+            shellCommand: capture.shellCommand ?? shellJoin([command, ...args]),
+            startedAt: capture.startedAt ?? null,
+            endedAt: capture.endedAt ?? null,
+            durationMs: capture.durationMs ?? null,
+            exitCode: capture.exitCode ?? null,
+            signal: capture.signal ?? null,
+            resultClass: summary.resultClass,
+            captureState: summary.captureState,
+            summary: summary.resultClass === "success"
+                ? `${label} completed successfully`
+                : `${label} ended as ${summary.resultClass}`,
+            stdoutPath: stdoutName,
+            stderrPath: stderrName,
+        });
+        return capture;
+    }
+    addStep("01-install", "install", cliInvocation.command, [...cliInvocation.args, "install", "--openclaw-home", options.openclawHome], { skipped: options.skipInstall === true });
+    addStep("02-restart", "gateway restart", "openclaw", buildGatewayArgs("restart", gatewayProfile), { skipped: options.skipRestart === true });
+    const gatewayStatusCapture = addStep("03-gateway-status", "gateway status", "openclaw", buildGatewayArgs("status", gatewayProfile));
+    const pluginInspectCapture = addStep("04-plugin-inspect", "plugin inspect", "openclaw", ["plugins", "inspect", options.pluginId]);
+    const statusCapture = addStep("05-detailed-status", "detailed status", cliInvocation.command, [...cliInvocation.args, "status", "--openclaw-home", options.openclawHome, "--detailed"]);
+    const gatewayLogPath = extractGatewayLogPath(gatewayStatusCapture.stdout);
+    const activationRoot = extractActivationRoot(statusCapture.stdout, options.activationRoot ?? null);
+    const runtimeLoadProofPath = path.join(activationRoot, "attachment-truth", "runtime-load-proofs.json");
+    const runtimeLoadProofSnapshot = readJsonSnapshot(runtimeLoadProofPath);
+    const gatewayLogText = readTextIfExists(gatewayLogPath);
+    const breadcrumbs = extractStartupBreadcrumbs(gatewayLogText, bundleStartedAt);
+    const statusSignals = extractStatusSignals(statusCapture.stdout);
+    writeText(path.join(bundleDir, "extracted-startup-breadcrumbs.log"), breadcrumbs.all.length === 0
+        ? "<no matching breadcrumbs found>\n"
+        : `${breadcrumbs.all.map((entry) => entry.line).join("\n")}\n`);
+    writeJson(path.join(bundleDir, "runtime-load-proof.json"), runtimeLoadProofSnapshot);
+    const verdict = buildVerdict({
+        steps,
+        gatewayStatus: gatewayStatusCapture.stdout,
+        pluginInspect: pluginInspectCapture.stdout,
+        statusSignals,
+        breadcrumbs,
+        runtimeLoadProofSnapshot,
+        openclawHome: options.openclawHome,
+    });
+    writeJson(path.join(bundleDir, "steps.json"), {
+        bundleStartedAt,
+        openclawHome: canonicalizeExistingProofPath(options.openclawHome),
+        activationRoot,
+        gatewayProfile,
+        gatewayLogPath,
+        steps,
+    });
+    writeJson(path.join(bundleDir, "verdict.json"), {
+        bundleStartedAt,
+        verdict,
+        statusSignals,
+        breadcrumbs: {
+            allCount: breadcrumbs.all.length,
+            postBundleCount: breadcrumbs.afterBundleStart.length,
+            postBundleKinds: breadcrumbs.afterBundleStart.map((entry) => entry.kind),
+        },
+        runtimeLoadProofPath,
+        runtimeLoadProofError: runtimeLoadProofSnapshot.error,
+    });
+    writeText(path.join(bundleDir, "summary.md"), buildSummary({
+        options,
+        steps,
+        verdict,
+        gatewayStatusText: gatewayStatusCapture.stdout,
+        pluginInspectText: pluginInspectCapture.stdout,
+        statusSignals,
+        breadcrumbs,
+        runtimeLoadProofSnapshot,
+    }));
+    return {
+        ok: true,
+        bundleDir,
+        bundleStartedAt,
+        activationRoot,
+        gatewayProfile,
+        gatewayLogPath,
+        runtimeLoadProofPath,
+        runtimeLoadProofSnapshot,
+        verdict,
+        statusSignals,
+        steps,
+        summaryPath: path.join(bundleDir, "summary.md"),
+        stepsPath: path.join(bundleDir, "steps.json"),
+        verdictPath: path.join(bundleDir, "verdict.json"),
+        breadcrumbPath: path.join(bundleDir, "extracted-startup-breadcrumbs.log"),
+        runtimeLoadProofSnapshotPath: path.join(bundleDir, "runtime-load-proof.json"),
+    };
+}
+
+export function formatOperatorProofResult(result) {
+    const lines = [
+        `PROOF ${result.verdict.verdict}`,
+        `  Severity: ${result.verdict.severity}`,
+        `  Why: ${result.verdict.why}`,
+        `  Bundle: ${result.bundleDir}`,
+        `  Summary: ${result.summaryPath}`,
+        `  Steps: ${result.stepsPath}`,
+        `  Verdict: ${result.verdictPath}`,
+        `  Breadcrumbs: ${result.breadcrumbPath}`,
+        `  Runtime proof: ${result.runtimeLoadProofSnapshotPath}`,
+    ];
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclawbrain/cli",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "description": "OpenClawBrain operator CLI package with install/status helpers, daemon controls, and import/export tooling.",
   "type": "module",
   "main": "./dist/src/index.js",