@smartmemory/compose 0.2.7-beta → 0.2.9-beta

package/lib/gsd.js

@@ -13,7 +13,7 @@
 // V1 limitation: runtime task-to-task handoff is not implemented; tasks see
 // only spec-level upstream context (Boundary Map declarations) per blueprint.
 
-import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, rmSync, statSync, renameSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
@@ -22,8 +22,17 @@ import { StratumMcpClient } from './stratum-mcp-client.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 } from './gsd-blackboard.js';
+import { writeAll, validate as validateTaskResult, read as readBlackboard } from './gsd-blackboard.js';
 import { executeParallelDispatchServer, executeShipStep } from './build.js';
+import { GsdStuckDetector, DEFAULT_THRESHOLDS } from './gsd-stuck.js';
+import { readGsdBudgetConfig, buildBudgetBlock, injectBudget, composeBudgetDiagnostic } 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.
+import { writeGsdState, readGsdState, gsdStatePath, pidAlive, clearGsdHaltArtifacts } from './gsd-state.js';
+import { generateGsdMilestoneReport } from './gsd-milestone-report.js';
+import { readHeadlessConfig } from './gsd-headless-config.js';
+import { appendGsdEvent, clearGsdEvents } from './gsd-events.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(__dirname, '..');
@@ -38,6 +47,15 @@ export async function runGsd(featureCode, opts = {}) {
   }
   const cwd = opts.cwd ?? process.cwd();
 
+  // COMP-GSD-6: a FRESH (non-resume) run must not inherit a prior run's
+  // state.json. Clear it up front so that if a precondition below throws BEFORE
+  // the planning checkpoint, NO running state remains → the headless supervisor
+  // (and `query`) read 'absent' → fatal-by-absence, never a stale 'complete'
+  // success. A resume keeps the old state.json (the crash-bridge may need it).
+  if (!opts.resume) {
+    try { rmSync(gsdStatePath(cwd, featureCode), { force: true }); } catch { /* ignore */ }
+  }
+
   // 1. Validate preconditions: blueprint exists + Boundary Map ok
   const blueprintPath = join(cwd, 'docs', 'features', featureCode, 'blueprint.md');
   if (!existsSync(blueprintPath)) {
@@ -62,12 +80,36 @@ export async function runGsd(featureCode, opts = {}) {
     );
   }
 
-  // 2. Refuse to start in a dirty workspace BEFORE any Stratum side effects.
+  // 2. COMP-GSD-5 resume branch — runs BEFORE the dirty-tree check so a
+  // pid/mode-guard failure (the more specific precondition) is reported first.
+  // --resume reads pause.json, guards on ownership (no live pid) +
+  // mode==='gsd' (mirrors `compose fix --resume`), and seeds a precomputed task
+  // graph = decomposedTasks MINUS completedTaskIds so the execute step
+  // re-dispatches only the unfinished work. Completed results already live in
+  // the blackboard. resumeTaskGraph (when set) makes runOneStep skip the
+  // decompose agent entirely → stable task IDs, no re-decompose.
+  // COMP-GSD-4: read+guard the resume graph here for guard-ordering, but DEFER
+  // the atomic pause.lock claim (claim:false) — runGsd claims inside its try so
+  // the finally always releases it (no strand on re-halt/refusal/throw).
+  let resumeTaskGraph = null;
+  if (opts.resume) {
+    resumeTaskGraph = loadResumeTaskGraph(cwd, featureCode, { claim: false });
+  }
+
+  // 3. Refuse to start in a dirty workspace BEFORE any Stratum side effects.
   // v1 rationale: alternatives (baseline subtract + post-execute delta) drop
   // legitimate edits to pre-existing dirty files. Refuse-if-dirty makes
   // post-execute dirty set unambiguous: every entry is GSD-produced.
+  //
+  // On --resume the GSD control plane (.compose/gsd/<feature>/) legitimately
+  // carries the prior run's pause.json/blackboard.json/results — that's the
+  // resume STATE, not an unrelated edit — so exclude it from the dirty set.
   if (!opts.allowDirtyWorkspace) {
-    const startingDirty = collectChangedFiles(cwd);
+    let startingDirty = collectChangedFiles(cwd);
+    if (opts.resume) {
+      const ctrlPrefix = `.compose/gsd/${featureCode}/`;
+      startingDirty = startingDirty.filter((f) => !f.startsWith(ctrlPrefix));
+    }
     if (startingDirty.length > 0) {
       throw new Error(
         `runGsd: working tree must be clean to ensure ship_gsd stages only GSD-produced changes. ` +
@@ -77,38 +119,197 @@ export async function runGsd(featureCode, opts = {}) {
     }
   }
 
-  // 3. Resolve gateCommands. loadProjectConfig() does not merge defaults, so
+  // 4. Resolve gateCommands. loadProjectConfig() does not merge defaults, so
   // explicit fallback here.
   const gateCommands = resolveGateCommands(cwd, opts.gateCommands);
 
   // 4. Load pipeline spec
   const specPath = join(PACKAGE_ROOT, 'pipelines', 'gsd.stratum.yaml');
-  const specYaml = readFileSync(specPath, 'utf-8');
+  // 4a. COMP-GSD-4: inject the stratum flow budget block from `gsd.budget.*`.
+  // injectBudget is IDENTITY when nothing is configured, so an un-budgeted gsd
+  // run (and plain `compose build`) is byte-identical.
+  const budgetCfg = readGsdBudgetConfig(cwd);
+  const specYaml = injectBudget(readFileSync(specPath, 'utf-8'), budgetCfg);
+
+  // 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 —
+  // re-dispatching would immediately re-trip. Runs before the try, so no
+  // pause.lock is held yet (the claim is the first statement inside the try).
+  const cumulative = buildBudgetBlock(budgetCfg).cumulative;
+  if (cumulative) {
+    const chk = checkGsdCumulativeBudget(join(cwd, '.compose'), featureCode, cumulative);
+    if (chk.exceeded) {
+      writeCumulativeRefusal(cwd, featureCode, chk, cumulative);
+      return { status: 'budget', flowId: null, axis: 'cumulative', reason: chk.reason };
+    }
+  }
+
+  // 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.
+  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();
+  // 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
+  // (EEXIST) from deleting the winner's lock on its way out.
+  let lockClaimed = false;
+  let runLockClaimed = false;
+  // COMP-GSD-6: the in-memory run-state, threaded through stepCtx and flushed to
+  // state.json. Declared here so the catch/finally can read it.
+  let stepCtx = null;
+  // COMP-GSD-6-WATCHDOG: independent wall-clock heartbeat timer (see below).
+  // Declared here so the finally can always clear it.
+  let heartbeatTimer = null;
   try {
-    let response = await stratum.plan(specYaml, 'gsd', {
-      featureCode,
-      gateCommands,
-    });
-    const flowId = response.flow_id;
+    // COMP-GSD-6: claim the live-run lock BEFORE any stratum side effect, so two
+    // fresh `compose gsd <same-feature>` runs can't race the results dir. Takes
+    // over a stale lock (dead owner) and refuses a live one.
+    claimRunLock(cwd, featureCode);
+    runLockClaimed = true;
+
+    // COMP-GSD-4: claim the resume lock HERE (first statement in the try) so the
+    // finally releases it on EVERY exit — budget/stuck re-halt, throw, or clean
+    // finish. loadResumeTaskGraph above already read+guarded (claim:false).
+    if (opts.resume) {
+      claimResumeLock(cwd, featureCode); // throws EEXIST → finally sees lockClaimed=false
+      lockClaimed = true;
+    }
+
+    // COMP-GSD-6: pre-plan "planning" checkpoint. A crash during plan/decompose
+    // now leaves a dead-pid state.json — the failed-vs-fatal boundary. A throw
+    // BEFORE this point (preconditions) leaves no running state → fatal by
+    // absence; a throw AFTER → the catch converts it to status:"failed".
+    // On resume, seed the planning checkpoint from the (in-memory) resume graph
+    // so that if THIS resume re-crashes before its decompose step repopulates
+    // state.json, the crash-bridge still has a task graph to recover from
+    // (otherwise the fresh empty checkpoint would clobber the prior good data).
+    const resumeTasks = opts.resume ? (resumeTaskGraph?.tasks ?? []).map((t) => ({ ...t })) : [];
+    const initialState = {
+      feature: featureCode,
+      flowId: null,
+      pid: process.pid,
+      mode: 'gsd',
+      phase: 'planning',
+      status: 'running',
+      startedAt: new Date().toISOString(),
+      headless: !!opts.headless,
+      attempt: opts.attempt ?? 1,
+      resumeReady: opts.resume && resumeTasks.length > 0,
+      decomposedTasks: resumeTasks,
+      completedTaskIds: collectCompletedTaskIds(cwd, featureCode),
+    };
 
     // Track files merged into the base cwd by the execute step so ship_gsd
     // can stage them. executeShipStep's default filter only stages feature
     // docs unless context.filesChanged is provided.
-    const stepCtx = {
+    stepCtx = {
       stratum, cwd, featureCode, blueprintText, gateCommands,
       filesChanged: [],
+      stuckDetector,
+      resumeTaskGraph,
+      stuck: null, // set by runOneStep on a stuck verdict
+      runState: initialState, // COMP-GSD-6: flushState merges into this
+      // COMP-GSD-7-EVENTLOG: tasks already completed at run start (a resume
+      // preloads them) are seeded as already-emitted so the appended log never
+      // re-fires task_completed for prior-session completions.
+      emittedCompletions: new Set(initialState.completedTaskIds),
+      // COMP-GSD-7-EVENTLOG: phases already announced (dedupe — runState.phase is
+      // set to 'execute' before the merge checkpoint, so it can't gate emission).
+      emittedPhases: new Set(),
     };
+    flushState(stepCtx, {}); // write the planning checkpoint
+
+    // COMP-GSD-7-EVENTLOG: at the planning checkpoint — AFTER preconditions
+    // passed (so a failed fresh invocation never wipes a prior run's history) —
+    // a fresh run truncates the event log and clears stale halt artifacts so the
+    // timeline reflects only this run; a resume appends to the existing log.
+    if (!opts.resume) {
+      clearGsdEvents(cwd, featureCode);
+      clearGsdHaltArtifacts(cwd, featureCode);
+    }
+    appendGsdEvent(cwd, featureCode, 'run_started', {
+      mode: opts.resume ? 'resume' : 'fresh',
+      attempt: opts.attempt ?? 1,
+    });
+
+    // COMP-GSD-6-WATCHDOG: an INDEPENDENT wall-clock heartbeat. The existing
+    // heartbeat only advances on agent push-events (onHeartbeat below), so a
+    // quiet-but-healthy task would look stale. This timer restamps state.json's
+    // heartbeat on a fixed cadence whenever the event loop is still turning — so
+    // a stale heartbeat genuinely means the loop is WEDGED (or the process dead),
+    // which is what the headless watchdog keys its hung-kill on. .unref() so it
+    // never holds the process open; cleared in finally. Same empty-patch restamp
+    // onHeartbeat uses, so it's behavior-compatible.
+    //
+    // Gated to SUPERVISED children only (GSD_HEADLESS_ATTEMPT, set by the
+    // supervisor's spawner) — the supervisor is the sole watcher, so an
+    // interactive `compose gsd` stays byte-identical (no extra state.json writes).
+    if (process.env.GSD_HEADLESS_ATTEMPT != null) {
+      const hbMs = readHeadlessConfig(cwd).watchdogHeartbeatMs;
+      heartbeatTimer = setInterval(() => {
+        try { if (stepCtx?.runState) flushState(stepCtx, {}); } catch { /* best-effort */ }
+      }, hbMs);
+      heartbeatTimer.unref?.();
+    }
 
-    // 5. Status loop
-    while (response.status !== 'complete' && response.status !== 'killed') {
+    let response = await stratum.plan(specYaml, 'gsd', {
+      featureCode,
+      gateCommands,
+    });
+    const flowId = response.flow_id;
+    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).
+    while (
+      response.status !== 'complete' &&
+      response.status !== 'killed' &&
+      response.status !== 'stuck' &&
+      response.status !== 'budget_exhausted'
+    ) {
       response = await runOneStep(response, stepCtx);
     }
 
+    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
+      // verdict (the stuck path returns early, before the execute-merge delta),
+      // then record the pause.
+      emitCompletionDeltas(stepCtx);
+      appendGsdEvent(cwd, featureCode, 'paused', { pauseKind: 'stuck', taskId: stepCtx.stuck?.taskId ?? null });
+      flushState(stepCtx, { status: 'stuck' }); // COMP-GSD-6 terminal checkpoint
+      return {
+        status: 'stuck',
+        flowId,
+        stuckTaskId: stepCtx.stuck?.taskId ?? null,
+        signal: stepCtx.stuck?.signal ?? null,
+      };
+    }
+
+    if (response.status === 'budget_exhausted') {
+      // COMP-GSD-4: the stratum flow budget tripped. The flow already
+      // 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 ?? {};
+      writeBudgetArtifacts(stepCtx, response, budgetState);
+      recordGsdUsageFromState(cwd, featureCode, budgetState);
+      const axis = composeBudgetDiagnostic(budgetState, { feature: featureCode }).json.axis;
+      // COMP-GSD-7-EVENTLOG: flush pre-halt completions, then record the pause.
+      emitCompletionDeltas(stepCtx);
+      appendGsdEvent(cwd, featureCode, 'paused', { pauseKind: 'budget', axis });
+      flushState(stepCtx, { status: 'budget' }); // COMP-GSD-6 terminal checkpoint
+      return { status: 'budget', flowId, axis, consumed: budgetState.consumed ?? {}, caps: budgetState.caps ?? {} };
+    }
+
     // 6. Post-step blackboard finalization — read each task's TaskResult JSON
     // and write the consolidated blackboard.
     const blackboard = collectBlackboard(cwd, featureCode);
@@ -116,12 +317,85 @@ export async function runGsd(featureCode, opts = {}) {
       await writeAll(featureCode, blackboard, { cwd });
     }
 
+    // 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') {
+      // 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);
+      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) {
+        try {
+          writeBudgetFinalSnapshot(stepCtx, response.budget_state);
+        } catch (err) {
+          console.warn(`[gsd] budget-final snapshot failed: ${err.message}`);
+        }
+      }
+    }
+
+    // COMP-GSD-6: terminal state.json flush. Only 'complete' is a success; any
+    // 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';
+    // COMP-GSD-7-EVENTLOG: emit the terminal event. complete → final completion
+    // deltas + 'completed'; any other terminal (e.g. stratum 'killed') → 'failed'.
+    if (terminalStatus === 'complete') {
+      emitCompletionDeltas(stepCtx);
+      appendGsdEvent(cwd, featureCode, 'completed', {});
+    } else {
+      appendGsdEvent(cwd, featureCode, 'failed', { reason: response.status ?? 'unknown' });
+    }
+    flushState(stepCtx, { status: terminalStatus, phase: 'done', completedAt: new Date().toISOString() });
+
+    // COMP-GSD-7: best-effort milestone report on a clean complete. A report
+    // failure must never fail the run — it is a derived artifact.
+    if (terminalStatus === 'complete') {
+      try {
+        const r = generateGsdMilestoneReport(featureCode, cwd);
+        if (!r.ok) console.warn(`[gsd] milestone report skipped: ${r.error}`);
+      } catch (err) {
+        console.warn(`[gsd] milestone report generation failed: ${err.message}`);
+      }
+    }
+
+    // Return the normalized closed-vocabulary status (not the raw stratum status)
+    // so the CLI/callers don't mistake a 'killed' terminal for success.
     return {
-      status: response.status,
+      status: terminalStatus,
       flowId,
       blackboardEntries: Object.keys(blackboard).length,
     };
+  } catch (err) {
+    // COMP-GSD-6: an orderly throw AFTER the planning checkpoint becomes a
+    // terminal status:"failed" so the supervisor treats it as non-recoverable
+    // (vs a hard crash → status stays "running" + dead pid → reader-derived
+    // "crashed"). Guard on a persisted running state so pre-checkpoint throws
+    // (which left no running state) stay fatal-by-absence, not "failed".
+    if (stepCtx?.runState && readGsdState(cwd, featureCode)?.status === 'running') {
+      try { flushState(stepCtx, { status: 'failed' }); } catch { /* best-effort */ }
+      // COMP-GSD-7-EVENTLOG: record the failure (only when a run actually started
+      // — a pre-checkpoint throw left no running state and gets no event). Append
+      // is best-effort; never mask the original error.
+      appendGsdEvent(cwd, featureCode, 'failed', { reason: err?.message ?? 'error' });
+    }
+    throw err;
   } finally {
+    // COMP-GSD-6-WATCHDOG: stop the independent heartbeat timer.
+    if (heartbeatTimer) clearInterval(heartbeatTimer);
+    // COMP-GSD-6: release the live-run lock if THIS process claimed it.
+    if (runLockClaimed) releaseRunLock(cwd, featureCode);
+    // COMP-GSD-4: release the resume claim ONLY if THIS process claimed it
+    // (ownership-aware — never clobber a concurrent run's valid claim, and don't
+    // release after losing the claim race). pause.json persists for --resume
+    // unless a clean complete cleared it above.
+    if (lockClaimed) releasePauseLock(cwd, featureCode);
     if (ownsStratum) {
       try { await stratum.disconnect?.(); } catch { /* best-effort */ }
     }
@@ -153,6 +427,7 @@ async function runOneStep(response, 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)
@@ -160,15 +435,40 @@ async function runOneStep(response, ctx) {
       const outcome = await executeParallelDispatchServer(
         response,
         stratum,
-        { cwd, featureCode },
+        { 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 };
+      }
+
       // 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);
+      }
       // executeParallelDispatchServer returns the next-step dispatch envelope
       return outcome;
     }
@@ -191,6 +491,26 @@ async function runOneStep(response, ctx) {
       return await stratum.stepDone(flowId, stepId, shipResult);
     }
 
+    // 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) {
+      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);
+    }
+
     // Single-agent step: dispatch via runAgentText. The agent returns text;
     // we expect JSON matching the step's output_contract.
     const prompt = response.intent ?? '';
@@ -207,6 +527,19 @@ async function runOneStep(response, ctx) {
     // T6 step 7: validate decompose_gsd output and repair missing descriptions.
     if (stepId === 'decompose_gsd') {
       result = validateAndRepairTaskGraph(result, blueprintText, 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.
+      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 })),
+        });
+      }
     }
 
     return await stratum.stepDone(flowId, stepId, result);
@@ -362,3 +695,562 @@ function collectBlackboard(cwd, featureCode) {
   }
   return out;
 }
+
+// ===========================================================================
+// COMP-GSD-5: stuck detection + resume
+// ===========================================================================
+
+function gsdDir(cwd, featureCode) {
+  return join(cwd, '.compose', 'gsd', featureCode);
+}
+
+// ===========================================================================
+// COMP-GSD-6: run.lock (live-run exclusivity) + state.json flush helpers
+// ===========================================================================
+
+const RUN_LOCK_STALE_MS = 90000;
+
+function runLockDir(cwd, featureCode) {
+  return join(gsdDir(cwd, featureCode), 'run.lock');
+}
+
+// Atomically take over a stale lock dir. The naive `rmSync` + `mkdirSync` is
+// racy — two reclaimers can both see "stale", both rm, and one deletes the
+// other's fresh lock. renameSync IS atomic, so only one racer can rename the
+// stale dir aside; the loser gets ENOENT. The winner removes the renamed copy
+// and re-creates the lock; if a NEW claimant raced into the freed name first,
+// our mkdir gets EEXIST and we (correctly) report we lost. Returns true iff WE
+// recreated the lock.
+function takeoverStaleLock(lockPath) {
+  const aside = `${lockPath}.stale.${process.pid}.${Date.now()}`;
+  try {
+    renameSync(lockPath, aside); // atomic — loser gets ENOENT
+  } catch {
+    return false; // another racer already took it over (or it vanished)
+  }
+  try { rmSync(aside, { recursive: true, force: true }); } catch { /* best-effort */ }
+  try {
+    mkdirSync(lockPath);
+    return true;
+  } catch (err) {
+    if (err.code === 'EEXIST') return false; // a fresh claimant won the freed name
+    throw err;
+  }
+}
+
+// Read the owning pid for a run.lock: run.lock/owner.json first (lock-local
+// record), then state.json (Codex review precedence). Returns a number or null.
+function runLockOwnerPid(cwd, featureCode) {
+  const ownerPath = join(runLockDir(cwd, featureCode), 'owner.json');
+  if (existsSync(ownerPath)) {
+    try {
+      const o = JSON.parse(readFileSync(ownerPath, 'utf-8'));
+      if (typeof o.pid === 'number') return o.pid;
+    } catch { /* fall through to state.json */ }
+  }
+  const state = readGsdState(cwd, featureCode);
+  return typeof state?.pid === 'number' ? state.pid : null;
+}
+
+// Atomic live-run claim, taken BEFORE the first stratum side effect. mkdirSync
+// is atomic on POSIX: the loser gets EEXIST. On EEXIST we take over a STALE lock
+// — owner pid dead, OR (no owner record AND lock-dir mtime older than the stale
+// window, which covers the sub-ms gap before owner.json lands). A live owner
+// refuses. Writes run.lock/owner.json {pid,startedAt} immediately after winning.
+export function claimRunLock(cwd, featureCode) {
+  const dir = gsdDir(cwd, featureCode);
+  mkdirSync(dir, { recursive: true });
+  const lock = runLockDir(cwd, featureCode);
+  const write = () => {
+    writeFileSync(
+      join(lock, 'owner.json'),
+      JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }, null, 2),
+    );
+  };
+  try {
+    mkdirSync(lock);
+    write();
+    return;
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+  }
+  // EEXIST — decide stale vs live.
+  const ownerPid = runLockOwnerPid(cwd, featureCode);
+  let stale = false;
+  if (typeof ownerPid === 'number') {
+    stale = !pidAlive(ownerPid);
+  } else {
+    // No owner record yet: fall back to lock-dir age.
+    try {
+      stale = Date.now() - statSync(lock).mtimeMs > RUN_LOCK_STALE_MS;
+    } catch { stale = true; }
+  }
+  if (!stale) {
+    throw new Error(
+      `runGsd: another gsd run owns ${featureCode} (.compose/gsd/${featureCode}/run.lock, ` +
+        `pid ${ownerPid ?? 'unknown'} alive). Refusing to start a concurrent run.`,
+    );
+  }
+  // Atomic stale takeover (rename-aside). If we lose the takeover race, another
+  // run now legitimately owns the feature — refuse.
+  if (!takeoverStaleLock(lock)) {
+    throw new Error(
+      `runGsd: another gsd run claimed ${featureCode} during stale-lock takeover. ` +
+        `Refusing to start a concurrent run.`,
+    );
+  }
+  write();
+}
+
+export function releaseRunLock(cwd, featureCode) {
+  rmSync(runLockDir(cwd, featureCode), { recursive: true, force: true });
+}
+
+// Merge a patch into ctx.runState and atomically flush state.json. ctx.runState
+// is the single in-memory source of truth; every flush restamps heartbeatAt.
+function flushState(ctx, patch) {
+  ctx.runState = { ...(ctx.runState ?? {}), ...patch };
+  writeGsdState(ctx.cwd, ctx.featureCode, ctx.runState);
+}
+
+// COMP-GSD-7-EVENTLOG: emit a `task_completed` event for each task that has
+// completed since the last emit. Dedupes via ctx.emittedCompletions (seeded from
+// the run's initial completed snapshot, so a resume never re-fires prior-session
+// completions). Called at the execute-merge checkpoint and before each halt
+// (stuck/budget) — the halt paths return early, before the merge checkpoint.
+function emitCompletionDeltas(ctx, completedIds) {
+  if (!ctx?.emittedCompletions) return;
+  const ids = completedIds ?? collectCompletedTaskIds(ctx.cwd, ctx.featureCode);
+  for (const id of ids) {
+    if (!id || ctx.emittedCompletions.has(id)) continue;
+    ctx.emittedCompletions.add(id);
+    appendGsdEvent(ctx.cwd, ctx.featureCode, 'task_completed', { taskId: id });
+  }
+}
+
+// COMP-GSD-7-EVENTLOG: emit a `phase` event the first time a phase is entered.
+// Deduped via ctx.emittedPhases — runState.phase is set to 'execute' before the
+// execute-merge checkpoint runs, so it can't itself gate the emission.
+function emitPhaseOnce(ctx, phase) {
+  if (!ctx?.emittedPhases || ctx.emittedPhases.has(phase)) return;
+  ctx.emittedPhases.add(phase);
+  appendGsdEvent(ctx.cwd, ctx.featureCode, 'phase', { phase });
+}
+
+/**
+ * Build a GsdStuckDetector from `.compose/compose.json` `gsd.stuck.*`, falling
+ * back to documented defaults (sameFileEdits=3, errorRepeats=3,
+ * noProgressCalls=8, wallClockMs=600000). Config keys use snake_case to match
+ * the design table; the detector takes camelCase.
+ */
+export function buildStuckDetector(cwd) {
+  const cfg = readGsdStuckConfig(cwd);
+  return new GsdStuckDetector({
+    sameFileEdits: cfg.same_file_edits ?? DEFAULT_THRESHOLDS.sameFileEdits,
+    errorRepeats: cfg.error_repeats ?? DEFAULT_THRESHOLDS.errorRepeats,
+    noProgressCalls: cfg.no_progress_calls ?? DEFAULT_THRESHOLDS.noProgressCalls,
+    wallClockMs: cfg.wall_clock_ms ?? DEFAULT_THRESHOLDS.wallClockMs,
+  });
+}
+
+function readGsdStuckConfig(cwd) {
+  const configPath = join(cwd, '.compose', 'compose.json');
+  if (!existsSync(configPath)) return {};
+  try {
+    const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+    return cfg?.gsd?.stuck ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Task ids whose VALIDATED TaskResult is already known — the union of the
+ * persisted blackboard and any per-task result files that validate. Lenient
+ * (does NOT throw on a bad file) because at stuck-halt time the run is being
+ * abandoned, not finalized.
+ */
+function collectCompletedTaskIds(cwd, featureCode) {
+  const done = new Set(Object.keys(readBlackboard(featureCode, { cwd }) ?? {}));
+  const dir = join(gsdDir(cwd, featureCode), 'results');
+  if (existsSync(dir)) {
+    for (const f of readdirSync(dir).filter((x) => x.endsWith('.json'))) {
+      try {
+        const parsed = JSON.parse(readFileSync(join(dir, f), 'utf-8'));
+        if (validateTaskResult(parsed).ok) done.add(f.replace(/\.json$/, ''));
+      } catch { /* skip unreadable */ }
+    }
+  }
+  return [...done];
+}
+
+/** Best-effort unified diff of the whole working tree (for the stuck.md triage). */
+function captureWorkingDiff(cwd) {
+  try {
+    return execSync('git diff HEAD', {
+      cwd, encoding: 'utf-8', timeout: 5000, maxBuffer: 4 * 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Persist the stuck diagnostic (stuck.md + stuck.json, per
+ * contracts/gsd-stuck.json#stuck) AND the resume state (pause.json, per
+ * #pause). decomposedTasks is the FULL task list (from the dispatch envelope),
+ * persisted so --resume does not re-decompose. completedTaskIds comes from the
+ * blackboard / results dir.
+ */
+function writeStuckArtifacts(ctx, dispatchResponse, verdict) {
+  const { cwd, featureCode } = ctx;
+  const dir = gsdDir(cwd, featureCode);
+  mkdirSync(dir, { recursive: true });
+  const ts = new Date().toISOString();
+
+  // Persist the FULLY-ENRICHED task graph (captured at decompose) so --resume
+  // re-dispatches the unfinished subset WITHOUT re-decomposing or re-enriching.
+  // Fall back to the dispatch envelope's tasks only if enrichment wasn't seen.
+  const sourceTasks = ctx.lastTaskGraph?.tasks ?? dispatchResponse.tasks ?? [];
+  const decomposedTasks = sourceTasks.map((t) => ({ ...t }));
+  const completedTaskIds = collectCompletedTaskIds(cwd, featureCode);
+  const partialDiff = captureWorkingDiff(cwd);
+
+  const stuck = {
+    feature: featureCode,
+    taskId: verdict.taskId,
+    signal: verdict.signal,
+    detail: verdict.detail,
+    attemptCounts: verdict.attemptCounts ?? {},
+    ts,
+  };
+  if (partialDiff) stuck.partialDiff = partialDiff;
+  writeFileSync(join(dir, 'stuck.json'), JSON.stringify(stuck, null, 2) + '\n');
+
+  const pause = {
+    flowId: dispatchResponse.flow_id,
+    stepId: dispatchResponse.step_id,
+    stuckTaskId: verdict.taskId,
+    signal: verdict.signal,
+    detail: verdict.detail,
+    decomposedTasks,
+    completedTaskIds,
+    pid: process.pid,
+    mode: 'gsd',
+    ts,
+  };
+  writeFileSync(join(dir, 'pause.json'), JSON.stringify(pause, null, 2) + '\n');
+
+  writeFileSync(join(dir, 'stuck.md'), renderStuckMarkdown(stuck, pause));
+}
+
+function renderStuckMarkdown(stuck, pause) {
+  const remaining = pause.decomposedTasks
+    .map((t) => t.id)
+    .filter((id) => !pause.completedTaskIds.includes(id));
+  return `# GSD stuck: ${stuck.feature}
+
+**Signal:** \`${stuck.signal}\`
+**Stuck task:** \`${stuck.taskId}\`
+**Detected:** ${stuck.ts}
+
+## What happened
+
+${stuck.detail}
+
+Attempt counts at halt:
+- same-file edits (max across files): ${stuck.attemptCounts.sameFileEdits ?? 0}
+- error repeats (max across hashes): ${stuck.attemptCounts.errorRepeats ?? 0}
+- consecutive no-progress calls: ${stuck.attemptCounts.noProgressCalls ?? 0}
+
+The in-flight task was cancelled and the run halted cleanly.
+
+## Resume or abort
+
+Completed tasks (already in the blackboard, will be skipped): ${pause.completedTaskIds.length ? pause.completedTaskIds.map((x) => `\`${x}\``).join(', ') : '(none)'}
+Tasks that will re-dispatch on resume: ${remaining.length ? remaining.map((x) => `\`${x}\``).join(', ') : '(none)'}
+
+- **Resume:** \`compose gsd ${stuck.feature} --resume\` — re-dispatches the unfinished tasks into fresh worktrees.
+- **Abort:** delete \`.compose/gsd/${stuck.feature}/pause.json\` and start over.
+
+State for resume is in \`pause.json\` (schema: \`contracts/gsd-stuck.json#/definitions/pause\`).
+`;
+}
+
+/**
+ * --resume: read pause.json, enforce the ownership + mode guard (mirrors
+ * `compose fix --resume`, bin/compose.js:1933), and return the persisted task
+ * graph filtered to exclude completedTaskIds. Throws (caller surfaces the
+ * message + exits 1) when there is nothing to resume or the guard fails.
+ *
+ * COMP-GSD-4: `claim` (default true) controls the atomic pause.lock ownership
+ * claim. runGsd passes `{claim:false}` and claims later (claimResumeLock) as
+ * the first statement INSIDE its try, so the run-loop's finally always releases
+ * the lock — no strand on a budget/stuck re-halt or a pre-dispatch throw. The
+ * CLI/test callers keep the default (read+guard+claim in one call).
+ */
+export function loadResumeTaskGraph(cwd, featureCode, { claim = true } = {}) {
+  const pausePath = join(gsdDir(cwd, featureCode), 'pause.json');
+  let pause;
+  if (existsSync(pausePath)) {
+    try {
+      pause = JSON.parse(readFileSync(pausePath, 'utf-8'));
+    } catch (err) {
+      throw new Error(`runGsd: pause.json for ${featureCode} is unreadable: ${err.message}`);
+    }
+  } else {
+    // COMP-GSD-6 crash bridge: a hard crash never reaches the stuck/budget halt
+    // paths that write pause.json. If state.json shows a running run with a DEAD
+    // pid and a populated task graph (resumeReady), synthesize a pause-shaped
+    // object so the unfinished subset can be re-dispatched through the same
+    // guards/filtering below. An EMPTY graph (crashed pre/at decompose) is NOT
+    // resumable here — it (correctly) falls through to the throw; the supervisor
+    // restarts such runs fresh rather than --resume.
+    const state = readGsdState(cwd, featureCode);
+    if (
+      state && state.status === 'running' && !pidAlive(state.pid) &&
+      Array.isArray(state.decomposedTasks) && state.decomposedTasks.length > 0
+    ) {
+      pause = {
+        flowId: state.flowId ?? null,
+        stepId: state.lastStepId ?? 'execute',
+        decomposedTasks: state.decomposedTasks,
+        completedTaskIds: state.completedTaskIds ?? [],
+        pid: state.pid,
+        mode: 'gsd',
+        ts: state.heartbeatAt ?? new Date().toISOString(),
+      };
+    } else {
+      throw new Error(
+        `runGsd: no pause.json to resume for ${featureCode}. ` +
+          `Nothing to resume — run \`compose gsd ${featureCode}\` to start fresh.`,
+      );
+    }
+  }
+
+  // Mode guard: refuse to resume a non-gsd pause file.
+  if (pause.mode && pause.mode !== 'gsd') {
+    throw new Error(
+      `runGsd: cannot --resume: pause.json for ${featureCode} is in ${pause.mode} mode, not gsd.`,
+    );
+  }
+
+  // Ownership guard: refuse if the recorded pid is still alive. A resumable
+  // pause is one whose writing process has EXITED — a live pid means another
+  // run still owns this feature (mirrors `compose fix --resume`). We do not
+  // make a self-pid exception: if a live process holds the pause, resuming is
+  // unsafe regardless of whether that pid happens to match ours.
+  if (typeof pause.pid === 'number' && pidAlive(pause.pid)) {
+    throw new Error(
+      `runGsd: cannot --resume: pid ${pause.pid} still owns this gsd run (process is live). ` +
+        `Wait for it to exit (or remove a stale pause.json) before resuming.`,
+    );
+  }
+
+  const tasks = Array.isArray(pause.decomposedTasks) ? pause.decomposedTasks : [];
+  if (tasks.length === 0) {
+    throw new Error(`runGsd: pause.json for ${featureCode} has no decomposedTasks to resume.`);
+  }
+  const completed = new Set(pause.completedTaskIds ?? []);
+  const remaining = tasks
+    .filter((t) => !completed.has(t.id))
+    .map((t) => {
+      // A completed dependency is already satisfied (its result is in the
+      // blackboard); strip it from depends_on so the re-dispatched subgraph is
+      // self-consistent and a remaining task does not wait on a task that will
+      // never be re-dispatched (COMP-GSD-5 Codex review residual).
+      if (!Array.isArray(t.depends_on) || t.depends_on.length === 0) return t;
+      const deps = t.depends_on.filter((id) => !completed.has(id));
+      return deps.length === t.depends_on.length ? t : { ...t, depends_on: deps };
+    });
+  if (remaining.length === 0) {
+    // Everything already completed — nothing to re-dispatch. Treat as clean.
+    throw new Error(
+      `runGsd: all tasks for ${featureCode} are already completed; nothing to re-dispatch. ` +
+        `Delete pause.json to finish.`,
+    );
+  }
+  if (claim) claimResumeLock(cwd, featureCode);
+  return { tasks: remaining };
+}
+
+/**
+ * Atomic ownership claim (COMP-GSD-5 Codex review, HIGH). `mkdirSync` is an
+ * atomically exclusive create, so two concurrent --resume invocations cannot
+ * both claim — the loser gets EEXIST and refuses.
+ *
+ * COMP-GSD-6: a STALE claim left by a crashed --resume is now auto-recovered.
+ * The HOLDER of pause.lock writes its own pid into pause.lock/owner.json (NOT
+ * pause.json.pid, which is the original crashed run's pid — always dead at
+ * resume time and so useless for liveness). Takeover when that holder pid is
+ * dead, OR no owner record exists and the lock-dir mtime is older than the
+ * stale window. TOCTOU-safe: remove + re-attempt the atomic mkdir; a concurrent
+ * winner still wins.
+ */
+export function claimResumeLock(cwd, featureCode) {
+  const claimPath = join(gsdDir(cwd, featureCode), 'pause.lock');
+  const writeOwner = () => {
+    try {
+      writeFileSync(
+        join(claimPath, 'owner.json'),
+        JSON.stringify({ pid: process.pid, ts: new Date().toISOString() }, null, 2),
+      );
+    } catch { /* best-effort; mtime fallback still protects takeover */ }
+  };
+  try {
+    mkdirSync(claimPath);
+    writeOwner();
+    return;
+  } catch (err) {
+    if (err.code !== 'EEXIST') throw err;
+  }
+  // EEXIST — decide stale vs live by the lock HOLDER's own owner record.
+  let holderPid = null;
+  const ownerPath = join(claimPath, 'owner.json');
+  if (existsSync(ownerPath)) {
+    try {
+      const o = JSON.parse(readFileSync(ownerPath, 'utf-8'));
+      if (typeof o.pid === 'number') holderPid = o.pid;
+    } catch { /* fall through to mtime */ }
+  }
+  let stale = false;
+  if (typeof holderPid === 'number') {
+    stale = !pidAlive(holderPid);
+  } else {
+    try {
+      stale = Date.now() - statSync(claimPath).mtimeMs > RUN_LOCK_STALE_MS;
+    } catch { stale = true; }
+  }
+  if (!stale) {
+    throw new Error(
+      `runGsd: a resume claim already exists for ${featureCode} ` +
+        `(.compose/gsd/${featureCode}/pause.lock, pid ${holderPid ?? 'unknown'} alive). ` +
+        `Another --resume may be in progress; if none is, remove that directory to clear a stale claim.`,
+    );
+  }
+  // Atomic stale takeover (rename-aside) — a concurrent reclaimer can't delete
+  // our fresh lock. If we lose the race, refuse.
+  if (!takeoverStaleLock(claimPath)) {
+    throw new Error(
+      `runGsd: another --resume claimed ${featureCode} during stale-claim takeover; retry.`,
+    );
+  }
+  writeOwner();
+}
+
+/**
+ * COMP-GSD-4: release ONLY the resume ownership claim (pause.lock), leaving
+ * pause.json intact for the next --resume. Called in runGsd's finally on every
+ * exit so a budget/stuck re-halt, cumulative refusal, or pre-dispatch throw
+ * never strands the lock. Idempotent (force) — a no-op when no lock was claimed.
+ */
+function releasePauseLock(cwd, featureCode) {
+  try { rmSync(join(gsdDir(cwd, featureCode), 'pause.lock'), { recursive: true, force: true }); } catch { /* best-effort */ }
+}
+
+/**
+ * COMP-GSD-4: persist the budget halt diagnostic (budget.json + budget.md, via
+ * composeBudgetDiagnostic) AND the resume state (pause.json, kind:'budget').
+ * Mirrors writeStuckArtifacts but carries the `budget` block instead of the
+ * stuck-specific fields. decomposedTasks comes from the enriched graph so
+ * --resume re-dispatches the unfinished subset without re-decomposing.
+ */
+function writeBudgetArtifacts(ctx, response, budgetState) {
+  const { cwd, featureCode } = ctx;
+  const dir = gsdDir(cwd, featureCode);
+  mkdirSync(dir, { recursive: true });
+  const ts = new Date().toISOString();
+
+  const sourceTasks = ctx.lastTaskGraph?.tasks ?? response.tasks ?? [];
+  const decomposedTasks = sourceTasks.map((t) => ({ ...t }));
+  const completedTaskIds = collectCompletedTaskIds(cwd, featureCode);
+
+  const { json, md } = composeBudgetDiagnostic(budgetState, { feature: featureCode, decomposedTasks, completedTaskIds });
+  writeFileSync(join(dir, 'budget.json'), JSON.stringify(json, null, 2) + '\n');
+  writeFileSync(join(dir, 'budget.md'), md);
+
+  const pause = {
+    flowId: response.flow_id ?? null,
+    stepId: response.step_id ?? ctx.lastStepId ?? 'execute',
+    kind: 'budget',
+    budget: { axis: json.axis, caps: budgetState.caps ?? {}, consumed: budgetState.consumed ?? {} },
+    decomposedTasks,
+    completedTaskIds,
+    pid: process.pid,
+    mode: 'gsd',
+    ts,
+  };
+  writeFileSync(join(dir, 'pause.json'), JSON.stringify(pause, null, 2) + '\n');
+}
+
+/**
+ * COMP-GSD-7: on a clean complete, snapshot the run's final budget actuals-vs-caps
+ * to budget-final.json so the milestone report has them retroactively (a clean
+ * complete writes no budget.json — only halts do). Distinct filename from the
+ * halt artifact budget.json (which buildGsdQuery's precedence reads). Atomic write.
+ */
+export function writeBudgetFinalSnapshot(ctx, budgetState) {
+  const { cwd, featureCode } = ctx;
+  const dir = gsdDir(cwd, featureCode);
+  mkdirSync(dir, { recursive: true });
+  const decomposedTasks = (ctx.runState?.decomposedTasks ?? []).map((t) => ({ ...t }));
+  const completedTaskIds = collectCompletedTaskIds(cwd, featureCode);
+  const { json } = composeBudgetDiagnostic(budgetState, { feature: featureCode, decomposedTasks, completedTaskIds });
+  const target = join(dir, 'budget-final.json');
+  const tmp = `${target}.tmp`;
+  writeFileSync(tmp, JSON.stringify(json, null, 2) + '\n');
+  renameSync(tmp, target);
+}
+
+/**
+ * COMP-GSD-4: append a run's consumed usage to the cumulative ledger. Sourced
+ * 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) {
+  const consumed = budgetState?.consumed;
+  if (!consumed) return;
+  recordGsdUsage(join(cwd, '.compose'), featureCode, {
+    tokens: consumed.tokens ?? 0,
+    costUsd: consumed.dollars ?? 0,
+    dispatches: consumed.dispatches ?? 0,
+    timeMs: Math.round((consumed.wall_s ?? 0) * 1000),
+  });
+}
+
+/**
+ * COMP-GSD-4: write a budget refusal diagnostic when the cumulative ceiling is
+ * already spent (pre-dispatch). No pause.json — nothing was dispatched, so
+ * there is no run to resume; the user raises the cap or runs --reset-budget.
+ */
+function writeCumulativeRefusal(cwd, featureCode, chk, limits) {
+  const dir = gsdDir(cwd, featureCode);
+  mkdirSync(dir, { recursive: true });
+  const ts = new Date().toISOString();
+  const json = { feature: featureCode, kind: 'budget', axis: 'cumulative', reason: chk.reason, usage: chk.usage, limits, ts };
+  writeFileSync(join(dir, 'budget.json'), JSON.stringify(json, null, 2) + '\n');
+  const md = [
+    `# GSD budget refusal — ${featureCode}`,
+    '',
+    `**${chk.reason}**`,
+    '',
+    `Cumulative usage: ${chk.usage.totalTokens} tokens, $${(chk.usage.totalCostUsd ?? 0).toFixed(4)}.`,
+    '',
+    'This feature has already spent its cumulative `gsd.budget.cumulative.*` ceiling.',
+    'Raise the cap in `.compose/compose.json`, or clear the ledger:',
+    '',
+    '```',
+    `compose gsd ${featureCode} --reset-budget`,
+    '```',
+    '',
+  ].join('\n');
+  writeFileSync(join(dir, 'budget.md'), md);
+}
+
+function clearPauseFile(cwd, featureCode) {
+  const dir = gsdDir(cwd, featureCode);
+  try { rmSync(join(dir, 'pause.json'), { force: true }); } catch { /* best-effort */ }
+  // Release the resume ownership claim dir (COMP-GSD-5 Codex review) alongside it.
+  try { rmSync(join(dir, 'pause.lock'), { recursive: true, force: true }); } catch { /* best-effort */ }
+}