@tekyzinc/gsd-t 2.76.10 → 3.10.11

package/bin/gsd-t.js

@@ -2592,19 +2592,30 @@ function parseHeadlessFlags(args) {
 
 /**
  * Build the claude -p invocation string for a GSD-T command.
+ *
+ * Non-interactive `claude -p` mode requires the bare `/gsd-t-X` form — the
+ * `/user:gsd-t-X` namespace prefix is rejected as "Unknown command" even
+ * though interactive mode accepts both. Verified by M36 Phase 0 Spike A
+ * (2026-04-15). See .gsd-t/M36-spike-findings.md.
  */
 function buildHeadlessCmd(command, cmdArgs) {
   const argStr = cmdArgs.length > 0 ? " " + cmdArgs.join(" ") : "";
-  return `/user:gsd-t-${command}${argStr}`;
+  return `/gsd-t-${command}${argStr}`;
 }
 
 /**
  * Map claude output + process exit code to a GSD-T headless exit code.
- * Exit codes: 0=success, 1=verify-fail, 2=context-budget-exceeded, 3=error, 4=blocked-needs-human
+ * Exit codes: 0=success, 1=verify-fail, 2=context-budget-exceeded, 3=error,
+ *             4=blocked-needs-human, 5=command-dispatch-failed
  */
 function mapHeadlessExitCode(processExitCode, output) {
   if (processExitCode !== 0 && processExitCode !== null) return 3;
-  const lower = (output || "").toLowerCase();
+  const raw = output || "";
+  const lower = raw.toLowerCase();
+  // Command dispatch failure — `claude -p` prints "Unknown command: /X"
+  // to stdout and still exits 0. Without this sentinel, a mistyped or
+  // namespace-prefixed slash command silently reports success. (M36 Phase 0.)
+  if (/^unknown command:/im.test(raw)) return 5;
   if (lower.includes("context budget exceeded") || lower.includes("context window exceeded") ||
       lower.includes("budget exceeded") || lower.includes("token limit")) return 2;
   if (lower.includes("blocked") && (lower.includes("needs human") || lower.includes("need human") ||

package/bin/handoff-lock.js

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+
+/**
+ * GSD-T Handoff Lock — Fail-safe sentinel preventing parent/child race
+ * conditions in `autoSpawnHeadless()`.
+ *
+ * Problem: when the interactive parent spawns a detached headless child to
+ * resume a session, both processes may briefly contend for the continue-here
+ * file and session JSON. If the child wakes and reads before the parent has
+ * finished writing, it sees stale or partial state.
+ *
+ * Solution: the parent acquires a short-lived lock on
+ * `.gsd-t/.handoff/lock-{sessionId}` BEFORE writing handoff artifacts and
+ * releases it AFTER `child.unref()` returns. The child waits on the same
+ * lock path before reading the continue-here file.
+ *
+ * Locks are TTL-bounded (default 30s) so a crashed parent can never wedge
+ * a future spawn — `cleanStaleLocks()` swept by housekeeping or by the next
+ * acquire attempt against an expired record reclaims the slot.
+ *
+ * Zero external dependencies (Node.js built-ins only).
+ *
+ * Contract: .gsd-t/contracts/headless-auto-spawn-contract.md v1.0.0
+ *           (implementation-detail primitive; no contract bump)
+ * Consumers: bin/headless-auto-spawn.js (Task 2 — wires this in),
+ *            commands/gsd-t-resume.md (child-side wait).
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const HANDOFF_DIR_REL = path.join(".gsd-t", ".handoff");
+const LOCK_FILE_PREFIX = "lock-";
+const DEFAULT_TTL_MS = 30000;
+const DEFAULT_WAIT_TIMEOUT_MS = 30000;
+const DEFAULT_STALE_AGE_MS = 60000;
+const POLL_INTERVAL_MS = 100;
+const GRACE_MS = 500;
+
+// ── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  acquireHandoffLock,
+  releaseHandoffLock,
+  waitForLockRelease,
+  cleanStaleLocks,
+  // Exported for tests / consumer wiring:
+  lockPathFor,
+  HANDOFF_DIR_REL,
+};
+
+// ── acquireHandoffLock ───────────────────────────────────────────────────────
+
+/**
+ * Acquire an exclusive handoff lock for the given sessionId.
+ *
+ * @param {string} projectDir
+ * @param {string} sessionId
+ * @param {{ ttlMs?: number }} [opts]
+ * @returns {{ lockPath: string, sessionId: string }} release handle
+ * @throws {Error} if an unexpired lock already exists
+ */
+function acquireHandoffLock(projectDir, sessionId, opts) {
+  if (!projectDir || typeof projectDir !== "string") {
+    throw new Error("acquireHandoffLock: `projectDir` is required");
+  }
+  if (!sessionId || typeof sessionId !== "string") {
+    throw new Error("acquireHandoffLock: `sessionId` is required");
+  }
+  const ttlMs = (opts && opts.ttlMs) || DEFAULT_TTL_MS;
+
+  const dir = path.join(projectDir, HANDOFF_DIR_REL);
+  ensureDir(dir);
+
+  const lockPath = lockPathFor(projectDir, sessionId);
+
+  // If a lock file already exists, decide whether it is still binding.
+  if (fs.existsSync(lockPath)) {
+    const existing = readLockSafe(lockPath);
+    const now = Date.now();
+    if (existing && now < existing.releaseBy + GRACE_MS) {
+      throw new Error(
+        `handoff lock held by PID ${existing.parentPid} until ${new Date(
+          existing.releaseBy,
+        ).toISOString()}`,
+      );
+    }
+    // Expired or unparseable — reclaim it.
+    try {
+      fs.unlinkSync(lockPath);
+    } catch (_) {
+      /* race: someone else cleaned it; fall through */
+    }
+  }
+
+  const acquiredAt = Date.now();
+  const record = {
+    sessionId,
+    parentPid: process.pid,
+    acquiredAt,
+    releaseBy: acquiredAt + ttlMs,
+  };
+
+  // Write atomically: O_EXCL ensures we lose if a concurrent acquirer beats
+  // us between the existsSync check above and this write.
+  let fd;
+  try {
+    fd = fs.openSync(lockPath, "wx");
+  } catch (e) {
+    if (e && e.code === "EEXIST") {
+      // Another acquirer raced ahead; surface a uniform error.
+      const existing = readLockSafe(lockPath);
+      const pid = existing ? existing.parentPid : "unknown";
+      const until = existing
+        ? new Date(existing.releaseBy).toISOString()
+        : "unknown";
+      throw new Error(`handoff lock held by PID ${pid} until ${until}`);
+    }
+    throw e;
+  }
+  try {
+    fs.writeSync(fd, JSON.stringify(record, null, 2) + "\n");
+  } finally {
+    fs.closeSync(fd);
+  }
+
+  return { lockPath, sessionId };
+}
+
+// ── releaseHandoffLock ───────────────────────────────────────────────────────
+
+/**
+ * Release a previously acquired handoff lock. Idempotent — tolerates a
+ * missing file (already released or never existed).
+ *
+ * @param {{ lockPath: string, sessionId: string }} handle
+ */
+function releaseHandoffLock(handle) {
+  if (!handle || !handle.lockPath) return;
+  try {
+    fs.unlinkSync(handle.lockPath);
+  } catch (e) {
+    if (e && e.code === "ENOENT") return; // already released
+    throw e;
+  }
+}
+
+// ── waitForLockRelease ───────────────────────────────────────────────────────
+
+/**
+ * Poll until the lock file for {sessionId} no longer exists, OR until
+ * timeoutMs elapses. Throws on timeout.
+ *
+ * @param {string} projectDir
+ * @param {string} sessionId
+ * @param {number} [timeoutMs]
+ * @returns {Promise<true>}
+ */
+function waitForLockRelease(projectDir, sessionId, timeoutMs) {
+  const limit = typeof timeoutMs === "number" ? timeoutMs : DEFAULT_WAIT_TIMEOUT_MS;
+  const lockPath = lockPathFor(projectDir, sessionId);
+  const start = Date.now();
+
+  return new Promise((resolve, reject) => {
+    const check = () => {
+      if (!fs.existsSync(lockPath)) {
+        resolve(true);
+        return;
+      }
+      if (Date.now() - start >= limit) {
+        reject(new Error(`waitForLockRelease timeout after ${limit}ms`));
+        return;
+      }
+      setTimeout(check, POLL_INTERVAL_MS);
+    };
+    check();
+  });
+}
+
+// ── cleanStaleLocks ──────────────────────────────────────────────────────────
+
+/**
+ * Sweep `.gsd-t/.handoff/` and remove any `lock-*` file whose `acquiredAt`
+ * is older than `maxAgeMs`. Returns the count of files removed.
+ *
+ * @param {string} projectDir
+ * @param {number} [maxAgeMs]
+ * @returns {number}
+ */
+function cleanStaleLocks(projectDir, maxAgeMs) {
+  const limit = typeof maxAgeMs === "number" ? maxAgeMs : DEFAULT_STALE_AGE_MS;
+  const dir = path.join(projectDir, HANDOFF_DIR_REL);
+  if (!fs.existsSync(dir)) return 0;
+
+  let removed = 0;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch (_) {
+    return 0;
+  }
+  const now = Date.now();
+  for (const name of entries) {
+    if (!name.startsWith(LOCK_FILE_PREFIX)) continue;
+    const fp = path.join(dir, name);
+    const rec = readLockSafe(fp);
+    // Unparseable lock files are treated as stale — they're not protecting
+    // anything, and leaving them around defeats the cleaner.
+    if (!rec || now - rec.acquiredAt > limit) {
+      try {
+        fs.unlinkSync(fp);
+        removed++;
+      } catch (_) {
+        /* ignore */
+      }
+    }
+  }
+  return removed;
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function lockPathFor(projectDir, sessionId) {
+  return path.join(projectDir, HANDOFF_DIR_REL, `${LOCK_FILE_PREFIX}${sessionId}`);
+}
+
+function readLockSafe(fp) {
+  try {
+    const raw = fs.readFileSync(fp, "utf8");
+    const j = JSON.parse(raw);
+    if (
+      typeof j === "object" &&
+      j &&
+      typeof j.acquiredAt === "number" &&
+      typeof j.releaseBy === "number"
+    ) {
+      return j;
+    }
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+function ensureDir(d) {
+  if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+}

package/bin/headless-auto-spawn.js

@@ -21,6 +21,14 @@
 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.js");
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -67,39 +75,69 @@ function autoSpawnHeadless(opts) {
   ensureDir(path.join(projectDir, LOG_DIR_REL));
   ensureDir(path.join(projectDir, SESSIONS_DIR_REL));
 
-  // 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"];
-
-  const child = spawn("node", childArgs, {
-    cwd: projectDir,
-    detached: true,
-    stdio: ["ignore", logFd, logFd],
-    env: process.env,
-  });
-
-  child.unref();
-  fs.closeSync(logFd);
-
-  const 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);
+  // 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"];
+
+    const child = spawn("node", childArgs, {
+      cwd: projectDir,
+      detached: true,
+      stdio: ["ignore", logFd, logFd],
+      env: process.env,
+    });
+
+    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

package/commands/gsd-t-help.md

@@ -46,6 +46,9 @@ MILESTONE WORKFLOW                                          [auto] = in wave
 AUTOMATION                                                                Auto
 ───────────────────────────────────────────────────────────────────────────────
   wave                Full cycle: partition → ... → complete (auto-advances)
+  unattended          Run active milestone unattended — detached OS supervisor, multi-worker relay (24h+)
+  unattended-watch    Show live supervisor status; reschedules every 270s via ScheduleWakeup
+  unattended-stop     Request graceful supervisor stop (sentinel file — safe mid-worker)
 
 UTILITIES                                                              Manual
 ───────────────────────────────────────────────────────────────────────────────

package/commands/gsd-t-resume.md

@@ -2,7 +2,34 @@
 
 You are resuming work after an interruption. This handles both same-session pauses (user pressed Esc to interject) and cross-session recovery (new Claude Code session).
 
-## Step 0: Detect Resume Mode
+## Step 0: Unattended Supervisor Auto-Reattach
+
+**This step runs FIRST, before reading any docs, contracts, or continue-here files.**
+
+Check whether an unattended supervisor is actively running for this project:
+
+1. Check if `.gsd-t/.unattended/supervisor.pid` exists.
+   - **Does not exist** → no supervisor running. Fall through to Step 0.1.
+
+2. **File exists**: Read the PID (single integer on one line). Run:
+   ```bash
+   kill -0 <pid> 2>/dev/null && echo "alive" || echo "dead"
+   ```
+   - **"dead"** → supervisor exited (cleanly or crashed). The PID file is stale. Log: `[resume] supervisor PID <pid> no longer alive — stale PID file, falling through to normal resume`. Fall through to Step 0.1.
+   - **"alive"** → supervisor process is live. Proceed to step 3.
+
+3. **Supervisor is alive**: Read `.gsd-t/.unattended/state.json`. Check `state.status`:
+   - **Terminal status** (`done`, `failed`, `stopped`, `crashed`) → the supervisor has finished and is waiting for cleanup. Fall through to Step 0.1 so normal resume flow runs (it will see progress.md state and continue from where the supervisor left off).
+   - **Non-terminal status** (`initializing`, `running`, or any unrecognized value) → **AUTO-REATTACH**:
+     - Print the current watch status using the data in `state.json` (elapsed time, current iteration, milestone/wave/task, last worker exit code).
+     - Call `ScheduleWakeup(270, '/user:gsd-t-unattended-watch', reason='resumed watch')`.
+     - **STOP reading resume.md entirely. Do NOT proceed to Step 0.1 or any later step. Do NOT read docs, contracts, or continue-here files. Do NOT display a headless read-back banner.** The watcher will display the live status block and re-schedule itself. Return now.
+
+Contract reference: `unattended-supervisor-contract.md` §9 (Resume Auto-Reattach Handshake)
+
+---
+
+## Step 0.1: Detect Resume Mode
 
 **Same-session** (conversation context still available — you can see prior messages about the active phase/task):
 - Skip to Step 2 — you already have the context loaded
@@ -11,6 +38,28 @@ You are resuming work after an interruption. This handles both same-session paus
 **Cross-session** (first command in a new session, no prior conversation context):
 - Run Step 1 to load full state
 
+## Step 0.2: Handoff Lock Wait (headless resume only)
+
+Before reading any continue-here file or state file, check if a parent process wrote a handoff lock for this session:
+
+```bash
+node -e "
+const sessionId = process.env.CLAUDE_HEADLESS_SESSION_ID;
+if (!sessionId) { process.exit(0); }
+const hl = require('./bin/handoff-lock.js');
+hl.waitForLockRelease('.', sessionId, 5000)
+  .then(() => process.exit(0))
+  .catch(e => { console.error('[resume] handoff lock wait timed out:', e.message); process.exit(0); });
+"
+```
+
+- If `CLAUDE_HEADLESS_SESSION_ID` is not set (interactive resume) → the script exits immediately; no wait needed.
+- If set → wait up to **5 seconds** for the parent's handoff lock to be released before reading `.gsd-t/continue-here-*.md` or any other state file. On timeout, log and proceed anyway (parent may have crashed after spawning).
+
+This prevents the child side of a headless runway-handoff from reading a partial continue-here file written by the parent. Contract: `headless-auto-spawn-contract.md` v1.0.0, m35-gap-fixes T2 deferred hook.
+
+---
+
 ## Step 0.5: Headless Read-Back Banner (MANDATORY)
 
 Before loading full state, surface any completed headless sessions the user hasn't seen yet. Run this once at the start of every resume invocation:

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

@@ -0,0 +1,83 @@
+# GSD-T: Unattended Stop — Signal Supervisor to Halt
+
+**Model**: haiku (trivial sentinel toucher — no reasoning needed)
+
+You are signaling the unattended supervisor to halt cleanly between worker iterations by writing the stop sentinel file at `.gsd-t/.unattended/stop`. This is a fire-and-forget command: no PID kill, no wait, no confirmation prompt.
+
+See `unattended-supervisor-contract.md` §10 (Stop Mechanism) for the full handshake.
+
+## Step 1: Check Supervisor State Directory Exists
+
+Run via Bash:
+
+```bash
+if [ ! -d ".gsd-t/.unattended" ]; then
+  echo "No supervisor state directory — nothing to stop."
+  exit 0
+fi
+```
+
+If the directory does not exist, exit 0 (not an error — there is simply nothing to signal).
+
+## Step 2: Check Supervisor PID File Exists
+
+Run via Bash:
+
+```bash
+if [ ! -f ".gsd-t/.unattended/supervisor.pid" ]; then
+  echo "No supervisor running in this project (no PID file at .gsd-t/.unattended/supervisor.pid)."
+  exit 0
+fi
+```
+
+If the PID file is missing, the supervisor has already finalized cleanly. Exit 0 without writing the sentinel.
+
+## Step 3: Read Current Session Snapshot
+
+Run via Bash to grab the session ID and current iteration from `state.json` (best-effort — tolerate missing or partial state):
+
+```bash
+node -e "
+try {
+  const s = JSON.parse(require('fs').readFileSync('.gsd-t/.unattended/state.json', 'utf8'));
+  console.log('SESSION=' + (s.sessionId || 'unknown'));
+  console.log('ITER=' + (s.iter ?? 'unknown'));
+  console.log('STATUS=' + (s.status || 'unknown'));
+} catch (e) {
+  console.log('SESSION=unknown');
+  console.log('ITER=unknown');
+  console.log('STATUS=unknown');
+}
+"
+```
+
+## Step 4: Write the Stop Sentinel
+
+Write `.gsd-t/.unattended/stop` containing the current ISO timestamp as the body (for diagnostics — the supervisor only checks for the file's existence, not its contents):
+
+```bash
+node -e "require('fs').writeFileSync('.gsd-t/.unattended/stop', new Date().toISOString())"
+```
+
+This is race-free, terminal-close-safe, and language-agnostic (per contract §10).
+
+## Step 5: Print Confirmation
+
+Output the confirmation block:
+
+```
+🛑  Stop sentinel written. Supervisor will halt between next worker iterations (within ~5 minutes). State file will finalize with status=stopped.
+
+   Session: {SESSION from Step 3}
+   Iter:    {ITER from Step 3}
+   Status:  {STATUS from Step 3}
+
+   The current worker will run to completion (up to ~1h). Stop is honored at the next pre-worker checkpoint.
+   No kill signal is sent — this is a clean cooperative halt.
+```
+
+## Step 6: Return Immediately
+
+Do NOT wait for the supervisor to acknowledge. Do NOT poll state.json. Do NOT call ScheduleWakeup. The supervisor will finalize state.json with `status=stopped` on its next iteration check — that's the watch loop's job to observe, not this command's.
+
+$ARGUMENTS