@tekyzinc/gsd-t 3.13.16 → 3.16.11

package/commands/gsd-t-design-decompose.md

@@ -358,9 +358,7 @@ After writing all contracts but BEFORE proceeding to partition or build, spawn a
 
 > **Why a separate agent?** The decompose agent that classified the charts cannot objectively verify its own classifications. It has the same blind spots that caused the misclassification. This was proven repeatedly — the same agent rubber-stamps its own work. A fresh agent with only the contracts and Figma access catches what the classifier missed.
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the Chart Classification Verifier spawn with `captureSpawn`:** route through `bin/gsd-t-token-capture.cjs` with `{command: 'gsd-t-design-decompose', step: 'Chart Classification Verifier', model: 'opus', projectDir: '.', notes: 'verification {PASSED/FAILED}'}`. The wrapper owns banner + timing + envelope parse + row write.
 
 ⚙ [opus] gsd-t-design-decompose → Chart Classification Verifier
 
@@ -443,10 +441,7 @@ If ALL ✅ MATCH:
 "
 ```
 
-After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))`
-
-Compute tokens/compaction per standard pattern. Append to `.gsd-t/token-log.md`.
+After the `captureSpawn` wrapper returns, the row is already written to `.gsd-t/token-log.md` under the canonical header with Tokens = `in=N out=N cr=N cc=N $X.XX` (or `—` if no envelope). No post-processing needed.
 
 **If VERIFICATION FAILED**: Fix every misclassified element contract before proceeding:
 1. Rename the contract file to match the correct chart type

package/commands/gsd-t-doc-ripple.md

@@ -97,19 +97,28 @@ For each document or logical group:
 ⚙ [haiku] gsd-t-doc-ripple → update {document}
 (Use sonnet for docs/architecture.md and docs/requirements.md — these need reasoning.)
 
-**OBSERVABILITY LOGGING (MANDATORY) — for each subagent spawn:**
+**OBSERVABILITY LOGGING (MANDATORY) — wrap each document-update subagent with `captureSpawn`:**
 
-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))`
-
-Read the real context% from the Context Meter state file:
-`CTX_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs'); process.stdout.write(String(tb.getSessionStatus('.').pct))}catch(_){process.stdout.write('N/A')}")`
+```
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-doc-ripple',
+    step: 'Step 5',
+    model: '{haiku|sonnet}',
+    description: 'update {document}',
+    projectDir: '.',
+    domain: 'doc-ripple',
+    task: '-',
+    notes: 'update:{document}',
+    spawnFn: async () => { /* Task subagent call for the document-update prompt below */ },
+  });
+})();
+"
+```
 
-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-doc-ripple | Step 5 | {model} | {DURATION}s | update:{document} | doc-ripple | — | {CTX_PCT} |`
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 **Each document-update subagent prompt:**
 ```

package/commands/gsd-t-execute.md

@@ -170,18 +170,30 @@ Each domain's work runs via a lightweight domain task-dispatcher. The dispatcher
 - Up to 5 prior task summaries (10-20 lines each, most recent first)
 - Past failure/learning entries for this domain (max 5 lines)
 
-**OBSERVABILITY LOGGING (MANDATORY) — repeat for every task subagent spawn:**
+**OBSERVABILITY LOGGING (MANDATORY) — wrap every task subagent spawn with `captureSpawn`:**
 
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
+Route the spawn through `bin/gsd-t-token-capture.cjs` so the real `usage` envelope is parsed. The wrapper owns banner + timing + envelope parse + row write + JSONL record. Example for a per-task dispatch:
 
-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 | Ctx% |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-execute | task:{task-id} | sonnet | {DURATION}s | {pass/fail} | {domain-name} | task-{task-id} | {CTX_PCT} |`
+```
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-execute',
+    step: 'task:{task-id}',
+    model: 'sonnet',
+    description: 'domain: {domain-name} task: {task-id}',
+    projectDir: '.',
+    domain: '{domain-name}',
+    task: '{task-id}',
+    notes: '{pass/fail}',
+    spawnFn: async () => { /* Task(...) or spawn('claude', ...) call */ },
+  });
+})();
+"
+```
 
-Where `{CTX_PCT}` is the current `pct` value returned by `getSessionStatus()` (Step 3.5). As of v2.0.0 (M34), `pct` reads the **real** `input_tokens` count from `.gsd-t/.context-meter-state.json` — the count_tokens-based measurement produced by the Context Meter PostToolUse hook. When the state file is absent or stale, the fallback heuristic writes a best-effort percentage and this column reads `N/A` instead. The previous `Tasks-Since-Reset` column (v2.74.12) is retired.
+`captureSpawn` writes the row to `.gsd-t/token-log.md` under the canonical header (`| Datetime-start | Datetime-end | Command | Step | Model | Duration(s) | Tokens | Notes | Domain | Task | Ctx% |`) — upgrading old headers in place. The **Tokens** cell renders as `in=N out=N cr=N cc=N $X.XX` when `result.usage` is present, or `—` when absent. Never `0`. Never `N/A`. The wrapper also pulls `Ctx%` from `getSessionStatus()` automatically (Step 3.5 context) — `pct` reads the real `input_tokens` count from `.gsd-t/.context-meter-state.json` produced by the Context Meter PostToolUse hook; when the state file is absent or stale, it reads `N/A`.
 
 **For each domain (in wave order), run the domain task-dispatcher:**
 
@@ -753,9 +765,7 @@ If it DOES exist AND this domain touched UI files — spawn the **Design Verific
 
 ⚙ [opus] Design Verification → visual comparison for domain {domain-name}
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the Design Verification spawn with `captureSpawn`:**
 
 Resolve the templated prompt path first so the orchestrator never holds the full ~3500-token verification protocol in its own context:
 
@@ -764,23 +774,35 @@ DV_PROMPT="$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t/templates/prompts/design-v
 [ -f "$DV_PROMPT" ] || DV_PROMPT="templates/prompts/design-verify-subagent.md"
 ```
 
-Then spawn the subagent with this short prompt — `spawnType: 'validation'` (always headless, `--watch` ignored):
-
-```
-Task subagent (spawnType: validation, general-purpose, model: opus):
-"You are the Design Verification Agent. Read $DV_PROMPT and follow it exactly.
-Do not deviate from that protocol. Context for this run:
-  - domain: {domain-name}
-  - design contract: .gsd-t/contracts/design-contract.md
-  - files modified by this domain: {list}
-Report back the verdict, match count, breakpoints verified, deviation count
-and summary, and the full comparison table per the protocol's Step 7."
-```
-
-After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs'); 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-execute | Design Verify | opus | {DURATION}s | {VERDICT} — {MATCH}/{TOTAL} elements for {domain-name} | | | {CTX_PCT} |`
+Then spawn through `captureSpawn` — `spawnType: 'validation'` (always headless, `--watch` ignored):
+
+```
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-execute',
+    step: 'Design Verify',
+    model: 'opus',
+    description: 'visual comparison for domain {domain-name}',
+    projectDir: '.',
+    domain: '{domain-name}',
+    task: '-',
+    notes: '{VERDICT} — {MATCH}/{TOTAL} elements',
+    spawnFn: async () => { /* Task subagent (spawnType: validation, general-purpose, model: opus):
+      'You are the Design Verification Agent. Read $DV_PROMPT and follow it exactly.
+      Do not deviate from that protocol. Context for this run:
+        - domain: {domain-name}
+        - design contract: .gsd-t/contracts/design-contract.md
+        - files modified by this domain: {list}
+      Report back the verdict, match count, breakpoints verified, deviation count
+      and summary, and the full comparison table per the protocol's Step 7.' */ },
+  });
+})();
+"
+```
+
+`captureSpawn` parses `result.usage` and appends a row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 **Artifact Gate (MANDATORY):**
 After the Design Verification Agent returns, check `.gsd-t/contracts/design-contract.md`:
@@ -809,9 +831,7 @@ After all tasks in the CURRENT DOMAIN pass their tests, spawn an adversarial Red
 
 ⚙ [opus] Red Team → adversarial validation for domain {domain-name}
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the Red Team spawn with `captureSpawn`:**
 
 Resolve the templated prompt path so the orchestrator never holds the full ~3500-token Red Team protocol in its own context:
 
@@ -820,24 +840,36 @@ RT_PROMPT="$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t/templates/prompts/red-team
 [ -f "$RT_PROMPT" ] || RT_PROMPT="templates/prompts/red-team-subagent.md"
 ```
 
-Then spawn the subagent with this short prompt — `spawnType: 'validation'` (always headless, `--watch` ignored):
-
-```
-Task subagent (spawnType: validation, general-purpose, model: opus):
-"You are a Red Team QA adversary. Read $RT_PROMPT and follow it exactly.
-Do not deviate from that protocol. Context for this run:
-  - domain: {domain-name}
-  - files modified by this domain: {list}
-  - tasks just completed: {task-id list}
-Report back the verdict (FAIL or GRUDGING PASS), bugs found by severity,
-attack categories exhausted, and the path to the written
-.gsd-t/red-team-report.md."
-```
-
-After subagent returns — run via Bash:
-`T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START)) && CTX_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs'); 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-execute | Red Team | opus | {DURATION}s | {VERDICT} — {N} bugs found in {domain-name} | | | {CTX_PCT} |`
+Then spawn through `captureSpawn` — `spawnType: 'validation'` (always headless, `--watch` ignored):
+
+```
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-execute',
+    step: 'Red Team',
+    model: 'opus',
+    description: 'adversarial validation for domain {domain-name}',
+    projectDir: '.',
+    domain: '{domain-name}',
+    task: '-',
+    notes: '{VERDICT} — {N} bugs found',
+    spawnFn: async () => { /* Task subagent (spawnType: validation, general-purpose, model: opus):
+      'You are a Red Team QA adversary. Read $RT_PROMPT and follow it exactly.
+      Do not deviate from that protocol. Context for this run:
+        - domain: {domain-name}
+        - files modified by this domain: {list}
+        - tasks just completed: {task-id list}
+      Report back the verdict (FAIL or GRUDGING PASS), bugs found by severity,
+      attack categories exhausted, and the path to the written
+      .gsd-t/red-team-report.md.' */ },
+  });
+})();
+"
+```
+
+`captureSpawn` parses `result.usage` and appends a row to `.gsd-t/token-log.md`. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 **If Red Team VERDICT is FAIL:**
 1. Fix all CRITICAL and HIGH bugs immediately (up to 2 fix attempts per bug)

package/commands/gsd-t-integrate.md

@@ -209,13 +209,26 @@ After all scripted tests pass:
 Note: Exploratory findings do NOT count against the scripted test pass/fail ratio."
 ```
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-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 | Ctx% |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-integrate | Step 5 | haiku | {DURATION}s | {pass/fail}, {N} boundaries tested | | | {CTX_PCT} |`
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the Step 5 validation spawn with `captureSpawn`:**
+
+```
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-integrate',
+    step: 'Step 5',
+    model: 'haiku',
+    description: 'cross-boundary integration QA',
+    projectDir: '.',
+    notes: '{pass/fail}, {N} boundaries tested',
+    spawnFn: async () => { /* Task validation subagent call */ },
+  });
+})();
+"
+```
+
+`captureSpawn` writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 If QA found issues, append each to `.gsd-t/qa-issues.md` (create with header `| Date | Command | Step | Model | Duration(s) | Severity | Finding |` if missing):
 `| {DT_START} | gsd-t-integrate | Step 5 | haiku | {DURATION}s | {severity} | {finding} |`
 
@@ -270,22 +283,36 @@ After integration tests pass, spawn an adversarial Red Team agent on the integra
 ⚙ [opus] Red Team → adversarial validation of integrated system
 
 Resolve the templated prompt path via Bash:
-```
+```bash
 RT_PROMPT="$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t/templates/prompts/red-team-subagent.md"
 [ -f "$RT_PROMPT" ] || RT_PROMPT="templates/prompts/red-team-subagent.md"
-T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")
 ```
 
-Spawn Task subagent (spawnType: validation, general-purpose, model: opus) — always headless, `--watch` ignored:
-> "Read `$RT_PROMPT` and follow it. Context: cross-domain integration run. **Additional category for this run: Cross-Domain Boundaries** — test data flow across every domain boundary; does data arriving from domain A get validated by domain B; what happens when A sends malformed data that passed A's own validation. Write findings to `.gsd-t/red-team-report.md`."
+Then spawn through `captureSpawn` — `spawnType: 'validation'` (always headless, `--watch` ignored):
 
-After subagent returns — run via Bash:
 ```
-T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))
-CTX_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs'); process.stdout.write(String(tb.getSessionStatus('.').pct))}catch(_){process.stdout.write('N/A')}")
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-integrate',
+    step: 'Red Team',
+    model: 'opus',
+    description: 'cross-domain adversarial validation',
+    projectDir: '.',
+    notes: '{VERDICT} — {N} bugs found',
+    spawnFn: async () => { /* Task subagent (spawnType: validation, general-purpose, model: opus):
+      'Read \$RT_PROMPT and follow it. Context: cross-domain integration run.
+      Additional category for this run: Cross-Domain Boundaries — test data flow across every
+      domain boundary; does data arriving from domain A get validated by domain B; what happens
+      when A sends malformed data that passed A own validation.
+      Write findings to .gsd-t/red-team-report.md.' */ },
+  });
+})();
+"
 ```
-Append to `.gsd-t/token-log.md`:
-`| {DT_START} | {DT_END} | gsd-t-integrate | Red Team | opus | {DURATION}s | {VERDICT} — {N} bugs found | | | {CTX_PCT} |`
+
+`captureSpawn` writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 **If FAIL:** fix CRITICAL/HIGH bugs (≤2 cycles) → re-run. Persistent bugs → `.gsd-t/deferred-items.md`.
 **If GRUDGING PASS:** proceed to doc-ripple.

package/commands/gsd-t-plan.md

@@ -415,13 +415,26 @@ Check:
 Report: PASS (all checks pass) or FAIL with specific gaps listed."
 ```
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-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)) && CTX_PCT=$(node -e "const tb=require('./bin/token-budget.cjs'); 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} |`
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the validation spawn with `captureSpawn`:**
+
+```
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-plan',
+    step: 'Step 7',
+    model: 'haiku',
+    description: 'plan validation, iteration {N}',
+    projectDir: '.',
+    notes: '{PASS/FAIL}, iteration {N}',
+    spawnFn: async () => { /* Task validation subagent call */ },
+  });
+})();
+"
+```
+
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header (Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`).
 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

@@ -10,22 +10,29 @@ To give PRD generation a fresh context window:
 
 **If you are the orchestrating agent** (you received the slash command directly):
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the PRD subagent spawn with `captureSpawn`:**
 
-Spawn a fresh subagent using the Task tool:
 ```
-subagent_type: general-purpose
-prompt: "You are running gsd-t-prd for this request: {$ARGUMENTS}
-Working directory: {current project root}
-Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-prd starting at Step 1."
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-prd',
+    step: 'Step 0',
+    model: 'sonnet',
+    description: 'prd: {topic summary}',
+    projectDir: '.',
+    notes: 'prd: {topic summary}',
+    spawnFn: async () => { /* Task subagent (subagent_type: general-purpose):
+      'You are running gsd-t-prd for this request: {\$ARGUMENTS}
+      Working directory: {current project root}
+      Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-prd starting at Step 1.' */ },
+  });
+})();
+"
 ```
 
-After subagent returns — run via Bash:
-`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.cjs'); 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} |`
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 Relay the subagent's summary to the user. **Do not execute Steps 1–6 yourself.**
 

package/commands/gsd-t-quick.md

@@ -34,10 +34,6 @@ To give this task a fresh context window and prevent compaction during consecuti
 
 **If you are the orchestrating agent** (you received the slash command directly):
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
-
 **Token Budget Check (before spawning subagent):**
 
 Run via Bash:
@@ -109,20 +105,32 @@ Violations are task failures, not warnings.
 
 If STACK_RULES is empty (no templates/stacks/ dir or no matches), skip silently.
 
-Spawn a fresh subagent using the Task tool — `spawnType: 'primary'` (respects `--watch`: headless by default, in-context when `WATCH_FLAG=true`):
+Spawn a fresh subagent via `captureSpawn` — `spawnType: 'primary'` (respects `--watch`: headless by default, in-context when `WATCH_FLAG=true`):
+
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the primary subagent spawn with `captureSpawn`:**
+
 ```
-subagent_type: general-purpose
-spawnType: primary
-prompt: "You are running gsd-t-quick for this request: {$ARGUMENTS}
-Working directory: {current project root}
-Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-quick starting at Step 1.
-{STACK_RULES block — if non-empty, append the ## Stack Rules section defined above; omit if empty}"
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-quick',
+    step: 'Step 0',
+    model: 'sonnet',
+    description: 'quick: {task summary}',
+    projectDir: '.',
+    notes: 'quick: {task summary}',
+    spawnFn: async () => { /* Task subagent (general-purpose, spawnType: primary, model: sonnet):
+      'You are running gsd-t-quick for this request: {\$ARGUMENTS}
+      Working directory: {current project root}
+      Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-quick starting at Step 1.
+      {STACK_RULES block — if non-empty, append the ## Stack Rules section defined above; omit if empty}' */ },
+  });
+})();
+"
 ```
 
-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 | Ctx% |` if missing):
-`| {DT_START} | {DT_END} | gsd-t-quick | Step 0 | sonnet | {DURATION}s | quick: {task summary} | {CTX_PCT} |`
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 Relay the subagent's summary to the user. **Do not execute Steps 1–5 yourself.**
 
@@ -305,11 +313,30 @@ After tests pass, check if `.gsd-t/contracts/design-contract.md` exists. If it d
 
 If it DOES exist and this task involved UI changes — spawn the Design Verification Agent. This agent's ONLY job is to open a browser, compare the built frontend against the original design, and produce a structured comparison table. It writes NO feature code.
 
-⚙ [{model}] Design Verification → visual comparison of built frontend vs design
+⚙ [opus] Design Verification → visual comparison of built frontend vs design
+
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the Design Verification subagent spawn with `captureSpawn`:**
+
+```
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-quick',
+    step: 'Design Verify',
+    model: 'opus',
+    description: 'visual comparison of built frontend vs design',
+    projectDir: '.',
+    notes: 'design-verify',
+    spawnFn: async () => { /* Task subagent (spawnType: validation, general-purpose, model: opus) — body below */ },
+  });
+})();
+"
+```
+
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
-**OBSERVABILITY LOGGING (MANDATORY):**
-Before spawning — run via Bash:
-`T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")`
+**Design Verification subagent prompt body (passed to `spawnFn`):**
 
 ```
 Task subagent (spawnType: validation, general-purpose, model: opus):
@@ -366,8 +393,6 @@ cannot be redeemed by visual polish.
 10. Report: DESIGN VERIFIED | DESIGN DEVIATIONS FOUND ({count})"
 ```
 
-After subagent returns — run observability Bash and append to token-log.md.
-
 **Artifact Gate:** Read `.gsd-t/contracts/design-contract.md` — if no `## Verification Status` section with a comparison table exists, re-spawn (1 retry).
 
 **If deviations found:** Fix them (max 2 cycles), re-verify. If persistent, log to `.gsd-t/deferred-items.md`.
@@ -386,19 +411,29 @@ Resolve the templated prompt path via Bash (same pattern as execute.md):
 ```
 RT_PROMPT="$(npm root -g 2>/dev/null)/@tekyzinc/gsd-t/templates/prompts/red-team-subagent.md"
 [ -f "$RT_PROMPT" ] || RT_PROMPT="templates/prompts/red-team-subagent.md"
-T_START=$(date +%s) && DT_START=$(date +"%Y-%m-%d %H:%M")
 ```
 
-Spawn Task subagent (spawnType: validation, general-purpose, model: opus) — always headless, `--watch` ignored:
-> "Read `$RT_PROMPT` and follow it. Context for this run: quick task — adversarial validation of the code just changed. Write findings to `.gsd-t/red-team-report.md`."
+**OBSERVABILITY LOGGING (MANDATORY) — wrap the Red Team subagent spawn with `captureSpawn`:**
 
-After subagent returns — run via Bash:
 ```
-T_END=$(date +%s) && DT_END=$(date +"%Y-%m-%d %H:%M") && DURATION=$((T_END-T_START))
-CTX_PCT=$(node -e "try{const tb=require('./bin/token-budget.cjs'); process.stdout.write(String(tb.getSessionStatus('.').pct))}catch(_){process.stdout.write('N/A')}")
+node -e "
+const { captureSpawn } = require('./bin/gsd-t-token-capture.cjs');
+(async () => {
+  await captureSpawn({
+    command: 'gsd-t-quick',
+    step: 'Red Team',
+    model: 'opus',
+    description: 'adversarial validation of quick task',
+    projectDir: '.',
+    notes: '{VERDICT} — {N} bugs found',
+    spawnFn: async () => { /* Task subagent (spawnType: validation, general-purpose, model: opus) — always headless, --watch ignored:
+      'Read \$RT_PROMPT and follow it. Context for this run: quick task — adversarial validation of the code just changed. Write findings to .gsd-t/red-team-report.md.' */ },
+  });
+})();
+"
 ```
-Append to `.gsd-t/token-log.md`:
-`| {DT_START} | {DT_END} | gsd-t-quick | Red Team | opus | {DURATION}s | {VERDICT} — {N} bugs found | | | {CTX_PCT} |`
+
+`captureSpawn` parses `result.usage` and writes the row to `.gsd-t/token-log.md` under the canonical header. Tokens column renders as `in=N out=N cr=N cc=N $X.XX` or `—`, never `N/A`.
 
 **If Red Team VERDICT is FAIL:**
 1. Fix all CRITICAL and HIGH bugs (up to 2 fix cycles)

package/commands/gsd-t-resume.md

@@ -17,12 +17,26 @@ 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:
+2. **File exists**: Run the liveness + fingerprint check via the helper:
    ```bash
-   kill -0 <pid> 2>/dev/null && echo "alive" || echo "dead"
+   node -e "
+   const { readPidFile, verifyFingerprint } = require('./bin/supervisor-pid-fingerprint.cjs');
+   const entry = readPidFile(process.cwd());
+   if (!entry) { console.log('no_pid_file'); process.exit(0); }
+   try { process.kill(entry.pid, 0); } catch { console.log('dead:' + entry.pid); process.exit(0); }
+   const r = verifyFingerprint(entry, process.cwd());
+   if (r.ok === true)  console.log('alive_verified:' + entry.pid);
+   else if (r.ok === null) console.log('alive_legacy_pid:' + entry.pid);
+   else console.log('alive_but_stale:' + entry.pid + ':' + r.reason);
+   "
    ```
-   - **"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.
+
+   Five possible outcomes:
+   - `no_pid_file` → no supervisor running, fall through to Step 0.1.
+   - `dead:<pid>` → supervisor exited (cleanly or crashed). PID file stale. Log: `[resume] supervisor PID <pid> no longer alive — stale PID file, falling through to normal resume`. Fall through.
+   - `alive_verified:<pid>` → our supervisor, same project, ps confirms command line. Proceed to step 3 (AUTO-REATTACH).
+   - `alive_legacy_pid:<pid>` → PID file is legacy bare-integer form; we can only confirm "some process with this PID exists." Log a one-line warning: `[resume] supervisor PID <pid> file uses legacy bare-integer form — next supervisor launch will upgrade to JSON fingerprint`. Proceed to step 3 as if verified (preserves behavior for any already-running legacy supervisors).
+   - `alive_but_stale:<pid>:<reason>` → process alive but **not** our supervisor (different project recycled PID, or non-gsd-t process). Log: `[resume] supervisor PID <pid> no longer identifies our supervisor (reason: <reason>) — treating as stale, falling through to normal resume`. Fall through to Step 0.1.
 
 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).
@@ -74,6 +88,39 @@ This prevents the child side of a headless spawn from reading a partial continue
 
 ---
 
+## Step 0.3: Orchestrator Run Recovery (M40 D6)
+
+```bash
+node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-id "${GSD_T_PARENT_AGENT_ID:-null}" --command gsd-t-resume --step 0 --step-label ".3: Orchestrator Run Recovery (M40 D6)" 2>/dev/null || true
+```
+
+If an orchestrator run was interrupted (crash, SIGINT, kill, parent timeout), `.gsd-t/orchestrator/state.json` will still exist with a non-terminal `status`. Detect this and offer to resume it via the deterministic `--resume` path rather than attempting prose-driven reconciliation:
+
+```bash
+node -e "
+const fs = require('fs');
+const path = require('path');
+const fp = path.join('.gsd-t', 'orchestrator', 'state.json');
+if (!fs.existsSync(fp)) process.exit(0);
+let s; try { s = JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { process.exit(0); }
+const TERMINAL = new Set(['done','failed','stopped','interrupted','completed']);
+if (!s || TERMINAL.has(s.status)) process.exit(0);
+const running = Object.entries(s.tasks || {}).filter(([,t]) => t && t.status === 'running');
+console.error('▶ Orchestrator run still in-flight (status=' + (s.status||'?') + ', ' + running.length + ' running task(s))');
+console.error('  Resume via: node bin/gsd-t-orchestrator.js orchestrate --milestone ' + (s.milestone || '<id>') + ' --resume');
+console.error('  This calls recoverRunState() to reconcile in-flight tasks (ok/ambiguous/failed) before continuing.');
+" || true
+```
+
+Rules:
+- **State absent or terminal** → nothing to do; fall through.
+- **Non-terminal** → surface the recovery hint and, at Level 3, auto-invoke the orchestrator with `--resume` when the current milestone matches `state.milestone`. Ambiguous tasks (commit but no progress entry) are flagged in the orchestrator output and require operator triage — do **not** silently claim them done.
+- The recovery algorithm, archiving, and ambiguous handling are covered by unit tests in `test/m40-recovery.test.js` and implemented in `bin/gsd-t-orchestrator-recover.cjs`.
+
+Contract: stream-json-sink v1.1.0, wave-join v1.x, completion-signal v1.x.
+
+---
+
 ## Step 0.5: Headless Read-Back Banner (MANDATORY)
 
 ```bash