@tekyzinc/gsd-t 2.76.10 → 3.10.11

package/commands/gsd-t-unattended.md

@@ -0,0 +1,420 @@
+# GSD-T: Unattended — Launch the Background Supervisor
+
+**Model**: sonnet (pre-flight reasoning + spawn coordination)
+
+You are launching the GSD-T unattended supervisor — a detached background process that drives the active milestone to completion by spawning `claude -p` worker iterations in a relay, without human intervention. The supervisor runs outside the interactive Claude session and survives `/clear`, terminal close, and session expiry.
+
+This command performs pre-flight checks, spawns the supervisor via the cross-platform helper, verifies liveness, displays the initial status block, and schedules the first watch tick. It then returns — the watch loop takes over.
+
+See `unattended-supervisor-contract.md` §7 (Launch Handshake), §4 (Status Enum), §3 (state.json schema).
+
+## Step 1: Pre-Flight Checks
+
+### 1a: Verify GSD-T Project
+
+Run via Bash:
+
+```bash
+if [ ! -f ".gsd-t/progress.md" ]; then
+  echo "ERROR: .gsd-t/progress.md not found — not a GSD-T project. Run /user:gsd-t-init first."
+  exit 1
+fi
+```
+
+If the file is missing, stop immediately with the error above. Do NOT proceed.
+
+### 1b: Check for an Already-Running Supervisor
+
+Run via Bash:
+
+```bash
+node -e "
+const fs = require('fs');
+const PID_FILE = '.gsd-t/.unattended/supervisor.pid';
+
+if (!fs.existsSync(PID_FILE)) {
+  console.log('PID_RUNNING=false');
+  process.exit(0);
+}
+
+let pid = null;
+try {
+  pid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
+} catch (_) {}
+
+if (!pid || !Number.isFinite(pid)) {
+  console.log('PID_RUNNING=false');
+  process.exit(0);
+}
+
+let alive = false;
+try { process.kill(pid, 0); alive = true; }
+catch (e) { alive = e.code === 'EPERM'; }
+
+console.log('PID_RUNNING=' + alive);
+console.log('PID=' + pid);
+"
+```
+
+If `PID_RUNNING=true`, **STOP** and print:
+
+```
+🔴  Unattended supervisor is already running (PID {PID}).
+
+    Use /user:gsd-t-unattended-stop to request a clean halt, then wait for the
+    watch loop to confirm it has stopped before relaunching.
+
+    To just watch the current run: /user:gsd-t-unattended-watch
+```
+
+Do NOT spawn a second supervisor. End the turn.
+
+### 1c: Parse Arguments and Resolve Milestone
+
+Parse `$ARGUMENTS` for:
+- `--hours=N` — wall-clock cap in hours (default: `24`)
+- `--milestone=LABEL` — milestone to drive (default: read from `.gsd-t/progress.md`)
+- `--max-iterations=N` — iteration cap (default: `200`)
+- `--dry-run` — preflight only; print what would be spawned, do NOT spawn
+
+**Persistent overrides**: create `.gsd-t/.unattended/config.json` to change
+defaults per-project (caps, protected branches, dirty-tree whitelist). CLI
+flags always win over the config file. See `docs/unattended-config.md` for
+the full schema and common recipes (e.g. `{"protectedBranches": []}` for
+solo projects that commit directly to main).
+
+Run via Bash to read the current milestone from progress.md:
+
+```bash
+node -e "
+const fs = require('fs');
+let milestone = '';
+try {
+  const text = fs.readFileSync('.gsd-t/progress.md', 'utf8');
+  // Look for '## Current Milestone: M36' or 'Milestone: M36' patterns
+  const m = text.match(/(?:##\s*)?(?:Current\s+)?Milestone[:\s]+(\S+)/i);
+  if (m) milestone = m[1].replace(/[^A-Za-z0-9_.-]/g, '');
+} catch (_) {}
+console.log('MILESTONE=' + (milestone || 'unknown'));
+"
+```
+
+Also read the project name from `package.json` (best-effort):
+
+```bash
+node -e "
+try {
+  const p = JSON.parse(require('fs').readFileSync('package.json', 'utf8'));
+  console.log('PROJECT_NAME=' + (p.name || ''));
+} catch (_) {
+  console.log('PROJECT_NAME=');
+}
+"
+```
+
+### 1d: Check for Stale Stop Sentinel
+
+If `.gsd-t/.unattended/stop` exists from a previous run, remove it before spawning (per contract §10 — the launch command cleans the stale sentinel):
+
+```bash
+if [ -f ".gsd-t/.unattended/stop" ]; then
+  rm ".gsd-t/.unattended/stop"
+  echo "STALE_SENTINEL=removed"
+else
+  echo "STALE_SENTINEL=none"
+fi
+```
+
+If the sentinel was removed, print: `ℹ️  Removed stale stop sentinel from previous run.`
+
+### 1e: Verify Required Software is Installed
+
+The unattended supervisor depends on platform-specific helpers. Check them up front and fail fast with clear install instructions rather than crashing mid-run.
+
+Run via Bash:
+
+```bash
+node -e "
+const { execSync } = require('child_process');
+const os = require('os');
+const platform = os.platform();
+
+function has(cmd) {
+  try {
+    const which = platform === 'win32' ? 'where' : 'command -v';
+    execSync(which + ' ' + cmd, { stdio: 'ignore' });
+    return true;
+  } catch (_) { return false; }
+}
+
+const missing = [];
+const warnings = [];
+
+// REQUIRED on all platforms
+if (!has('node')) missing.push({ name: 'node', install: 'https://nodejs.org (>= 16)' });
+if (!has('claude')) {
+  missing.push({
+    name: 'claude',
+    install: platform === 'win32'
+      ? 'npm install -g @anthropic-ai/claude-code (then ensure claude.cmd is on PATH)'
+      : 'npm install -g @anthropic-ai/claude-code'
+  });
+}
+if (!has('git')) missing.push({ name: 'git', install: 'https://git-scm.com/downloads' });
+
+// PLATFORM-SPECIFIC (warnings only — supervisor runs without them, just less resilient)
+if (platform === 'darwin') {
+  if (!has('caffeinate')) warnings.push('caffeinate (macOS built-in) — missing means sleep may interrupt long runs');
+} else if (platform === 'linux') {
+  if (!has('systemd-inhibit') && !has('caffeine')) {
+    warnings.push('systemd-inhibit or caffeine — missing means sleep/screen-lock may interrupt long runs');
+  }
+  if (!has('notify-send')) {
+    warnings.push('notify-send (libnotify-bin) — missing means no desktop notifications on milestone events');
+  }
+} else if (platform === 'win32') {
+  warnings.push('Windows: sleep prevention uses PowerShell SetThreadExecutionState — no external helper required');
+  warnings.push('Windows: desktop notifications use BurntToast PowerShell module — install with: Install-Module BurntToast');
+}
+
+if (missing.length > 0) {
+  console.log('PREFLIGHT=fail');
+  console.log('MISSING=' + JSON.stringify(missing));
+} else {
+  console.log('PREFLIGHT=ok');
+}
+if (warnings.length > 0) {
+  console.log('WARNINGS=' + JSON.stringify(warnings));
+}
+"
+```
+
+If `PREFLIGHT=fail`, **STOP** and print:
+
+```
+❌  Required software missing — cannot launch unattended supervisor.
+
+    Missing:
+{for each item in MISSING:}
+      • {name}
+        Install: {install}
+
+    Install the missing software and retry: /user:gsd-t-unattended
+```
+
+End the turn. Do NOT spawn.
+
+If `WARNINGS` were emitted, print them as a non-blocking advisory before proceeding:
+
+```
+⚠️  Platform advisories (non-blocking):
+{for each warning:}
+      • {warning}
+
+    Supervisor will still launch, but consider installing these for best reliability.
+```
+
+## Step 2: Spawn the Detached Supervisor
+
+⚙ [sonnet] gsd-t-unattended → spawning detached supervisor
+
+**Before spawn — read starting context tokens (observability bracket):**
+
+```bash
+T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")
+T0_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
+T0_PCT=$(node -e "try{const tb=require('./bin/token-budget.js');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
+```
+
+If `--dry-run` was specified, print:
+
+```
+🔎  Dry-run mode — would spawn:
+    node bin/gsd-t.js unattended --hours={hours} --milestone={milestone} --max-iterations={maxIterations}
+    Project: {cwd}
+
+    No supervisor launched. Remove --dry-run to proceed.
+```
+
+Then end the turn.
+
+Otherwise, run the actual spawn:
+
+```bash
+node -e "
+const path = require('path');
+const { spawnSupervisor } = require('./bin/gsd-t-unattended-platform.js');
+
+// Parse CLI args forwarded from the launch command
+const hours = parseInt(process.env.GSD_T_HOURS || '24', 10) || 24;
+const milestone = process.env.GSD_T_MILESTONE || '';
+const maxIterations = parseInt(process.env.GSD_T_MAX_ITERATIONS || '200', 10) || 200;
+
+const binPath = path.resolve(__dirname, 'bin', 'gsd-t.js');
+const cwd = process.cwd();
+
+const extraArgs = [];
+if (hours !== 24)         extraArgs.push('--hours=' + hours);
+if (milestone)            extraArgs.push('--milestone=' + milestone);
+if (maxIterations !== 200) extraArgs.push('--max-iterations=' + maxIterations);
+
+const result = spawnSupervisor({ binPath, args: extraArgs, cwd });
+console.log('SPAWNED_PID=' + result.pid);
+" \
+  GSD_T_HOURS={hours} \
+  GSD_T_MILESTONE={milestone} \
+  GSD_T_MAX_ITERATIONS={maxIterations}
+```
+
+Capture `SPAWNED_PID` from the output.
+
+**After spawn — record observability bracket:**
+
+```bash
+T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))
+T1_TOKENS=$(node -e "try{const s=require('fs').readFileSync('.gsd-t/.context-meter-state.json','utf8');process.stdout.write(String(JSON.parse(s).inputTokens||0))}catch(_){process.stdout.write('0')}")
+T1_PCT=$(node -e "try{const tb=require('./bin/token-budget.js');process.stdout.write(String(tb.getSessionStatus('.').pct||0))}catch(_){process.stdout.write('0')}")
+COUNTER=$(node bin/task-counter.cjs status 2>/dev/null | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{process.stdout.write(String(JSON.parse(s).count||''))}catch(_){process.stdout.write('')}})")
+```
+
+Append to `.gsd-t/token-log.md` (create with header if missing):
+
+```bash
+node -e "
+const fs = require('fs');
+const LOG = '.gsd-t/token-log.md';
+const header = '| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Tasks-Since-Reset |\n|---|---|---|---|---|---|---|---|---|---|\n';
+const row = '| ${DT_START} | ${DT_END} | gsd-t-unattended | Step 2 | sonnet | ${DURATION}s | supervisor spawned PID ${SPAWNED_PID} | | | ${COUNTER} |\n';
+if (!fs.existsSync(LOG)) fs.writeFileSync(LOG, header);
+fs.appendFileSync(LOG, row);
+"
+```
+
+## Step 3: Verify Supervisor Liveness
+
+Wait up to 2 seconds for the supervisor to write its PID file and transition out of `initializing`:
+
+```bash
+node -e "
+const fs = require('fs');
+const path = require('path');
+
+const PID_FILE = '.gsd-t/.unattended/supervisor.pid';
+const STATE_FILE = '.gsd-t/.unattended/state.json';
+const LOG_FILE = '.gsd-t/.unattended/run.log';
+const SPAWNED_PID = parseInt(process.env.SPAWNED_PID || '0', 10);
+const WAIT_MS = 2000;
+const POLL_MS = 100;
+
+function sleep(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }
+
+let alive = false;
+let pidFromFile = null;
+const deadline = Date.now() + WAIT_MS;
+
+while (Date.now() < deadline) {
+  // Check process liveness via process.kill(pid, 0)
+  if (SPAWNED_PID > 0) {
+    try { process.kill(SPAWNED_PID, 0); alive = true; } catch (e) {
+      alive = e.code === 'EPERM';
+    }
+  }
+  // Also try reading the PID file the supervisor writes
+  if (fs.existsSync(PID_FILE)) {
+    try { pidFromFile = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10); } catch (_) {}
+  }
+  if (alive || pidFromFile) break;
+  sleep(POLL_MS);
+}
+
+if (!alive && !pidFromFile) {
+  console.log('LIVENESS=dead');
+  // Emit last few lines of run.log if it exists
+  if (fs.existsSync(LOG_FILE)) {
+    try {
+      const txt = fs.readFileSync(LOG_FILE, 'utf8');
+      const tail = txt.split('\n').filter(l => l.trim()).slice(-20).join('\n');
+      console.log('LOG_TAIL=' + JSON.stringify(tail));
+    } catch (_) { console.log('LOG_TAIL='); }
+  } else {
+    console.log('LOG_TAIL=');
+  }
+} else {
+  console.log('LIVENESS=ok');
+  console.log('PID_FROM_FILE=' + (pidFromFile || SPAWNED_PID));
+}
+" SPAWNED_PID=${SPAWNED_PID}
+```
+
+If `LIVENESS=dead`, the supervisor crashed at startup. Print diagnostics and **STOP**:
+
+```
+💥  Supervisor crashed at startup (PID {SPAWNED_PID} no longer alive after 2s).
+
+    Startup diagnostics (run.log tail):
+    ──────────────────────────────────────────────────────────────
+    {LOG_TAIL}
+    ──────────────────────────────────────────────────────────────
+
+    Common causes:
+      • Missing Node.js or claude binary on PATH
+      • .gsd-t/progress.md has no active milestone
+      • Protected branch or dirty worktree rejected by safety rails
+      • Permissions error on .gsd-t/.unattended/ directory
+
+    Fix the issue above and retry: /user:gsd-t-unattended
+```
+
+End the turn without scheduling a watch tick.
+
+## Step 4: Display Initial Status Block
+
+Print the launch confirmation block:
+
+```
+🟢  Unattended supervisor launched.
+
+    PID:            {PID_FROM_FILE}
+    Project:        {PROJECT_NAME}
+    Milestone:      {milestone}
+    Max hours:      {hours}
+    Max iterations: {maxIterations}
+    Log:            .gsd-t/.unattended/run.log
+    State:          .gsd-t/.unattended/state.json
+    Watch:          ScheduleWakeup every 270s
+
+    The supervisor is running detached — it survives /clear and terminal close.
+    Stop gracefully: /user:gsd-t-unattended-stop
+    Watch manually:  /user:gsd-t-unattended-watch
+```
+
+## Step 5: Schedule the First Watch Tick
+
+Call the harness `ScheduleWakeup` tool with these exact parameters:
+
+- `delaySeconds`: `270` (fixed — inside the 5-minute prompt-cache TTL)
+- `prompt`: `/user:gsd-t-unattended-watch`
+- `reason`: `first unattended tick`
+
+Tool invocation pattern (make this a real tool call, not a bash command):
+
+```
+ScheduleWakeup(
+  delaySeconds: 270,
+  prompt: "/user:gsd-t-unattended-watch",
+  reason: "first unattended tick"
+)
+```
+
+After the tool call, end the turn. The in-session watch loop takes over from here. Do NOT output a "Next Up" block — this is a self-rescheduling loop, not a phase workflow.
+
+## Notes
+
+- **Singleton**: only one supervisor per project at a time. PID collision → refuse with "already running" message.
+- **Stale stop sentinel**: if `.gsd-t/.unattended/stop` exists from a prior run, Step 1d removes it before spawning.
+- **Platform helper**: uses `spawnSupervisor` from `bin/gsd-t-unattended-platform.js` — never hand-rolls `child_process.spawn` directly. This handles macOS/Linux/Windows differences.
+- **Dry-run**: `--dry-run` prints the would-be invocation without spawning. Useful for validating flags before a long overnight run.
+- **No doc ripple, no pre-commit gate**: this command spawns a background process; it does not modify any source files or contracts.
+- **watch command is stateless**: after this command returns, every `/user:gsd-t-unattended-watch` tick re-reads state from disk. There is no in-memory state to preserve.
+
+$ARGUMENTS

package/commands/gsd-t-wave.md

@@ -201,7 +201,7 @@ The JSON on stdout contains `{consumed, estimated_remaining, pct, threshold}`
 Exit-code handling (three-band model per `token-budget-contract.md` v3.0.0):
 - `0` (normal, <70%) → proceed to the next phase at full quality.
 - `13` (warn, 70–85%) → log the warning to `.gsd-t/token-log.md` and proceed to the next phase at full quality. **Never downgrade models or skip phases** — the runway estimator (m35-runway-estimator) is responsible for halting cleanly before reaching `stop`.
-- `10` (stop, ≥85%) → STOP the wave loop. Save checkpoint to `.gsd-t/progress.md` — record which phases are complete, which remain. Output exactly: `⏸️ Wave orchestrator context gate reached ({pct}% of model window). Progress saved. Run /clear then /user:gsd-t-wave to continue from the next phase.` Do NOT spawn the next phase agent.
+- `10` (stop, ≥85%) → STOP the wave loop. Save checkpoint to `.gsd-t/progress.md` — record which phases are complete, which remain. Call `autoSpawnHeadless({command: 'gsd-t-wave', args, projectDir})` — this spawns a fresh headless session that auto-resumes via `/gsd-t-resume` without any manual `/clear`. Output: `⏸️ Wave orchestrator context gate reached ({pct}% of model window) — handing off to a fresh headless session (ID: {id}). Progress saved.` Return cleanly. Do NOT spawn the next phase agent, do NOT exit with a special code — the handoff is the success path.
 
 As of v2.0.0 (M34), the wave orchestrator reads the SAME `bin/token-budget.js` real-source measurement as the execute orchestrator — both trace back to `.gsd-t/.context-meter-state.json` produced by the Context Meter PostToolUse hook. Each phase spawn (PARTITION, DISCUSS, PLAN, IMPACT, EXECUTE, TEST-SYNC, INTEGRATE, VERIFY+COMPLETE, DOC-RIPPLE) causes post-call updates to the state file, so each subsequent gate check reflects the real context consumption trajectory. When the state file is absent or stale, the call falls back to the historical heuristic.
 

package/docs/GSD-T-README.md

@@ -114,6 +114,9 @@ GSD-T reads all state files and tells you exactly where you left off.
 
 | Command | Purpose | Auto |
 |---------|---------|------|
+| `/user:gsd-t-unattended` | Launch detached supervisor — runs active milestone to completion with zero human intervention | Manual |
+| `/user:gsd-t-unattended-watch` | Watch tick — fires every 270s via ScheduleWakeup, reports supervisor status | Auto |
+| `/user:gsd-t-unattended-stop` | Touch stop sentinel — supervisor halts after current worker finishes | Manual |
 | `/user:gsd-t-wave` | Full cycle, auto-advances all phases | Manual |
 | `/user:gsd-t-status` | Cross-domain progress view with token breakdown, global ELO and cross-project rankings | Manual |
 | `/user:gsd-t-resume` | Restore context, continue | Manual |
@@ -286,6 +289,20 @@ Drop a `.md` file into `templates/stacks/` to add a new stack. Files prefixed wi
 
 ---
 
+## Unattended Execution (M36)
+
+Run the active milestone to completion over hours or days with zero human intervention. The unattended supervisor is an OS-level process that spawns `claude -p` workers in a relay — each worker runs in a fresh context window, completing one round of wave tasks before handing off to the next. The supervisor survives `/clear`, terminal close, and sleep/wake cycles (macOS/Linux; see `docs/unattended-windows-caveats.md` for Windows).
+
+**Relay model**: Each iteration spawns a fresh `claude -p` session with a compact prompt derived from `.gsd-t/progress.md` state. The supervisor waits for the worker to exit, records the exit code in `state.json`, runs safety checks (gutter detection, blocker sentinel scan), and spawns the next worker. Workers never overlap. Context rot is impossible — each worker starts clean.
+
+**Watch loop**: `/user:gsd-t-unattended` starts an in-session ScheduleWakeup loop that ticks every 270 seconds. Each tick reads `state.json` and `supervisor.pid` to render a live progress block. When the supervisor reaches a terminal state (`done`, `failed`, `stopped`), the watch loop stops rescheduling and prints a final summary. A `/clear` + `/user:gsd-t-resume` transparently re-attaches: the resume command checks for a live `supervisor.pid` and re-starts the watch loop automatically.
+
+**Safety rails**: Branch protection (refuses to run on `main`/`master`/`release/*` by default), dirty-tree check (whitelists GSD-T runtime files), per-iteration gutter detection (repeated error patterns, file thrash, no-progress stall), wall-clock and iteration caps, and a blocker sentinel that halts on unrecoverable worker errors.
+
+**Contract**: `.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0 is the authoritative reference for the state file schema, exit codes, CLI surface, and platform matrix.
+
+---
+
 ## Headless Mode
 
 Run GSD-T non-interactively in CI/CD pipelines or automated workflows.

package/docs/architecture.md

@@ -68,14 +68,14 @@ The framework has no runtime — it is consumed entirely by Claude Code's slash
 
 ### Headless Mode (M23 — complete)
 - **doHeadless(args)**: Dispatch function for the `headless` CLI subcommand.
-- **doHeadlessExec(command, cmdArgs, flags)**: Wraps `claude -p "/user:gsd-t-{command}"` via `execFileSync`. Verifies claude CLI availability, enforces timeout, writes log file if `--log` requested. Returns structured JSON if `--json` flag set.
+- **doHeadlessExec(command, cmdArgs, flags)**: Wraps `claude -p "/gsd-t-{command}"` via `execFileSync`. Verifies claude CLI availability, enforces timeout, writes log file if `--log` requested. Returns structured JSON if `--json` flag set. (M36 Phase 0: prompt form is `/gsd-t-X`, NOT `/user:gsd-t-X` — non-interactive mode rejects the `/user:` namespace prefix.)
 - **parseHeadlessFlags(args)**: Extracts `--json`, `--timeout=N`, `--log` from raw args. Returns `{ flags, positional }`.
-- **buildHeadlessCmd(command, cmdArgs)**: Builds the `/user:gsd-t-{command}` prompt string.
-- **mapHeadlessExitCode(processExitCode, output)**: Maps process exit code + output text patterns to GSD-T exit codes (0–4).
+- **buildHeadlessCmd(command, cmdArgs)**: Builds the bare `/gsd-t-{command}` prompt string. Interactive-mode `/user:` prefix deliberately omitted — see `.gsd-t/M36-spike-findings.md` Spike A.
+- **mapHeadlessExitCode(processExitCode, output)**: Maps process exit code + output text patterns to GSD-T exit codes (0–5).
 - **headlessLogPath(projectDir, timestamp)**: Generates `.gsd-t/headless-{timestamp}.log` path.
 - **doHeadlessQuery(type)**: Dispatches to one of 7 query functions. All pure Node.js file reads, no LLM calls, <100ms.
 - **Query functions** (7): `queryStatus`, `queryDomains`, `queryContracts`, `queryDebt`, `queryContext`, `queryBacklog`, `queryGraph` — each reads corresponding `.gsd-t/` file and returns typed JSON result.
-- **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 (M36 Phase 0 — `claude -p` returned `Unknown command:` for the slash command; caller should treat as a bug not a transient failure)
 - **CI/CD examples**: `docs/ci-examples/github-actions.yml` (GitHub Actions), `docs/ci-examples/gitlab-ci.yml` (GitLab CI)
 
 ### Compaction-Proof Debug Loop (M29 — complete)
@@ -272,6 +272,83 @@ QA runs inline or as Task subagent depending on phase (M10 refactor). Removed fr
 - **Resource limits**: Heartbeat stdin capped at 1MB, HTTP responses capped at 1MB (M5), 5s/8s timeouts, 7-day file cleanup
 - **Wave security**: `bypassPermissions` mode documented with attack surface analysis and mitigations (M5)
 
+## Unattended Supervisor (M36)
+
+The unattended supervisor is a cross-session relay engine that runs an active GSD-T milestone to completion over hours or days without human intervention. It spans the boundary between the interactive Claude session and the OS process layer.
+
+### Component Diagram
+
+```
+Interactive Claude session
+  └── /user:gsd-t-unattended (launch command)
+        ├── Pre-flight safety checks (branch, dirty tree)
+        └── spawn(detached) → Supervisor process (bin/gsd-t-unattended.js)
+                               ├── writes .gsd-t/.unattended/supervisor.pid
+                               ├── writes .gsd-t/.unattended/state.json  (atomic rewrite each iter)
+                               ├── appends .gsd-t/.unattended/run.log    (worker stdout+stderr)
+                               ├── checks .gsd-t/.unattended/stop        (sentinel — presence = halt)
+                               └── relay loop:
+                                    spawnSync('claude -p "/gsd-t-resume"')
+                                      → worker exits → post-worker safety check → next iter
+
+In-session watch loop (every 270s via ScheduleWakeup)
+  └── /user:gsd-t-unattended-watch
+        ├── reads supervisor.pid  (kill -0 liveness)
+        ├── reads state.json      (status, iter, lastTick)
+        └── reschedules or reports final status
+```
+
+### State Directory Layout
+
+```
+.gsd-t/.unattended/
+├── supervisor.pid   — Integer PID. Exists ONLY while supervisor is alive.
+├── state.json       — Live state snapshot. Atomically rewritten between iterations.
+├── run.log          — Append-only worker stdout+stderr. Never truncated during a run.
+├── stop             — Sentinel file. Absence = run. Presence = user-requested stop.
+└── config.json      — Optional per-project config overrides (maxIterations, hours, etc.)
+```
+
+Sibling: `.gsd-t/.handoff/` — owned by M35-gap-fixes for single-shot handoff locks (see below).
+
+### Contract
+
+`.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0 — authoritative source for: state schema, status enum, exit-code table, launch handshake, watch tick decision tree, resume auto-reattach handshake, stop mechanism, safety-rails hook points, and CLI surface.
+
+### Platform Abstraction Layer (`bin/gsd-t-unattended-platform.js`)
+
+Exports four cross-platform functions:
+
+| Export | macOS | Linux | Windows |
+|--------|-------|-------|---------|
+| `spawnSupervisor(args)` | `spawn(node, ...)` detached | same | same (`windowsHide:true`) |
+| `preventSleep()` | `caffeinate -i` subprocess | `systemd-inhibit` or no-op | no-op (not supported — see docs/unattended-windows-caveats.md) |
+| `releaseSleep(handle)` | kill caffeinate PID | release inhibit or no-op | no-op |
+| `notify(title, msg, level)` | `osascript` | `notify-send` | no-op |
+| `resolveClaudePath()` | PATH lookup | PATH lookup | `claude.cmd` via PATH |
+
+### Safety Rails (`bin/gsd-t-unattended-safety.js`)
+
+Called at four supervisor hook points (pre-launch, supervisor-init, pre-worker, post-worker):
+
+- **Gutter detection**: stall pattern — repeated identical errors or no file changes for N iterations
+- **Blocker sentinels**: scan worker stdout for unrecoverable-error markers (`BLOCKED_NEEDS_HUMAN`, `DISPATCH_FAILED`)
+- **Iteration cap**: `maxIterations` guard (default 200)
+- **Wall-clock cap**: `hours` guard (default 24h)
+- **Branch/dirty-tree pre-flight**: refuses to start on protected branches or uncleaned worktrees
+
+Each check returns `{ ok, reason?, code? }`. A `false` result halts with `status = 'failed'` and the corresponding exit code (6=gutter, 7=protected-branch, 8=dirty-tree).
+
+### Handoff-Lock Primitive (`bin/handoff-lock.js`)
+
+Closes the M35 parent/child race in `bin/headless-auto-spawn.js`. When the runway estimator fires `autoSpawnHeadless()`, the parent session writes a lock file in `.gsd-t/.handoff/` before spawning the child and removes it only after the child has confirmed PID + state-ready. Prevents the child from beginning execution before the parent has cleanly exited — eliminating the race where both sessions wrote to the same `.gsd-t/` files simultaneously.
+
+### Resume Auto-Reattach
+
+`/user:gsd-t-resume` Step 0 checks for a live supervisor before any other resume logic. If `supervisor.pid` exists and `kill -0` succeeds and `state.json.status` is non-terminal, the resume command skips normal resume flow entirely, prints the current watch block, and calls `ScheduleWakeup(270, '/user:gsd-t-unattended-watch', ...)`. The user transparently re-enters the watch loop without any manual step.
+
+---
+
 ## Design Decisions
 
 | Date | Decision | Rationale | Alternatives Considered |

package/docs/infrastructure.md

@@ -312,6 +312,110 @@ Read-only surface onto the token telemetry stream. Backward-compatible with pre-
 
 When a sonnet-default phase hits a complexity signal that warrants opus (e.g., cross-module refactor detected mid-execution), the command may emit an `/advisor` hook line in its output — a structured suggestion for the orchestrator to escalate the **next** spawn of that phase to opus. This is a plan-time signal, not a runtime swap: the current spawn completes at its assigned tier, and the escalation applies to subsequent work. See `.gsd-t/contracts/model-selection-contract.md` for the hook schema.
 
+## Unattended Supervisor Setup (M36)
+
+The unattended supervisor runs an active GSD-T milestone to completion in a detached OS process — no terminal needed, no human intervention required.
+
+### Quick Start
+
+```bash
+# From within an interactive Claude session:
+/user:gsd-t-unattended
+
+# From the terminal (detached — returns immediately):
+gsd-t unattended --hours=24 --milestone=M36
+
+# Watch current run status (in-session, 270s tick):
+/user:gsd-t-unattended-watch
+
+# Request a graceful stop:
+/user:gsd-t-unattended-stop
+```
+
+### CLI Flags
+
+```
+gsd-t unattended [OPTIONS]
+  --hours=24              Wall-clock cap in hours (default: 24)
+  --max-iterations=200    Worker iteration cap (default: 200)
+  --project=.             Project directory (default: cwd)
+  --branch=AUTO           Branch to run on; AUTO = current non-protected branch
+  --on-done=print         Terminal action: print | merge-commit (merge-commit is v2)
+  --dry-run               Preflight only; no spawn
+  --verbose               Extra log detail
+  --test-mode             Uses stub worker; for CI and smoke tests
+```
+
+### Config File (optional)
+
+`.gsd-t/unattended-config.json` — per-project overrides. Absence = hardcoded defaults.
+
+```json
+{
+  "hours": 24,
+  "maxIterations": 200,
+  "gutterNoProgressIters": 5,
+  "workerTimeoutMs": 3600000,
+  "protectedBranches": ["main", "master", "develop", "trunk"],
+  "dirtyTreeWhitelist": [".gsd-t/.unattended/*", ".gsd-t/events/*.jsonl"]
+}
+```
+
+### State Files
+
+| File | Purpose |
+|------|---------|
+| `.gsd-t/.unattended/supervisor.pid` | Integer PID. Exists only while supervisor is alive. |
+| `.gsd-t/.unattended/state.json` | Live state snapshot — status, iter, milestone, lastTick, etc. Full schema in `unattended-supervisor-contract.md`. |
+| `.gsd-t/.unattended/run.log` | Append-only worker stdout+stderr. Never truncated during a run. |
+| `.gsd-t/.unattended/stop` | Sentinel — touching this file requests a graceful stop. |
+| `.gsd-t/.unattended/config.json` | Optional per-project config overrides (same keys as CLI flags). |
+
+### Required Platform Helpers
+
+| Platform | Sleep Prevention | Notifications |
+|----------|-----------------|---------------|
+| macOS | `caffeinate` (built-in) | `osascript` (built-in) |
+| Linux | `systemd-inhibit` or no-op | `notify-send` (install via `apt`/`dnf`) |
+| Windows | NOT supported — see `docs/unattended-windows-caveats.md` | no-op |
+
+macOS and Linux work out of the box on standard installs. Windows can run the supervisor but the machine may sleep mid-run.
+
+### Contract
+
+`.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0 — authoritative state schema, exit-code table, status enum, launch/resume handshakes.
+
+### Troubleshooting
+
+**Supervisor won't start**
+- Check `.gsd-t/.unattended/run.log` for error output
+- Run `gsd-t unattended --dry-run` to run pre-flight checks without spawning
+- Verify no protected branch: `git branch --show-current`
+
+**"Already running" error**
+```bash
+# Verify supervisor is actually alive:
+kill -0 $(cat .gsd-t/.unattended/supervisor.pid) && echo "alive" || echo "stale PID"
+
+# If stale, remove PID file:
+rm .gsd-t/.unattended/supervisor.pid
+
+# Or request a graceful stop:
+/user:gsd-t-unattended-stop
+# (or) touch .gsd-t/.unattended/stop
+```
+
+**Watch loop stopped firing**
+- Re-invoke `/user:gsd-t-resume` from a fresh session
+- Step 0 auto-reattach reads `supervisor.pid` — if the supervisor is still alive, it re-enters the watch loop automatically (no manual steps needed)
+
+**Supervisor crashed mid-run**
+- The watch loop detects crash via `kill -0` failure
+- Check `.gsd-t/.unattended/run.log` and final `state.json` for diagnostics
+- Resume normally with `/user:gsd-t-resume` — the milestone continues from its last checkpoint
+
+---
+
 ## Security Notes
 
 - Zero npm dependencies — no supply chain risk