@smartmemory/compose 0.2.58-beta → 0.3.1-beta

package/lib/gsd.js

@@ -4,7 +4,7 @@
 //
 // Self-contained status loop. Does NOT modify lib/build.js. Reuses primitives:
 //   - StratumMcpClient (lib/stratum-mcp-client.js) for plan/stepDone/runAgentText
-//   - executeParallelDispatchServer (lib/build.js) for the execute step
+//   - runConsumerIssuance (lib/build.js) for TS consumer fanout work
 //   - validateBoundaryMap (lib/boundary-map.js) for precondition check
 //   - enrichTaskGraph (lib/gsd-decompose-enrich.js) for decompose validation
 //   - buildTaskDescription (lib/gsd-prompt.js) for description repair fallback
@@ -17,15 +17,23 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, rmSync
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import YAML from 'yaml';
 
 import { StratumMcpClient } from './stratum-mcp-client.js';
+import { resolveStratumMcpConnection } from './stratum-engine.js';
 import { validateBoundaryMap } from './boundary-map.js';
 import { enrichTaskGraph } from './gsd-decompose-enrich.js';
 import { buildTaskDescription } from './gsd-prompt.js';
 import { writeAll, validate as validateTaskResult, read as readBlackboard } from './gsd-blackboard.js';
-import { executeParallelDispatchServer, executeShipStep } from './build.js';
+import { executeShipStep, runConsumerIssuance, ConsumerStuckError, filesOwnedConflict, toEngineUsage } from './build.js';
+import {
+  ConsumerFanoutArtifacts,
+  ConsumerMergeDecisionError,
+  isConsumerDescriptor,
+} from './consumer-fanout.js';
 import { GsdStuckDetector, DEFAULT_THRESHOLDS } from './gsd-stuck.js';
-import { readGsdBudgetConfig, buildBudgetBlock, injectBudget, composeBudgetDiagnostic } from './gsd-budget.js';
+import { readGsdBudgetConfig, buildBudgetBlock, injectBudget, composeBudgetDiagnostic, budgetStateFromLedger } from './gsd-budget.js';
 import { recordGsdUsage, checkGsdCumulativeBudget } from './budget-ledger.js';
 // COMP-GSD-6: continuous run-state checkpoint + canonical pid-liveness probe.
 // pidAlive is canonical in gsd-state.js (EPERM=alive) and imported one-way here.
@@ -45,6 +53,10 @@ const DEFAULT_GATE_COMMANDS = ['pnpm lint', 'pnpm build', 'pnpm test'];
 // (execute.pre_merge_verify) and the instructed gate (task descriptions).
 const DEFAULT_FAST_GATE = ['pnpm lint', 'pnpm build'];
 
+function sha256(value) {
+  return createHash('sha256').update(String(value)).digest('hex');
+}
+
 // ---------- Public API ----------
 
 export async function runGsd(featureCode, opts = {}) {
@@ -138,6 +150,8 @@ export async function runGsd(featureCode, opts = {}) {
   // run (and plain `compose build`) is byte-identical.
   const budgetCfg = readGsdBudgetConfig(cwd);
   const specYaml = injectBudget(readFileSync(specPath, 'utf-8'), budgetCfg);
+  const localSpec = YAML.parse(specYaml);
+  const localSpecDigest = sha256(JSON.stringify(localSpec));
 
   // 4a. COMP-GSD-4: cumulative cross-session ceiling pre-check (tokens/cost).
   // Refuse to start/resume a run that has already spent its lifetime budget —
@@ -154,13 +168,13 @@ export async function runGsd(featureCode, opts = {}) {
 
   // 4b. COMP-GSD-5 stuck detector — thresholds from .compose/compose.json
   // `gsd.stuck.*` with documented defaults. ONLY gsd passes this into the
-  // shared executeParallelDispatchServer, so build mode is byte-identical.
+  // TS consumer runner, so build mode remains unaffected.
   const stuckDetector = buildStuckDetector(cwd);
 
   // 5. Connect Stratum + plan (only after preconditions pass)
   const stratum = opts.stratum ?? new StratumMcpClient();
   const ownsStratum = !opts.stratum;
-  if (ownsStratum) await stratum.connect();
+  if (ownsStratum) await stratum.connect(resolveStratumMcpConnection(cwd));
   // COMP-GSD-4: ownership flag — release the resume lock in finally ONLY if THIS
   // process successfully claimed it (set below). Prevents (a) a non-resume run
   // from clobbering a concurrent resume's valid claim and (b) a claim-race loser
@@ -217,8 +231,12 @@ export async function runGsd(featureCode, opts = {}) {
     // docs unless context.filesChanged is provided.
     stepCtx = {
       stratum, cwd, featureCode, blueprintText, gateCommands, preMergeGate,
+      localSpec, localSpecDigest,
       filesChanged: [],
       stuckDetector,
+      // D2(a): per-ITEM wall-clock ceiling from gsd.budget.per_task_ms, enforced
+      // compose-side in runConsumerIssuance (the engine can't bound N items).
+      perItemTimeoutMs: budgetCfg.per_task_ms ?? null,
       resumeTaskGraph,
       stuck: null, // set by runOneStep on a stuck verdict
       runState: initialState, // COMP-GSD-6: flushState merges into this
@@ -269,43 +287,22 @@ export async function runGsd(featureCode, opts = {}) {
       featureCode,
       gateCommands,
       pre_merge_gate: preMergeGate,
-    });
-    const flowId = response.flow_id;
+    }, { workspaceRoot: cwd });
+    const flowId = response.runId;
     flushState(stepCtx, { flowId, phase: 'decompose' });
     emitPhaseOnce(stepCtx, 'decompose'); // COMP-GSD-7-EVENTLOG
 
-    // 5. Status loop. `stuck` (COMP-GSD-5) and `budget_exhausted` (COMP-GSD-4)
-    // are terminal statuses. `stuck` is set compose-side by runOneStep; budget
-    // is the stratum flow-budget terminal, surfaced verbatim through the advance/
-    // poll envelopes (and carries budget_state).
+    // 5. TS status loop. `stuck` is a Compose-side terminal and
+    // `budget_exhausted` is the Stratum flow-budget terminal.
     while (
-      response.status !== 'complete' &&
-      response.status !== 'killed' &&
+      response.status !== 'completed' &&
+      response.status !== 'failed' &&
       response.status !== 'stuck' &&
-      response.status !== 'budget_exhausted' &&
-      response.status !== 'error'   // COMP-PAR-MERGE-QUEUE: terminal step failure (e.g. retries_exhausted)
+      response.status !== 'budget_exhausted'
     ) {
       response = await runOneStep(response, stepCtx);
     }
 
-    // COMP-PAR-MERGE-QUEUE: a step that exhausted its retries (e.g. the execute
-    // step after repeated pre-merge gate failures) surfaces as a terminal `error`
-    // envelope rather than silently advancing to ship. Stop here with the failure
-    // and its bounce context instead of throwing `unknown response status`.
-    if (response.status === 'error') {
-      emitCompletionDeltas(stepCtx);
-      flushState(stepCtx, { status: 'failed' });
-      return {
-        status: 'failed',
-        flowId,
-        stepId: response.step_id ?? stepCtx.lastStepId ?? null,
-        errorType: response.error_type ?? 'step_failed',
-        message: response.message ?? 'GSD step failed',
-        violations: response.violations ?? [],
-        bouncedTasks: response.bounced_tasks ?? [],
-      };
-    }
-
     if (response.status === 'stuck') {
       // Artifacts (stuck.md/json + pause.json) were written by runOneStep.
       // COMP-GSD-7-EVENTLOG: flush any completions that finished before the stuck
@@ -327,9 +324,10 @@ export async function runGsd(featureCode, opts = {}) {
       // cascade-cancelled in-flight siblings. Persist budget.{md,json} +
       // pause.json (kind:budget) for --resume, record cumulative usage, and
       // return a terminal `budget` envelope. pause.lock is released by finally.
-      const budgetState = response.budget_state ?? {};
+      // D2(c): derive Compose's budget diagnostic from the TS ledger.
+      const budgetState = budgetStateFromLedger(response.ledger) ?? {};
       writeBudgetArtifacts(stepCtx, response, budgetState);
-      recordGsdUsageFromState(cwd, featureCode, budgetState);
+      recordGsdUsageFromState(cwd, featureCode, budgetState, stepCtx.recordedUsage);
       const axis = composeBudgetDiagnostic(budgetState, { feature: featureCode }).json.axis;
       // COMP-GSD-7-EVENTLOG: flush pre-halt completions, then record the pause.
       emitCompletionDeltas(stepCtx);
@@ -347,20 +345,22 @@ export async function runGsd(featureCode, opts = {}) {
 
     // 6b. COMP-GSD-5: a clean (non-stuck) finish clears any pause.json — the
     // resume completed, or a fresh run superseded a stale pause.
-    if (response.status === 'complete') {
+    if (response.status === 'complete' || response.status === 'completed') {
       // COMP-GSD-4: record this run's cumulative usage (best-effort; no-op when
-      // the complete envelope carries no budget_state, e.g. un-budgeted runs).
-      recordGsdUsageFromState(cwd, featureCode, response.budget_state);
+      // the terminal envelope carries no budget accounting, e.g. un-budgeted
+      // runs). D2(c): the TS engine returns `ledger`, not `budget_state`.
+      const terminalBudgetState = response.budget_state ?? budgetStateFromLedger(response.ledger);
+      recordGsdUsageFromState(cwd, featureCode, terminalBudgetState, stepCtx.recordedUsage);
       clearPauseFile(cwd, featureCode);
       // COMP-GSD-7: on a clean complete, budget.json is NOT written (only halts
       // write it). Persist a budget-final.json snapshot so the milestone report
       // (auto + retroactive `gsd report`) has actuals-vs-caps. No-op when the
-      // envelope carries no budget_state (un-budgeted run). Best-effort: this is
-      // a derived report input — a write failure must NEVER demote a successful
-      // run to 'failed' via the outer catch.
-      if (response.budget_state) {
+      // envelope carries no budget accounting (un-budgeted run). Best-effort:
+      // this is a derived report input — a write failure must NEVER demote a
+      // successful run to 'failed' via the outer catch.
+      if (terminalBudgetState) {
         try {
-          writeBudgetFinalSnapshot(stepCtx, response.budget_state);
+          writeBudgetFinalSnapshot(stepCtx, terminalBudgetState);
         } catch (err) {
           console.warn(`[gsd] budget-final snapshot failed: ${err.message}`);
         }
@@ -371,7 +371,7 @@ export async function runGsd(featureCode, opts = {}) {
     // other terminal here (e.g. stratum 'killed') maps to 'failed' so we stay
     // within the closed status vocabulary the contract + supervisor share.
     // COMP-GSD-7: stamp completedAt so retroactive reports can recover wall-clock.
-    const terminalStatus = response.status === 'complete' ? 'complete' : 'failed';
+    const terminalStatus = ['complete', 'completed'].includes(response.status) ? 'complete' : 'failed';
     // COMP-GSD-7-EVENTLOG: emit the terminal event. complete → final completion
     // deltas + 'completed'; any other terminal (e.g. stratum 'killed') → 'failed'.
     if (terminalStatus === 'complete') {
@@ -475,61 +475,78 @@ export function resolvePreMergeGate(cwd, override) {
 }
 
 async function runOneStep(response, ctx) {
-  const { stratum, cwd, featureCode, blueprintText, gateCommands, preMergeGate } = ctx;
-  const flowId = response.flow_id;
-  const stepId = response.step_id;
-  const stepType = response.type ?? response.step_type;
-  if (stepId) ctx.lastStepId = stepId; // COMP-GSD-4: for the budget pause's stepId
-
-  if (response.status === 'execute_step') {
-    // parallel_dispatch step (the `execute` step)
-    if (stepType === 'parallel_dispatch' || response.tasks) {
-      const outcome = await executeParallelDispatchServer(
-        response,
-        stratum,
-        { cwd, featureCode, gsd: true }, // COMP-GSD-7: gates timing+diff capture
-        null, // progress
-        { write: () => {} }, // streamWriter — no-op for v1
-        cwd,
-        {
-          stuckDetector: ctx.stuckDetector, // COMP-GSD-5 (null in non-gsd callers)
-          // COMP-GSD-6: bump state.json's heartbeat on every task event so a long
-          // task sitting in the dispatch poll loop isn't mistaken for crashed.
-          onHeartbeat: ctx.runState ? () => { try { flushState(ctx, {}); } catch { /* best-effort */ } } : null,
-        },
-      );
-
-      // COMP-GSD-5: a stuck verdict halts the run. Persist the diagnostic +
-      // resume state, then return a terminal `stuck` envelope so runGsd's loop
-      // exits. The task was already cancelled (conflict) inside dispatch.
-      if (outcome && outcome.stuck) {
-        ctx.stuck = outcome.stuck;
-        writeStuckArtifacts(ctx, response, outcome.stuck);
-        return { status: 'stuck', flow_id: flowId, step_id: stepId };
+  const { stratum, cwd, featureCode, localSpec, localSpecDigest } = ctx;
+  const flowId = response.runId;
+
+  if (response.status === 'ready') {
+    const ready = response.ready ?? [];
+    if (ready.length === 0) throw new Error('runGsd: TS engine returned ready without a ready entry');
+    const descriptor = ready.find(isConsumerDescriptor);
+    if (descriptor) {
+      if (!ctx.consumerArtifacts) {
+        ctx.consumerArtifacts = new ConsumerFanoutArtifacts({
+          runId: flowId,
+          targetCwd: cwd,
+          revisionDigest: descriptor.revisionDigest,
+          specDigest: localSpecDigest,
+        });
       }
-
-      // After diffs are merged, capture the touched files for ship_gsd
-      // staging. The clean-workspace precondition above guarantees every
-      // file in the post-execute dirty set is genuinely a GSD-produced change.
-      ctx.filesChanged = collectChangedFiles(cwd);
-      // COMP-GSD-6: checkpoint completed tasks after the execute merge.
-      // COMP-GSD-7-EVENTLOG: emit the execute-phase transition once, then a
-      // task_completed event per newly-completed task.
-      if (ctx.runState) {
-        const completed = collectCompletedTaskIds(cwd, featureCode);
-        flushState(ctx, { phase: 'execute', completedTaskIds: completed });
-        emitPhaseOnce(ctx, 'execute'); // dedupes; runState.phase can't gate this
-        emitCompletionDeltas(ctx, completed);
+      ctx.consumerArtifacts.bindRunRevision({
+        revisionDigest: descriptor.revisionDigest,
+        specDigest: localSpecDigest,
+      });
+      // D7(a): render the exact TaskResult path from the item's task id (the
+      // fanout `over` is decompose_gsd.output.tasks, indexed by itemIndex).
+      const consumerItem = ctx.lastTaskGraph?.tasks?.[descriptor.itemIndex];
+      const taskResultPath = consumerItem?.id
+        ? gsdTaskResultPath(featureCode, consumerItem.id)
+        : undefined;
+      try {
+        return await runConsumerIssuance({
+          descriptor,
+          flowId,
+          stratum,
+          artifacts: ctx.consumerArtifacts,
+          audit: await stratum.audit(flowId),
+          localSpec,
+          // D2(b): onUsage debits each item's agent usage into the cumulative
+          // ledger. D2(a): per-item wall-clock ceiling from gsd.budget.per_task_ms.
+          // D3: the stuck detector observes this item's agent tool events.
+          // D7(a): taskResultPath spells out the exact TaskResult filename.
+          // I3: `gsd: true` is the REAL GSD marker the milestone instrumentation
+          // in runConsumerIssuance keys on — every consumer item dispatched here is
+          // by definition a GSD task, so timing.json + diffs/<id>.diff are written
+          // for the milestone report. The build consumer path omits it (no marker),
+          // so build-mode fanout stays byte-identical.
+          context: { cwd, featureCode, gsd: true, gsdTaskId: consumerItem?.id, filesChanged: ctx.filesChanged, onUsage: (usage) => recordTsAgentUsage(ctx, usage), taskResultPath },
+          // runAndNormalize narrates via progress.debug/warn/info/toolUse — gsd
+          // has no cockpit, so a COMPLETE no-op (not just stepStart/stepDone) is
+          // required or the item throws "progress.debug is not a function".
+          progress: NOOP_PROGRESS,
+          streamWriter: { write() {} },
+          perItemTimeoutMs: ctx.perItemTimeoutMs,
+          stuckDetector: ctx.stuckDetector,
+        });
+      } catch (error) {
+        // D3: a stuck verdict halts the run. Persist the diagnostic + resume
+        // state and return a terminal `stuck` envelope so runGsd's loop exits.
+        if (!(error instanceof ConsumerStuckError)) throw error;
+        const verdict = {
+          taskId: error.taskId,
+          signal: error.verdict?.signal,
+          detail: error.verdict?.detail,
+          attemptCounts: ctx.stuckDetector?.attemptCounts?.(error.taskId) ?? {},
+        };
+        ctx.stuck = verdict;
+        writeStuckArtifacts(ctx, { flow_id: flowId, step_id: descriptor.step ?? descriptor.id }, verdict);
+        return { status: 'stuck', flow_id: flowId, step_id: descriptor.step ?? descriptor.id };
       }
-      // executeParallelDispatchServer returns the next-step dispatch envelope
-      return outcome;
     }
 
-    // ship_gsd: delegate to executeShipStep with filesChanged from execute step
-    // so source files are staged. Agent sandbox blocks git, so commit must
-    // run in-process (mirrors runBuild's special case at lib/build.js:963-981).
-    if (stepId === 'ship_gsd') {
-      const shipResult = await executeShipStep(
+    const step = ready[0];
+    ctx.lastStepId = step.id;
+    if (step.id === 'ship_gsd') {
+      const result = await executeShipStep(
         featureCode,
         cwd,
         cwd,
@@ -537,80 +554,161 @@ async function runOneStep(response, ctx) {
         '',
         null,
       );
-      // executeShipStep stages + commits but does NOT push. Push is a
-      // user-facing operation deferred to the user in v1; runBuild's ship
-      // step doesn't auto-push either. Document via ship intent later.
-      return await stratum.stepDone(flowId, stepId, shipResult);
+      return stratum.stepDone(flowId, step.id, { output: result }, step.dispatchToken);
     }
-
-    // COMP-GSD-5 resume: skip the decompose AGENT entirely and substitute the
-    // persisted task graph (already enriched/repaired during the original run
-    // and already filtered to exclude completedTaskIds). We do NOT re-run
-    // validateAndRepairTaskGraph: enrichTaskGraph would flag the completed
-    // tasks' Boundary Map slices as orphaned (no task in the SUBSET owns them).
-    // Stable task IDs + no re-decompose are the whole point.
-    if (stepId === 'decompose_gsd' && ctx.resumeTaskGraph) {
+    if (step.id === 'decompose_gsd' && ctx.resumeTaskGraph) {
       ctx.lastTaskGraph = ctx.resumeTaskGraph;
-      // COMP-GSD-6: a resume already has the (filtered) task graph — mark
-      // resumeReady so a re-crash during execute resumes rather than restarts.
-      if (ctx.runState) {
-        flushState(ctx, {
-          phase: 'execute',
-          resumeReady: true,
-          decomposedTasks: (ctx.resumeTaskGraph.tasks ?? []).map((t) => ({ ...t })),
-        });
-      }
-      return await stratum.stepDone(flowId, stepId, ctx.resumeTaskGraph);
+      return stratum.stepDone(
+        flowId, step.id, { output: ctx.resumeTaskGraph }, step.dispatchToken,
+      );
     }
 
-    // Single-agent step: dispatch via runAgentText. The agent returns text;
-    // we expect JSON matching the step's output_contract.
-    const prompt = response.intent ?? '';
-    const text = await stratum.runAgentText(response.agent ?? 'claude', prompt, { cwd });
+    // D2(b): dispatch via agentRun (not runAgentText) so the TS complete
+    // envelope's usage is captured and debited into the cumulative ledger.
+    const runOut = await stratum.agentRun(step.agent ?? 'claude', step.do ?? '', { cwd });
+    const text = runOut?.text ?? '';
+    recordTsAgentUsage(ctx, runOut?.usage);
+    // V1: also report usage in the step_done envelope so the ENGINE debits its
+    // flow budget (not just compose's cumulative ledger above).
+    const ordinaryUsage = toEngineUsage(runOut?.usage);
     let result;
     try {
       result = parseJsonFromText(text);
     } catch (err) {
-      throw new Error(
-        `runGsd: step ${stepId} agent did not return parseable JSON: ${err.message}`,
-      );
+      throw new Error(`runGsd: step ${step.id} agent did not return parseable JSON: ${err.message}`);
     }
-
-    // T6 step 7: validate decompose_gsd output and repair missing descriptions.
-    if (stepId === 'decompose_gsd') {
-      // COMP-PAR-MERGE-QUEUE: single-source the per-task instructed gate to the
-      // fast pre-merge gate (== the enforced execute.pre_merge_verify). Full
-      // `pnpm test` is instructed only at ship_gsd.
-      result = validateAndRepairTaskGraph(result, blueprintText, preMergeGate ?? gateCommands);
-      // COMP-GSD-5: remember the ENRICHED graph so a later stuck halt can
-      // persist the full task definitions (with descriptions/produces/consumes)
-      // into pause.json — resume re-dispatches these without re-enriching.
+    if (step.id === 'decompose_gsd') {
+      try {
+        result = validateAndRepairTaskGraph(result, ctx.blueprintText, ctx.preMergeGate ?? ctx.gateCommands);
+      } catch (err) {
+        // F6: an ownership conflict is an expected, retryable rejection. Send a
+        // FAILURE step_done envelope (not a thrown abort) so decompose_gsd's
+        // declared attempts govern — the engine retries with previousFailure
+        // feedback. Genuinely unexpected errors still propagate.
+        if (!(err instanceof TaskGraphOwnershipError) && !(err instanceof TaskGraphDuplicateIdError)) throw err;
+        return stratum.stepDone(
+          flowId, step.id,
+          { failure: err.message, ...(ordinaryUsage ? { usage: ordinaryUsage } : {}) },
+          step.dispatchToken,
+        );
+      }
       ctx.lastTaskGraph = result;
-      // COMP-GSD-6: the task graph now exists → resumeReady true; persist it so a
-      // crash during execute can synthesize a resume graph from state.json.
       if (ctx.runState) {
         flushState(ctx, {
           phase: 'execute',
           resumeReady: true,
-          decomposedTasks: (result.tasks ?? []).map((t) => ({ ...t })),
+          decomposedTasks: (result.tasks ?? []).map((task) => ({ ...task })),
         });
       }
     }
-
-    return await stratum.stepDone(flowId, stepId, result);
+    return stratum.stepDone(
+      flowId, step.id,
+      { output: result, ...(ordinaryUsage ? { usage: ordinaryUsage } : {}) },
+      step.dispatchToken,
+    );
   }
 
-  if (response.status === 'await_gate') {
-    // GSD has no gates in v1. If we hit one, surface it.
-    throw new Error(
-      `runGsd: unexpected gate at step ${stepId}. v1 has no gates in the gsd flow.`,
+  if (response.status === 'running') {
+    const audit = await stratum.audit(flowId);
+    const waiting = Object.entries(audit?.steps ?? {})
+      .find(([, state]) => state?.status === 'waiting_gate');
+    if (!waiting) throw new Error('runGsd: TS engine is running without ready work or a waiting gate');
+    const [gateStepId, gateState] = waiting;
+    const steps = localSpec.flows[localSpec.flows.entry].steps;
+    const gateStep = steps.find((step) => step.id === gateStepId);
+    const predecessorIds = new Set(gateStep?.after ?? []);
+    const fanoutStep = steps.find((step) => predecessorIds.has(step.id) && step.fanout?.dispatch === 'consumer');
+    if (!fanoutStep) {
+      throw new Error(`runGsd: unexpected non-consumer gate ${gateStepId} on the TS path`);
+    }
+    if (!ctx.consumerArtifacts) {
+      ctx.consumerArtifacts = new ConsumerFanoutArtifacts({
+        runId: flowId,
+        targetCwd: cwd,
+        revisionDigest: response.revisionDigest,
+        specDigest: localSpecDigest,
+      });
+    }
+    const artifacts = ctx.consumerArtifacts;
+    artifacts.recordGateBinding({ gateStepId, fanoutStepId: fanoutStep.id });
+    let transaction;
+    let outcome = 'approve';
+    let rationale = 'consumer fanout artifacts merged';
+    try {
+      transaction = artifacts.prepareMerge({
+        gateStepId,
+        gateToken: gateState.gateToken,
+        fanoutStepId: fanoutStep.id,
+        audit,
+      });
+      await artifacts.applyMerge(transaction);
+    } catch (error) {
+      if (!(error instanceof ConsumerMergeDecisionError)) throw error;
+      outcome = gateStep?.gate?.on_revise ? 'revise' : 'kill';
+      rationale = `${error.code}: ${error.message}`;
+      transaction ??= artifacts.journal.mergeTransactions.find(
+        (entry) => entry.gateToken === gateState.gateToken,
+      );
+      if (transaction) artifacts.restoreMergeBaseline(transaction, audit);
+    }
+    const next = await stratum.gateResolve(
+      flowId, gateStepId, outcome, rationale, 'system', gateState.gateToken,
     );
+    artifacts.markGateResolved(transaction, outcome);
+    if (outcome !== 'revise') artifacts.cleanupWorktrees(`GSD merge gate ${outcome}`);
+    if (outcome === 'approve') ctx.filesChanged = collectChangedFiles(cwd);
+    return next;
   }
 
-  throw new Error(`runGsd: unknown response status: ${response.status}`);
+  return response;
+}
+
+/**
+ * F6: raised by validateAndRepairTaskGraph on a files_owned conflict. A typed
+ * class lets the decompose_gsd site distinguish this expected, retryable rejection
+ * (→ failure step_done envelope, engine attempts govern) from a genuinely
+ * unexpected error (which still propagates).
+ */
+export class TaskGraphOwnershipError extends Error {
+  constructor(conflict) {
+    super(`decompose_gsd file-ownership conflict: ${conflict}`);
+    this.name = 'TaskGraphOwnershipError';
+    this.conflict = conflict;
+  }
+}
+
+/**
+ * Raised by validateAndRepairTaskGraph when two tasks share an `id`. Task ids are
+ * the primary key for EVERY GSD id-keyed system: the blackboard, `results/<id>.json`,
+ * the milestone timing/diff instrumentation (keyed by gsdTaskId), and the stuck
+ * detector's per-task bookkeeping. A duplicate id silently cross-contaminates all of
+ * them (last-writer-wins results, inherited detector state), so reject it up front —
+ * a retryable malformed-decompose rejection, same channel as the ownership conflict.
+ */
+export class TaskGraphDuplicateIdError extends Error {
+  constructor(id) {
+    super(`decompose_gsd duplicate task id: ${id} (task ids must be unique)`);
+    this.name = 'TaskGraphDuplicateIdError';
+    this.id = id;
+  }
 }
 
 export function validateAndRepairTaskGraph(taskGraph, blueprintText, gateCommands) {
+  // D5: deterministic file-ownership enforcement — reject overlapping
+  // files_owned before any repair. Two tasks owning the same file would race
+  // in their worktrees and collide at merge; fail loudly with the conflict.
+  const conflict = filesOwnedConflict(taskGraph?.tasks);
+  if (conflict) throw new TaskGraphOwnershipError(conflict);
+
+  // Unique-id enforcement — every id-keyed GSD system (blackboard, results,
+  // milestone instrumentation, stuck detector) assumes task ids are unique.
+  const seenIds = new Set();
+  for (const task of taskGraph?.tasks ?? []) {
+    if (task?.id == null) continue;
+    if (seenIds.has(task.id)) throw new TaskGraphDuplicateIdError(task.id);
+    seenIds.add(task.id);
+  }
+
   // Structural check via enrichTaskGraph. Throws on orphan slice/task —
   // that's a "fail loudly" case (no reliable repair path).
   const enriched = enrichTaskGraph(taskGraph, blueprintText);
@@ -1226,8 +1324,8 @@ function writeBudgetArtifacts(ctx, response, budgetState) {
   writeFileSync(join(dir, 'budget.md'), md);
 
   const pause = {
-    flowId: response.flow_id ?? null,
-    stepId: response.step_id ?? ctx.lastStepId ?? 'execute',
+    flowId: response.runId ?? null,
+    stepId: ctx.lastStepId ?? 'execute',
     kind: 'budget',
     budget: { axis: json.axis, caps: budgetState.caps ?? {}, consumed: budgetState.consumed ?? {} },
     decomposedTasks,
@@ -1263,15 +1361,71 @@ export function writeBudgetFinalSnapshot(ctx, budgetState) {
  * from the stratum budget_state.consumed ({tokens,dispatches,wall_s,dollars}).
  * No-op when budget_state is absent (un-budgeted runs).
  */
-function recordGsdUsageFromState(cwd, featureCode, budgetState) {
+export function recordGsdUsageFromState(cwd, featureCode, budgetState, alreadyRecorded = null) {
   const consumed = budgetState?.consumed;
   if (!consumed) return;
-  recordGsdUsage(join(cwd, '.compose'), featureCode, {
+  const engine = {
     tokens: consumed.tokens ?? 0,
     costUsd: consumed.dollars ?? 0,
     dispatches: consumed.dispatches ?? 0,
     timeMs: Math.round((consumed.wall_s ?? 0) * 1000),
-  });
+  };
+  // G4: the engine ledger is ground truth, but on the TS path it now INCLUDES the
+  // per-invocation usage compose already recorded incrementally into the same
+  // cumulative store (via recordTsAgentUsage, from the step_done envelopes). Fold
+  // only the DELTA — the engine-only debits (e.g. judged predicates) not already
+  // counted — so nothing is double-debited. `alreadyRecorded` is this run's
+  // incremental total (ctx.recordedUsage); absent → full fold.
+  const prior = alreadyRecorded ?? { tokens: 0, costUsd: 0, dispatches: 0, timeMs: 0 };
+  const delta = {
+    tokens: Math.max(0, engine.tokens - (prior.tokens ?? 0)),
+    costUsd: Math.max(0, engine.costUsd - (prior.costUsd ?? 0)),
+    dispatches: Math.max(0, engine.dispatches - (prior.dispatches ?? 0)),
+    timeMs: Math.max(0, engine.timeMs - (prior.timeMs ?? 0)),
+  };
+  if (delta.tokens === 0 && delta.costUsd === 0 && delta.dispatches === 0 && delta.timeMs === 0) return;
+  recordGsdUsage(join(cwd, '.compose'), featureCode, delta);
+}
+
+/**
+ * D7(a): the exact TaskResult path a gsd execute item must write, keyed by the
+ * item's task id. Single-sources the filename with the blackboard reader
+ * (collectBlackboard reads .compose/gsd/<feature>/results/<taskId>.json).
+ */
+export function gsdTaskResultPath(featureCode, taskId) {
+  return `.compose/gsd/${featureCode}/results/${taskId}.json`;
+}
+
+// runAndNormalize narrates through a progress object (debug/warn/info/toolUse/
+// toolSummary/stepStart/stepDone). GSD runs headless with no cockpit, so it
+// hands the consumer loop a COMPLETE no-op — a partial stub throws mid-item.
+const NOOP_PROGRESS = Object.freeze({
+  stepStart() {}, stepDone() {}, debug() {}, warn() {}, info() {},
+  toolUse() {}, toolSummary() {},
+});
+
+/**
+ * D2(b): debit one TS-route agent invocation's usage into the cumulative gsd
+ * ledger. On the TS path the engine's flow ledger never sees compose-dispatched
+ * agents, so compose accounts each dispatch itself. `usage` is the normalized
+ * shape from runAndNormalize ({input_tokens, output_tokens, cost_usd,
+ * duration_ms}) or the raw TS complete usage ({tokens, usd, ms}).
+ */
+export function recordTsAgentUsage(ctx, usage) {
+  if (!usage || !ctx?.cwd || !ctx?.featureCode) return;
+  const tokens = usage.tokens ?? ((usage.input_tokens ?? 0) + (usage.output_tokens ?? 0));
+  const costUsd = usage.cost_usd ?? usage.usd ?? 0;
+  const timeMs = usage.duration_ms ?? usage.ms ?? 0;
+  if (tokens === 0 && costUsd === 0 && timeMs === 0) return;
+  recordGsdUsage(join(ctx.cwd, '.compose'), ctx.featureCode, { tokens, costUsd, timeMs, dispatches: 1 });
+  // G4: remember what THIS run recorded incrementally so the terminal/budget-halt
+  // fold (recordGsdUsageFromState) records only the engine-only delta, never
+  // double-counting these envelope-reported invocations.
+  ctx.recordedUsage ??= { tokens: 0, costUsd: 0, dispatches: 0, timeMs: 0 };
+  ctx.recordedUsage.tokens += tokens;
+  ctx.recordedUsage.costUsd += costUsd;
+  ctx.recordedUsage.timeMs += timeMs;
+  ctx.recordedUsage.dispatches += 1;
 }
 
 /**