@tekyzinc/gsd-t 3.29.11 → 4.0.12

package/bin/headless-auto-spawn.cjs

@@ -1,711 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * GSD-T Headless Auto-Spawn — Detached headless continuation
- *
- * Every GSD-T command spawn routes through `autoSpawnHeadless()` to a
- * detached child process running `gsd-t headless {command} --log`. The
- * interactive session never blocks on the child (`child.unref()`), so the
- * user retains their terminal and can work on unrelated tasks. On child
- * completion, a macOS notification fires (T2). The interactive session
- * surfaces the result via a read-back banner on the next `gsd-t-resume`
- * or `gsd-t-status` call (T4).
- *
- * Zero external dependencies (Node.js built-ins only).
- *
- * Contract: .gsd-t/contracts/headless-default-contract.md v2.0.0
- *   - v2.0.0 (M43 D4): channel-separation invariant. Every command spawns.
- *     No opt-out flag, no context-meter threshold gating, no `--in-session`
- *     escape hatch. `shouldSpawnHeadless` is a constant `() => true`. The
- *     `watch` parameter is accepted for caller backward-compat for one
- *     version but ignored (deprecation warning emitted once per process).
- * Consumers: every command file that spawns subagents (execute, wave, quick,
- *            integrate, debug, scan, verify, complete-milestone, test-sync,
- *            scan, gap-analysis, populate, feature, project, partition);
- *            the `/gsd` router (Step 2 action-turn handoff).
- */
-
-const fs = require("fs");
-const path = require("path");
-const { spawn } = require("child_process");
-const {
-  acquireHandoffLock,
-  releaseHandoffLock,
-  // waitForLockRelease — NOT consumed here. The child-side wait is
-  // performed by `commands/gsd-t-resume.md` Step 0 (wired in m36
-  // watch-loop Task 4); it calls waitForLockRelease(projectDir,
-  // sessionId) before reading the continue-here file.
-} = require("./handoff-lock.cjs");
-
-// ── Constants ────────────────────────────────────────────────────────────────
-
-const SESSIONS_DIR_REL = path.join(".gsd-t", "headless-sessions");
-const LOG_DIR_REL = ".gsd-t"; // headless-{id}.log lives directly in .gsd-t
-
-// M50 D2 — Whitelist of commands that touch UI / tests. Centralized constant
-// referenced by the spawn-gate (`_isTestingOrUICommand`). When any of these
-// commands is about to spawn for a project where `hasUI(projectDir) === true`
-// and `hasPlaywright(projectDir) === false`, the gate auto-installs Playwright
-// before the spawn proceeds. See playwright-bootstrap-contract.md §3 +
-// m50-integration-points.md "E2E Specs Server Lifecycle".
-const TESTING_OR_UI_COMMANDS = new Set([
-  "gsd-t-execute",
-  "gsd-t-test-sync",
-  "gsd-t-verify",
-  "gsd-t-quick",
-  "gsd-t-wave",
-  "gsd-t-milestone",
-  "gsd-t-complete-milestone",
-  "gsd-t-debug",
-  "gsd-t-integrate",
-]);
-
-function _isTestingOrUICommand(command) {
-  if (typeof command !== "string" || !command) return false;
-  // Accept both raw command names and prefixed variants ("execute" or "gsd-t-execute").
-  const normalized = command.startsWith("gsd-t-") ? command : `gsd-t-${command}`;
-  return TESTING_OR_UI_COMMANDS.has(normalized);
-}
-
-// ── Exports ──────────────────────────────────────────────────────────────────
-
-module.exports = {
-  autoSpawnHeadless,
-  makeSessionId,
-  writeSessionFile,
-  writeContinueHereFile,
-  markSessionCompleted,
-  // M43 D4 — channel-separation invariant. The helper is retained for
-  // backward-compat with any caller that imported it from a v1.x consumer;
-  // it now unconditionally returns true. See headless-default-contract
-  // v2.0.0 §Invariants.
-  shouldSpawnHeadless: () => true,
-  // M49 — exported for tests. Synchronous probe; never throws.
-  _probeDashboardLazy,
-  // M50 D2 — exported for tests. Whitelist + classifier, both synchronous.
-  TESTING_OR_UI_COMMANDS,
-  _isTestingOrUICommand,
-};
-
-// M43 D4 — one-shot deprecation banner when a caller still passes `watch`
-// (or the never-shipped `inSession`). Module-level flag avoids log spam.
-let _deprecatedWatchWarned = false;
-
-// ── autoSpawnHeadless ────────────────────────────────────────────────────────
-
-/**
- * @param {{
- *   command: string,
- *   args?: string[],
- *   continue_from?: string,
- *   projectDir?: string,
- *   context?: object,
- *   sessionContext?: object,
- *   sessionId?: string,
- *   watch?: boolean,
- *   spawnType?: 'primary' | 'validation',
- *   env?: object,
- *   workerModel?: string
- * }} opts
- * @returns {{ id: string | null, pid: number | null, logPath: string | null, timestamp: string, mode: 'headless' | 'in-context' }}
- */
-function autoSpawnHeadless(opts) {
-  const command = opts.command;
-  const args = opts.args || [];
-  const continue_from = opts.continue_from || ".";
-  const projectDir = opts.projectDir || process.cwd();
-  const context = opts.context || opts.sessionContext || null;
-  // M44 D9 Step 3 — optional per-call env overrides layered over the inherited
-  // process.env. Used by `runDispatch` in gsd-t-parallel.cjs to forward
-  // GSD_T_WORKER_TASK_IDS / _WORKER_INDEX / _WORKER_TOTAL to each fan-out
-  // child so the child knows which task subset to handle. Purely additive —
-  // callers that don't pass `env` get the pre-M44-D9 behavior unchanged.
-  const envOverride = (opts.env && typeof opts.env === "object") ? opts.env : null;
-  // M43 D4 — `watch` is accepted for caller backward-compat but IGNORED.
-  // `inSession` was never shipped; accept+ignore for the same reason.
-  // Under headless-default-contract v2.0.0 every spawn goes headless; the
-  // only in-session surface is the `/gsd` router dialog channel, which is
-  // upstream of this function. One-shot deprecation warning on stderr.
-  const legacyWatch = opts.watch === true;
-  const legacyInSession = opts.inSession === true;
-  if ((legacyWatch || legacyInSession) && !_deprecatedWatchWarned) {
-    _deprecatedWatchWarned = true;
-    try {
-      process.stderr.write(
-        "[headless-default] `watch`/`inSession` flag is deprecated under headless-default-contract v2.0.0 — every spawn is headless; caller hint ignored.\n",
-      );
-    } catch (_) {
-      /* best-effort */
-    }
-  }
-  const spawnType = opts.spawnType || "primary";
-
-  if (!command || typeof command !== "string") {
-    throw new Error("autoSpawnHeadless: `command` is required");
-  }
-  if (spawnType !== "primary" && spawnType !== "validation") {
-    throw new Error(
-      `autoSpawnHeadless: \`spawnType\` must be 'primary' or 'validation' (got ${JSON.stringify(spawnType)})`,
-    );
-  }
-
-  // M50 D2 — Spawn-time Playwright gate. When the command being spawned is a
-  // testing/UI-touching command AND the project has a UI signal AND there's
-  // no playwright.config.* yet, auto-install Playwright before the spawn
-  // proceeds. On install failure, write a `mode: 'blocked-needs-human'`
-  // session-state file (read by gsd-t-resume Step 0 + read-back banner) and
-  // exit 4. See playwright-bootstrap-contract.md §3 + §8 and
-  // m50-integration-points.md for the full protocol.
-  //
-  // Hot path: the gate evaluates `_isTestingOrUICommand` (Set lookup) →
-  // `hasUI` (depth-bounded fs walk) → `hasPlaywright` (existsSync). When the
-  // gate does NOT fire (non-testing command, non-UI project, or already
-  // configured), overhead is the cost of three fast filesystem checks.
-  // Tests inject `opts._gateInstaller` to substitute a stub installer; tests
-  // also inject `opts._gateProbes` to override `hasUI`/`hasPlaywright` for
-  // non-fixture-based assertions.
-  if (_isTestingOrUICommand(command)) {
-    const probes = (opts && opts._gateProbes) || null;
-    let projectHasUI;
-    let projectHasPlaywright;
-    try {
-      const ui = probes && probes.hasUI ? probes.hasUI : require("./ui-detection.cjs").hasUI;
-      const pw = probes && probes.hasPlaywright ? probes.hasPlaywright : require("./playwright-bootstrap.cjs").hasPlaywright;
-      projectHasUI = !!ui(projectDir);
-      projectHasPlaywright = !!pw(projectDir);
-    } catch (_e) {
-      // Probe failure → fail open: skip the gate. A broken probe is worse
-      // than a permissive one (we don't want to block every spawn on a stale
-      // import path).
-      projectHasUI = false;
-      projectHasPlaywright = true;
-    }
-    if (projectHasUI && !projectHasPlaywright) {
-      let installer;
-      try {
-        installer = (opts && opts._gateInstaller) ||
-          require("./playwright-bootstrap.cjs").installPlaywrightSync;
-      } catch (_e) {
-        installer = null;
-      }
-      if (typeof installer === "function") {
-        const result = installer(projectDir);
-        if (result && result.ok) {
-          try {
-            // Concise stdout signal so the user sees the gate fired.
-            process.stdout.write(
-              `▶ Playwright auto-installed (${path.relative(projectDir, path.join(projectDir, "playwright.config.ts"))})\n`,
-            );
-          } catch (_) { /* best-effort */ }
-        } else {
-          // Install failed → mode: 'blocked-needs-human', exit 4.
-          const blockedId = makeSessionId(command, new Date());
-          try {
-            ensureDir(path.join(projectDir, SESSIONS_DIR_REL));
-            writeSessionFile(projectDir, {
-              id: blockedId,
-              pid: null,
-              logPath: null,
-              startTimestamp: new Date().toISOString(),
-              command,
-              args,
-              status: "blocked",
-              mode: "blocked-needs-human",
-              reason: "playwright-install-failed",
-              err: (result && result.err) || "unknown",
-              hint: (result && result.hint) || null,
-              continueFromPath: continue_from,
-              surfaced: false,
-            });
-          } catch (_) { /* best-effort */ }
-          try {
-            process.stderr.write(
-              `[m50-spawn-gate] Playwright install failed (${(result && result.err) || "unknown"}). ` +
-              `Run \`gsd-t doctor --install-playwright\` to retry. Spawn aborted.\n`,
-            );
-          } catch (_) { /* best-effort */ }
-          // In test runs we don't want to actually exit the test harness;
-          // tests inject `opts._gateExit` to capture the exit instead.
-          if (opts && typeof opts._gateExit === "function") {
-            opts._gateExit(4);
-            return {
-              id: blockedId,
-              pid: null,
-              logPath: null,
-              timestamp: new Date().toISOString(),
-              mode: "blocked-needs-human",
-            };
-          }
-          process.exit(4);
-        }
-      }
-    }
-  }
-
-  const timestamp = new Date().toISOString();
-  const id = makeSessionId(command, new Date());
-  const logPath = path.join(projectDir, LOG_DIR_REL, `headless-${id}.log`);
-
-  ensureDir(path.join(projectDir, LOG_DIR_REL));
-  ensureDir(path.join(projectDir, SESSIONS_DIR_REL));
-
-  // M49 — Lazy dashboard. Spawns no longer autostart the dashboard. Each
-  // spawn would otherwise fork-detach a fresh `gsd-t-dashboard-server.js`
-  // (M43 D6-T4); 99% of those banners are never opened so they accumulated
-  // to 88+ orphans on the project-scoped port range. The dashboard now only
-  // starts when the user explicitly invokes `/gsd-t-visualize`. The banner
-  // below remains, but becomes conditional on whether a dashboard is already
-  // listening on the project's scoped port.
-  //
-  // Probe is sync + cheap: read `.gsd-t/.dashboard.pid` and `process.kill(pid, 0)`.
-  // Falls back to "no dashboard" on any error — never throws.
-  // See .gsd-t/contracts/headless-default-contract.md v2.0.0 §M49 (lazy banner).
-  const dashboardInfo = _probeDashboardLazy(projectDir);
-
-  // M46 follow-up — Date + version banner. Printed before the transcript URL
-  // so multi-day-old read-backs are immediately dated. Best-effort.
-  try {
-    const { dateStamp } = require("../scripts/gsd-t-update-check.js");
-    const fsLocal = require("fs");
-    const osLocal = require("os");
-    const pathLocal = require("path");
-    let v = "unknown";
-    try {
-      v = fsLocal.readFileSync(
-        pathLocal.join(osLocal.homedir(), ".claude/.gsd-t-version"), "utf8"
-      ).trim();
-    } catch (_) { /* fall through with "unknown" */ }
-    process.stdout.write(`${dateStamp()}GSD-T v${v} — CURRENT\n`);
-  } catch (_) {
-    /* best-effort — never crash the spawn on banner failure */
-  }
-
-  // M49 — Conditional transcript banner. If a dashboard is already running
-  // on the project's scoped port, point at the live URL (M43 D6-T3 shape).
-  // Otherwise, point at the on-disk log path and hint at /gsd-t-visualize so
-  // the user knows how to open the viewer if they want it. The viewer URL
-  // is no longer printed for spawns where no listener exists — that is what
-  // caused users to assume one was running and accumulated orphans on retry.
-  //
-  // Text is coordinated with D4 — banner format spec in
-  // .gsd-t/contracts/dashboard-server-contract.md v1.3.0 §Banner Format
-  // and headless-default-contract.md v2.0.0 §M49.
-  try {
-    if (dashboardInfo.running && dashboardInfo.port) {
-      process.stdout.write(
-        `▶ Live transcript: http://127.0.0.1:${dashboardInfo.port}/transcript/${id}\n`,
-      );
-    } else {
-      const relLog = path.relative(projectDir, logPath);
-      process.stdout.write(
-        `▶ Transcript file: ${relLog}\n  (to view live: gsd-t-visualize)\n`,
-      );
-    }
-  } catch (_) {
-    /* best-effort — never crash the spawn on banner failure */
-  }
-
-  // Handoff-lock gate (m36 gap-fix T2). Only engaged when the caller
-  // supplies a `sessionId` — existing callers that do not pass one keep
-  // the pre-m36 behavior unchanged. When engaged, the lock is held
-  // across writeContinueHereFile + spawn so a child that is already
-  // waiting via `waitForLockRelease()` (see commands/gsd-t-resume.md
-  // Step 0, wired by m36 watch-loop T4) cannot read a half-written
-  // continue-here file. See .gsd-t/contracts/headless-auto-spawn-contract.md
-  // v1.0.0 (implementation-detail primitive; no contract bump).
-  const lockSessionId = typeof opts.sessionId === "string" && opts.sessionId
-    ? opts.sessionId
-    : null;
-  let lockHandle = null;
-  if (lockSessionId) {
-    lockHandle = acquireHandoffLock(projectDir, lockSessionId);
-  }
-
-  let pid = 0;
-  try {
-    // Open log file descriptor before spawning — child writes directly.
-    const logFd = fs.openSync(logPath, "a");
-
-    // Headless invocation: `node bin/gsd-t.js headless <command> [args] --log`
-    // The `gsd-t` CLI entry point is bin/gsd-t.js relative to projectDir.
-    const gsdtCli = path.join(projectDir, "bin", "gsd-t.js");
-    const childArgs = [gsdtCli, "headless", stripGsdtPrefix(command), ...args, "--log"];
-
-    // Inject command/phase/trace/model into worker env so event-stream entries
-    // (both the writer CLI and the heartbeat PostToolUse hook) are tagged in
-    // the child's context (Fix 2, v3.12.12; trace/model/project-dir added
-    // v3.12.14 to close the null-telemetry regression).
-    //
-    // GSD_T_PHASE defaults to "execute" for primary spawns.
-    // GSD_T_TRACE_ID / GSD_T_MODEL are inherited from parent env if set;
-    // parents (orchestrator, command files) should set them before spawning.
-    // GSD_T_PROJECT_DIR gives the writer a stable target when the child cwd
-    // drifts (e.g., temp dirs in subagents).
-    const workerEnv = Object.assign({}, process.env, {
-      GSD_T_COMMAND: command,
-      GSD_T_PHASE: process.env.GSD_T_PHASE || "execute",
-      GSD_T_PROJECT_DIR: process.env.GSD_T_PROJECT_DIR || projectDir,
-    });
-    if (process.env.GSD_T_TRACE_ID) {
-      workerEnv.GSD_T_TRACE_ID = process.env.GSD_T_TRACE_ID;
-    }
-    if (process.env.GSD_T_MODEL) {
-      workerEnv.GSD_T_MODEL = process.env.GSD_T_MODEL;
-    }
-    workerEnv.GSD_T_AGENT_ID = "headless-" + id;
-    if (process.env.GSD_T_AGENT_ID) {
-      workerEnv.GSD_T_PARENT_AGENT_ID = process.env.GSD_T_AGENT_ID;
-    }
-    // M44 D9 Step 3 — caller-supplied env overrides (e.g., fan-out task ids).
-    // Applied AFTER the canonical GSD_T_* keys so a caller can override any
-    // of them if needed; opaque for everything else.
-    if (envOverride) {
-      for (const [k, v] of Object.entries(envOverride)) {
-        if (v == null) continue;
-        workerEnv[k] = String(v);
-      }
-    }
-    // Worker-model override (v3.18.18) — let `runDispatch` fan-outs default to
-    // Sonnet while the orchestrator stays on whatever the parent runs (often
-    // Opus). Moves mechanical fan-out work onto a separate rate-limit bucket,
-    // raising the provider concurrency ceiling from ~3 to ~6+ per the
-    // Max-subscription concurrency analysis (2026-04-23).
-    if (typeof opts.workerModel === "string" && opts.workerModel) {
-      workerEnv.ANTHROPIC_MODEL = opts.workerModel;
-    }
-
-    const child = spawn("node", childArgs, {
-      cwd: projectDir,
-      detached: true,
-      stdio: ["ignore", logFd, logFd],
-      env: workerEnv,
-    });
-
-    child.unref();
-    fs.closeSync(logFd);
-
-    pid = child.pid || 0;
-
-    writeSessionFile(projectDir, {
-      id,
-      pid,
-      logPath: path.relative(projectDir, logPath),
-      startTimestamp: timestamp,
-      command,
-      args,
-      status: "running",
-      continueFromPath: continue_from,
-      surfaced: false,
-    });
-
-    writeContinueHereFile(projectDir, id, context);
-  } finally {
-    // Release the lock AFTER the child is confirmed started and
-    // handoff artifacts are on disk. The finally ensures a spawn
-    // failure still frees the slot for a retry.
-    if (lockHandle) {
-      try {
-        releaseHandoffLock(lockHandle);
-      } catch (_) {
-        /* idempotent best-effort */
-      }
-    }
-  }
-
-  // T2 — install completion watcher. Non-blocking (setImmediate) so the
-  // caller's return is not delayed. The watcher uses `child.on('exit')` on
-  // a separately-spawned bridge process; here we defer to fs.watchFile for
-  // a detached approach that survives even after the parent's `unref()`.
-  installCompletionWatcher({ projectDir, id, logPath, pid, startTimestamp: timestamp });
-
-  return {
-    id,
-    pid,
-    logPath: path.relative(projectDir, logPath),
-    timestamp,
-    mode: "headless",
-  };
-}
-
-// ── makeSessionId ────────────────────────────────────────────────────────────
-
-/**
- * @param {string} command
- * @param {Date} [now]
- * @returns {string} e.g., "gsd-t-execute-2026-04-15-01-23-45"
- */
-function makeSessionId(command, now) {
-  const d = now || new Date();
-  const pad = (n) => String(n).padStart(2, "0");
-  const date = `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
-  const time = `${pad(d.getHours())}-${pad(d.getMinutes())}-${pad(d.getSeconds())}`;
-  const base = stripGsdtPrefix(command) || command;
-  return `gsd-t-${base}-${date}-${time}`;
-}
-
-// ── writeSessionFile ─────────────────────────────────────────────────────────
-
-function writeSessionFile(projectDir, session) {
-  const fp = path.join(projectDir, SESSIONS_DIR_REL, `${session.id}.json`);
-  ensureDir(path.dirname(fp));
-  fs.writeFileSync(fp, JSON.stringify(session, null, 2) + "\n");
-  return fp;
-}
-
-// ── writeContinueHereFile ────────────────────────────────────────────────────
-
-function writeContinueHereFile(projectDir, id, context) {
-  const fp = path.join(projectDir, SESSIONS_DIR_REL, `${id}-context.json`);
-  const payload = context || buildContextSnapshot(projectDir);
-  fs.writeFileSync(fp, JSON.stringify(payload, null, 2) + "\n");
-  return fp;
-}
-
-function buildContextSnapshot(projectDir) {
-  // Best-effort snapshot of current GSD-T state at handoff time.
-  const snap = {
-    capturedAt: new Date().toISOString(),
-    progress: null,
-    currentDomain: null,
-    pendingTasks: [],
-    lastDecisionLogEntry: null,
-    currentWave: null,
-  };
-  try {
-    const progressFp = path.join(projectDir, ".gsd-t", "progress.md");
-    if (fs.existsSync(progressFp)) {
-      const raw = fs.readFileSync(progressFp, "utf8");
-      snap.progress = firstNLines(raw, 20);
-      // Pull the last Decision Log entry (last non-empty bullet line).
-      const lines = raw.split("\n");
-      for (let i = lines.length - 1; i >= 0; i--) {
-        const ln = lines[i].trim();
-        if (ln.startsWith("- ")) {
-          snap.lastDecisionLogEntry = ln;
-          break;
-        }
-      }
-    }
-  } catch (_) {
-    /* best-effort */
-  }
-  return snap;
-}
-
-function firstNLines(s, n) {
-  return s.split("\n").slice(0, n).join("\n");
-}
-
-// ── markSessionCompleted ─────────────────────────────────────────────────────
-
-/**
- * T2 completion hook — updates the session file in place.
- * @param {string} projectDir
- * @param {string} id
- * @param {{ exitCode: number, endTimestamp?: string }} result
- */
-function markSessionCompleted(projectDir, id, result) {
-  const fp = path.join(projectDir, SESSIONS_DIR_REL, `${id}.json`);
-  if (!fs.existsSync(fp)) return;
-  try {
-    const s = JSON.parse(fs.readFileSync(fp, "utf8"));
-    s.status = "completed";
-    s.exitCode = result.exitCode;
-    s.endTimestamp = result.endTimestamp || new Date().toISOString();
-    fs.writeFileSync(fp, JSON.stringify(s, null, 2) + "\n");
-  } catch (_) {
-    /* ignore */
-  }
-}
-
-// ── Completion watcher (T2) — macOS notification on exit ─────────────────────
-
-function installCompletionWatcher(opts) {
-  const { projectDir, id, pid, startTimestamp } = opts;
-  if (!pid || pid <= 0) return;
-
-  // Poll-based watcher. We can't hold a reference to the child (it's unref'd
-  // and detached), so we poll `process.kill(pid, 0)` which throws if the
-  // process is gone. This is cheap and survives across detachment.
-  const POLL_MS = 2000;
-  const MAX_WAIT_MS = 60 * 60 * 1000; // 1 hour safety cap
-  const startMs = Date.now();
-  const dtStart = new Date(startTimestamp).toLocaleString("sv-SE", { hour12: false }).slice(0, 16);
-
-  const timer = setInterval(() => {
-    let alive = false;
-    try {
-      process.kill(pid, 0);
-      alive = true;
-    } catch (_) {
-      alive = false;
-    }
-    if (!alive) {
-      clearInterval(timer);
-      // Exit code is unknown from a signal-based probe. Best-effort: read
-      // the log's last lines to guess, otherwise default to 0.
-      const exitCode = guessExitCodeFromLog(projectDir, id);
-      const endTimestamp = new Date().toISOString();
-      markSessionCompleted(projectDir, id, {
-        exitCode,
-        endTimestamp,
-      });
-      // Append token-log row (Fix 1, v3.12.12)
-      const dtEnd = new Date(endTimestamp).toLocaleString("sv-SE", { hour12: false }).slice(0, 16);
-      const durationS = Math.round((Date.now() - startMs) / 1000);
-      appendTokenLog(projectDir, {
-        dtStart,
-        dtEnd,
-        command: extractCommand(id),
-        durationS,
-        exitCode,
-      });
-      fireMacNotification({ id, command: extractCommand(id), startTimestamp });
-    } else if (Date.now() - startMs > MAX_WAIT_MS) {
-      clearInterval(timer);
-    }
-  }, POLL_MS);
-
-  // Let the timer not block the parent's exit.
-  if (typeof timer.unref === "function") timer.unref();
-}
-
-function guessExitCodeFromLog(projectDir, id) {
-  try {
-    const fp = path.join(projectDir, LOG_DIR_REL, `headless-${id}.log`);
-    if (!fs.existsSync(fp)) return 0;
-    const raw = fs.readFileSync(fp, "utf8");
-    if (/exit code[: ]+(\d+)/i.test(raw)) {
-      const m = raw.match(/exit code[: ]+(\d+)/i);
-      return parseInt(m[1], 10);
-    }
-    return 0;
-  } catch (_) {
-    return 0;
-  }
-}
-
-function extractCommand(id) {
-  // id format: gsd-t-{command}-{date}-{time}
-  const m = id.match(/^gsd-t-(.+?)-\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}$/);
-  return m ? m[1] : id;
-}
-
-function fireMacNotification({ id, command }) {
-  if (process.platform !== "darwin") return;
-  try {
-    const { spawn } = require("child_process");
-    const msg = `GSD-T headless run complete: ${id}`;
-    const script = `display notification "${msg}" with title "GSD-T" subtitle "${command}"`;
-    const child = spawn("osascript", ["-e", script], {
-      detached: true,
-      stdio: "ignore",
-    });
-    child.unref();
-  } catch (_) {
-    /* graceful degradation */
-  }
-}
-
-// ── Token-Log Writer (Fix 1, v3.12.12) ───────────────────────────────────────
-
-const TOKEN_LOG_HEADER =
-  "| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Ctx% |\n" +
-  "|---|---|---|---|---|---|---|---|---|---|\n";
-
-/**
- * Append one row to {projectDir}/.gsd-t/token-log.md matching the schema used
- * by interactive command-file observability blocks.
- *
- * @param {string} projectDir
- * @param {{ dtStart: string, dtEnd: string, command: string, durationS: number, exitCode: number }} entry
- */
-function appendTokenLog(projectDir, entry) {
-  try {
-    const logPath = path.join(projectDir, ".gsd-t", "token-log.md");
-    const note = entry.exitCode === 0 ? "headless spawn: ok" : `headless spawn: exit ${entry.exitCode}`;
-    // v3.12.14: prefer env-var model over the old hardcoded "unknown". The
-    // parent session should have set GSD_T_MODEL before invoking spawn; fall
-    // back to "unknown" if not (graceful).
-    const model = process.env.GSD_T_MODEL || "unknown";
-    const row =
-      `| ${entry.dtStart} | ${entry.dtEnd} | ${entry.command} | headless | ${model} | ${entry.durationS}s | ${note} | - | - | unknown |\n`;
-    if (!fs.existsSync(logPath)) {
-      // Create with header
-      ensureDir(path.dirname(logPath));
-      fs.writeFileSync(logPath, `# GSD-T Token Log\n\n${TOKEN_LOG_HEADER}${row}`);
-    } else {
-      // Check if header row exists; if not prepend it (migration for files created before this fix)
-      const existing = fs.readFileSync(logPath, "utf8");
-      if (!existing.includes("| Datetime-start |")) {
-        fs.writeFileSync(logPath, `# GSD-T Token Log\n\n${TOKEN_LOG_HEADER}${existing}${row}`);
-      } else {
-        fs.appendFileSync(logPath, row);
-      }
-    }
-  } catch (_) {
-    /* best-effort — never halt the completion watcher */
-  }
-}
-
-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-/**
- * M49 — Cheap synchronous probe: is a dashboard listening on this project's
- * scoped port? Strategy: read `.gsd-t/.dashboard.pid`; if the pid is alive
- * (`process.kill(pid, 0)` doesn't throw), assume the dashboard is up and
- * resolve the port via `projectScopedDefaultPort(projectDir)`. No child
- * process forking — this runs on every spawn and must be cheap.
- *
- * Returns `{ running: boolean, port: number|null, pid: number|null }`. Never
- * throws. A return of `{ running: false }` is the safe fallback that drives
- * the file-path-only banner.
- *
- * @param {string} projectDir
- * @returns {{ running: boolean, port: number|null, pid: number|null }}
- */
-function _probeDashboardLazy(projectDir) {
-  const out = { running: false, port: null, pid: null };
-  try {
-    const pidFile = path.join(projectDir, ".gsd-t", ".dashboard.pid");
-    if (!fs.existsSync(pidFile)) return out;
-    const raw = fs.readFileSync(pidFile, "utf8").trim();
-    const pid = parseInt(raw, 10);
-    if (!pid || Number.isNaN(pid) || pid <= 0) return out;
-    // process.kill(pid, 0) — signal 0 only checks for existence/permission.
-    // Throws ESRCH if no such process; EPERM if process exists but owned by
-    // someone else. EPERM still implies "alive", so treat both ESRCH-only as
-    // dead.
-    try {
-      process.kill(pid, 0);
-    } catch (err) {
-      if (err && err.code === "EPERM") {
-        // Alive but not owned by us — still a live listener; treat as running.
-      } else {
-        return out; // ESRCH or unknown — treat as dead.
-      }
-    }
-    out.pid = pid;
-    out.running = true;
-    try {
-      const { projectScopedDefaultPort } = require("../scripts/gsd-t-dashboard-server.js");
-      out.port = projectScopedDefaultPort(projectDir);
-    } catch (_) {
-      // Without the port we can't render the URL — fall back to file banner.
-      out.running = false;
-      out.port = null;
-    }
-  } catch (_) {
-    /* probe is best-effort */
-  }
-  return out;
-}
-
-function ensureDir(d) {
-  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
-}
-
-function stripGsdtPrefix(command) {
-  if (typeof command !== "string") return "";
-  return command.replace(/^gsd-t-/, "");
-}