@openclawbrain/cli 0.4.29 → 0.4.30

package/dist/src/cli.js

@@ -562,7 +562,7 @@ function operatorCliHelp() {
         "  openclawbrain-ops scan --session <trace.json> --root <path> [options]    # compatibility alias",
         "",
         "Options:",
-        "  --openclaw-home <path>      OpenClaw home dir for install/attach/detach/uninstall (e.g. ~/.openclaw-Tern or ~/.openclaw). Also pins status/rollback/context/history/learn to that installed target when applicable.",
+        "  --openclaw-home <path>      OpenClaw home dir for install/attach/detach/uninstall (e.g. ./openclaw-cormorantai, ~/.openclaw-Tern, or ~/.openclaw). Also pins status/rollback/context/history/learn to that installed target when applicable.",
         "  --shared                    Set brain-attachment-policy to shared instead of dedicated (install/attach only).",
         `  --skip-embedder-provision  Skip the default Ollama ${DEFAULT_OLLAMA_EMBEDDING_MODEL} pull before install/attach bootstrap. Use only when intentionally deferring embedder setup. Also supports ${OPENCLAWBRAIN_INSTALL_SKIP_EMBEDDER_PROVISION_ENV}=1.`,
         "  --activation-root <path>    Explicit activation root for attach/watch/daemon and other stateful commands; install/attach default to sibling .openclawbrain/activation next to the selected OpenClaw home.",
@@ -602,6 +602,11 @@ function operatorCliHelp() {
         "  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",
         "",
+        "Examples:",
+        "  openclawbrain install --openclaw-home ./openclaw-cormorantai",
+        "  openclawbrain status --openclaw-home ./openclaw-cormorantai --detailed",
+        "  openclawbrain proof --openclaw-home ./openclaw-cormorantai",
+        "",
         "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",
@@ -955,16 +960,69 @@ function summarizeStatusAttachmentTruth(input) {
         })
     };
 }
+let cachedCliPackageMetadata = null;
+function resolveCliPackageManifestPath() {
+    const candidates = [
+        path.resolve(__dirname, "..", "..", "package.json"),
+        path.resolve(__dirname, "..", "package.json"),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error("OpenClawBrain CLI package manifest not found. Searched:\n" +
+        candidates.map((candidate) => `  - ${candidate}`).join("\n"));
+}
+function readCliPackageMetadata() {
+    if (cachedCliPackageMetadata !== null) {
+        return cachedCliPackageMetadata;
+    }
+    const manifest = JSON.parse(readFileSync(resolveCliPackageManifestPath(), "utf8"));
+    const name = typeof manifest.name === "string" && manifest.name.trim().length > 0
+        ? manifest.name.trim()
+        : "@openclawbrain/cli";
+    const version = typeof manifest.version === "string" && manifest.version.trim().length > 0
+        ? manifest.version.trim()
+        : "0.0.0";
+    cachedCliPackageMetadata = { name, version };
+    return cachedCliPackageMetadata;
+}
+function inspectDaemonRuntimeSurface(activationRoot) {
+    const managedInspection = inspectManagedLearnerService(activationRoot);
+    if (managedInspection.installed === true ||
+        managedInspection.configuredRuntimePath !== null ||
+        managedInspection.configuredRuntimePackageSpec !== null ||
+        managedInspection.configuredRuntimePackageName !== null ||
+        managedInspection.configuredRuntimePackageVersion !== null) {
+        return {
+            ...managedInspection,
+            surfaceIdentitySource: "managed_service"
+        };
+    }
+    const cliPackageMetadata = readCliPackageMetadata();
+    return {
+        ...managedInspection,
+        configuredRuntimePath: canonicalizeExistingCliPath(__filename),
+        configuredRuntimePackageName: cliPackageMetadata.name,
+        configuredRuntimePackageVersion: cliPackageMetadata.version,
+        configuredRuntimePackageSpec: null,
+        surfaceIdentitySource: "current_cli"
+    };
+}
 function summarizeStatusHotfixBoundary(status) {
     return describeOpenClawBrainHotfixBoundary({
         hookInspection: status.hook,
-        daemonInspection: inspectManagedLearnerService(status.host.activationRoot)
+        daemonInspection: inspectDaemonRuntimeSurface(status.host.activationRoot)
     });
 }
 function formatStatusHotfixBoundarySummary(boundary) {
     return [
         `boundary=${boundary.boundary}`,
         `skew=${boundary.skew}`,
+        `converge=${boundary.convergeState ?? "unverified"}`,
+        `daemonSource=${boundary.daemonSource ?? "unverified"}`,
+        `selectedHome=${boundary.selectedOpenClawHome === null ? "unverified" : shortenPath(boundary.selectedOpenClawHome)}`,
         `daemon=${boundary.daemonPackage ?? "unverified"}`,
         `hook=${boundary.hookPackage ?? "unverified"}`
     ].join(" ");
@@ -1649,6 +1707,8 @@ function readInstallRuntimeFingerprint(openclawHome) {
         openclawHome,
         quiet: true
     });
+    const activationRoot = resolvedActivationRoot.trim().length === 0 ? null : path.resolve(resolvedActivationRoot);
+    const daemonSurface = activationRoot === null ? null : inspectDaemonRuntimeSurface(activationRoot);
     const { config } = readOpenClawJsonConfig(openclawHome);
     return {
         selectedInstall: selectedInstall === null
@@ -1664,10 +1724,15 @@ function readInstallRuntimeFingerprint(openclawHome) {
         hookPath: hook.hookPath,
         hookState: hook.installState,
         loadability: hook.loadability,
-        activationRoot: resolvedActivationRoot.trim().length === 0 ? null : path.resolve(resolvedActivationRoot),
+        activationRoot,
         loaderSource: readTextFileIfExists(selectedInstall?.loaderEntryPath ?? null),
         runtimeGuardSource: readTextFileIfExists(selectedInstall?.runtimeGuardPath ?? null),
-        pluginsConfig: JSON.stringify(config.plugins ?? null)
+        pluginsConfig: JSON.stringify(config.plugins ?? null),
+        daemonRuntimePath: daemonSurface?.configuredRuntimePath ?? null,
+        daemonRuntimePackageName: daemonSurface?.configuredRuntimePackageName ?? null,
+        daemonRuntimePackageVersion: daemonSurface?.configuredRuntimePackageVersion ?? null,
+        daemonRuntimePackageSpec: daemonSurface?.configuredRuntimePackageSpec ?? null,
+        daemonRuntimeSource: daemonSurface?.surfaceIdentitySource ?? null
     };
 }
 function runOpenClawBrainConvergePluginStep(openclawHome) {
@@ -1738,7 +1803,22 @@ function inspectInstallConvergeVerification(parsed) {
         status: normalizedStatusAndReport.status
     });
     const displayedStatus = summarizeDisplayedStatus(normalizedStatusAndReport.status, installHook);
+    const hotfixBoundary = summarizeStatusHotfixBoundary(normalizedStatusAndReport.status);
+    const surfaceSummary = hotfixBoundary.convergeState === "half_converged"
+        ? `daemon runtime and installed hook/runtime-guard are half-converged: ${hotfixBoundary.detail}`
+        : hotfixBoundary.convergeState === "warning"
+            ? `daemon runtime and installed hook/runtime-guard identity is not fully proven: ${hotfixBoundary.detail}`
+            : hotfixBoundary.convergeState === "unverified"
+                ? `daemon runtime and installed hook/runtime-guard convergence is unverified: ${hotfixBoundary.detail}`
+                : hotfixBoundary.detail;
     const routeFn = summarizeStatusRouteFn(normalizedStatusAndReport.status, normalizedStatusAndReport.report);
+    const defaultNextStep = buildStatusNextStep(normalizedStatusAndReport.status, normalizedStatusAndReport.report, {
+        openclawHome: parsed.openclawHome,
+        installHook
+    });
+    const nextStep = hotfixBoundary.convergeState === "half_converged"
+        ? `Daemon runtime and installed hook/runtime-guard are half-converged for ${shortenPath(parsed.openclawHome)} (${hotfixBoundary.skew}); refresh the daemon-side CLI/runtime surface, then rerun ${buildInstallCommand(parsed.openclawHome)}.`
+        : defaultNextStep;
     return {
         targetInspection,
         status: normalizedStatusAndReport.status,
@@ -1747,11 +1827,9 @@ function inspectInstallConvergeVerification(parsed) {
         attachmentTruth,
         displayedStatus,
         routeFn,
-        nextStep: buildStatusNextStep(normalizedStatusAndReport.status, normalizedStatusAndReport.report, {
-            openclawHome: parsed.openclawHome,
-            installHook
-        }),
-        summaryLine: `STATUS ${displayedStatus}; hook=${installHook.state}/${installHook.loadability}; guard=${normalizedStatusAndReport.status.hook.guardSeverity}/${normalizedStatusAndReport.status.hook.guardActionability}; runtime=${attachmentTruth.runtimeLoad}; loadProof=${normalizedStatusAndReport.status.hook.loadProof}; serve=${normalizedStatusAndReport.status.brainStatus.serveState}`,
+        hotfixBoundary,
+        nextStep,
+        summaryLine: `STATUS ${displayedStatus}; hook=${installHook.state}/${installHook.loadability}; surface=${hotfixBoundary.convergeState}/${hotfixBoundary.skew}; guard=${normalizedStatusAndReport.status.hook.guardSeverity}/${normalizedStatusAndReport.status.hook.guardActionability}; runtime=${attachmentTruth.runtimeLoad}; loadProof=${normalizedStatusAndReport.status.hook.loadProof}; serve=${normalizedStatusAndReport.status.brainStatus.serveState}`,
         facts: {
             installLayout: normalizedStatusAndReport.status.hook.installLayout ?? installHook.installLayout ?? null,
             installState: installHook.state,
@@ -1763,7 +1841,17 @@ function inspectInstallConvergeVerification(parsed) {
             loadProof: normalizedStatusAndReport.status.hook.loadProof,
             serveState: normalizedStatusAndReport.status.brainStatus.serveState,
             routeFnAvailable: routeFn.available,
-            awaitingFirstExport: normalizedStatusAndReport.status.brainStatus.awaitingFirstExport
+            awaitingFirstExport: normalizedStatusAndReport.status.brainStatus.awaitingFirstExport,
+            surfaceBoundary: hotfixBoundary.boundary,
+            surfaceSkew: hotfixBoundary.skew,
+            surfaceConvergeState: hotfixBoundary.convergeState,
+            surfaceSummary,
+            daemonPackage: hotfixBoundary.daemonPackage,
+            hookPackage: hotfixBoundary.hookPackage,
+            daemonPath: hotfixBoundary.daemonPath,
+            hookPath: hotfixBoundary.hookPath,
+            runtimeGuardPath: hotfixBoundary.runtimeGuardPath,
+            selectedOpenClawHome: hotfixBoundary.selectedOpenClawHome
         }
     };
 }
@@ -4065,6 +4153,8 @@ function emitInstallConvergeResult(result, parsed) {
     console.log(`Attach:     ${result.attach.detail}`);
     console.log(`Restart:    ${result.restart.detail}`);
     console.log(`Verify:     ${result.verification.summaryLine}`);
+    console.log(`Surface:    ${result.verification.surface.summaryLine}`);
+    console.log(`Paths:      ${result.verification.surface.pathsLine}`);
     console.log(`Verdict:    ${result.verdict.verdict}`);
     console.log(`Why:        ${result.verdict.why}`);
     if (result.verdict.warnings.length > 0) {
@@ -4126,7 +4216,22 @@ function runInstallCommand(parsed) {
                 loadProof: "unknown",
                 serveState: "unknown",
                 routeFnAvailable: false,
-                awaitingFirstExport: false
+                awaitingFirstExport: false,
+                surface: {
+                    summaryLine: "daemon/runtime hook surface identity was not verified because install failed earlier",
+                    pathsLine: "daemonPath=none hookPath=unverified runtimeGuard=unverified",
+                    boundary: "unknown",
+                    skew: "unknown",
+                    convergeState: "unknown",
+                    daemonSource: "unknown",
+                    daemonPackage: null,
+                    hookPackage: null,
+                    detail: "install failed before daemon/runtime hook surface identity could be verified",
+                    daemonPath: null,
+                    hookPath: null,
+                    runtimeGuardPath: null,
+                    selectedOpenClawHome: parsed.openclawHome
+                }
             },
             verdict
         };
@@ -4211,7 +4316,22 @@ function runInstallCommand(parsed) {
             loadProof: verificationSnapshot.facts.loadProof,
             serveState: verificationSnapshot.facts.serveState,
             routeFnAvailable: verificationSnapshot.facts.routeFnAvailable,
-            awaitingFirstExport: verificationSnapshot.facts.awaitingFirstExport
+            awaitingFirstExport: verificationSnapshot.facts.awaitingFirstExport,
+            surface: {
+                summaryLine: `boundary=${verificationSnapshot.hotfixBoundary.boundary}; skew=${verificationSnapshot.hotfixBoundary.skew}; converge=${verificationSnapshot.hotfixBoundary.convergeState}; daemonSource=${verificationSnapshot.hotfixBoundary.daemonSource}; selectedHome=${verificationSnapshot.hotfixBoundary.selectedOpenClawHome === null ? "unverified" : shortenPath(verificationSnapshot.hotfixBoundary.selectedOpenClawHome)}; daemon=${verificationSnapshot.hotfixBoundary.daemonPackage ?? "unverified"}; hook=${verificationSnapshot.hotfixBoundary.hookPackage ?? "unverified"}; detail=${verificationSnapshot.hotfixBoundary.detail}`,
+                pathsLine: `daemonPath=${verificationSnapshot.hotfixBoundary.daemonPath === null ? "none" : shortenPath(verificationSnapshot.hotfixBoundary.daemonPath)} hookPath=${verificationSnapshot.hotfixBoundary.hookPath === null ? "unverified" : shortenPath(verificationSnapshot.hotfixBoundary.hookPath)} runtimeGuard=${verificationSnapshot.hotfixBoundary.runtimeGuardPath === null ? "unverified" : shortenPath(verificationSnapshot.hotfixBoundary.runtimeGuardPath)}`,
+                boundary: verificationSnapshot.hotfixBoundary.boundary,
+                skew: verificationSnapshot.hotfixBoundary.skew,
+                convergeState: verificationSnapshot.hotfixBoundary.convergeState,
+                daemonSource: verificationSnapshot.hotfixBoundary.daemonSource,
+                daemonPackage: verificationSnapshot.hotfixBoundary.daemonPackage,
+                hookPackage: verificationSnapshot.hotfixBoundary.hookPackage,
+                detail: verificationSnapshot.hotfixBoundary.detail,
+                daemonPath: verificationSnapshot.hotfixBoundary.daemonPath,
+                hookPath: verificationSnapshot.hotfixBoundary.hookPath,
+                runtimeGuardPath: verificationSnapshot.hotfixBoundary.runtimeGuardPath,
+                selectedOpenClawHome: verificationSnapshot.hotfixBoundary.selectedOpenClawHome
+            }
         },
         verdict,
         underlyingInstall: attachResult

package/dist/src/install-converge.js

@@ -10,8 +10,22 @@ const CHANGE_REASON_LABELS = {
   loader_source: "loader source changed",
   runtime_guard_source: "runtime-guard source changed",
   plugins_config: "OpenClaw plugins config changed",
+  daemon_runtime_path: "daemon runtime path changed",
+  daemon_runtime_identity: "daemon runtime identity changed",
 };
 
+const GATEWAY_RESTART_CHANGE_REASONS = new Set([
+  "install_identity",
+  "install_layout",
+  "hook_path",
+  "hook_state",
+  "loadability",
+  "activation_root",
+  "loader_source",
+  "runtime_guard_source",
+  "plugins_config",
+]);
+
 function sameValue(left, right) {
   return left === right;
 }
@@ -28,6 +42,32 @@ function installIdentityOf(fingerprint) {
   });
 }
 
+function daemonRuntimeIdentityOf(fingerprint) {
+  return JSON.stringify({
+    runtimePackageName: fingerprint?.daemonRuntimePackageName ?? null,
+    runtimePackageVersion: fingerprint?.daemonRuntimePackageVersion ?? null,
+    runtimePackageSpec: fingerprint?.daemonRuntimePackageSpec ?? null,
+    runtimeSource: fingerprint?.daemonRuntimeSource ?? null,
+  });
+}
+
+function describeSurfaceHalfConvergedReason(input) {
+  const boundary = input.surfaceBoundary ?? null;
+  const skew = input.surfaceSkew ?? null;
+  const selectedOpenClawHome = input.selectedOpenClawHome ?? null;
+  const daemonPackage = input.daemonPackage ?? null;
+  const hookPackage = input.hookPackage ?? null;
+  const boundarySuffix = boundary === null
+    ? ""
+    : skew === null || skew === "unverified"
+      ? ` (${boundary})`
+      : ` (${boundary}/${skew})`;
+  const packageSuffix = daemonPackage === null && hookPackage === null
+    ? ""
+    : `; daemon=${daemonPackage ?? "unverified"} hook=${hookPackage ?? "unverified"}`;
+  return `daemon runtime and installed hook/runtime-guard are half-converged${selectedOpenClawHome === null ? "" : ` for ${selectedOpenClawHome}`}${boundarySuffix}${packageSuffix}`;
+}
+
 export function shouldReplaceOpenClawBrainInstallBeforeConverge(fingerprint) {
   const selectedInstall = fingerprint?.selectedInstall ?? null;
   if (selectedInstall === null) {
@@ -99,6 +139,12 @@ export function diffOpenClawBrainConvergeRuntimeFingerprint(before, after) {
   if (!sameValue(before?.pluginsConfig ?? null, after?.pluginsConfig ?? null)) {
     reasons.push("plugins_config");
   }
+  if (!sameValue(before?.daemonRuntimePath ?? null, after?.daemonRuntimePath ?? null)) {
+    reasons.push("daemon_runtime_path");
+  }
+  if (!sameValue(daemonRuntimeIdentityOf(before), daemonRuntimeIdentityOf(after))) {
+    reasons.push("daemon_runtime_identity");
+  }
   return {
     changed: reasons.length > 0,
     reasons,
@@ -114,12 +160,15 @@ export function describeOpenClawBrainConvergeChangeReasons(reasons) {
 
 export function buildOpenClawBrainConvergeRestartPlan(input) {
   const changeReasons = input.changeReasons ?? [];
-  if (changeReasons.length === 0) {
+  const gatewayRestartReasons = changeReasons.filter((reason) => GATEWAY_RESTART_CHANGE_REASONS.has(reason));
+  if (gatewayRestartReasons.length === 0) {
     return {
       required: false,
       automatic: false,
-      reason: "no_runtime_affecting_changes",
-      detail: "Skipped gateway restart because converge did not change plugin files, hook wiring, or the pinned activation root.",
+      reason: changeReasons.length === 0 ? "no_runtime_affecting_changes" : "daemon_only_runtime_changes",
+      detail: changeReasons.length === 0
+        ? "Skipped gateway restart because converge did not change plugin files, hook wiring, or the pinned activation root."
+        : "Skipped gateway restart because converge only changed the daemon runtime surface; the selected OpenClaw hook/runtime-guard wiring did not change.",
     };
   }
   if (input.profileName === null) {
@@ -149,6 +198,13 @@ export function classifyOpenClawBrainConvergeVerification(input) {
   const loadProof = input.loadProof ?? "unverified";
   const serveState = input.serveState ?? "unknown";
   const installedPackageName = input.installedPackageName ?? null;
+  const surfaceConvergeState = input.surfaceConvergeState ?? null;
+  const surfaceBoundary = input.surfaceBoundary ?? null;
+  const surfaceSkew = input.surfaceSkew ?? null;
+  const selectedOpenClawHome = input.selectedOpenClawHome ?? null;
+  const daemonPackage = input.daemonPackage ?? null;
+  const hookPackage = input.hookPackage ?? null;
+  const surfaceSummary = input.surfaceSummary ?? null;
   if (installedPackageName === LEGACY_COMPAT_PACKAGE_NAME) {
     blockingReasons.push(`installed plugin still references the retired compatibility package ${LEGACY_COMPAT_PACKAGE_NAME}; converge must replace it with @openclawbrain/openclaw`);
   }
@@ -164,6 +220,15 @@ export function classifyOpenClawBrainConvergeVerification(input) {
   if (displayedStatus === "fail") {
     blockingReasons.push("status still reports fail");
   }
+  if (surfaceConvergeState === "half_converged") {
+    blockingReasons.push(surfaceSummary ?? describeSurfaceHalfConvergedReason({
+      surfaceBoundary,
+      surfaceSkew,
+      selectedOpenClawHome,
+      daemonPackage,
+      hookPackage,
+    }));
+  }
   const runtimeTruthAlreadyProven = runtimeLoad === "proven"
     && loadProof === "status_probe_ready"
     && installState === "installed"
@@ -182,6 +247,12 @@ export function classifyOpenClawBrainConvergeVerification(input) {
   if (input.restartRequired === true && input.restartPerformed !== true && runtimeTruthAlreadyProven) {
     warnings.push("automatic restart was not performed because install could not infer an exact OpenClaw profile token, but current status already proves runtime load");
   }
+  if (surfaceConvergeState === "warning") {
+    warnings.push(surfaceSummary ?? "daemon runtime vs installed hook/runtime-guard identity is not fully proven from this verification snapshot");
+  }
+  if (surfaceConvergeState === "unverified") {
+    warnings.push(surfaceSummary ?? "daemon runtime vs installed hook/runtime-guard convergence is not fully proven from this verification snapshot");
+  }
   // When runtime proof is green for the repaired profile, promote the proof
   // surface to healthy rather than leaving stale degraded warnings that
   // contradict the proven truth.

package/dist/src/openclaw-hook-truth.js

@@ -66,6 +66,58 @@ function normalizeSurfacePath(filePath) {
         ? path.resolve(filePath)
         : null;
 }
+function classifyRuntimeSurfaceConvergeState(input) {
+    const reasons = [];
+    if (input.scope === "activation_root_only") {
+        reasons.push("selected_openclaw_home_unverified");
+        return {
+            state: "unverified",
+            reasons
+        };
+    }
+    if (input.daemonPath === null) {
+        reasons.push("daemon_surface_unverified");
+    }
+    if (input.hookPath === null && input.runtimeGuardPath === null) {
+        reasons.push("installed_surface_unverified");
+        return {
+            state: input.daemonPath === null ? "unverified" : "half_converged",
+            reasons
+        };
+    }
+    if (input.hookLoadability !== "loadable") {
+        reasons.push("installed_surface_not_loadable");
+        return {
+            state: input.daemonPath === null ? "unverified" : "half_converged",
+            reasons
+        };
+    }
+    if (input.daemonPath === null) {
+        return {
+            state: "unverified",
+            reasons
+        };
+    }
+    if (input.samePath) {
+        reasons.push("same_path");
+        return {
+            state: "converged",
+            reasons
+        };
+    }
+    if (input.daemonVersion !== null && input.hookVersion !== null) {
+        reasons.push(input.daemonVersion === input.hookVersion ? "split_path_same_version" : "version_skew");
+        return {
+            state: input.daemonVersion === input.hookVersion ? "converged" : "half_converged",
+            reasons
+        };
+    }
+    reasons.push("version_unverified");
+    return {
+        state: "unverified",
+        reasons
+    };
+}
 function inspectInstalledHookActivationRoot(loaderEntryPath) {
     let content;
     try {
@@ -328,77 +380,101 @@ export function describeOpenClawBrainHotfixBoundary(input) {
     const daemonPath = normalizeSurfacePath(daemonInspection?.configuredRuntimePath ?? null);
     const hookPath = normalizeSurfacePath(hookInspection.hookPath);
     const runtimeGuardPath = normalizeSurfacePath(hookInspection.runtimeGuardPath);
+    const selectedOpenClawHome = typeof hookInspection.openclawHome === "string" && hookInspection.openclawHome.trim().length > 0
+        ? path.resolve(hookInspection.openclawHome)
+        : null;
+    const daemonSource = daemonInspection?.surfaceIdentitySource ?? (daemonPath === null ? "unverified" : "managed_service");
+    const daemonPackageName = daemonInspection?.configuredRuntimePackageName ?? null;
+    const daemonPackageVersion = daemonInspection?.configuredRuntimePackageVersion ?? null;
+    const hookPackageName = hookInspection.packageName ?? null;
+    const hookPackageVersion = hookInspection.packageVersion ?? null;
     const daemonPackage = formatPackageIdentity(daemonInspection?.configuredRuntimePackageName ?? null, daemonInspection?.configuredRuntimePackageVersion ?? null, daemonInspection?.configuredRuntimePackageSpec ?? null);
     const hookPackage = formatPackageIdentity(hookInspection.packageName, hookInspection.packageVersion);
+    const samePath = daemonPath === hookPath || daemonPath === runtimeGuardPath;
+    const daemonVersion = daemonPackageVersion;
+    const hookVersion = hookPackageVersion;
+    let boundary;
+    let skew;
+    let displayedHookPath = hookPath;
+    let displayedRuntimeGuardPath = runtimeGuardPath;
+    let displayedDaemonPackage = daemonPackage;
+    let displayedHookPackage = hookPackage;
+    let guidance;
+    let detail;
     if (hookInspection.scope === "activation_root_only") {
-        return {
-            boundary: "hook_surface_unverified",
-            skew: "unverified",
-            daemonPath,
-            hookPath: null,
-            runtimeGuardPath: null,
-            daemonPackage,
-            hookPackage: null,
-            guidance: "Pin --openclaw-home before patching the installed hook/runtime-guard surface; activation-root-only status does not prove which OpenClaw install you would be changing.",
-            detail: daemonPath === null
-                ? "activation-root-only status does not expose the installed hook/runtime-guard surface."
-                : `daemon runtime path ${shortenPath(daemonPath)} is visible, but activation-root-only status still does not expose the installed hook/runtime-guard surface.`
-        };
+        boundary = "hook_surface_unverified";
+        skew = "unverified";
+        displayedHookPath = null;
+        displayedRuntimeGuardPath = null;
+        displayedHookPackage = null;
+        guidance = "Pin --openclaw-home before patching the installed hook/runtime-guard surface; activation-root-only status does not prove which OpenClaw install you would be changing.";
+        detail = daemonPath === null
+            ? "activation-root-only status does not expose the installed hook/runtime-guard surface."
+            : `daemon runtime path ${shortenPath(daemonPath)} is visible, but activation-root-only status still does not expose the installed hook/runtime-guard surface.`;
     }
-    if (hookPath === null && runtimeGuardPath === null) {
-        return {
-            boundary: "hook_surface_unverified",
-            skew: "unverified",
-            daemonPath,
-            hookPath: null,
-            runtimeGuardPath: null,
-            daemonPackage,
-            hookPackage,
-            guidance: daemonPath === null
-                ? "Repair or reinstall the installed hook surface before patching OpenClaw load behavior."
-                : "Patch the daemon runtime path for background watch fixes, but repair or reinstall the installed hook/runtime-guard surface before patching OpenClaw load behavior.",
-            detail: daemonPath === null
-                ? "no verified daemon runtime path or installed hook/runtime-guard path is visible from this status snapshot."
-                : `daemon runtime path ${shortenPath(daemonPath)} is visible, but the installed hook/runtime-guard surface is not yet loadable.`
-        };
+    else if (hookPath === null && runtimeGuardPath === null) {
+        boundary = "hook_surface_unverified";
+        skew = "unverified";
+        displayedHookPath = null;
+        displayedRuntimeGuardPath = null;
+        guidance = daemonPath === null
+            ? "Repair or reinstall the installed hook surface before patching OpenClaw load behavior."
+            : "Patch the daemon runtime path for background watch fixes, but repair or reinstall the installed hook/runtime-guard surface before patching OpenClaw load behavior.";
+        detail = daemonPath === null
+            ? "no verified daemon runtime path or installed hook/runtime-guard path is visible from this status snapshot."
+            : `daemon runtime path ${shortenPath(daemonPath)} is visible, but the installed hook/runtime-guard surface is not yet loadable.`;
     }
-    if (daemonPath === null) {
-        return {
-            boundary: "daemon_surface_only",
-            skew: "unverified",
-            daemonPath: null,
-            hookPath,
-            runtimeGuardPath,
-            daemonPackage: null,
-            hookPackage,
-            guidance: "Patch the installed hook/runtime-guard surface for OpenClaw load fixes. No configured daemon runtime path is visible from status.",
-            detail: `installed hook loads from ${hookPath === null ? "unverified" : shortenPath(hookPath)}${runtimeGuardPath === null ? "" : ` with runtime-guard ${shortenPath(runtimeGuardPath)}`}, but no configured daemon runtime path is visible.`
-        };
+    else if (daemonPath === null) {
+        boundary = "daemon_surface_only";
+        skew = "unverified";
+        displayedDaemonPackage = null;
+        guidance = "Patch the installed hook/runtime-guard surface for OpenClaw load fixes. No configured daemon runtime path is visible from status.";
+        detail = `installed hook loads from ${hookPath === null ? "unverified" : shortenPath(hookPath)}${runtimeGuardPath === null ? "" : ` with runtime-guard ${shortenPath(runtimeGuardPath)}`}, but no configured daemon runtime path is visible.`;
     }
-    const samePath = daemonPath === hookPath || daemonPath === runtimeGuardPath;
-    const daemonVersion = daemonInspection?.configuredRuntimePackageVersion ?? null;
-    const hookVersion = hookInspection.packageVersion ?? null;
-    const skew = samePath
-        ? "same_path"
-        : daemonVersion !== null && hookVersion !== null
-            ? daemonVersion === hookVersion
-                ? "split_path_same_version"
-                : "split_path_version_skew"
-            : "split_path_version_unverified";
+    else {
+        skew = samePath
+            ? "same_path"
+            : daemonVersion !== null && hookVersion !== null
+                ? daemonVersion === hookVersion
+                    ? "split_path_same_version"
+                    : "split_path_version_skew"
+                : "split_path_version_unverified";
+        boundary = samePath ? "same_surface" : "split_surfaces";
+        guidance = samePath
+            ? "Daemon and installed hook paths currently collapse to the same file; verify both surfaces before patching anyway."
+            : "Patch the daemon runtime path for background watch/learner fixes. Patch the installed hook/runtime-guard paths for OpenClaw load fixes.";
+        detail = samePath
+            ? `daemon runtime path ${shortenPath(daemonPath)} currently resolves to the same file as the installed OpenClaw hook surface.`
+            : `daemon background watch runs from ${shortenPath(daemonPath)}${daemonPackage === null ? "" : ` (${daemonPackage})`}; OpenClaw loads the installed hook from ${hookPath === null ? "unverified" : shortenPath(hookPath)}${hookPackage === null ? "" : ` (${hookPackage})`}${runtimeGuardPath === null ? "" : ` and runtime-guard ${shortenPath(runtimeGuardPath)}`}.`;
+    }
+    const converge = classifyRuntimeSurfaceConvergeState({
+        scope: hookInspection.scope,
+        daemonPath,
+        hookPath: displayedHookPath,
+        runtimeGuardPath: displayedRuntimeGuardPath,
+        hookLoadability: hookInspection.loadability,
+        daemonVersion,
+        hookVersion,
+        samePath
+    });
     return {
-        boundary: samePath ? "same_surface" : "split_surfaces",
+        boundary,
         skew,
         daemonPath,
-        hookPath,
-        runtimeGuardPath,
-        daemonPackage,
-        hookPackage,
-        guidance: samePath
-            ? "Daemon and installed hook paths currently collapse to the same file; verify both surfaces before patching anyway."
-            : "Patch the daemon runtime path for background watch/learner fixes. Patch the installed hook/runtime-guard paths for OpenClaw load fixes.",
-        detail: samePath
-            ? `daemon runtime path ${shortenPath(daemonPath)} currently resolves to the same file as the installed OpenClaw hook surface.`
-            : `daemon background watch runs from ${shortenPath(daemonPath)}${daemonPackage === null ? "" : ` (${daemonPackage})`}; OpenClaw loads the installed hook from ${hookPath === null ? "unverified" : shortenPath(hookPath)}${hookPackage === null ? "" : ` (${hookPackage})`}${runtimeGuardPath === null ? "" : ` and runtime-guard ${shortenPath(runtimeGuardPath)}`}.`
+        hookPath: displayedHookPath,
+        runtimeGuardPath: displayedRuntimeGuardPath,
+        daemonPackage: displayedDaemonPackage,
+        hookPackage: displayedHookPackage,
+        daemonPackageName,
+        daemonPackageVersion,
+        hookPackageName,
+        hookPackageVersion,
+        daemonSource,
+        selectedOpenClawHome,
+        convergeState: converge.state,
+        convergeReasons: converge.reasons,
+        guidance,
+        detail
     };
 }
 //# sourceMappingURL=openclaw-hook-truth.js.map

package/dist/src/proof-command.js

@@ -279,6 +279,7 @@ function extractStartupBreadcrumbs(logText, bundleStartedAtIso) {
 }
 
 function extractStatusSignals(statusText) {
+    const surface = extractKeyValuePairs(extractDetailedStatusLine(statusText, "surface"));
     return {
         statusOk: /^STATUS ok$/m.test(statusText),
         loadProofReady: /loadProof=status_probe_ready/.test(statusText),
@@ -288,6 +289,11 @@ function extractStatusSignals(statusText) {
         routeFnAvailable: /routeFn\s+available=yes/.test(statusText),
         proofPath: statusText.match(/proofPath=([^\s]+)/)?.[1] ?? null,
         proofError: statusText.match(/proofError=([^\s]+)/)?.[1] ?? null,
+        surfaceBoundary: surface.boundary ?? null,
+        surfaceSkew: surface.skew ?? null,
+        surfaceConvergeState: surface.converge ?? null,
+        surfaceDaemonSource: surface.daemonSource ?? null,
+        surfaceSelectedHome: surface.selectedHome ?? null,
     };
 }
 function extractDetailedStatusLine(statusText, prefix) {
@@ -378,10 +384,11 @@ function buildCoverageSnapshot({ attachedSetLine, runtimeLoadProofSnapshot, open
         profiles
     };
 }
-function buildHardeningSnapshot({ attachTruthLine, serveLine, routeFnLine, verdict, statusSignals }) {
+function buildHardeningSnapshot({ attachTruthLine, serveLine, routeFnLine, surfaceLine, verdict, statusSignals }) {
     const attachTruth = extractKeyValuePairs(attachTruthLine);
     const serve = extractKeyValuePairs(serveLine);
     const routeFn = extractKeyValuePairs(routeFnLine);
+    const surface = extractKeyValuePairs(surfaceLine);
     return {
         contract: "openclaw_operator_hardening_snapshot.v1",
         generatedAt: new Date().toISOString(),
@@ -391,6 +398,7 @@ function buildHardeningSnapshot({ attachTruthLine, serveLine, routeFnLine, verdi
             runtimeProven: statusSignals.runtimeProven,
             serveActivePack: statusSignals.serveActivePack,
             routeFnAvailable: statusSignals.routeFnAvailable,
+            surfaceConverged: statusSignals.surfaceConvergeState === "converged",
         },
         attachTruth: {
             current: attachTruth.current ?? null,
@@ -399,6 +407,15 @@ function buildHardeningSnapshot({ attachTruthLine, serveLine, routeFnLine, verdi
             runtime: attachTruth.runtime ?? null,
             watcher: attachTruth.watcher ?? null,
         },
+        surface: {
+            boundary: surface.boundary ?? null,
+            skew: surface.skew ?? null,
+            converge: surface.converge ?? null,
+            daemonSource: surface.daemonSource ?? null,
+            selectedHome: surface.selectedHome ?? null,
+            daemon: surface.daemon ?? null,
+            hook: surface.hook ?? null,
+        },
         serve: {
             state: serve.state ?? null,
             failOpen: serve.failOpen ?? null,
@@ -450,6 +467,8 @@ function buildVerdict({ steps, gatewayStatus, pluginInspect, statusSignals, brea
         && statusSignals.runtimeProven
         && statusSignals.serveActivePack
         && statusSignals.routeFnAvailable;
+    const surfaceConverged = statusSignals.surfaceConvergeState === "converged";
+    const surfaceHalfConverged = statusSignals.surfaceConvergeState === "half_converged";
     if (!statusSignals.loadProofReady)
         runtimeTruthGaps.push("load_proof");
     if (!statusSignals.runtimeProven)
@@ -458,6 +477,9 @@ function buildVerdict({ steps, gatewayStatus, pluginInspect, statusSignals, brea
         runtimeTruthGaps.push("serve_active_pack");
     if (!statusSignals.routeFnAvailable)
         runtimeTruthGaps.push("route_fn");
+    if (surfaceHalfConverged) {
+        runtimeTruthGaps.push("surface_converged");
+    }
     const warningCodes = [];
     const warnings = [];
     if (!statusSignals.statusOk) {
@@ -495,6 +517,14 @@ function buildVerdict({ steps, gatewayStatus, pluginInspect, statusSignals, brea
                 ? "runtime-load-proof snapshot did not include the current openclaw home"
                 : "runtime-load-proof snapshot was missing");
     }
+    if (surfaceHalfConverged) {
+        warningCodes.push(`surface_half_converged:${statusSignals.surfaceSkew ?? "unknown"}`);
+        warnings.push(`detailed status reported daemon-vs-installed-surface half-converged (${statusSignals.surfaceSkew ?? "unknown"})`);
+    }
+    else if (!surfaceConverged) {
+        warningCodes.push(`surface_unverified:${statusSignals.surfaceConvergeState ?? "unknown"}`);
+        warnings.push("detailed status did not fully prove daemon-vs-installed-surface convergence");
+    }
     if (statusSignals.proofError !== null && statusSignals.proofError !== "none") {
         warningCodes.push(`proof_error:${statusSignals.proofError}`);
         warnings.push(`detailed status reported proofError=${statusSignals.proofError}`);
@@ -546,7 +576,7 @@ function buildVerdict({ steps, gatewayStatus, pluginInspect, statusSignals, brea
     };
 }
 
-function buildSummary({ options, steps, verdict, gatewayStatusText, pluginInspectText, statusSignals, breadcrumbs, runtimeLoadProofSnapshot, surfaceLine, surfacesLine, hotfixLine, guardLine, feedbackLine, attributionLine, attributionCoverageLine, learningPathLine, learningFlowLine, learningHealthLine, coverageSnapshot, hardeningSnapshot }) {
+function buildSummary({ options, steps, verdict, gatewayStatusText, pluginInspectText, statusSignals, breadcrumbs, runtimeLoadProofSnapshot, surfaceLine, surfacesLine, surfaceNoteLine, hotfixLine, guardLine, feedbackLine, attributionLine, attributionCoverageLine, learningPathLine, learningFlowLine, learningHealthLine, coverageSnapshot, hardeningSnapshot }) {
     const passed = [];
     const missing = [];
     const warnings = Array.isArray(verdict.warnings) ? verdict.warnings : [];
@@ -574,11 +604,20 @@ function buildSummary({ options, steps, verdict, gatewayStatusText, pluginInspec
     if (statusSignals.routeFnAvailable) {
         passed.push("detailed status reported routeFn available=yes");
     }
+    if (statusSignals.surfaceConvergeState === "converged") {
+        passed.push("detailed status reported daemon-vs-installed-surface convergence");
+    }
     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 (statusSignals.surfaceConvergeState === "half_converged") {
+        missing.push(`detailed status reported daemon-vs-installed-surface half-converged (${statusSignals.surfaceSkew ?? "unknown"})`);
+    }
+    else if (statusSignals.surfaceConvergeState !== "converged") {
+        missing.push("detailed status did not fully prove daemon-vs-installed-surface convergence");
+    }
     if (!breadcrumbs.afterBundleStart.some((entry) => entry.kind === "loaded"))
         missing.push("no post-bundle startup breadcrumb was found");
     if (runtimeLoadProofSnapshot.path === null)
@@ -609,6 +648,9 @@ function buildSummary({ options, steps, verdict, gatewayStatusText, pluginInspec
         ...(surfacesLine === null
             ? ["- hotfix paths line not reported by detailed status"]
             : [`- ${surfacesLine}`]),
+        ...(surfaceNoteLine === null
+            ? ["- hotfix detail line not reported by detailed status"]
+            : [`- ${surfaceNoteLine}`]),
         ...(hotfixLine === null
             ? ["- hotfix guidance line not reported by detailed status"]
             : [`- ${hotfixLine}`]),
@@ -649,7 +691,8 @@ function buildSummary({ options, steps, verdict, gatewayStatusText, pluginInspec
             : coverageSnapshot.profiles.map((entry) => `- ${entry.current ? "*" : ""}${entry.label} coverage=${entry.coverageState} hook=${entry.hookFiles} config=${entry.configLoad} runtime=${entry.runtimeLoad} loadedAt=${entry.loadedAt ?? "none"}`)),
         "",
         "## Hardening snapshot",
-        `- status signals: statusOk=${hardeningSnapshot.statusSignals.statusOk} loadProofReady=${hardeningSnapshot.statusSignals.loadProofReady} runtimeProven=${hardeningSnapshot.statusSignals.runtimeProven} serveActivePack=${hardeningSnapshot.statusSignals.serveActivePack} routeFnAvailable=${hardeningSnapshot.statusSignals.routeFnAvailable}`,
+        `- status signals: statusOk=${hardeningSnapshot.statusSignals.statusOk} loadProofReady=${hardeningSnapshot.statusSignals.loadProofReady} runtimeProven=${hardeningSnapshot.statusSignals.runtimeProven} serveActivePack=${hardeningSnapshot.statusSignals.serveActivePack} routeFnAvailable=${hardeningSnapshot.statusSignals.routeFnAvailable} surfaceConverged=${hardeningSnapshot.statusSignals.surfaceConverged}`,
+        `- surface: boundary=${hardeningSnapshot.surface.boundary ?? "none"} skew=${hardeningSnapshot.surface.skew ?? "none"} converge=${hardeningSnapshot.surface.converge ?? "none"} daemonSource=${hardeningSnapshot.surface.daemonSource ?? "none"} daemon=${hardeningSnapshot.surface.daemon ?? "none"} hook=${hardeningSnapshot.surface.hook ?? "none"} selectedHome=${hardeningSnapshot.surface.selectedHome ?? "none"}`,
         `- serve: state=${hardeningSnapshot.serve.state ?? "none"} failOpen=${hardeningSnapshot.serve.failOpen ?? "none"} hardFail=${hardeningSnapshot.serve.hardFail ?? "none"} usedRouteFn=${hardeningSnapshot.serve.usedRouteFn ?? "none"}`,
         `- attachTruth: current=${hardeningSnapshot.attachTruth.current ?? "none"} hook=${hardeningSnapshot.attachTruth.hook ?? "none"} config=${hardeningSnapshot.attachTruth.config ?? "none"} runtime=${hardeningSnapshot.attachTruth.runtime ?? "none"}`,
         `- proof verdict: ${hardeningSnapshot.verdict.verdict} severity=${hardeningSnapshot.verdict.severity} warnings=${hardeningSnapshot.verdict.warningCount}`,
@@ -702,6 +745,7 @@ export function buildProofCommandHelpSection() {
     return {
         usage: "  openclawbrain proof --openclaw-home <path> [options]",
         optionLines: [
+            "  --openclaw-home <path>      Target one explicit OpenClaw home (for example ./openclaw-cormorantai or ~/.openclaw).",
             "  --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).",
@@ -937,6 +981,7 @@ export function captureOperatorProofBundle(options) {
     const statusSignals = extractStatusSignals(statusCapture.stdout);
     const surfaceLine = extractDetailedStatusLine(statusCapture.stdout, "surface");
     const surfacesLine = extractDetailedStatusLine(statusCapture.stdout, "surfaces");
+    const surfaceNoteLine = extractDetailedStatusLine(statusCapture.stdout, "surfaceNote");
     const hotfixLine = extractDetailedStatusLine(statusCapture.stdout, "hotfix");
     const attachTruthLine = extractDetailedStatusLine(statusCapture.stdout, "attachTruth");
     const attachedSetLine = extractDetailedStatusLine(statusCapture.stdout, "attachedSet");
@@ -978,6 +1023,7 @@ export function captureOperatorProofBundle(options) {
         attachTruthLine,
         serveLine,
         routeFnLine,
+        surfaceLine,
         verdict,
         statusSignals,
     });
@@ -1004,6 +1050,7 @@ export function captureOperatorProofBundle(options) {
         runtimeLoadProofError: runtimeLoadProofSnapshot.error,
         surfaceLine,
         surfacesLine,
+        surfaceNoteLine,
         hotfixLine,
         guardLine,
         learningFlowLine,
@@ -1025,6 +1072,7 @@ export function captureOperatorProofBundle(options) {
         runtimeLoadProofSnapshot,
         surfaceLine,
         surfacesLine,
+        surfaceNoteLine,
         hotfixLine,
         guardLine,
         learningFlowLine,
@@ -1051,6 +1099,7 @@ export function captureOperatorProofBundle(options) {
         statusSignals,
         surfaceLine,
         surfacesLine,
+        surfaceNoteLine,
         hotfixLine,
         guardLine,
         learningFlowLine,

package/package.json

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