@openclawbrain/cli 0.4.10 → 0.4.12

package/README.md

@@ -1,31 +1,32 @@
 # @openclawbrain/cli
 
-`@openclawbrain/cli@0.4.10` is the published operator CLI package for OpenClawBrain.
+Operator CLI for OpenClawBrain. Use it with `@openclawbrain/openclaw`.
 
-Primary public flow:
+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@0.4.0
-npx @openclawbrain/cli@0.4.10 install --openclaw-home ~/.openclaw
+openclaw plugins install @openclawbrain/openclaw
+npx @openclawbrain/cli install --openclaw-home ~/.openclaw
 openclaw gateway restart
-npx @openclawbrain/cli@0.4.10 status --openclaw-home ~/.openclaw --detailed
+npx @openclawbrain/cli status --openclaw-home ~/.openclaw --detailed
+npx @openclawbrain/cli proof --openclaw-home ~/.openclaw --skip-install --skip-restart
 ```
 
-Patch note for `0.4.4`: the CLI now normalizes `plugins.allow` / `plugins.entries.openclawbrain` correctly on reinstall and reports the canonical `openclawbrain` install identity in status output.
+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.
 
-Host release note: patched OpenClaw host builds no longer emit the old `openclaw` vs `openclawbrain` mismatch warning. Older host builds may still show that warning until the host-side alias fix is released there.
-
-This package carries the `openclawbrain` CLI, daemon controls, import/export helpers, and install/status/operator management code. `@openclawbrain/openclaw` is the plugin/runtime payload.
-
-## Commands
+## Common commands
 
 ```bash
-npx @openclawbrain/cli@0.4.10 install --openclaw-home ~/.openclaw
-npx @openclawbrain/cli@0.4.10 status --openclaw-home ~/.openclaw --detailed
-npx @openclawbrain/cli@0.4.10 rollback --activation-root /var/openclawbrain/activation --dry-run
-npx @openclawbrain/cli@0.4.10 daemon status --activation-root /var/openclawbrain/activation
+npx @openclawbrain/cli rollback --openclaw-home ~/.openclaw --dry-run
+npx @openclawbrain/cli detach --openclaw-home ~/.openclaw
+npx @openclawbrain/cli uninstall --openclaw-home ~/.openclaw --keep-data
+npx @openclawbrain/cli learn --openclaw-home ~/.openclaw --json
+npx @openclawbrain/cli daemon status --activation-root ~/.openclawbrain/activation
 ```
 
-If the CLI is already on your `PATH`, `openclawbrain ...` is the same command surface. The docs lead with `npx` because that is the clean-host public-registry lane that already passed on `redogfood`.
+## Docs
 
-The old `openclawbrain-ops` alias stays wired to the same entrypoint for compatibility.
+- [Repo README](../../README.md)
+- [Quick start](../../docs/getting-started/quick-start.md)
+- [Lifecycle](../../docs/lifecycle.md)
+- [Troubleshooting](../../docs/operating/troubleshooting.md)

package/dist/src/cli.js

@@ -23,6 +23,8 @@ import { summarizePackVectorEmbeddingState } from "./embedding-status.js";
 import { buildTracedLearningBridgePayloadFromRuntime, buildTracedLearningStatusSurface, persistTracedLearningBridgeState } from "./traced-learning-bridge.js";
 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";
@@ -465,6 +467,7 @@ function buildSetupDeletedMessage() {
     ].join(" ");
 }
 function operatorCliHelp() {
+    const proofHelp = buildProofCommandHelpSection();
     return [
         "Usage:",
         "  openclawbrain install [--openclaw-home <path>] [options]",
@@ -479,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",
         "",
@@ -507,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.",
         "",
@@ -515,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",
@@ -538,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) {
@@ -1396,7 +1404,11 @@ function formatCurrentProfileStatusSummary(status, report, targetInspection, opt
         `scanner     flowing=${yesNo(report.supervision.flowing)} scan=${report.supervision.scanPolicy ?? "none"} surfaces=${formatScannerSurfaces(report)} labels=${report.supervision.humanLabelCount ?? "none"}/${report.supervision.selfLabelCount ?? "none"} attributable=${report.supervision.attributedEventCount ?? "none"}/${report.supervision.totalEventCount ?? "none"} digests=${report.supervision.selectionDigestCount ?? "none"}`,
         `labels      ${formatLabelFlowSummary(report.labelFlow)}`,
         `graph       source=${report.graph.runtimePlasticitySource ?? "none"} blocks=${report.graph.blockCount ?? "none"} strongest=${report.graph.strongestBlockId ?? "none"} ops=${formatStructuralOps(report)} latest=${report.graph.latestMaterialization.packId ?? "none"} latestChanged=${yesNo(report.graph.latestMaterialization.changed)} connect=${formatGraphConnectDiagnostics(report.graph.latestMaterialization.connectDiagnostics ?? report.graph.connectDiagnostics)} summary=${formatGraphSummary(report)}`,
-        `path        ${formatLearningPathSummary(report.learningPath)}`,
+        `path        ${formatOperatorLearningPathSummary({
+            status,
+            learningPath: report.learningPath,
+            tracedLearning
+        })}`,
         `learning    state=${report.learning.backlogState} bootstrapped=${yesNo(report.learning.bootstrapped)} mode=${report.learning.mode} next=${report.learning.nextPriorityLane} priority=${report.learning.nextPriorityBucket} pending=${report.learning.pendingLive ?? "none"}/${report.learning.pendingBackfill ?? "none"} buckets=${formatLearningBuckets(report)} warn=${formatLearningWarnings(report)} lastPack=${report.learning.lastMaterializedPackId ?? "none"} detail=${report.learning.detail}`,
         `traced      ${formatTracedLearningSurface(tracedLearning)}`,
         `teacherProof ${formatTeacherLoopSummary(report)}`,
@@ -1875,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")) {
@@ -2002,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];
@@ -3384,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)}`
@@ -3532,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)}`);
@@ -4238,7 +4255,8 @@ function runLearnCommand(parsed) {
         maxCycles: 16,
         pgVersion: serveTimeLearning.pgVersion,
         ...(serveTimeLearning.decisionLogCount > 0 ? { serveTimeDecisions: serveTimeLearning.serveTimeDecisions } : {}),
-        ...(serveTimeLearning.baselineState !== undefined ? { baselineState: serveTimeLearning.baselineState } : {})
+        ...(serveTimeLearning.baselineState !== undefined ? { baselineState: serveTimeLearning.baselineState } : {}),
+        activationRoot
     });
     const lastMaterialization = learnerResult.materializations.at(-1) ?? null;
     const plan = describeAlwaysOnLearningRuntimeState(learnerResult.state, lastMaterialization);
@@ -5542,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") {
@@ -5550,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;
 }