@tekyzinc/gsd-t 2.74.13 → 3.10.10

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

@@ -0,0 +1,290 @@
+# GSD-T: Unattended Watch — Stateless Watch Tick
+
+**Model**: haiku (polling a state file is mechanical — no reasoning needed)
+
+You are running one tick of the unattended supervisor watch loop. This command is **stateless**: every firing re-reads `.gsd-t/.unattended/supervisor.pid` + `state.json` + `run.log` from disk and makes a fresh decision. There is no in-memory state between ticks, and a `/clear` followed by `/user:gsd-t-resume` during a live unattended run is a no-op.
+
+The watch loop is the user's visibility surface into the running supervisor. It fires every 270 seconds (inside the 5-minute prompt-cache TTL) and either:
+1. Renders a compact status block + reschedules itself, OR
+2. Prints a terminal report and STOPS rescheduling.
+
+See `unattended-supervisor-contract.md` §8 (Watch Tick Decision Tree), §4 (Status Enum), §3 (state.json schema).
+
+## Decision Tree (Contract §8)
+
+```
+1. supervisor.pid absent           → finalized cleanly  → final report, STOP
+2. kill -0 {pid} fails             → crashed            → crash diagnostics + log tail, STOP
+3. state.json.status:
+     - done                        → success report, STOP
+     - failed                      → failure summary,  STOP
+     - stopped                     → user-stop confirm, STOP
+     - initializing | running      → render watch block, go to 4
+4. ScheduleWakeup(270, '/user:gsd-t-unattended-watch', reason='unattended tick {iter}')
+```
+
+**Critical**: Every branch except `initializing`/`running` is TERMINAL — do NOT reschedule. When you reach a terminal state, print the report and end the turn. Do not add a "Next Up" block — this is a self-rescheduling loop, not a phase workflow.
+
+## Step 1: Check State Directory
+
+Run via Bash:
+
+```bash
+if [ ! -d ".gsd-t/.unattended" ]; then
+  echo "No supervisor state directory at .gsd-t/.unattended/ — nothing to watch."
+  exit 0
+fi
+```
+
+If the directory does not exist, there is no supervisor to watch. Exit 0, do NOT reschedule. End the turn.
+
+## Step 2: Read State, PID, and Run.log Tail
+
+Run a single `node -e` block that gathers everything needed for the decision tree. This reads the last ~2KB of `run.log` via `fs.open` + `fs.read` with a negative offset from end (not `readFileSync`), so the command stays cheap even when `run.log` is hundreds of MB.
+
+```bash
+node -e "
+const fs = require('fs');
+const path = require('path');
+
+const UDIR = '.gsd-t/.unattended';
+const PID_FILE = path.join(UDIR, 'supervisor.pid');
+const STATE_FILE = path.join(UDIR, 'state.json');
+const LOG_FILE = path.join(UDIR, 'run.log');
+
+function out(k, v) { console.log(k + '=' + JSON.stringify(v ?? null)); }
+
+// --- PID file ---
+let pid = null;
+let pidFileExists = fs.existsSync(PID_FILE);
+if (pidFileExists) {
+  try {
+    pid = parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10);
+    if (!Number.isFinite(pid)) pid = null;
+  } catch (_) { pid = null; }
+}
+out('PID_FILE_EXISTS', pidFileExists);
+out('PID', pid);
+
+// --- kill -0 liveness ---
+let alive = null;
+if (pid !== null) {
+  try { process.kill(pid, 0); alive = true; }
+  catch (_) { alive = false; }
+}
+out('ALIVE', alive);
+
+// --- state.json ---
+let state = null;
+try { state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8')); }
+catch (_) {
+  // tolerate transient rename race — retry once
+  try { state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8')); }
+  catch (_) { state = null; }
+}
+if (state) {
+  out('STATUS', state.status);
+  out('SESSION', state.sessionId);
+  out('MILESTONE', state.milestone);
+  out('WAVE', state.wave);
+  out('TASK', state.task);
+  out('ITER', state.iter);
+  out('MAX_ITER', state.maxIterations);
+  out('STARTED_AT', state.startedAt);
+  out('LAST_TICK', state.lastTick);
+  out('LAST_EXIT', state.lastExit);
+  out('LAST_ELAPSED_MS', state.lastElapsedMs);
+  out('LOG_PATH', state.logPath || LOG_FILE);
+  // elapsed
+  const started = state.startedAt ? Date.parse(state.startedAt) : null;
+  const elapsedMs = started ? (Date.now() - started) : null;
+  out('ELAPSED_MS', elapsedMs);
+  // last tick age
+  const lt = state.lastTick ? Date.parse(state.lastTick) : null;
+  const tickAgeMs = lt ? (Date.now() - lt) : null;
+  out('TICK_AGE_MS', tickAgeMs);
+} else {
+  out('STATUS', null);
+}
+
+// --- run.log tail (last ~2KB via fd seek, not full read) ---
+let tailLines = [];
+try {
+  const st = fs.statSync(LOG_FILE);
+  const size = st.size;
+  const readLen = Math.min(size, 2048);
+  const offset = size - readLen;
+  const fd = fs.openSync(LOG_FILE, 'r');
+  const buf = Buffer.alloc(readLen);
+  fs.readSync(fd, buf, 0, readLen, offset);
+  fs.closeSync(fd);
+  const text = buf.toString('utf8');
+  tailLines = text.split('\n').filter(l => l.trim().length > 0);
+} catch (_) { tailLines = []; }
+// last 50 lines for crash path; last 1 non-empty for normal path
+const last50 = tailLines.slice(-50);
+const last1 = tailLines.length > 0 ? tailLines[tailLines.length - 1] : '';
+out('LOG_TAIL_LAST1', last1);
+out('LOG_TAIL_LAST50', last50.join('\n'));
+"
+```
+
+## Step 3: Branch on PID File Absence (Finalized Cleanly)
+
+If `PID_FILE_EXISTS=false`:
+
+The supervisor has finalized cleanly and removed its own PID file. Read the final `state.json` status and iter, then print the terminal report:
+
+```
+✅  Unattended supervisor finalized cleanly.
+
+   Session:       {SESSION}
+   Milestone:     {MILESTONE}
+   Final status:  {STATUS}
+   Iterations:    {ITER} / {MAX_ITER}
+   Total elapsed: {Hh Mm — formatted from ELAPSED_MS}
+   Log:           {LOG_PATH}
+   State:         .gsd-t/.unattended/state.json
+```
+
+If `state.json` was also unreadable (null STATUS), emit:
+
+```
+⚠️   Unattended supervisor PID file absent but state.json unreadable.
+    Manual inspection required: ls -la .gsd-t/.unattended/
+```
+
+**STOP** — do NOT reschedule. End the turn.
+
+## Step 4: Branch on Dead PID (Crashed)
+
+If `PID_FILE_EXISTS=true` AND `ALIVE=false`:
+
+The supervisor process is gone but it did not remove its PID file — this is a crash. Print crash diagnostics including the last 50 lines of `run.log`:
+
+```
+💥  Unattended supervisor CRASHED (PID {PID} no longer alive).
+
+    Last known state:
+      Session:   {SESSION}
+      Status:    {STATUS}
+      Iter:      {ITER} / {MAX_ITER}
+      Last tick: {LAST_TICK} (age {tickAgeMs → seconds})
+      Last exit: {LAST_EXIT}
+
+    Last 50 lines of run.log:
+    ──────────────────────────────────────────────
+    {LOG_TAIL_LAST50}
+    ──────────────────────────────────────────────
+
+    Recovery: inspect .gsd-t/.unattended/run.log and .gsd-t/.unattended/state.json.
+    Remove the stale PID file with: rm .gsd-t/.unattended/supervisor.pid
+    Then relaunch with: /user:gsd-t-unattended
+```
+
+**STOP** — do NOT reschedule. End the turn.
+
+## Step 5: Branch on Terminal Status
+
+If `PID_FILE_EXISTS=true` AND `ALIVE=true` AND `STATUS` is terminal (`done` | `failed` | `stopped`):
+
+The supervisor is still alive but has transitioned to a terminal status on its last tick. The next supervisor pass will remove the PID file — we just caught it mid-cleanup. Print the matching report and STOP.
+
+### 5a: STATUS=done
+
+```
+🎉  Unattended supervisor COMPLETED the milestone.
+
+    Session:       {SESSION}
+    Milestone:     {MILESTONE} — DONE
+    Iterations:    {ITER} / {MAX_ITER}
+    Total elapsed: {Hh Mm}
+    Log:           {LOG_PATH}
+
+    The supervisor will clean up its PID file momentarily.
+```
+
+### 5b: STATUS=failed
+
+```
+❌  Unattended supervisor HALTED — status=failed.
+
+    Session:       {SESSION}
+    Milestone:     {MILESTONE}
+    Iterations:    {ITER} / {MAX_ITER}
+    Last exit:     {LAST_EXIT}
+    Total elapsed: {Hh Mm}
+    Log:           {LOG_PATH}
+
+    See run.log for the halt reason. The supervisor finalized state.json before exiting.
+```
+
+### 5c: STATUS=stopped
+
+```
+🛑  Unattended supervisor STOPPED by user.
+
+    Session:       {SESSION}
+    Milestone:     {MILESTONE}
+    Iterations:    {ITER} / {MAX_ITER}
+    Total elapsed: {Hh Mm}
+    Log:           {LOG_PATH}
+
+    Stop sentinel was honored between worker iterations. Relaunch with /user:gsd-t-unattended.
+```
+
+**STOP** — do NOT reschedule. End the turn.
+
+## Step 6: Render Live Watch Block (Non-Terminal)
+
+If `PID_FILE_EXISTS=true` AND `ALIVE=true` AND `STATUS` is `initializing` or `running`:
+
+Render the compact watch block below. Format rules:
+- One extra space after each emoji (per CLAUDE.md markdown table rules — preserves alignment in terminal views).
+- Elapsed formatted as `{H}h{M}m` from `ELAPSED_MS`.
+- Last-tick age formatted as `{S}s` or `{M}m{S}s`. If age > 540s (2× tick cadence), append ` ⚠️  stale` as a soft warning (not a crash — per contract §3 write semantics).
+- `LAST_EXIT` duration from `LAST_ELAPSED_MS` rendered as seconds.
+- Wave/task lines are omitted when absent from state.
+- Last non-empty `run.log` line is truncated to 80 chars.
+
+```
+⚙  Unattended — {MILESTONE}{ Wave {WAVE}}{ · Task {TASK}}
+⏱  Iter {ITER} / {MAX_ITER} · elapsed {Hh Mm} · last tick {tickAge}
+📊  Last exit: {LAST_EXIT} ({durationSec}s) · PID {PID} · session {SESSION}
+📝  {truncated last log line or "(no output yet)"}
+⏰  Next tick in 270s · Stop: /user:gsd-t-unattended-stop
+```
+
+(5 lines — the contract §8 format allows up to 10. Keep it tight.)
+
+## Step 7: Reschedule via ScheduleWakeup (Non-Terminal Only)
+
+**This step runs ONLY when Step 6 rendered a live watch block.** All terminal branches (Steps 3, 4, 5) must NOT reach this step — they STOP.
+
+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`: `unattended tick {ITER}` — substituting the integer `ITER` from Step 2
+
+Tool invocation pattern (make this real tool call, not a bash command):
+
+```
+ScheduleWakeup(
+  delaySeconds: 270,
+  prompt: "/user:gsd-t-unattended-watch",
+  reason: "unattended tick {ITER}"
+)
+```
+
+After the tool call, end the turn. Do NOT output a "Next Up" hint, do NOT continue with further steps, do NOT summarize. The watch block from Step 6 plus the ScheduleWakeup tool call IS the entire turn output.
+
+## Notes
+
+- **Stateless**: every tick re-reads state from disk. No memory between firings.
+- **Terminal = STOP**: any terminal branch (3, 4, 5) ends the loop. The user relaunches via `/user:gsd-t-unattended` if needed.
+- **Never spawn subagents**: this is a pure polling command — no Task, no TeamCreate, no observability logging block.
+- **No branch guard, no pre-commit gate, no doc ripple**: this command does not modify any files.
+- **Stale-tick tolerance**: if `lastTick` is >540s old but PID is still alive, warn soft (`⚠️  stale`) but still reschedule — the supervisor may be mid-worker.
+
+$ARGUMENTS

package/commands/gsd-t-unattended.md

@@ -0,0 +1,414 @@
+# 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
+
+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