@openclawbrain/cli 0.4.13 → 0.4.15

package/dist/src/teacher-decision-match.js

@@ -0,0 +1,277 @@
+const DEFAULT_MATCH_WINDOW_MS = 60_000;
+const OPERATIONAL_DECISION_PATTERNS = [
+    /^NO_REPLY$/i,
+    /^HEARTBEAT_OK$/i,
+    /^read heartbeat\.md if it exists\b/i,
+    /^a new session was started via \/new or \/reset\./i,
+    /\[cron:[a-f0-9-]+\s/i,
+    /\[system message\]\s*\[sessionid:/i,
+];
+
+function normalizeOptionalString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function toTimestamp(value) {
+    const normalized = normalizeOptionalString(value);
+    if (normalized === undefined) {
+        return null;
+    }
+    const parsed = Date.parse(normalized);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+
+function buildSessionChannelKey(sessionId, channel) {
+    const normalizedSessionId = normalizeOptionalString(sessionId);
+    const normalizedChannel = normalizeOptionalString(channel);
+    if (normalizedSessionId === undefined || normalizedChannel === undefined) {
+        return null;
+    }
+    return `${normalizedSessionId}|${normalizedChannel}`;
+}
+
+function buildCandidateKey(sessionId, channel, createdAt) {
+    const sessionChannelKey = buildSessionChannelKey(sessionId, channel);
+    const normalizedCreatedAt = normalizeOptionalString(createdAt);
+    if (sessionChannelKey === null || normalizedCreatedAt === undefined) {
+        return null;
+    }
+    return `${sessionChannelKey}|${normalizedCreatedAt}`;
+}
+
+function buildSelectionDigestKey(selectionDigest, activePackGraphChecksum) {
+    const normalizedSelectionDigest = normalizeOptionalString(selectionDigest);
+    const normalizedGraphChecksum = normalizeOptionalString(activePackGraphChecksum);
+    if (normalizedSelectionDigest === undefined || normalizedGraphChecksum === undefined) {
+        return null;
+    }
+    return `${normalizedGraphChecksum}|${normalizedSelectionDigest}`;
+}
+
+function toRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+
+function readInteractionExactDecisionRecordId(interaction) {
+    return normalizeOptionalString(interaction?.serveDecisionRecordId)
+        ?? normalizeOptionalString(toRecord(interaction?.routeMetadata)?.serveDecisionRecordId)
+        ?? normalizeOptionalString(toRecord(interaction?.decisionProvenance)?.serveDecisionRecordId)
+        ?? normalizeOptionalString(toRecord(interaction?.metadata)?.serveDecisionRecordId)
+        ?? undefined;
+}
+
+function readInteractionSelectionDigest(interaction) {
+    return normalizeOptionalString(interaction?.selectionDigest)
+        ?? normalizeOptionalString(toRecord(interaction?.routeMetadata)?.selectionDigest)
+        ?? normalizeOptionalString(toRecord(interaction?.decisionProvenance)?.selectionDigest)
+        ?? normalizeOptionalString(toRecord(interaction?.metadata)?.selectionDigest)
+        ?? undefined;
+}
+
+function readInteractionActivePackGraphChecksum(interaction) {
+    return normalizeOptionalString(interaction?.activePackGraphChecksum)
+        ?? normalizeOptionalString(toRecord(interaction?.routeMetadata)?.activePackGraphChecksum)
+        ?? normalizeOptionalString(toRecord(interaction?.decisionProvenance)?.activePackGraphChecksum)
+        ?? normalizeOptionalString(toRecord(interaction?.metadata)?.activePackGraphChecksum)
+        ?? undefined;
+}
+
+function readInteractionExplicitTurnCompileEventId(interaction) {
+    return normalizeOptionalString(interaction?.turnCompileEventId)
+        ?? normalizeOptionalString(toRecord(interaction?.routeMetadata)?.turnCompileEventId)
+        ?? normalizeOptionalString(toRecord(interaction?.decisionProvenance)?.turnCompileEventId)
+        ?? normalizeOptionalString(toRecord(interaction?.metadata)?.turnCompileEventId)
+        ?? undefined;
+}
+
+function buildDecisionTimestamps(decision) {
+    const timestamps = [];
+    const turnCreatedAt = toTimestamp(decision.turnCreatedAt);
+    const recordedAt = toTimestamp(decision.recordedAt);
+    if (turnCreatedAt !== null) {
+        timestamps.push(turnCreatedAt);
+    }
+    if (recordedAt !== null && !timestamps.includes(recordedAt)) {
+        timestamps.push(recordedAt);
+    }
+    return timestamps;
+}
+
+function isOperationalDecision(decision) {
+    const userMessage = normalizeOptionalString(decision.userMessage);
+    if (userMessage === undefined) {
+        return true;
+    }
+    return OPERATIONAL_DECISION_PATTERNS.some((pattern) => pattern.test(userMessage));
+}
+
+function selectNearestDecision(entries, interactionAt, maxTimeDeltaMs) {
+    const candidates = entries
+        .map((entry) => {
+        const deltas = entry.timestamps.map((timestamp) => Math.abs(timestamp - interactionAt));
+        const bestDelta = deltas.length === 0 ? null : Math.min(...deltas);
+        return bestDelta === null || bestDelta > maxTimeDeltaMs
+            ? null
+            : {
+                decision: entry.decision,
+                deltaMs: bestDelta,
+                recordedAt: toTimestamp(entry.decision.recordedAt) ?? 0,
+            };
+    })
+        .filter((entry) => entry !== null)
+        .sort((left, right) => {
+        if (left.deltaMs !== right.deltaMs) {
+            return left.deltaMs - right.deltaMs;
+        }
+        return right.recordedAt - left.recordedAt;
+    });
+    const best = candidates[0] ?? null;
+    const runnerUp = candidates[1] ?? null;
+    if (best === null) {
+        return null;
+    }
+    if (runnerUp !== null && runnerUp.deltaMs === best.deltaMs && runnerUp.decision !== best.decision) {
+        return null;
+    }
+    return best.decision;
+}
+
+export function createServeTimeDecisionMatcher(decisions, options = {}) {
+    const maxTimeDeltaMs = Number.isInteger(options.maxTimeDeltaMs) && options.maxTimeDeltaMs >= 0
+        ? options.maxTimeDeltaMs
+        : DEFAULT_MATCH_WINDOW_MS;
+    const decisionsByRecordId = new Map();
+    const decisionsBySelectionDigest = new Map();
+    const ambiguousSelectionDigests = new Set();
+    const decisionsByTurnCompileEventId = new Map();
+    const ambiguousTurnCompileEventIds = new Set();
+    const fallbackDecisions = new Map();
+    const ambiguousFallbackDecisionKeys = new Set();
+    const decisionsBySessionChannel = new Map();
+    const globalFallbackDecisions = [];
+
+    for (const decision of [...decisions].sort((left, right) => Date.parse(right.recordedAt) - Date.parse(left.recordedAt))) {
+        const userMessage = normalizeOptionalString(decision.userMessage);
+        if (userMessage === undefined) {
+            continue;
+        }
+        const decisionRecordId = normalizeOptionalString(decision.recordId);
+        if (decisionRecordId !== undefined && !decisionsByRecordId.has(decisionRecordId)) {
+            decisionsByRecordId.set(decisionRecordId, decision);
+        }
+        const selectionDigestKey = buildSelectionDigestKey(decision.selectionDigest, decision.activePackGraphChecksum);
+        if (selectionDigestKey !== null) {
+            if (decisionsBySelectionDigest.has(selectionDigestKey)) {
+                decisionsBySelectionDigest.delete(selectionDigestKey);
+                ambiguousSelectionDigests.add(selectionDigestKey);
+            }
+            else if (!ambiguousSelectionDigests.has(selectionDigestKey)) {
+                decisionsBySelectionDigest.set(selectionDigestKey, decision);
+            }
+        }
+        const turnCompileEventId = normalizeOptionalString(decision.turnCompileEventId);
+        if (turnCompileEventId !== undefined) {
+            if (decisionsByTurnCompileEventId.has(turnCompileEventId)) {
+                decisionsByTurnCompileEventId.delete(turnCompileEventId);
+                ambiguousTurnCompileEventIds.add(turnCompileEventId);
+            }
+            else if (!ambiguousTurnCompileEventIds.has(turnCompileEventId)) {
+                decisionsByTurnCompileEventId.set(turnCompileEventId, decision);
+            }
+        }
+        for (const candidateKey of [
+            buildCandidateKey(decision.sessionId, decision.channel, decision.turnCreatedAt),
+            buildCandidateKey(decision.sessionId, decision.channel, decision.recordedAt),
+        ]) {
+            if (candidateKey !== null) {
+                if (fallbackDecisions.has(candidateKey)) {
+                    fallbackDecisions.delete(candidateKey);
+                    ambiguousFallbackDecisionKeys.add(candidateKey);
+                }
+                else if (!ambiguousFallbackDecisionKeys.has(candidateKey)) {
+                    fallbackDecisions.set(candidateKey, decision);
+                }
+            }
+        }
+        const sessionChannelKey = buildSessionChannelKey(decision.sessionId, decision.channel);
+        if (sessionChannelKey === null) {
+            if (!isOperationalDecision(decision)) {
+                globalFallbackDecisions.push({
+                    decision,
+                    timestamps: buildDecisionTimestamps(decision),
+                });
+            }
+            continue;
+        }
+        const indexedEntry = {
+            decision,
+            timestamps: buildDecisionTimestamps(decision),
+            operational: isOperationalDecision(decision),
+        };
+        const indexed = decisionsBySessionChannel.get(sessionChannelKey) ?? [];
+        indexed.push(indexedEntry);
+        decisionsBySessionChannel.set(sessionChannelKey, indexed);
+        if (!indexedEntry.operational) {
+            globalFallbackDecisions.push(indexedEntry);
+        }
+    }
+
+    return (interaction) => {
+        const decisionRecordId = readInteractionExactDecisionRecordId(interaction);
+        if (decisionRecordId !== undefined) {
+            return decisionsByRecordId.get(decisionRecordId) ?? null;
+        }
+        const interactionSelectionDigest = readInteractionSelectionDigest(interaction);
+        const interactionGraphChecksum = readInteractionActivePackGraphChecksum(interaction);
+        const selectionDigestKey = buildSelectionDigestKey(interactionSelectionDigest, interactionGraphChecksum);
+        if (selectionDigestKey !== null) {
+            if (ambiguousSelectionDigests.has(selectionDigestKey)) {
+                return null;
+            }
+            return decisionsBySelectionDigest.get(selectionDigestKey) ?? null;
+        }
+        if (interactionSelectionDigest !== undefined || interactionGraphChecksum !== undefined) {
+            return null;
+        }
+        const explicitTurnCompileEventId = readInteractionExplicitTurnCompileEventId(interaction);
+        if (explicitTurnCompileEventId !== undefined) {
+            if (ambiguousTurnCompileEventIds.has(explicitTurnCompileEventId)) {
+                return null;
+            }
+            return decisionsByTurnCompileEventId.get(explicitTurnCompileEventId) ?? null;
+        }
+        const softTurnCompileEventId = normalizeOptionalString(interaction.eventId);
+        const exact = softTurnCompileEventId === undefined || ambiguousTurnCompileEventIds.has(softTurnCompileEventId)
+            ? undefined
+            : decisionsByTurnCompileEventId.get(softTurnCompileEventId);
+        if (exact !== undefined) {
+            return exact;
+        }
+        const exactFallbackKey = buildCandidateKey(interaction.sessionId, interaction.channel, interaction.createdAt);
+        if (exactFallbackKey !== null) {
+            if (ambiguousFallbackDecisionKeys.has(exactFallbackKey)) {
+                return null;
+            }
+            const fallback = fallbackDecisions.get(exactFallbackKey);
+            if (fallback !== undefined) {
+                return fallback;
+            }
+        }
+        const interactionAt = toTimestamp(interaction.createdAt);
+        const sessionChannelKey = buildSessionChannelKey(interaction.sessionId, interaction.channel);
+        if (interactionAt === null) {
+            return null;
+        }
+        if (sessionChannelKey !== null) {
+            const sessionMatch = selectNearestDecision((decisionsBySessionChannel.get(sessionChannelKey) ?? []).filter((entry) => entry.operational !== true), interactionAt, maxTimeDeltaMs);
+            if (sessionMatch !== null) {
+                return sessionMatch;
+            }
+        }
+        return selectNearestDecision(globalFallbackDecisions, interactionAt, maxTimeDeltaMs);
+    };
+}

package/dist/src/teacher-labeler.js

@@ -1,5 +1,6 @@
 import { CONTRACT_IDS, checksumJsonPayload, validateTeacherSupervisionArtifact } from "@openclawbrain/contracts";
 import { buildNormalizedEventDedupId } from "@openclawbrain/event-export";
+import { createServeTimeDecisionMatcher } from "./teacher-decision-match.js";
 const FEEDBACK_KINDS = new Set(["correction", "teaching", "approval", "suppression"]);
 const OLLAMA_ROUTE_DECISION_STREAM = "openclaw/learning-spine/serve-time-route-decisions";
 const DEFAULT_OLLAMA_BASE_URL = "http://127.0.0.1:11434";
@@ -140,41 +141,14 @@ function buildPrompt(candidates, config) {
         payload
     ].join("\n");
 }
-function buildCandidateKey(interaction) {
-    return `${interaction.sessionId}|${interaction.channel}|${interaction.createdAt}`;
-}
-function matchServeTimeDecision(interaction, exactDecisions, fallbackDecisions) {
-    const exact = exactDecisions.get(interaction.eventId);
-    if (exact !== undefined) {
-        return exact;
-    }
-    return fallbackDecisions.get(buildCandidateKey(interaction)) ?? null;
-}
 function collectCandidates(input, config) {
     const decisions = [...(input.serveTimeDecisions ?? [])].sort((left, right) => Date.parse(right.recordedAt) - Date.parse(left.recordedAt));
-    const exactDecisions = new Map();
-    const fallbackDecisions = new Map();
-    for (const decision of decisions) {
-        const userMessage = normalizeOptionalString(decision.userMessage);
-        if (userMessage === undefined) {
-            continue;
-        }
-        if (decision.turnCompileEventId !== null && !exactDecisions.has(decision.turnCompileEventId)) {
-            exactDecisions.set(decision.turnCompileEventId, decision);
-        }
-        const turnCreatedAt = normalizeOptionalString(decision.turnCreatedAt);
-        if (turnCreatedAt !== undefined && decision.sessionId !== null && decision.channel !== null) {
-            const key = `${decision.sessionId}|${decision.channel}|${turnCreatedAt}`;
-            if (!fallbackDecisions.has(key)) {
-                fallbackDecisions.set(key, decision);
-            }
-        }
-    }
+    const matchServeTimeDecision = createServeTimeDecisionMatcher(decisions);
     return input.normalizedEventExport.interactionEvents
         .filter((interaction) => interaction.kind === "memory_compiled")
         .sort((left, right) => Date.parse(right.createdAt) - Date.parse(left.createdAt))
         .map((interaction) => {
-        const decision = matchServeTimeDecision(interaction, exactDecisions, fallbackDecisions);
+        const decision = matchServeTimeDecision(interaction);
         const userMessage = normalizeOptionalString(decision?.userMessage);
         if (decision === null || userMessage === undefined) {
             return null;
@@ -421,4 +395,4 @@ export function createTeacherLabeler(config) {
     }
     return createOllamaTeacherLabeler(config);
 }
-//# sourceMappingURL=teacher-labeler.js.map
+//# sourceMappingURL=teacher-labeler.js.map

package/dist/src/traced-learning-bridge.js

@@ -18,6 +18,22 @@ function normalizeOptionalString(value) {
 function normalizeSource(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 }
+function summarizeBridgeSource(value) {
+    const source = normalizeSource(value);
+    if (source === null) {
+        return null;
+    }
+    const summarized = {
+        command: normalizeOptionalString(source.command),
+        bridge: normalizeOptionalString(source.bridge),
+        brainRoot: normalizeOptionalString(source.brainRoot),
+        stateDbPath: normalizeOptionalString(source.stateDbPath),
+        persistedKey: normalizeOptionalString(source.persistedKey),
+        candidatePackVersion: Number.isFinite(source.candidatePackVersion) ? Math.trunc(source.candidatePackVersion) : undefined,
+        candidateUpdateCount: normalizeCount(source.candidateUpdateCount)
+    };
+    return Object.fromEntries(Object.entries(summarized).filter(([, candidate]) => candidate !== null && candidate !== undefined));
+}
 function normalizeBridgePayload(payload) {
     if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
         throw new Error("expected traced-learning bridge payload object");
@@ -579,7 +595,7 @@ export function mergeTracedLearningBridgePayload(payload, persisted) {
                 supervisionCount: persistedBridge.supervisionCount,
                 routerUpdateCount: persistedBridge.routerUpdateCount,
                 teacherArtifactCount: persistedBridge.teacherArtifactCount,
-                source: persistedBridge.source
+                source: summarizeBridgeSource(persistedBridge.source)
             }
         }
     });

package/extension/index.ts

@@ -18,6 +18,7 @@ import {
 } from "@openclawbrain/openclaw";
 import {
   createBeforePromptBuildHandler,
+  type ExtensionDiagnostic,
   isActivationRootPlaceholder,
   validateExtensionRegistrationApi
 } from "./runtime-guard.js";
@@ -52,7 +53,7 @@ async function appendLocalDiagnosticLog(message: string): Promise<void> {
   }
 }
 
-async function reportDiagnostic(input: { key: string; message: string; once?: boolean }): Promise<void> {
+async function reportDiagnostic(input: ExtensionDiagnostic): Promise<void> {
   if (input.once) {
     if (warnedDiagnostics.has(input.key)) {
       return;
@@ -60,8 +61,30 @@ async function reportDiagnostic(input: { key: string; message: string; once?: bo
     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: ExtensionDiagnostic): string {
+  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(): void {
@@ -107,8 +130,12 @@ export default function register(api: unknown) {
       } 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}`
         });
       }
@@ -119,6 +146,10 @@ export default function register(api: unknown) {
     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}`
     });
   }

package/extension/runtime-guard.ts

@@ -27,10 +27,23 @@ export type ExtensionCompileResult = ExtensionCompileSuccess | ExtensionCompileF
 
 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 {
@@ -53,13 +66,13 @@ export function validateExtensionRegistrationApi(api: unknown): { ok: true; 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)})`
-      }
+      })
     };
   }
 
@@ -145,12 +158,12 @@ export function createBeforePromptBuildHandler(input: {
 }): (event: unknown, ctx: unknown) => Promise<Record<string, unknown>> {
   return async (event: unknown, _ctx: unknown) => {
     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 {};
     }
 
@@ -190,12 +203,12 @@ 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 {};
       }
 
@@ -207,12 +220,12 @@ 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 {};
@@ -220,10 +233,10 @@ export function createBeforePromptBuildHandler(input: {
 }
 
 function failOpenDiagnostic(key: string, reason: string, detail: string): ExtensionDiagnostic {
-  return {
+  return shapeDiagnostic({
     key,
     message: `[openclawbrain] fail-open: ${reason} (${detail})`
-  };
+  });
 }
 
 function normalizeOptionalScalarField(
@@ -244,12 +257,12 @@ function normalizeOptionalScalarField(
     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;
 }
@@ -284,12 +297,12 @@ function normalizeOptionalNonNegativeIntegerField(
     }
   }
 
-  warnings.push({
+  warnings.push(shapeDiagnostic({
     key: `runtime-${fieldName}-ignored`,
     message:
       `[openclawbrain] fail-open: ignored unsupported before_prompt_build ${fieldName} ` +
       `(${fieldName}=${describeValue(value)})`
-  });
+  }));
 
   return undefined;
 }
@@ -402,6 +415,71 @@ function describeValue(value: unknown): string {
   return `${typeof value}(${String(value)})`;
 }
 
+function shapeDiagnostic(diagnostic: ExtensionDiagnostic): ExtensionDiagnostic {
+  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: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclawbrain/cli",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "description": "OpenClawBrain operator CLI package with install/status helpers, daemon controls, and import/export tooling.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -48,9 +48,11 @@
     "@openclawbrain/compiler": "0.3.5",
     "@openclawbrain/contracts": "^0.3.5",
     "@openclawbrain/events": "^0.3.4",
+    "@openclawbrain/event-export": "^0.3.4",
     "@openclawbrain/learner": "^0.3.4",
     "@openclawbrain/pack-format": "^0.3.4",
-    "@openclawbrain/event-export": "^0.3.4"
+    "@openclawbrain/provenance": "^0.3.4",
+    "@openclawbrain/workspace-metadata": "^0.3.4"
   },
   "bin": {
     "openclawbrain": "dist/src/cli.js",
@@ -62,4 +64,3 @@
     "test": "node --test dist/test/*.test.js"
   }
 }
-