@tekyzinc/gsd-t 2.76.10 → 3.10.11

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to GSD-T are documented here. Updated with each release.
 
+## [3.10.11] - 2026-04-15
+
+### Added
+- `docs/unattended-config.md` — full schema and recipe reference for `.gsd-t/.unattended/config.json`. The supervisor has always loaded this file (M36 safety rails), but there was no user-facing doc explaining the schema, precedence, or common overrides.
+- `commands/gsd-t-unattended.md` Step 1c cross-references the new config doc and calls out the solo-project recipe (`{"protectedBranches": []}` to disable the main/master guard).
+
+### Fixed
+- Flaky test: `scripts/gsd-t-context-meter.e2e.test.js` `HARD_TIMEOUT_MS` bumped 6000 → 12000ms. The hook child process runs fine in 30ms in isolation but was timing out under full-suite parallelism load on some machines. No behavioral change — just a more forgiving outer cap.
+- `commands/gsd-t-unattended.md` gained Step 1e: pre-flight software check that hard-fails the launch if `node`, `claude`, or `git` are missing, and prints soft warnings for missing platform helpers (`caffeinate` on darwin; `systemd-inhibit`/`notify-send` on linux; BurntToast advisory on win32). Replaces the previous "crash mid-run when a helper is missing" behavior with fail-fast + actionable install instructions.
+- `docs/unattended-windows-caveats.md` added §0 "Required Software" matrix listing hard-required and soft-recommended tools per platform.
+
+### Notes
+- No API or contract changes. `.gsd-t/.unattended/config.json` loader and precedence (CLI > env > config > defaults) were already built into M36 safety rails — this release only surfaces them in documentation.
+
+## [3.10.10] - 2026-04-15
+
+### Major version bump: 2.x → 3.x
+
+M36 ships the third pillar of the context/runway/autonomy arc (M34 context meter → M35 no-silent-degradation → M36 unattended supervisor). Cumulatively these three milestones are substantial enough to mark a new major version. No breaking API changes — existing commands and contracts continue to work — but v3.x establishes "unattended-capable" as the default expectation for the harness. Semver major bump also aligns with the "always 2-digit minor and patch" display convention (Minor and Patch start at 10 after a major reset).
+
+### M36: Unattended Supervisor — Zero-Human-Intervention Milestone Execution
+
+**Background**: M35 introduced headless auto-spawn to continue a single runway-exhausted session in a fresh context. M36 generalizes this into a first-class long-running supervisor: a detached OS-level process that drives the active GSD-T milestone to completion over hours or days via a `claude -p` worker relay. Each worker runs in its own fresh context window; the supervisor survives terminal close, `/clear`, and sleep/wake cycles. A 270-second ScheduleWakeup watch loop in the interactive session provides live status without blocking the user.
+
+### Added
+
+- **`bin/gsd-t-unattended.js`** — detached supervisor process. Spawns `claude -p` workers in a relay, writes atomic `state.json` between iterations, manages `supervisor.pid` lifecycle, invokes safety rails at hook points, sends OS notifications on terminal transitions (macOS `osascript`; silent no-op on other platforms), and removes its own PID file on any exit. Singleton: a second launch with a live PID refuses.
+- **`bin/gsd-t-unattended-safety.js`** — safety rails module. Exports: `checkGitBranch` (protected branch list; configurable), `checkWorktreeCleanliness` (dirty-tree guard with whitelist), `checkIterationCap`, `checkWallClockCap`, `validateState`, `detectBlockerSentinel` (scan run.log tail for unrecoverable/dispatch-failed patterns), `detectGutter` (repeated-error / file-thrash / no-progress stall detection). Each check returns `{ ok, reason?, code? }`.
+- **`bin/gsd-t-unattended-platform.js`** — platform abstraction. Exports: `spawnSupervisor` (detached spawn with `windowsHide`), `preventSleep` / `releaseSleep` (`caffeinate -i` on darwin; no-op on linux/win32), `sendNotification` (osascript on darwin; `notify-send` on linux; toast via PowerShell on win32 — all graceful no-op on failure), `resolveClaudeBin` (`claude.cmd` on win32; `claude` elsewhere + PATH search), `getPlatform`.
+- **`bin/handoff-lock.js`** — parent/child race guard for headless-auto-spawn. Writes `.gsd-t/.handoff/{session-id}.lock` before detaching; child removes on first iteration. Prevents the parent from reporting "failed" while the child is still starting. Exports: `acquireLock`, `releaseLock`, `waitForRelease`, `isLocked`.
+- **`commands/gsd-t-unattended.md`** — `/user:gsd-t-unattended` launch command. Pre-flights (singleton check, safety rails, active milestone), spawns the supervisor via `bin/gsd-t-unattended-platform.js`, polls for `supervisor.pid` + `status=running` (up to 5s), prints the initial watch block, calls `ScheduleWakeup(270, '/user:gsd-t-unattended-watch')`.
+- **`commands/gsd-t-unattended-watch.md`** — `/user:gsd-t-unattended-watch` watch tick. Stateless; reads `supervisor.pid` + `state.json`; renders progress or final summary; reschedules via `ScheduleWakeup(270, ...)` on non-terminal status; stops on terminal status or missing PID file.
+- **`commands/gsd-t-unattended-stop.md`** — `/user:gsd-t-unattended-stop` stop command. Touches `.gsd-t/.unattended/stop` sentinel; prints reassurance; returns immediately (no kill, no wait).
+- **`.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0 ACTIVE** — authoritative interface for state file schema (18 fields), PID file lifecycle, sentinel semantics, exit codes 0–8+124, launch handshake, watch tick decision tree, resume auto-reattach handshake, stop mechanism, notification levels, safety rails hook points, and configuration file schema.
+- **`docs/unattended-windows-caveats.md`** — known Windows limitations: sleep-prevention not supported (no `caffeinate` equivalent wired; `powercfg /requests` path is v2), `claude.cmd` wrapper adds ~500ms per spawn, Windows Defender may scan each worker spawn, notification via PowerShell toast requires non-interactive shell workaround.
+- **`.claude/settings.json`** (project-shared) — SessionStart hook registered: `node bin/check-headless-sessions.js . 2>/dev/null || true` surfaces completed headless session banners on session start.
+
+### Changed
+
+- **`commands/gsd-t-wave.md`** — "Run /clear" STOP block removed from the runway-exceeded handoff path. The command now calls `autoSpawnHeadless()` seamlessly; user never sees a manual-intervention prompt under normal runway overflow.
+- **`commands/gsd-t-execute.md`**, **`gsd-t-quick.md`**, **`gsd-t-integrate.md`**, **`gsd-t-debug.md`** — same "Run /clear" prompt removal; headless auto-spawn wired in.
+- **`commands/gsd-t-resume.md`** — new Step 0 "Unattended Supervisor Auto-Reattach": checks `supervisor.pid`; if live and non-terminal, skips normal resume and re-starts the watch loop. New Step 0.2 "Handoff Lock Wait": polls until `.gsd-t/.handoff/*.lock` is released (headless child has taken ownership) before proceeding.
+
+### Fixed
+
+- **`bin/gsd-t.js` headless dispatch** (Phase 0 P0, committed prior milestone): `mapHeadlessExitCode` now maps `"Unknown command:"` in worker stdout → exit code 5 (`command-dispatch-failed`). Worker invocation no longer prepends `/user:` to command names, preventing "Unknown command:" failures in non-interactive `claude -p` sessions.
+
+### Tests
+
+- `test/unattended-supervisor.test.js` — 42 tests: happy-path relay, gutter halt, stop sentinel, dispatch-failure halt, crash detection, dirty-tree pre-flight refusal.
+- `test/unattended-safety.test.js` — 18 tests: each check function, combined pre-flight, gutter threshold config.
+- `test/unattended-platform.test.js` — 14 tests: platform detection, spawn flags, sleep-prevention no-op on linux, claude binary resolution.
+- `test/handoff-lock.test.js` — 16 tests: acquire/release, race prevention, waitForRelease timeout, stale lock cleanup.
+- `test/headless-auto-spawn.test.js` — +9 tests (new handoff-lock integration cases added to existing suite).
+- `test/filesystem.test.js` — counts updated to reflect new files (+6 bin files, +3 command files, +1 docs file).
+- **Total**: 1146 → 1226 (+80 new tests).
+
+### Migration
+
+After `npm install @tekyzinc/gsd-t@3.10.10`, run `/user:gsd-t-version-update-all` to propagate v3.10.10 to all registered projects. The new command files, `bin/` modules, and contract are written into each project automatically. No existing `.gsd-t/` state is modified.
+
+---
+
 ## [2.76.10] - 2026-04-15
 
 ### M35: Runway-Protected Execution — Aggressive Pause-Resume Replaces Graduated Degradation

package/README.md

@@ -10,6 +10,7 @@ A methodology for reliable, parallelizable development using Claude Code with op
 **Protects existing work** — destructive action guard prevents schema drops, architecture replacements, and data loss without explicit approval.
 **Visualizes execution in real time** — live browser dashboard renders agent hierarchy, tool activity, and phase progression from the event stream.
 **Generates visual scan reports** — every `/gsd-t-scan` produces a self-contained HTML report with 6 live architectural diagrams, a tech debt register, and domain health scores; optional DOCX/PDF export via `--export docx|pdf`.
+**Unattended execution** — `gsd-t unattended --hours=N` spawns a detached OS-process supervisor that drives the active milestone to completion over hours or days with zero human intervention. A ScheduleWakeup watch loop ticks every 270 seconds; `/clear` + resume transparently re-attaches to the running supervisor.
 **Self-learning rule engine** — declarative rules in rules.jsonl detect failure patterns from task metrics. Candidate patches progress through a 5-stage lifecycle (candidate, applied, measured, promoted, graduated) with >55% improvement gates before becoming permanent methodology artifacts.
 **Cross-project learning** — proven rules propagate to `~/.claude/metrics/` and sync across all registered projects via `update-all`. Rules validated in 3+ projects become universal; 5+ projects qualify for npm distribution. Cross-project signal comparison and global ELO rankings available via `gsd-t-metrics --cross-project` and `gsd-t-status`.
 **Stack Rules Engine** — auto-detects project tech stack (React, TypeScript, Node API, Python, Go, Rust) from manifest files and injects mandatory best-practice rules into subagent prompts at execute-time. Universal security rules always apply; stack-specific rules layer on top. Includes **design-to-code** rules for pixel-perfect frontend implementation from Figma, screenshots, or design images — with Figma MCP integration, design token extraction, stack capability evaluation, and mandatory visual verification: every screen is rendered in a real browser, screenshotted at mobile/tablet/desktop, and compared pixel-by-pixel against the Figma design. Auto-bootstraps during partition when design references are detected. Extensible: drop a `.md` file in `templates/stacks/` to add a new stack.
@@ -175,6 +176,14 @@ This will replace changed command files, back up your CLAUDE.md if customized, a
 | `/user:gsd-t-verify` | Run quality gates + goal-backward behavior verification | In wave |
 | `/user:gsd-t-complete-milestone` | Archive + git tag (goal-backward gate required) | In wave |
 
+### Unattended Execution
+
+| 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 |
+
 ### Automation & Utilities
 
 | Command | Purpose | Auto |
@@ -311,6 +320,43 @@ your-project/
 
 ---
 
+## Unattended Execution (M36 — v3.10.10+)
+
+Run the active milestone to completion over hours or days — no human in the loop.
+
+```bash
+# Launch from the CLI (detached OS process)
+gsd-t unattended --hours=24
+
+# Or from within Claude Code (starts a 270s watch loop)
+/user:gsd-t-unattended
+
+# Stop (graceful — supervisor halts after the current worker finishes)
+/user:gsd-t-unattended-stop
+```
+
+**How it works:**
+
+- `gsd-t unattended` spawns `bin/gsd-t-unattended.js` as a fully detached OS process. The supervisor runs `claude -p` workers in a relay — one worker per iteration — each in a fresh context window. State is written atomically to `.gsd-t/.unattended/state.json` between iterations.
+- `/user:gsd-t-unattended` does the same from inside Claude Code, then calls `ScheduleWakeup(270, '/user:gsd-t-unattended-watch')` to start an in-session watch loop that ticks every 270 seconds and prints progress.
+- If you run `/clear` + `/user:gsd-t-resume` during a live run, the resume command auto-detects the running supervisor and re-attaches the watch loop — no re-launch needed.
+- The supervisor halts automatically when: the milestone reaches COMPLETED status, the `--hours` wall-clock cap expires, `--max-iterations` is reached, safety rails detect a stall or unrecoverable error, or the stop sentinel is touched.
+
+**Platform support:** macOS and Linux fully supported (including sleep-prevention via `caffeinate` on macOS). Windows is supported except sleep-prevention. See `docs/unattended-windows-caveats.md` for known Windows limitations.
+
+**Key flags:**
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--hours=N` | 24  |  Wall-clock cap |
+| `--max-iterations=N` | 200 | Iteration cap |
+| `--milestone=NAME` | (current) | Override active milestone |
+| `--dry-run` | false | Preflight only — no spawn |
+
+**State files** live under `.gsd-t/.unattended/`: `supervisor.pid`, `state.json`, `run.log`, `stop` (sentinel). Authoritative field definitions: `.gsd-t/contracts/unattended-supervisor-contract.md` v1.0.0.
+
+---
+
 ## Context Meter Setup (M34 — v2.75.10+)
 
 The Context Meter replaces the v2.74.12 task-counter proxy with real context-window measurement via the Anthropic `count_tokens` API. This is the authoritative signal for session-stop gates in `gsd-t-execute`, `gsd-t-wave`, `gsd-t-quick`, `gsd-t-integrate`, and `gsd-t-debug`.

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

@@ -0,0 +1,381 @@
+/**
+ * gsd-t-unattended-platform.js
+ *
+ * Cross-platform helpers for the unattended supervisor (M36).
+ *
+ * This module is the SINGLE place where `process.platform` branches live.
+ * Supervisor-core, watch-loop, and safety-rails import from here so that
+ * the rest of the supervisor can stay platform-agnostic.
+ *
+ * Contract: .gsd-t/contracts/unattended-supervisor-contract.md v1.0.0
+ *   §5  Exit Code Table (timeout = 3, OS process-timeout = 124)
+ *   §7  Launch Handshake (spawn semantics)
+ *
+ * Task 1 of m36-cross-platform delivers:
+ *   - resolveClaudePath()
+ *   - isAlive(pid)
+ *   - spawnWorker(projectDir, timeoutMs)
+ *
+ * Cross-platform notes:
+ *   - darwin / linux paths are runtime-tested.
+ *   - win32 paths are implementation-complete but NOT runtime-tested on the
+ *     dev host (macOS). Spike C and the full Windows caveats matrix ship in
+ *     Task 3 (`docs/unattended-windows-caveats.md`).
+ *
+ * Zero external dependencies — Node built-ins only.
+ */
+
+"use strict";
+
+const { spawnSync, spawn } = require("node:child_process");
+
+// ─── resolveClaudePath ───────────────────────────────────────────────────────
+
+/**
+ * Resolve the executable name for the `claude` CLI on the current platform.
+ *
+ * Returns `'claude.cmd'` on win32 and `'claude'` everywhere else.
+ *
+ * This is intentionally a simple platform branch — it does NOT shell out to
+ * `which` / `where`. The resolver assumes `claude` is on PATH; PATH lookup is
+ * delegated to `spawnSync`, which is cross-platform and quoting-safe.
+ *
+ * Cross-platform:
+ *   - darwin / linux: returns `'claude'`. The macOS / Linux installer puts
+ *     `claude` on PATH via `/usr/local/bin` or `/opt/homebrew/bin`.
+ *   - win32: returns `'claude.cmd'`. The Anthropic Windows installer ships a
+ *     `.cmd` shim. Using the `.cmd` filename explicitly (instead of bare
+ *     `claude`) avoids `spawnSync` falling through to `cmd.exe /c claude`,
+ *     which would re-introduce the Spike C PowerShell quoting hazard.
+ *
+ * @returns {string} `'claude'` or `'claude.cmd'`
+ */
+function resolveClaudePath() {
+  return process.platform === "win32" ? "claude.cmd" : "claude";
+}
+
+// ─── isAlive ─────────────────────────────────────────────────────────────────
+
+/**
+ * Cross-platform liveness check for a PID.
+ *
+ * Uses the POSIX trick `kill(pid, 0)` — sends signal 0, which performs all
+ * permission and existence checks but delivers no signal. Node's
+ * `process.kill` implements the same semantics on Windows.
+ *
+ * Errors:
+ *   - `ESRCH`  → no such process. Returns `false`.
+ *   - `EPERM`  → process exists but we don't own it. Returns `true` (we got
+ *                permission feedback, which proves the PID is live).
+ *   - other    → unexpected; rethrown.
+ *
+ * @param {number} pid
+ * @returns {boolean}
+ */
+function isAlive(pid) {
+  if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    if (err && err.code === "ESRCH") return false;
+    if (err && err.code === "EPERM") return true; // exists, not ours
+    throw err;
+  }
+}
+
+// ─── spawnWorker ─────────────────────────────────────────────────────────────
+
+/**
+ * Spawn a synchronous `claude -p '/gsd-t-resume'` worker iteration for the
+ * unattended supervisor.
+ *
+ * Returns a normalized result object: `{ status, stdout, stderr, signal,
+ * timedOut, error }`. Never throws — spawn errors are returned in `error`.
+ *
+ * Timeout semantics: when `spawnSync`'s `timeout` fires, the child is sent
+ * SIGTERM (or the equivalent on win32), `status` is `null`, and `signal` is
+ * non-null. We surface this as `timedOut: true` so callers can map to exit
+ * code 3 per contract §5.
+ *
+ * Spawn recipe (uniform across platforms):
+ *   - `shell: false`  → no shell quoting hazards
+ *   - `windowsHide: true`  → no flashed window on win32
+ *   - explicit `claude.cmd` filename on win32 (see resolveClaudePath JSDoc)
+ *
+ * @todo Spike C: verify `claude.cmd -p "/gsd-t-resume"` dispatches correctly
+ *       under PowerShell + cmd.exe + Git Bash. See
+ *       `docs/unattended-windows-caveats.md` (Task 3 of m36-cross-platform).
+ *
+ * @param {string} projectDir   Absolute path to the project directory (cwd).
+ * @param {number} timeoutMs    Wall-clock cap per worker iteration in ms.
+ * @param {object} [opts]       Optional overrides (test-mode hooks).
+ * @param {string} [opts.bin]   Override the resolved binary (test-mode only).
+ * @param {string[]} [opts.args] Override args (defaults to `['-p', '/gsd-t-resume']`).
+ * @param {object} [opts.env]   Override env (defaults to `process.env`).
+ * @returns {{
+ *   status: number|null,
+ *   stdout: string,
+ *   stderr: string,
+ *   signal: string|null,
+ *   timedOut: boolean,
+ *   error: Error|null
+ * }}
+ */
+function spawnWorker(projectDir, timeoutMs, opts = {}) {
+  const bin = opts.bin || resolveClaudePath();
+  const args = opts.args || ["-p", "/gsd-t-resume"];
+  const env = opts.env || process.env;
+
+  const result = spawnSync(bin, args, {
+    cwd: projectDir,
+    encoding: "utf8",
+    timeout: timeoutMs,
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: false,
+    windowsHide: true,
+  });
+
+  // Normalize. spawnSync may return error if the binary cannot be launched
+  // (ENOENT etc.) — surface it instead of throwing.
+  const stdout = typeof result.stdout === "string" ? result.stdout : "";
+  const stderr = typeof result.stderr === "string" ? result.stderr : "";
+  const signal = result.signal || null;
+  const status = typeof result.status === "number" ? result.status : null;
+
+  // Timeout detection: when spawnSync's `timeout` option fires it sets
+  //   - status === null
+  //   - signal !== null  (SIGTERM on POSIX, equivalent on win32)
+  //   - error.code === 'ETIMEDOUT'  (Node surfaces it as a synthetic Error)
+  // The ETIMEDOUT code is the authoritative signal — checking it
+  // discriminates a genuine timeout from an ENOENT/spawn failure.
+  const errCode = result.error && result.error.code;
+  const timedOut =
+    errCode === "ETIMEDOUT" || (status === null && signal !== null && !result.error);
+
+  return {
+    status,
+    stdout,
+    stderr,
+    signal,
+    timedOut,
+    // Suppress the synthetic ETIMEDOUT error so callers can rely on
+    // `timedOut` for the timeout case and `error` for genuine spawn failures.
+    error: errCode === "ETIMEDOUT" ? null : result.error || null,
+  };
+}
+
+// ─── spawnSupervisor ─────────────────────────────────────────────────────────
+
+/**
+ * Spawn a detached unattended supervisor process.
+ *
+ * Implements the Launch Handshake from contract §7: the interactive launch
+ * command forks a long-lived supervisor that outlives the parent, reads the
+ * state file, and relays `claude -p` workers until the milestone terminates.
+ *
+ * Spawn recipe:
+ *   - `node {binPath} unattended {...args}` — the `unattended` subcommand is
+ *     prepended automatically so callers pass only user-facing args.
+ *   - `detached: true` — the child becomes a process-group leader on POSIX
+ *     (darwin/linux) so it survives the parent closing its terminal. On win32
+ *     the equivalent flag produces a separate process tree.
+ *   - `stdio: 'ignore'` — no pipes held open that would block the parent
+ *     from exiting.
+ *   - `windowsHide: true` (win32 only) — no flashed console window.
+ *   - `child.unref()` — the parent event loop will not wait on the child.
+ *
+ * Cross-platform notes:
+ *   - darwin / linux: runtime-tested.
+ *   - win32: implementation-complete; documented in
+ *     `docs/unattended-windows-caveats.md` (Task 3).
+ *
+ * @param {object} params
+ * @param {string} params.binPath  Absolute path to `bin/gsd-t.js`.
+ * @param {string[]} params.args   Extra args appended after `unattended`.
+ * @param {string} params.cwd      Project directory (supervisor's cwd).
+ * @returns {{ pid: number }}      The detached child's PID.
+ */
+function spawnSupervisor({ binPath, args, cwd }) {
+  const spawnArgs = [binPath, "unattended", ...(args || [])];
+  const opts = {
+    cwd,
+    detached: true,
+    stdio: "ignore",
+  };
+  if (process.platform === "win32") {
+    opts.windowsHide = true;
+  }
+  const child = spawn("node", spawnArgs, opts);
+  child.unref();
+  return { pid: child.pid };
+}
+
+// ─── preventSleep ────────────────────────────────────────────────────────────
+
+/**
+ * Prevent the OS from going to sleep while the supervisor is running.
+ *
+ * Returns a handle that must be passed to `releaseSleep` when the supervisor
+ * terminates.
+ *
+ * Cross-platform:
+ *   - darwin: `caffeinate -i -w <supervisor-pid>` — the `-w` flag ties the
+ *     caffeinate lifetime to the supervisor's PID. Even if the supervisor
+ *     forgets to call `releaseSleep`, caffeinate will self-exit when the
+ *     supervisor dies. Returns the caffeinate child PID as the handle.
+ *   - linux: returns `null`. Reliable sleep prevention requires
+ *     `systemd-inhibit`, which only works under a user session bus and is
+ *     not universally available. v1 documents the gap; v2 may add opt-in
+ *     systemd-inhibit. Prints a one-line notice to stderr.
+ *   - win32: returns `null`. `SetThreadExecutionState` is the native API but
+ *     requires a C binding. v1 documents the gap; see
+ *     `docs/unattended-windows-caveats.md` (Task 3).
+ *
+ * @param {string} [reason]  Informational label (reserved; not currently used
+ *                           — darwin's caffeinate has no reason field, and
+ *                           linux/win32 don't have sleep prevention yet).
+ * @returns {number|null}    PID handle on darwin, `null` elsewhere.
+ */
+function preventSleep(reason) {
+  void reason; // reserved for future implementations
+  if (process.platform === "darwin") {
+    try {
+      const child = spawn("caffeinate", ["-i", "-w", String(process.pid)], {
+        detached: true,
+        stdio: "ignore",
+      });
+      child.unref();
+      return typeof child.pid === "number" ? child.pid : null;
+    } catch (err) {
+      process.stderr.write(
+        `[platform] caffeinate failed to spawn: ${err && err.message}\n`,
+      );
+      return null;
+    }
+  }
+  if (process.platform === "linux") {
+    process.stderr.write(
+      "[platform] sleep prevention not implemented on linux\n",
+    );
+    return null;
+  }
+  process.stderr.write(
+    "[platform] sleep prevention not implemented on win32 (see docs/unattended-windows-caveats.md)\n",
+  );
+  return null;
+}
+
+// ─── releaseSleep ────────────────────────────────────────────────────────────
+
+/**
+ * Release a sleep-prevention handle obtained from `preventSleep`.
+ *
+ * Idempotent and tolerant:
+ *   - `null` / non-number handle → no-op.
+ *   - handle is a dead PID → no-op (ESRCH is swallowed).
+ *   - handle is a live PID → `SIGTERM` is delivered (EPERM and other unusual
+ *     errors are swallowed — caller cannot reasonably act on them).
+ *
+ * @param {number|null} handle
+ * @returns {void}
+ */
+function releaseSleep(handle) {
+  if (handle == null) return;
+  if (typeof handle !== "number" || !Number.isInteger(handle) || handle <= 0) {
+    return;
+  }
+  if (!isAlive(handle)) return;
+  try {
+    process.kill(handle, "SIGTERM");
+  } catch (_err) {
+    // Swallow — releaseSleep must never throw. A dead/gone process is fine;
+    // an EPERM on an adopted PID is also fine (not ours to reap).
+  }
+}
+
+// ─── notify ──────────────────────────────────────────────────────────────────
+
+/**
+ * Emit an OS-level desktop notification. Fire-and-forget — never throws.
+ *
+ * Cross-platform:
+ *   - darwin: `osascript -e 'display notification "msg" with title "title"'`.
+ *   - linux: `notify-send "title" "message"` (requires libnotify).
+ *   - win32: `msg.exe * "title: message"` (console msg; ships with Windows).
+ *
+ * All platform helpers are fire-and-forget `spawn` calls. Errors are caught
+ * and logged to stderr so a missing binary (e.g., no libnotify installed on a
+ * headless Linux box) does NOT break the supervisor.
+ *
+ * @param {string} title
+ * @param {string} message
+ * @param {string} [level]   `info` | `warn` | `done` | `failed` — accepted but
+ *                           currently unused. Reserved for future formatting.
+ * @returns {void}
+ */
+function notify(title, message, level) {
+  void level; // reserved for future formatting
+  const safeTitle = String(title || "");
+  const safeMessage = String(message || "");
+  try {
+    if (process.platform === "darwin") {
+      // Escape double-quotes and backslashes for the AppleScript string
+      // literal. osascript uses double-quoted string syntax.
+      const esc = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+      const script =
+        `display notification "${esc(safeMessage)}" ` +
+        `with title "${esc(safeTitle)}"`;
+      const child = spawn("osascript", ["-e", script], { stdio: "ignore" });
+      child.on("error", (err) => {
+        process.stderr.write(
+          `[platform] notify(osascript) failed: ${err && err.message}\n`,
+        );
+      });
+      child.unref && child.unref();
+      return;
+    }
+    if (process.platform === "linux") {
+      const child = spawn("notify-send", [safeTitle, safeMessage], {
+        stdio: "ignore",
+      });
+      child.on("error", (err) => {
+        process.stderr.write(
+          `[platform] notify(notify-send) failed: ${err && err.message}\n`,
+        );
+      });
+      child.unref && child.unref();
+      return;
+    }
+    // win32
+    const child = spawn("msg.exe", ["*", `${safeTitle}: ${safeMessage}`], {
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    child.on("error", (err) => {
+      process.stderr.write(
+        `[platform] notify(msg.exe) failed: ${err && err.message}\n`,
+      );
+    });
+    child.unref && child.unref();
+  } catch (err) {
+    // Defense in depth — spawn() itself can throw synchronously on certain
+    // argument errors. Never propagate.
+    process.stderr.write(
+      `[platform] notify synchronous error: ${err && err.message}\n`,
+    );
+  }
+}
+
+module.exports = {
+  resolveClaudePath,
+  isAlive,
+  spawnWorker,
+  spawnSupervisor,
+  preventSleep,
+  releaseSleep,
+  notify,
+};