@tekyzinc/gsd-t 3.13.16 → 3.16.11

package/bin/gsd-t.js

@@ -567,6 +567,50 @@ function installContextMeter(projectDir) {
 }
 
 // Register the Context Meter PostToolUse hook in ~/.claude/settings.json.
+// Opt-in pre-commit hook installer (M41 D5). Appends the capture-lint block
+// to .git/hooks/pre-commit; if the file doesn't exist, copies our stock
+// script. Never overwrites an existing hook.
+const CAPTURE_LINT_HOOK_MARKER = "# GSD-T capture lint";
+function installCaptureLintHook(projectDir) {
+  const gitDir = path.join(projectDir, ".git");
+  if (!fs.existsSync(gitDir)) {
+    warn("No .git directory — not a git repo; skipping hook install");
+    return false;
+  }
+  const hooksDir = path.join(gitDir, "hooks");
+  try { fs.mkdirSync(hooksDir, { recursive: true }); } catch (_) {}
+  const hookPath = path.join(hooksDir, "pre-commit");
+  const stockSrc = path.join(PKG_ROOT, "scripts", "hooks", "pre-commit-capture-lint");
+  let stock = "";
+  try { stock = fs.readFileSync(stockSrc, "utf8"); } catch (_) {
+    warn("Could not read pre-commit-capture-lint script from package");
+    return false;
+  }
+
+  if (!fs.existsSync(hookPath)) {
+    fs.writeFileSync(hookPath, stock);
+    try { fs.chmodSync(hookPath, 0o755); } catch (_) {}
+    success(`Hook installed at ${path.relative(projectDir, hookPath)}`);
+    info("Test with: gsd-t capture-lint --staged");
+    return true;
+  }
+
+  const existing = fs.readFileSync(hookPath, "utf8");
+  if (existing.includes(CAPTURE_LINT_HOOK_MARKER)) {
+    info("Capture-lint block already present in pre-commit hook — no change");
+    return true;
+  }
+
+  const appended = existing.trimEnd() +
+    "\n\n" + CAPTURE_LINT_HOOK_MARKER + "\n" +
+    stock.replace(/^#!.*\n/, "") + "\n";
+  fs.writeFileSync(hookPath, appended);
+  try { fs.chmodSync(hookPath, 0o755); } catch (_) {}
+  success(`Capture-lint block appended to ${path.relative(projectDir, hookPath)}`);
+  info("Test with: gsd-t capture-lint --staged");
+  return true;
+}
+
 // Idempotent — if an existing hook references CONTEXT_METER_HOOK_MARKER the
 // command string is refreshed/migrated in-place to the canonical form.
 // Stale entries matching CONTEXT_METER_STALE_PATTERNS are migrated on the spot.
@@ -1545,9 +1589,29 @@ function doStatus() {
   showStatusTeams();
   showStatusContextMeter();
   showStatusProject();
+  showStatusTokenBlock();
   log("");
 }
 
+function showStatusTokenBlock() {
+  const cwd = process.cwd();
+  if (!fs.existsSync(path.join(cwd, ".gsd-t"))) return;
+  let milestone = null;
+  try {
+    const progressPath = path.join(cwd, ".gsd-t", "progress.md");
+    if (fs.existsSync(progressPath)) {
+      const src = fs.readFileSync(progressPath, "utf8");
+      const m = src.match(/## Current Milestone:\s*(\S+)/) || src.match(/Milestone:\s*(M\d+)/);
+      if (m) milestone = m[1];
+    }
+  } catch (_) {}
+  try {
+    const dashboard = require(path.join(__dirname, "gsd-t-token-dashboard.cjs"));
+    const agg = dashboard.aggregateSync({ projectDir: cwd, milestone });
+    log(dashboard.renderStatusBlock(agg));
+  } catch (_) {}
+}
+
 function formatRelativeTime(timestampIso) {
   const then = Date.parse(timestampIso);
   if (!Number.isFinite(then)) return "unknown";
@@ -3517,6 +3581,122 @@ function doMetrics(_args) {
   log(`${DIM}metrics removed in v3.12 — context meter is no longer telemetry-instrumented${RESET}`);
 }
 
+function doStreamFeed(args) {
+  const sub = args[0];
+  const projectDir = process.cwd();
+  const pidFile = path.join(projectDir, ".gsd-t", "stream-feed", ".server.pid");
+  const portFile = path.join(projectDir, ".gsd-t", "stream-feed", ".server.port");
+
+  function readPid() {
+    try { return parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10); }
+    catch { return null; }
+  }
+  function readPort() {
+    try { return parseInt(fs.readFileSync(portFile, "utf8").trim(), 10); }
+    catch { return null; }
+  }
+  function isAlive(pid) {
+    if (!pid) return false;
+    try { process.kill(pid, 0); return true; } catch { return false; }
+  }
+
+  if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+    log(`\n${BOLD}gsd-t stream-feed${RESET} — Localhost stream-json watcher (M40 D4)\n`);
+    log(`${BOLD}Usage:${RESET}`);
+    log(`  gsd-t stream-feed ${CYAN}start${RESET} [--port N]`);
+    log(`  gsd-t stream-feed ${CYAN}status${RESET}`);
+    log(`  gsd-t stream-feed ${CYAN}stop${RESET}`);
+    log(`\nDefault port: 7842. Env override: GSD_T_STREAM_FEED_PORT.`);
+    return;
+  }
+
+  if (sub === "start") {
+    const existing = readPid();
+    if (isAlive(existing)) {
+      log(`${YELLOW}stream-feed-server already running${RESET} (pid ${existing}, port ${readPort() || "?"})`);
+      return;
+    }
+    let port = null;
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--port") port = Number(args[++i]);
+    }
+    const { spawn } = require("child_process");
+    const serverScript = path.join(__dirname, "..", "scripts", "gsd-t-stream-feed-server.js");
+    const forward = ["--project-dir", projectDir];
+    if (port) forward.push("--port", String(port));
+    const feedDir = path.join(projectDir, ".gsd-t", "stream-feed");
+    try { fs.mkdirSync(feedDir, { recursive: true }); } catch { /* exists */ }
+    const out = fs.openSync(path.join(feedDir, "server.log"), "a");
+    const err = fs.openSync(path.join(feedDir, "server.log"), "a");
+    const child = spawn(process.execPath, [serverScript, ...forward], {
+      detached: true, stdio: ["ignore", out, err], cwd: projectDir,
+    });
+    child.unref();
+    try { fs.writeFileSync(pidFile, String(child.pid)); } catch { /* noop */ }
+    try { fs.writeFileSync(portFile, String(port || process.env.GSD_T_STREAM_FEED_PORT || 7842)); } catch { /* noop */ }
+    log(`${GREEN}✓${RESET} stream-feed-server started (pid ${child.pid}, port ${port || 7842})`);
+    log(`  log: .gsd-t/stream-feed/server.log`);
+    return;
+  }
+
+  if (sub === "status") {
+    const pid = readPid();
+    const port = readPort();
+    if (!isAlive(pid)) {
+      log(`${DIM}stream-feed-server not running${RESET}`);
+      return;
+    }
+    log(`${GREEN}●${RESET} stream-feed-server running`);
+    log(`  pid:  ${pid}`);
+    log(`  port: ${port || 7842}`);
+    // Try to fetch live stats
+    try {
+      const http = require("http");
+      const done = { v: false };
+      const req = http.get({ host: "127.0.0.1", port: port || 7842, path: "/status", timeout: 1000 }, (res) => {
+        let body = "";
+        res.on("data", (c) => body += c);
+        res.on("end", () => {
+          try {
+            const j = JSON.parse(body);
+            log(`  frames today: ${j.framesToday}`);
+            log(`  clients: ${j.clients}`);
+            log(`  stats: ingested=${j.stats.framesIngested} broadcast=${j.stats.framesBroadcast} kicked=${j.stats.kicked}`);
+          } catch { /* noop */ }
+          done.v = true;
+        });
+      });
+      req.on("error", () => { done.v = true; });
+      req.on("timeout", () => { req.destroy(); done.v = true; });
+    } catch { /* noop */ }
+    return;
+  }
+
+  if (sub === "stop") {
+    const pid = readPid();
+    if (!isAlive(pid)) {
+      log(`${DIM}stream-feed-server not running${RESET}`);
+      try { fs.unlinkSync(pidFile); } catch { /* noop */ }
+      try { fs.unlinkSync(portFile); } catch { /* noop */ }
+      return;
+    }
+    try { process.kill(pid, "SIGTERM"); } catch { /* noop */ }
+    log(`${GREEN}✓${RESET} stream-feed-server stopped (pid ${pid})`);
+    // Clean up stale PID files after a short wait
+    setTimeout(() => {
+      if (!isAlive(pid)) {
+        try { fs.unlinkSync(pidFile); } catch { /* noop */ }
+        try { fs.unlinkSync(portFile); } catch { /* noop */ }
+      }
+    }, 500);
+    return;
+  }
+
+  error(`Unknown stream-feed subcommand: ${sub}`);
+  log(`Try: gsd-t stream-feed --help`);
+  process.exit(1);
+}
+
 function showHelp() {
   log(`\n${BOLD}GSD-T${RESET} — Contract-Driven Development for Claude Code\n`);
   log(`${BOLD}Usage:${RESET}  npx @tekyzinc/gsd-t ${CYAN}<command>${RESET} [options]\n`);
@@ -3532,6 +3712,9 @@ function showHelp() {
   log(`  ${CYAN}changelog${RESET}      Open changelog in the browser`);
   log(`  ${CYAN}graph${RESET}          Code graph operations (index, status, query)`);
   log(`  ${CYAN}headless${RESET}       Non-interactive execution via claude -p + fast state queries`);
+  log(`  ${CYAN}orchestrate${RESET}    External task orchestrator — one claude -p spawn per task (M40)`);
+  log(`  ${CYAN}benchmark-orchestrator${RESET} M40 speed gate — compares orchestrator vs in-session wall-clock`);
+  log(`  ${CYAN}stream-feed${RESET}    Localhost stream-json watcher (start|status|stop) — M40 D4`);
   log(`  ${CYAN}design-build${RESET}   Deterministic design→code pipeline (elements → widgets → pages)`);
   log(`  ${CYAN}help${RESET}           Show this help\n`);
   log(`${BOLD}Examples:${RESET}`);
@@ -3652,9 +3835,21 @@ if (require.main === module) {
     case "update-all":
       doUpdateAll().catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
-    case "init":
-      doInit(args[1]).catch((e) => { error(e.message || String(e)); process.exit(1); });
+    case "init": {
+      let initProject = null;
+      let installHooks = false;
+      for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--install-hooks') installHooks = true;
+        else if (!a.startsWith('-')) initProject = a;
+      }
+      doInit(initProject)
+        .then(() => {
+          if (installHooks) installCaptureLintHook(process.cwd());
+        })
+        .catch((e) => { error(e.message || String(e)); process.exit(1); });
       break;
+    }
     case "register":
       doRegister();
       break;
@@ -3684,9 +3879,141 @@ if (require.main === module) {
       });
       process.exit(res.status == null ? 1 : res.status);
     }
+    case "orchestrate": {
+      const { spawnSync } = require("child_process");
+      const js = path.join(__dirname, "gsd-t-orchestrator.js");
+      const res = spawnSync(process.execPath, [js, ...args.slice(1)], {
+        stdio: "inherit",
+      });
+      process.exit(res.status == null ? 1 : res.status);
+    }
+    case "benchmark-orchestrator": {
+      const { spawnSync } = require("child_process");
+      const js = path.join(__dirname, "gsd-t-benchmark-orchestrator.js");
+      const res = spawnSync(process.execPath, [js, ...args.slice(1)], {
+        stdio: "inherit",
+      });
+      process.exit(res.status == null ? 1 : res.status);
+    }
+    case "stream-feed": {
+      doStreamFeed(args.slice(1));
+      break;
+    }
     case "metrics":
       doMetrics(args.slice(1));
       break;
+    case "backfill-tokens": {
+      const bfOpts = { projectDir: process.cwd(), since: null, patchLog: false, dryRun: false };
+      for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--since' && args[i+1]) { bfOpts.since = args[++i]; }
+        else if (a.startsWith('--since=')) { bfOpts.since = a.slice(8); }
+        else if (a === '--patch-log') { bfOpts.patchLog = true; }
+        else if (a === '--dry-run') { bfOpts.dryRun = true; }
+        else if (a === '--project-dir' && args[i+1]) { bfOpts.projectDir = args[++i]; }
+        else if (a.startsWith('--project-dir=')) { bfOpts.projectDir = a.slice(14); }
+        else if (a === '--help' || a === '-h') {
+          log('Usage: gsd-t backfill-tokens [--since YYYY-MM-DD] [--patch-log] [--dry-run] [--project-dir PATH]');
+          process.exit(0);
+        }
+        else {
+          error(`backfill-tokens: unknown arg: ${a}`);
+          process.exit(2);
+        }
+      }
+      const backfill = require(path.join(__dirname, 'gsd-t-token-backfill.cjs'));
+      backfill.main(bfOpts)
+        .then(({ exitCode }) => process.exit(exitCode || 0))
+        .catch((e) => { error(e.message || String(e)); process.exit(3); });
+      break;
+    }
+    case "capture-lint": {
+      const clOpts = { projectDir: process.cwd(), mode: 'staged' };
+      for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--staged') { clOpts.mode = 'staged'; }
+        else if (a === '--all') { clOpts.mode = 'all'; }
+        else if (a === '--project-dir' && args[i+1]) { clOpts.projectDir = args[++i]; }
+        else if (a.startsWith('--project-dir=')) { clOpts.projectDir = a.slice(14); }
+        else if (a === '--help' || a === '-h') {
+          log('Usage: gsd-t capture-lint [--staged] [--all] [--project-dir PATH]');
+          process.exit(0);
+        }
+        else {
+          error(`capture-lint: unknown arg: ${a}`);
+          process.exit(2);
+        }
+      }
+      try {
+        const linter = require(path.join(__dirname, 'gsd-t-capture-lint.cjs'));
+        const res = linter.main(clOpts);
+        if (res.error) {
+          error(`capture-lint: ${res.error}`);
+          process.exit(2);
+        }
+        for (const v of res.violations) {
+          log(`${v.file}:${v.line}: ${v.message}`);
+        }
+        if (res.violations.length === 0) {
+          log(`capture-lint: ${res.files.length} file(s) checked — clean`);
+        } else {
+          log(`capture-lint: ${res.violations.length} violation(s) across ${res.files.length} file(s)`);
+        }
+        process.exit(res.exitCode);
+      } catch (e) {
+        error(e.message || String(e));
+        process.exit(2);
+      }
+      break;
+    }
+    case "tokens": {
+      const tkOpts = { projectDir: process.cwd(), since: null, milestone: null, format: 'table', regenerateLog: false };
+      for (let i = 1; i < args.length; i++) {
+        const a = args[i];
+        if (a === '--since' && args[i+1]) { tkOpts.since = args[++i]; }
+        else if (a.startsWith('--since=')) { tkOpts.since = a.slice(8); }
+        else if (a === '--milestone' && args[i+1]) { tkOpts.milestone = args[++i]; }
+        else if (a.startsWith('--milestone=')) { tkOpts.milestone = a.slice(12); }
+        else if (a === '--format' && args[i+1]) { tkOpts.format = args[++i]; }
+        else if (a.startsWith('--format=')) { tkOpts.format = a.slice(9); }
+        else if (a === '--project-dir' && args[i+1]) { tkOpts.projectDir = args[++i]; }
+        else if (a.startsWith('--project-dir=')) { tkOpts.projectDir = a.slice(14); }
+        else if (a === '--regenerate-log') { tkOpts.regenerateLog = true; }
+        else if (a === '--help' || a === '-h') {
+          log('Usage: gsd-t tokens [--since YYYY-MM-DD] [--milestone Mxx] [--format table|json]');
+          log('       gsd-t tokens --regenerate-log   (rewrite .gsd-t/token-log.md from token-usage.jsonl)');
+          process.exit(0);
+        }
+        else {
+          error(`tokens: unknown arg: ${a}`);
+          process.exit(2);
+        }
+      }
+      if (tkOpts.regenerateLog) {
+        try {
+          const regen = require(path.join(__dirname, 'gsd-t-token-regenerate-log.cjs'));
+          const res = regen.regenerateLog({ projectDir: tkOpts.projectDir });
+          log(`Regenerated ${res.wrote} (${res.rowCount} row${res.rowCount === 1 ? '' : 's'})`);
+          process.exit(0);
+        } catch (e) {
+          error(e.message || String(e));
+          process.exit(3);
+        }
+        break;
+      }
+      if (tkOpts.format !== 'table' && tkOpts.format !== 'json') {
+        error(`tokens: --format must be 'table' or 'json' (got: ${tkOpts.format})`);
+        process.exit(2);
+      }
+      const dashboard = require(path.join(__dirname, 'gsd-t-token-dashboard.cjs'));
+      dashboard.aggregate(tkOpts)
+        .then((agg) => {
+          log(tkOpts.format === 'json' ? dashboard.renderJson(agg) : dashboard.renderTable(agg));
+          process.exit(0);
+        })
+        .catch((e) => { error(e.message || String(e)); process.exit(3); });
+      break;
+    }
     case "design-build": {
       const orchestrator = require("./design-orchestrator.js");
       orchestrator.run(args.slice(1)).catch(e => { console.error(e); process.exit(1); });

package/bin/supervisor-pid-fingerprint.cjs

@@ -0,0 +1,126 @@
+/**
+ * Supervisor PID fingerprint.
+ *
+ * The supervisor.pid file is written as JSON `{pid, projectDir, startedAt}`
+ * so that resume-time liveness checks can distinguish "our supervisor is
+ * running" from "some other process recycled this PID."
+ *
+ * Backward-compat: if the file parses as a bare integer (legacy format),
+ * treat it as `{pid, projectDir: null, startedAt: null, form: "legacy"}`
+ * and let callers decide whether to trust it.
+ */
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { execSync } = require("node:child_process");
+
+const PID_REL = path.join(".gsd-t", ".unattended", "supervisor.pid");
+
+function pidPathFor(projectDir) {
+  return path.join(path.resolve(projectDir), PID_REL);
+}
+
+function writePidFile(projectDir, pid) {
+  if (!projectDir || typeof projectDir !== "string") {
+    throw new Error("writePidFile: projectDir required");
+  }
+  if (!Number.isInteger(pid) || pid <= 0) {
+    throw new Error(`writePidFile: invalid pid ${pid}`);
+  }
+  const entry = {
+    pid,
+    projectDir: path.resolve(projectDir),
+    startedAt: new Date().toISOString(),
+  };
+  const p = pidPathFor(projectDir);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(entry) + "\n", "utf8");
+  return entry;
+}
+
+function readPidFile(projectDir) {
+  const p = pidPathFor(projectDir);
+  if (!fs.existsSync(p)) return null;
+  const raw = fs.readFileSync(p, "utf8").trim();
+  if (!raw) return null;
+
+  // Try JSON form first.
+  if (raw.startsWith("{")) {
+    try {
+      const obj = JSON.parse(raw);
+      if (obj && Number.isInteger(obj.pid)) {
+        return {
+          pid: obj.pid,
+          projectDir: obj.projectDir || null,
+          startedAt: obj.startedAt || null,
+          form: "json",
+        };
+      }
+    } catch {
+      // fall through to legacy attempt
+    }
+  }
+
+  // Legacy bare-integer form.
+  const n = Number.parseInt(raw, 10);
+  if (Number.isInteger(n) && n > 0) {
+    return { pid: n, projectDir: null, startedAt: null, form: "legacy" };
+  }
+  return null;
+}
+
+/**
+ * verifyFingerprint(entry, projectDir, opts?)
+ *
+ * Returns { ok, reason, command? }:
+ *   ok: true   → entry matches this project AND ps confirms gsd-t command line
+ *   ok: false  → mismatch (see reason)
+ *   ok: null   → inconclusive (legacy entry, can't verify)
+ *
+ * reason values when ok=false:
+ *   "project_mismatch"   — entry.projectDir !== resolved projectDir
+ *   "process_not_found"  — ps -p returned nothing
+ *   "command_not_gsd_t"  — ps succeeded but command line doesn't match /gsd-t|unattended/i
+ *   "ps_failed"          — ps threw (couldn't introspect)
+ *
+ * opts._execSync — injection point for tests
+ */
+function verifyFingerprint(entry, projectDir, opts = {}) {
+  if (!entry || typeof entry !== "object") {
+    return { ok: false, reason: "no_entry" };
+  }
+  if (entry.form === "legacy" || !entry.projectDir) {
+    return { ok: null, reason: "legacy_fingerprint" };
+  }
+  const resolved = path.resolve(projectDir);
+  if (entry.projectDir !== resolved) {
+    return { ok: false, reason: "project_mismatch" };
+  }
+
+  const exec = opts._execSync || execSync;
+  let cmd;
+  try {
+    const out = exec(`ps -p ${entry.pid} -o command=`, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    cmd = (out || "").trim();
+  } catch {
+    return { ok: false, reason: "ps_failed" };
+  }
+  if (!cmd) {
+    return { ok: false, reason: "process_not_found" };
+  }
+  if (!/gsd-t|unattended/i.test(cmd)) {
+    return { ok: false, reason: "command_not_gsd_t", command: cmd };
+  }
+  return { ok: true, reason: "verified", command: cmd };
+}
+
+module.exports = {
+  pidPathFor,
+  writePidFile,
+  readPidFile,
+  verifyFingerprint,
+};

package/commands/gsd-t-debug.md

@@ -96,23 +96,31 @@ Violations are task failures, not warnings.
 
 If STACK_RULES is empty (no templates/stacks/ dir or no matches), skip silently.
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
+Spawn a fresh subagent via `captureSpawn` — `spawnType: 'primary'` (respects `--watch`: headless by default, in-context when `WATCH_FLAG=true`):
+
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the primary subagent spawn with `captureSpawn`:**
 
-Spawn a fresh subagent using the Task tool — `spawnType: 'primary'` (respects `--watch`: headless by default, in-context when `WATCH_FLAG=true`):
 ```
-subagent_type: general-purpose
-spawnType: primary
-prompt: "You are running gsd-t-debug for this issue: {$ARGUMENTS}
-Working directory: {current project root}
-Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-debug starting at Step 1."
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-debug',
+    step: 'Step 0',
+    model: 'sonnet',
+    description: 'debug: {issue summary}',
+    projectDir: '.',
+    notes: 'debug: {issue summary}',
+    spawnFn: async () => { /* Task subagent (general-purpose, spawnType: primary, model: sonnet):
+      'You are running gsd-t-debug for this issue: {\$ARGUMENTS}
+      Working directory: {current project root}
+      Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-debug starting at Step 1.' */ },
+  });
+})();
+"
 ```
 
-After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-debug | Step 0 | sonnet | {DURATION}s | debug: {issue summary} | {CTX_PCT} |`
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 Relay the subagent's summary to the user. **Do not execute Steps 1–5 yourself.**
 
@@ -154,40 +162,30 @@ Before attempting any fix, check whether this issue has been through multiple fa
 
 The current approach has failed 3+ times. This means the root cause is not yet understood. A different strategy — possibly a fundamentally different technical approach — is required.
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the Deep Research team spawn with `captureSpawn`:**
 
 ```
-Spawn a deep research team (run all three in parallel):
-
-- Teammate "researcher-root-cause": Take the broadest possible look at
-  the problem. Ignore prior fix attempts. Read the full component,
-  its dependencies, contracts, and all error traces from scratch.
-  What is the actual root cause — not the symptom? Consider that the
-  real issue may be architectural, not in the code being patched.
-
-- Teammate "researcher-alternatives": Enumerate 3–5 fundamentally
-  different ways to solve this problem. Include approaches that would
-  require refactoring or changing the technical direction entirely.
-  For each: what are the trade-offs, effort, and risk?
-
-- Teammate "researcher-prior-art": Search external sources, docs,
-  GitHub issues, and known patterns for this class of bug. Has this
-  problem been documented elsewhere? What did others find? Are there
-  framework-specific pitfalls or known workarounds?
-
-Lead: Wait for all three researchers to complete. Then synthesize:
-1. What is the true root cause based on full investigation?
-2. What are the viable solution paths (ranked by confidence)?
-3. Does any path require a different technical approach than what has been tried?
-4. What is the recommended path and why?
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-debug',
+    step: 'Step 1.5',
+    model: 'sonnet',
+    description: 'deep research loop break: {issue summary}',
+    projectDir: '.',
+    notes: 'deep research loop break: {issue summary}',
+    spawnFn: async () => { /* Deep research team (three teammates in parallel):
+      - Teammate 'researcher-root-cause': broadest look at the problem, ignore prior fix attempts, identify true root cause (possibly architectural, not in code being patched).
+      - Teammate 'researcher-alternatives': enumerate 3–5 fundamentally different solutions with trade-offs, effort, and risk.
+      - Teammate 'researcher-prior-art': search external sources, docs, GitHub issues for this class of bug and known workarounds.
+      Lead synthesizes after all three complete: true root cause, ranked solution paths, whether a different technical approach is required, and the recommended path. */ },
+  });
+})();
+"
 ```
 
-After team completes — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.cjs'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
-Append to `.gsd-t/token-log.md`:
-`| {DT_START} | {DT_END} | gsd-t-debug | Step 1.5 | sonnet | {DURATION}s | deep research loop break: {issue summary} | {CTX_PCT} |`
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 **STOP. Present findings to the user before making any changes:**
 
@@ -447,19 +445,33 @@ Resolve the templated prompt path via Bash:
 ```
 RT_PROMPT="$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t/templates/prompts/red-team-subagent.md"
 [ -f "$RT_PROMPT" ] || RT_PROMPT="templates/prompts/red-team-subagent.md"
-T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")
 ```
 
-Spawn Task subagent (spawnType: validation, general-purpose, model: opus) — always headless, `--watch` ignored:
-> "Read `$RT_PROMPT` and follow it. Context: post-fix validation for a debug session. **Additional categories for this run:** (a) **Regression Around the Fix** — test every code path adjacent to the changed lines; fixes frequently break neighboring functionality. (b) **Original Bug Variants** — the original bug was {one-line description}; search for SIMILAR bugs in related code (same pattern, different location). Write findings to `.gsd-t/red-team-report.md`."
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the Red Team subagent spawn with `captureSpawn`:**
 
-After subagent returns — run via Bash:
 ```
-T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))
-CTX_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs'); process.stdout.write(String(tb.getSessionStatus('.').pct))}catch(_){process.stdout.write('N/A')}")
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-debug',
+    step: 'Red Team',
+    model: 'opus',
+    description: 'adversarial validation of debug fix',
+    projectDir: '.',
+    notes: '{VERDICT} — {N} bugs found',
+    spawnFn: async () => { /* Task subagent (spawnType: validation, general-purpose, model: opus) — always headless, --watch ignored:
+      'Read \$RT_PROMPT and follow it. Context: post-fix validation for a debug session.
+      Additional categories for this run:
+      (a) Regression Around the Fix — test every code path adjacent to the changed lines; fixes frequently break neighboring functionality.
+      (b) Original Bug Variants — the original bug was {one-line description}; search for SIMILAR bugs in related code (same pattern, different location).
+      Write findings to .gsd-t/red-team-report.md.' */ },
+  });
+})();
+"
 ```
-Append to `.gsd-t/token-log.md`:
-`| {DT_START} | {DT_END} | gsd-t-debug | Red Team | opus | {DURATION}s | {VERDICT} — {N} bugs found | | | {CTX_PCT} |`
+
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 **If FAIL:** fix CRITICAL/HIGH bugs (≤2 cycles) → re-run. Persistent bugs → `.gsd-t/deferred-items.md`.
 **If GRUDGING PASS:** proceed to metrics and doc-ripple.