@smartmemory/compose 0.2.7-beta → 0.2.9-beta

package/lib/gsd-headless-config.js

@@ -0,0 +1,110 @@
+// lib/gsd-headless-config.js
+//
+// COMP-GSD-6 S05: headless auto-resume policy. Reads `gsd.headless.*` from
+// .compose/compose.json and merges over conservative defaults. Every pause kind
+// is independently overridable (per the product decision): crash and stuck
+// auto-resume by default, budget does NOT (opting in would defeat the GSD-4
+// ceiling), but a user MAY set budget.enabled:true for a fully-unattended burn.
+//
+// Unset config ⇒ defaults ⇒ behavior is a plain run plus supervision.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const HEADLESS_DEFAULTS = Object.freeze({
+  autoResume: {
+    crash: { enabled: true, maxAttempts: 5 },
+    stuck: { enabled: true, maxAttempts: 2 },
+    budget: { enabled: false, maxAttempts: 0 },
+    // COMP-GSD-6-WATCHDOG: a hung child (heartbeat frozen on a live pid) is
+    // killed + resumed like a crash. On by default — that's the whole point of
+    // unattended robustness.
+    hung: { enabled: true, maxAttempts: 3 },
+  },
+  backoff: { baseMs: 2000, factor: 2, maxMs: 60000 },
+  heartbeatStaleMs: 90000,
+  // COMP-GSD-6-WATCHDOG: supervisor poll cadence, SIGTERM→SIGKILL grace, and the
+  // child's independent wall-clock heartbeat cadence (must be < heartbeatStaleMs).
+  watchdogPollMs: 15000,
+  watchdogKillGraceMs: 5000,
+  watchdogHeartbeatMs: 30000,
+});
+
+function num(v, fallback) {
+  return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback;
+}
+function bool(v, fallback) {
+  return typeof v === 'boolean' ? v : fallback;
+}
+
+function mergeKind(override, def) {
+  const o = override ?? {};
+  return {
+    enabled: bool(o.enabled, def.enabled),
+    maxAttempts: num(o.maxAttempts, def.maxAttempts),
+  };
+}
+
+// Merge a raw `gsd.headless` object over HEADLESS_DEFAULTS with per-field type
+// validation (a malformed field falls back to its default, never throws).
+export function resolveHeadlessConfig(raw) {
+  const h = raw && typeof raw === 'object' ? raw : {};
+  const ar = h.autoResume && typeof h.autoResume === 'object' ? h.autoResume : {};
+  const bo = h.backoff && typeof h.backoff === 'object' ? h.backoff : {};
+  const d = HEADLESS_DEFAULTS;
+
+  // COMP-GSD-6-WATCHDOG: enforce the load-bearing invariant
+  // `watchdogHeartbeatMs < heartbeatStaleMs`. The child must restamp its heartbeat
+  // at least twice within the stale window, or a healthy quiet child trips the
+  // watchdog. Two guards:
+  //   - a degenerate stale window (< 2ms, incl. 0) is unusable — there's no room
+  //     for a smaller heartbeat — so it falls back to the default.
+  //   - a heartbeat cadence ≥ the (now positive) stale window is clamped to half
+  //     it (always strictly < stale for stale ≥ 2), rather than honored.
+  let heartbeatStaleMs = num(h.heartbeatStaleMs, d.heartbeatStaleMs);
+  if (heartbeatStaleMs < 2) heartbeatStaleMs = d.heartbeatStaleMs;
+  let watchdogHeartbeatMs = num(h.watchdogHeartbeatMs, d.watchdogHeartbeatMs);
+  if (watchdogHeartbeatMs >= heartbeatStaleMs) {
+    watchdogHeartbeatMs = Math.floor(heartbeatStaleMs / 2);
+  }
+
+  return {
+    autoResume: {
+      crash: mergeKind(ar.crash, d.autoResume.crash),
+      stuck: mergeKind(ar.stuck, d.autoResume.stuck),
+      budget: mergeKind(ar.budget, d.autoResume.budget),
+      hung: mergeKind(ar.hung, d.autoResume.hung),
+    },
+    backoff: {
+      baseMs: num(bo.baseMs, d.backoff.baseMs),
+      factor: num(bo.factor, d.backoff.factor),
+      maxMs: num(bo.maxMs, d.backoff.maxMs),
+    },
+    heartbeatStaleMs,
+    watchdogPollMs: num(h.watchdogPollMs, d.watchdogPollMs),
+    watchdogKillGraceMs: num(h.watchdogKillGraceMs, d.watchdogKillGraceMs),
+    watchdogHeartbeatMs,
+  };
+}
+
+// Read .compose/compose.json gsd.headless.* and resolve against defaults.
+export function readHeadlessConfig(cwd) {
+  const configPath = join(cwd, '.compose', 'compose.json');
+  let raw = {};
+  if (existsSync(configPath)) {
+    try {
+      const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
+      raw = cfg?.gsd?.headless ?? {};
+    } catch {
+      /* malformed config → defaults */
+    }
+  }
+  return resolveHeadlessConfig(raw);
+}
+
+// Backoff for attempt N (1-based): base * factor^(N-1), capped at maxMs.
+export function backoffMs(cfg, attempt) {
+  const { baseMs, factor, maxMs } = cfg.backoff;
+  const raw = baseMs * Math.pow(factor, Math.max(0, attempt - 1));
+  return Math.min(raw, maxMs);
+}

package/lib/gsd-milestone-report.js

@@ -0,0 +1,323 @@
+// lib/gsd-milestone-report.js
+//
+// COMP-GSD-7: milestone report generator. On GSD feature completion (and via
+// `compose gsd report <feature>`), assemble a read-only data model from the
+// persisted run artifacts and render a single self-contained HTML report to
+// docs/gsd-reports/<feature>.html — auto-discovered by the cockpit DocsView.
+//
+// Data sources (all read-only):
+//   .compose/gsd/<f>/state.json        run state + completedAt (gsd-state.js)
+//   .compose/gsd/<f>/blackboard.json   per-task TaskResults (gsd-blackboard.js)
+//   .compose/gsd/<f>/timing.json       per-task elapsed (gsd-timing.js sidecar)
+//   .compose/gsd/<f>/diffs/<id>.diff   per-task diff snapshots (build.js capture)
+//   budget-final.json | budget.json    budget actuals vs caps (gsd-budget shape)
+//
+// HTML shape mirrors server/graph-export.js: one template literal, inline CSS,
+// no external assets. Atomic write mirrors gsd-state.js:44.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { readGsdState } from './gsd-state.js';
+import { read as readBlackboard } from './gsd-blackboard.js';
+import { readTimingSidecar } from './gsd-timing.js';
+import { gsdTaskDiffPath } from './gsd-diff-capture.js';
+import { readGsdEvents } from './gsd-events.js';
+
+const DIFF_INLINE_CAP_BYTES = 200 * 1024; // 200 KB per task
+
+function gsdDir(cwd, featureCode) {
+  return join(cwd, '.compose', 'gsd', featureCode);
+}
+
+function readJsonOrNull(p) {
+  if (!existsSync(p)) return null;
+  try { return JSON.parse(readFileSync(p, 'utf-8')); } catch { return null; }
+}
+
+// ---------- Model assembly ----------
+
+function resolveBudget(cwd, featureCode, opts) {
+  // Precedence: in-process budget_state → budget-final.json → halt budget.json → none.
+  const fromOpts = opts?.budgetState;
+  const src = fromOpts
+    ?? readJsonOrNull(join(gsdDir(cwd, featureCode), 'budget-final.json'))
+    ?? readJsonOrNull(join(gsdDir(cwd, featureCode), 'budget.json'));
+  if (!src || (!src.caps && !src.consumed)) return { configured: false, caps: {}, consumed: {}, axis: null };
+  return { configured: true, caps: src.caps ?? {}, consumed: src.consumed ?? {}, axis: src.axis ?? null };
+}
+
+function readDiff(cwd, featureCode, taskId) {
+  const p = gsdTaskDiffPath(cwd, featureCode, taskId);
+  if (!existsSync(p)) return null;
+  try { return readFileSync(p, 'utf-8'); } catch { return null; }
+}
+
+// COMP-GSD-7-EVENTLOG: map a run-event to a timeline row. Unknown future kinds
+// render their kind verbatim rather than dropping out.
+function eventLabel(e) {
+  switch (e.kind) {
+    case 'run_started': return `Run started (${e.mode ?? 'fresh'})`;
+    case 'phase': return `Phase: ${e.phase ?? '?'}`;
+    case 'task_completed': return `Task completed: ${e.taskId ?? '?'}`;
+    case 'paused': return `Paused (${e.pauseKind ?? '?'})`;
+    case 'completed': return 'Run completed';
+    case 'failed': return `Run failed${e.reason ? `: ${e.reason}` : ''}`;
+    default: return String(e.kind ?? 'event');
+  }
+}
+
+function buildTimeline(state, cwd, featureCode) {
+  // COMP-GSD-7-EVENTLOG: prefer the real append-only event stream. Fall back to
+  // the snapshot-derived timeline only when there are ZERO usable events (a run
+  // that predates the log, or a truncated/torn/corrupt file) — never render an
+  // empty timeline because the file happens to exist.
+  const events = readGsdEvents(cwd, featureCode);
+  if (events.length > 0) {
+    return events.map((e) => ({ label: eventLabel(e), ts: e.ts ?? null }));
+  }
+
+  const dir = gsdDir(cwd, featureCode);
+  const tl = [];
+  if (state.startedAt) tl.push({ label: 'Run started', ts: state.startedAt });
+  if (existsSync(join(dir, 'stuck.json'))) {
+    const s = readJsonOrNull(join(dir, 'stuck.json'));
+    tl.push({ label: `Stuck halt${s?.taskId ? ` (${s.taskId})` : ''}`, ts: s?.ts ?? null });
+  }
+  if (existsSync(join(dir, 'budget.json'))) {
+    const b = readJsonOrNull(join(dir, 'budget.json'));
+    tl.push({ label: `Budget halt${b?.axis ? ` (${b.axis})` : ''}`, ts: b?.ts ?? null });
+  }
+  if (existsSync(join(dir, 'pause.json'))) {
+    const p = readJsonOrNull(join(dir, 'pause.json'));
+    tl.push({ label: `Paused${p?.kind ? ` (${p.kind})` : ''}`, ts: p?.ts ?? null });
+  }
+  if (state.completedAt) {
+    tl.push({ label: `Run ${state.status === 'complete' ? 'completed' : `ended (${state.status})`}`, ts: state.completedAt });
+  }
+  return tl;
+}
+
+/**
+ * Read all persisted artifacts for a completed GSD feature and return a flat,
+ * render-ready model. Returns null if there is no run state at all.
+ */
+export function assembleReportModel(featureCode, cwd, opts = {}) {
+  const state = readGsdState(cwd, featureCode);
+  if (!state) return null;
+
+  const blackboard = readBlackboard(featureCode, { cwd });
+  const timing = readTimingSidecar(cwd, featureCode);
+
+  // Order by decomposedTasks; append any blackboard tasks not in the graph.
+  const order = Array.isArray(state.decomposedTasks)
+    ? state.decomposedTasks.map((t) => t.id).filter(Boolean)
+    : [];
+  const ids = [...order];
+  for (const id of Object.keys(blackboard)) if (!ids.includes(id)) ids.push(id);
+
+  const tasks = ids.map((id) => {
+    const tr = blackboard[id] ?? {};
+    const tm = timing[id] ?? {};
+    const diff = readDiff(cwd, featureCode, id);
+    return {
+      id,
+      status: tr.status ?? 'unknown',
+      attempts: tr.attempts ?? null,
+      filesChanged: Array.isArray(tr.files_changed) ? tr.files_changed : [],
+      summary: tr.summary ?? '',
+      startedAt: tm.startedAt ?? null,
+      completedAt: tm.completedAt ?? null,
+      durationMs: typeof tm.durationMs === 'number' ? tm.durationMs : null,
+      hasDiff: diff != null,
+      diff: diff ?? null,
+    };
+  });
+
+  const completedSet = new Set(Array.isArray(state.completedTaskIds) ? state.completedTaskIds : []);
+  const completed = completedSet.size || tasks.filter((t) => t.status === 'passed').length;
+  const taskCount = tasks.length;
+  const totalWallClockMs = state.startedAt && state.completedAt
+    ? Math.max(0, Date.parse(state.completedAt) - Date.parse(state.startedAt))
+    : null;
+
+  return {
+    feature: featureCode,
+    status: state.status ?? 'unknown',
+    phase: state.phase ?? null,
+    startedAt: state.startedAt ?? null,
+    completedAt: state.completedAt ?? null,
+    flowId: state.flowId ?? null,
+    tasks,
+    budget: resolveBudget(cwd, featureCode, opts),
+    timeline: buildTimeline(state, cwd, featureCode),
+    totals: {
+      taskCount,
+      completed,
+      completionRate: taskCount > 0 ? completed / taskCount : 0,
+      totalWallClockMs,
+    },
+  };
+}
+
+// ---------- HTML render ----------
+
+function esc(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function fmtMs(ms) {
+  if (ms == null) return '—';
+  if (ms < 1000) return `${ms} ms`;
+  const s = ms / 1000;
+  if (s < 60) return `${s.toFixed(1)} s`;
+  const m = Math.floor(s / 60);
+  return `${m}m ${Math.round(s - m * 60)}s`;
+}
+
+const BUDGET_ROWS = [
+  { axis: 'tokens', cap: 'max_tokens', use: 'tokens', fmt: (v) => String(v ?? 0) },
+  { axis: 'agent dispatches', cap: 'max_agent_dispatches', use: 'dispatches', fmt: (v) => String(v ?? 0) },
+  { axis: 'wall-clock (s)', cap: 'ms', use: 'wall_s', fmt: (v) => String(Math.round(v ?? 0)), capFmt: (v) => String(Math.round((v ?? 0) / 1000)) },
+  { axis: 'cost (USD)', cap: 'usd', use: 'dollars', fmt: (v) => Number(v ?? 0).toFixed(4), capFmt: (v) => Number(v ?? 0).toFixed(4) },
+];
+
+function renderBudget(budget) {
+  if (!budget.configured) {
+    return `<p class="muted">Unbudgeted run — no GSD budget caps were enforced.</p>`;
+  }
+  const rows = BUDGET_ROWS
+    .filter((r) => budget.caps[r.cap] != null)
+    .map((r) => {
+      const cap = r.capFmt ? r.capFmt(budget.caps[r.cap]) : String(budget.caps[r.cap]);
+      const used = r.fmt(budget.consumed[r.use]);
+      return `<tr><td>${esc(r.axis)}</td><td>${esc(used)}</td><td>${esc(cap)}</td></tr>`;
+    })
+    .join('\n');
+  if (!rows) return `<p class="muted">Budget configured but no enforced axes recorded.</p>`;
+  return `<table><thead><tr><th>Axis</th><th>Consumed</th><th>Cap</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+
+function renderTaskDiff(task) {
+  if (!task.hasDiff) {
+    const files = task.filesChanged.length
+      ? `<p class="muted">No diff captured. Files changed: ${task.filesChanged.map(esc).join(', ')}</p>`
+      : `<p class="muted">No diff captured.</p>`;
+    return files;
+  }
+  let body = task.diff;
+  let note = '';
+  if (Buffer.byteLength(body, 'utf-8') > DIFF_INLINE_CAP_BYTES) {
+    body = body.slice(0, DIFF_INLINE_CAP_BYTES);
+    note = `<p class="muted">Diff truncated at ${Math.round(DIFF_INLINE_CAP_BYTES / 1024)} KB — see .compose/gsd/&lt;feature&gt;/diffs/${esc(task.id)}.diff for the full text.</p>`;
+  }
+  return `<details><summary>diff (${task.filesChanged.length} file${task.filesChanged.length !== 1 ? 's' : ''})</summary>${note}<pre class="diff">${esc(body)}</pre></details>`;
+}
+
+function renderTasks(tasks) {
+  return tasks.map((t) => `
+    <div class="task">
+      <h3>${esc(t.id)} <span class="status status-${esc(t.status)}">${esc(t.status)}</span></h3>
+      <div class="meta">attempts: ${esc(t.attempts ?? '—')} · files: ${t.filesChanged.length} · elapsed: ${esc(fmtMs(t.durationMs))}</div>
+      ${t.summary ? `<p class="summary">${esc(t.summary)}</p>` : ''}
+      ${renderTaskDiff(t)}
+    </div>`).join('\n');
+}
+
+function renderTimeline(timeline) {
+  if (!timeline.length) return '';
+  const items = timeline.map((e) => `<li><span class="ts">${esc(e.ts ?? '—')}</span> ${esc(e.label)}</li>`).join('\n');
+  return `<ul class="timeline">${items}</ul>`;
+}
+
+/** Pure: model → self-contained HTML string. */
+export function renderReportHtml(model) {
+  const t = model.totals;
+  const pct = `${Math.round(t.completionRate * 100)}%`;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>${esc(model.feature)} — GSD Milestone Report</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { font: 14px/1.5 -apple-system, system-ui, sans-serif; max-width: 980px; margin: 2rem auto; padding: 0 1rem; }
+  h1 { margin-bottom: .25rem; } h2 { margin-top: 2rem; border-bottom: 1px solid #8884; padding-bottom: .25rem; }
+  .sub { color: #888; margin-top: 0; }
+  table { border-collapse: collapse; width: 100%; margin: .5rem 0; }
+  th, td { text-align: left; padding: .35rem .6rem; border-bottom: 1px solid #8883; }
+  .muted { color: #888; }
+  .cards { display: flex; gap: 1rem; flex-wrap: wrap; }
+  .card { border: 1px solid #8884; border-radius: 8px; padding: .75rem 1rem; min-width: 120px; }
+  .card .n { font-size: 1.6rem; font-weight: 600; }
+  .task { border: 1px solid #8884; border-radius: 8px; padding: .75rem 1rem; margin: .75rem 0; }
+  .task h3 { margin: 0 0 .25rem; } .task .meta { color: #888; font-size: .85rem; }
+  .status { font-size: .7rem; padding: .1rem .4rem; border-radius: 4px; background: #8883; vertical-align: middle; }
+  .status-passed { background: #2e7d3233; } .status-failed { background: #c6282833; }
+  pre.diff { overflow: auto; background: #8881; padding: .6rem; border-radius: 6px; font-size: 12px; }
+  ul.timeline { list-style: none; padding-left: 0; } ul.timeline .ts { color: #888; font-variant-numeric: tabular-nums; }
+  footer { margin-top: 3rem; color: #888; font-size: .8rem; }
+</style>
+</head>
+<body>
+<h1>${esc(model.feature)}</h1>
+<p class="sub">GSD milestone report · status <strong>${esc(model.status)}</strong>${model.phase ? ` · phase ${esc(model.phase)}` : ''}</p>
+
+<div class="cards">
+  <div class="card"><div class="n">${t.taskCount}</div>tasks</div>
+  <div class="card"><div class="n">${t.completed}</div>completed</div>
+  <div class="card"><div class="n">${pct}</div>completion</div>
+  <div class="card"><div class="n">${esc(fmtMs(t.totalWallClockMs))}</div>wall-clock</div>
+</div>
+
+<h2>Budget — actuals vs caps</h2>
+${renderBudget(model.budget)}
+
+<h2>Timeline</h2>
+${renderTimeline(model.timeline) || '<p class="muted">No timeline events recorded.</p>'}
+
+<h2>Tasks</h2>
+${renderTasks(model.tasks) || '<p class="muted">No tasks recorded.</p>'}
+
+<footer>
+Generated by COMP-GSD-7. Per-task elapsed time is poll-granularity-approximate
+(bounded by the dispatch poll interval). Diffs over ${Math.round(DIFF_INLINE_CAP_BYTES / 1024)} KB are truncated.
+</footer>
+</body>
+</html>`;
+}
+
+// ---------- Write + orchestrate ----------
+
+export function reportPath(cwd, featureCode) {
+  return join(cwd, 'docs', 'gsd-reports', `${featureCode}.html`);
+}
+
+/** Atomic write to docs/gsd-reports/<feature>.html. Returns the path. */
+export function writeGsdReport(cwd, featureCode, html) {
+  const target = reportPath(cwd, featureCode);
+  mkdirSync(join(cwd, 'docs', 'gsd-reports'), { recursive: true });
+  const tmp = `${target}.tmp`;
+  if (existsSync(tmp)) { try { unlinkSync(tmp); } catch { /* ignore */ } }
+  writeFileSync(tmp, html);
+  renameSync(tmp, target);
+  return target;
+}
+
+/**
+ * Assemble → render → write. Returns { ok, path, model, html } on success or
+ * { ok:false, error } when there is no run state to report on. Never throws on
+ * a missing-state condition (callers use it best-effort).
+ */
+export function generateGsdMilestoneReport(featureCode, cwd, opts = {}) {
+  const model = assembleReportModel(featureCode, cwd, opts);
+  if (!model) return { ok: false, error: `no GSD run state for ${featureCode} (no state.json)` };
+  const html = renderReportHtml(model);
+  const path = writeGsdReport(cwd, featureCode, html);
+  return { ok: true, path, model, html };
+}

package/lib/gsd-state.js

@@ -0,0 +1,165 @@
+// lib/gsd-state.js
+//
+// COMP-GSD-6 S01: continuous gsd run-state checkpoint (.compose/gsd/<f>/state.json).
+//
+// The load-bearing primitive for headless crash recovery, `compose gsd query`,
+// and the live-run lock. A run flushes this file continuously (init pre-plan,
+// per-task heartbeat, post-decompose, terminal); a hard crash leaves the last
+// checkpoint with status:"running" + a dead pid, which readers derive as
+// "crashed". Plain JSON, atomic tmp+rename — no SQLite (mirrors writeActiveBuild
+// in lib/build.js). `pidAlive` lives here canonically (gsd.js imports it) to
+// keep the gsd.js <-> gsd-state.js dependency one-directional.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DEFAULT_STALE_MS = 90000;
+
+function gsdDir(cwd, featureCode) {
+  return join(cwd, '.compose', 'gsd', featureCode);
+}
+
+export function gsdStatePath(cwd, featureCode) {
+  return join(gsdDir(cwd, featureCode), 'state.json');
+}
+
+// COMP-GSD-6-WATCHDOG: best-effort removal of pause.json. After the supervisor
+// kills a hung child, clearing pause.json lets loadResumeTaskGraph's crash-bridge
+// recover from the current state.json (it prefers pause.json when present). A
+// path+rm helper lives here (gsd-state owns the gsd dir layout) so the supervisor
+// needn't import the heavy gsd.js.
+export function clearGsdPause(cwd, featureCode) {
+  const p = join(gsdDir(cwd, featureCode), 'pause.json');
+  try { if (existsSync(p)) rmSync(p, { force: true }); } catch { /* best-effort */ }
+}
+
+// COMP-GSD-7-EVENTLOG: best-effort removal of a prior run's halt artifacts
+// (stuck.{json,md}, budget.{json,md}). A fresh run clears these at its planning
+// checkpoint so the milestone report's timeline — and its snapshot fallback,
+// which reads these files — reflects only the current run, not a stale earlier
+// halt. A clean complete clears only pause.json, so these can otherwise linger.
+export function clearGsdHaltArtifacts(cwd, featureCode) {
+  const dir = gsdDir(cwd, featureCode);
+  for (const name of ['stuck.json', 'stuck.md', 'budget.json', 'budget.md']) {
+    const p = join(dir, name);
+    try { if (existsSync(p)) rmSync(p, { force: true }); } catch { /* best-effort */ }
+  }
+}
+
+// Authoritative liveness probe. Signal 0 checks existence without delivering a
+// signal. EPERM => the process exists but isn't ours (still alive) — this is the
+// semantics crash detection needs (cf. build.js isProcessAlive, which returns
+// false on EPERM and is therefore wrong for this purpose).
+export function pidAlive(pid) {
+  if (!pid || typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+// Atomic write: stamp heartbeatAt, write to a tmp sibling, rename into place.
+// Returns the object as persisted (with heartbeatAt). The caller owns `pid`
+// (the runtime sets process.pid; tests inject a synthetic pid) — unlike
+// writeActiveBuild, we do NOT force process.pid here.
+export function writeGsdState(cwd, featureCode, state) {
+  const dir = gsdDir(cwd, featureCode);
+  mkdirSync(dir, { recursive: true });
+  const persisted = { ...state, heartbeatAt: new Date().toISOString() };
+  const target = gsdStatePath(cwd, featureCode);
+  const tmp = `${target}.tmp`;
+  writeFileSync(tmp, JSON.stringify(persisted, null, 2));
+  renameSync(tmp, target);
+  return persisted;
+}
+
+export function readGsdState(cwd, featureCode) {
+  const p = gsdStatePath(cwd, featureCode);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+// Reader-side status derivation. Dead pid is the ONLY crash signal; a stale
+// heartbeat on a live pid is advisory (heartbeatStale) — never a crash verdict,
+// because a healthy long task legitimately sits in the dispatch poll loop.
+//
+// Returns { status, heartbeatStale }.
+//   running + live pid + fresh hb  -> { running, false }
+//   running + live pid + stale hb  -> { running, true }
+//   running + dead pid             -> { crashed, false }
+//   <terminal>                     -> { <terminal>, false }   (complete|stuck|budget|failed)
+//   null/no status                 -> { absent, false }
+export function deriveRunStatus(state, { staleMs = DEFAULT_STALE_MS, now = Date.now() } = {}) {
+  if (!state || !state.status) return { status: 'absent', heartbeatStale: false };
+  if (state.status !== 'running') {
+    return { status: state.status, heartbeatStale: false };
+  }
+  if (!pidAlive(state.pid)) {
+    return { status: 'crashed', heartbeatStale: false };
+  }
+  const hb = state.heartbeatAt ? Date.parse(state.heartbeatAt) : null;
+  const heartbeatStale = hb != null && !Number.isNaN(hb) && now - hb > staleMs;
+  return { status: 'running', heartbeatStale };
+}
+
+// COMP-GSD-6: synthesize the `compose gsd query` snapshot (contracts/
+// gsd-state.json#/definitions/query). Fixed source precedence so the
+// pre-dispatch cumulative-budget refusal (budget.json, no state.json) isn't
+// mislabeled 'absent': state.json -> pause.json -> budget.json -> absent.
+// Pure synchronous reads — no LLM/server/Stratum (~ms).
+export function buildGsdQuery(cwd, featureCode, { staleMs = DEFAULT_STALE_MS, now = Date.now() } = {}) {
+  const dir = gsdDir(cwd, featureCode);
+
+  // 1. state.json
+  const state = readGsdState(cwd, featureCode);
+  if (state) {
+    const { status, heartbeatStale } = deriveRunStatus(state, { staleMs, now });
+    const total = Array.isArray(state.decomposedTasks) ? state.decomposedTasks.length : 0;
+    const completed = Array.isArray(state.completedTaskIds) ? state.completedTaskIds.length : 0;
+    return {
+      feature: featureCode,
+      status,
+      phase: state.phase ?? null,
+      heartbeatStale,
+      progress: { completed, total },
+      resumeReady: !!state.resumeReady,
+      pid: state.pid ?? null,
+      flowId: state.flowId ?? null,
+      heartbeatAt: state.heartbeatAt ?? null,
+      budget: state.budget ?? null,
+    };
+  }
+
+  // 2. pause.json (paused, no live state.json — e.g. a pre-GSD-6 halt)
+  const pausePath = join(dir, 'pause.json');
+  if (existsSync(pausePath)) {
+    try {
+      const p = JSON.parse(readFileSync(pausePath, 'utf-8'));
+      const kind = p.kind === 'budget' ? 'budget' : 'stuck';
+      return {
+        feature: featureCode,
+        status: kind,
+        phase: 'execute',
+        pause: { kind, detail: p.detail ?? null, stuckTaskId: p.stuckTaskId ?? null },
+      };
+    } catch { /* fall through */ }
+  }
+
+  // 3. budget.json (pre-dispatch cumulative refusal — writes budget.json, no state)
+  const budgetPath = join(dir, 'budget.json');
+  if (existsSync(budgetPath)) {
+    try {
+      const b = JSON.parse(readFileSync(budgetPath, 'utf-8'));
+      return { feature: featureCode, status: 'budget', budget: b };
+    } catch { /* fall through */ }
+  }
+
+  // 4. absent
+  return { feature: featureCode, status: 'absent' };
+}