@tekyzinc/gsd-t 2.74.13 → 3.10.10

package/commands/gsd-t-pause.md

@@ -47,6 +47,9 @@ Create `.gsd-t/continue-here-{timestamp}.md`:
 {any known blockers, pending decisions, or things to watch out for}
 {None if clean}
 
+## Outstanding User Directive
+{Copy any multi-step chain the user gave earlier in the session that has NOT been fully executed, verbatim. Examples: "run until milestone complete, then checkin publish update all", "complete M34 and then archive + publish". Resume honors this after the resumed phase finishes. Leave as _None_ if no outstanding chain.}
+
 ## User Note
 {$ARGUMENTS if provided, otherwise: _No note provided._}
 

package/commands/gsd-t-plan.md

@@ -2,6 +2,13 @@
 
 You are the lead agent creating atomic execution plans for each domain. This phase is ALWAYS single-session — one agent with full context across all domains to ensure consistency.
 
+## Model Assignment
+
+Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
+
+- **Default**: `sonnet` (`selectModel({phase: "plan"})`) — task decomposition is structured work.
+- **Escalation**: `/advisor` convention-based fallback from `bin/advisor-integration.js` when a task touches a contract boundary or requires a decision about task granularity (too coarse → brittle execution; too fine → coordination overhead). Never silently downgrade the model under context pressure — M35 removed that behavior.
+
 ## Step 1: Load Full Context
 
 Read ALL of these:
@@ -376,9 +383,9 @@ Report: PASS (all checks pass) or FAIL with specific gaps listed."
 Before spawning — run via Bash:
 `T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
 After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-plan | Step 7 | haiku | {DURATION}s | {PASS/FAIL}, iteration {N} | | | {COUNTER} |`
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Domain | Task | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-plan | Step 7 | haiku | {DURATION}s | {PASS/FAIL}, iteration {N} | | | {CTX_PCT} |`
 If validation FAIL, append each gap to `.gsd-t/qa-issues.md` (create with header `| Date | Command | Step | Model | Duration(s) | Severity | Finding |` if missing):
 `| {DT_START} | gsd-t-plan | Step 7 | haiku | {DURATION}s | medium | {gap description} |`
 

package/commands/gsd-t-prd.md

@@ -23,9 +23,9 @@ Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-pr
 ```
 
 After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-prd | Step 0 | sonnet | {DURATION}s | prd: {topic summary} | {COUNTER} |`
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-prd | Step 0 | sonnet | {DURATION}s | prd: {topic summary} | {CTX_PCT} |`
 
 Relay the subagent's summary to the user. **Do not execute Steps 1–6 yourself.**
 

package/commands/gsd-t-quick.md

@@ -2,7 +2,70 @@
 
 You are executing a small, focused task that doesn't need full phase planning. This is for bug fixes, config changes, small features, and ad-hoc work.
 
-## Step 0: Launch via Subagent
+## Model Assignment
+
+Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
+
+- **Default**: `sonnet` (`selectModel({phase: "quick"})`) — routine one-off task.
+- **Mechanical subroutines** (demote to `haiku`): test runners (`selectModel({phase: "quick", task_type: "test_runner"})`).
+- **Red Team (Step 5.5)**: `opus` — adversarial reasoning always runs at top tier.
+- **Escalation**: `/advisor` convention-based fallback from `bin/advisor-integration.js` at declared high-stakes sub-decisions (see `.gsd-t/M35-advisor-findings.md`). Never silently downgrade the model or skip Red Team / doc-ripple under context pressure — M35 removed that behavior.
+
+## Per-Spawn Token Bracket (MANDATORY — wrap EVERY Task subagent spawn)
+
+Per `.gsd-t/contracts/token-telemetry-contract.md` v1.0.0. Every Task subagent spawn below **MUST** be wrapped in this token bracket so `.gsd-t/token-metrics.jsonl` gets one record per spawn. This is additive — the existing OBSERVABILITY LOGGING blocks in each spawn site are preserved unmodified alongside this bracket.
+
+**Before each spawn — read starting context tokens:**
+
+```bash
+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')}")
+```
+
+**After each spawn — record the bracket:**
+
+```bash
+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')}")
+node -e "require('./bin/token-telemetry.js').recordSpawn({timestamp:new Date().toISOString(),milestone:process.env.GSD_T_MILESTONE||'',command:'gsd-t-quick',phase:'quick',step:'${STEP:-}',domain:'${DOMAIN:-}',domain_type:'${DOMAIN_TYPE:-}',task:'${TASK:-}',model:'${MODEL:-sonnet}',duration_s:${DURATION:-0},input_tokens_before:${T0_TOKENS},input_tokens_after:${T1_TOKENS},tokens_consumed:${T1_TOKENS}-${T0_TOKENS},context_window_pct_before:${T0_PCT},context_window_pct_after:${T1_PCT},outcome:'${OUTCOME:-success}',halt_type:${HALT_TYPE:-null},escalated_via_advisor:${ESCALATED_VIA_ADVISOR:-false}})" 2>/dev/null || true
+```
+
+The bracket is additive to the existing `.gsd-t/token-log.md` OBSERVABILITY LOGGING rows. Both sinks coexist — token-log.md is human-readable, token-metrics.jsonl is machine-readable for `gsd-t metrics` aggregation.
+
+## Step 0: Runway Check (MANDATORY — before any other work in a fresh session)
+
+Quick tasks are always single-task, so `remaining_tasks=1`. Run via Bash:
+
+```bash
+node -e "
+const r = require('./bin/runway-estimator.js').estimateRunway({
+  command: 'gsd-t-quick',
+  domain_type: '',
+  remaining_tasks: 1,
+  projectDir: '.'
+});
+console.log(JSON.stringify(r, null, 2));
+if (!r.can_start) {
+  console.log('⛔ Insufficient runway — projected ' + r.projected_end_pct + '% (current ' + r.current_pct + '%, ' + r.pct_per_task + '%/task, ' + r.confidence + ' confidence, ' + r.confidence_basis + ' records)');
+  console.log('Auto-spawning headless to continue in a fresh context.');
+  const s = require('./bin/headless-auto-spawn.js').autoSpawnHeadless({
+    command: 'gsd-t-quick', args: [], continue_from: '.'
+  });
+  console.log('Session ID: ' + s.id);
+  console.log('Status: tail ' + s.logPath);
+  console.log('');
+  console.log('Your interactive session remains idle — you can use it for other work.');
+  console.log('You will be notified when the headless run completes.');
+  process.exit(0);
+}
+"
+```
+
+If `can_start === false`, the headless continuation has been spawned and the interactive session must stop here. Do NOT proceed to Step 0.1.
+
+**Contract**: `.gsd-t/contracts/runway-estimator-contract.md` v1.0.0; stop threshold (85%) mirrors `.gsd-t/contracts/token-budget-contract.md` v3.0.0.
+
+## Step 0.1: Launch via Subagent
 
 To give this task a fresh context window and prevent compaction during consecutive quick runs, always execute via a Task subagent.
 
@@ -17,11 +80,10 @@ Before spawning — run via Bash:
 Run via Bash:
 `node -e "const tb = require('./bin/token-budget.js'); const s = tb.getSessionStatus('.'); process.stdout.write(s.threshold);" 2>/dev/null`
 
-Apply the result:
+Apply the result (three-band model per `token-budget-contract.md` v3.0.0 — never silently degrade quality):
 - `normal` or file missing → proceed with default model (sonnet)
-- `downgrade` → downgrade subagent model from sonnet to haiku for non-critical tasks; apply `getDegradationActions()` model overrides
-- `conserve` → run quick task inline (skip subagent spawn overhead); skip Red Team and doc-ripple
-- `stop` → output: "Token budget exhausted — quick task deferred. Resume after session reset." and halt
+- `warn` (≥70%) → log the warning to `.gsd-t/token-log.md` and proceed at full quality. **Do NOT downgrade models, skip Red Team, or skip doc-ripple** — M35 removed that behavior intentionally.
+- `stop` (≥85%) → output: "Context gate reached ({pct}%). Quick task deferred. Resume after session reset." and halt.
 
 **Stack Rules Detection (before spawning subagent):**
 
@@ -96,8 +158,8 @@ Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-qu
 
 After subagent returns — run via Bash:
 `T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-quick | Step 0 | sonnet | {DURATION}s | quick: {task summary} | {COUNTER} |`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-quick | Step 0 | sonnet | {DURATION}s | quick: {task summary} | {CTX_PCT} |`
 
 Relay the subagent's summary to the user. **Do not execute Steps 1–5 yourself.**
 
@@ -341,10 +403,10 @@ Spawn Task subagent (general-purpose, model: opus):
 After subagent returns — run via Bash:
 ```
 T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))
-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('')}})")
+CTX_PCT=$(node -e "try{const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct))}catch(_){process.stdout.write('N/A')}")
 ```
 Append to `.gsd-t/token-log.md`:
-`| {DT_START} | {DT_END} | gsd-t-quick | Red Team | opus | {DURATION}s | {VERDICT} — {N} bugs found | | | {COUNTER} |`
+`| {DT_START} | {DT_END} | gsd-t-quick | Red Team | opus | {DURATION}s | {VERDICT} — {N} bugs found | | | {CTX_PCT} |`
 
 **If Red Team VERDICT is FAIL:**
 1. Fix all CRITICAL and HIGH bugs (up to 2 fix cycles)

package/commands/gsd-t-reflect.md

@@ -21,14 +21,10 @@ Skip Step 0 — you are already the subagent."
 **OBSERVABILITY LOGGING — after subagent returns:**
 
 Run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
+`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.js'); process.stdout.write(String(tb.getSessionStatus('.').pct||'N/A'))" 2>/dev/null || echo "N/A")`
 
-Compute tokens:
-- No compaction (TOK_END >= TOK_START): `TOKENS=$((TOK_END-TOK_START))`, COMPACTED=null
-- Compaction detected (TOK_END < TOK_START): `TOKENS=$(((TOK_MAX-TOK_START)+TOK_END))`, COMPACTED=$DT_END
-
-Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Tasks-Since-Reset |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-reflect | Step 0 | sonnet | {DURATION}s | retrospective generated | {COUNTER} |`
+Append to `.gsd-t/token-log.md` (create with header `| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Notes | Ctx% |` if missing):
+`| {DT_START} | {DT_END} | gsd-t-reflect | Step 0 | sonnet | {DURATION}s | retrospective generated | {CTX_PCT} |`
 
 Return the subagent's output and stop. Only skip Step 0 if you are already running as a subagent.
 

package/commands/gsd-t-resume.md

@@ -2,7 +2,34 @@
 
 You are resuming work after an interruption. This handles both same-session pauses (user pressed Esc to interject) and cross-session recovery (new Claude Code session).
 
-## Step 0: Detect Resume Mode
+## Step 0: Unattended Supervisor Auto-Reattach
+
+**This step runs FIRST, before reading any docs, contracts, or continue-here files.**
+
+Check whether an unattended supervisor is actively running for this project:
+
+1. Check if `.gsd-t/.unattended/supervisor.pid` exists.
+   - **Does not exist** → no supervisor running. Fall through to Step 0.1.
+
+2. **File exists**: Read the PID (single integer on one line). Run:
+   ```bash
+   kill -0 <pid> 2>/dev/null && echo "alive" || echo "dead"
+   ```
+   - **"dead"** → supervisor exited (cleanly or crashed). The PID file is stale. Log: `[resume] supervisor PID <pid> no longer alive — stale PID file, falling through to normal resume`. Fall through to Step 0.1.
+   - **"alive"** → supervisor process is live. Proceed to step 3.
+
+3. **Supervisor is alive**: Read `.gsd-t/.unattended/state.json`. Check `state.status`:
+   - **Terminal status** (`done`, `failed`, `stopped`, `crashed`) → the supervisor has finished and is waiting for cleanup. Fall through to Step 0.1 so normal resume flow runs (it will see progress.md state and continue from where the supervisor left off).
+   - **Non-terminal status** (`initializing`, `running`, or any unrecognized value) → **AUTO-REATTACH**:
+     - Print the current watch status using the data in `state.json` (elapsed time, current iteration, milestone/wave/task, last worker exit code).
+     - Call `ScheduleWakeup(270, '/user:gsd-t-unattended-watch', reason='resumed watch')`.
+     - **STOP reading resume.md entirely. Do NOT proceed to Step 0.1 or any later step. Do NOT read docs, contracts, or continue-here files. Do NOT display a headless read-back banner.** The watcher will display the live status block and re-schedule itself. Return now.
+
+Contract reference: `unattended-supervisor-contract.md` §9 (Resume Auto-Reattach Handshake)
+
+---
+
+## Step 0.1: Detect Resume Mode
 
 **Same-session** (conversation context still available — you can see prior messages about the active phase/task):
 - Skip to Step 2 — you already have the context loaded
@@ -11,6 +38,40 @@ You are resuming work after an interruption. This handles both same-session paus
 **Cross-session** (first command in a new session, no prior conversation context):
 - Run Step 1 to load full state
 
+## Step 0.2: Handoff Lock Wait (headless resume only)
+
+Before reading any continue-here file or state file, check if a parent process wrote a handoff lock for this session:
+
+```bash
+node -e "
+const sessionId = process.env.CLAUDE_HEADLESS_SESSION_ID;
+if (!sessionId) { process.exit(0); }
+const hl = require('./bin/handoff-lock.js');
+hl.waitForLockRelease('.', sessionId, 5000)
+  .then(() => process.exit(0))
+  .catch(e => { console.error('[resume] handoff lock wait timed out:', e.message); process.exit(0); });
+"
+```
+
+- If `CLAUDE_HEADLESS_SESSION_ID` is not set (interactive resume) → the script exits immediately; no wait needed.
+- If set → wait up to **5 seconds** for the parent's handoff lock to be released before reading `.gsd-t/continue-here-*.md` or any other state file. On timeout, log and proceed anyway (parent may have crashed after spawning).
+
+This prevents the child side of a headless runway-handoff from reading a partial continue-here file written by the parent. Contract: `headless-auto-spawn-contract.md` v1.0.0, m35-gap-fixes T2 deferred hook.
+
+---
+
+## Step 0.5: Headless Read-Back Banner (MANDATORY)
+
+Before loading full state, surface any completed headless sessions the user hasn't seen yet. Run this once at the start of every resume invocation:
+
+```bash
+node bin/check-headless-sessions.js . 2>/dev/null || true
+```
+
+This prints a `## Headless runs since you left` banner listing any completed sessions with their duration, outcome, and log path, then marks them surfaced so the banner never re-appears for the same session. If no completed sessions exist, it prints nothing.
+
+Contract: `.gsd-t/contracts/headless-auto-spawn-contract.md` v1.0.0
+
 ## Step 1: Load Full State (cross-session only)
 
 Read in this exact order:
@@ -69,4 +130,28 @@ Otherwise, pick up from the logical next action based on current state:
 - Blocked → Explain what's needed to unblock
 - Verify failed → Show remediation tasks
 
+## Step 5: Auto-Advance Through End of Milestone (MANDATORY)
+
+**Resume does NOT stop at the end of a wave or phase. It must chain all the way to `COMPLETED` status.**
+
+When the resumed work reaches a natural handoff point, do NOT print a "Next Up" hint and wait for the user. At Level 3 Full Auto, keep going. The successor mapping in CLAUDE-global.md is the contract — resume honors it exactly like any other command:
+
+| If resume just finished… | Auto-advance to |
+|--------------------------|-----------------|
+| A task (mid-wave, tasks remaining) | next task in the same wave |
+| The last task of a wave (waves remaining) | next wave |
+| The last task of the last wave | `/user:gsd-t-verify` (which auto-invokes `/user:gsd-t-complete-milestone` per verify Step 8) |
+| `/user:gsd-t-verify` (VERIFIED or VERIFIED-WITH-WARNINGS) | `/user:gsd-t-complete-milestone` (verify already spawns this — do not re-invoke) |
+| `/user:gsd-t-complete-milestone` | honor any outstanding multi-step user directive (see below) |
+
+**Never stop at "Wave N complete" or "Task N done" and wait.** The only stopping points are:
+1. VERIFY-FAILED (report failures)
+2. Destructive action needing approval
+3. Unrecoverable error after 2 fix attempts + debug-loop exit 4
+4. `COMPLETED` status reached AND no outstanding user directive
+
+**Outstanding User Directive** (from the continue-here file): If the continue-here file contains an `## Outstanding User Request` or `## User Note` section with a multi-step chain (e.g., "run until milestone complete, then checkin publish update-all"), resume MUST continue executing that chain AFTER complete-milestone finishes. Parse the remaining steps and invoke them in order. Do not stop and ask — the directive was already given.
+
+**Self-check before printing a "Next Up" hint**: Before emitting any `## ▶ Next Up` block, ask: "Is this a Level 3 auto-advance transition?" If yes (which it almost always is at end-of-wave or end-of-milestone under Level 3), SKIP the hint and invoke the next command directly. The hint exists for commands with no successor OR for lower autonomy levels, NOT for the resume-driven path back to COMPLETED.
+
 $ARGUMENTS

package/commands/gsd-t-status.md

@@ -19,6 +19,37 @@ Wait for the subagent to complete. Relay its output to the user. **Do not read f
 **If you are the spawned subagent** (your prompt says "running gsd-t-status"):
 Continue below.
 
+## Step 0: Headless Read-Back Banner (MANDATORY)
+
+Before reading any files, surface any completed headless sessions the user hasn't seen yet. Run this once at the start of every status invocation:
+
+```bash
+node bin/check-headless-sessions.js . 2>/dev/null || true
+```
+
+This prints a `## Headless runs since you left` banner listing any completed sessions with their duration, outcome, and log path, then marks them surfaced so the banner never re-appears for the same session. If no completed sessions exist, it prints nothing. The banner appears at the very top of status output — before the main status table.
+
+Contract: `.gsd-t/contracts/headless-auto-spawn-contract.md` v1.0.0
+
+## Step 0.5: Optimization Backlog Pending Count (one-liner)
+
+Immediately after the headless banner, surface the count of pending token-optimizer recommendations. Show only when `N > 0` — when `N === 0`, omit the line entirely (no noise).
+
+```bash
+node -e "
+try {
+  const opt = require('./bin/token-optimizer.js');
+  const entries = opt.parseBacklog(opt.readBacklog('.'));
+  const pending = entries.filter(e => e.status === 'pending').length;
+  if (pending > 0) {
+    console.log('Optimization backlog: ' + pending + ' pending recommendation(s) — /user:gsd-t-backlog-list --file optimization-backlog.md');
+  }
+} catch (_) { /* optimizer unavailable — silent */ }
+"
+```
+
+Contract: `.gsd-t/contracts/token-telemetry-contract.md` v1.0.0
+
 ## Read These Files
 
 1. `.gsd-t/progress.md`

package/commands/gsd-t-test-sync.md

@@ -2,6 +2,13 @@
 
 You are maintaining test coverage as code changes. Your job is to identify stale tests, coverage gaps, and dead tests, then generate tasks to address them.
 
+## Model Assignment
+
+Per `.gsd-t/contracts/model-selection-contract.md` v1.0.0.
+
+- **Default**: `sonnet` (`selectModel({phase: "test-sync"})`) — test alignment is routine refactoring work.
+- **Escalation**: `/advisor` convention-based fallback from `bin/advisor-integration.js` when a test touches a contract boundary or requires judgment about what "missing coverage" means. Never silently skip test-sync under context pressure — M35 removed that behavior.
+
 This command is:
 - **Auto-invoked** during execute phase (after each task) and verify phase
 - **Standalone** when user wants to audit test health

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

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