@smartmemory/compose 0.3.6-beta → 0.3.8

package/server/index.js

@@ -3,16 +3,10 @@ import cors from 'cors';
 import http from 'node:http';
 import path from 'node:path';
 import { existsSync, statSync, readFileSync } from 'node:fs';
-import { FileWatcherServer } from './file-watcher.js';
-import { VisionStore } from './vision-store.js';
-import { VisionServer } from './vision-server.js';
-import { SessionManager } from './session-manager.js';
-import { scanFeatures, seedFeatures, scanSubPackages, seedSubPackages } from './feature-scan.js';
-import { attachGraphExportRoutes } from './graph-export.js';
+import { WorkspaceRuntime } from './workspace-runtime.js';
 import { attachWorkspaceRoutes } from './workspace-routes.js';
-import { attachGraphLayoutRoutes } from './graph-layout-routes.js';
 import { createWorkspaceMiddleware } from './workspace-middleware.js';
-import { getTargetRoot, getDataDir, ensureDataDir, loadProjectConfig, resolveProjectPath, switchProject, COMPOSE_HOME } from './project-root.js';
+import { getTargetRoot, getDataDir, ensureDataDir, loadProjectConfig, withProjectContext, COMPOSE_HOME } from './project-root.js';
 import { resolveStratumEngine } from './stratum-client.js';
 import { probeStratumBin, resolveStratumBin } from '../lib/stratum-engine.js';
 import { createAuthStore } from './auth-store.js';
@@ -64,21 +58,44 @@ if (projectConfig.capabilities.stratum) {
 }
 
 // Handle unexpected errors — fatal startup errors exit (supervisor retries),
-// runtime errors keep the process alive to preserve PTY sessions
+// runtime errors keep the process alive to preserve PTY sessions.
+//
+// stdio death is fatal by design: when the parent process dies, stdout/stderr
+// become dead sockets and every console.* write throws EPIPE. Logging from the
+// uncaughtException handler then throws again, which re-enters the handler via
+// the stream's error emission — an infinite setImmediate loop pinning a core
+// (observed 2026-09-01: 2 days at 100% CPU as an orphan). So: stream errors on
+// stdio exit immediately, and every log in an error/signal path is guarded.
+const isDeadStdio = (err) =>
+  err && (err.code === 'EPIPE' || err.code === 'ERR_STREAM_DESTROYED' || err.code === 'ERR_STREAM_WRITE_AFTER_END');
+const safeLog = (...args) => {
+  try {
+    console.error(...args);
+  } catch {
+    process.exit(0); // stdio is gone — parent died, nothing left to serve logs to
+  }
+};
+process.stdout.on('error', (err) => {
+  if (isDeadStdio(err)) process.exit(0);
+});
+process.stderr.on('error', (err) => {
+  if (isDeadStdio(err)) process.exit(0);
+});
 let serverListening = false;
 process.on('uncaughtException', (err) => {
+  if (isDeadStdio(err)) process.exit(0);
   if (!serverListening && err.code === 'EADDRINUSE') {
-    console.error(`[compose] Port in use, exiting for supervisor retry: ${err.message}`);
+    safeLog(`[compose] Port in use, exiting for supervisor retry: ${err.message}`);
     process.exit(1);
   }
-  console.error('[compose] Uncaught exception (process kept alive):', err.message);
-  console.error(err.stack);
+  safeLog('[compose] Uncaught exception (process kept alive):', err.message);
+  safeLog(err.stack);
 });
 process.on('unhandledRejection', (reason) => {
-  console.error('[compose] Unhandled rejection (process kept alive):', reason);
+  safeLog('[compose] Unhandled rejection (process kept alive):', reason);
 });
 process.on('SIGTERM', () => {
-  console.log('[compose] SIGTERM received, shutting down gracefully');
+  safeLog('[compose] SIGTERM received, shutting down gracefully');
   process.exit(0);
 });
 
@@ -141,23 +158,21 @@ attachAuthRoutes(app, {
     } catch { return null; }
   },
   broadcast: (msg) => {
-    if (typeof visionServer?.broadcastMessage === 'function') {
-      visionServer.broadcastMessage(msg);
+    if (typeof workspaces?.active?.visionServer?.broadcastMessage === 'function') {
+      activeVision().broadcastMessage(msg);
     }
   },
   requireSensitive: requireSensitiveToken,
 });
 
 // ---------------------------------------------------------------------------
-// Agent proxy (BOTH modes — additive) — mounted after the gate so gate clears
-// requests first. Proxy injects the real sensitive token server-side.
+// Each workspace installs its agent proxy after workspace resolution. The
+// proxy stamps the selected root and sensitive token for the SDK process.
 // ---------------------------------------------------------------------------
 const _agentPort = parseInt(process.env.AGENT_PORT || '4002', 10);
-attachAgentProxy(app, { agentPort: _agentPort });
 
 attachWorkspaceRoutes(app);
-attachGraphLayoutRoutes(app);
-app.use(createWorkspaceMiddleware());
+app.use(createWorkspaceMiddleware({ resolveKnownWorkspace: (id) => workspaces.resolveKnownWorkspace(id) }));
 
 // `remote` lets clients (desktop cockpit served through a tunnel) detect
 // remote mode at boot and switch their WS/SSE URLs to token-carrying form.
@@ -174,81 +189,27 @@ app.get('/api/project', (_req, res) => {
   });
 });
 
+const server = http.createServer(app);
+const workspaces = new WorkspaceRuntime(server, { agentPort: _agentPort });
+try { workspaces.switch(getTargetRoot(), projectConfig); }
+catch (err) {
+  console.error(`[compose] Workspace startup failed: ${err.message}`);
+  process.exit(1);
+}
+
+// Accessors always select the current context; old requests retain their own router.
+const activeVision = () => workspaces.active.visionServer;
 app.post('/api/project/switch', (req, res) => {
   const { path: projectPath } = req.body || {};
-  if (!projectPath) return res.status(400).json({ error: 'path is required' });
+  if (typeof projectPath !== 'string' || !projectPath) return res.status(400).json({ error: 'path is required' });
   try {
-    const result = switchProject(projectPath);
-    ensureDataDir();
-    // Reload store from new data directory
-    visionStore.reloadFrom(result.dataDir);
-    // Re-scan features and sub-packages from new project
-    try {
-      const features = scanFeatures();
-      if (features.length > 0) seedFeatures(features, visionStore);
-      const packages = scanSubPackages();
-      if (packages.length > 0) seedSubPackages(packages, visionStore);
-    } catch (err) {
-      console.error('[compose] Feature scan after switch:', err.message);
-    }
-    // Broadcast new state to all connected clients
-    visionServer.scheduleBroadcast();
-    res.json({ ok: true, targetRoot: result.targetRoot, name: path.basename(result.targetRoot) });
+    const { binding } = workspaces.switch(projectPath);
+    res.json({ ok: true, targetRoot: binding.targetRoot, name: path.basename(binding.targetRoot) });
   } catch (err) {
     res.status(400).json({ error: err.message });
   }
 });
-
-const server = http.createServer(app);
-const fileWatcher = new FileWatcherServer();
-fileWatcher.attach(server, app);
-
-const visionStore = new VisionStore(getDataDir());
-const sessionManager = new SessionManager({
-  getFeaturePhase: (featureCode) => {
-    const item = visionStore.getItemByFeatureCode(featureCode);
-    return item?.lifecycle?.currentPhase || null;
-  },
-  featureRoot: resolveProjectPath('features'),
-});
-const visionServer = new VisionServer(visionStore, sessionManager, { config: projectConfig });
-visionServer.attach(server, app);
-
-// Seed feature folders and sub-packages into vision store on startup
-try {
-  const features = scanFeatures();
-  if (features.length > 0) seedFeatures(features, visionStore);
-  const packages = scanSubPackages();
-  if (packages.length > 0) seedSubPackages(packages, visionStore);
-} catch (err) {
-  console.error('[compose] Feature scan startup error:', err.message);
-}
-
-// Wire feature folder changes → auto-reseed vision store
-fileWatcher.onFeatureChanged = (_relativePath) => {
-  try {
-    const features = scanFeatures();
-    seedFeatures(features, visionStore);
-    visionServer.scheduleBroadcast();
-  } catch (err) {
-    console.error('[compose] Feature reseed error:', err.message);
-  }
-};
-
-// Wire build state changes → broadcast over /ws/vision
-fileWatcher.onBuildStateChanged = (state) => {
-  if (state) {
-    // Broadcast flat payload per STRAT-COMP-4 contract
-    visionServer.broadcastMessage({ type: 'buildState', ...state });
-  }
-};
-
-// Wire pipelines/*.stratum.yaml external changes → broadcast `specChanged` on
-// the VISION WS (COMP-PIPE-EDIT-6 — the channel the pipeline editor store uses,
-// not /ws/files). The message already carries { type:'specChanged', file, path }.
-fileWatcher.onSpecChanged = (message) => {
-  visionServer.broadcastMessage(message);
-};
+app.use((req, res, next) => workspaces.handle(req, res, next));
 
 // ---------------------------------------------------------------------------
 // Static serving + SPA fallback (BOTH modes — additive)
@@ -282,18 +243,27 @@ server.on('upgrade', (req, socket, head) => {
     return;
   }
 
-  const { pathname } = new URL(req.url, 'http://localhost');
-  if (pathname === '/ws/files' && fileWatcher.wss) {
-    fileWatcher.wss.handleUpgrade(req, socket, head, (ws) => {
-      fileWatcher.wss.emit('connection', ws, req);
-    });
-  } else if (pathname === '/ws/vision' && visionServer.wss) {
-    visionServer.wss.handleUpgrade(req, socket, head, (ws) => {
-      visionServer.wss.emit('connection', ws, req);
-    });
-  } else {
-    socket.destroy();
+  const url = new URL(req.url, 'http://localhost');
+  const workspaceId = req.headers['x-compose-workspace-id'] || url.searchParams.get('workspaceId');
+  let context = workspaces.active;
+  if (workspaceId) {
+    try {
+      const resolved = workspaces.resolveKnownWorkspace(workspaceId);
+      context = resolved && workspaces.get(resolved.root);
+    } catch { context = null; }
+    if (!context) {
+      socket.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+      socket.destroy();
+      return;
+    }
   }
+  const { fileWatcher, visionServer } = context;
+  const wss = url.pathname === '/ws/files' ? fileWatcher.wss
+    : url.pathname === '/ws/vision' ? visionServer.wss : null;
+  if (!wss) { socket.destroy(); return; }
+  withProjectContext(context.binding, () => {
+    wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
+  });
 });
 
 server.listen(PORT, _host, () => {

package/server/lifecycle-guard.js

@@ -14,12 +14,20 @@
 
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { spawnSync } from 'node:child_process';
+import { execFile, spawnSync } from 'node:child_process';
 import path from 'node:path';
+import { promisify } from 'node:util';
+
+import { descriptorIdFor, deriveBackfillPolicy, ensureSignedDescriptors } from '../lib/guard-descriptors.js';
+import { acquireDirLock } from '../lib/dir-lock.js';
+import { custodySign, DESCRIPTOR_LOCK_TIMEOUT_MS, HINT_APPROVE } from '../lib/guard-custody.js';
 
 import {
   guardRegister as _guardRegister,
   guardTransition as _guardTransition,
+  guardPolicy as _guardPolicy,
+  guardApplyUpgrade as _guardApplyUpgrade,
+  guardDescriptors as _guardDescriptors,
 } from './stratum-client.js';
 import { setFeatureStatus as _setFeatureStatus } from '../lib/feature-writer.js';
 import {
@@ -31,6 +39,8 @@ import {
   edgeEvidenceOf,
 } from '../lib/lifecycle-modes.js';
 
+const execFileAsync = promisify(execFile);
+
 // ---------------------------------------------------------------------------
 // Canonical phase graph (compose-owned data — single source of truth)
 // ---------------------------------------------------------------------------
@@ -53,7 +63,12 @@ export const BASE_TRANSITIONS = {
 export const SKIPPABLE = new Set(['prd', 'architecture', 'report']);
 
 /** Terminal phases — no outgoing edges. */
-export const TERMINAL = new Set(['complete', 'killed']);
+export const TERMINAL = new Set(['complete', 'killed', 'complete_backfilled']);
+
+/** Normalise raw stratum and local adapter error envelopes at the boundary. */
+export const isGuardError = (result) => !result || Boolean(result.error) || result.status === 'error';
+export const guardErrorType = (result) => (result && (result.error?.code ?? result.error_type)) ?? null;
+export const guardErrorMessage = (result) => (result && (result.error?.message ?? result.message)) ?? 'no guard response';
 
 /**
  * Assemble the FULL guarded graph the design requires: the forward
@@ -77,6 +92,13 @@ export function buildPhaseGraph(mode = 'build') {
   // separately in vision-routes at /lifecycle/complete, so absent from the mode's
   // forward transitions). For build this is `ship → complete`.
   graph[completable] = [...(graph[completable] || []), 'complete'];
+  // Every non-terminal phase → complete_backfilled. This must precede the
+  // killed loop: stratum fingerprints adjacency arrays in their stored order.
+  for (const s of nodes) {
+    if (terminal.has(s)) continue;
+    graph[s] = graph[s] || [];
+    if (!graph[s].includes('complete_backfilled')) graph[s].push('complete_backfilled');
+  }
   // Every non-terminal phase → killed (vision-routes /lifecycle/kill allows
   // kill from any non-terminal phase, including the completable phase).
   for (const s of nodes) {
@@ -141,6 +163,7 @@ export function resourceId(featureCode, workspaceRoot, mode = 'build') {
  * and stay set_feature_status's domain.
  */
 export function phaseToStatus(phase) {
+  if (phase === 'complete_backfilled') return 'COMPLETE';
   if (phase === 'complete') return 'COMPLETE';
   if (phase === 'killed') return 'KILLED';
   return 'IN_PROGRESS';
@@ -223,20 +246,110 @@ export async function verifyCompletionEvidence({ commitSha, cwd, testCommand, te
   return { ok: reasons.length === 0, reasons, testsAttested };
 }
 
+/**
+ * Async equivalent for backfill completion while a directory lock heartbeat is
+ * active. The synchronous live-completion verifier above remains unchanged.
+ */
+export async function verifyCompletionEvidenceAsync({ commitSha, cwd, testCommand, testsPassClaim }) {
+  const reasons = [];
+
+  if (!commitSha || typeof commitSha !== 'string' || !commitSha.trim()) {
+    reasons.push('commit_sha is required for evidence-bound completion');
+  } else {
+    try {
+      await execFileAsync('git', ['rev-parse', '--verify', '--quiet', `${commitSha.trim()}^{commit}`], { cwd, encoding: 'utf8' });
+    } catch {
+      reasons.push(`commit ${commitSha.trim()} not found in repository (server-read git verification)`);
+    }
+  }
+
+  let testsAttested = false;
+  if (Array.isArray(testCommand) && testCommand.length > 0) {
+    const [bin, ...rest] = testCommand;
+    try {
+      await execFileAsync(bin, rest, { cwd, encoding: 'utf8' });
+      testsAttested = true;
+    } catch (error) {
+      if (error?.code === 'ENOENT') reasons.push(`test command failed to run: ${error.message}`);
+      else reasons.push(`test command exited ${error?.code ?? 'null'} (not 0)`);
+    }
+  } else if (testsPassClaim !== true) {
+    reasons.push('tests_pass must be explicitly true (no configured test command to attest test results)');
+  }
+
+  return { ok: reasons.length === 0, reasons, testsAttested };
+}
+
 // ---------------------------------------------------------------------------
 // Guard client (injectable for tests)
 // ---------------------------------------------------------------------------
 
-let _client = { register: _guardRegister, transition: _guardTransition };
+let _client = {
+  register: _guardRegister,
+  transition: _guardTransition,
+  policy: _guardPolicy,
+  applyUpgrade: _guardApplyUpgrade,
+  descriptors: _guardDescriptors,
+};
 /** @internal test seam */
 export function _testOnly_setGuardClient(c) { _client = c; }
 
+const _custody = { sign: custodySign };
+let _ensureDescriptors = ensureSignedDescriptors;
+/** @internal test seam: real enumeration bypasses the injectable guard client. */
+export function _testOnly_setEnsureDescriptors(ensure) {
+  _ensureDescriptors = ensure ?? ensureSignedDescriptors;
+}
+
 // Per-process registration cache — register is idempotent server-side, but the
 // cache avoids a subprocess per request once a resource is known-registered.
-const _registered = new Set();
+const _registered = new Map();
 /** @internal test seam */
 export function _testOnly_resetGuardCache() { _registered.clear(); }
 
+/** The four and only four fields covered by stratum's policy checksum. */
+export function policyChecksumFields(policy) {
+  return {
+    graph: policy.graph,
+    edge_predicates: policy.edge_predicates,
+    terminal: policy.terminal,
+    stakes: policy.stakes,
+  };
+}
+
+/** Reverse buildPhaseGraph's complete_backfilled additions for legacy comparison. */
+export function legacyPolicyProjection(policy) {
+  const fields = policyChecksumFields(policy);
+  const graph = {};
+  for (const [phase, targets] of Object.entries(fields.graph || {})) {
+    if (phase === 'complete_backfilled') continue;
+    graph[phase] = (targets || []).filter((target) => target !== 'complete_backfilled');
+  }
+  return {
+    graph,
+    edge_predicates: fields.edge_predicates,
+    terminal: (fields.terminal || []).filter((phase) => phase !== 'complete_backfilled'),
+    stakes: fields.stakes,
+  };
+}
+
+function _sortPolicyObject(value) {
+  if (Array.isArray(value)) return value.map(_sortPolicyObject);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, _sortPolicyObject(value[key])]));
+  }
+  return value;
+}
+
+/** Object key order is irrelevant; terminal order is not; adjacency order is. */
+export function policiesEqual(a, b) {
+  const normalise = (policy) => {
+    const fields = policyChecksumFields(policy);
+    return _sortPolicyObject({ ...fields, terminal: [...(fields.terminal || [])].sort() });
+  };
+  return JSON.stringify(normalise(a)) === JSON.stringify(normalise(b));
+}
+
 /**
  * Resolve the feature directory RELATIVE to the served `workspaceRoot` — read
  * from `<workspaceRoot>/.compose/compose.json` (NOT the process-global config,
@@ -298,11 +411,13 @@ export function guardTestCommand(workspaceRoot) {
  */
 export async function ensureGuard(featureCode, currentPhase, workspaceRoot, mode = 'build') {
   const rid = resourceId(featureCode, workspaceRoot, mode);
-  if (_registered.has(rid)) return { guard_id: rid, status: 'cached' };
+  if (_registered.has(rid)) {
+    return { guard_id: rid, status: _registered.get(rid) === 'legacy' ? 'legacy' : 'cached' };
+  }
 
   let res;
   try {
-    res = await _client.register({
+    const newPolicy = {
       resourceId: rid,
       graph: buildPhaseGraph(mode),
       edgePredicates: edgePredicates(_featureRelDir(featureCode, workspaceRoot, mode), mode),
@@ -310,18 +425,123 @@ export async function ensureGuard(featureCode, currentPhase, workspaceRoot, mode
       terminal: terminalOf(mode),
       stakes: {},
       workspaceRoot,
-    });
+    };
+    res = await _client.register(newPolicy);
+    if (guardErrorType(res) === 'guard_already_registered') {
+      const stored = await _client.policy(rid);
+      if (isGuardError(stored)) {
+        return { error: { code: guardErrorType(stored), message: guardErrorMessage(stored) } };
+      }
+      const projected = legacyPolicyProjection({
+        graph: newPolicy.graph,
+        edge_predicates: newPolicy.edgePredicates,
+        terminal: newPolicy.terminal,
+        stakes: newPolicy.stakes,
+      });
+      if (policiesEqual(projected, policyChecksumFields(stored))) {
+        _registered.set(rid, 'legacy');
+        return { guard_id: rid, status: 'legacy', storedChecksum: stored.checksum };
+      }
+      return {
+        error: {
+          code: 'GUARD_POLICY_DIVERGED',
+          message: `stored guard policy for ${rid} differs from the expected legacy policy`,
+        },
+      };
+    }
   } catch (e) {
     // A thrown Stratum CLI failure must NOT escape as
     // a generic 500/400 — normalise to a fail-closed error result.
     return { error: { code: 'GUARD_UNREACHABLE', message: e.message } };
   }
   if (res && (res.status === 'registered' || res.status === 'exists')) {
-    _registered.add(rid);
+    _registered.set(rid, 'cached');
   }
   return res;
 }
 
+/** Lazily apply the signed legacy-policy upgrade required for backfilled completion. */
+export async function applyBackfillUpgrade({ featureCode, workspaceRoot, mode = 'build' }) {
+  const rid = resourceId(featureCode, workspaceRoot, mode);
+  let stored;
+  try {
+    stored = await _client.policy(rid);
+  } catch (error) {
+    const message = error?.message || String(error);
+    return { ok: false, reasons: ['could not read stored guard policy'], error: { code: 'GUARD_UNREACHABLE', message, hint: HINT_APPROVE } };
+  }
+  if (isGuardError(stored)) {
+    const message = guardErrorMessage(stored);
+    return { ok: false, reasons: ['could not read stored guard policy'], error: { code: guardErrorType(stored) ?? 'upgrade_descriptor_unavailable', message, hint: HINT_APPROVE } };
+  }
+  const expected = deriveBackfillPolicy(policyChecksumFields(stored), mode);
+  if (policiesEqual(expected, policyChecksumFields(stored))) {
+    _registered.set(rid, 'cached');
+    return { ok: true, status: 'unchanged', checksum: stored.checksum };
+  }
+
+  let release;
+  try {
+    release = await acquireDirLock(
+      path.join(workspaceRoot, '.compose', 'data', 'locks', 'guard-descriptors'),
+      { timeoutMs: DESCRIPTOR_LOCK_TIMEOUT_MS },
+    );
+  } catch (error) {
+    const message = error?.message || String(error);
+    return { ok: false, reasons: [message], error: { code: 'upgrade_descriptor_unavailable', message, hint: HINT_APPROVE } };
+  }
+  try {
+    const ensured = await _ensureDescriptors({
+      workspaceRoot,
+      needChecksums: [stored.checksum],
+      custody: _custody,
+      verifier: _client.descriptors,
+    });
+    if (ensured.status === 'refused') {
+      return {
+        ok: false,
+        reasons: [ensured.message],
+        error: { code: ensured.code ?? 'upgrade_descriptor_unavailable', message: ensured.message, hint: ensured.hint ?? HINT_APPROVE },
+      };
+    }
+
+    let applied;
+    try {
+      applied = await _client.applyUpgrade({
+        resourceId: rid,
+        descriptorId: descriptorIdFor(stored.checksum, mode),
+        descriptorsPath: ensured.path,
+      });
+    } catch (error) {
+      const message = error?.message || String(error);
+      return { ok: false, reasons: ['guard upgrade failed'], error: { code: 'GUARD_UNREACHABLE', message, hint: HINT_APPROVE } };
+    }
+    if (isGuardError(applied)) {
+      const message = guardErrorMessage(applied);
+      return {
+        ok: false,
+        reasons: ['guard upgrade failed'],
+        error: { code: guardErrorType(applied) ?? 'upgrade_descriptor_unavailable', message, hint: HINT_APPROVE },
+      };
+    }
+    if (applied.status !== 'applied' && applied.status !== 'unchanged') {
+      const message = 'guard upgrade returned an unexpected result';
+      return { ok: false, reasons: [message], error: { code: 'upgrade_descriptor_unavailable', message, hint: HINT_APPROVE } };
+    }
+    _registered.set(rid, 'cached');
+    return {
+      ok: true,
+      status: applied.status,
+      ledgerRef: applied.ledger_ref,
+      checksum: applied.checksum,
+      descriptorId: descriptorIdFor(stored.checksum, mode),
+      generation: ensured.sha,
+    };
+  } finally {
+    await release();
+  }
+}
+
 /**
  * Attempt a guarded lifecycle transition. Registers (idempotently) then
  * transitions. FAIL-CLOSED: any guard error (unreachable, illegal edge, error
@@ -330,14 +550,22 @@ export async function ensureGuard(featureCode, currentPhase, workspaceRoot, mode
  * @returns {Promise<{applied:boolean, refused?:boolean, verdict?:object,
  *   ledgerRef?:string, currentState?:string, error?:object}>}
  */
-export async function guardedTransition({ featureCode, from, to, workspaceRoot, commitSha, resolvedBy = 'agent', mode = 'build' }) {
+export async function guardedTransition({ featureCode, from, to, workspaceRoot, commitSha, resolvedBy = 'agent', mode = 'build', artifacts: extraArtifacts, idempotencyKey, expectedPolicyChecksum }) {
   const reg = await ensureGuard(featureCode, from, workspaceRoot, mode);
   if (reg && (reg.error || reg.status === 'error')) {
     return { applied: false, error: reg.error || reg };
   }
 
   const rid = resourceId(featureCode, workspaceRoot, mode);
-  const artifacts = commitSha ? { commit_sha: commitSha } : {};
+  // COMP-COMPLETION-GATE: callers may add artifacts (e.g. the completion gate's
+  // `operation_id`). Artifacts feed the ledger's payload_digest, which is the
+  // only way two commit-less transitions on one resource are distinguishable —
+  // without it, every null-SHA completion hashes identically and a crash-recovery
+  // check cannot tell one operation from another.
+  const artifacts = {
+    ...(commitSha ? { commit_sha: commitSha } : {}),
+    ...(extraArtifacts || {}),
+  };
   // No idempotency_key: a refuse→fix→retry is a NEW logical attempt that must
   // re-evaluate evidence, but it carries an identical (from,to,artifacts)
   // payload — an idempotency_key would make the guard replay the prior refusal.
@@ -350,6 +578,8 @@ export async function guardedTransition({ featureCode, from, to, workspaceRoot,
       fromState: from,
       toState: to,
       artifacts,
+      idempotencyKey,
+      expectedPolicyChecksum,
       resolvedBy,
     });
   } catch (e) {