@openclawbrain/cli 0.4.13 → 0.4.15

package/dist/src/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { execFileSync, execSync } from "node:child_process";
+import { execFileSync, execSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, readSync, openSync, closeSync, realpathSync, rmSync, statSync, writeFileSync, symlinkSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -9,21 +9,23 @@ import { DEFAULT_OLLAMA_EMBEDDING_MODEL, createOllamaEmbedder } from "@openclawb
 import { ensureManagedLearnerServiceForActivationRoot, inspectManagedLearnerService, removeManagedLearnerServiceForActivationRoot, parseDaemonArgs, runDaemonCommand } from "./daemon.js";
 import { exportBrain, importBrain } from "./import-export.js";
 import { buildNormalizedEventExport } from "@openclawbrain/contracts";
-import { buildTeacherSupervisionArtifactsFromNormalizedEventExport, createAlwaysOnLearningRuntimeState, describeAlwaysOnLearningRuntimeState, drainAlwaysOnLearningRuntime, loadOrInitBaseline, reindexCandidatePackBuildResultWithEmbedder, materializeAlwaysOnLearningCandidatePack, persistBaseline } from "./local-learner.js";
+import { buildTeacherSupervisionArtifactsFromNormalizedEventExport, createAlwaysOnLearningRuntimeState, describeAlwaysOnLearningRuntimeState, drainAlwaysOnLearningRuntime, loadOrInitBaseline, materializeAlwaysOnLearningCandidatePack, persistBaseline } from "./local-learner.js";
 import { inspectActivationState, loadPackFromActivation, promoteCandidatePack, readLearningSpineLogEntries, stageCandidatePack } from "@openclawbrain/pack-format";
 import { resolveActivationRoot } from "./resolve-activation-root.js";
 import { describeOpenClawHomeInspection, discoverOpenClawHomes, formatOpenClawHomeLayout, formatOpenClawHomeProfileSource, inspectOpenClawHome } from "./openclaw-home-layout.js";
 import { inspectOpenClawBrainHookStatus, inspectOpenClawBrainPluginAllowlist } from "./openclaw-hook-truth.js";
 import { describeOpenClawBrainInstallIdentity, describeOpenClawBrainInstallLayout, findInstalledOpenClawBrainPlugin, getOpenClawBrainKnownPluginIds, normalizeOpenClawBrainPluginsConfig, pinInstalledOpenClawBrainPluginActivationRoot, resolveOpenClawBrainInstallTarget } from "./openclaw-plugin-install.js";
+import { buildOpenClawBrainConvergeRestartPlan, classifyOpenClawBrainConvergeVerification, describeOpenClawBrainConvergeChangeReasons, diffOpenClawBrainConvergeRuntimeFingerprint, finalizeOpenClawBrainConvergeResult, planOpenClawBrainConvergePluginAction } from "./install-converge.js";
 import { loadAttachmentPolicyDeclaration, resolveEffectiveAttachmentPolicyTruth, writeAttachmentPolicyDeclaration } from "./attachment-policy-truth.js";
 import { DEFAULT_WATCH_POLL_INTERVAL_SECONDS, buildNormalizedEventExportFromScannedEvents, bootstrapRuntimeAttach, buildOperatorSurfaceReport, clearOpenClawProfileRuntimeLoadProof, compileRuntimeContext, createAsyncTeacherLiveLoop, createOpenClawLocalSessionTail, createRuntimeEventExportScanner, describeCurrentProfileBrainStatus, formatOperatorRollbackReport, listOpenClawProfileRuntimeLoadProofs, loadRuntimeEventExportBundle, loadWatchTeacherSnapshotState, persistWatchTeacherSnapshot, rollbackRuntimeAttach, resolveAttachmentRuntimeLoadProofsPath, resolveOperatorTeacherSnapshotPath, resolveAsyncTeacherLiveLoopSnapshotPath, resolveWatchSessionTailCursorPath, resolveWatchStateRoot, resolveWatchTeacherSnapshotPath, scanLiveEventExport, scanRecordedSession, summarizeLearningPathFromMaterialization, summarizeNormalizedEventExportLabelFlow, writeScannedEventExportBundle } from "./index.js";
 import { appendLearningUpdateLogs } from "./learning-spine.js";
 import { buildPassiveLearningSessionExportFromOpenClawSessionStore } from "./local-session-passive-learning.js";
+import { reindexMaterializationCandidateWithEmbedder } from "./materialization-embedder.js";
 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 { formatOperatorLearningAttributionSummary, 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";
@@ -516,7 +518,7 @@ function operatorCliHelp() {
         "  --help                      Show this help.",
         "",
         "Lifecycle flow:",
-        "  1. install            openclawbrain install — safe first-time default; writes the generated shadow hook or pins an already-installed native package plugin for one OpenClaw home",
+        "  1. install            openclawbrain install — converge one OpenClaw home: plugin-manager install/update/repair, hook repair, conditional restart, then status verification",
         "  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",
@@ -706,6 +708,10 @@ function summarizeStatusHookLoad(installHook, status) {
         installState: installHook.state === "unknown" ? "unverified" : installHook.state,
         loadability: installHook.loadability,
         loadProof: status.hook.loadProof,
+        guardSeverity: status.hook.guardSeverity,
+        guardActionability: status.hook.guardActionability,
+        guardSummary: status.hook.guardSummary,
+        guardAction: status.hook.guardAction,
         detail: status.hook.detail
     };
 }
@@ -1076,7 +1082,7 @@ function summarizeStatusTeacher(report, providerConfig, localLlm) {
             detail: `${providerConfig.teacher.model} is enabled on Ollama, but no watch teacher snapshot is visible yet`
         };
     }
-    const stale = report.teacherLoop.latestFreshness === "stale" || report.teacherLoop.watchState === "stale_snapshot";
+    const stale = report.teacherLoop.watchState === "stale_snapshot" || (report.teacherLoop.latestFreshness === "stale" && report.teacherLoop.lastNoOpReason !== "no_teacher_artifacts");
     const idle = report.teacherLoop.running === false &&
         (report.teacherLoop.queueDepth ?? 0) === 0 &&
         report.teacherLoop.failureMode === "none";
@@ -1343,7 +1349,7 @@ function buildCompactStatusHeader(status, report, options) {
     const tracedLearning = options.tracedLearning ?? buildTracedLearningStatusSurface(status.host.activationRoot);
     return [
         `lifecycle   attach=${status.attachment.state} learner=${yesNo(status.passiveLearning.learnerRunning)} watch=${summarizeStatusWatchState(status)} export=${status.passiveLearning.exportState} promote=${summarizeStatusPromotionState(status)} serve=${summarizeStatusServeReality(status)}`,
-        `hook        install=${hookLoad.installState} loadability=${hookLoad.loadability} loadProof=${hookLoad.loadProof} layout=${status.hook.installLayout ?? "unverified"} additional=${status.hook.additionalInstallCount ?? 0} detail=${hookLoad.detail}`,
+        `hook        install=${hookLoad.installState} loadability=${hookLoad.loadability} loadProof=${hookLoad.loadProof} layout=${status.hook.installLayout ?? "unverified"} additional=${status.hook.additionalInstallCount ?? 0} severity=${hookLoad.guardSeverity} actionability=${hookLoad.guardActionability} summary=${hookLoad.guardSummary}`,
         `attachTruth current=${attachmentTruth.currentProfileLabel} hook=${attachmentTruth.hookFiles} config=${attachmentTruth.configLoad} runtime=${attachmentTruth.runtimeLoad} watcher=${attachmentTruth.watcher} attachedSet=${formatAttachedProfileTruthCompactList(attachmentTruth.attachedProfiles)} why=${attachmentTruth.detail}`,
         `passive     firstExport=${yesNo(status.passiveLearning.firstExportOccurred)} backlog=${status.passiveLearning.backlogState} pending=${formatStatusNullableNumber(status.passiveLearning.pendingLive)}/${formatStatusNullableNumber(status.passiveLearning.pendingBackfill)}`,
         `serving     pack=${status.passiveLearning.currentServingPackId ?? "none"} lastExport=${status.passiveLearning.lastExportAt ?? "none"} lastPromotion=${status.passiveLearning.lastPromotionAt ?? "none"}`,
@@ -1352,6 +1358,7 @@ function buildCompactStatusHeader(status, report, options) {
         `changed     ${status.passiveLearning.lastObservedDelta.explanation}`,
         `explain     ${status.brain.summary}`,
         `graph       blocks=${report.graph.blockCount ?? "none"} strongest=${report.graph.strongestBlockId ?? "none"} latest=${report.graph.latestMaterialization.packId ?? "none"} latestChanged=${yesNo(report.graph.latestMaterialization.changed)} connect=${formatCompactGraphConnectDiagnostics(report.graph.latestMaterialization.connectDiagnostics ?? report.graph.connectDiagnostics)}`,
+        `attribution ${formatOperatorLearningAttributionSummary({ status })}`,
         `teacher     model=${teacher.model} enabled=${yesNo(teacher.enabled)} healthy=${yesNo(teacher.healthy)} stale=${yesNo(teacher.stale)} idle=${yesNo(teacher.idle)} cycle=${teacher.latestCycle} why=${teacher.detail}`,
         `embedder    model=${embedder.model} provisioned=${yesNo(embedder.provisioned)} live=${yesNo(embedder.live)} why=${embedder.detail}`,
         `routeFn     available=${yesNo(routeFn.available)} freshness=${routeFn.freshness} trained=${routeFn.trainedAt ?? "none"} updated=${routeFn.updatedAt ?? "none"} used=${routeFn.usedAt ?? "none"} why=${routeFn.detail}`,
@@ -1389,6 +1396,7 @@ function formatCurrentProfileStatusSummary(status, report, targetInspection, opt
         })}`,
         `host        runtime=${status.host.runtimeOwner} activation=${status.host.activationRoot}`,
         `profile     selector=${status.profile.selector}${profileIdSuffix} attachment=${status.attachment.state} policy=${status.attachment.policyMode}`,
+        `guard       severity=${status.hook.guardSeverity} actionability=${status.hook.guardActionability} action=${status.hook.guardAction} summary=${status.hook.guardSummary}`,
         `attachTruth current=${attachmentTruth.currentProfileLabel} hook=${attachmentTruth.hookFiles} config=${attachmentTruth.configLoad} runtime=${attachmentTruth.runtimeLoad} watcher=${attachmentTruth.watcher} detail=${attachmentTruth.detail}`,
         `attachedSet ${formatAttachedProfileTruthDetailedList(attachmentTruth.attachedProfiles)} proofPath=${shortenPath(attachmentTruth.runtimeProofPath)} proofError=${attachmentTruth.runtimeProofError ?? "none"}`,
         `manyProfile surface=${report.manyProfile.operatorSurface} policy=${report.manyProfile.declaredAttachmentPolicy} intent=${report.manyProfile.sameGatewayIntent} checkedProof=${report.manyProfile.checkedInProofTopology} sameGatewayProof=${yesNo(report.manyProfile.sameGatewayProof)} sharedWriteProof=${yesNo(report.manyProfile.sharedWriteSafetyProof)}`,
@@ -1409,6 +1417,7 @@ function formatCurrentProfileStatusSummary(status, report, targetInspection, opt
             learningPath: report.learningPath,
             tracedLearning
         })}`,
+        `attribution ${formatOperatorLearningAttributionSummary({ status })}`,
         `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)}`,
@@ -1452,6 +1461,184 @@ function buildGatewayRestartCommand(profileId) {
 function buildGatewayStatusCommand(profileId) {
     return `env -i HOME="$HOME" PATH="$PATH" openclaw --profile ${quoteShellArg(profileId)} gateway status`;
 }
+function buildGatewayRestartArgs(profileId) {
+    return profileId === null ? ["gateway", "restart"] : ["gateway", "restart", "--profile", profileId];
+}
+function shellJoin(parts) {
+    return parts
+        .map((part) => {
+        if (/^[A-Za-z0-9_./:@=-]+$/.test(part)) {
+            return part;
+        }
+        return JSON.stringify(part);
+    })
+        .join(" ");
+}
+function runCapturedExternalCommand(command, args, options = {}) {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd ?? process.cwd(),
+        env: options.env ?? process.env,
+        encoding: "utf8",
+        stdio: "pipe"
+    });
+    return {
+        command,
+        args,
+        shellCommand: shellJoin([command, ...args]),
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        exitCode: typeof result.status === "number" ? result.status : null,
+        signal: result.signal ?? null,
+        error: result.error ? toErrorMessage(result.error) : null
+    };
+}
+function summarizeCapturedCommandFailure(capture) {
+    const parts = [];
+    if (capture.error !== null) {
+        parts.push(capture.error);
+    }
+    if (capture.stderr.trim().length > 0) {
+        parts.push(capture.stderr.trim());
+    }
+    if (capture.stdout.trim().length > 0) {
+        parts.push(capture.stdout.trim());
+    }
+    if (capture.exitCode !== null) {
+        parts.push(`exitCode=${capture.exitCode}`);
+    }
+    return parts.length === 0 ? "no command output was captured" : parts.join(" | ");
+}
+function readTextFileIfExists(filePath) {
+    if (filePath === null || !existsSync(filePath)) {
+        return null;
+    }
+    try {
+        return readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function readInstallRuntimeFingerprint(openclawHome) {
+    const installedPlugin = findInstalledOpenClawBrainPlugin(openclawHome);
+    const selectedInstall = installedPlugin.selectedInstall;
+    const hook = inspectOpenClawBrainHookStatus(openclawHome);
+    const resolvedActivationRoot = resolveActivationRoot({
+        openclawHome,
+        quiet: true
+    });
+    const { config } = readOpenClawJsonConfig(openclawHome);
+    return {
+        selectedInstall: selectedInstall === null
+            ? null
+            : {
+                extensionDir: selectedInstall.extensionDir,
+                manifestId: selectedInstall.manifestId,
+                installId: selectedInstall.installId,
+                packageName: selectedInstall.packageName,
+                installLayout: selectedInstall.installLayout
+            },
+        installLayout: hook.installLayout,
+        hookPath: hook.hookPath,
+        hookState: hook.installState,
+        loadability: hook.loadability,
+        activationRoot: resolvedActivationRoot.trim().length === 0 ? null : path.resolve(resolvedActivationRoot),
+        loaderSource: readTextFileIfExists(selectedInstall?.loaderEntryPath ?? null),
+        runtimeGuardSource: readTextFileIfExists(selectedInstall?.runtimeGuardPath ?? null),
+        pluginsConfig: JSON.stringify(config.plugins ?? null)
+    };
+}
+function runOpenClawBrainConvergePluginStep(openclawHome) {
+    const before = readInstallRuntimeFingerprint(openclawHome);
+    const plan = planOpenClawBrainConvergePluginAction(before);
+    const commandArgs = plan.action === "install"
+        ? ["plugins", "install", plan.packageSpec]
+        : ["plugins", "update", plan.pluginId];
+    const capture = runCapturedExternalCommand("openclaw", commandArgs);
+    if (capture.error !== null || capture.exitCode !== 0) {
+        const hasAuthoritativeNativePlugin = before.selectedInstall !== null && before.installLayout === "native_package_plugin";
+        if (plan.action === "update" && hasAuthoritativeNativePlugin) {
+            return {
+                plan,
+                command: capture.shellCommand,
+                changed: false,
+                changeReasons: [],
+                detail: `Skipped plugin-manager refresh because the existing split-package plugin is already authoritative and \
+\`${capture.shellCommand}\` failed: ${summarizeCapturedCommandFailure(capture)}`,
+                warning: `plugin-manager refresh skipped after \`${capture.shellCommand}\` failed; keeping the existing authoritative split-package plugin for this converge run`,
+                capture,
+                before,
+                after: before
+            };
+        }
+        throw new Error(`OpenClaw plugin-manager ${plan.action} failed for ${path.resolve(openclawHome)}. Tried \`${capture.shellCommand}\`. Detail: ${summarizeCapturedCommandFailure(capture)}`);
+    }
+    const after = readInstallRuntimeFingerprint(openclawHome);
+    const diff = diffOpenClawBrainConvergeRuntimeFingerprint(before, after);
+    return {
+        plan,
+        command: capture.shellCommand,
+        changed: diff.changed,
+        changeReasons: diff.reasons,
+        detail: diff.changed
+            ? `${plan.action === "install" ? "Installed" : "Refreshed"} plugin-manager state: ${describeOpenClawBrainConvergeChangeReasons(diff.reasons)}`
+            : `${plan.action === "install" ? "Ran install" : "Ran update"} through the OpenClaw plugin manager, but no runtime-affecting plugin delta was detected`,
+        warning: null,
+        capture,
+        before,
+        after
+    };
+}
+function inspectInstallConvergeVerification(parsed) {
+    const targetInspection = inspectOpenClawHome(parsed.openclawHome);
+    const operatorInput = {
+        activationRoot: parsed.activationRoot,
+        eventExportPath: null,
+        teacherSnapshotPath: resolveOperatorTeacherSnapshotPath(parsed.activationRoot, null),
+        updatedAt: null,
+        brainAttachmentPolicy: null,
+        openclawHome: parsed.openclawHome,
+        ...(targetInspection.profileId === null ? {} : { profileId: targetInspection.profileId })
+    };
+    const status = describeCurrentProfileBrainStatus(operatorInput);
+    const report = buildOperatorSurfaceReport(operatorInput);
+    const normalizedStatusAndReport = applyAttachmentPolicyTruth(status, report);
+    const installHook = summarizeStatusInstallHook(parsed.openclawHome);
+    const attachmentTruth = summarizeStatusAttachmentTruth({
+        activationRoot: parsed.activationRoot,
+        openclawHome: parsed.openclawHome,
+        status: normalizedStatusAndReport.status
+    });
+    const displayedStatus = summarizeDisplayedStatus(normalizedStatusAndReport.status, installHook);
+    const routeFn = summarizeStatusRouteFn(normalizedStatusAndReport.status, normalizedStatusAndReport.report);
+    return {
+        targetInspection,
+        status: normalizedStatusAndReport.status,
+        report: normalizedStatusAndReport.report,
+        installHook,
+        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}`,
+        facts: {
+            installLayout: normalizedStatusAndReport.status.hook.installLayout ?? installHook.installLayout ?? null,
+            installState: installHook.state,
+            loadability: installHook.loadability,
+            guardSeverity: normalizedStatusAndReport.status.hook.guardSeverity,
+            guardActionability: normalizedStatusAndReport.status.hook.guardActionability,
+            displayedStatus,
+            runtimeLoad: attachmentTruth.runtimeLoad,
+            loadProof: normalizedStatusAndReport.status.hook.loadProof,
+            serveState: normalizedStatusAndReport.status.brainStatus.serveState,
+            routeFnAvailable: routeFn.available,
+            awaitingFirstExport: normalizedStatusAndReport.status.brainStatus.awaitingFirstExport
+        }
+    };
+}
 function buildInstallCommand(openclawHome) {
     return `openclawbrain install --openclaw-home ${quoteShellArg(openclawHome)}`;
 }
@@ -2933,10 +3120,133 @@ function buildExtensionPluginManifest() {
         name: "OpenClawBrain",
         description: "Learned memory and context from OpenClawBrain",
         version: packageMetadata.version,
+        uiHints: {
+            brainRoot: {
+                label: "Brain Root",
+                help: "Directory containing OpenClawBrain state.db and immutable packs"
+            },
+            brainEmbeddingProvider: {
+                label: "Embedding Provider",
+                help: "Provider used for learned retrieval embeddings"
+            },
+            brainEmbeddingModel: {
+                label: "Embedding Model",
+                help: "Embedding model used for init, retrieval, and brain_teach"
+            },
+            brainEmbeddingBaseUrl: {
+                label: "Embedding Base URL",
+                help: "Optional base URL override for the embedding provider endpoint"
+            },
+            brainMaxCompileMs: {
+                label: "Brain Compile Deadline",
+                help: "Soft wall-clock deadline in milliseconds for brain assembly phase-boundary checks"
+            },
+            brainBudgetFraction: {
+                label: "Brain Budget Fraction",
+                help: "Fraction of the available token budget reserved for retrieval before final prompt clipping"
+            },
+            brainMaxHops: {
+                label: "Brain Max Hops",
+                help: "Maximum learned-retrieval graph expansion depth per query"
+            },
+            brainMaxFanoutPerNode: {
+                label: "Brain Max Fanout Per Node",
+                help: "Maximum accepted traversals from a single source node expansion"
+            },
+            brainMaxFrontierSize: {
+                label: "Brain Max Frontier Size",
+                help: "Maximum traversal frontier size during learned retrieval"
+            },
+            brainMaxSeeds: {
+                label: "Brain Max Seeds",
+                help: "Maximum seed nodes admitted into learned retrieval before graph expansion"
+            },
+            brainSemanticThreshold: {
+                label: "Brain Semantic Threshold",
+                help: "Minimum semantic similarity required for seed admission during learned retrieval"
+            },
+            brainShadowMode: {
+                label: "Brain Shadow Mode",
+                help: "Run learned retrieval for telemetry only without injecting brain context into prompts"
+            },
+            brainWorkerMode: {
+                label: "Worker Mode",
+                help: "Run the learner in a supervised child process (default) or fall back to in-process mode"
+            },
+            brainWorkerHeartbeatTimeoutMs: {
+                label: "Worker Heartbeat Timeout",
+                help: "Milliseconds to wait before treating the supervised learner worker as stalled"
+            },
+            brainWorkerRestartDelayMs: {
+                label: "Worker Restart Delay",
+                help: "Milliseconds to wait before restarting the supervised learner worker after exit or crash"
+            }
+        },
         configSchema: {
             type: "object",
             additionalProperties: false,
-            properties: {}
+            properties: {
+                brainEnabled: {
+                    type: "boolean"
+                },
+                brainRoot: {
+                    type: "string"
+                },
+                brainEmbeddingProvider: {
+                    type: "string"
+                },
+                brainEmbeddingModel: {
+                    type: "string"
+                },
+                brainEmbeddingBaseUrl: {
+                    type: "string"
+                },
+                brainMaxCompileMs: {
+                    type: "integer",
+                    minimum: 0
+                },
+                brainBudgetFraction: {
+                    type: "number",
+                    minimum: 0,
+                    maximum: 1
+                },
+                brainMaxHops: {
+                    type: "integer",
+                    minimum: 1
+                },
+                brainMaxFanoutPerNode: {
+                    type: "integer",
+                    minimum: 1
+                },
+                brainMaxFrontierSize: {
+                    type: "integer",
+                    minimum: 1
+                },
+                brainMaxSeeds: {
+                    type: "integer",
+                    minimum: 1
+                },
+                brainSemanticThreshold: {
+                    type: "number",
+                    minimum: 0,
+                    maximum: 1
+                },
+                brainShadowMode: {
+                    type: "boolean"
+                },
+                brainWorkerMode: {
+                    type: "string",
+                    enum: ["child", "in_process"]
+                },
+                brainWorkerHeartbeatTimeoutMs: {
+                    type: "integer",
+                    minimum: 1000
+                },
+                brainWorkerRestartDelayMs: {
+                    type: "integer",
+                    minimum: 0
+                }
+            }
         }
     }, null, 2) + "\n";
 }
@@ -3238,7 +3548,7 @@ function runHistoryCommand(parsed) {
     }
     return 0;
 }
-function runProfileHookAttachCommand(parsed) {
+function executeProfileHookAttachCommand(parsed) {
     const steps = [];
     const commandLabel = parsed.command.toUpperCase();
     const isInstall = parsed.command === "install";
@@ -3458,106 +3768,273 @@ function runProfileHookAttachCommand(parsed) {
                 ? `Install: kept healthy active pack ${activationPlan.activePackId} in place`
                 : `Attach: rewired the profile hook to healthy active pack ${activationPlan.activePackId}`
     ];
-    // 9. Print summary
-    if (parsed.json) {
-        console.log(JSON.stringify({
-            command: parsed.command,
-            openclawHome: parsed.openclawHome,
-            openclawHomeSource: parsed.openclawHomeSource,
-            openclawTarget: {
-                layout: targetInspection.layout,
-                detail: describeOpenClawHomeInspection(targetInspection),
-                profileId: targetInspection.profileId,
-                profileSource: targetInspection.profileSource,
-                configuredProfileIds: targetInspection.configuredProfileIds
+    return {
+        command: parsed.command,
+        commandLabel,
+        openclawHome: parsed.openclawHome,
+        openclawHomeSource: parsed.openclawHomeSource,
+        openclawTarget: {
+            layout: targetInspection.layout,
+            detail: describeOpenClawHomeInspection(targetInspection),
+            profileId: targetInspection.profileId,
+            profileSource: targetInspection.profileSource,
+            configuredProfileIds: targetInspection.configuredProfileIds
+        },
+        activationRoot: parsed.activationRoot,
+        resolvedInputs: {
+            activationRoot: {
+                value: parsed.activationRoot,
+                source: parsed.activationRootSource
             },
-            activationRoot: parsed.activationRoot,
-            resolvedInputs: {
-                activationRoot: {
-                    value: parsed.activationRoot,
-                    source: parsed.activationRootSource
-                },
-                workspaceId: {
-                    value: parsed.workspaceId,
-                    source: parsed.workspaceIdSource
-                }
+            workspaceId: {
+                value: parsed.workspaceId,
+                source: parsed.workspaceIdSource
+            }
+        },
+        workspaceId: parsed.workspaceId,
+        shared: parsed.shared,
+        embedderProvision: embedderProvision === null
+            ? null
+            : {
+                skipped: parsed.skipEmbedderProvision,
+                source: parsed.skipEmbedderProvisionSource,
+                model: embedderProvision.model,
+                baseUrl: embedderProvision.baseUrl
             },
-            workspaceId: parsed.workspaceId,
-            shared: parsed.shared,
-            embedderProvision: embedderProvision === null
-                ? null
-                : {
-                    skipped: parsed.skipEmbedderProvision,
-                    source: parsed.skipEmbedderProvisionSource,
-                    model: embedderProvision.model,
-                    baseUrl: embedderProvision.baseUrl
-                },
-            providerDefaults: providerDefaults === null
-                ? null
-                : {
-                    path: providerDefaults.path,
-                    teacher: providerDefaults.defaults.teacher === undefined
-                        ? null
-                        : {
-                            provider: providerDefaults.defaults.teacher.provider ?? null,
-                            model: providerDefaults.defaults.teacher.model ?? null,
-                            detectedLocally: providerDefaults.defaults.teacher.detectedLocally ?? false
-                        },
-                    embedder: providerDefaults.defaults.embedder === undefined
-                        ? null
-                        : {
-                            provider: providerDefaults.defaults.embedder.provider ?? null,
-                            model: providerDefaults.defaults.embedder.model ?? null
-                        },
-                    teacherBaseUrl: providerDefaults.defaults.teacherBaseUrl ?? null,
-                    embedderBaseUrl: providerDefaults.defaults.embedderBaseUrl ?? null
-                },
-            pluginConfigRepair,
-            learnerService,
-            brainFeedback: {
-                hookPath: brainFeedback.hookPath,
-                hookLayout: brainFeedback.hookLayout,
-                providerDefaultsPath: brainFeedback.providerDefaultsPath,
-                profile: brainFeedback.profile,
-                attachment: brainFeedback.attachment,
-                restart: brainFeedback.restart,
-                embedder: brainFeedback.embedder,
-                teacher: brainFeedback.teacher,
-                learnerService: brainFeedback.learnerService,
-                startup: brainFeedback.startup,
-                provedNow: brainFeedback.provedNow,
-                notYetProved: brainFeedback.notYetProved,
-                lines: brainFeedback.lines
+        providerDefaults: providerDefaults === null
+            ? null
+            : {
+                path: providerDefaults.path,
+                teacher: providerDefaults.defaults.teacher === undefined
+                    ? null
+                    : {
+                        provider: providerDefaults.defaults.teacher.provider ?? null,
+                        model: providerDefaults.defaults.teacher.model ?? null,
+                        detectedLocally: providerDefaults.defaults.teacher.detectedLocally ?? false
+                    },
+                embedder: providerDefaults.defaults.embedder === undefined
+                    ? null
+                    : {
+                        provider: providerDefaults.defaults.embedder.provider ?? null,
+                        model: providerDefaults.defaults.embedder.model ?? null
+                    },
+                teacherBaseUrl: providerDefaults.defaults.teacherBaseUrl ?? null,
+                embedderBaseUrl: providerDefaults.defaults.embedderBaseUrl ?? null
             },
-            extensionDir,
-            lifecycleSummary,
-            preflightSummary,
-            restartGuidance,
-            nextSteps,
-            steps
-        }, null, 2));
+        pluginConfigRepair,
+        learnerService,
+        brainFeedback: {
+            hookPath: brainFeedback.hookPath,
+            hookLayout: brainFeedback.hookLayout,
+            providerDefaultsPath: brainFeedback.providerDefaultsPath,
+            profile: brainFeedback.profile,
+            attachment: brainFeedback.attachment,
+            restart: brainFeedback.restart,
+            embedder: brainFeedback.embedder,
+            teacher: brainFeedback.teacher,
+            learnerService: brainFeedback.learnerService,
+            startup: brainFeedback.startup,
+            provedNow: brainFeedback.provedNow,
+            notYetProved: brainFeedback.notYetProved,
+            lines: brainFeedback.lines
+        },
+        extensionDir,
+        lifecycleSummary,
+        preflightSummary,
+        restartGuidance,
+        nextSteps,
+        steps
+    };
+}
+function emitProfileHookAttachCommandResult(result, parsed) {
+    if (parsed.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
     }
-    else {
-        console.log(`${commandLabel} complete\n`);
-        console.log("Brain feedback:");
-        for (const line of brainFeedback.lines) {
-            console.log(`  ${line}`);
-        }
-        console.log(`Restart:    ${restartGuidance}`);
-        if (brainFeedback.restart.gatewayStatusCommand !== null) {
-            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)}`);
-        }
+    console.log(`${result.commandLabel} complete\n`);
+    console.log("Brain feedback:");
+    for (const line of result.brainFeedback.lines) {
+        console.log(`  ${line}`);
+    }
+    console.log(`Restart:    ${result.restartGuidance}`);
+    if (result.brainFeedback.restart.gatewayStatusCommand !== null) {
+        console.log(`Gateway:    Confirm OpenClaw after restart: ${result.brainFeedback.restart.gatewayStatusCommand}`);
+    }
+    console.log(`Check:      ${buildInstallStatusCommand(result.activationRoot)}`);
+    console.log(`Proof:      ${buildProofCommandForOpenClawHome(result.openclawHome)}`);
+    console.log(`Learner:    ${buildLearnerServiceStatusCommand(result.activationRoot)}`);
+    if (result.embedderProvision !== null && result.embedderProvision.skipped) {
+        console.log(`Embedder:   ${buildInstallEmbedderProvisionCommand(result.embedderProvision.baseUrl, result.embedderProvision.model)}`);
     }
+}
+function runProfileHookAttachCommand(parsed) {
+    const result = executeProfileHookAttachCommand(parsed);
+    emitProfileHookAttachCommandResult(result, parsed);
     return 0;
 }
+function emitInstallConvergeResult(result, parsed) {
+    if (parsed.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const heading = result.verdict.verdict === "failed"
+        ? "INSTALL converge failed"
+        : "INSTALL converge complete";
+    console.log(`${heading}\n`);
+    console.log(`Plugin:     ${result.plugin.detail}`);
+    console.log(`Attach:     ${result.attach.detail}`);
+    console.log(`Restart:    ${result.restart.detail}`);
+    console.log(`Verify:     ${result.verification.summaryLine}`);
+    console.log(`Verdict:    ${result.verdict.verdict}`);
+    console.log(`Why:        ${result.verdict.why}`);
+    if (result.verdict.warnings.length > 0) {
+        console.log(`Warnings:   ${result.verdict.warnings.join("; ")}`);
+    }
+    console.log(`Next:       ${result.verification.nextStep}`);
+    console.log(`Proof:      ${buildProofCommandForOpenClawHome(result.openclawHome)}`);
+    console.log(`Learner:    ${buildLearnerServiceStatusCommand(result.activationRoot)}`);
+}
 function runInstallCommand(parsed) {
-    return runProfileHookAttachCommand(parsed);
+    let pluginResult = null;
+    let attachResult = null;
+    try {
+        validateOpenClawHome(parsed.openclawHome);
+        pluginResult = runOpenClawBrainConvergePluginStep(parsed.openclawHome);
+        attachResult = executeProfileHookAttachCommand(parsed);
+    }
+    catch (error) {
+        const verdict = finalizeOpenClawBrainConvergeResult({
+            stepFailure: toErrorMessage(error),
+            verification: null,
+            warnings: []
+        });
+        const failureResult = {
+            command: "install",
+            openclawHome: parsed.openclawHome,
+            activationRoot: parsed.activationRoot,
+            plugin: pluginResult ?? {
+                action: null,
+                command: null,
+                changed: false,
+                changeReasons: [],
+                detail: "plugin-manager converge did not complete"
+            },
+            attach: attachResult ?? {
+                changed: false,
+                changeReasons: [],
+                detail: "under-the-hood install/attach repair did not complete",
+                hookLayout: null,
+                hookPath: null
+            },
+            restart: {
+                required: false,
+                automatic: false,
+                performed: false,
+                command: null,
+                detail: "restart did not run because install failed earlier",
+                error: null
+            },
+            verification: {
+                summaryLine: "verification did not run because install failed earlier",
+                nextStep: "Fix the install failure and rerun openclawbrain install.",
+                displayedStatus: "unknown",
+                installState: "unknown",
+                loadability: "unknown",
+                runtimeLoad: "unknown",
+                loadProof: "unknown",
+                serveState: "unknown",
+                routeFnAvailable: false,
+                awaitingFirstExport: false
+            },
+            verdict
+        };
+        emitInstallConvergeResult(failureResult, parsed);
+        return 1;
+    }
+    const attachDiff = diffOpenClawBrainConvergeRuntimeFingerprint(pluginResult.after, readInstallRuntimeFingerprint(parsed.openclawHome));
+    const changeReasons = [...new Set([...pluginResult.changeReasons, ...attachDiff.reasons])];
+    const restartPlan = buildOpenClawBrainConvergeRestartPlan({
+        profileName: attachResult.brainFeedback.profile.exactProfileName,
+        changeReasons
+    });
+    let restartCapture = null;
+    let restartError = null;
+    if (restartPlan.required && restartPlan.automatic) {
+        restartCapture = runCapturedExternalCommand("openclaw", buildGatewayRestartArgs(attachResult.brainFeedback.profile.exactProfileName));
+        if (restartCapture.error !== null || restartCapture.exitCode !== 0) {
+            restartError = `Automatic restart failed after converge. Tried \`${restartCapture.shellCommand}\`. Detail: ${summarizeCapturedCommandFailure(restartCapture)}`;
+        }
+    }
+    const verificationSnapshot = inspectInstallConvergeVerification(parsed);
+    const verification = classifyOpenClawBrainConvergeVerification({
+        ...verificationSnapshot.facts,
+        restartRequired: restartPlan.required,
+        restartPerformed: restartPlan.required && restartPlan.automatic && restartError === null
+    });
+    const convergeWarnings = [];
+    if (pluginResult.warning) {
+        convergeWarnings.push(pluginResult.warning);
+    }
+    if (restartError !== null) {
+        convergeWarnings.push(restartError);
+    }
+    const verdict = finalizeOpenClawBrainConvergeResult({
+        stepFailure: null,
+        verification,
+        warnings: convergeWarnings
+    });
+    const result = {
+        command: "install",
+        openclawHome: parsed.openclawHome,
+        activationRoot: parsed.activationRoot,
+        plugin: {
+            action: pluginResult.plan.action,
+            command: pluginResult.command,
+            changed: pluginResult.changed,
+            changeReasons: pluginResult.changeReasons,
+            detail: pluginResult.detail
+        },
+        attach: {
+            changed: attachDiff.changed,
+            changeReasons: attachDiff.reasons,
+            detail: attachDiff.changed
+                ? `Converged hook/install repair: ${describeOpenClawBrainConvergeChangeReasons(attachDiff.reasons)}`
+                : "Converged hook/install repair confirmed the selected activation root and hook wiring without additional runtime-affecting changes",
+            hookLayout: attachResult.brainFeedback.hookLayout,
+            hookPath: attachResult.brainFeedback.hookPath
+        },
+        restart: {
+            required: restartPlan.required,
+            automatic: restartPlan.automatic,
+            performed: restartPlan.required && restartPlan.automatic && restartError === null,
+            command: restartCapture?.shellCommand ?? null,
+            detail: restartPlan.required
+                ? restartPlan.automatic
+                    ? restartError === null
+                        ? `Ran automatic gateway restart: ${restartCapture.shellCommand}`
+                        : restartError
+                    : `${restartPlan.detail} Restart it manually, then rerun status.`
+                : restartPlan.detail,
+            error: restartError
+        },
+        verification: {
+            summaryLine: verificationSnapshot.summaryLine,
+            nextStep: verificationSnapshot.nextStep,
+            displayedStatus: verificationSnapshot.displayedStatus,
+            installState: verificationSnapshot.facts.installState,
+            installLayout: verificationSnapshot.facts.installLayout,
+            loadability: verificationSnapshot.facts.loadability,
+            runtimeLoad: verificationSnapshot.facts.runtimeLoad,
+            loadProof: verificationSnapshot.facts.loadProof,
+            serveState: verificationSnapshot.facts.serveState,
+            routeFnAvailable: verificationSnapshot.facts.routeFnAvailable,
+            awaitingFirstExport: verificationSnapshot.facts.awaitingFirstExport
+        },
+        verdict,
+        underlyingInstall: attachResult
+    };
+    emitInstallConvergeResult(result, parsed);
+    return verdict.verdict === "failed" || verdict.verdict === "manual_action_required" ? 1 : 0;
 }
 function runAttachCommand(parsed) {
     return runProfileHookAttachCommand(parsed);
@@ -4023,7 +4500,7 @@ function persistWatchTracedLearningBridgeSurface(input) {
         }
     }));
 }
-function runLearnCommand(parsed) {
+async function runLearnCommand(parsed) {
     const learnStatePath = path.join(parsed.activationRoot, "learn-cli-state.json");
     const teacherSnapshotPath = resolveAsyncTeacherLiveLoopSnapshotPath(parsed.activationRoot);
     function isLearnRuntimeStateLike(value) {
@@ -4236,6 +4713,7 @@ function runLearnCommand(parsed) {
         return 0;
     }
     const learningExport = normalizedEventExport;
+    const resolvedEmbedder = resolveCliEmbedderConfig(undefined, activationRoot);
     const serveTimeLearning = resolveServeTimeLearningRuntimeInput(activationRoot);
     const learnerResult = drainAlwaysOnLearningRuntime({
         packLabel: "learn-cli",
@@ -4258,7 +4736,11 @@ function runLearnCommand(parsed) {
         ...(serveTimeLearning.baselineState !== undefined ? { baselineState: serveTimeLearning.baselineState } : {}),
         activationRoot
     });
-    const lastMaterialization = learnerResult.materializations.at(-1) ?? null;
+    let lastMaterialization = learnerResult.materializations.at(-1) ?? null;
+    lastMaterialization = await reindexMaterializationCandidateWithEmbedder(lastMaterialization, resolvedEmbedder.embedder);
+    if (lastMaterialization !== null && learnerResult.materializations.length > 0) {
+        learnerResult.materializations[learnerResult.materializations.length - 1] = lastMaterialization;
+    }
     const plan = describeAlwaysOnLearningRuntimeState(learnerResult.state, lastMaterialization);
     const learningPath = summarizeLearningPathFromMaterialization(lastMaterialization);
     const graphEvolution = lastMaterialization?.candidate.payloads.graph.evolution;
@@ -4651,14 +5133,9 @@ async function applyWatchMaterialization(activationRoot, snapshot, lastHandledMa
             failure: null
         };
     }
-    if (embedder !== null) {
-        materialization = {
-            ...materialization,
-            candidate: await reindexCandidatePackBuildResultWithEmbedder(materialization.candidate, embedder)
-        };
-        if (snapshot?.learner !== undefined && snapshot.learner !== null) {
-            snapshot.learner.lastMaterialization = materialization;
-        }
+    materialization = await reindexMaterializationCandidateWithEmbedder(materialization, embedder);
+    if (snapshot?.learner !== undefined && snapshot.learner !== null) {
+        snapshot.learner.lastMaterialization = materialization;
     }
     const shortPackId = packId.length > 16 ? packId.slice(0, 16) : packId;
     const observedAt = new Date().toISOString();
@@ -4839,7 +5316,7 @@ function resolveWatchTeacherLabelerConfig(input, activationRoot) {
         warnings
     };
 }
-function resolveWatchEmbedderConfig(input, activationRoot) {
+function resolveCliEmbedderConfig(input, activationRoot) {
     if (input !== undefined) {
         return {
             embedder: input,
@@ -5023,7 +5500,7 @@ export async function createWatchCommandRuntime(input) {
     log(`Scan root: ${shortenPath(scanRoot)}`);
     log(`State: cursor=${shortenPath(sessionTailCursorPath)} snapshot=${shortenPath(teacherSnapshotPath)}`);
     const resolvedTeacherLabeler = resolveWatchTeacherLabelerConfig(input.teacherLabeler, activationRoot);
-    const resolvedEmbedder = resolveWatchEmbedderConfig(input.embedder, activationRoot);
+    const resolvedEmbedder = resolveCliEmbedderConfig(input.embedder, activationRoot);
     const teacherLabeler = resolvedTeacherLabeler.teacherLabeler;
     for (const warning of resolvedTeacherLabeler.warnings) {
         startupWarnings.push(`teacher_config_warning:${warning}`);
@@ -5644,7 +6121,12 @@ export function runOperatorCli(argv = process.argv.slice(2)) {
         return runHistoryCommand(parsed);
     }
     if (parsed.command === "learn") {
-        return runLearnCommand(parsed);
+        runLearnCommand(parsed).then((code) => { process.exitCode = code; }, (error) => {
+            console.error("[openclawbrain] learn failed");
+            console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+            process.exitCode = 1;
+        });
+        return 0;
     }
     if (parsed.command === "watch") {
         // Watch is async — bridge to sync CLI entry by scheduling and returning 0.