@smartmemory/compose 0.3.7 → 0.4.0

package/server/vision-routes.js

@@ -44,6 +44,7 @@ function getSchemaValidator() {
 import { randomUUID } from 'node:crypto';
 import { getTargetRoot, resolveProjectPath } from './project-root.js';
 import { resolveFeaturesPathFromConfig } from '../lib/project-paths.js';
+import { isManagedBuildItem, applyVerifiedProjection } from './completion-projection.js';
 import { getCompletions } from '../lib/completion-writer.js';
 import { isFeatureCode } from '../lib/feature-code.js';
 import { anchorBoundary } from '../lib/checkpoint/checkpoint-writer.js';
@@ -59,7 +60,6 @@ import {
 } from '../lib/lifecycle-modes.js';
 import { requireSensitiveOrPaired as requireSensitiveToken } from './security.js';
 
-const PROJECT_ROOT = getTargetRoot();
 
 /**
  * Read the compose.json config for an ARBITRARY workspace root (not the bound
@@ -81,10 +81,10 @@ function loadComposeConfig(root) {
  * @param {object} app — Express app
  * @param {{ store: object, scheduleBroadcast: function, broadcastMessage: function, projectRoot: string, settingsStore?: object, capabilities?: object }} deps
  */
-export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMessage, projectRoot = PROJECT_ROOT, settingsStore, capabilities }) {
+export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMessage, projectRoot = getTargetRoot(), settingsStore, capabilities }) {
   // COMP-MCP-ENFORCE: when enabled, lifecycle transitions are verdict-gated by
   // stratum's STRAT-GUARD (fail-closed). Default OFF — legacy behavior intact.
-  const guardEnabled = capabilities?.guard === true;
+  const guardEnabled = () => capabilities?.guard === true;
 
   // COMP-MCP-ENFORCE Slice 4: opt-in loopback REST auth on vision MUTATION
   // endpoints (lifecycle transitions, iterations, gate resolve, item CRUD,
@@ -95,9 +95,8 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
   // returns 503 (mutations disabled) rather than silently allowing them — enabling
   // auth without a token is a misconfiguration, not an open door. Pass-through
   // when off, so route wiring is unconditional.
-  const guardAuthEnabled = capabilities?.guardAuth === true;
   const guardAuth = (req, res, next) =>
-    guardAuthEnabled ? requireSensitiveToken(req, res, next) : next();
+    capabilities?.guardAuth === true ? requireSensitiveToken(req, res, next) : next();
 
   // PARITY-5: GET /api/completions — read-only recorded-completion log for a
   // feature. Reads are open (not guardAuth-wrapped); wraps the same
@@ -148,6 +147,34 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
   // PATCH /api/vision/items/:id — update item
   app.patch('/api/vision/items/:id', guardAuth, (req, res) => {
     try {
+      // COMP-COMPLETION-GATE slice 3 (AC-10, path 7): `status: 'complete'` on a
+      // MANAGED BUILD-MODE feature item is refused here. The general PATCH has
+      // no evidence to offer; the legitimate write is the self-verifying
+      // projection endpoint below, which the gate reaches after the guard has
+      // applied. Fix/plan items and unmanaged items are untouched (§2.3d) —
+      // round 5 caught that an unconditional refusal bricks those modes
+      // whenever a server is running, since every mode shares the terminal call.
+      // The verification stamp is SERVER-OWNED: only the §2.3b predicate writes
+      // it. A PATCH carrying it could relabel a legacy item as `guarded` with a
+      // fake ledger ref (Codex r2 #1).
+      if (req.body && Object.prototype.hasOwnProperty.call(req.body, 'completion_projection')) {
+        return res.status(422).json({
+          error: 'completion_projection is written by the completion projection only and cannot be set through PATCH',
+          code: 'PROJECTION_STAMP_READONLY',
+        });
+      }
+      if (req.body?.status === 'complete') {
+        const existing = store.items.get(req.params.id);
+        if (existing && isManagedBuildItem(existing, projectRoot)) {
+          return res.status(422).json({
+            error: `refusing status: complete for ${existing.lifecycle.featureCode} — a managed build-mode ` +
+              'feature completes through the completion gate (record_completion / the build runner / ' +
+              'POST …/lifecycle/complete), which verifies evidence and projects the item via ' +
+              'POST /api/vision/items/:id/completion-projection.',
+            code: 'COMPLETE_VIA_GATE_ONLY',
+          });
+        }
+      }
       const item = store.updateItem(req.params.id, req.body);
       // If group changed, write back to docs/features/<code>/feature.json
       // so the change survives restart and re-scan. Non-fatal on failure.
@@ -166,6 +193,31 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
     }
   });
 
+  // POST /api/vision/items/:id/completion-projection — COMP-COMPLETION-GATE
+  // slice 3 (§2.3b, AC-4b/4d). Self-verifying, NOT privileged: before writing
+  // it re-reads feature.json (must already be COMPLETE — §2.3a step 2, the
+  // durable truth) and, if a guard resource exists, the guard ledger (must be
+  // complete). It cannot be used to complete anything; it only mirrors a
+  // completion canonical state already records — which is why it needs no
+  // token and does not reopen the bypass the PATCH refusal closes. Never calls
+  // the gate (no recursion: gate → here is one-directional).
+  app.post('/api/vision/items/:id/completion-projection', guardAuth, async (req, res) => {
+    try {
+      const { featureCode, commitSha, ledgerRef } = req.body || {};
+      if (!featureCode) return res.status(400).json({ error: 'featureCode required' });
+      if (!store.items.get(req.params.id)) return res.status(404).json({ error: `Item not found: ${req.params.id}` });
+      const r = await applyVerifiedProjection(store, {
+        itemId: req.params.id, featureCode, cwd: projectRoot, consultGuard: true,
+        evidence: { commitSha: commitSha || undefined, ledgerRef: ledgerRef || undefined, source: 'rest' },
+      });
+      if (!r.ok) return res.status(422).json({ error: 'completion projection refused', reasons: r.reasons });
+      scheduleBroadcast();
+      res.json({ ok: true, itemId: req.params.id, verified_by: r.verified_by });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
   // DELETE /api/vision/items/:id — delete item + connections
   app.delete('/api/vision/items/:id', guardAuth, (req, res) => {
     try {
@@ -213,9 +265,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
   });
 
   // ── Lifecycle endpoints (simplified — no state machine) ──────────────
-  const featuresPath = projectRoot !== PROJECT_ROOT
-    ? resolveFeaturesPathFromConfig(projectRoot, loadComposeConfig(projectRoot))
-    : resolveProjectPath('features');
+  const featuresPath = () => resolveFeaturesPathFromConfig(projectRoot, loadComposeConfig(projectRoot));
 
   // Phase graph + skippable + terminal are owned by the mode registry (single
   // source of truth shared with the STRAT-GUARD graph) — see COMP-MCP-ENFORCE /
@@ -283,7 +333,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // (the clean bootstrap path; backfill for pre-rollout items happens lazily
       // on first transition). Best-effort — a registration hiccup must not block
       // starting a lifecycle; the next guarded transition re-attempts ensureGuard.
-      if (guardEnabled) {
+      if (guardEnabled()) {
         try { await ensureGuard(featureCode, genesis, projectRoot, mode); }
         catch (e) { console.warn(`[lifecycle/start] guard register for ${featureCode} failed: ${e.message}`); }
         // Slice 2: starting a lifecycle projects the genesis phase → IN_PROGRESS so
@@ -352,7 +402,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!valid?.includes(targetPhase)) return res.status(400).json({ error: `Invalid transition: ${from} → ${targetPhase}` });
 
       // COMP-MCP-ENFORCE: verdict-gate the transition (fail-closed) before mutating.
-      if (guardEnabled) {
+      if (guardEnabled()) {
         const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, workspaceRoot: projectRoot, resolvedBy: 'agent', mode: modeOf(item) });
         if (!g.applied) return res.status(422).json({ error: 'transition refused by guard', from, to: targetPhase, verdict: g.verdict, guardError: g.error });
       }
@@ -365,7 +415,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // COMP-MCP-ENFORCE Slice 2 (lifecycle-as-truth): project the new phase onto
       // feature.json STATUS (best-effort; idempotent — only writes on a real change).
       // COMP-ROADMAP-PLAN: skipped for tracksFeatureJson:false modes (no feature.json).
-      if (guardEnabled && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: targetPhase, cwd: projectRoot });
+      if (guardEnabled() && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: targetPhase, cwd: projectRoot });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: targetPhase, outcome, timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, outcome, timestamp: now }));
@@ -394,7 +444,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!valid?.includes(targetPhase)) return res.status(400).json({ error: `Invalid transition: ${from} → ${targetPhase}` });
 
       // COMP-MCP-ENFORCE: verdict-gate the skip (fail-closed) before mutating.
-      if (guardEnabled) {
+      if (guardEnabled()) {
         const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, workspaceRoot: projectRoot, resolvedBy: 'agent', mode: modeOf(item) });
         if (!g.applied) return res.status(422).json({ error: 'transition refused by guard', from, to: targetPhase, verdict: g.verdict, guardError: g.error });
       }
@@ -406,7 +456,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       store.updateLifecycle(req.params.id, item.lifecycle);
       // COMP-MCP-ENFORCE Slice 2 (lifecycle-as-truth): project phase → STATUS.
       // COMP-ROADMAP-PLAN: skipped for tracksFeatureJson:false modes (no feature.json).
-      if (guardEnabled && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: targetPhase, cwd: projectRoot });
+      if (guardEnabled() && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: targetPhase, cwd: projectRoot });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: targetPhase, outcome: 'skipped', timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: targetPhase, outcome: 'skipped', timestamp: now }));
@@ -435,7 +485,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // The `<from>→killed` edge has no predicate, so it only fails if the guard
       // is unreachable — consistent with advance/skip/complete. Authorized
       // bypass remains stratum_guard_override (Slice 3).
-      if (guardEnabled) {
+      if (guardEnabled()) {
         const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from, to: 'killed', workspaceRoot: projectRoot, resolvedBy: 'agent', mode: modeOf(item) });
         if (!g.applied) return res.status(422).json({ error: 'kill refused by guard', from, to: 'killed', verdict: g.verdict, guardError: g.error });
       }
@@ -451,7 +501,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // COMP-MCP-ENFORCE Slice 2: project kill → KILLED onto feature.json
       // (closes the COMP-PARITY-7 gap — kill previously wrote vision-state only).
       // COMP-ROADMAP-PLAN: skipped for tracksFeatureJson:false modes (no feature.json).
-      if (guardEnabled && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: 'killed', cwd: projectRoot });
+      if (guardEnabled() && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode: item.lifecycle.featureCode, phase: 'killed', cwd: projectRoot });
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from, to: 'killed', outcome: 'killed', timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from, to: 'killed', outcome: 'killed', timestamp: now }));
@@ -479,39 +529,93 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
         return res.status(400).json({ error: `Can only complete from ${completable} phase, currently in: ${item.lifecycle.currentPhase}` });
       }
 
-      // COMP-MCP-ENFORCE Slice 3: evidence-bound completion. Under the guard,
-      // ship→complete requires REAL evidence — the commit must exist (server-read
-      // git) and tests must be attested (configured test command exits 0, or
-      // tests_pass is explicitly true; never a silent default). Then the guard
-      // verdict gates the transition (fail-closed).
-      let verifiedTestsPass = req.body?.tests_pass;
-      if (guardEnabled) {
-        const ev = await verifyCompletionEvidence({
-          commitSha: req.body?.commit_sha,
-          cwd: projectRoot,
-          testCommand: guardTestCommand(projectRoot),
-          testsPassClaim: req.body?.tests_pass,
+      const featureCode = item.lifecycle.featureCode;
+      const completionResult = { partial: false };
+      let now;
+
+      // MANAGED build item = bound to a code, build mode, feature.json exists
+      // (the same key AC-10/AC-16 use). An unmanaged build item — a lifecycle
+      // started for a code that has no feature.json — has nothing canonical to
+      // complete and keeps the pre-slice-3 path, as fix/plan do.
+      if (isManagedBuildItem(item, projectRoot)) {
+        // COMP-COMPLETION-GATE slice 3 (§2.1, AC-10): for a mode that tracks
+        // feature.json (build), the cockpit completion IS a completion and goes
+        // through the gate — evidence, ONE guarded transition, then the gate
+        // performs record → status → ROADMAP → vision → events (§2.3a). The
+        // vision step is an in-process projector against this server's live
+        // store (a REST call back into ourselves would race it; a direct file
+        // write would leave it stale). Under the guard a request with no
+        // commit_sha is refused by the evidence check: an evidence-free cockpit
+        // completion was path 7's quieter twin and is closed on purpose.
+        const { completionGate } = await import('../lib/completion-gate.js');
+        const { commit_sha, tests_pass, files_changed, notes } = req.body || {};
+        const gated = await completionGate({
+          featureCode,
+          ...(commit_sha ? { commitSha: commit_sha } : {}),
+          // Guard on: no default — the evidence check attests (test command) or
+          // the caller states it. Guard off: the cockpit's pre-existing default
+          // (flag-off parity, the same opt-out the gate itself honours in AC-5).
+          testsPass: guardEnabled() ? tests_pass : (tests_pass ?? true),
+          filesChanged: files_changed ?? [],
+          notes: notes ?? `cockpit lifecycle: ${featureCode} complete`,
+          workspaceRoot: projectRoot,
+          mode: modeOf(item),
+          visionItemId: req.params.id,
+          visionProjector: ({ visionItemId, commitSha, ledgerRef, guarded }) => applyVerifiedProjection(store, {
+            itemId: visionItemId, featureCode, cwd: projectRoot, consultGuard: guarded ?? true,
+            guardEnabledOverride: guarded,
+            evidence: { commitSha, ledgerRef, source: 'lifecycle/complete' },
+          }).then((r) => { if (!r.ok) throw new Error(r.reasons.join('; ')); return r; }),
         });
-        if (!ev.ok) {
-          return res.status(422).json({ error: 'completion evidence not satisfied', reasons: ev.reasons });
+        if (!gated.ok) {
+          return res.status(422).json({
+            error: gated.refusedAt === 'evidence' ? 'completion evidence not satisfied' : 'completion refused',
+            refusedAt: gated.refusedAt, reasons: gated.reasons,
+            ...(gated.verdict ? { verdict: gated.verdict } : {}),
+            ...(gated.error ? { guardError: gated.error } : {}),
+          });
         }
-        verifiedTestsPass = ev.testsAttested ? true : (req.body?.tests_pass === true);
-
-        const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from: completable, to: 'complete', workspaceRoot: projectRoot, commitSha: req.body?.commit_sha, resolvedBy: 'agent', mode: modeOf(item) });
-        if (!g.applied) return res.status(422).json({ error: 'completion refused by guard', from: completable, to: 'complete', verdict: g.verdict, guardError: g.error });
+        now = new Date().toISOString();
+        item.lifecycle.currentPhase = 'complete';
+        item.lifecycle.completedAt = now;
+        appendPhaseHistory(item, { from: completable, to: 'complete', outcome: 'approved', timestamp: now });
+        store.updateLifecycle(req.params.id, item.lifecycle);
+        const failures = [...(gated.failures || [])];
+        if (store.lastSaveOk === false) {
+          // The projection reached disk; this lifecycle write did not. Report it
+          // as a partial like any other projection failure (Codex r2 #3).
+          failures.push({ step: 'lifecycle-persist', message: 'vision-state could not be persisted after the lifecycle transition', recover: 'restart the server or re-run compose validate --fix' });
+        }
+        if (failures.length > 0) {
+          completionResult.partial = true;
+          completionResult.failures = failures;
+        }
+        completionResult.ledgerRef = gated.ledgerRef ?? null;
+        completionResult.verified_by = gated.visionProjection?.verified_by ?? null;
+      } else {
+        // Fix/plan (no feature.json — COMP-COMPLETION-GATE-MODES) and items
+        // with no feature code: the pre-slice-3 path, byte-identical.
+        if (guardEnabled()) {
+          const ev = await verifyCompletionEvidence({
+            commitSha: req.body?.commit_sha,
+            cwd: projectRoot,
+            testCommand: guardTestCommand(projectRoot),
+            testsPassClaim: req.body?.tests_pass,
+          });
+          if (!ev.ok) {
+            return res.status(422).json({ error: 'completion evidence not satisfied', reasons: ev.reasons });
+          }
+          const g = await guardedTransition({ featureCode: item.lifecycle.featureCode, from: completable, to: 'complete', workspaceRoot: projectRoot, commitSha: req.body?.commit_sha, resolvedBy: 'agent', mode: modeOf(item) });
+          if (!g.applied) return res.status(422).json({ error: 'completion refused by guard', from: completable, to: 'complete', verdict: g.verdict, guardError: g.error });
+        }
+        now = new Date().toISOString();
+        item.lifecycle.currentPhase = 'complete';
+        item.lifecycle.completedAt = now;
+        appendPhaseHistory(item, { from: completable, to: 'complete', outcome: 'approved', timestamp: now });
+        store.updateLifecycle(req.params.id, item.lifecycle);
+        store.updateItem(req.params.id, { status: 'complete' });
       }
 
-      const now = new Date().toISOString();
-      item.lifecycle.currentPhase = 'complete';
-      item.lifecycle.completedAt = now;
-      // COMP-OBS-TIMELINE: populate phaseHistory + emit phase_transition DecisionEvent
-      appendPhaseHistory(item, { from: completable, to: 'complete', outcome: 'approved', timestamp: now });
-      store.updateLifecycle(req.params.id, item.lifecycle);
-      store.updateItem(req.params.id, { status: 'complete' });
-      // COMP-MCP-ENFORCE Slice 2: status projection for the no-commit path is
-      // applied BELOW (in the `else` branch) so it does not pre-empt and mask the
-      // recordCompletion bridge, which is the authority + partial-write reporter
-      // on the commit_sha path.
       scheduleBroadcast();
       broadcastMessage({ type: 'lifecycleTransition', itemId: req.params.id, from: completable, to: 'complete', outcome: 'approved', timestamp: now });
       emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({ featureCode: item.lifecycle.featureCode, from: completable, to: 'complete', outcome: 'approved', timestamp: now }));
@@ -522,61 +626,67 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       // COMP-RESUME: best-effort anchor checkpoint at the (terminal) phase boundary
       anchorBoundary(getTargetRoot(), { item, trigger: 'phase-transition' });
 
-      // COMP-MCP-MIGRATION: reconcile cockpit complete with record_completion
-      // (commit-bound completion writer). Best-effort: failures emit a decision
-      // event but never roll back the lifecycle transition.
+      res.json({ completedAt: now, ...completionResult });
+    } catch (err) {
+      const status = err.message.includes('not found') ? 404 : 400;
+      res.status(status).json({ error: err.message });
+    }
+  });
+
+  // A reconstructed completion has the same completion evidence and durable
+  // writes as the normal gate, but may be reached from any active lifecycle
+  // phase. The gate owns the terminal history/item mutation as one recoverable
+  // transaction; this route only supplies the live store and emits its effects.
+  app.post('/api/vision/items/:id/lifecycle/backfill', guardAuth, async (req, res) => {
+    try {
+      const item = store.items.get(req.params.id);
+      if (!item?.lifecycle) return res.status(404).json({ error: 'No lifecycle on this item' });
+      const { commit_sha, tests_pass, files_changed, notes, reason, occurrences } = req.body || {};
+      if (typeof reason !== 'string' || reason.trim().length === 0) {
+        return res.status(400).json({ error: 'reason is required' });
+      }
+      const { completionGate } = await import('../lib/completion-gate.js');
       const featureCode = item.lifecycle.featureCode;
-      const completionResult = { partial: false };
-      if (featureCode) {
-        const { commit_sha, tests_pass, files_changed, notes } = req.body || {};
-        if (commit_sha) {
-          try {
-            const { recordCompletion } = await import('../lib/completion-writer.js');
-            await recordCompletion(projectRoot, {
-              feature_code: featureCode,
-              commit_sha,
-              // Slice 3: under the guard, tests_pass reflects verified evidence
-              // (attested or explicit), NOT a silent default-to-true.
-              tests_pass: guardEnabled ? (verifiedTestsPass === true) : (tests_pass ?? true),
-              files_changed: files_changed ?? [],
-              notes: notes ?? `cockpit lifecycle: ${featureCode} complete`,
-            });
-          } catch (err) {
-            completionResult.partial = true;
-            const eventType = err.code === 'STATUS_FLIP_AFTER_COMPLETION_RECORDED'
-              ? 'cockpit_completion_partial_status_flip'
-              : 'cockpit_completion_failed';
-            completionResult.completion_failed = err.code || 'UNKNOWN';
-            completionResult.message = err.message;
-            try {
-              emitDecisionEvent(broadcastMessage, {
-                type: eventType,
-                featureCode,
-                timestamp: now,
-                error: { code: err.code, message: err.message },
-              });
-            } catch { /* decision event emit best-effort */ }
-            // eslint-disable-next-line no-console
-            console.warn(`[lifecycle/complete] record_completion ${eventType} for ${featureCode}: ${err.message}`);
-          }
-        } else {
-          // No SHA — emit a skip event so validate_feature can flag drift later
-          try {
-            emitDecisionEvent(broadcastMessage, {
-              type: 'cockpit_completion_skipped',
-              featureCode,
-              timestamp: now,
-              reason: 'no_commit_sha',
-            });
-          } catch { /* decision event emit best-effort */ }
-          // No recordCompletion bridge ran — project complete → COMPLETE so
-          // lifecycle-as-truth still reaches feature.json (best-effort).
-          // COMP-ROADMAP-PLAN: skipped for tracksFeatureJson:false modes (no feature.json).
-          if (guardEnabled && getMode(modeOf(item)).runner.tracksFeatureJson) await projectFeatureStatus({ featureCode, phase: 'complete', cwd: projectRoot });
-        }
+      const gated = await completionGate({
+        intent: 'backfill', featureCode,
+        ...(commit_sha !== undefined ? { commitSha: commit_sha } : {}),
+        testsPass: tests_pass,
+        filesChanged: files_changed ?? [], notes, reason, occurrences: occurrences ?? [],
+        workspaceRoot: projectRoot, mode: modeOf(item), item, store,
+        visionItemId: req.params.id,
+        visionProjector: ({ visionItemId, commitSha, ledgerRef, guarded }) => applyVerifiedProjection(store, {
+          itemId: visionItemId, featureCode, cwd: projectRoot,
+          consultGuard: guarded ?? true, guardEnabledOverride: guarded,
+          evidence: { commitSha, ledgerRef, source: 'lifecycle/backfill' },
+        }).then((r) => { if (!r.ok) throw new Error(r.reasons.join('; ')); return r; }),
+      });
+      if (!gated.ok) {
+        return res.status(422).json({
+          error: 'backfill refused', refusedAt: gated.refusedAt, reasons: gated.reasons,
+          ...(gated.verdict ? { verdict: gated.verdict } : {}),
+          ...(gated.error ? { guardError: gated.error } : {}),
+          ...(gated.error?.hint ? { hint: gated.error.hint } : {}),
+        });
       }
 
-      res.json({ completedAt: now, ...completionResult });
+      const timestamp = item.lifecycle.completedAt;
+      if (!gated.replayed) {
+        const terminal = item.lifecycle.phaseHistory?.findLast((entry) => entry.phase === 'complete_backfilled');
+        scheduleBroadcast();
+        broadcastMessage({
+          type: 'lifecycleTransition', itemId: req.params.id, from: terminal?.from ?? null,
+          to: 'complete_backfilled', outcome: terminal?.outcome ?? 'backfilled', timestamp,
+        });
+        emitDecisionEvent(broadcastMessage, buildPhaseTransitionEvent({
+          featureCode, from: terminal?.from ?? null, to: 'complete_backfilled',
+          outcome: terminal?.outcome ?? 'backfilled', timestamp,
+          origin: terminal?.origin, recordedAt: terminal?.recordedAt, confidence: terminal?.confidence,
+        }));
+        emitDriftAxes(broadcastMessage, store, item, projectRoot, timestamp);
+        emitStatusSnapshot(broadcastMessage, store, featureCode, timestamp);
+        anchorBoundary(getTargetRoot(), { item, trigger: 'phase-transition' });
+      }
+      res.json({ completedAt: timestamp, backfill: gated.backfill ?? null, ...gated });
     } catch (err) {
       const status = err.message.includes('not found') ? 404 : 400;
       res.status(status).json({ error: err.message });
@@ -794,7 +904,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!item.lifecycle?.featureCode) {
         return res.status(400).json({ error: 'Item has no lifecycle featureCode' });
       }
-      const assessment = new ArtifactManager(featuresPath, item.lifecycle?.mode).assess(item.lifecycle.featureCode);
+      const assessment = new ArtifactManager(featuresPath(), item.lifecycle?.mode).assess(item.lifecycle.featureCode);
       res.json(assessment);
     } catch (err) {
       res.status(500).json({ error: err.message });
@@ -808,7 +918,7 @@ export function attachVisionRoutes(app, { store, scheduleBroadcast, broadcastMes
       if (!item.lifecycle?.featureCode) {
         return res.status(400).json({ error: 'Item has no lifecycle featureCode' });
       }
-      const result = new ArtifactManager(featuresPath, item.lifecycle?.mode).scaffold(item.lifecycle.featureCode, req.body);
+      const result = new ArtifactManager(featuresPath(), item.lifecycle?.mode).scaffold(item.lifecycle.featureCode, req.body);
       res.json(result);
     } catch (err) {
       res.status(400).json({ error: err.message });

package/server/vision-server.js

@@ -1,3 +1,4 @@
+import express from 'express';
 /**
  * Vision Server — REST endpoints + WebSocket broadcast for the vision surface.
  * Follows the same attach() pattern as FileWatcherServer.
@@ -31,6 +32,7 @@ import { attachHealthRoutes } from './health-routes.js';
 import { attachValidateRoutes } from './validate-routes.js';
 import { attachQaScopeRoutes } from './qa-scope-routes.js';
 import { attachSmartmemoryRoutes } from './smartmemory-routes.js';
+import { attachMayaRoutes } from './maya-routes.js';
 import { attachDesignRoutes } from './design-routes.js';
 import { DesignSessionManager } from './design-session.js';
 import { attachPipelineRoutes } from './pipeline-routes.js';
@@ -80,6 +82,18 @@ export class VisionServer {
     this._stratumSync = null;
   }
 
+  /**
+   * Create the Stratum poller on first use. Never called while
+   * `capabilities.stratum` is false, so a stratum-disabled workspace keeps
+   * `_stratumSync === null` (no timers, no poller) for its whole lifetime.
+   */
+  _ensureStratumSync() {
+    if (!this._stratumSync) {
+      this._stratumSync = new StratumSync(this.store, () => this.scheduleBroadcast());
+    }
+    return this._stratumSync;
+  }
+
   attach(httpServer, app) {
     // ── Settings store ────────────────────────────────────────────────────
     this.settingsStore = new SettingsStore(undefined, SETTINGS_DEFAULTS);
@@ -108,6 +122,11 @@ export class VisionServer {
     // answers {enabled:false} from config alone when the flag is OFF.
     attachSmartmemoryRoutes(app);
 
+    // ── Maya colleague relay (COMP-FOH FOH-6, opt-in) ──────────────────────
+    // GET /api/maya/status (degrade-never-fail funnel probe) + POST
+    // /api/maya/message. Auth-gated in remote mode — never allowlisted.
+    attachMayaRoutes(app);
+
     // ── Vision CRUD + lifecycle routes ─────────────────────────────────────
     attachVisionRoutes(app, {
       store: this.store,
@@ -155,17 +174,14 @@ export class VisionServer {
     });
 
     // ── Design conversation routes ──────────────────────────────────────────
-    // Re-resolve on every call so project switches get fresh instances.
+    // The workspace owns its manager; pending conversations retain their data root.
     let _designSessionManager = null;
-    let _designDataDir = null;
 
     attachDesignRoutes(app, {
       getSessionManager: () => {
-        const dataDir = getDataDir();
-        if (dataDir !== _designDataDir) {
-          if (_designSessionManager) _designSessionManager.destroy();
-          _designSessionManager = new DesignSessionManager(dataDir);
-          _designDataDir = dataDir;
+        if (!_designSessionManager) {
+          _designSessionManager = new DesignSessionManager(getDataDir());
+          this._designSessionManager = _designSessionManager;
         }
         return _designSessionManager;
       },
@@ -262,28 +278,32 @@ export class VisionServer {
     });
 
     // ── Stratum (conditional) ────────────────────────────────────────────
-    if (this._config.capabilities?.stratum) {
-      app.use('/api/stratum', createStratumRouter());
-      this._stratumSync = new StratumSync(this.store, () => this.scheduleBroadcast());
-      attachStratumRoutes(app, {
-        store: this.store,
-        scheduleBroadcast: () => this.scheduleBroadcast(),
-        broadcastMessage: (msg) => this.broadcastMessage(msg),
-        sync: this._stratumSync,
-      });
-      this._stratumSync.start();
-      console.log('[vision] Stratum sync enabled');
-    } else {
-      app.use('/api/stratum', (_req, res) => {
-        res.status(503).json({ error: 'Stratum not enabled', hint: 'compose init (TS engine; python retired — see python-legacy branch)' });
-      });
-    }
+    const self = this;
+    const stratumRouter = express.Router();
+    stratumRouter.use('/api/stratum', createStratumRouter());
+    attachStratumRoutes(stratumRouter, {
+      store: this.store,
+      scheduleBroadcast: () => this.scheduleBroadcast(),
+      broadcastMessage: (msg) => this.broadcastMessage(msg),
+      // Lazily resolved: the poller only exists while stratum is enabled
+      // (capabilities can flip at runtime via refreshConfig/switch).
+      get sync() { return self._stratumSync; },
+    });
+    app.use((req, res, next) => {
+      if (this._config.capabilities?.stratum) return stratumRouter(req, res, next);
+      if (req.path.startsWith('/api/stratum')) return res.status(503).json({ error: 'Stratum not enabled', hint: 'compose init (TS engine; python retired — see python-legacy branch)' });
+      return next();
+    });
+    if (this._config.capabilities?.stratum) this._ensureStratumSync().start();
 
     // ── COMP-OBS-BRANCH: CC-session watcher (opt-in) ──────────────────────
     // Default OFF. Enable by setting `capabilities.cc_session_watcher: true` in compose.json
     // or by setting the `CC_SESSION_WATCHER=1` env var. When enabled, Forge reads
     // `~/.claude/projects/**/*.jsonl` and emits BranchLineage + DecisionEvents tied to the
     // current feature via sessions.json's transcriptPath basename.
+    this._refreshCCWatcher = () => {
+    this._ccWatcher?.stop();
+    this._ccWatcher = null;
     const ccWatcherEnabled =
       this._config.capabilities?.cc_session_watcher === true ||
       process.env.CC_SESSION_WATCHER === '1';
@@ -354,6 +374,9 @@ export class VisionServer {
       }
     }
 
+    };
+    this._refreshCCWatcher();
+
     // ── Haiku summary broadcast ─────────────────────────────────────────────
     if (this.sessionManager) {
       this.sessionManager.onSummary((summary) => {
@@ -470,7 +493,47 @@ export class VisionServer {
     }
   }
 
+  /** The live config object routes and the workspace binding both hold. */
+  get config() { return this._config; }
+
+  refreshConfig(config) {
+    this._stratumSync?.stop();
+    // C4: the incoming config may BE the object we already hold — the workspace
+    // binding aliases it, so `switch(root, ctx.binding.config)` hands it straight
+    // back. Snapshot first: clearing the holder would otherwise empty the very
+    // config being installed, leaving the workspace with no capabilities at all.
+    const next = JSON.parse(JSON.stringify(config ?? {}));
+    // Existing routes hold this capabilities object; update it in place.
+    const capabilities = this._config.capabilities ?? {};
+    for (const key of Object.keys(capabilities)) delete capabilities[key];
+    Object.assign(capabilities, next.capabilities);
+    for (const key of Object.keys(this._config)) delete this._config[key];
+    Object.assign(this._config, next, { capabilities });
+    if (this.sessionManager) this.sessionManager._featureRoot = resolveProjectPath('features');
+    this._refreshCCWatcher?.();
+  }
+
+  suspend() {
+    this._healthMonitor?.suspend();
+    this._coalescingBuffer?.stop();
+    this._stratumSync?.stop();
+    this._ccWatcher?.stop();
+    this._worktreeGC?.stop();
+    for (const client of this.clients) client.close(1000, 'Workspace changed');
+    this.clients.clear();
+  }
+
+  resume() {
+    this._healthMonitor?.resume();
+    this._coalescingBuffer?.start();
+    if (this._config.capabilities?.stratum) this._ensureStratumSync().start();
+    this._ccWatcher?.start();
+    this._worktreeGC?.start();
+  }
+
   close() {
+    this.suspend();
+    this._designSessionManager?.destroy();
     this._coalescingBuffer?.stop();
     if (this._stratumSync) this._stratumSync.stop();
     if (this._healthMonitor) this._healthMonitor.destroy();