@smartmemory/compose 0.2.8-beta → 0.2.10-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, writeFileSync, existsSync, readdirSync, mkdirSync, rmSync } 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';
@@ -27,11 +27,22 @@ 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, '..');
 
 const DEFAULT_GATE_COMMANDS = ['pnpm lint', 'pnpm build', 'pnpm test'];
+// COMP-PAR-MERGE-QUEUE: the fast per-task pre-merge gate (lint + build, no full
+// test suite). Enforced in each task's worktree before its diff merges; the full
+// `pnpm test` runs once at ship_gsd. Single-sourced into both the enforced gate
+// (execute.pre_merge_verify) and the instructed gate (task descriptions).
+const DEFAULT_FAST_GATE = ['pnpm lint', 'pnpm build'];
 
 // ---------- Public API ----------
 
@@ -41,6 +52,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)) {
@@ -107,6 +127,8 @@ export async function runGsd(featureCode, opts = {}) {
   // 4. Resolve gateCommands. loadProjectConfig() does not merge defaults, so
   // explicit fallback here.
   const gateCommands = resolveGateCommands(cwd, opts.gateCommands);
+  // COMP-PAR-MERGE-QUEUE: the fast per-task pre-merge gate (lint+build).
+  const preMergeGate = resolvePreMergeGate(cwd, opts.preMergeGate);
 
   // 4. Load pipeline spec
   const specPath = join(PACKAGE_ROOT, 'pipelines', 'gsd.stratum.yaml');
@@ -143,7 +165,20 @@ export async function runGsd(featureCode, opts = {}) {
   // 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 {
+    // 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).
@@ -152,22 +187,91 @@ export async function runGsd(featureCode, opts = {}) {
       lockClaimed = true;
     }
 
-    let response = await stratum.plan(specYaml, 'gsd', {
-      featureCode,
-      gateCommands,
-    });
-    const flowId = response.flow_id;
+    // 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 = {
-      stratum, cwd, featureCode, blueprintText, gateCommands,
+    stepCtx = {
+      stratum, cwd, featureCode, blueprintText, gateCommands, preMergeGate,
       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?.();
+    }
+
+    let response = await stratum.plan(specYaml, 'gsd', {
+      featureCode,
+      gateCommands,
+      pre_merge_gate: preMergeGate,
+    });
+    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
@@ -177,13 +281,38 @@ export async function runGsd(featureCode, opts = {}) {
       response.status !== 'complete' &&
       response.status !== 'killed' &&
       response.status !== 'stuck' &&
-      response.status !== 'budget_exhausted'
+      response.status !== 'budget_exhausted' &&
+      response.status !== 'error'   // COMP-PAR-MERGE-QUEUE: terminal step failure (e.g. retries_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
+      // 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,
@@ -201,6 +330,10 @@ export async function runGsd(featureCode, opts = {}) {
       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 ?? {} };
     }
 
@@ -218,14 +351,73 @@ export async function runGsd(featureCode, opts = {}) {
       // 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
@@ -257,8 +449,32 @@ export function resolveGateCommands(cwd, override) {
   return [...DEFAULT_GATE_COMMANDS];
 }
 
+// COMP-PAR-MERGE-QUEUE: resolve the fast per-task pre-merge gate. Mirrors
+// resolveGateCommands but defaults to lint+build (no full test suite). Honors
+// `.compose/compose.json#preMergeGate`, else falls back to the non-test subset
+// of `gateCommands`, else DEFAULT_FAST_GATE.
+export function resolvePreMergeGate(cwd, override) {
+  if (Array.isArray(override) && override.length > 0) return override;
+  const configPath = join(cwd, '.compose', 'compose.json');
+  if (existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+      if (Array.isArray(cfg.preMergeGate) && cfg.preMergeGate.length > 0) {
+        return cfg.preMergeGate;
+      }
+      if (Array.isArray(cfg.gateCommands) && cfg.gateCommands.length > 0) {
+        const fast = cfg.gateCommands.filter((c) => !/\btest\b/.test(c));
+        if (fast.length > 0) return fast;
+      }
+    } catch {
+      /* fall through to default */
+    }
+  }
+  return [...DEFAULT_FAST_GATE];
+}
+
 async function runOneStep(response, ctx) {
-  const { stratum, cwd, featureCode, blueprintText, gateCommands } = 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;
@@ -270,11 +486,16 @@ 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)
+        {
+          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 +
@@ -290,6 +511,15 @@ async function runOneStep(response, ctx) {
       // 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;
     }
@@ -320,6 +550,15 @@ async function runOneStep(response, ctx) {
     // 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);
     }
 
@@ -338,11 +577,23 @@ 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-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.
       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);
@@ -507,6 +758,139 @@ 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,
@@ -662,17 +1046,41 @@ State for resume is in \`pause.json\` (schema: \`contracts/gsd-stuck.json#/defin
  */
 export function loadResumeTaskGraph(cwd, featureCode, { claim = true } = {}) {
   const pausePath = join(gsdDir(cwd, featureCode), 'pause.json');
-  if (!existsSync(pausePath)) {
-    throw new Error(
-      `runGsd: no pause.json to resume for ${featureCode}. ` +
-        `Nothing to resume — run \`compose gsd ${featureCode}\` to start fresh.`,
-    );
-  }
   let pause;
-  try {
-    pause = JSON.parse(readFileSync(pausePath, 'utf-8'));
-  } catch (err) {
-    throw new Error(`runGsd: pause.json for ${featureCode} is unreadable: ${err.message}`);
+  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.
@@ -687,7 +1095,7 @@ export function loadResumeTaskGraph(cwd, featureCode, { claim = true } = {}) {
   // 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' && isPidAlive(pause.pid)) {
+  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.`,
@@ -724,26 +1132,65 @@ export function loadResumeTaskGraph(cwd, featureCode, { claim = true } = {}) {
 /**
  * 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. We deliberately do NOT
- * auto-take-over a pre-existing claim: stale-claim recovery (a crashed resume's
- * leftover) has an inherent TOCTOU race and is GSD-6's (crash-recovery) job,
- * built on this same pause-state. A claim left by a crashed resume is cleared
- * manually (message below) until GSD-6 lands.
+ * 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 new Error(
-        `runGsd: a resume claim already exists for ${featureCode} ` +
-          `(.compose/gsd/${featureCode}/pause.lock). Another --resume may be in progress; ` +
-          `if none is, remove that directory to clear a stale claim, then retry.`,
-      );
-    }
-    throw 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();
 }
 
 /**
@@ -791,6 +1238,25 @@ function writeBudgetArtifacts(ctx, response, budgetState) {
   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}).
@@ -836,17 +1302,6 @@ function writeCumulativeRefusal(cwd, featureCode, chk, limits) {
   writeFileSync(join(dir, 'budget.md'), md);
 }
 
-function isPidAlive(pid) {
-  try {
-    // signal 0 probes existence without sending a signal.
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    // ESRCH = no such process; EPERM = exists but not ours (still alive).
-    return err.code === 'EPERM';
-  }
-}
-
 function clearPauseFile(cwd, featureCode) {
   const dir = gsdDir(cwd, featureCode);
   try { rmSync(join(dir, 'pause.json'), { force: true }); } catch { /* best-effort */ }