@haaaiawd/second-nature 0.1.8 → 0.1.10

package/index.js

@@ -19,12 +19,102 @@
  * Test coverage:
  * - tests/integration/cli/plugin-runtime-registration.test.ts
  * - tests/integration/cli/plugin-packaging-walkthrough.test.ts
+ * - tests/integration/cli/plugin-workspace-ops-bridge.test.ts (T1.1.4)
  */
 import { startRuntimeService, } from "./runtime/core/second-nature/runtime/service-entry.js";
 import { getLifecycleState, recordRegistration, } from "./runtime/core/second-nature/runtime/lifecycle-service.js";
+import { openWorkspaceOpsBridge } from "./workspace-ops-bridge.js";
 const INTERNAL_RUNTIME_TRACE_PREFIX = "sn-runtime-";
 const HOST_SAFE_LIMITATION_MESSAGE = "Host-safe plugin package keeps synchronous register/load semantics, but mutating workspace runtime flows remain unavailable here.";
 let activationSpine = null;
+/** T1.1.4 — lazily opened full read bridge; closed when workspace root / resolution changes. */
+let workspaceOpsBridge = null;
+function disposeWorkspaceOpsBridge() {
+    if (workspaceOpsBridge) {
+        workspaceOpsBridge.close();
+        workspaceOpsBridge = null;
+    }
+}
+const WORKSPACE_BRIDGE_COMMANDS = new Set([
+    "status",
+    "quiet",
+    "report",
+    "session",
+    "explain",
+    "heartbeat_check",
+    "fallback",
+    "storage_smoke",
+]);
+function isWorkspaceBridgeCommand(command, input) {
+    if (command === "credential") {
+        const action = typeof input?.action === "string" ? input.action : "show";
+        return action !== "verify";
+    }
+    return WORKSPACE_BRIDGE_COMMANDS.has(command);
+}
+async function ensureWorkspaceOpsBridge(spine) {
+    const root = spine.workspaceRootContext.runtimeRoot;
+    if (workspaceOpsBridge?.root === root) {
+        return { ok: true, dispatch: workspaceOpsBridge.dispatch };
+    }
+    disposeWorkspaceOpsBridge();
+    const opened = await openWorkspaceOpsBridge(root);
+    if (!opened.ok) {
+        return opened;
+    }
+    workspaceOpsBridge = { root, close: opened.close, dispatch: opened.dispatch };
+    return { ok: true, dispatch: opened.dispatch };
+}
+async function routeSecondNatureCommand(spine, command, input) {
+    const wr = spine.workspaceRootContext;
+    const useBridge = wr.resolution !== "unknown" && isWorkspaceBridgeCommand(command, input);
+    if (useBridge) {
+        const bridge = await ensureWorkspaceOpsBridge(spine);
+        if (!bridge.ok) {
+            return {
+                ok: false,
+                surfaceMode: "host_safe_carrier",
+                workspaceReadModelsEvaluated: false,
+                message: HOST_SAFE_LIMITATION_MESSAGE,
+                error: bridge.error,
+                data: {
+                    workspaceRootResolution: wr.resolution,
+                    bridgeAttempted: true,
+                    declaredRoot: wr.declaredRoot,
+                },
+            };
+        }
+        return (await bridge.dispatch(command, input));
+    }
+    const def = spine.router.resolve(command);
+    if (!def) {
+        return { ok: false, message: `Unknown Second Nature command: ${command}` };
+    }
+    return def.execute(input);
+}
+function resolveWorkspaceRoot(toolWorkspaceRoot) {
+    const env = process.env.SECOND_NATURE_WORKSPACE_ROOT?.trim();
+    if (env) {
+        return { resolution: "env", declaredRoot: env, runtimeRoot: env };
+    }
+    const tool = toolWorkspaceRoot?.trim();
+    if (tool) {
+        return { resolution: "tool_args", declaredRoot: tool, runtimeRoot: tool };
+    }
+    return { resolution: "unknown", declaredRoot: undefined, runtimeRoot: process.cwd() };
+}
+function syncWorkspaceRootFromTool(spine, toolWorkspaceRoot) {
+    const next = resolveWorkspaceRoot(toolWorkspaceRoot);
+    const prev = spine.workspaceRootContext;
+    const changed = next.runtimeRoot !== prev.runtimeRoot || next.resolution !== prev.resolution;
+    if (changed) {
+        disposeWorkspaceOpsBridge();
+    }
+    spine.workspaceRootContext = next;
+    if (changed) {
+        spine.runtimeHandle = startRuntimeService({ workspaceRoot: next.runtimeRoot });
+    }
+}
 function trimRuntimeEvidence(spine) {
     if (spine.runtimeEvidence.length > 12) {
         spine.runtimeEvidence.splice(0, spine.runtimeEvidence.length - 12);
@@ -70,6 +160,17 @@ function parseExplainSubject(subjectRaw) {
         case "soul":
         case "soul-change":
             return { subjectType: "soul-change", subjectId: id };
+        case "fallback":
+            return { subjectType: "fallback", subjectId: id };
+        case "probe":
+            return { subjectType: "probe", subjectId: id };
+        case "report":
+            return { subjectType: "report", subjectId: id };
+        case "delivery":
+            return { subjectType: "delivery", subjectId: id };
+        case "source":
+        case "source_ref":
+            return { subjectType: "source_ref", subjectId: id };
         default:
             throw new Error("explain_subject_unsupported");
     }
@@ -77,56 +178,73 @@ function parseExplainSubject(subjectRaw) {
 function buildStatusPayload(spine) {
     const runtimeEvidence = latestRuntimeEvidence(spine);
     const updatedAt = runtimeEvidence?.createdAt ?? new Date(spine.lifecycleState.lastChangedAt).toISOString();
+    const wr = spine.workspaceRootContext;
+    const needsRootHint = wr.resolution === "unknown";
     return {
-        ok: true,
+        ok: false,
+        surfaceMode: "host_safe_carrier",
+        workspaceReadModelsEvaluated: false,
+        message: HOST_SAFE_LIMITATION_MESSAGE,
+        error: {
+            code: "WORKSPACE_READ_SURFACE_UNAVAILABLE",
+            message: "Aggregated status requires workspace state; the host-safe plugin does not load persisted read models on this surface.",
+            requiredUserInput: needsRootHint ? ["SECOND_NATURE_WORKSPACE_ROOT or tool workspaceRoot"] : [],
+            nextStep: "run_workspace_second_nature_cli_or_full_runtime_package",
+        },
         data: {
-            runtime: {
+            workspaceRootResolution: wr.resolution,
+            carrier: {
                 host: "openclaw-plugin",
                 serviceStatus: spine.runtimeHandle.ready ? "running" : "idle",
                 updatedAt,
-            },
-            rhythm: {
-                mode: "active",
-                windowId: undefined,
-            },
-            quiet: {
-                mode: "unknown",
-                lastEvent: runtimeEvidence?.traceId,
-                interrupted: undefined,
-            },
-            connectors: [],
-            credentials: [],
-            risk: {
-                level: "low",
-                flags: [],
+                lastRuntimeTraceId: runtimeEvidence?.traceId,
             },
         },
     };
 }
-function buildQuietPayload(scope) {
+function buildQuietPayload(spine, scope) {
+    const wr = spine.workspaceRootContext;
     return {
-        ok: true,
+        ok: false,
+        surfaceMode: "host_safe_carrier",
+        workspaceReadModelsEvaluated: false,
+        message: HOST_SAFE_LIMITATION_MESSAGE,
+        error: {
+            code: "QUIET_READ_SURFACE_UNAVAILABLE",
+            message: "Quiet read surface requires workspace runtime; not evaluated in host-safe carrier mode.",
+            requiredUserInput: wr.resolution === "unknown" ? ["SECOND_NATURE_WORKSPACE_ROOT or tool workspaceRoot"] : [],
+            nextStep: "run_workspace_second_nature_cli_or_full_runtime_package",
+        },
         data: {
             scope,
-            mode: "unknown",
-            sourceCount: 0,
-            reportCount: 0,
-            recentJournalCount: 0,
+            evaluated: false,
+            unavailableReason: "host_safe_carrier_no_workspace_db",
+            workspaceRootResolution: wr.resolution,
         },
     };
 }
-function buildReportPayload(day) {
+function buildReportPayload(spine, day) {
+    const wr = spine.workspaceRootContext;
     return {
-        ok: true,
+        ok: false,
+        surfaceMode: "host_safe_carrier",
+        workspaceReadModelsEvaluated: false,
+        message: HOST_SAFE_LIMITATION_MESSAGE,
+        error: {
+            code: "REPORT_READ_SURFACE_UNAVAILABLE",
+            message: "Daily report artifacts require workspace runtime.",
+            requiredUserInput: wr.resolution === "unknown" ? ["SECOND_NATURE_WORKSPACE_ROOT or tool workspaceRoot"] : [],
+            nextStep: "run_workspace_second_nature_cli_or_full_runtime_package",
+        },
         data: {
+            evaluated: false,
+            unavailableReason: "host_safe_carrier_no_workspace_db",
             day: day && day.trim() ? day : new Date().toISOString().slice(0, 10),
-            summary: "",
-            highlights: [],
-            sourceRefs: [],
+            workspaceRootResolution: wr.resolution,
         },
     };
 }
-function buildSessionPayload(sessionId) {
+function buildSessionPayload(spine, sessionId) {
     if (!sessionId) {
         return {
             ok: false,
@@ -138,26 +256,44 @@ function buildSessionPayload(sessionId) {
             },
         };
     }
+    const wr = spine.workspaceRootContext;
     return {
-        ok: true,
+        ok: false,
+        surfaceMode: "host_safe_carrier",
+        workspaceReadModelsEvaluated: false,
+        message: HOST_SAFE_LIMITATION_MESSAGE,
+        error: {
+            code: "SESSION_READ_SURFACE_UNAVAILABLE",
+            message: "Session analytics require workspace state database.",
+            requiredUserInput: wr.resolution === "unknown" ? ["SECOND_NATURE_WORKSPACE_ROOT or tool workspaceRoot"] : [],
+            nextStep: "run_workspace_second_nature_cli_or_full_runtime_package",
+        },
         data: {
             requestedSessionId: sessionId,
-            traceId: sessionId,
-            decisionCount: 0,
-            attemptCount: 0,
-            governanceCount: 0,
-            keyFactors: [],
-            evidenceRefs: [],
+            evaluated: false,
+            unavailableReason: "host_safe_carrier_no_workspace_db",
+            workspaceRootResolution: wr.resolution,
         },
     };
 }
-function buildCredentialPayload(platformId) {
+function buildCredentialPayload(spine, platformId) {
+    const wr = spine.workspaceRootContext;
     return {
-        ok: true,
+        ok: false,
+        surfaceMode: "host_safe_carrier",
+        workspaceReadModelsEvaluated: false,
+        message: HOST_SAFE_LIMITATION_MESSAGE,
+        error: {
+            code: "CREDENTIAL_READ_SURFACE_UNAVAILABLE",
+            message: "Credential inspection requires workspace runtime on this surface.",
+            requiredUserInput: wr.resolution === "unknown" ? ["SECOND_NATURE_WORKSPACE_ROOT or tool workspaceRoot"] : [],
+            nextStep: "run_workspace_second_nature_cli_or_full_runtime_package",
+        },
         data: {
-            platformId: platformId && platformId.trim() ? platformId : "unknown",
-            status: "missing",
-            nextStep: "provide_credential_context",
+            platformId: platformId && platformId.trim() ? platformId : undefined,
+            evaluated: false,
+            unavailableReason: "host_safe_carrier_no_workspace_db",
+            workspaceRootResolution: wr.resolution,
         },
     };
 }
@@ -183,44 +319,79 @@ function buildExplainPayload(spine, subjectRaw) {
             return createUnavailableActionError("EXPLAIN_SUBJECT_REQUIRES_ID", "subject must include identifier", ["subject"], "reinvoke_explain_with_supported_subject");
         }
         if (code === "explain_subject_unsupported") {
-            return createUnavailableActionError("EXPLAIN_SUBJECT_UNSUPPORTED", "supported subjects are decision:<id>, platform:<id>, outreach:<id>, soul:<id>", ["subject"], "reinvoke_explain_with_supported_subject");
+            return createUnavailableActionError("EXPLAIN_SUBJECT_UNSUPPORTED", "supported subjects include decision:, platform:, outreach:, soul:, fallback:, delivery:, probe:, report:, source:", ["subject"], "reinvoke_explain_with_supported_subject");
         }
         return createUnavailableActionError("EXPLAIN_SUBJECT_INVALID", "invalid explain subject", ["subject"], "reinvoke_explain_with_supported_subject");
     }
-    const runtimeEvidence = latestRuntimeEvidence(spine);
+    const wr = spine.workspaceRootContext;
     return {
-        ok: true,
+        ok: false,
+        surfaceMode: "host_safe_carrier",
+        workspaceReadModelsEvaluated: false,
+        message: HOST_SAFE_LIMITATION_MESSAGE,
+        error: {
+            code: "EXPLAIN_READ_SURFACE_UNAVAILABLE",
+            message: "Evidence-backed explain requires persisted workspace read models; host-safe carrier did not evaluate operator explain (CH-11-02).",
+            requiredUserInput: wr.resolution === "unknown" ? ["SECOND_NATURE_WORKSPACE_ROOT or tool workspaceRoot"] : [],
+            nextStep: "run_workspace_second_nature_cli_or_full_runtime_package",
+        },
         data: {
             subjectType: subject.subjectType,
-            conclusion: "Plugin surface is loaded in host-safe mode with a minimal activation spine.",
-            keyFactors: [
-                "synchronous_register",
-                `subject:${subject.subjectId}`,
-                runtimeEvidence?.capability ?? "runtime.activate",
-            ],
-            evidenceRefs: [
-                runtimeEvidence?.traceId ?? `${INTERNAL_RUNTIME_TRACE_PREFIX}none`,
-                `subject:${subjectRaw.trim()}`,
-                "host_safe_mode",
-            ],
-            nextStep: "use full workspace runtime for evidence-backed explain details",
+            evaluated: false,
+            workspaceRootResolution: wr.resolution,
         },
     };
 }
+async function buildStorageSmokePayload(input) {
+    try {
+        const mod = await import("./runtime/storage/bootstrap/storage-mode-smoke.js");
+        const runRepairFixture = Boolean(input?.runRepairFixture);
+        const workspaceRoot = typeof input?.workspaceRoot === "string" ? input.workspaceRoot : undefined;
+        const data = await mod.runStorageModeSmoke({ runRepairFixture, workspaceRoot });
+        return { ok: true, data };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: error instanceof Error ? error.message : String(error),
+            error: {
+                code: "STORAGE_SMOKE_LOAD_FAILED",
+                message: "Could not load packaged storage-mode smoke module",
+                nextStep: "rebuild_plugin_runtime_package",
+            },
+        };
+    }
+}
+function buildFallbackHostSafePayload(ref) {
+    if (!ref?.trim()) {
+        return {
+            ok: false,
+            error: {
+                code: "MISSING_FALLBACK_REF",
+                message: "fallback requires ref (e.g. fallback:…)",
+                requiredUserInput: ["ref"],
+                nextStep: "reinvoke_with_ref",
+            },
+        };
+    }
+    return createUnavailableActionError("HOST_SAFE_FALLBACK_VIEW_UNAVAILABLE", "Operator fallback view requires workspace state database; host-safe plugin cannot read persisted fallback artifacts.", ["ref"], "run_workspace_second_nature_cli_or_full_runtime_package");
+}
 function buildHeartbeatCheckPayload(spine, input) {
     const runtimeEvidence = latestRuntimeEvidence(spine);
     const updatedAt = runtimeEvidence?.createdAt ?? new Date(spine.lifecycleState.lastChangedAt).toISOString();
     const timestamp = typeof input?.timestamp === "string" && input.timestamp.trim().length > 0 ? input.timestamp : updatedAt;
+    const wr = spine.workspaceRootContext;
     return {
         ok: true,
-        status: "heartbeat_ok",
-        heartbeat: "HEARTBEAT_OK",
+        status: "runtime_carrier_only",
+        livedExperienceLoopClaimed: false,
         scope: "rhythm",
         trigger: "heartbeat_bridge",
-        reasons: ["host_safe_bridge_ready"],
-        nextAction: "continue",
-        message: "Host-safe heartbeat bridge acknowledged the round. No additional action is required from this surface.",
+        reasons: ["runtime_carrier_only", "host_safe_bridge_ack"],
+        nextAction: "continue_carrier_surface_only",
+        message: "Packaged carrier acknowledged this heartbeat round. This is not a full lived-experience decision loop; use the workspace CLI when read models are required.",
         data: {
+            workspaceRootResolution: wr.resolution,
             runtime: {
                 host: "openclaw-plugin",
                 serviceStatus: spine.runtimeHandle.ready ? "running" : "idle",
@@ -271,7 +442,7 @@ function createHostSafeRouter(spine) {
                     return createUnavailableActionError("HOST_SAFE_CREDENTIAL_VERIFY_UNAVAILABLE", "credential verify is unavailable in the host-safe plugin package", ["verification_answer"], "run_workspace_runtime_or_reinstall_full_build");
                 }
                 const platformId = typeof input?.platformId === "string" ? input.platformId : undefined;
-                return buildCredentialPayload(platformId);
+                return buildCredentialPayload(spine, platformId);
             },
         },
         {
@@ -279,7 +450,7 @@ function createHostSafeRouter(spine) {
             description: "Inspect Quiet lifecycle state",
             execute: async (input) => {
                 const scope = typeof input?.scope === "string" ? input.scope : undefined;
-                return buildQuietPayload(scope);
+                return buildQuietPayload(spine, scope);
             },
         },
         {
@@ -287,7 +458,7 @@ function createHostSafeRouter(spine) {
             description: "Show daily report artifacts",
             execute: async (input) => {
                 const day = typeof input?.day === "string" ? input.day : undefined;
-                return buildReportPayload(day);
+                return buildReportPayload(spine, day);
             },
         },
         {
@@ -295,7 +466,7 @@ function createHostSafeRouter(spine) {
             description: "Inspect continuity session details",
             execute: async (input) => {
                 const sessionId = typeof input?.sessionId === "string" ? input.sessionId : undefined;
-                return buildSessionPayload(sessionId);
+                return buildSessionPayload(spine, sessionId);
             },
         },
         {
@@ -316,6 +487,19 @@ function createHostSafeRouter(spine) {
             description: "Acknowledge the shipping heartbeat bridge round",
             execute: async (input) => buildHeartbeatCheckPayload(spine, input),
         },
+        {
+            name: "fallback",
+            description: "Operator-visible delivery fallback view (full workspace runtime required)",
+            execute: async (input) => {
+                const ref = typeof input?.ref === "string" ? input.ref.trim() : undefined;
+                return buildFallbackHostSafePayload(ref);
+            },
+        },
+        {
+            name: "storage_smoke",
+            description: "T4.1.4 storage mode smoke report (sql.js vs native probe)",
+            execute: async (input) => buildStorageSmokePayload(input),
+        },
     ];
     return {
         commands,
@@ -325,12 +509,14 @@ function createHostSafeRouter(spine) {
     };
 }
 function createActivationSpine() {
+    const workspaceRootContext = resolveWorkspaceRoot(undefined);
     const spine = {
         router: undefined,
-        runtimeHandle: startRuntimeService({ workspaceRoot: process.cwd() }),
+        runtimeHandle: startRuntimeService({ workspaceRoot: workspaceRootContext.runtimeRoot }),
         lifecycleState: getLifecycleState(),
         serviceStartRecorded: false,
         runtimeEvidence: [],
+        workspaceRootContext,
     };
     spine.router = createHostSafeRouter(spine);
     return spine;
@@ -364,7 +550,14 @@ function recordRuntimeEvidence(spine, origin) {
 }
 function refreshRegistrationState() {
     const spine = ensureActivationSpine();
-    spine.runtimeHandle = startRuntimeService({ workspaceRoot: process.cwd() });
+    const workspaceRootContext = resolveWorkspaceRoot(undefined);
+    const prev = spine.workspaceRootContext;
+    const changed = workspaceRootContext.runtimeRoot !== prev.runtimeRoot || workspaceRootContext.resolution !== prev.resolution;
+    if (changed) {
+        disposeWorkspaceOpsBridge();
+    }
+    spine.workspaceRootContext = workspaceRootContext;
+    spine.runtimeHandle = startRuntimeService({ workspaceRoot: workspaceRootContext.runtimeRoot });
     spine.lifecycleState = recordRegistration();
     spine.serviceStartRecorded = false;
     recordRuntimeEvidence(spine, "register");
@@ -442,6 +635,20 @@ function parseCommandInput(rawArgs) {
                 command,
                 input: rest.length > 0 ? { subject: rest.join(" ") } : undefined,
             };
+        case "fallback":
+            return {
+                ok: true,
+                command,
+                input: rest.length > 0 ? { ref: rest.join(" ") } : undefined,
+            };
+        case "storage_smoke": {
+            const wantRepair = rest[0] === "repair" || rest.includes("--repair");
+            return {
+                ok: true,
+                command,
+                input: wantRepair ? { runRepairFixture: true } : undefined,
+            };
+        }
         default:
             return {
                 ok: true,
@@ -503,7 +710,7 @@ export default {
                         text: JSON.stringify({ ok: false, command: parsed.command, message: "Unknown Second Nature command." }),
                     };
                 }
-                const result = await resolved.execute(parsed.input);
+                const result = await routeSecondNatureCommand(spine, parsed.command, parsed.input);
                 return {
                     text: JSON.stringify(result),
                 };
@@ -518,11 +725,16 @@ export default {
                 properties: {
                     command: { type: "string" },
                     args: { type: "object", additionalProperties: true },
+                    workspaceRoot: {
+                        type: "string",
+                        description: "Workspace root for packaged smoke/runtime alignment (optional; prefer SECOND_NATURE_WORKSPACE_ROOT).",
+                    },
                 },
                 required: ["command"],
             },
             async execute(_id, params) {
                 const spine = ensureActivationSpine();
+                syncWorkspaceRootFromTool(spine, params.workspaceRoot);
                 const resolved = spine.router.resolve(params.command);
                 if (!resolved) {
                     return {
@@ -534,7 +746,7 @@ export default {
                         ],
                     };
                 }
-                const result = await resolved.execute(params.args);
+                const result = await routeSecondNatureCommand(spine, params.command, params.args);
                 return {
                     content: [
                         {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "second-nature",
   "name": "Second Nature",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "entry": "./index.js",
   "description": "OpenClaw native plugin package with synchronous surface registration and a bundled runtime spine.",
   "capabilities": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haaaiawd/second-nature",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "OpenClaw native plugin with synchronous registration, a packaged runtime artifact, and operator-facing status/explain flows.",
   "keywords": [
     "openclaw",
@@ -17,6 +17,7 @@
   "main": "./index.js",
   "files": [
     "index.js",
+    "workspace-ops-bridge.js",
     "openclaw.plugin.json",
     "runtime/"
   ],

package/runtime/cli/commands/index.d.ts

@@ -1,4 +1,5 @@
 import type { ActionBridge } from "../action-bridge.js";
+import type { OpsRouter } from "../ops/ops-router.js";
 import type { CliReadModels } from "../read-models/index.js";
 export interface CliCommandDefinition {
     name: string;
@@ -8,5 +9,6 @@ export interface CliCommandDefinition {
 export interface CliCommandDeps {
     readModels: CliReadModels;
     actionBridge: ActionBridge;
+    opsRouter: OpsRouter;
 }
 export declare function createCliCommands(deps: CliCommandDeps): CliCommandDefinition[];

package/runtime/cli/commands/index.js

@@ -1,6 +1,8 @@
 import { credentialVerify } from "./credential.js";
 import { formatExplanation } from "../explain/format-explanation.js";
-import { resolveExplainSubject } from "../explain/resolve-subject.js";
+import { explainSurfaceSubject } from "../explain/explain-surface-subject.js";
+import { showOperatorFallback, OperatorFallbackNotFoundError } from "../ops/show-operator-fallback.js";
+import { runStorageModeSmoke } from "../../storage/bootstrap/storage-mode-smoke.js";
 import { policySet } from "./policy.js";
 const notImplemented = async (command) => ({
     ok: false,
@@ -19,7 +21,7 @@ function explainSubjectError(code, message) {
     };
 }
 export function createCliCommands(deps) {
-    const { readModels, actionBridge } = deps;
+    const { readModels, actionBridge, opsRouter } = deps;
     return [
         {
             name: "status",
@@ -113,9 +115,9 @@ export function createCliCommands(deps) {
                         },
                     };
                 }
-                let subject;
+                let model;
                 try {
-                    subject = resolveExplainSubject(subjectRaw);
+                    model = await explainSurfaceSubject(subjectRaw, readModels);
                 }
                 catch (error) {
                     const code = error.message;
@@ -123,16 +125,69 @@ export function createCliCommands(deps) {
                         return explainSubjectError("EXPLAIN_SUBJECT_REQUIRES_ID", "subject must include identifier");
                     }
                     if (code === "explain_subject_unsupported") {
-                        return explainSubjectError("EXPLAIN_SUBJECT_UNSUPPORTED", "supported subjects are decision:<id>, platform:<id>, outreach:<id>, soul:<id>");
+                        return explainSubjectError("EXPLAIN_SUBJECT_UNSUPPORTED", "supported subjects include decision:, platform:, outreach:, soul:, fallback:, delivery:, probe:, report:, source:");
                     }
                     return explainSubjectError("EXPLAIN_SUBJECT_INVALID", "invalid explain subject");
                 }
-                const model = await readModels.explain(subject);
                 return {
                     ok: true,
                     data: formatExplanation(model),
                 };
             },
         },
+        {
+            name: "heartbeat_check",
+            description: "Workspace heartbeat_check ops surface (v5 HeartbeatSurfaceResult)",
+            execute: async (input) => {
+                const surface = await Promise.resolve(opsRouter.dispatch("heartbeat_check", input));
+                return surface;
+            },
+        },
+        {
+            name: "storage_smoke",
+            description: "T4.1.4 — report sql.js vs native SQLite probe and optional artifact→index repair fixture",
+            execute: async (input) => {
+                const runRepairFixture = Boolean(input?.runRepairFixture);
+                const workspaceRoot = typeof input?.workspaceRoot === "string" ? input.workspaceRoot : undefined;
+                const data = await runStorageModeSmoke({ runRepairFixture, workspaceRoot });
+                return { ok: true, data };
+            },
+        },
+        {
+            name: "fallback",
+            description: "Operator-visible delivery fallback view (status always not_sent)",
+            execute: async (input) => {
+                const ref = typeof input?.ref === "string" ? input.ref.trim() : "";
+                if (!ref) {
+                    return {
+                        ok: false,
+                        error: {
+                            code: "MISSING_FALLBACK_REF",
+                            message: "fallback requires ref (e.g. fallback:…)",
+                            requiredUserInput: ["ref"],
+                            nextStep: "reinvoke_with_ref",
+                        },
+                    };
+                }
+                try {
+                    const data = await showOperatorFallback(ref, readModels);
+                    return { ok: true, data };
+                }
+                catch (error) {
+                    if (error instanceof OperatorFallbackNotFoundError) {
+                        return {
+                            ok: false,
+                            error: {
+                                code: error.code,
+                                message: error.message,
+                                requiredUserInput: ["ref"],
+                                nextStep: "verify_fallback_ref_from_delivery_audit",
+                            },
+                        };
+                    }
+                    throw error;
+                }
+            },
+        },
     ];
 }

package/runtime/cli/explain/explain-surface-subject.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Stable operator explain entry matching cli-system.detail §3.8 (T1.2.1).
+ *
+ * Core logic: parse subject string via resolveExplainSubject, delegate to read models.
+ */
+import type { CliReadModels } from "../read-models/index.js";
+import type { ExplainReadModel } from "../read-models/types.js";
+export declare function explainSurfaceSubject(subjectRaw: string, readModels: CliReadModels): Promise<ExplainReadModel>;