@tekyzinc/gsd-t 3.18.13 → 3.19.0

package/commands/gsd-t-integrate.md

@@ -103,25 +103,19 @@ If rolled-back domains exist, report them to the user (or if Level 3: log to `.g
 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-integrate --step 3 --step-label "Wire Integration Points" 2>/dev/null || true
 ```
 
-### Optional — Parallel Dispatch (M44)
+### Parallel Dispatch (MANDATORY — single instrument)
 
-When integration work spans **more than one domain simultaneously** (i.e., the integration-points.md list contains independent integration tasks across multiple domains), the ready batch may be dispatched via `gsd-t parallel` instead of the sequential task-level dispatch below. When integration touches only one domain (single-domain wiring), the conditional is a no-op and the existing sequential path runs unchanged.
-
-- **Conditional check** — only triggers when integrating > 1 domain AND the integration tasks pass D4 depgraph + D5 file-disjointness + D6 economics gates. Otherwise the block is a no-op.
-- **Mode auto-detection** — mode is auto-detected from `GSD_T_UNATTENDED=1` by `bin/gsd-t-parallel.cjs`. Do not hardcode `--mode` in this command file.
-- **Fallback** — any gate veto (unmet deps, overlapping write targets, unprovable disjointness) removes the affected tasks from the parallel batch; they fall back to the sequential task-dispatcher silently. No user prompt.
-- **Observability** — D2 owns the spawn observability. The parallel path writes the same `.gsd-t/events/YYYY-MM-DD.jsonl` records (`gate_veto`, `parallelism_reduced`, `task_split`) and `.gsd-t/token-log.md` rows as the sequential path via `captureSpawn`. D3 adds no new spawn machinery.
-- **Zero-compaction invariant (unattended)** — for `[unattended]` runs, D2 enforces zero-compaction by splitting integration tasks when D6 estimates > 60% per-worker CW.
-- **In-session invariant** — NEVER interrupts the user with a pause/resume prompt. If headroom is tight, D2 reduces the worker count (floor N=1) and emits `parallelism_reduced`. If all gates fail, falls back to sequential silently. No opt-out flag exists (consistent with M43 D4: `--in-session` / `--headless` were never shipped).
-
-Example (mode auto-detected from env):
+Delegate to `gsd-t parallel --command` — do NOT re-implement probe-and-branch logic here (M44 D9 Step 3: "create 1 instrument that accomplishes this instead of implementing it in all the commands").
 
 ```bash
-gsd-t parallel --milestone {milestone} --dry-run   # preview plan, no spawn
-gsd-t parallel --milestone {milestone}             # live dispatch
+node bin/gsd-t.js parallel --milestone {milestone} --command gsd-t-integrate && exit 0 || true
+# Exit 0  → multi-domain integration; N detached children handle disjoint subsets.
+# Exit 2+ → single-domain wiring. Fall through to sequential dispatch below.
 ```
 
-Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0.
+`runDispatch` owns the D4/D5/D6 gates + disjoint task-id partitioning + `autoSpawnHeadless()` fan-out. Mode auto-detects from `GSD_T_UNATTENDED=1`. No user prompt. Parallel-when-safe + headless-when-possible are both the default.
+
+Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0; `.gsd-t/contracts/headless-default-contract.md` v2.0.0.
 
 **Stack Rules Detection (before spawning subagent):**
 Run via Bash to detect project stack and collect matching rules:

package/commands/gsd-t-quick.md

@@ -184,24 +184,20 @@ Proceed.
 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-quick --step 3 --step-label "Execute" 2>/dev/null || true
 ```
 
-### Optional — Parallel Dispatch (M44, lightweight · conditional-only)
+### Parallel Dispatch (MANDATORY — single instrument)
 
-**This block is a no-op for the typical quick invocation.** `gsd-t-quick` is designed for single-focus work; forcing parallel on every quick invocation would add gate overhead without benefit.
+Delegate to `gsd-t parallel --command` — do NOT re-implement probe-and-branch logic here (M44 D9 Step 3: "create 1 instrument that accomplishes this instead of implementing it in all the commands").
 
-**Trigger conditions (BOTH must hold)**:
-1. `.gsd-t/domains/` contains more than one pending task, AND
-2. All three gates (D4 depgraph + D5 file-disjointness + D6 economics) pass for the candidate batch.
-
-**If either condition fails** — and that includes the common case of a single-task quick invocation — skip this block entirely. The sequential single-subagent path in Step 0.1 remains unchanged.
-
-**If BOTH conditions hold** — dispatch the ready batch via `gsd-t parallel` (mode auto-detected from `GSD_T_UNATTENDED=1`; do not hardcode `--mode`):
+```bash
+node bin/gsd-t.js parallel --command gsd-t-quick && exit 0 || true
+# Exit 0  → fan-out happened; detached children handle the work.
+# Exit 2+ → sequential (N<2 or quick is single-task — the common case).
+#           Fall through to the single-subagent path in Step 0.1.
+```
 
-- Fallback is silent — any gate veto drops the affected tasks back to the sequential quick path.
-- D2 owns the spawn observability; the parallel path writes the same `.gsd-t/events/YYYY-MM-DD.jsonl` records and `.gsd-t/token-log.md` rows via `captureSpawn`. D3 adds no new spawn machinery.
-- `[unattended]` — D2 enforces the zero-compaction contract by splitting tasks when D6 estimates > 60% per-worker CW.
-- `[in-session]` — NEVER interrupts the user with a pause/resume prompt. If headroom is tight, D2 reduces the worker count (floor N=1). No opt-out flag exists (consistent with M43 D4: `--in-session` / `--headless` were never shipped).
+`runDispatch` inside `bin/gsd-t-parallel.cjs` owns the probe + D4/D5/D6 gate math + disjoint task-id partitioning + `autoSpawnHeadless()` fan-out. Mode auto-detects from `GSD_T_UNATTENDED=1`. No user prompt. Parallel-when-safe + headless-when-possible are both the default (per headless-default-contract v2.0.0).
 
-Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0.
+Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0; `.gsd-t/contracts/headless-default-contract.md` v2.0.0.
 
 ### Deviation Rules
 

package/commands/gsd-t-resume.md

@@ -12,6 +12,38 @@ node scripts/gsd-t-watch-state.js advance --agent-id "$GSD_T_AGENT_ID" --parent-
 
 **Worker bypass**: If the environment variable `GSD_T_UNATTENDED_WORKER=1` is set, this resume is being invoked by the unattended supervisor as a worker iteration. **SKIP this entire Step 0** — do NOT check for supervisor.pid, do NOT auto-reattach, do NOT schedule a watch tick. Fall through directly to Step 0.1. The worker's job is to do actual work, not watch itself.
 
+### Worker Sub-Dispatch (M46-D2)
+
+When the worker bypass above applies (`GSD_T_UNATTENDED_WORKER=1` is set), the worker performs an **additional deterministic check** BEFORE falling through to Step 0.1. This lets a worker with multiple file-disjoint tasks fan out its own work as concurrent headless sub-workers, rather than running its task set serially.
+
+Decision rule (all conditions must hold):
+- `GSD_T_WORKER_TASK_IDS` is present in the environment (the supervisor declared the task set for this worker).
+- The worker has **more than one task** to run (`tasks.length > 1`).
+- The supervisor has exported the worker's task list to a JSON file on disk (the tasks file path is provided via env or the worker's continue-here block).
+- The tasks are pairwise **file-disjoint** per `.gsd-t/contracts/file-disjointness-rules.md` (the dispatcher re-verifies this internally; the worker does not need to pre-check).
+
+If all conditions hold, the worker invokes:
+
+```bash
+node bin/gsd-t-worker-dispatch.cjs \
+  --parent-session "$GSD_T_PARENT_AGENT_ID" \
+  --tasks <path-to-tasks-json>
+```
+
+Interpret the exit code as follows:
+- **Exit 0** → every sub-worker succeeded. Aggregate the stdout JSON result (which contains `{parallel, taskResults, wallClockMs, reason}`) and report completion of the worker iteration with all taskIds marked done. Do NOT fall through to the serial pre-M46 path.
+- **Exit 1** → at least one sub-worker failed. Report mixed status for the worker iteration, listing the failed `taskId`s from the aggregated `taskResults` (any entry with a non-zero, non-null `exitCode`). The sibling sub-workers' successful results still count — do NOT re-run them. Do NOT fall through to the serial path.
+- **Exit 2** → precondition failure (missing `--parent-session`, unreadable or malformed tasks JSON). Log the stderr reason and **fall through to the current (pre-M46) worker behavior** — the serial path that existed before D2.
+
+Skip sub-dispatch and fall through to the current behavior when:
+- `tasks.length <= 1` (single-task or empty workloads have nothing to parallelize — the dispatcher itself returns early with `reason: 'single-task'` / `'no-tasks'`, but the worker can short-circuit without spawning the adapter at all).
+- Tasks are not file-disjoint per the disjointness contract (the dispatcher will return `parallel: false, reason: 'file-overlap'`; the worker treats this identically to the serial fallback).
+- The tasks file was not written by the supervisor (no sub-dispatch surface available this iteration).
+
+**Rationale** — Per `.gsd-t/contracts/headless-default-contract.md` §Worker Sub-Dispatch (v2.1.0), this hand-off is the third parallelism layer (iter-parallel → supervisor fan-out → worker sub-dispatch). It is a deterministic, file-disjointness-gated consumer of the M44-verified `runDispatch` instrument — not a modification of it. The in-session dispatch path is byte-identical; this sub-section only adds a new invocation site on the unattended worker leg.
+
+---
+
 Check whether an unattended supervisor is actively running for this project:
 
 1. Check if `.gsd-t/.unattended/supervisor.pid` exists.

package/commands/gsd-t-status.md

@@ -19,6 +19,16 @@ 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.0: Date + Version Banner (MANDATORY)
+
+Before anything else, print the current date and GSD-T version so a multi-day-old session is immediately dated when the user reads the output:
+
+```bash
+node -e "const{dateStamp}=require('./scripts/gsd-t-update-check.js');const fs=require('fs'),os=require('os'),path=require('path');const v=(()=>{try{return fs.readFileSync(path.join(os.homedir(),'.claude/.gsd-t-version'),'utf8').trim()}catch{return 'unknown'}})();process.stdout.write(dateStamp()+'GSD-T v'+v+' — CURRENT\n')" 2>/dev/null || true
+```
+
+Format: `Tue: Mar 26, 2026,  GSD-T v3.19.00 — CURRENT`. Currency claim is best-effort — the canonical authority is the `~/.claude/.gsd-t-update-check` cache consulted by the SessionStart hook; status mode trusts the installed version label.
+
 ## 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:

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

@@ -207,7 +207,64 @@ out('DOMAIN_SUMMARY', domainSummary.join(' | '));
 
 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:
+The supervisor has finalized cleanly and removed its own PID file.
+
+### Step 3a: Reconciliation probe
+
+Before emitting a report, check whether the supervisor's final `status` agrees with the on-disk milestone evidence. A `status=failed` with a **fresh matching milestone archive** is the M45-class false-failed-marker pathology: the worker completed the milestone (including the archive rename under `.gsd-t/milestones/`) but a polarity-unsound exit-code matcher mapped the worker's clean exit to `1`, which the supervisor then finalized as `status=failed`.
+
+```bash
+node -e "
+const fs = require('fs');
+const path = require('path');
+const state = JSON.parse(fs.readFileSync('.gsd-t/.unattended/state.json', 'utf8'));
+const milestone = (state.milestone || '').toLowerCase();
+let reconciled = false;
+if (state.status === 'failed' && milestone) {
+  // Look for a fresh archive directory matching the milestone slug.
+  // Pattern: .gsd-t/milestones/{slug}-YYYY-MM-DD where slug contains the
+  // milestone identifier (e.g. 'M45' → 'm45-conversation-stream-observability-2026-04-23').
+  try {
+    const archives = fs.readdirSync('.gsd-t/milestones')
+      .filter(n => n.toLowerCase().includes(milestone));
+    if (archives.length > 0) {
+      // Check the most recent archive's mtime is within the supervisor's run window.
+      const recent = archives
+        .map(n => ({ n, mtime: fs.statSync(path.join('.gsd-t/milestones', n)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime)[0];
+      const runStart = Date.parse(state.startedAt || 0);
+      if (recent && recent.mtime >= runStart) {
+        reconciled = true;
+        console.log('RECONCILED=true');
+        console.log('RECONCILED_ARCHIVE=' + recent.n);
+      }
+    }
+  } catch (_) {}
+}
+if (!reconciled) console.log('RECONCILED=false');
+"
+```
+
+### Step 3b: Render reconciled or raw report
+
+If `RECONCILED=true` AND `STATUS=failed`, the archive is the authority — render the reconciled success report:
+
+```
+✅  Unattended supervisor finalized — milestone completed (auto-reconciled).
+
+   Session:       {SESSION}
+   Milestone:     {MILESTONE} — archived as {RECONCILED_ARCHIVE}
+   Supervisor flag: status=failed (not trusted — archive present)
+   Iterations:    {ITER} / {MAX_ITER}
+   Total elapsed: {Hh Mm — formatted from ELAPSED_MS}
+   Log:           {LOG_PATH}
+   State:         .gsd-t/.unattended/state.json
+
+   Note: the worker completed the milestone, but a polarity-unsound exit-code
+   matcher mapped clean exit → failed. Treat the archive as the source of truth.
+```
+
+Otherwise (no reconciliation — `STATUS` is genuinely terminal `done`, `failed` without archive, or `stopped`), render the raw final report:
 
 ```
 ✅  Unattended supervisor finalized cleanly.

package/commands/gsd-t-visualize.md

@@ -55,49 +55,52 @@ If `.gsd-t/graph/index.json` exists, the dashboard can render entity-relationshi
 
 If `$ARGUMENTS` contains "stop", skip to **Step 5**. Otherwise continue to Step 3.
 
-## Step 3: Check if Server is Already Running
+## Step 3: Resolve Port + Check if Server is Already Running
+
+The dashboard server binds to a **per-project hashed port** in `[7433, 7532]` (see `projectScopedDefaultPort` in `gsd-t-dashboard-server.js`). Resolve it once and reuse:
 
-Run via Bash:
 ```bash
+PORT=$(node -e "console.log(require('$HOME/.claude/scripts/gsd-t-dashboard-server.js').resolvePort({ projectDir: process.cwd() }))")
 if [ -f .gsd-t/dashboard.pid ]; then
   PID=$(cat .gsd-t/dashboard.pid)
-  curl -sf http://localhost:7433/ping 2>/dev/null | grep -q '"ok"' && echo "SERVER_RUNNING=true" || echo "SERVER_RUNNING=false"
+  curl -sf http://localhost:$PORT/ping 2>/dev/null | grep -q '"ok"' && echo "SERVER_RUNNING=true" || echo "SERVER_RUNNING=false"
 else
   echo "SERVER_RUNNING=false"
 fi
 ```
 
-If output is `SERVER_RUNNING=true`, skip Step 3a and go directly to Step 4.
+If output is `SERVER_RUNNING=true`, skip Step 3a and go directly to Step 4. Carry `$PORT` forward to subsequent steps.
 
 ### Step 3a: Start Server if Not Running
 
-Run via Bash:
+Run via Bash (reuses `$PORT` from Step 3):
 ```bash
 node ~/.claude/scripts/gsd-t-dashboard-server.js --detach || true
 for i in 1 2 3 4 5; do
-  curl -sf http://localhost:7433/ping 2>/dev/null | grep -q '"ok"' && break
+  curl -sf http://localhost:$PORT/ping 2>/dev/null | grep -q '"ok"' && break
   sleep 1
 done
 ```
 
 ## Step 4: Open Browser
 
-Run via Bash:
+Run via Bash (reuses `$PORT` from Step 3):
 ```bash
-node -e "const {execFileSync}=require('child_process'); const url='http://localhost:7433'; try { if(process.platform==='win32'){execFileSync('cmd',['/c','start','',url],{stdio:'ignore'})}else{execFileSync(process.platform==='darwin'?'open':'xdg-open',[url],{stdio:'ignore'})} } catch(e) { console.error('Could not open browser:', e.message); }" || true
+URL="http://localhost:$PORT"
+node -e "const {execFileSync}=require('child_process'); const url=process.argv[1]; try { if(process.platform==='win32'){execFileSync('cmd',['/c','start','',url],{stdio:'ignore'})}else{execFileSync(process.platform==='darwin'?'open':'xdg-open',[url],{stdio:'ignore'})} } catch(e) { console.error('Could not open browser:', e.message); }" "$URL" || true
 ```
 
-Report to the user: "Dashboard is running at http://localhost:7433 — browser opened."
+Report to the user: "Dashboard is running at $URL — browser opened."
 
 ## Step 5: Stop Handler
 
-Run only when `$ARGUMENTS` contains "stop".
+Run only when `$ARGUMENTS` contains "stop". Resolves the same hashed port used at start:
 
-Run via Bash:
 ```bash
+PORT=$(node -e "console.log(require('$HOME/.claude/scripts/gsd-t-dashboard-server.js').resolvePort({ projectDir: process.cwd() }))")
 if [ -f .gsd-t/dashboard.pid ]; then
   PID=$(cat .gsd-t/dashboard.pid)
-  curl -sf http://localhost:7433/stop 2>/dev/null || kill $PID 2>/dev/null || true
+  curl -sf http://localhost:$PORT/stop 2>/dev/null || kill $PID 2>/dev/null || true
   rm -f .gsd-t/dashboard.pid
   echo "Dashboard server stopped"
 else

package/commands/gsd-t-wave.md

@@ -211,18 +211,9 @@ Spawn agent → `commands/gsd-t-impact.md`
 Spawn agent → `commands/gsd-t-execute.md`
 - This is the heaviest phase. The execute agent uses **task-level dispatch** (fresh-dispatch-contract.md): one Task subagent per task within each domain, each receiving only scope.md + relevant contracts + single task + graph context + up to 5 prior summaries. The execute agent handles domain task-dispatching and QA internally.
 
-##### Optional — Parallel Dispatch (M44)
+##### Parallel Dispatch (M44 D9, single instrument)
 
-The spawned execute agent will itself decide whether to dispatch parallel workers via `gsd-t parallel` (see `commands/gsd-t-execute.md` Step 3 → "Optional — Parallel Dispatch (M44)"). The wave orchestrator does not need to configure this — it is automatic:
-
-- If `.gsd-t/domains/` contains more than one pending task passing D4/D5/D6 gates, the execute agent dispatches via `gsd-t parallel` instead of sequentially.
-- Mode is auto-detected from `GSD_T_UNATTENDED=1` — the wave orchestrator inherits this env from its own spawn. Do not hardcode `--mode`.
-- Fallback is silent: any gate veto, unprovable disjointness, or single-task scope drops back to the sequential execute path without a user prompt.
-- D2 owns the spawn observability; the parallel path writes the same `.gsd-t/events/YYYY-MM-DD.jsonl` records and `.gsd-t/token-log.md` rows as the sequential path via `captureSpawn`. D3 adds no new spawn machinery.
-- `[unattended]` — D2 enforces the zero-compaction contract by splitting tasks when D6 estimates per-worker CW > 60%.
-- `[in-session]` — NEVER interrupts the user with pause/resume. If headroom is tight, D2 reduces the worker count (floor N=1) and emits `parallelism_reduced`.
-
-No wave-orchestrator-level flag exists to opt out; the parallel-vs-sequential decision is owned by the execute agent and the D2 gating math. Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0.
+The spawned execute agent delegates the parallel-vs-sequential decision to the single instrument `gsd-t parallel --command gsd-t-execute` (see `commands/gsd-t-execute.md` → "Parallel Dispatch"). The wave orchestrator does not need to configure this — it is automatic, deterministic, and inherited via `GSD_T_UNATTENDED` env. Contract: `.gsd-t/contracts/wave-join-contract.md` v1.2.0 §Single Instrument.
 
 - **Adaptive replanning**: After each domain completes, the execute agent runs a replan check (per `adaptive-replan-contract.md`). If a completed domain's task summaries reveal new constraints (e.g., deprecated API, wrong column name, incompatible library), the execute agent checks remaining domains' `tasks.md` files for invalidated assumptions and revises them on disk before dispatching the next domain. Maximum 2 replan cycles per execute run — if exceeded, execution pauses for user input. All replan decisions are logged to the Decision Log in `progress.md`. The wave phase summary includes any replan actions taken.
 - **Team/parallel mode**: If the plan defines parallel domains (same wave), the execute agent dispatches each domain teammate with `isolation: "worktree"` (per worktree-isolation-contract.md). Each domain works in an isolated git worktree. After all domains complete, the execute agent runs the Sequential Merge Protocol: merge domain A → test → merge domain B → test. Per-domain rollback if tests fail. Worktrees are cleaned up after all merges complete.

package/docs/architecture.md

@@ -978,6 +978,72 @@ means in-flight.
 `test/m44-d8-dashboard-spawn-plans-endpoint.test.js`,
 `test/m44-d8-transcript-renderer-panel.test.js` — 36 tests total.
 
+## Parallelism Panel (M44 D9, v3.19.0+)
+
+Pure-observer readout answering two questions:
+
+> *Is the orchestrator actually fanning out, or serializing despite parallelism being available?*
+
+> *When this wave finishes, did it hit the parallelism factor D6 estimated?*
+
+Zero added LLM token cost — every number is derived from files the other
+M44 domains already write: D8 spawn-plan files, D4/D5/D6 event rows, and
+D7 `cw_id` columns in `.gsd-t/token-log.md`.
+
+**Module**: `bin/parallelism-report.cjs` —
+`computeParallelismMetrics({projectDir, wave?, now?})` returns the shape
+defined in `.gsd-t/contracts/parallelism-report-contract.md` v1.0.0.
+`buildFullReport(...)` returns a post-mortem markdown string with Summary,
+Per-spawn timeline, Per-gate decisions, Per-worker Gantt, Token cost, and
+Notes sections.
+
+**Data flow**:
+
+```
+  .gsd-t/spawns/*.json  ─┐                     (D8 writer)
+  .gsd-t/events/*.jsonl ─┼─▶  bin/parallelism-report.cjs
+  .gsd-t/domains/*/tasks.md ┤       │
+  .gsd-t/token-log.md   ─┘       (pure I/O — never writes, never spawns)
+                                    │
+                                    ▼
+                    scripts/gsd-t-dashboard-server.js
+                    (5s in-memory cache per wave param)
+                      ├── GET /api/parallelism           → JSON metrics
+                      ├── GET /api/parallelism/report    → markdown
+                      └── POST /api/unattended-stop      → writes sentinel
+                                    │
+                                    ▼
+                    scripts/gsd-t-transcript.html
+                    `<aside class="spawn-panel"> .parallelism-panel`
+                    polls /api/parallelism every 5s
+```
+
+**Color thresholds** (worst-of across five per-signal colors, from contract §color_state):
+
+| Signal | Green | Yellow | Red |
+|--------|-------|--------|-----|
+| activeWorkers / readyTasks | ≥80% | 50–80% | <50% AND >10 min since last spawn |
+| Gate veto rate (D4) | <10% | 10–30% | >30% |
+| parallelism_factor vs. D6 estimate | ≥80% | 50–80% | <50% |
+| Spawn age (any active worker) | <30 min | 30–45 min | >45 min |
+| Time since last `spawn_started` (when ready>0) | <5 min | 5–10 min | >10 min |
+
+Special: `color_state === "dimmed"` when no spawn-plan files exist (idle
+project) — never red.
+
+**Silent-fail invariant**: malformed spawn-plan JSON, corrupt JSONL event
+lines, missing `.gsd-t/domains/`, missing `.gsd-t/token-log.md` — every
+case logs a note to `metrics.notes` / Full Report `## Notes` and continues
+with partial data. Observer must never throw when watching a live system.
+
+**Contract**: `.gsd-t/contracts/parallelism-report-contract.md` v1.0.0.
+
+**Tests**: `test/m44-d9-parallelism.test.js` — 16 tests covering metric
+shape, parallelism_factor math (live 1-worker, 4-worker, mixed-duration,
+post-wave), color-state thresholds, silent-fail on malformed inputs, Full
+Report markdown sections, and `/api/parallelism*` endpoint shape + 5s
+cache behaviour.
+
 ## Planned Architecture Changes (M23-M24)
 
 **M23: Headless Mode**
@@ -993,3 +1059,19 @@ means in-flight.
 2. **Four-file synchronization**: Any command change requires updating README, GSD-T-README, CLAUDE-global template, and gsd-t-help. Manual process — no automated validation.
 3. **Pre-Commit Gate unenforced**: Mental checklist in CLAUDE.md, not a git hook or CI check.
 4. **Progress.md Decision Log growth**: Unbounded append-only log. May need periodic archival strategy for long-lived projects.
+
+## M46 Worker Sub-Dispatch
+
+`bin/gsd-t-worker-dispatch.cjs` lets an unattended supervisor worker iteration fan out its own file-disjoint tasks as concurrent sub-workers. The module's `dispatchWorkerTasks({projectDir, parentSessionId, tasks, maxParallel})` entry point gates on three conditions: `process.env.GSD_T_UNATTENDED_WORKER === '1'` (caller runs inside a supervisor-launched worker child), `tasks.length > 1`, and pairwise file-disjointness across the task set's `files` arrays. When all three hold, it emits a spawn-plan frame with `kind: 'unattended-worker-sub'` and delegates execution to `bin/gsd-t-parallel.cjs::runDispatch` — the same M44-verified instrument the in-session planner uses. When any condition fails it returns `{parallel: false, reason}` and the worker falls through to its existing serial path.
+
+Architecturally the module is a **new consumer** of `runDispatch`, not a modifier. The in-session dispatch call site is byte-identical post-D2; the worker adapter is a sibling caller. This completes the three-layer unattended parallelism model: supervisor iterations run in parallel (M46 D1 iter-parallel), each iteration's worker may sub-dispatch its disjoint tasks (M46 D2), and within the orchestrator the `/gsd` router still fans out via `runDispatch` for in-session action turns (M44). All three layers share one dispatch instrument and one disjointness predicate.
+
+Contract: `.gsd-t/contracts/headless-default-contract.md` v2.1.0 §Worker Sub-Dispatch.
+
+## M46 Iteration-Parallel Supervisor
+
+`bin/gsd-t-unattended.cjs` ships four helpers that scaffold iteration-level parallelism in the supervisor main loop: `_runOneIter(state, opts)` is the extract-method of the single-iter body (one `claude -p` dispatch, heartbeat bookkeeping, state mutation) and returns an `IterResult` envelope; `_computeIterBatchSize(state, opts)` is the mode-safety gate that returns `1` when `state.status === "verify-needed"`, when `state.milestoneBoundary === true`, when `state.status === "complete-milestone"`, or when the caller did not pass `opts.maxIterParallel` as a number, and otherwise returns `min(opts.maxIterParallel, remainingIters, 8)` with a hard ceiling of 8; `_runIterParallel(state, opts, iterFn, batchSize)` is the concurrent driver — it builds `batchSize` promises, awaits them with `Promise.allSettled` so a rejected slice does not cancel siblings, and maps rejections into `{status: "error", tasksDone: [], verifyNeeded: false, artifacts: [], error}` envelopes; `_reconcile(state, results)` folds the `IterResult[]` back into canonical state with append-only union on `completedTasks`, last-writer-wins on `status`, OR across `verifyNeeded`, append on `artifacts`, and an overwrite `lastBatch` metadata block.
+
+The production main loop currently runs exactly one iter per pass (`batchSize === 1`) always, unless a caller explicitly threads `opts.maxIterParallel` as a number through `_computeIterBatchSize` — which today's supervisor CLI does not. The four helpers are exported via `module.exports.__test__` so the T7 unit suite and any future caller can exercise batched iteration deterministically, but iter-parallelism at this layer is **scaffolded, not engaged in production**. The gate is intentional: `_runOneIter` mutates shared `state` fields (`state.iter`, heartbeat bookkeeping, the `writeState` side effect) that are not safe to execute concurrently against the same state object. Backlog #24 tracks the follow-up to make `_runOneIter` state-clone-safe and lift the production gate so the supervisor CLI can set a non-1 default.
+
+Contract: `.gsd-t/contracts/iter-parallel-contract.md` v1.0.0.

package/docs/requirements.md

@@ -664,3 +664,23 @@ Milestone 44 D8 delivers a right-side two-layer task panel in the dashboard and
 
 Supporting contract:
 - `.gsd-t/contracts/spawn-plan-contract.md` v1.0.0 — schema + writer/reader/updater protocol + silent-fail rules.
+
+### M46 D2 Worker Sub-Dispatch
+
+A supervisor worker iteration assigned more than one ready task MUST fan those tasks out as concurrent sub-workers via the M44-verified `runDispatch` instrument rather than running them serially, provided the task set is pairwise file-disjoint and the iteration is running inside an unattended worker child (`GSD_T_UNATTENDED_WORKER=1`). This closes the parallelism gap where unattended workers historically executed their assigned tasks one-at-a-time even when the disjointness precondition held, defeating the purpose of the M44 dispatch infrastructure for all unattended runs. The sub-dispatch path is a new consumer of `bin/gsd-t-parallel.cjs::runDispatch` — no changes to the in-session planner's call site, no new disjointness predicate, and no new dispatch logic. Distinguished in telemetry via the new spawn-plan `kind: 'unattended-worker-sub'` value.
+
+Acceptance:
+- `bin/gsd-t-worker-dispatch.cjs` exists and exports `dispatchWorkerTasks` plus the `_areFileDisjoint` helper and the `SPAWN_PLAN_KIND` constant (`'unattended-worker-sub'`).
+- Unit + integration tests in `test/m46-d2-worker-subdispatch.test.js` pass (trigger-condition matrix, disjointness predicate, runDispatch delegation, spawn-plan frame emission, serial fallback on overlap/single-task).
+- Proof measurement recorded in `.gsd-t/metrics/m46-worker-proof.json` shows a parallel-vs-serial speedup of at least **2.5×** on a representative file-disjoint worker iteration.
+- `.gsd-t/contracts/headless-default-contract.md` v2.1.0 §Worker Sub-Dispatch present as the locked source of truth.
+
+### M46 D1 Iteration Parallelism
+
+The unattended supervisor main loop MUST expose iter-level parallelism machinery via four extracted helpers — `_runOneIter`, `_computeIterBatchSize`, `_runIterParallel`, `_reconcile` — so unit tests and future callers can exercise batched iteration deterministically, with `_runIterParallel` using `Promise.allSettled` so a single rejected slice does not cancel siblings and `_reconcile` merging `IterResult[]` into state with append-only `completedTasks`, last-writer-wins `status`, OR across `verifyNeeded`, append on `artifacts`, and overwrite `lastBatch` metadata. The production main loop default remains serial (`batchSize = 1` always, via `_computeIterBatchSize` returning `1` whenever `opts.maxIterParallel` is not a number) pending the state-clone-safety follow-up tracked in backlog #24 — that work must land before the supervisor CLI sets a non-1 default.
+
+Acceptance:
+- `_runOneIter`, `_computeIterBatchSize`, `_runIterParallel`, and `_reconcile` are all exported via `module.exports.__test__` on `bin/gsd-t-unattended.cjs`.
+- Tests in `test/m46-d1-iter-parallel.test.js` pass (serial fallback, parallel batch, mode-safety gate, error isolation, state reconciliation).
+- Proof speedup ≥ **3.0×** recorded in `.gsd-t/metrics/m46-iter-proof.json` — a synthetic `batchSize = 4` measurement of the `_runIterParallel` driver, not the production main loop (which remains serial until backlog #24 lands).
+- `.gsd-t/contracts/iter-parallel-contract.md` v1.0.0 present as the locked source of truth.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekyzinc/gsd-t",
-  "version": "3.18.13",
+  "version": "3.19.00",
   "description": "GSD-T: Contract-Driven Development for Claude Code — 54 slash commands with headless-by-default workflow spawning, unattended supervisor relay with event stream, graph-powered code analysis, real-time agent dashboard, task telemetry, doc-ripple enforcement, backlog management, impact analysis, test sync, milestone archival, and PRD generation",
   "author": "Tekyz, Inc.",
   "license": "MIT",

package/scripts/gsd-t-compact-detector.js

@@ -131,7 +131,20 @@ function writeRow(payload) {
 /**
  * Find the most-recently-modified .ndjson in <cwd>/.gsd-t/transcripts/.
  * Returns the absolute path, or null if none exists or the directory is absent.
+ *
+ * Target-selection rules (M45 D2):
+ * 1. Default: prefer the most-recently-modified SPAWN NDJSON (any file whose
+ *    basename does NOT start with `in-session-`).
+ * 2. Fallback: if no spawn NDJSON has been modified within the last
+ *    IN_SESSION_FALLBACK_MS (30s) AND a fresh `in-session-*.ndjson` exists,
+ *    target that file instead. Log the decision to stderr so regressions
+ *    are obvious during debugging.
+ * 3. Last resort: if only in-session NDJSONs exist, pick the newest one
+ *    (covers the edge case where a user triggers /compact during a pure
+ *    conversation session with no spawns in flight).
  */
+const IN_SESSION_FALLBACK_MS = 30 * 1000; // 30 seconds
+
 function findActiveTranscript(cwd) {
   const transcriptsDir = path.join(cwd, ".gsd-t", "transcripts");
   let entries;
@@ -143,21 +156,51 @@ function findActiveTranscript(cwd) {
   const ndjsons = entries.filter((e) => e.endsWith(".ndjson"));
   if (!ndjsons.length) return null;
 
-  let newest = null;
-  let newestMtime = -1;
+  let newestSpawn = null;
+  let newestSpawnMtime = -1;
+  let newestInSession = null;
+  let newestInSessionMtime = -1;
   for (const name of ndjsons) {
     const full = path.join(transcriptsDir, name);
+    let mtimeMs;
     try {
-      const stat = fs.statSync(full);
-      if (stat.mtimeMs > newestMtime) {
-        newestMtime = stat.mtimeMs;
-        newest = full;
+      mtimeMs = fs.statSync(full).mtimeMs;
+    } catch {
+      continue;
+    }
+    const isInSession = name.indexOf("in-session-") === 0;
+    if (isInSession) {
+      if (mtimeMs > newestInSessionMtime) {
+        newestInSessionMtime = mtimeMs;
+        newestInSession = full;
+      }
+    } else {
+      if (mtimeMs > newestSpawnMtime) {
+        newestSpawnMtime = mtimeMs;
+        newestSpawn = full;
       }
+    }
+  }
+
+  const now = Date.now();
+  const spawnFresh = newestSpawn != null && (now - newestSpawnMtime) < IN_SESSION_FALLBACK_MS;
+
+  if (spawnFresh) return newestSpawn;
+
+  if (newestInSession != null) {
+    try {
+      process.stderr.write(
+        "compact-detector: targeting " + path.basename(newestInSession) + " (fallback)\n"
+      );
     } catch {
-      // skip unreadable entries
+      // silent — stderr write must never break the hook
     }
+    return newestInSession;
   }
-  return newest;
+
+  // No fresh spawn, no in-session — fall back to the newest spawn (even if stale)
+  // so v1.0.0 behavior is preserved for legacy projects with no in-session file.
+  return newestSpawn;
 }
 
 /**