@tekyzinc/gsd-t 3.12.15 → 3.13.11

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.13.11] - 2026-04-17
+
+### Fixed — Unattended supervisor reliability triple-fix (bee-poc 15-min hang fallout)
+
+A real bee-poc supervisor relay hung for 15+ minutes on v3.12.15 (pid 70897). Three independent defects surfaced from that incident and are fixed together in this patch. The root cause of the hang itself — a 1-hour worker timeout on the deployed v3.12.15 package — is finally resolved by shipping v3.13.10's D4 work to npm; the two other bugs are fixes for contract-boundary and cosmetic issues the hang exposed.
+
+**Bug 1 (P0) — supervisor watchdog visibility on timeout**:
+The spawnSync `timeout` option kills a hung worker after `DEFAULT_WORKER_TIMEOUT_MS` (270 s in v3.13.10+) and maps the result to contract exit code 124, but the event was not legibly surfaced in `run.log`. Operators tailing the log saw an empty iter block with no indication that the watchdog had fired. `runMainLoop` now writes a deterministic `[worker_timeout] iter=N budget=Nms elapsed=Nms` line to `run.log` immediately before the regular iter trailer, so timeout-induced cache misses are self-documenting. The existing `writeState` call still commits `lastExit=124` + a fresh `lastTick` so `/gsd-t-unattended-watch` sees a heartbeat post-timeout.
+
+**Note on the deployed-version aspect**: the 1-hour → 270 s worker-timeout reduction shipped in v3.13.10 on GitHub but v3.13.10 was never published to npm (progress.md was in "pending publish" state when the bee-poc run started). bee-poc was running against the installed v3.12.15, which still had `DEFAULT_WORKER_TIMEOUT_MS = 3600000`. Publishing v3.13.11 closes both issues — the timeout reduction reaches bee-poc (and every downstream project) and the new diagnostic line makes future watchdog firings visible.
+
+**Bug 2 (P0) — worker cwd invariant**:
+run.log from the bee-poc hang showed a `Shell cwd was reset to /Users/david/projects/GSD-T` line mid-iter — the worker's Bash shell had escaped bee-poc's project directory, and subsequent tool calls silently targeted the wrong repo. `_spawnWorker` already passes `cwd: projectDir` to `platformSpawnWorker` and sets `GSD_T_PROJECT_DIR` on the worker env (correct baseline), but the worker itself had no instruction to re-assert that invariant. The worker prompt now carries an explicit `# CWD Invariant` section that instructs the worker to (a) run `[ "$(pwd)" = "$GSD_T_PROJECT_DIR" ] || cd "$GSD_T_PROJECT_DIR"` as its first Bash call, and (b) scope any directory change inside a subshell (`( cd other && cmd )`) rather than using bare top-level `cd`.
+
+**Bug 3 (P2) — IS_STALE determinism**:
+`/gsd-t-unattended-watch` is run by the haiku model and the "tick age > 540 s → append ⚠️ stale" threshold lived in the Step 6a rendering prose. Haiku would occasionally apply the stale flag to ticks in the 330–540 s band by misreading the prose. The threshold math now lives entirely inside Step 2's `node -e` block as a boolean emission (`IS_STALE = tickAgeMs !== null && tickAgeMs > 540000`), and Step 6a just reads the flag. Boundary cases: 539 s = false, 540 s = false (strict greater-than), 541 s = true.
+
+**Files**:
+- `bin/gsd-t-unattended.cjs` — worker_timeout run.log append; CWD Invariant section in `_spawnWorker` prompt.
+- `commands/gsd-t-unattended-watch.md` — Step 2 IS_STALE computation + emission; Step 6a reader-only rendering; Notes section updated.
+- `test/unattended-triple-fix-v3-13-11.test.js` — 8 new tests (3 Bug 1 + 3 Bug 2 + 3 Bug 3 — one boundary-math test covers three points, bringing the practical count to 8 assertions across 8 it-blocks, of which 3 exercise the Bug 3 boundaries).
+
+**Tests**: 1235/1235 pass (was 1227; +8 new assertions). E2E: N/A (no playwright.config.*).
+
+**Impact**: bee-poc-class hangs are self-recoverable in v3.13.11 — a hung worker is bounded at 270 s by the watchdog, the timeout is now visible in run.log, cwd drift is caught by the worker itself on entry, and `/gsd-t-unattended-watch` no longer produces spurious stale warnings under the threshold.
+
+## [3.13.10] - 2026-04-17
+
+### Added — M39: Fast Unattended + Universal Watch-Progress Tree
+
+Closes the 3–5× speed gap between unattended and in-session execution, adds a universal task-list progress view under every `--watch` surface, and keeps supervisor→worker handoffs inside the 5-minute Anthropic prompt-cache TTL.
+
+**D2 — progress-watch (12 tasks)**:
+- `.gsd-t/contracts/watch-progress-contract.md` v1.0.0 — state-file schema, tree-reconstruction algorithm, stale-state expiry (24h), renderer contract, integration invariants.
+- `scripts/gsd-t-watch-state.js` — zero-dep writer CLI with shim-safe agent-id resolution (CLI arg → `GSD_T_AGENT_ID` env → auto-minted `shell-{pid}-{ts}` fallback). Atomic tmp-write+rename; `start`/`advance`/`done`/`skip`/`fail` subcommands.
+- `bin/watch-progress.js` — tree builder (parent_agent_id lineage, orphan handling) + renderer (✅/🔄/⬜/➡️/❌ markers; expanded-current-subtree + collapsed-siblings layout).
+- 189 step-shims across 17 workflow command files — every numbered step now writes its progress state under `.gsd-t/.watch-state/{agent_id}.json`.
+- Integration into `bin/gsd-t-unattended.cjs`, `bin/unattended-watch-format.cjs`, `bin/headless-auto-spawn.cjs` — tree appends below the existing banner (banner preserved intact).
+
+**D3 — parallel-exec (4 tasks)**:
+- Team Mode prompt block inserted into `_spawnWorker` at the worker instruction boundary. Unattended worker now spawns up to 15 concurrent `Task` subagents per wave (intra-wave parallel), waits for all, then advances (inter-wave sequential). Falls back to sequential when the wave contains only one domain.
+- `.gsd-t/contracts/unattended-supervisor-contract.md` §15 v1.3.0 — Team Mode contract: cap of 15, dependency-graph preservation, wave-boundary semantics.
+
+**D4 — cache-warm-pacing (3 tasks)**:
+- `DEFAULT_WORKER_TIMEOUT_MS = 270000` (270 s) in `bin/gsd-t-unattended.cjs` + `.js`. Preserves the Anthropic 5-min prompt-cache TTL with a ~30 s supervisor→worker handoff budget, eliminating the cold-cache penalty that was adding minutes per iter.
+- `--worker-timeout=<ms>` CLI flag parsed and merged into the live config (was documented in §6 but silently ignored pre-M39).
+- `.gsd-t/contracts/unattended-supervisor-contract.md` §16 v1.3.0 — cache-warm pacing contract: inline rationale comment requirement, inter-iteration sleep invariant (< 5 s), timeout override semantics.
+
+**Red Team**: Initial FAIL (2 CRITICAL + 2 HIGH) → fixes → GRUDGING PASS.
+- BUG-1 (CRITICAL): `GSD_T_AGENT_ID` had no producer — 189 shims would silently fail. Fixed by injecting `supervisor-iter-{N}` in `_spawnWorker`, `headless-{id}` in `autoSpawnHeadless`, and adding an auto-mint fallback chain to the writer CLI.
+- BUG-2 (CRITICAL): `--worker-timeout` flag documented in §6 but no `case "worker-timeout":` in `parseArgs`. Fixed with parse case + config merge + test assertion.
+- BUG-3 (HIGH): `.js` and `.cjs` variants of unattended + safety files had divergent defaults (3600000 vs 270000). Fixed by aligning all four files to 270000.
+- BUG-4 (HIGH): Team Mode prompt referenced "Step 4" but the current execute flow uses "Step 3". Fixed in both the prompt string and the contract §15.
+
+**Tests**: 1227/1227 pass (+3 new: shim-safe agent-id auto-mint, env-var fallback, `--worker-timeout` flag parse).
+
+**Impact**: bee-poc's next supervisor relaunch on v3.13.10 should complete iters 3–5× faster than the v3.12.13 baseline, with visible task-list progression under every `--watch` surface.
+
 ## [3.12.15] - 2026-04-17
 
 ### Fixed — Decision Log Trim — stop live progress.md bloat

package/bin/gsd-t-unattended-safety.cjs

@@ -55,7 +55,7 @@ const DEFAULTS = Object.freeze({
   maxIterations: 200,
   hours: 24,
   gutterNoProgressIters: 5,
-  workerTimeoutMs: 3600000,
+  workerTimeoutMs: 270000,
 });
 
 // ── Glob → regex helper ─────────────────────────────────────────────────────

package/bin/gsd-t-unattended-safety.js

@@ -55,7 +55,7 @@ const DEFAULTS = Object.freeze({
   maxIterations: 200,
   hours: 24,
   gutterNoProgressIters: 5,
-  workerTimeoutMs: 3600000,
+  workerTimeoutMs: 270000,
 });
 
 // ── Glob → regex helper ─────────────────────────────────────────────────────

package/bin/gsd-t-unattended.cjs

@@ -73,7 +73,13 @@ const RUN_LOG = "run.log";
 
 const DEFAULT_HOURS = 24;
 const DEFAULT_MAX_ITERATIONS = 200;
-const DEFAULT_WORKER_TIMEOUT_MS = 3600000; // 1 hour per contract §13
+// Anthropic prompt-cache TTL is 5 minutes (300,000 ms). The supervisor→worker
+// handoff budget is ~30 s (process exit + state persist + next spawn). A 270 s
+// worker timeout leaves room to complete the iter AND still relaunch against
+// a warm cache. If a single iter legitimately exceeds 270 s, the supervisor
+// kills the worker and logs a cache-miss warning; the next iter pays a
+// cold-cache cost but execution continues.
+const DEFAULT_WORKER_TIMEOUT_MS = 270 * 1000; // 270s — see cache-warm-pacing note above; contract §13/§16
 
 const TERMINAL_STATUSES = new Set(["done", "failed", "stopped", "crashed"]);
 const VALID_STATUSES = new Set([
@@ -205,6 +211,17 @@ function parseArgs(argv) {
       case "test-mode":
         out.testMode = true;
         break;
+      case "worker-timeout": {
+        // Per unattended-supervisor-contract §6 + §16: user-supplied override
+        // of DEFAULT_WORKER_TIMEOUT_MS (270 s). Accepts ms. Must not be raised
+        // above 270000 without a separate user-approved contract revision —
+        // the supervisor clamps but does not refuse silently.
+        const n = parseInt(val, 10);
+        if (Number.isFinite(n) && n > 0) {
+          out.workerTimeoutMs = n;
+        }
+        break;
+      }
       default:
         // Unknown flag — ignore for forward compatibility
         break;
@@ -558,6 +575,13 @@ function doUnattended(argv, deps) {
   ) {
     opts.maxIterations = config.maxIterations;
   }
+  if (
+    opts.workerTimeoutMs === undefined &&
+    typeof config.workerTimeoutMs === "number" &&
+    config.workerTimeoutMs > 0
+  ) {
+    opts.workerTimeoutMs = config.workerTimeoutMs;
+  }
   // CLI values now win — mirror them back into config so the pre-worker
   // safety caps (checkIterationCap / checkWallClockCap) use the effective
   // supervisor-scoped limits rather than the on-disk file defaults.
@@ -705,6 +729,21 @@ function doUnattended(argv, deps) {
     console.log(
       `[gsd-t-unattended] running — sessionId=${state.sessionId} pid=${process.pid} milestone=${state.milestone} platform=${state.platform}`,
     );
+    // M39 D2 — append watch-progress tree below banner (best-effort).
+    // Banner preserved verbatim above; renderer output appended below per
+    // watch-progress-contract.md §7. Never throws into the supervisor loop.
+    try {
+      const wp = require("./watch-progress.js");
+      const stateDir = path.join(projectDir, ".gsd-t", ".watch-state");
+      const tree = wp.buildTree(stateDir);
+      const rendered = wp.renderTree(tree, { currentAgent: state.sessionId });
+      if (rendered) {
+        // eslint-disable-next-line no-console
+        console.log(rendered);
+      }
+    } catch (_) {
+      /* watch-progress is best-effort; never crash the watch */
+    }
   }
 
   // ── SUPERVISOR-INIT HOOK (contract §12) ──────────────────────────────────
@@ -936,8 +975,22 @@ function runMainLoop(state, dir, opts, deps, ctx) {
       exitCode = mapHeadlessExitCode(res.status, stdout + "\n" + stderr);
     }
 
+    // v3.13.11 Bug 1: when the watchdog fires (spawnSync timeout SIGTERM or
+    // platform.spawnWorker timedOut flag), make the event explicit in run.log
+    // so operators can see WHICH iteration timed out without inferring from
+    // exit codes. The marker is prepended to stdout and written in the single
+    // per-iter run.log append (no duplicate header).
+    let loggedStdout = stdout;
+    if (exitCode === 124) {
+      const marker =
+        `[worker_timeout] iter=${state.iter} budget=${workerTimeoutMs}ms ` +
+        `elapsed=${elapsedMs}ms — watchdog SIGTERM delivered, ` +
+        `supervisor continues relay per contract §16.\n`;
+      loggedStdout = marker + (stdout || "");
+    }
+
     // Append the full worker output to run.log (never truncate).
-    _appendRunLog(dir, state.iter, workerEnd, exitCode, stdout, stderr);
+    _appendRunLog(dir, state.iter, workerEnd, exitCode, loggedStdout, stderr);
 
     // Append to token-log.md (Fix 1, v3.12.12) — supervisor workers write rows
     // so the log captures headless/unattended activity, not just interactive spawns.
@@ -1138,11 +1191,65 @@ function _spawnWorker(state, opts) {
   else if (process.env.GSD_T_TRACE_ID) workerEnv.GSD_T_TRACE_ID = process.env.GSD_T_TRACE_ID;
   if (state && state.model) workerEnv.GSD_T_MODEL = state.model;
   else if (process.env.GSD_T_MODEL) workerEnv.GSD_T_MODEL = process.env.GSD_T_MODEL;
+  // D2 watch-progress: mint a per-worker agent id and forward the supervisor's
+  // id as parent, so shims inside the worker write state files that the tree
+  // builder can attach under the supervisor root.
+  workerEnv.GSD_T_AGENT_ID =
+    "supervisor-iter-" + (state && state.iter ? state.iter : Date.now());
+  if (process.env.GSD_T_AGENT_ID) {
+    workerEnv.GSD_T_PARENT_AGENT_ID = process.env.GSD_T_AGENT_ID;
+  }
   const res = platformSpawnWorker(opts.cwd, opts.timeout, {
     bin,
     args: [
       "-p",
-      "You are an unattended worker iteration. CRITICAL: Do NOT check supervisor.pid, do NOT auto-reattach to a watch loop, do NOT schedule any ScheduleWakeup. You ARE the worker spawned by the supervisor. Skip Step 0 (auto-reattach) entirely and go directly to Step 0.1. Run /gsd-t-resume but skip the unattended supervisor auto-reattach check in Step 0.",
+      [
+        "You are an unattended worker iteration. CRITICAL: Do NOT check supervisor.pid, do NOT auto-reattach to a watch loop, do NOT schedule any ScheduleWakeup. You ARE the worker spawned by the supervisor. Skip Step 0 (auto-reattach) entirely and go directly to Step 0.1.",
+        "",
+        "# CWD Invariant (v3.13.11 Bug 2)",
+        "",
+        "Before any other work, assert your current working directory matches the",
+        "supervisor's project directory. A worker that silently drifts to a",
+        "different repo will commit to the wrong tree and corrupt state.json.",
+        "",
+        "First Bash call this turn (mandatory):",
+        "",
+        "    [ \"$(pwd)\" = \"$GSD_T_PROJECT_DIR\" ] || cd \"$GSD_T_PROJECT_DIR\"",
+        "    pwd  # confirm",
+        "",
+        "Thereafter, scope any directory change inside a subshell so a `cd` in",
+        "one Bash call cannot contaminate the next one:",
+        "",
+        "    ( cd some/subdir && run-command )   # safe — subshell",
+        "    cd some/subdir && run-command        # UNSAFE — leaks cwd",
+        "",
+        "# Team Mode (Intra-Wave Parallelism)",
+        "",
+        "Before executing tasks for this iteration, read `.gsd-t/partition.md` to",
+        "identify the current wave and which domains belong to it.",
+        "",
+        "If the current wave has MULTIPLE independent domains/tasks (check",
+        "`.gsd-t/domains/*/tasks.md` — 2 or more domains with incomplete tasks in the",
+        "current wave):",
+        "",
+        "  SPAWN PARALLEL SUBAGENTS — up to 15 concurrent Task subagents, one per",
+        "  domain, using `general-purpose` subagent_type. Use the same subagent",
+        "  prompt pattern as `/gsd-t-execute` Team Mode (see `commands/gsd-t-execute.md`",
+        "  Step 3 Team Mode section). Each subagent:",
+        "    - Receives the domain name, its scope.md, its tasks.md (only incomplete",
+        "      tasks from the current wave), and the relevant contracts",
+        "    - Works ONLY within its domain boundary",
+        "    - Returns when all its current-wave tasks are committed",
+        "  WAIT for ALL spawned subagents to report back before advancing.",
+        "",
+        "If the current wave has only 1 domain with incomplete tasks, execute",
+        "sequentially in this worker (no subagent spawn needed).",
+        "",
+        "Inter-wave boundaries always remain sequential — never parallelize across",
+        "waves, because wave-N+1 may depend on wave-N contract/state updates.",
+        "",
+        "Your job: run /gsd-t-resume but skip the unattended supervisor auto-reattach check in Step 0.",
+      ].join("\n"),
       "--dangerously-skip-permissions",
     ],
     env: workerEnv,

package/bin/gsd-t-unattended.js

@@ -74,7 +74,11 @@ const RUN_LOG = "run.log";
 
 const DEFAULT_HOURS = 24;
 const DEFAULT_MAX_ITERATIONS = 200;
-const DEFAULT_WORKER_TIMEOUT_MS = 3600000; // 1 hour per contract §13
+// Anthropic prompt-cache TTL is 5 minutes (300,000 ms). The supervisor→worker
+// handoff budget is ~30 s (process exit + state persist + next spawn). A 270 s
+// worker timeout leaves room to complete the iter AND still relaunch against
+// a warm cache. See contract §16 (cache-warm pacing).
+const DEFAULT_WORKER_TIMEOUT_MS = 270 * 1000;
 
 const TERMINAL_STATUSES = new Set(["done", "failed", "stopped", "crashed"]);
 const VALID_STATUSES = new Set([

package/bin/headless-auto-spawn.cjs

@@ -84,6 +84,21 @@ function autoSpawnHeadless(opts) {
   //   watch=true + validation → warn on stderr; proceed headless
   //   watch=false             → headless (default behavior)
   if (watch && spawnType === "primary") {
+    // M39 D2 — append watch-progress tree below banner (best-effort).
+    // Banner here is the in-context-fallback signal printed by the caller;
+    // we don't own it, so we only render the tree to stdout. Never throws.
+    try {
+      const wp = require("./watch-progress.js");
+      const stateDir = path.join(projectDir, ".gsd-t", ".watch-state");
+      const tree = wp.buildTree(stateDir);
+      const rendered = wp.renderTree(tree, { currentAgent: null });
+      if (rendered) {
+        // eslint-disable-next-line no-console
+        console.log(rendered);
+      }
+    } catch (_) {
+      /* watch-progress is best-effort; never crash the watch */
+    }
     return {
       id: null,
       pid: null,
@@ -156,6 +171,10 @@ function autoSpawnHeadless(opts) {
     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;
+    }
 
     const child = spawn("node", childArgs, {
       cwd: projectDir,

package/bin/unattended-watch-format.cjs

@@ -99,6 +99,21 @@ function _formatIteration(iter, evs) {
  * @param {number} [args.now] — override for Date.now() (tests)
  * @returns {string}
  */
+function _renderWatchProgressTree(args) {
+  // M39 D2 — best-effort watch-progress tree appended below the formatter
+  // output. Banner preserved verbatim; returns "" on any failure so callers
+  // never see a tree when state is missing/unavailable.
+  try {
+    const wp = require("./watch-progress.js");
+    const stateDir = (args && args.stateDir) || ".gsd-t/.watch-state";
+    const current = args && args.currentAgent ? args.currentAgent : null;
+    const tree = wp.buildTree(stateDir);
+    return wp.renderTree(tree, { currentAgent: current }) || "";
+  } catch (_) {
+    return "";
+  }
+}
+
 function formatWatchTick(args) {
   const events = Array.isArray(args && args.events) ? args.events : [];
   const state = (args && args.state) || {};
@@ -108,21 +123,30 @@ function formatWatchTick(args) {
   const iter = Number.isFinite(state.iter) ? state.iter : 0;
   const header = `[unattended supervisor — iter ${iter}${elapsed ? `, ${elapsed}` : ""}]`;
 
+  let body;
   if (events.length === 0) {
-    return `${header} (no new activity since last tick)`;
+    body = `${header} (no new activity since last tick)`;
+  } else {
+    const groups = _groupByIter(events);
+    const blocks = [];
+    for (const [groupIter, evs] of groups) {
+      const groupHeader = groups.length > 1 ? `[iter ${groupIter}]` : header;
+      const bodyLines = _formatIteration(groupIter, evs);
+      blocks.push([groupHeader, ...bodyLines].join("\n"));
+    }
+    body = groups.length > 1 ? `${header}\n${blocks.join("\n")}` : blocks[0];
   }
 
-  const groups = _groupByIter(events);
-  const blocks = [];
-  for (const [groupIter, evs] of groups) {
-    const groupHeader = groups.length > 1 ? `[iter ${groupIter}]` : header;
-    const body = _formatIteration(groupIter, evs);
-    blocks.push([groupHeader, ...body].join("\n"));
-  }
-  if (groups.length > 1) {
-    return `${header}\n${blocks.join("\n")}`;
-  }
-  return blocks[0];
+  // M39 D2 — watch-progress tree below the existing formatter output.
+  // Banner preserved verbatim; tree appended only when caller opts in via
+  // `args.withWatchProgress = true`. Default-off preserves backward
+  // compatibility with existing snapshot-style callers (tests).
+  if (!(args && args.withWatchProgress === true)) return body;
+  const tree = _renderWatchProgressTree({
+    stateDir: args && args.stateDir,
+    currentAgent: args && (args.currentAgent || state.sessionId),
+  });
+  return tree ? `${body}\n${tree}` : body;
 }
 
 /**

package/bin/watch-progress.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * bin/watch-progress.js — GSD-T Watch-Progress Tree Builder + Renderer
+ *
+ * Reads `.gsd-t/.watch-state/*.json` state files written by
+ * `scripts/gsd-t-watch-state.js` and reconstructs the agent workflow tree
+ * via `parent_agent_id` lineage. Renders a task-list with ✅/🔄/⬜ markers
+ * below every `--watch` surface (banner preserved intact).
+ *
+ * Contract: `.gsd-t/contracts/watch-progress-contract.md` v1.0.0
+ * Owner:    D2 (M39 `d2-progress-watch`)
+ * Zero external deps.
+ */
+
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const STALE_MS = 24 * 60 * 60 * 1000; // 24h
+
+const MARKERS = {
+  done: "✅",
+  in_progress: "🔄",
+  pending: "⬜",
+  skipped: "➡️",
+  failed: "❌",
+};
+
+function _readAll(stateDir) {
+  if (!stateDir || !fs.existsSync(stateDir)) return [];
+  let entries;
+  try {
+    entries = fs.readdirSync(stateDir);
+  } catch (_) {
+    return [];
+  }
+  const records = [];
+  for (const f of entries) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const raw = fs.readFileSync(path.join(stateDir, f), "utf8");
+      const rec = JSON.parse(raw);
+      if (rec && typeof rec === "object" && typeof rec.agent_id === "string") {
+        records.push(rec);
+      }
+    } catch (_) { /* skip malformed */ }
+  }
+  return records;
+}
+
+function _isStale(record, now) {
+  if (!record.completed_at) return false;
+  const t = Date.parse(record.completed_at);
+  if (!Number.isFinite(t)) return false;
+  return (now - t) > STALE_MS;
+}
+
+function buildTree(stateDir, options) {
+  const now = options && Number.isFinite(options.now) ? options.now : Date.now();
+  const records = _readAll(stateDir).filter((r) => !_isStale(r, now));
+  const index = new Map();
+  for (const r of records) index.set(r.agent_id, { record: r, children: [] });
+  const roots = [];
+  const orphans = [];
+  for (const r of records) {
+    const node = index.get(r.agent_id);
+    const parentId = r.parent_agent_id;
+    if (parentId === null || parentId === undefined) {
+      roots.push(node);
+    } else if (index.has(parentId)) {
+      index.get(parentId).children.push(node);
+    } else {
+      orphans.push(node);
+    }
+  }
+  return { roots, orphans };
+}
+
+function _marker(status) {
+  return MARKERS[status] || MARKERS.pending;
+}
+
+function _countDone(node) {
+  let count = 0;
+  const s = node.record.status;
+  if (s === "done" || s === "skipped") count = 1;
+  for (const c of node.children) count += _countDone(c);
+  return count;
+}
+
+function _flattenIds(node, acc) {
+  acc.push(node.record.agent_id);
+  for (const c of node.children) _flattenIds(c, acc);
+  return acc;
+}
+
+function _containsAgent(node, agentId) {
+  if (!agentId) return false;
+  return _flattenIds(node, []).includes(agentId);
+}
+
+function _pickCurrent(tree) {
+  let pick = null;
+  let latest = -Infinity;
+  const walk = (node) => {
+    const r = node.record;
+    if (r.status === "in_progress" && r.started_at) {
+      const t = Date.parse(r.started_at);
+      if (Number.isFinite(t) && t > latest) { latest = t; pick = r.agent_id; }
+    }
+    for (const c of node.children) walk(c);
+  };
+  for (const root of tree.roots) walk(root);
+  return pick;
+}
+
+function _renderExpanded(node, depth, lines) {
+  const indent = "  ".repeat(depth);
+  const r = node.record;
+  lines.push(`${indent}${_marker(r.status)} ${r.step_label || r.command || r.agent_id}`);
+  for (const c of node.children) _renderExpanded(c, depth + 1, lines);
+}
+
+function _renderCollapsed(node, depth, lines) {
+  const indent = "  ".repeat(depth);
+  const r = node.record;
+  const doneCount = _countDone(node);
+  const label = r.step_label || r.command || r.agent_id;
+  lines.push(`${indent}${_marker(r.status)} ${label} (${doneCount} tasks done)`);
+}
+
+function renderTree(tree, options) {
+  if (!tree || (tree.roots.length === 0 && tree.orphans.length === 0)) return "";
+  const opts = options || {};
+  const currentAgent = opts.currentAgent || _pickCurrent(tree);
+  const lines = [];
+  for (const root of tree.roots) {
+    if (_containsAgent(root, currentAgent)) _renderExpanded(root, 0, lines);
+    else _renderCollapsed(root, 0, lines);
+  }
+  if (tree.orphans.length > 0) {
+    lines.push("⬜ (orphan subtree — parent state missing)");
+    for (const o of tree.orphans) _renderExpanded(o, 1, lines);
+  }
+  return lines.join("\n");
+}
+
+module.exports = { buildTree, renderTree, MARKERS, STALE_MS, _pickCurrent };
+
+if (require.main === module) {
+  const stateDir = process.argv[2] || path.join(".gsd-t", ".watch-state");
+  const out = renderTree(buildTree(stateDir));
+  if (out) process.stdout.write(out + "\n");
+}