@openclawbrain/cli 0.4.14 → 0.4.16

package/dist/extension/index.js

@@ -44,8 +44,26 @@ async function reportDiagnostic(input) {
         }
         warnedDiagnostics.add(input.key);
     }
-    console.warn(input.message);
-    await appendLocalDiagnosticLog(input.message);
+    const formatted = formatDiagnosticMessage(input);
+    console.warn(formatted);
+    await appendLocalDiagnosticLog(formatted);
+}
+function formatDiagnosticMessage(input) {
+    if (input.severity === undefined ||
+        input.actionability === undefined ||
+        input.summary === undefined ||
+        input.action === undefined) {
+        return input.message;
+    }
+    const detail = input.message.replace(/^\[openclawbrain\]\s*/, "");
+    return [
+        "[openclawbrain]",
+        `severity=${input.severity}`,
+        `actionability=${input.actionability}`,
+        `summary=${JSON.stringify(input.summary)}`,
+        `action=${JSON.stringify(input.action)}`,
+        `detail=${JSON.stringify(detail)}`
+    ].join(" ");
 }
 function announceStartupBreadcrumb() {
     if (isActivationRootPlaceholder(ACTIVATION_ROOT)) {
@@ -78,8 +96,12 @@ export default function register(api) {
             catch (error) {
                 const detail = error instanceof Error ? error.message : String(error);
                 void reportDiagnostic({
-                    key: `runtime-load-proof:${detail}`,
+                    key: "runtime-load-proof-failed",
                     once: true,
+                    severity: "degraded",
+                    actionability: "inspect_local_proof_write",
+                    summary: "runtime-load proof write failed after hook registration",
+                    action: "Inspect local filesystem permissions and the activation-root proof path if proof capture is expected.",
                     message: `[openclawbrain] runtime load proof failed: ${detail}`
                 });
             }
@@ -91,8 +113,12 @@ export default function register(api) {
         void reportDiagnostic({
             key: "registration-failed",
             once: true,
+            severity: "blocking",
+            actionability: "rerun_install",
+            summary: "extension registration threw before the runtime hook was fully attached",
+            action: "Rerun openclawbrain install --openclaw-home <path>; if it still fails, inspect the extension loader/runtime.",
             message: `[openclawbrain] extension registration failed: ${detail}`
         });
     }
 }
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/extension/runtime-guard.d.ts

@@ -22,10 +22,16 @@ export interface ExtensionCompileFailure {
 }
 export type ExtensionCompileResult = ExtensionCompileSuccess | ExtensionCompileFailure;
 export type ExtensionCompileRuntimeContext = (input: ExtensionCompileInput) => ExtensionCompileResult;
+export type ExtensionDiagnosticSeverity = "degraded" | "blocking";
+export type ExtensionDiagnosticActionability = "inspect_host_event_shape" | "inspect_host_registration_api" | "inspect_local_proof_write" | "inspect_runtime_compile" | "rerun_install";
 export interface ExtensionDiagnostic {
     key: string;
     message: string;
     once?: boolean;
+    severity?: ExtensionDiagnosticSeverity;
+    actionability?: ExtensionDiagnosticActionability;
+    summary?: string;
+    action?: string;
 }
 export interface ExtensionRegistrationApi {
     on(eventName: string, handler: (event: unknown, ctx: unknown) => Promise<Record<string, unknown>>, options?: {

package/dist/extension/runtime-guard.js

@@ -5,12 +5,12 @@ export function validateExtensionRegistrationApi(api) {
     if (!isRecord(api) || typeof api.on !== "function") {
         return {
             ok: false,
-            diagnostic: {
+            diagnostic: shapeDiagnostic({
                 key: "registration-api-invalid",
                 once: true,
                 message: `[openclawbrain] extension inactive: host registration API is missing api.on(event, handler, options) ` +
                     `(received=${describeValue(api)})`
-            }
+            })
         };
     }
     return {
@@ -64,11 +64,11 @@ export function normalizePromptBuildEvent(event) {
 export function createBeforePromptBuildHandler(input) {
     return async (event, _ctx) => {
         if (isActivationRootPlaceholder(input.activationRoot)) {
-            await input.reportDiagnostic({
+            await input.reportDiagnostic(shapeDiagnostic({
                 key: "activation-root-placeholder",
                 once: true,
                 message: "[openclawbrain] BRAIN NOT YET LOADED: ACTIVATION_ROOT is still a placeholder. Install @openclawbrain/cli, then run: openclawbrain install --openclaw-home <path>"
-            });
+            }));
             return {};
         }
         const normalized = normalizePromptBuildEvent(event);
@@ -103,11 +103,11 @@ export function createBeforePromptBuildHandler(input) {
             });
             if (!result.ok) {
                 const mode = result.hardRequirementViolated ? "hard-fail" : "fail-open";
-                await input.reportDiagnostic({
+                await input.reportDiagnostic(shapeDiagnostic({
                     key: `compile-${mode}`,
                     message: `[openclawbrain] ${mode}: ${result.error} ` +
                         `(activationRoot=${input.activationRoot}, sessionId=${normalized.event.sessionId ?? "unknown"}, channel=${normalized.event.channel ?? "unknown"})`
-                });
+                }));
                 return {};
             }
             if (result.brainContext.length > 0) {
@@ -119,20 +119,20 @@ export function createBeforePromptBuildHandler(input) {
         }
         catch (error) {
             const detail = error instanceof Error ? error.stack ?? error.message : String(error);
-            await input.reportDiagnostic({
+            await input.reportDiagnostic(shapeDiagnostic({
                 key: "compile-threw",
                 message: `[openclawbrain] compile threw: ${detail} ` +
                     `(activationRoot=${input.activationRoot}, sessionId=${normalized.event.sessionId ?? "unknown"}, channel=${normalized.event.channel ?? "unknown"})`
-            });
+            }));
         }
         return {};
     };
 }
 function failOpenDiagnostic(key, reason, detail) {
-    return {
+    return shapeDiagnostic({
         key,
         message: `[openclawbrain] fail-open: ${reason} (${detail})`
-    };
+    });
 }
 function normalizeOptionalScalarField(value, fieldName, warnings) {
     if (value === undefined || value === null) {
@@ -145,11 +145,11 @@ function normalizeOptionalScalarField(value, fieldName, warnings) {
     if (typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
         return String(value);
     }
-    warnings.push({
+    warnings.push(shapeDiagnostic({
         key: `runtime-${fieldName}-ignored`,
         message: `[openclawbrain] fail-open: ignored unsupported before_prompt_build ${fieldName} ` +
             `(${fieldName}=${describeValue(value)})`
-    });
+    }));
     return undefined;
 }
 function normalizeOptionalNonNegativeIntegerField(value, fieldName, warnings) {
@@ -174,11 +174,11 @@ function normalizeOptionalNonNegativeIntegerField(value, fieldName, warnings) {
             }
         }
     }
-    warnings.push({
+    warnings.push(shapeDiagnostic({
         key: `runtime-${fieldName}-ignored`,
         message: `[openclawbrain] fail-open: ignored unsupported before_prompt_build ${fieldName} ` +
             `(${fieldName}=${describeValue(value)})`
-    });
+    }));
     return undefined;
 }
 function extractPromptMessage(message) {
@@ -264,7 +264,63 @@ function describeValue(value) {
     }
     return `${typeof value}(${String(value)})`;
 }
+function shapeDiagnostic(diagnostic) {
+    if (diagnostic.severity !== undefined &&
+        diagnostic.actionability !== undefined &&
+        diagnostic.summary !== undefined &&
+        diagnostic.action !== undefined) {
+        return diagnostic;
+    }
+    if (diagnostic.key === "activation-root-placeholder") {
+        return {
+            ...diagnostic,
+            severity: "blocking",
+            actionability: "rerun_install",
+            summary: "extension hook is installed but ACTIVATION_ROOT is still unpinned",
+            action: "Run openclawbrain install --openclaw-home <path> to pin the runtime hook."
+        };
+    }
+    if (diagnostic.key === "registration-api-invalid") {
+        return {
+            ...diagnostic,
+            severity: "blocking",
+            actionability: "inspect_host_registration_api",
+            summary: "extension host registration API is missing or incompatible",
+            action: "Repair or upgrade the host extension API so api.on(event, handler, options) is available."
+        };
+    }
+    if (diagnostic.key === "compile-hard-fail") {
+        return {
+            ...diagnostic,
+            severity: "blocking",
+            actionability: "inspect_runtime_compile",
+            summary: "brain context compile hit a hard requirement",
+            action: "Inspect the activation root and compile error; rerun install if the pinned hook may be stale."
+        };
+    }
+    if (diagnostic.key === "compile-fail-open" || diagnostic.key === "compile-threw") {
+        return {
+            ...diagnostic,
+            severity: "degraded",
+            actionability: "inspect_runtime_compile",
+            summary: diagnostic.key === "compile-threw"
+                ? "brain context compile threw during before_prompt_build"
+                : "brain context compile failed open during before_prompt_build",
+            action: "Inspect the activation root and compile error if brain context is unexpectedly empty."
+        };
+    }
+    if (diagnostic.key.startsWith("runtime-")) {
+        return {
+            ...diagnostic,
+            severity: "degraded",
+            actionability: "inspect_host_event_shape",
+            summary: "before_prompt_build payload was partial or malformed",
+            action: "Inspect the host before_prompt_build event shape; OpenClawBrain fail-opened safely."
+        };
+    }
+    return diagnostic;
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
-//# sourceMappingURL=runtime-guard.js.map
+//# sourceMappingURL=runtime-guard.js.map

package/dist/src/cli.js

@@ -9,7 +9,7 @@ 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";
@@ -17,14 +17,15 @@ import { inspectOpenClawBrainHookStatus, inspectOpenClawBrainPluginAllowlist } f
 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 { 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, summarizeTeacherNoArtifactCycle, 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";
@@ -681,14 +682,14 @@ const LEARNING_WARNING_MESSAGES = {
     passive_backfill_pending: "passive backfill remains queued",
     teacher_queue_full: "teacher queue is full",
     teacher_labels_stale: "teacher labels are stale",
-    teacher_no_artifacts: "teacher produced no artifacts",
+    teacher_no_artifacts: "latest no-op cycle had teachable material but no new teacher artifact",
     teacher_snapshot_unavailable: "teacher snapshot is unavailable"
 };
 const TEACHER_NO_OP_MESSAGES = {
     none: "the latest processed export produced teacher artifacts",
     duplicate_export: "the latest cycle was a no-op because the export was already seen",
     queue_full: "the latest cycle was a no-op because the teacher queue was full",
-    no_teacher_artifacts: "the latest cycle was a no-op because no teacher artifacts were produced",
+    no_teacher_artifacts: "the latest cycle produced no new teacher artifacts",
     empty_scan: "the latest cycle was a no-op because the scanner did not produce any events",
     unavailable: "the latest cycle is not visible from the current operator snapshot"
 };
@@ -707,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
     };
 }
@@ -1077,14 +1082,16 @@ 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";
     const healthy = report.teacherLoop.failureMode === "none" &&
         stale === false &&
         report.teacherLoop.watchState !== "not_visible";
-    const cycleDetail = TEACHER_NO_OP_MESSAGES[report.teacherLoop.lastNoOpReason] ?? "the latest teacher cycle detail is unavailable";
+    const cycleDetail = report.teacherLoop.lastNoOpReason === "no_teacher_artifacts"
+        ? summarizeTeacherNoArtifactCycle(report.teacherLoop.notes).detail
+        : TEACHER_NO_OP_MESSAGES[report.teacherLoop.lastNoOpReason] ?? "the latest teacher cycle detail is unavailable";
     if (report.teacherLoop.failureMode !== "none" && report.teacherLoop.failureMode !== "unavailable") {
         return {
             model: providerConfig.teacher.model,
@@ -1344,7 +1351,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"}`,
@@ -1353,6 +1360,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}`,
@@ -1390,6 +1398,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)}`,
@@ -1410,6 +1419,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)}`,
@@ -1615,11 +1625,13 @@ function inspectInstallConvergeVerification(parsed) {
             openclawHome: parsed.openclawHome,
             installHook
         }),
-        summaryLine: `STATUS ${displayedStatus}; hook=${installHook.state}/${installHook.loadability}; runtime=${attachmentTruth.runtimeLoad}; loadProof=${normalizedStatusAndReport.status.hook.loadProof}; serve=${normalizedStatusAndReport.status.brainStatus.serveState}`,
+        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,
@@ -3110,10 +3122,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";
 }
@@ -4367,7 +4502,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) {
@@ -4580,6 +4715,7 @@ function runLearnCommand(parsed) {
         return 0;
     }
     const learningExport = normalizedEventExport;
+    const resolvedEmbedder = resolveCliEmbedderConfig(undefined, activationRoot);
     const serveTimeLearning = resolveServeTimeLearningRuntimeInput(activationRoot);
     const learnerResult = drainAlwaysOnLearningRuntime({
         packLabel: "learn-cli",
@@ -4602,7 +4738,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;
@@ -4995,14 +5135,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();
@@ -5183,7 +5318,7 @@ function resolveWatchTeacherLabelerConfig(input, activationRoot) {
         warnings
     };
 }
-function resolveWatchEmbedderConfig(input, activationRoot) {
+function resolveCliEmbedderConfig(input, activationRoot) {
     if (input !== undefined) {
         return {
             embedder: input,
@@ -5367,7 +5502,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}`);
@@ -5988,7 +6123,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.