@haaaiawd/second-nature 0.1.7 → 0.1.9

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>;

package/runtime/cli/explain/explain-surface-subject.js

@@ -0,0 +1,9 @@
+import { resolveExplainSubject } from "./resolve-subject.js";
+export async function explainSurfaceSubject(subjectRaw, readModels) {
+    const trimmed = subjectRaw.trim();
+    if (!trimmed) {
+        throw new Error("explain_subject_requires_id");
+    }
+    const subject = resolveExplainSubject(trimmed);
+    return readModels.explain(subject);
+}

package/runtime/cli/explain/format-explanation.d.ts

@@ -6,5 +6,7 @@ export interface FormattedExplanation {
     evidenceRefs: string[];
     requiredUserInput?: string[];
     nextStep?: string;
+    warnings?: string[];
+    relatedAuditEventIds?: string[];
 }
 export declare function formatExplanation(model: ExplainReadModel): FormattedExplanation;

package/runtime/cli/explain/format-explanation.js

@@ -6,5 +6,7 @@ export function formatExplanation(model) {
         evidenceRefs: model.evidenceRefs,
         requiredUserInput: model.requiredUserInput,
         nextStep: model.nextStep,
+        warnings: model.warnings,
+        relatedAuditEventIds: model.relatedAuditEventIds,
     };
 }

package/runtime/cli/explain/resolve-subject.js

@@ -22,5 +22,20 @@ export function resolveExplainSubject(raw) {
     if (prefix === "soul") {
         return { kind: "soul-change", id };
     }
+    if (prefix === "fallback") {
+        return { kind: "fallback", id };
+    }
+    if (prefix === "probe") {
+        return { kind: "probe", id };
+    }
+    if (prefix === "report") {
+        return { kind: "report", id };
+    }
+    if (prefix === "delivery") {
+        return { kind: "delivery", id };
+    }
+    if (prefix === "source" || prefix === "source_ref") {
+        return { kind: "source_ref", id };
+    }
     throw new Error("explain_subject_unsupported");
 }

package/runtime/cli/host-capability/classify-delivery.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalizes host-reported delivery signals into DeliveryCapabilityStatus (cli-system).
+ */
+import type { DeliveryCapabilityStatus } from "./types.js";
+export interface ClassifyDeliveryCapabilityInput {
+    /** Host-reported delivery channel / target hint */
+    rawTarget?: string | null;
+    channel?: string | null;
+    /** When false, host API for delivery is not reachable */
+    apiAvailable?: boolean;
+    /** When true, host explicitly reports unsupported delivery surface */
+    hostUnsupported?: boolean;
+}
+export declare function classifyDeliveryCapability(input: ClassifyDeliveryCapabilityInput): DeliveryCapabilityStatus;

package/runtime/cli/host-capability/classify-delivery.js

@@ -0,0 +1,20 @@
+export function classifyDeliveryCapability(input) {
+    if (input.hostUnsupported) {
+        return "host_unsupported";
+    }
+    if (input.apiAvailable === false) {
+        return "host_api_unavailable";
+    }
+    const target = (input.rawTarget ?? "").trim().toLowerCase();
+    if (target === "none" || target === "") {
+        return "target_none";
+    }
+    const ch = (input.channel ?? "").trim();
+    if (!ch) {
+        return "channel_missing";
+    }
+    if (target === "unknown" || target === "unspecified") {
+        return "unknown";
+    }
+    return "target_available";
+}

package/runtime/cli/host-capability/probe-host-capability.d.ts

@@ -0,0 +1,2 @@
+import type { HostCapabilityProbeOptions, HostCapabilityReport } from "./types.js";
+export declare function probeHostCapability(options: HostCapabilityProbeOptions): HostCapabilityReport;

package/runtime/cli/host-capability/probe-host-capability.js

@@ -0,0 +1,58 @@
+/**
+ * OpenClaw host capability probe — aggregates adapter checks into HostCapabilityReport.
+ */
+import * as crypto from "node:crypto";
+function mergeEvidenceRefs(...groups) {
+    const seen = new Set();
+    const out = [];
+    for (const group of groups) {
+        for (const ref of group) {
+            const key = `${ref.kind}:${ref.id}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push(ref);
+            }
+        }
+    }
+    return out;
+}
+export function probeHostCapability(options) {
+    const { adapter, docLinks, docCheckedAt, hostVersion, observedVersion } = options;
+    const generatedAt = new Date().toISOString();
+    const pluginLoad = adapter.checkPluginLoad();
+    const heartbeatBridge = adapter.checkHeartbeatBridge();
+    const heartbeatToolInvocation = adapter.checkHeartbeatToolInvocation();
+    const delivery = adapter.checkDeliveryTarget();
+    const deliveryTarget = delivery.status;
+    const ackDropBehavior = adapter.checkAckDropBehavior();
+    const hookSupport = adapter.checkHookSupport();
+    const conflictRecords = [];
+    if (delivery.reason === "docs_vs_observed_mismatch" && docLinks.length > 0) {
+        const doc = docLinks[0];
+        conflictRecords.push({
+            capability: "delivery_target",
+            documentedBehavior: doc.documentedBehavior,
+            observedBehavior: deliveryTarget,
+            hostVersion,
+            docUrl: doc.url,
+        });
+    }
+    const evidenceRefs = mergeEvidenceRefs(pluginLoad.evidenceRefs, heartbeatBridge.evidenceRefs, heartbeatToolInvocation.evidenceRefs, delivery.evidenceRefs, ackDropBehavior.evidenceRefs, ...hookSupport.map((h) => h.evidenceRefs));
+    return {
+        reportId: crypto.randomUUID(),
+        generatedAt,
+        hostVersion,
+        observedVersion,
+        docLinks,
+        docCheckedAt,
+        pluginLoad,
+        heartbeatBridge,
+        heartbeatToolInvocation,
+        deliveryTarget,
+        ackDropBehavior,
+        hookSupport,
+        evidenceRefs,
+        conflictRecords,
+        recommendedNextStep: conflictRecords.length > 0 ? "reconcile_docs_vs_observed" : undefined,
+    };
+}

package/runtime/cli/host-capability/record-host-capability.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Persist HostCapabilityReport into observability SQLite (T1.1.2).
+ */
+import type { ObservabilityDatabase } from "../../observability/db/index.js";
+import type { HostCapabilityReport } from "./types.js";
+export declare function recordHostCapability(db: ObservabilityDatabase, report: HostCapabilityReport): Promise<void>;

package/runtime/cli/host-capability/record-host-capability.js

@@ -0,0 +1,14 @@
+import { hostCapabilityReports } from "../../observability/db/schema/host-capability-reports.js";
+export async function recordHostCapability(db, report) {
+    await db.db.insert(hostCapabilityReports).values({
+        reportId: report.reportId,
+        generatedAt: report.generatedAt,
+        hostVersion: report.hostVersion ?? null,
+        observedVersion: report.observedVersion ?? null,
+        docCheckedAt: report.docCheckedAt,
+        docLinksJson: JSON.stringify(report.docLinks),
+        deliveryTarget: report.deliveryTarget,
+        conflictRecordsJson: JSON.stringify(report.conflictRecords),
+        fullReportJson: JSON.stringify(report),
+    });
+}

package/runtime/cli/host-capability/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Host capability probe contracts (cli-system v5 / ADR-007).
+ *
+ * Test coverage: tests/unit/cli/host-capability.test.ts, tests/integration/cli/host-capability-probe.test.ts
+ */
+export type DeliveryCapabilityStatus = "target_available" | "target_none" | "channel_missing" | "host_api_unavailable" | "host_unsupported" | "unknown";
+export type CapabilityVerdict = "pass" | "fail" | "unknown" | "not_applicable";
+export interface SourceRef {
+    id: string;
+    kind: "platform_item" | "workspace_artifact" | "decision_record" | "user_anchor" | "connector_result" | "host_report" | "fallback_artifact";
+    uri: string;
+    excerptHash?: string;
+    observedAt?: string;
+}
+export interface HostCapabilityDocReference {
+    title: string;
+    url: string;
+    checkedAt: string;
+    documentedBehavior: string;
+}
+export interface HostCapabilityConflictRecord {
+    capability: string;
+    documentedBehavior: string;
+    observedBehavior: string;
+    hostVersion?: string;
+    docUrl?: string;
+}
+export interface CapabilityCheckResult {
+    name: string;
+    verdict: CapabilityVerdict;
+    observedAt: string;
+    reason?: string;
+    evidenceRefs: SourceRef[];
+}
+export interface HostCapabilityReport {
+    reportId: string;
+    generatedAt: string;
+    hostVersion?: string;
+    observedVersion?: string;
+    docLinks: HostCapabilityDocReference[];
+    docCheckedAt: string;
+    pluginLoad: CapabilityCheckResult;
+    heartbeatBridge: CapabilityCheckResult;
+    heartbeatToolInvocation: CapabilityCheckResult;
+    deliveryTarget: DeliveryCapabilityStatus;
+    ackDropBehavior: CapabilityCheckResult;
+    hookSupport: CapabilityCheckResult[];
+    evidenceRefs: SourceRef[];
+    conflictRecords: HostCapabilityConflictRecord[];
+    recommendedNextStep?: string;
+}
+export interface HostCapabilityProbeOptions {
+    adapter: HostCapabilityAdapter;
+    docLinks: HostCapabilityDocReference[];
+    docCheckedAt: string;
+    hostVersion?: string;
+    observedVersion?: string;
+}
+export interface HostCapabilityAdapter {
+    checkPluginLoad(): CapabilityCheckResult;
+    checkHeartbeatBridge(): CapabilityCheckResult;
+    checkHeartbeatToolInvocation(): CapabilityCheckResult;
+    /** Return normalized delivery capability as observed on the host */
+    checkDeliveryTarget(): {
+        status: DeliveryCapabilityStatus;
+        evidenceRefs: SourceRef[];
+        reason?: string;
+    };
+    checkAckDropBehavior(): CapabilityCheckResult;
+    checkHookSupport(): CapabilityCheckResult[];
+}

package/runtime/cli/host-capability/types.js

@@ -0,0 +1,6 @@
+/**
+ * Host capability probe contracts (cli-system v5 / ADR-007).
+ *
+ * Test coverage: tests/unit/cli/host-capability.test.ts, tests/integration/cli/host-capability-probe.test.ts
+ */
+export {};

package/runtime/cli/host-smoke/run-host-smoke.d.ts

@@ -0,0 +1,2 @@
+import type { HostSmokePlan, HostSmokeReport } from "./types.js";
+export declare function runHostSmoke(plan: HostSmokePlan): Promise<HostSmokeReport>;

package/runtime/cli/host-smoke/run-host-smoke.js

@@ -0,0 +1,40 @@
+/**
+ * Reproducible host smoke runner (T1.3.1). Uses transcript fixtures — no live OpenClaw in unit/integration path.
+ *
+ * Core logic: evaluate `heartbeat_tool_invocation` by substring match for heartbeat_check / second_nature_ops heartbeat surface.
+ */
+import * as crypto from "node:crypto";
+function evalHeartbeatToolInvocation(c) {
+    const hasHeartbeatCheck = c.toolInvocations.some((t) => /heartbeat_check|second_nature_ops\s*\(\s*\{[^}]*heartbeat_check|command\s*:\s*["']heartbeat_check["']/i.test(t));
+    if (hasHeartbeatCheck) {
+        return { caseType: c.type, status: "pass", reasons: [] };
+    }
+    return { caseType: c.type, status: "fail", reasons: ["heartbeat_tool_not_invoked"] };
+}
+function evalDocsConflict(c) {
+    if (c.observedBehavior.trim() === c.docExpectation.trim()) {
+        return { caseType: c.type, status: "pass", reasons: [] };
+    }
+    return {
+        caseType: c.type,
+        status: "fail",
+        reasons: ["docs_vs_observed_conflict", `expected:${c.docExpectation}`, `observed:${c.observedBehavior}`],
+    };
+}
+function evalCase(c) {
+    if (c.type === "heartbeat_tool_invocation") {
+        return evalHeartbeatToolInvocation(c);
+    }
+    return evalDocsConflict(c);
+}
+export async function runHostSmoke(plan) {
+    const results = plan.cases.map((c) => evalCase(c));
+    return {
+        reportId: crypto.randomUUID(),
+        generatedAt: new Date().toISOString(),
+        results,
+        docLinks: plan.docLinks,
+        docCheckedAt: plan.docCheckedAt,
+        hostVersion: plan.hostVersion,
+    };
+}

package/runtime/cli/host-smoke/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Host smoke plan + report types (T1.3.1).
+ *
+ * `heartbeat_tool_invocation` verifies that a near-real transcript actually invoked heartbeat_check.
+ */
+export interface HeartbeatToolInvocationCase {
+    readonly type: "heartbeat_tool_invocation";
+    /** Tool names, ops strings, or host transcript fragments observed during the smoke turn */
+    toolInvocations: string[];
+}
+export interface DocsVsObservedConflictCase {
+    readonly type: "docs_vs_observed_conflict";
+    docExpectation: string;
+    observedBehavior: string;
+}
+export type HostSmokeCase = HeartbeatToolInvocationCase | DocsVsObservedConflictCase;
+export interface HostSmokePlan {
+    cases: HostSmokeCase[];
+    docLinks?: string[];
+    docCheckedAt?: string;
+    hostVersion?: string;
+}
+export interface HostSmokeCaseResult {
+    caseType: HostSmokeCase["type"];
+    status: "pass" | "fail" | "unknown";
+    reasons: string[];
+}
+export interface HostSmokeReport {
+    reportId: string;
+    generatedAt: string;
+    results: HostSmokeCaseResult[];
+    docLinks?: string[];
+    docCheckedAt?: string;
+    hostVersion?: string;
+}

package/runtime/cli/host-smoke/types.js

@@ -0,0 +1,6 @@
+/**
+ * Host smoke plan + report types (T1.3.1).
+ *
+ * `heartbeat_tool_invocation` verifies that a near-real transcript actually invoked heartbeat_check.
+ */
+export {};

package/runtime/cli/index.js

@@ -1,8 +1,11 @@
 import { createObservabilityDatabase } from "../observability/db/index.js";
 import { createStateAPI, createStateDatabase } from "../storage/index.js";
+import path from "node:path";
 import { createActionBridge } from "./action-bridge.js";
 import { createCliCommands } from "./commands/index.js";
+import { createOpsRouter } from "./ops/ops-router.js";
 import { createCliReadModels } from "./read-models/index.js";
+import { resolvePackagedRuntime } from "./runtime/runtime-artifact-boundary.js";
 export function createCliRuntimeDeps(overrides = {}) {
     const stateDb = overrides.stateDb ?? createStateDatabase();
     const observabilityDb = overrides.observabilityDb ?? createObservabilityDatabase();
@@ -19,9 +22,15 @@ export function createCliRuntimeDeps(overrides = {}) {
 }
 export function createCommandRouter(options = {}) {
     const runtime = createCliRuntimeDeps(options.deps);
+    const pluginRoot = path.join(process.cwd(), "plugin");
+    const opsRouter = createOpsRouter({
+        runtimeAvailable: resolvePackagedRuntime(pluginRoot).ok,
+        readModels: runtime.readModels,
+    });
     const commands = createCliCommands({
         readModels: runtime.readModels,
         actionBridge: runtime.actionBridge,
+        opsRouter,
     });
     return {
         commands,
@@ -34,3 +43,12 @@ export function closeCliRuntimeDeps(deps) {
     deps.stateDb.close();
     deps.observabilityDb.close();
 }
+export { createOpsRouter } from "./ops/ops-router.js";
+export { heartbeatCheck, } from "./ops/heartbeat-surface.js";
+export * from "./host-capability/types.js";
+export { classifyDeliveryCapability } from "./host-capability/classify-delivery.js";
+export { probeHostCapability } from "./host-capability/probe-host-capability.js";
+export { recordHostCapability } from "./host-capability/record-host-capability.js";
+export { runHostSmoke } from "./host-smoke/run-host-smoke.js";
+export { explainSurfaceSubject } from "./explain/explain-surface-subject.js";
+export { showOperatorFallback, OperatorFallbackNotFoundError } from "./ops/show-operator-fallback.js";

package/runtime/cli/ops/heartbeat-surface.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Stable HeartbeatSurfaceResult for second_nature_ops / CLI (T1.1.3, cli-system / ADR-005).
+ *
+ * S1 scope: carrier / probe / runtime-unavailable / fake control-plane passthrough only.
+ * Workspace full runtime: delegates to `runHeartbeatCycle` when read models are wired (US-001 / CH-09-02).
+ */
+import type { SurfaceMode } from "../runtime/runtime-artifact-boundary.js";
+import type { HeartbeatSignal } from "../../core/second-nature/heartbeat/signal.js";
+import type { CliReadModels } from "../read-models/index.js";
+export type HeartbeatSurfaceStatus = "heartbeat_ok" | "intent_selected" | "denied" | "deferred" | "runtime_carrier_only" | "delivery_unavailable";
+export interface HeartbeatSurfaceResult {
+    ok: boolean;
+    status: HeartbeatSurfaceStatus;
+    surfaceMode: SurfaceMode;
+    decisionId?: string;
+    deliveryAttemptId?: string;
+    capabilityReportRef?: string;
+    fallbackRef?: string;
+    reasons: string[];
+    /** When false, callers must not treat the round as lived-experience loop completion */
+    livedExperienceLoopClaimed: boolean;
+    /** True when structured fields mirror a fake adapter for schema parity only */
+    schemaParityOnly?: boolean;
+}
+export interface HeartbeatCheckInput {
+    probeOnly?: boolean;
+    runtimeAvailable: boolean;
+    fakeControlPlanePassthrough?: Record<string, unknown>;
+    /** When set, full-runtime heartbeat_check runs the control-plane decision loop (US-001). */
+    readModels?: CliReadModels;
+    timestamp?: string;
+    sessionContext?: string;
+    scopeHint?: HeartbeatSignal["scopeHint"];
+}
+export declare function heartbeatCheck(input: HeartbeatCheckInput): Promise<HeartbeatSurfaceResult>;

package/runtime/cli/ops/heartbeat-surface.js

@@ -0,0 +1,71 @@
+import { createWorkspaceHeartbeatRunner } from "./workspace-heartbeat-runner.js";
+function mapCycleToSurface(cycle, surfaceMode) {
+    const status = cycle.status === "runtime_carrier_only" ? "runtime_carrier_only" : cycle.status;
+    return {
+        ok: true,
+        status,
+        surfaceMode,
+        decisionId: cycle.decisionId,
+        deliveryAttemptId: cycle.deliveryAttemptId,
+        fallbackRef: cycle.fallbackRef,
+        reasons: cycle.reasons,
+        livedExperienceLoopClaimed: false,
+    };
+}
+export async function heartbeatCheck(input) {
+    if (!input.runtimeAvailable) {
+        return {
+            ok: true,
+            status: "runtime_carrier_only",
+            surfaceMode: "host_safe_carrier",
+            reasons: ["runtime_unavailable_packaged_carrier"],
+            livedExperienceLoopClaimed: false,
+        };
+    }
+    if (input.probeOnly) {
+        return {
+            ok: true,
+            status: "heartbeat_ok",
+            surfaceMode: "capability_probe",
+            reasons: ["probe_only"],
+            livedExperienceLoopClaimed: false,
+        };
+    }
+    if (input.fakeControlPlanePassthrough) {
+        const decisionId = typeof input.fakeControlPlanePassthrough.decisionId === "string"
+            ? input.fakeControlPlanePassthrough.decisionId
+            : undefined;
+        return {
+            ok: true,
+            status: "intent_selected",
+            surfaceMode: "host_safe_carrier",
+            reasons: ["fake_control_plane_passthrough"],
+            decisionId,
+            livedExperienceLoopClaimed: false,
+            schemaParityOnly: true,
+        };
+    }
+    if (!input.readModels) {
+        return {
+            ok: true,
+            status: "heartbeat_ok",
+            surfaceMode: "workspace_full_runtime",
+            reasons: ["heartbeat_read_models_unavailable"],
+            livedExperienceLoopClaimed: false,
+        };
+    }
+    const timestamp = typeof input.timestamp === "string" && input.timestamp.trim().length > 0
+        ? input.timestamp.trim()
+        : new Date().toISOString();
+    const signal = {
+        trigger: "heartbeat_bridge",
+        scopeHint: input.scopeHint,
+        payload: {
+            timestamp,
+            sessionContext: typeof input.sessionContext === "string" ? input.sessionContext : undefined,
+        },
+    };
+    const run = createWorkspaceHeartbeatRunner(input.readModels);
+    const cycle = await run(signal);
+    return mapCycleToSurface(cycle, "workspace_full_runtime");
+}

package/runtime/cli/ops/ops-router.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared ops command dispatch for CLI + tool surfaces (T1.1.3, T1.2.2).
+ */
+import { type HeartbeatCheckInput, type HeartbeatSurfaceResult } from "./heartbeat-surface.js";
+import type { CliReadModels } from "../read-models/index.js";
+export interface OpsRouterDeps {
+    /** When true, packaged runtime artifacts resolved and full graph is loadable */
+    runtimeAvailable: boolean;
+    /** Workspace read models: fallback view + heartbeat decision loop inputs (T1.2.2 / US-001). */
+    readModels?: CliReadModels;
+}
+export interface OpsRouter {
+    heartbeatCheck(input: HeartbeatCheckInput): Promise<HeartbeatSurfaceResult>;
+    dispatch(command: string, input?: Record<string, unknown>): HeartbeatSurfaceResult | Record<string, unknown> | Promise<HeartbeatSurfaceResult> | Promise<Record<string, unknown>>;
+}
+export declare function createOpsRouter(deps: OpsRouterDeps): OpsRouter;