@tekyzinc/gsd-t 3.13.10 → 3.13.12

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.13.12] - 2026-04-17
+
+### Fixed — Project-local `bin/gsd-t.js` crash on missing `debug-ledger.js` + self-heal sweep
+
+A bee-poc relaunch after the v3.13.11 fix still crashed with `MODULE_NOT_FOUND: Cannot find module './debug-ledger.js'` — but the crash came from `bin/gsd-t.js` itself, not from the v3.13.11 supervisor code. Root cause: an older version of `copyBinToolsToProject` copied `bin/gsd-t.js` into registered projects as part of a now-deprecated whitelist. The current `PROJECT_BIN_TOOLS` whitelist (10 `.cjs` files) does not include `gsd-t.js` or its sibling `debug-ledger.js`, so `update-all` stopped maintaining both — but the stale copy persisted in project `bin/` directories, and `bin/gsd-t.js` had a hard require on `./debug-ledger.js` at the top of the file. Any invocation of the stale project-local copy crashed before the first line of real work. bee-poc had the 130 KB stale `bin/gsd-t.js` from this lineage.
+
+**Layer 1 — defensive require** (`bin/gsd-t.js:23`):
+The top-level `require('./debug-ledger.js')` is now wrapped in `try/catch` and falls back to a no-op stub exporting every function the real module exports (`readLedger`, `appendEntry`, `getLedgerStats`, `clearLedger`, `compactLedger`, `generateAntiRepetitionPreamble`). Projects with stale copies no longer crash; they degrade to debug-ledger-disabled behavior until `update-all` sweeps the stray away.
+
+**Layer 2 — deprecated-stray sweep** (`copyBinToolsToProject`):
+New `DEPRECATED_BIN_STRAYS = ["gsd-t.js"]` list is swept after the normal copy loop. For each entry: if the project has the stray AND its bytes match the source copy in this package, delete it (proves it's an installer artifact, not a user file that happens to share the name). User-owned files with different content are left untouched. Log line: `{project} — cleaned up N stray bin file(s)`. On the next `gsd-t update-all` after v3.13.12 installs, every project that picked up a stale `bin/gsd-t.js` self-heals; subsequent invocations fall through to the global install.
+
+**Files**:
+- `bin/gsd-t.js` — defensive require with full no-op stub; `DEPRECATED_BIN_STRAYS` list; post-copy sweep loop; `copyBinToolsToProject` returns `true` when either a copy happened or a stray was cleaned.
+- `test/bin-gsd-t-resilience.test.js` — 3 new tests: (a) loading `bin/gsd-t.js --help` without `debug-ledger.js` does not emit `MODULE_NOT_FOUND`; (b) byte-matching stray is deleted; (c) user-owned file (byte-divergent) is preserved.
+
+**Tests**: 1238/1238 pass (was 1235; +3 new assertions). E2E: N/A (no playwright.config.*).
+
+**Impact**: installed projects that inherited a stale `bin/gsd-t.js` from older `update-all` passes will self-heal on the next `gsd-t update-all` after installing v3.13.12. bee-poc's 130 KB stale copy is removed on its next pass, after which any invocation path that had been hitting the project-local copy falls through to the global install — no more divergent vendoring.
+
+## [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

package/bin/gsd-t-unattended.cjs

@@ -975,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.
@@ -1192,6 +1206,23 @@ function _spawnWorker(state, opts) {
       [
         "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",

package/bin/gsd-t.js

@@ -20,7 +20,19 @@ const path = require("path");
 const os = require("os");
 const readline = require("readline");
 const { execFileSync, spawn: cpSpawn } = require("child_process");
-const debugLedger = require(path.join(__dirname, "debug-ledger.js"));
+let debugLedger;
+try {
+  debugLedger = require(path.join(__dirname, "debug-ledger.js"));
+} catch (_) {
+  debugLedger = {
+    readLedger: () => [],
+    appendEntry: () => {},
+    getLedgerStats: () => ({ entryCount: 0, sizeBytes: 0, needsCompaction: false, failedHypotheses: [], passCount: 0, failCount: 0 }),
+    clearLedger: () => {},
+    compactLedger: () => {},
+    generateAntiRepetitionPreamble: () => "",
+  };
+}
 
 // ─── Configuration ───────────────────────────────────────────────────────────
 
@@ -2100,6 +2112,14 @@ const PROJECT_BIN_TOOLS = [
   "handoff-lock.cjs", "headless-auto-spawn.cjs",
 ];
 
+// Files that older versions of this installer copied into project bin/ but
+// are no longer part of PROJECT_BIN_TOOLS. On each update-all pass, sweep the
+// project's bin/ and remove any stray file that still byte-matches the source
+// copy in this package — that proves it's an old installer artifact, not a
+// user's own file sharing the same name. User-owned files (byte-divergent)
+// are left alone.
+const DEPRECATED_BIN_STRAYS = ["gsd-t.js"];
+
 function copyBinToolsToProject(projectDir, projectName) {
   const projectBinDir = path.join(projectDir, "bin");
   if (!fs.existsSync(projectBinDir)) {
@@ -2134,11 +2154,31 @@ function copyBinToolsToProject(projectDir, projectName) {
       }
     }
   }
+  let cleaned = 0;
+  for (const stray of DEPRECATED_BIN_STRAYS) {
+    const strayPath = path.join(projectBinDir, stray);
+    const srcPath = path.join(PKG_ROOT, "bin", stray);
+    if (!fs.existsSync(strayPath)) continue;
+    if (!fs.existsSync(srcPath)) continue;
+    try {
+      const strayContent = fs.readFileSync(strayPath, "utf8");
+      const srcContent = fs.readFileSync(srcPath, "utf8");
+      if (strayContent === srcContent) {
+        fs.unlinkSync(strayPath);
+        cleaned++;
+      }
+    } catch {
+      // leave the file alone on any read error
+    }
+  }
+  if (cleaned > 0) {
+    info(`${projectName} — cleaned up ${cleaned} stray bin file(s)`);
+  }
   if (copied > 0) {
     info(`${projectName} — copied ${copied} bin tool(s)`);
     return true;
   }
-  return false;
+  return cleaned > 0;
 }
 
 // One-shot migration: roll the project's progress.md Decision Log into archive
@@ -3497,6 +3537,7 @@ module.exports = {
   isNewerVersion,
   ensureDir,
   copyFile,
+  copyBinToolsToProject,
   hasPlaywright,
   hasSwagger,
   hasApi,

package/commands/gsd-t-unattended-watch.md

@@ -103,8 +103,15 @@ if (state) {
   const lt = state.lastTick ? Date.parse(state.lastTick) : null;
   const tickAgeMs = lt ? (Date.now() - lt) : null;
   out('TICK_AGE_MS', tickAgeMs);
+  // v3.13.11 Bug 3: IS_STALE computed deterministically here (not in Haiku's
+  // rendering step) — stale iff tickAgeMs > 540000 (2× 270s tick cadence per
+  // unattended-supervisor-contract §3). Below threshold → false. At/above
+  // threshold → true. Renderer just reads this flag; no prose interpretation.
+  const IS_STALE = tickAgeMs !== null && tickAgeMs > 540000;
+  out('IS_STALE', IS_STALE);
 } else {
   out('STATUS', null);
+  out('IS_STALE', false);
 }
 
 // --- run.log tail (last ~2KB via fd seek, not full read) ---
@@ -312,7 +319,7 @@ Render two blocks: the workflow-progress header (existing) plus the M38 **event-
 Format rules:
 - One extra space after each emoji (per CLAUDE.md markdown table rules — preserves alignment in terminal views).
 - Elapsed formatted as `{H}h{M}m` from `ELAPSED_MS`.
-- Last-tick age formatted as `{S}s` or `{M}m{S}s`. If age > 540s (2× tick cadence), append ` ⚠️  stale` as a soft warning.
+- Last-tick age formatted as `{S}s` or `{M}m{S}s`. If `IS_STALE=true` (computed deterministically in Step 2 as `tickAgeMs > 540000`), append ` ⚠️  stale`. The renderer must NOT interpret the threshold itself — Step 2 is the source of truth; rendering just reads the IS_STALE flag verbatim.
 - Tasks progress bar: `[████████░░░░] 8/12` — filled blocks proportional to done/total.
 - Domain breakdown only shown if ≤6 domains (otherwise too noisy).
 
@@ -395,6 +402,6 @@ After the tool call, end the turn. Do NOT output a "Next Up" hint, do NOT contin
 - **Terminal = STOP**: any terminal branch (3, 4, 5) ends the loop. The user relaunches via `/gsd-t-unattended` if needed.
 - **Never spawn subagents**: this is a pure polling command — no Task, no TeamCreate, no observability logging block.
 - **No branch guard, no pre-commit gate, no doc ripple**: this command does not modify any files.
-- **Stale-tick tolerance**: if `lastTick` is >540s old but PID is still alive, warn soft (`⚠️  stale`) but still reschedule — the supervisor may be mid-worker.
+- **Stale-tick tolerance**: `IS_STALE=true` iff `tickAgeMs > 540000` (computed deterministically in Step 2). When stale, warn soft (`⚠️  stale`) but still reschedule — the supervisor may be mid-worker. The threshold math lives in Step 2's node block; rendering reads the flag verbatim.
 
 $ARGUMENTS

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.13.10",
+  "version": "3.13.12",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",