@tekyzinc/gsd-t 2.76.10 → 3.10.11

package/docs/methodology.md

@@ -119,3 +119,11 @@ Between v2.74 and v2.75, GSD-T attempted to cope with context pressure through *
 **Structural guarantee.** Because `STOP_THRESHOLD_PCT = 85` and the runway estimator refuses runs that would project past 85%, the runtime's 95% native compact is now structurally unreachable under healthy operation. `halt_type: native-compact` in `.gsd-t/token-metrics.jsonl` is a defect signal — if it appears, the estimator needs re-tuning.
 
 **Message content is never logged**: the meter writes only token counts, band names, and error category codes. Never transcript text, never API response bodies, never the API key itself. See `docs/architecture.md` for the full data-flow diagram and `.gsd-t/contracts/context-meter-contract.md` for the schema.
+
+## From Runway-Protected Execution to Cross-Session Relay (M36)
+
+M34 gave GSD-T a real measurement of how much context window each session had consumed. M35 used that signal to refuse starting new work that would exceed the 85% threshold, auto-spawning a detached headless process instead so the user never had to manually run `/clear`. Both milestones still had a ceiling: the headless continuation was a single shot — it ran one Claude session, and if the milestone wasn't complete when that session exhausted its context, a human had to intervene again to trigger the next continuation. Long-running milestones (multi-day builds, large waves) still required periodic human attention to keep the relay going.
+
+M36 (v2.77.10) makes the relay automatic and indefinite. The unattended supervisor (`bin/gsd-t-unattended.js`) is a long-lived OS process, fully detached from any Claude Code terminal session, that drives the relay itself: it spawns a fresh `claude -p "/gsd-t-resume"` worker, waits for it to exit, reads the outcome, and immediately spawns the next worker — repeating until the milestone reaches COMPLETED status or a wall-clock cap is hit. Each worker gets a pristine context window. The `/compact` that inevitably fires in a long session is irrelevant because the *next* session has already started fresh. The supervisor IS the orchestrator of runway handoffs. Safety rails (`bin/gsd-t-unattended-safety.js`) prevent infinite-loop scenarios: gutter detection catches stall patterns, blocker sentinels catch unrecoverable errors, and iteration/hour caps ensure the machine doesn't run forever on a broken state. A cross-platform abstraction layer handles macOS sleep-prevention (`caffeinate`), Linux equivalents, and Windows limitations. From the user's perspective: invoke `/user:gsd-t-unattended`, walk away, and receive a native OS notification when the milestone is done — hours or days later.
+
+The in-session watch loop (270-second `ScheduleWakeup` ticks, chosen to stay inside the 5-minute prompt-cache TTL) closes the feedback loop for users who keep a Claude session open. And the `gsd-t-resume` Step 0 auto-reattach means that even a `/clear` or accidental session close is transparent: the next resume detects the live supervisor and silently re-enters the watch loop without any manual step. Taken together, M34 + M35 + M36 form a complete three-layer system: measure the context accurately, refuse to degrade when it runs low, and relay execution automatically across as many fresh sessions as the work requires.

package/docs/requirements.md

@@ -254,6 +254,15 @@
 | REQ-076 | Optimization backlog — detect only, never auto-apply, user promotes or rejects | optimization-backlog | T1–T4 | complete (Wave 4) |
 | REQ-077 | Headless auto-spawn on runway refusal — user never sees a `/clear` prompt | headless-auto-spawn | T1–T5 | complete (Waves 3–4) |
 | REQ-078 | Structural elimination of native compact messages — `halt_type: native-compact` count is 0 during M35 execution | runway-estimator + headless-auto-spawn | T1–T5 (RE), T1–T5 (HAS) | complete (Wave 5) |
+| REQ-079 | `gsd-t unattended` CLI subcommand runs an active milestone to completion unattended on macOS and Linux (24h+ multi-worker relay, detached OS process) | m36-supervisor-core | T1–T5 | complete (M36 Wave 1–2) |
+| REQ-080 | `/user:gsd-t-unattended` slash command launches the supervisor from within a Claude session without blocking the terminal | m36-supervisor-core + m36-watch-loop | T1, T3 | complete (M36 Wave 1–3) |
+| REQ-081 | In-session watch loop ticks every 270s via `ScheduleWakeup` (inside 5-min prompt-cache TTL) to report live supervisor state | m36-watch-loop | T1–T2 | complete (M36 Wave 3) |
+| REQ-082 | `/clear` + `/user:gsd-t-resume` during a live unattended run transparently re-attaches to the watch loop (Step 0 auto-reattach, no user-visible disruption) | m36-watch-loop | T4 | complete (M36 Wave 3) |
+| REQ-083 | Supervisor survives `/compact` and context resets — each worker is a fresh `claude -p` session; context exhaustion is structurally irrelevant | m36-supervisor-core | T1–T5 | complete (M36 Wave 1–2) |
+| REQ-084 | Safety rails prevent infinite loops: gutter detection, blocker sentinels (`BLOCKED_NEEDS_HUMAN`, `DISPATCH_FAILED`), max-hours and max-iterations timeouts | m36-safety-rails | T1–T5 | complete (M36 Wave 2) |
+| REQ-085 | Cross-platform support — macOS (caffeinate sleep-prevention) + Linux (systemd-inhibit or no-op) + Windows (claude.cmd via PATH; sleep-prevention not supported — see docs/unattended-windows-caveats.md) | m36-cross-platform | T1–T5 | complete (M36 Wave 2) |
+| REQ-086 | Handoff-lock primitive (`bin/handoff-lock.js`) eliminates parent/child race in `headless-auto-spawn.js` runway handoffs (M35 gap fix) | m36-m35-gap-fixes | T1–T3 | complete (M36 Wave 2) |
+| REQ-087 | 5 command files no longer emit "Run /clear" STOP — runway-exceeded handoff auto-invokes `autoSpawnHeadless()` seamlessly (M35 gap fix) | m36-m35-gap-fixes | T3 | complete (M36 Wave 3) |
 
 **M35 Functional Requirements:**
 - **REQ-069**: `bin/token-budget.js` `getDegradationActions()` must return `{band: 'normal'|'warn'|'stop', pct: number, message: string}` only. No `modelOverride`, no `skipPhases`, no `checkpoint` side-channel.
@@ -276,6 +285,26 @@
 **Orphaned requirements**: None — all M35 REQs mapped to tasks.
 **Unanchored tasks**: None — all 38 M35 tasks trace to REQ-069–REQ-078 or REQ-063–068 (existing requirements that M35 code continues to satisfy).
 
+**M36 Functional Requirements:**
+- **REQ-079**: `bin/gsd-t-unattended.js` implements the supervisor relay loop: spawn worker → await exit → post-worker safety check → next iter. State written atomically to `.gsd-t/.unattended/state.json`. Contract: `unattended-supervisor-contract.md` v1.0.0.
+- **REQ-080**: `commands/gsd-t-unattended.md` pre-flights branch + dirty tree, spawns supervisor detached, polls for PID readiness, displays initial watch block, and calls `ScheduleWakeup(270, '/user:gsd-t-unattended-watch')`.
+- **REQ-081**: `commands/gsd-t-unattended-watch.md` implements the watch tick decision tree (§8 of contract): reads PID → liveness probe → reads state.json → reschedule or terminal report.
+- **REQ-082**: `commands/gsd-t-resume.md` Step 0 checks `supervisor.pid` before any other resume logic. If live + non-terminal: skip normal resume, print watch block, call `ScheduleWakeup(270, '/user:gsd-t-unattended-watch')`.
+- **REQ-083**: Supervisor relay architecture ensures each worker gets a fresh context window. No compaction state carries over between workers — only `.gsd-t/` milestone state files.
+- **REQ-084**: `bin/gsd-t-unattended-safety.js` exports: `checkGitBranch`, `checkWorktreeCleanliness`, `validateState`, `checkIterationCap`, `checkWallClockCap`, `detectBlockerSentinel`, `detectGutter`. Called at all 4 supervisor hook points.
+- **REQ-085**: `bin/gsd-t-unattended-platform.js` exports: `spawnSupervisor`, `preventSleep`, `releaseSleep`, `notify`, `resolveClaudePath`. Windows: `preventSleep` is a documented no-op. Windows caveats documented in `docs/unattended-windows-caveats.md`.
+- **REQ-086**: `bin/handoff-lock.js` exports: `acquireLock(dir)`, `releaseLock(dir)`, `isLocked(dir)`. Used in `bin/headless-auto-spawn.js` `autoSpawnHeadless()` to guard the parent-exits-before-child-starts window.
+- **REQ-087**: `commands/gsd-t-execute.md`, `gsd-t-wave.md`, `gsd-t-integrate.md`, `gsd-t-quick.md`, `gsd-t-debug.md` — runway-exceeded path calls `autoSpawnHeadless()` and exits cleanly. No "Run /clear" instruction emitted.
+
+**M36 Non-Functional Requirements:**
+- Zero external npm dependencies (all M36 bin/ modules use Node.js built-ins only)
+- Supervisor launch → PID-ready in < 5 seconds (poll timeout in launch command)
+- Worker spawn overhead: < 500ms before `claude -p` subprocess starts
+- Test count: 1146 → 1226 (+80 net new tests across 6 M36 domain test files)
+
+**Orphaned requirements**: None — all M36 REQs mapped to tasks.
+**Unanchored tasks**: None — all M36 tasks trace to REQ-079–REQ-087.
+
 ---
 
 ## M17: Scan Visual Output — Feature Specification

package/docs/unattended-config.md

@@ -0,0 +1,138 @@
+# Unattended Supervisor — Configuration File
+
+**File**: `.gsd-t/.unattended/config.json` (optional, per-project)
+**Contract reference**: `.gsd-t/contracts/unattended-supervisor-contract.md` §13
+**Loader**: `bin/gsd-t-unattended-safety.js` → `loadConfig(projectDir)`
+**Consumer**: `bin/gsd-t-unattended.js` (supervisor entrypoint)
+
+The unattended supervisor reads an optional JSON config file at
+`.gsd-t/.unattended/config.json`. If present, its fields override the
+hardcoded defaults. If absent, the supervisor runs with the defaults below.
+Malformed JSON fails the launch with exit code 2 (preflight-failure) — the
+supervisor never silently falls back on a broken config.
+
+## Precedence
+
+From highest to lowest:
+
+1. **CLI flags** passed to `/user:gsd-t-unattended` (e.g. `--hours=48`)
+2. **Environment variables** (`GSD_T_HOURS`, `GSD_T_MAX_ITERATIONS`, etc.)
+3. **`.gsd-t/.unattended/config.json`** fields
+4. **Hardcoded defaults** in `bin/gsd-t-unattended-safety.js` → `DEFAULTS`
+
+A CLI flag always wins. An env var beats the config file. The config file
+beats the built-in defaults. Missing fields fall through to the next level
+individually — a config with only `protectedBranches` still uses the default
+`hours`, `maxIterations`, etc.
+
+## Schema
+
+```json
+{
+  "hours": 24,
+  "maxIterations": 200,
+  "protectedBranches": ["main", "master", "develop", "trunk", "release/*", "hotfix/*"],
+  "dirtyTreeWhitelist": [
+    ".gsd-t/heartbeat-*.jsonl",
+    ".gsd-t/.context-meter-state.json",
+    ".gsd-t/events/*.jsonl",
+    ".gsd-t/token-metrics.jsonl",
+    ".gsd-t/token-log.md",
+    ".gsd-t/.unattended/*",
+    ".gsd-t/.handoff/*",
+    ".claude/settings.local.json",
+    ".claude/settings.local.json.bak*"
+  ],
+  "gutterNoProgressIters": 5,
+  "workerTimeoutMs": 3600000
+}
+```
+
+### Field reference
+
+| Field | Type | Default | Purpose |
+|---|---|---|---|
+| `hours` | number | `24` | Wall-clock cap in hours. Supervisor exits with code 6 (gutter) once `wallClockElapsedMs >= hours * 3600 * 1000`. |
+| `maxIterations` | integer | `200` | Iteration cap. Supervisor exits with code 6 once `iter >= maxIterations`. |
+| `protectedBranches` | string[] | `["main","master","develop","trunk","release/*","hotfix/*"]` | Branches where the pre-launch guard refuses to spawn. Glob patterns supported (`*`, `**`, `?`). Empty array = no branch protection. |
+| `dirtyTreeWhitelist` | string[] | (see defaults) | Files that can be dirty without triggering the clean-worktree refusal. Glob patterns supported. Non-whitelisted dirty files cause exit code 8. |
+| `gutterNoProgressIters` | integer | `5` | Lookback window for the no-progress gutter detector. Larger = less sensitive. |
+| `workerTimeoutMs` | integer | `3600000` (1h) | Hard wall-clock timeout for a single `claude -p` worker iteration. Exceeding this causes worker SIGTERM + exit code 3. |
+
+## Common Overrides
+
+### Solo project — commit directly to main
+
+For projects where you're the only contributor and main is your working
+branch, disable the protected-branch guard:
+
+```json
+{
+  "protectedBranches": []
+}
+```
+
+The safety rail still runs, but with an empty list nothing matches, so the
+guard always allows. The Destructive Action Guard, blocker sentinels, caps,
+and Red Team are all still active — you're only opting out of one specific
+check.
+
+### Long overnight runs
+
+Raise the caps for multi-day unattended milestones:
+
+```json
+{
+  "hours": 72,
+  "maxIterations": 600
+}
+```
+
+### Extra-noisy project
+
+If your project writes logs or caches outside the default whitelist and you
+don't want to commit or stash them before each run:
+
+```json
+{
+  "dirtyTreeWhitelist": [
+    ".gsd-t/heartbeat-*.jsonl",
+    ".gsd-t/.context-meter-state.json",
+    ".gsd-t/events/*.jsonl",
+    ".gsd-t/token-metrics.jsonl",
+    ".gsd-t/token-log.md",
+    ".gsd-t/.unattended/*",
+    ".gsd-t/.handoff/*",
+    ".claude/settings.local.json",
+    "logs/**",
+    "tmp/**",
+    "*.local.cache"
+  ]
+}
+```
+
+Whitelist is a replacement, not an append. If you override it, restate the
+defaults you want to keep.
+
+## Validation
+
+The loader in `bin/gsd-t-unattended-safety.js` merges field-by-field. Only
+the fields you set are overridden — everything else keeps its default. If
+the file exists but isn't valid JSON, the launcher aborts with:
+
+```
+[gsd-t-unattended] preflight-failure: safety-rails: malformed JSON in
+.gsd-t/.unattended/config.json: <parse error>
+```
+
+and exits with code 2. The PID file, state file, and run log are never
+written on a preflight failure.
+
+## Git
+
+`.gsd-t/.unattended/` is in the dirty-tree whitelist, so you can either:
+- **Commit the config** — makes it part of the project's canonical setup
+- **Gitignore the config** — treat it as a per-developer preference
+
+Both work. There's no preferred choice — it depends on whether your team
+wants a uniform cap across machines or lets each developer tune their own.

package/docs/unattended-windows-caveats.md

@@ -0,0 +1,245 @@
+# Unattended Supervisor — Windows Caveats (v1.0.0)
+
+**Status**: Windows support is **shipping but caveated** in v1.0.0.
+
+**Contract reference**: `.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0
+**Platform module**: `bin/gsd-t-unattended-platform.js`
+
+---
+
+## 0. Required Software (All Platforms)
+
+The launch command (`/user:gsd-t-unattended`) pre-flights required software in
+Step 1e and refuses to spawn if anything is missing. Install these before
+launching:
+
+**Required everywhere (hard-fail):**
+
+| Tool    | Install                                                       |
+|---------|---------------------------------------------------------------|
+| node    | https://nodejs.org (>= 16)                                    |
+| claude  | `npm install -g @anthropic-ai/claude-code`                    |
+| git     | https://git-scm.com/downloads                                 |
+
+**macOS — soft warnings (install for best reliability):**
+
+| Tool        | Purpose                  | Install             |
+|-------------|--------------------------|---------------------|
+| caffeinate  | sleep prevention          | built-in (Apple)    |
+
+**Linux — soft warnings:**
+
+| Tool                      | Purpose                     | Install                                    |
+|---------------------------|-----------------------------|--------------------------------------------|
+| systemd-inhibit OR caffeine | sleep/screen-lock prevention | usually preinstalled; else `sudo apt install caffeine` |
+| notify-send               | desktop notifications        | `sudo apt install libnotify-bin`           |
+
+**Windows — soft warnings:**
+
+| Tool               | Purpose                      | Install                                |
+|--------------------|------------------------------|----------------------------------------|
+| PowerShell         | sleep prevention (built-in)  | ships with Windows                     |
+| BurntToast         | real toast notifications     | `Install-Module BurntToast` (PowerShell) |
+
+If the pre-flight fails, the launcher prints each missing tool with its
+install instructions and refuses to spawn. Soft warnings are advisory only —
+the supervisor still launches without them, but with degraded resilience.
+
+---
+
+## 1. Overview
+
+The GSD-T unattended supervisor (M36) ships cross-platform. All core supervisor
+mechanics — the watch loop, state-file lifecycle, worker spawning, stop
+sentinel, and safety rails — run unchanged on Windows. The darwin and linux
+code paths are runtime-tested; the win32 code paths are
+**implementation-complete but not runtime-tested on the dev host (macOS)**.
+
+Three OS-integration surfaces have known limitations on Windows:
+
+1. **Sleep prevention** — no stock `caffeinate` equivalent ships with Windows.
+2. **Notifications** — `msg.exe` is a minimal fire-and-forget shim with real
+   delivery restrictions.
+3. **Process detach** — `spawn(..., { detached: true })` behaves differently
+   from POSIX and is not a true daemonization primitive.
+
+This document covers what works, what doesn't, the Spike C disposition, and
+the recommended usage pattern. Everything below applies to `win32` only;
+darwin and linux are unaffected.
+
+---
+
+## 2. Known Gaps
+
+### 2.1 Sleep prevention (no-op on win32)
+
+`preventSleep(reason)` in `bin/gsd-t-unattended-platform.js` explicitly
+**returns `null` on win32** and writes a one-line notice to stderr:
+
+```
+[platform] sleep prevention not implemented on win32 (see docs/unattended-windows-caveats.md)
+```
+
+Windows has no stock command-line equivalent of macOS `caffeinate`. The
+native API (`SetThreadExecutionState`) requires a C binding, which violates
+the GSD-T zero-external-dependency constraint for `bin/`. `releaseSleep(null)`
+is a safe no-op, so the supervisor still shuts down cleanly.
+
+**Consequence**: if a Windows machine is configured to sleep on its default
+power schedule, a long unattended run will pause (or outright fail) when the
+machine sleeps. The supervisor has no way to prevent this.
+
+**Workaround (v1)**: the user must configure Windows power settings manually
+to keep the machine awake for the duration of the run. Microsoft's official
+guidance covers both GUI and command-line approaches:
+
+- [powercfg command-line options](https://learn.microsoft.com/en-us/windows-hardware/design/device-experiences/powercfg-command-line-options)
+- [Change power plan settings](https://support.microsoft.com/en-us/windows/change-power-mode-for-your-windows-pc-c2aff038-22f9-f46a-8ca1-ba5be2b6a7b9)
+
+Useful examples:
+
+```powershell
+# Disable sleep while on AC power (requires admin)
+powercfg /change standby-timeout-ac 0
+
+# Disable sleep while on battery (requires admin)
+powercfg /change standby-timeout-dc 0
+```
+
+### 2.2 Notifications (`msg.exe`, interactive-session only)
+
+`notify(title, message, level)` in `bin/gsd-t-unattended-platform.js` uses
+`msg.exe * "title: message"` on win32 with `windowsHide: true`. This is a
+deliberate minimal fire-and-forget dependency: `msg.exe` ships with Windows
+and has zero install cost.
+
+**Restrictions**:
+
+- `msg.exe` only delivers to **interactive Windows sessions**. If the
+  supervisor is launched under a Windows Service, a non-interactive ssh
+  session, or any other session without a desktop attached, `msg.exe` will
+  silently drop the notification (or fail with an access error). The
+  supervisor core is unaffected — the `child.on('error', ...)` handler logs
+  the failure to stderr and the relay loop continues.
+- `msg.exe` is not a true toast / Action Center notification. It pops a
+  blocking message-box dialog into the active session. This is visible and
+  audible but is not the modern Windows notification experience.
+
+**Recommended v2 enhancement**: integrate a real toast API such as
+[`BurntToast`](https://github.com/Windos/BurntToast) (a PowerShell module).
+`BurntToast` requires an opt-in install, so it will remain behind a capability
+check; stock installs will fall back to `msg.exe`.
+
+### 2.3 Process detach (`detached: true` is not full daemonization)
+
+`spawnSupervisor({ binPath, args, cwd })` uses
+`spawn('node', [...], { detached: true, stdio: 'ignore', windowsHide: true })`
+followed by `child.unref()`. On **POSIX** (darwin / linux) this makes the
+child a new process-group leader and the supervisor survives the parent
+terminal closing. On **win32** the same options produce a separate process
+tree but do **not** fully detach the child from the launching console:
+
+- Closing the launching terminal window may still deliver a console
+  `CTRL_CLOSE_EVENT` to the child and terminate the supervisor.
+- Signing out of the user session will terminate the child along with every
+  other user process.
+- There is no equivalent of POSIX `setsid()` purely from Node's `spawn`
+  options.
+
+**Workarounds**:
+
+- Use `start /B` via a shell wrapper to launch the supervisor in a fully
+  background-detached process on the current session.
+- For truly-outlive-the-session runs, register the supervisor as a **Windows
+  Task Scheduler** task. Task Scheduler manages its own process lifetime
+  independent of the interactive session.
+- Run inside **WSL2** (see §5) to get POSIX detach semantics end-to-end.
+
+---
+
+## 3. Spike C Disposition — Sleep Prevention Alternatives
+
+Spike C was an exploratory investigation of Windows-native alternatives to
+`caffeinate`. The question: can we keep the zero-dependency constraint and
+still prevent sleep?
+
+Three candidates were evaluated:
+
+| Option | Mechanism | Verdict |
+|--------|-----------|---------|
+| `SetThreadExecutionState` Win32 API via `ffi` | Native API, exactly what caffeinate maps to. | **Reject.** Requires `ffi-napi` or equivalent — a C binding and a compiled native dep. Violates the zero-external-dependency constraint for `bin/`. |
+| `powercfg` toggle | CLI that ships with Windows. `powercfg /change standby-timeout-ac 0` before run, restore after. | **Reject.** Requires administrator privileges. Persists across runs if the supervisor crashes mid-run, leaving the machine in a modified power state. Hard to guarantee restoration. |
+| Task Scheduler "wake to run" / wake events | Scheduled task can force the machine to wake at interval. | **Defer.** Best user-space path but adds non-trivial scheduler management code (create task, tear down on exit, handle orphaned tasks). |
+
+**Verdict**: **defer to v2.** v1.0.0 ships with the `null`-handle + documentation
+approach described in §2.1. v2 will consider Task Scheduler integration as the
+primary path, since it is the only candidate that is both user-space and
+compatible with the zero-dependency constraint.
+
+---
+
+## 4. What Works Today on Windows
+
+All of the following run on Windows with no caveats (pending runtime testing
+on a real Windows host; implementation is complete):
+
+- **Core supervisor process** — runs to completion, observes the state file,
+  dispatches workers, honours the watch-loop cadence, and exits cleanly.
+- **State file lifecycle** — atomic write, lockfile, heartbeat updates, and
+  teardown all use Node built-ins and behave identically on win32.
+- **Worker spawning** — `spawnWorker(projectDir, timeoutMs)` uses `claude.cmd`
+  via `resolveClaudePath()` with `shell: false` and `windowsHide: true`, which
+  avoids the Spike C PowerShell quoting hazard.
+- **Stop sentinel** — sentinel-file detection is filesystem-based and is
+  cross-platform by construction.
+- **Safety rails** — `isAlive(pid)` uses Node's `process.kill(pid, 0)`, which
+  implements POSIX signal-0 semantics on Windows. Liveness checks, watchdog
+  timers, and stuck-worker detection all work unchanged.
+
+Exit code table (contract §5), heartbeat contract, and the launch-handshake
+file contract are all platform-agnostic and fully honoured on win32.
+
+---
+
+## 5. Recommended Usage Pattern on Windows
+
+Given the gaps above, the recommended way to run the unattended supervisor on
+Windows for v1.0.0 is:
+
+1. **Run on a desktop that never sleeps.** Configure Windows power settings so
+   the machine will not sleep, hibernate, or turn off the display for the
+   expected duration of the run. Use `powercfg` or the Settings UI (see §2.1).
+2. **Launch from an interactive PowerShell session** (not a Windows Service,
+   not a non-interactive ssh session). This ensures `msg.exe` notifications
+   can be delivered and that the supervisor's stderr diagnostics are visible.
+3. **Monitor via the watch-tick command from the same interactive session.**
+   Do not close the launching terminal until the supervisor exits — see §2.3
+   for why.
+4. **Consider running inside WSL2** instead of native Windows. WSL2 provides a
+   full Linux userland where `bin/gsd-t-unattended-platform.js` takes the
+   `linux` branch everywhere: `isAlive`, `spawnWorker`, `spawnSupervisor`, and
+   `notify` all behave with POSIX semantics end-to-end. The only remaining gap
+   in WSL2 is sleep prevention (linux also returns `null` from `preventSleep`
+   in v1.0.0), which is still governed by the host Windows machine's power
+   settings. WSL2 is currently the closest thing to the full darwin / linux
+   feature set on a Windows box.
+
+---
+
+## 6. Summary Matrix
+
+| Feature                  | darwin    | linux     | win32                                          |
+|--------------------------|-----------|-----------|------------------------------------------------|
+| `resolveClaudePath`      | `claude`  | `claude`  | `claude.cmd`                                   |
+| `isAlive(pid)`           | works     | works     | works (POSIX signal-0 semantics)               |
+| `spawnWorker`            | works     | works     | implementation-complete, untested on real host |
+| `spawnSupervisor` detach | full      | full      | partial — console-close may kill child         |
+| `preventSleep`           | works     | null (v1) | null (v1) — see §2.1 and §3                    |
+| `releaseSleep`           | works     | no-op     | no-op                                          |
+| `notify`                 | works     | works     | works only in interactive sessions (§2.2)      |
+
+**v2 roadmap (non-binding)**:
+- Linux: opt-in `systemd-inhibit` for sleep prevention.
+- Windows: Task Scheduler integration for sleep prevention; `BurntToast`
+  capability check for real toast notifications; optional Task-Scheduler-based
+  daemonization path for true detachment.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "2.76.10",
-  "description": "GSD-T: Contract-Driven Development for Claude Code — 56 slash commands with headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
+  "version": "3.10.11",
+  "description": "GSD-T: Contract-Driven Development for Claude Code — 61 slash commands with unattended supervisor relay, headless CI/CD mode, graph-powered code analysis, real-time agent dashboard, execution intelligence, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",
   "repository": {

package/scripts/gsd-t-context-meter.e2e.test.js

@@ -44,7 +44,7 @@ const os = require("node:os");
 
 const HOOK_SCRIPT = path.resolve(__dirname, "gsd-t-context-meter.js");
 const INJECTOR = path.resolve(__dirname, "context-meter", "test-injector.js");
-const HARD_TIMEOUT_MS = 6000;
+const HARD_TIMEOUT_MS = 12000;
 
 /* ──────────────────────────── test fixtures ──────────────────────────── */
 

package/templates/CLAUDE-global.md

@@ -68,6 +68,9 @@ PROJECT or FEATURE or SCAN
 | `/user:gsd-t-resume` | Restore context, continue |
 | `/user:gsd-t-version-update` | Update GSD-T to latest version |
 | `/user:gsd-t-version-update-all` | Update GSD-T + all registered projects |
+| `/user:gsd-t-unattended` | Launch detached supervisor — runs active milestone to completion with zero human intervention |
+| `/user:gsd-t-unattended-watch` | Watch tick — fires every 270s via ScheduleWakeup, reports supervisor status |
+| `/user:gsd-t-unattended-stop` | Touch stop sentinel — supervisor halts after current worker finishes |
 | `/user:gsd-t-triage-and-merge` | Auto-review, merge, and publish GitHub branches |
 | `/user:gsd-t-audit` | Harness self-audit — analyze cost/benefit of enforcement components |
 | `/user:gsd-t-design-audit` | Compare built screen against Figma design — structured deviation report |
@@ -398,6 +401,15 @@ KEEP GOING. Only stop for:
 3. Milestone completion (checkpoint for user review)
 4. Destructive actions (see Destructive Action Guard above — ALWAYS stop)
 
+## Unattended Execution (M36, v3.10.10+)
+
+`/user:gsd-t-unattended` launches a detached OS-process supervisor that drives the active milestone to completion over hours or days via a `claude -p` worker relay — each worker in a fresh context window. The interactive Claude session receives a 270-second ScheduleWakeup watch loop (`/user:gsd-t-unattended-watch`) that ticks and prints progress until the supervisor reaches a terminal state.
+
+- **Resume re-attach**: `/user:gsd-t-resume` checks for a live `supervisor.pid`; if the supervisor is still running, it skips normal resume and re-starts the watch loop automatically.
+- **Stop**: `/user:gsd-t-unattended-stop` touches `.gsd-t/.unattended/stop`; supervisor halts after the current worker finishes.
+- **Contract**: `.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0 — authoritative for state schema, exit codes, CLI flags, and platform matrix.
+- **Platform**: macOS and Linux fully supported. Windows supported except sleep-prevention (see `docs/unattended-windows-caveats.md`).
+
 ## Pre-Commit Gate (MANDATORY)
 
 NEVER commit code without running this checklist. This is not optional.