@remnic/core 9.3.703 → 9.3.705

package/src/access-operations.ts

@@ -549,6 +549,10 @@ export const codegraphIngestTracesOperation = defineOperation<
   },
 });
 
+// Batch-migrated operations (issue #1525): registers all remaining
+// handlers through the boundary as a side effect of importing this module.
+import "./access-operations-batch.js";
+
 export const REGISTERED_OPERATIONS = [
   memoryGetOperation.spec.name,
   memorySearchOperation.spec.name,

package/src/access-surface-catalog.test.ts

@@ -44,7 +44,7 @@ import {
 // catalog-completeness correction: adding routes that were always live but
 // omitted from the catalog (review-caught). Such a bump MUST be accompanied
 // by the newly-cataloged entries; the higher count is the honest baseline.
-const UNMIGRATED_HANDLER_BASELINE = 134;
+const UNMIGRATED_HANDLER_BASELINE = 80;
 
 // Keep the import live — `getOperation` is the call surfaces use at dispatch
 // time; referencing it here pins the registry's lookup contract.
@@ -187,6 +187,7 @@ function extractHttpRouteDispatchMap(): Map<string, Set<string>> {
   const lines = source.split("\n");
   const routeOps = new Map<string, Set<string>>();
   let currentKey: string | null = null;
+  let lastSeenPathname: string | null = null;
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i]!;
@@ -217,6 +218,7 @@ function extractHttpRouteDispatchMap(): Map<string, Set<string>> {
     }
 
     if (pathname) {
+      lastSeenPathname = pathname;
       // Determine the HTTP method: same line first, then backward for
       // exact-match routes, forward for dynamic routes. Check both positive
       // (===) and negated (!==) method patterns — `req.method !== "GET"` as
@@ -253,6 +255,20 @@ function extractHttpRouteDispatchMap(): Map<string, Set<string>> {
       continue;
     }
 
+    // Detect method changes within a shared route block (e.g. a single
+    // regex match with GET/PUT/DELETE branches). When a new method check
+    // appears after a route pattern was already detected, update currentKey
+    // to the new method + the same pathname so per-method getOperation
+    // calls are tracked against the right route key.
+    const methodChange = line.match(/req\.method\s*===\s*"(\w+)"/);
+    if (methodChange && lastSeenPathname) {
+      const newKey = methodChange[1]! + " " + lastSeenPathname;
+      if (!routeOps.has(newKey)) {
+        routeOps.set(newKey, new Set<string>());
+      }
+      currentKey = newKey;
+    }
+
     // Collect getOperation calls within the current route block.
     if (currentKey) {
       const opMatch = line.match(/getOperation\("(\w+)"\)/);

package/src/access-surface-catalog.ts

@@ -160,65 +160,68 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
 // (health, adapters, the /mcp delegate, admin console, SSE-only endpoints)
 // carry no user request envelope and are intentionally excluded.
 export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
-  { method: "POST", pathname: "/engram/v1/recall", operation: null },
-  { method: "POST", pathname: "/engram/v1/coding-context", operation: null },
-  { method: "POST", pathname: "/engram/v1/capsules/export", operation: null },
-  { method: "POST", pathname: "/engram/v1/capsules/import", operation: null },
-  { method: "GET", pathname: "/engram/v1/offline-sync/snapshot", operation: null },
-  { method: "GET", pathname: "/engram/v1/offline-sync/snapshot-stream", operation: null },
-  { method: "POST", pathname: "/engram/v1/offline-sync/snapshot", operation: null },
-  { method: "POST", pathname: "/engram/v1/offline-sync/files", operation: null },
-  { method: "POST", pathname: "/engram/v1/offline-sync/file-content", operation: null },
-  { method: "POST", pathname: "/engram/v1/offline-sync/apply-file-content", operation: null },
-  { method: "POST", pathname: "/engram/v1/offline-sync/apply", operation: null },
-  { method: "POST", pathname: "/engram/v1/recall/explain", operation: null },
-  { method: "POST", pathname: "/engram/v1/action-confidence", operation: null },
-  { method: "GET", pathname: "/engram/v1/recall/tier-explain", operation: null },
-  { method: "GET", pathname: "/engram/v1/recall/xray", operation: null },
-  { method: "GET", pathname: "/engram/v1/wearables/status", operation: null },
-  { method: "POST", pathname: "/engram/v1/wearables/sync", operation: null },
-  { method: "GET", pathname: "/engram/v1/wearables/transcript", operation: null },
-  { method: "GET", pathname: "/engram/v1/wearables/transcripts/search", operation: null },
-  { method: "GET", pathname: "/engram/v1/wearables/memories", operation: null },
-  { method: "POST", pathname: "/engram/v1/observe", operation: null },
-  { method: "POST", pathname: "/engram/v1/lcm/search", operation: null },
-  { method: "POST", pathname: "/engram/v1/lcm/compaction/flush", operation: null },
-  { method: "POST", pathname: "/engram/v1/lcm/compaction/record", operation: null },
-  { method: "GET", pathname: "/engram/v1/lcm/status", operation: null },
+  { method: "POST", pathname: "/engram/v1/recall", operation: "recall" },
+  { method: "POST", pathname: "/engram/v1/coding-context", operation: "set_coding_context" },
+  { method: "POST", pathname: "/engram/v1/capsules/export", operation: "capsule_export" },
+  { method: "POST", pathname: "/engram/v1/capsules/import", operation: "capsule_import" },
+  { method: "GET", pathname: "/engram/v1/offline-sync/snapshot", operation: "offline_sync_snapshot" },
+    { method: "POST", pathname: "/engram/v1/offline-sync/snapshot", operation: "offline_sync_snapshot" },
+  { method: "POST", pathname: "/engram/v1/offline-sync/files", operation: "offline_sync_files" },
+  { method: "POST", pathname: "/engram/v1/offline-sync/file-content", operation: "offline_sync_file_content" },
+  { method: "POST", pathname: "/engram/v1/offline-sync/apply-file-content", operation: "offline_sync_apply_file_content" },
+  { method: "POST", pathname: "/engram/v1/offline-sync/apply", operation: "offline_sync_apply" },
+  { method: "POST", pathname: "/engram/v1/recall/explain", operation: "recall_explain" },
+  { method: "POST", pathname: "/engram/v1/action-confidence", operation: "action_confidence" },
+  { method: "GET", pathname: "/engram/v1/recall/tier-explain", operation: "recall_tier_explain" },
+  { method: "GET", pathname: "/engram/v1/recall/xray", operation: "recall_xray" },
+  { method: "GET", pathname: "/engram/v1/wearables/status", operation: "wearables_status" },
+  { method: "POST", pathname: "/engram/v1/wearables/sync", operation: "wearables_sync" },
+  { method: "GET", pathname: "/engram/v1/wearables/transcript", operation: "transcript_day" },
+  { method: "GET", pathname: "/engram/v1/wearables/transcripts/search", operation: "transcript_search" },
+  { method: "GET", pathname: "/engram/v1/wearables/memories", operation: "transcript_memories" },
+  { method: "POST", pathname: "/engram/v1/observe", operation: "observe" },
+  { method: "POST", pathname: "/engram/v1/lcm/search", operation: "lcm_search" },
+  { method: "POST", pathname: "/engram/v1/lcm/compaction/flush", operation: "lcm_compaction_flush" },
+  { method: "POST", pathname: "/engram/v1/lcm/compaction/record", operation: "lcm_compaction_record" },
+  { method: "GET", pathname: "/engram/v1/lcm/status", operation: "lcm_status" },
   { method: "POST", pathname: "/engram/v1/memories", operation: "memory_store" },
   { method: "POST", pathname: "/engram/v1/coding/decisions", operation: "coding_decision" },
   { method: "POST", pathname: "/engram/v1/coding/architecture", operation: "coding_architecture" },
   { method: "POST", pathname: "/engram/v1/coding/delta", operation: "coding_delta" },
-  { method: "POST", pathname: "/engram/v1/suggestions", operation: null },
-  { method: "GET", pathname: "/engram/v1/memories", operation: null },
+  { method: "POST", pathname: "/engram/v1/suggestions", operation: "suggestion_submit" },
+  { method: "GET", pathname: "/engram/v1/memories", operation: "memory_list" },
   { method: "GET", pathname: "/engram/v1/memories/:id", operation: "memory_get" },
-  { method: "GET", pathname: "/engram/v1/memories/:id/timeline", operation: null },
-  { method: "GET", pathname: "/engram/v1/entities", operation: null },
-  { method: "GET", pathname: "/engram/v1/entities/:id", operation: null },
-  { method: "GET", pathname: "/engram/v1/review-queue", operation: null },
-  { method: "GET", pathname: "/engram/v1/maintenance", operation: null },
-  { method: "GET", pathname: "/engram/v1/quality", operation: null },
-  { method: "GET", pathname: "/engram/v1/trust-zones/status", operation: null },
-  { method: "GET", pathname: "/engram/v1/procedural/stats", operation: null },
-  { method: "GET", pathname: "/engram/v1/trust-zones/records", operation: null },
-  { method: "POST", pathname: "/engram/v1/review-disposition", operation: null },
-  { method: "POST", pathname: "/engram/v1/trust-zones/promote", operation: null },
-  { method: "POST", pathname: "/engram/v1/trust-zones/demo-seed", operation: null },
-  { method: "POST", pathname: "/v1/citations/observed", operation: null },
-  { method: "GET", pathname: "/engram/v1/review/contradictions", operation: null },
-  { method: "GET", pathname: "/engram/v1/review/contradictions/:id", operation: null },
-  { method: "POST", pathname: "/engram/v1/review/resolve", operation: null },
-  { method: "GET", pathname: "/engram/v1/graph/snapshot", operation: null },
-  { method: "POST", pathname: "/engram/v1/contradiction-scan", operation: null },
-  { method: "GET", pathname: "/engram/v1/graph/events", operation: null },
-  { method: "GET", pathname: "/engram/v1/console/state", operation: null },
-  { method: "GET", pathname: "/engram/v1/peers", operation: null },
-  { method: "GET", pathname: "/engram/v1/peers/:id/profile", operation: null },
-  { method: "GET", pathname: "/engram/v1/peers/:id", operation: null },
-  { method: "PUT", pathname: "/engram/v1/peers/:id", operation: null },
-  { method: "DELETE", pathname: "/engram/v1/peers/:id", operation: null },
-  { method: "GET", pathname: "/engram/v1/dreams/status", operation: null },
-  { method: "POST", pathname: "/engram/v1/dreams/run", operation: null },
+  { method: "GET", pathname: "/engram/v1/memories/:id/timeline", operation: "memory_timeline" },
+  { method: "GET", pathname: "/engram/v1/entities", operation: "entity_list" },
+  { method: "GET", pathname: "/engram/v1/entities/:id", operation: "entity_get" },
+  { method: "GET", pathname: "/engram/v1/review-queue", operation: "review_queue_list" },
+  { method: "GET", pathname: "/engram/v1/maintenance", operation: "maintenance_status" },
+  { method: "GET", pathname: "/engram/v1/quality", operation: "quality_status" },
+  { method: "GET", pathname: "/engram/v1/trust-zones/status", operation: "trust_zones_status" },
+  { method: "GET", pathname: "/engram/v1/procedural/stats", operation: "procedural_stats" },
+  { method: "GET", pathname: "/engram/v1/trust-zones/records", operation: "trust_zones_records" },
+  { method: "POST", pathname: "/engram/v1/review-disposition", operation: "review_disposition" },
+  { method: "POST", pathname: "/engram/v1/trust-zones/promote", operation: "trust_zones_promote" },
+  { method: "POST", pathname: "/engram/v1/trust-zones/demo-seed", operation: "trust_zones_demo_seed" },
+  { method: "POST", pathname: "/v1/citations/observed", operation: "citations_observed" },
+  { method: "GET", pathname: "/engram/v1/review/contradictions", operation: "review_list" },
+  { method: "GET", pathname: "/engram/v1/review/contradictions/:id", operation: "contradiction_detail" },
+  { method: "POST", pathname: "/engram/v1/review/resolve", operation: "review_resolve" },
+  { method: "GET", pathname: "/engram/v1/graph/snapshot", operation: "graph_snapshot" },
+  { method: "POST", pathname: "/engram/v1/contradiction-scan", operation: "contradiction_scan_run" },
+    { method: "GET", pathname: "/engram/v1/console/state", operation: "console_state" },
+  { method: "GET", pathname: "/engram/v1/peers", operation: "peer_list" },
+  { method: "GET", pathname: "/engram/v1/peers/:id/profile", operation: "peer_profile_get" },
+  { method: "GET", pathname: "/engram/v1/peers/:id", operation: "peer_get" },
+  { method: "PUT", pathname: "/engram/v1/peers/:id", operation: "peer_set" },
+  { method: "DELETE", pathname: "/engram/v1/peers/:id", operation: "peer_delete" },
+  { method: "GET", pathname: "/engram/v1/dreams/status", operation: "dreams_status" },
+  { method: "POST", pathname: "/engram/v1/dreams/run", operation: "dreams_run" },
+  // SSE-only endpoints: carried in the catalog for completeness tracking.
+  // The operation registration makes them visible to the boundary; the
+  // streaming lifecycle is owned by the HTTP transport (handleGraphEventsSSE).
+  { method: "GET", pathname: "/engram/v1/offline-sync/snapshot-stream", operation: "offline_sync_snapshot_stream" },
+  { method: "GET", pathname: "/engram/v1/graph/events", operation: "graph_events" },
 ];
 
 /**

package/src/cli/creation-ledger-commands.ts

@@ -0,0 +1,346 @@
+/**
+ * Creation-memory ledger command group — extracted from cli.ts (#1532 Phase B).
+ *
+ * Ten creation-memory ledger commands — thin wrappers over exported
+ * runXxxCliCommand helpers across three ledgers:
+ *   - resume-bundle (status / record / build)
+ *   - commitment    (status / record / set-state / lifecycle)
+ *   - work-product  (status / record / recall-search)
+ *
+ * Behaviour is identical to the inline registration it replaces — the
+ * cli-command-surface contract tests guard against silent drift.
+ *
+ * Circular import note: same safe pattern as research-status-commands.ts —
+ * the runXxx helpers are referenced only inside action callbacks invoked at
+ * runtime, never at module-eval time.
+ */
+
+import type { Orchestrator } from "../orchestrator.js";
+import type { CliCommand } from "../cli.js";
+import type { CommitmentLedgerEntry } from "../commitment-ledger.js";
+import type { WorkProductLedgerEntry } from "../work-product-ledger.js";
+import type { ResumeBundle } from "../resume-bundles.js";
+import {
+  runResumeBundleStatusCliCommand,
+  runResumeBundleRecordCliCommand,
+  runResumeBundleBuildCliCommand,
+  runCommitmentStatusCliCommand,
+  runCommitmentRecordCliCommand,
+  runCommitmentSetStateCliCommand,
+  runCommitmentLifecycleCliCommand,
+  runWorkProductStatusCliCommand,
+  runWorkProductRecordCliCommand,
+  runWorkProductRecallSearchCliCommand,
+} from "../cli.js";
+
+/**
+ * Register the creation-memory ledger command group on the parent `engram`
+ * command. Extracted verbatim from registerCli; behaviour-preserving.
+ */
+export function registerCreationLedgerCommands(
+  cmd: CliCommand,
+  orchestrator: Orchestrator,
+): void {
+cmd
+  .command("resume-bundle-status")
+  .description("Show resume bundle status, bundle counts, and the latest recorded handoff bundle")
+  .action(async () => {
+    const status = await runResumeBundleStatusCliCommand({
+      memoryDir: orchestrator.config.memoryDir,
+      resumeBundleDir: orchestrator.config.resumeBundleDir,
+      creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+      resumeBundlesEnabled: orchestrator.config.resumeBundlesEnabled,
+    });
+    console.log(JSON.stringify(status, null, 2));
+    console.log("OK");
+  });
+
+cmd
+  .command("resume-bundle-record")
+  .description("Record an explicit resume bundle when creation-memory handoff bundles are enabled")
+  .requiredOption("--bundle-id <bundleId>", "Resume bundle id")
+  .requiredOption("--recorded-at <recordedAt>", "ISO timestamp for the bundle")
+  .requiredOption("--session-key <sessionKey>", "Session key that owns the bundle")
+  .requiredOption("--source <source>", "Bundle source (tool_result|cli|system|manual)")
+  .requiredOption("--scope <scope>", "Primary scope or recovery domain for the bundle")
+  .requiredOption("--summary <summary>", "Human-readable summary of what this bundle preserves")
+  .option("--key-fact <keyFact...>", "Short facts that a resumed agent should retain")
+  .option("--next-action <nextAction...>", "Explicit next actions for the resumed agent")
+  .option("--risk-flag <riskFlag...>", "Open risks or cautions attached to the bundle")
+  .option(
+    "--objective-state-snapshot-ref <objectiveStateSnapshotRef...>",
+    "Objective-state snapshot refs attached to the bundle",
+  )
+  .option(
+    "--work-product-entry-ref <workProductEntryRef...>",
+    "Work-product ledger refs attached to the bundle",
+  )
+  .option(
+    "--commitment-entry-ref <commitmentEntryRef...>",
+    "Commitment ledger refs attached to the bundle",
+  )
+  .action(async (...args: unknown[]) => {
+    const options = (args[0] ?? {}) as Record<string, unknown>;
+    const filePath = await runResumeBundleRecordCliCommand({
+      memoryDir: orchestrator.config.memoryDir,
+      resumeBundleDir: orchestrator.config.resumeBundleDir,
+      creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+      resumeBundlesEnabled: orchestrator.config.resumeBundlesEnabled,
+      bundle: {
+        schemaVersion: 1,
+        bundleId: String(options.bundleId ?? ""),
+        recordedAt: String(options.recordedAt ?? ""),
+        sessionKey: String(options.sessionKey ?? ""),
+        source: String(options.source ?? "") as ResumeBundle["source"],
+        scope: String(options.scope ?? ""),
+        summary: String(options.summary ?? ""),
+        keyFacts: Array.isArray(options.keyFact) ? options.keyFact.map(String) : undefined,
+        nextActions: Array.isArray(options.nextAction) ? options.nextAction.map(String) : undefined,
+        riskFlags: Array.isArray(options.riskFlag) ? options.riskFlag.map(String) : undefined,
+        objectiveStateSnapshotRefs: Array.isArray(options.objectiveStateSnapshotRef)
+          ? options.objectiveStateSnapshotRef.map(String)
+          : undefined,
+        workProductEntryRefs: Array.isArray(options.workProductEntryRef)
+          ? options.workProductEntryRef.map(String)
+          : undefined,
+        commitmentEntryRefs: Array.isArray(options.commitmentEntryRef)
+          ? options.commitmentEntryRef.map(String)
+          : undefined,
+      },
+    });
+    console.log(JSON.stringify({ wrote: filePath !== null, filePath }, null, 2));
+    console.log("OK");
+  });
+
+cmd
+  .command("resume-bundle-build")
+  .description("Build and persist a resume bundle from transcript recovery, objective state, work products, and open commitments")
+  .requiredOption("--bundle-id <bundleId>", "Resume bundle id")
+  .requiredOption("--recorded-at <recordedAt>", "ISO timestamp for the bundle")
+  .requiredOption("--session-key <sessionKey>", "Session key that owns the bundle")
+  .requiredOption("--scope <scope>", "Primary scope or recovery domain for the bundle")
+  .action(async (...args: unknown[]) => {
+    const options = (args[0] ?? {}) as Record<string, unknown>;
+    const built = await runResumeBundleBuildCliCommand({
+      memoryDir: orchestrator.config.memoryDir,
+      resumeBundleDir: orchestrator.config.resumeBundleDir,
+      objectiveStateStoreDir: orchestrator.config.objectiveStateStoreDir,
+      workProductLedgerDir: orchestrator.config.workProductLedgerDir,
+      commitmentLedgerDir: orchestrator.config.commitmentLedgerDir,
+      creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+      resumeBundlesEnabled: orchestrator.config.resumeBundlesEnabled,
+      transcriptEnabled: orchestrator.config.transcriptEnabled,
+      objectiveStateMemoryEnabled: orchestrator.config.objectiveStateMemoryEnabled,
+      commitmentLedgerEnabled: orchestrator.config.commitmentLedgerEnabled,
+      bundleId: String(options.bundleId ?? ""),
+      recordedAt: String(options.recordedAt ?? ""),
+      sessionKey: String(options.sessionKey ?? ""),
+      scope: String(options.scope ?? ""),
+    });
+    console.log(JSON.stringify({
+      wrote: built !== null,
+      filePath: built?.filePath ?? null,
+      bundle: built?.bundle ?? null,
+    }, null, 2));
+    console.log("OK");
+  });
+
+cmd
+  .command("commitment-status")
+  .description("Show commitment ledger status, entry counts, and the latest recorded commitment")
+  .action(async () => {
+    const status = await runCommitmentStatusCliCommand({
+      memoryDir: orchestrator.config.memoryDir,
+      commitmentLedgerDir: orchestrator.config.commitmentLedgerDir,
+      creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+      commitmentLedgerEnabled: orchestrator.config.commitmentLedgerEnabled,
+      commitmentLifecycleEnabled: orchestrator.config.commitmentLifecycleEnabled,
+      commitmentStaleDays: orchestrator.config.commitmentStaleDays,
+      commitmentDecayDays: orchestrator.config.commitmentDecayDays,
+    });
+    console.log(JSON.stringify(status, null, 2));
+    console.log("OK");
+  });
+
+cmd
+  .command("commitment-record")
+  .description("Record a commitment ledger entry when commitment memory is enabled")
+  .requiredOption("--entry-id <entryId>", "Commitment entry id")
+  .requiredOption("--recorded-at <recordedAt>", "ISO timestamp for the entry")
+  .requiredOption("--session-key <sessionKey>", "Session key that owns the commitment")
+  .requiredOption("--source <source>", "Entry source (tool_result|cli|system|manual)")
+  .requiredOption("--kind <kind>", "Entry kind (promise|follow_up|deadline|deliverable)")
+  .requiredOption("--state <state>", "Entry state (open|fulfilled|cancelled|expired)")
+  .requiredOption("--scope <scope>", "Primary scope or identifier for the commitment")
+  .requiredOption("--summary <summary>", "Human-readable summary of the commitment")
+  .option("--due-at <dueAt>", "Optional due timestamp for the commitment")
+  .option("--tag <tag...>", "Tags to attach to the commitment entry")
+  .option("--entity-ref <entityRef...>", "Entity refs to attach to the commitment entry")
+  .option(
+    "--work-product-entry-ref <workProductEntryRef...>",
+    "Work-product ledger refs that this commitment depends on",
+  )
+  .option(
+    "--objective-state-snapshot-ref <objectiveStateSnapshotRef...>",
+    "Objective-state snapshot refs to link to this commitment",
+  )
+  .action(async (...args: unknown[]) => {
+    const options = (args[0] ?? {}) as Record<string, unknown>;
+    const filePath = await runCommitmentRecordCliCommand({
+      memoryDir: orchestrator.config.memoryDir,
+      commitmentLedgerDir: orchestrator.config.commitmentLedgerDir,
+      creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+      commitmentLedgerEnabled: orchestrator.config.commitmentLedgerEnabled,
+      entry: {
+        schemaVersion: 1,
+        entryId: String(options.entryId ?? ""),
+        recordedAt: String(options.recordedAt ?? ""),
+        sessionKey: String(options.sessionKey ?? ""),
+        source: String(options.source ?? "") as CommitmentLedgerEntry["source"],
+        kind: String(options.kind ?? "") as CommitmentLedgerEntry["kind"],
+        state: String(options.state ?? "") as CommitmentLedgerEntry["state"],
+        scope: String(options.scope ?? ""),
+        summary: String(options.summary ?? ""),
+        dueAt: typeof options.dueAt === "string" ? options.dueAt : undefined,
+        tags: Array.isArray(options.tag) ? options.tag.map(String) : undefined,
+        entityRefs: Array.isArray(options.entityRef) ? options.entityRef.map(String) : undefined,
+        workProductEntryRefs: Array.isArray(options.workProductEntryRef)
+          ? options.workProductEntryRef.map(String)
+          : undefined,
+        objectiveStateSnapshotRefs: Array.isArray(options.objectiveStateSnapshotRef)
+          ? options.objectiveStateSnapshotRef.map(String)
+          : undefined,
+      },
+    });
+    console.log(JSON.stringify({ wrote: filePath !== null, filePath }, null, 2));
+    console.log("OK");
+  });
+
+cmd
+  .command("commitment-set-state")
+  .description("Transition an existing commitment ledger entry when commitment lifecycle is enabled")
+  .requiredOption("--entry-id <entryId>", "Commitment entry id")
+  .requiredOption("--state <state>", "Next state (open|fulfilled|cancelled|expired)")
+  .requiredOption("--changed-at <changedAt>", "ISO timestamp for the lifecycle transition")
+  .action(async (...args: unknown[]) => {
+    const options = (args[0] ?? {}) as Record<string, unknown>;
+    const entry = await runCommitmentSetStateCliCommand({
+      memoryDir: orchestrator.config.memoryDir,
+      commitmentLedgerDir: orchestrator.config.commitmentLedgerDir,
+      creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+      commitmentLedgerEnabled: orchestrator.config.commitmentLedgerEnabled,
+      commitmentLifecycleEnabled: orchestrator.config.commitmentLifecycleEnabled,
+      entryId: String(options.entryId ?? ""),
+      nextState: String(options.state ?? "") as CommitmentLedgerEntry["state"],
+      changedAt: String(options.changedAt ?? ""),
+    });
+    console.log(JSON.stringify({ updated: entry !== null, entry }, null, 2));
+    console.log("OK");
+  });
+
+cmd
+  .command("commitment-lifecycle-run")
+  .description("Apply overdue-expiry and resolved-entry cleanup to the commitment ledger")
+  .option("--now <now>", "Override the lifecycle timestamp for testing or backfills")
+  .action(async (...args: unknown[]) => {
+    const options = (args[0] ?? {}) as Record<string, unknown>;
+    const result = await runCommitmentLifecycleCliCommand({
+      memoryDir: orchestrator.config.memoryDir,
+      commitmentLedgerDir: orchestrator.config.commitmentLedgerDir,
+      creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+      commitmentLedgerEnabled: orchestrator.config.commitmentLedgerEnabled,
+      commitmentLifecycleEnabled: orchestrator.config.commitmentLifecycleEnabled,
+      commitmentDecayDays: orchestrator.config.commitmentDecayDays,
+      now: typeof options.now === "string" ? options.now : undefined,
+    });
+    console.log(JSON.stringify({ applied: result !== null, result }, null, 2));
+    console.log("OK");
+  });
+
+cmd
+  .command("work-product-status")
+  .description("Show work-product ledger status, entry counts, and the latest recorded work product")
+  .action(async () => {
+    const status = await runWorkProductStatusCliCommand({
+      memoryDir: orchestrator.config.memoryDir,
+      workProductLedgerDir: orchestrator.config.workProductLedgerDir,
+      creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+    });
+    console.log(JSON.stringify(status, null, 2));
+    console.log("OK");
+  });
+
+cmd
+  .command("work-product-record")
+  .description("Record a work-product ledger entry when creation-memory is enabled")
+  .requiredOption("--entry-id <entryId>", "Ledger entry id")
+  .requiredOption("--recorded-at <recordedAt>", "ISO timestamp for the entry")
+  .requiredOption("--session-key <sessionKey>", "Session key that created the work product")
+  .requiredOption("--source <source>", "Entry source (tool_result|cli|system|manual)")
+  .requiredOption("--kind <kind>", "Entry kind (artifact|file|record|report|workspace)")
+  .requiredOption(
+    "--entry-action <entryAction>",
+    "Entry action (created|updated|deleted|referenced|published)",
+  )
+  .requiredOption("--scope <scope>", "Primary scope or identifier for the created work product")
+  .requiredOption("--summary <summary>", "Human-readable summary of the work product")
+  .option("--artifact-path <artifactPath>", "Optional path to the created artifact")
+  .option("--tag <tag...>", "Tags to attach to the work-product entry")
+  .option("--entity-ref <entityRef...>", "Entity refs to attach to the work-product entry")
+  .option(
+    "--objective-state-snapshot-ref <objectiveStateSnapshotRef...>",
+    "Objective-state snapshot refs to link to this work product",
+  )
+  .action(async (...args: unknown[]) => {
+    const options = (args[0] ?? {}) as Record<string, unknown>;
+    const filePath = await runWorkProductRecordCliCommand({
+      memoryDir: orchestrator.config.memoryDir,
+      workProductLedgerDir: orchestrator.config.workProductLedgerDir,
+      creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+      entry: {
+        schemaVersion: 1,
+        entryId: String(options.entryId ?? ""),
+        recordedAt: String(options.recordedAt ?? ""),
+        sessionKey: String(options.sessionKey ?? ""),
+        source: String(options.source ?? "") as WorkProductLedgerEntry["source"],
+        kind: String(options.kind ?? "") as WorkProductLedgerEntry["kind"],
+        action: String(options.entryAction ?? "") as WorkProductLedgerEntry["action"],
+        scope: String(options.scope ?? ""),
+        summary: String(options.summary ?? ""),
+        artifactPath: typeof options.artifactPath === "string" ? options.artifactPath : undefined,
+        tags: Array.isArray(options.tag) ? options.tag.map(String) : undefined,
+        entityRefs: Array.isArray(options.entityRef) ? options.entityRef.map(String) : undefined,
+        objectiveStateSnapshotRefs: Array.isArray(options.objectiveStateSnapshotRef)
+          ? options.objectiveStateSnapshotRef.map(String)
+          : undefined,
+      },
+    });
+    console.log(JSON.stringify({ wrote: filePath !== null, filePath }, null, 2));
+    console.log("OK");
+  });
+
+cmd
+  .command("work-product-recall-search")
+  .description("Preview work-product recovery candidates when creation-memory recall is enabled")
+  .argument("<query>", "Prompt-like query to evaluate against the work-product ledger")
+  .option("--max-results <count>", "Maximum number of work-product results to return", "3")
+  .option("--session-key <sessionKey>", "Optional session key to boost same-session work products")
+  .action(async (...args: unknown[]) => {
+    const query = typeof args[0] === "string" ? args[0] : "";
+    const options = (args[1] ?? {}) as Record<string, unknown>;
+    const maxResults = typeof options.maxResults === "string"
+      ? Number.parseInt(options.maxResults, 10)
+      : 3;
+    const results = await runWorkProductRecallSearchCliCommand({
+      memoryDir: orchestrator.config.memoryDir,
+      workProductLedgerDir: orchestrator.config.workProductLedgerDir,
+      creationMemoryEnabled: orchestrator.config.creationMemoryEnabled,
+      workProductRecallEnabled: orchestrator.config.workProductRecallEnabled,
+      query,
+      maxResults: Number.isFinite(maxResults) ? maxResults : 3,
+      sessionKey: typeof options.sessionKey === "string" ? options.sessionKey : undefined,
+    });
+    console.log(JSON.stringify(results, null, 2));
+    console.log("OK");
+  });
+}