@tekyzinc/gsd-t 3.18.13 → 3.19.0

package/bin/parallelism-report.cjs

@@ -0,0 +1,535 @@
+'use strict';
+
+/**
+ * GSD-T Parallelism Report (M44 D9 T1)
+ *
+ * Pure read-only observer that answers 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?"
+ *
+ * Contract: .gsd-t/contracts/parallelism-report-contract.md v1.0.0
+ *
+ * Hard rules:
+ *   1. NEVER writes a file.
+ *   2. NEVER calls an LLM or spawns a subprocess.
+ *   3. Silent-fail on malformed inputs — skip the bad file, note it, continue.
+ *   4. Zero external deps. `.cjs` so it loads in both ESM and CJS projects.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_VERSION = 1;
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir='.']
+ * @param {string} [opts.wave]
+ * @param {Date}   [opts.now]  injection for tests
+ * @returns {object} Metrics (see contract §Metrics shape)
+ */
+function computeParallelismMetrics(opts) {
+  opts = opts || {};
+  const projectDir = opts.projectDir || '.';
+  const wave = opts.wave || null;
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  const notes = [];
+
+  const spawnPlans = _readSpawnPlans(projectDir, notes);
+  const active = spawnPlans.filter((p) => p && p.endedAt === null);
+  const lastSpawnAt = _computeLastSpawnAt(spawnPlans);
+
+  const activeSpawnAges_s = active
+    .map((p) => {
+      const started = _safeDate(p.startedAt);
+      if (!started) return null;
+      return Math.max(0, Math.floor((now.getTime() - started.getTime()) / 1000));
+    })
+    .filter((x) => x !== null)
+    .sort((a, b) => b - a);
+
+  const readyTasks = _countReadyTasks(projectDir, notes);
+
+  const gate = _computeGateDecisions(projectDir, now, notes);
+
+  const factor = _computeParallelismFactor({ active, spawnPlans, wave, now });
+
+  const colorState = _computeColorState({
+    activeWorkers: active.length,
+    readyTasks,
+    gate,
+    factor,
+    activeSpawnAges_s,
+    lastSpawnAt,
+    now,
+    noSpawns: spawnPlans.length === 0,
+  });
+
+  const out = {
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: now.toISOString(),
+    wave,
+    activeWorkers: active.length,
+    readyTasks,
+    parallelism_factor: factor.value,
+    parallelism_factor_mode: factor.mode,
+    gate_decisions: gate,
+    color_state: colorState,
+    lastSpawnAt,
+    activeSpawnAges_s,
+  };
+  if (notes.length) out.notes = notes;
+  return out;
+}
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.projectDir='.']
+ * @param {string} [opts.wave]
+ * @param {Date}   [opts.now]
+ * @returns {string} markdown post-mortem
+ */
+function buildFullReport(opts) {
+  opts = opts || {};
+  const projectDir = opts.projectDir || '.';
+  const wave = opts.wave || null;
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  const notes = [];
+
+  const m = computeParallelismMetrics({ projectDir, wave, now });
+  const spawnPlans = _readSpawnPlans(projectDir, notes);
+
+  const parts = [];
+  parts.push('# Parallelism Report — ' + (wave || 'all'));
+  parts.push('');
+
+  // §Summary
+  parts.push('## Summary');
+  parts.push('');
+  parts.push('| Field | Value |');
+  parts.push('|-------|-------|');
+  parts.push('| wave | ' + (wave || '—') + ' |');
+  parts.push('| generatedAt | ' + m.generatedAt + ' |');
+  parts.push('| activeWorkers | ' + m.activeWorkers + ' |');
+  parts.push('| readyTasks | ' + m.readyTasks + ' |');
+  parts.push('| parallelism_factor | ' + m.parallelism_factor.toFixed(2) + ' (' + m.parallelism_factor_mode + ') |');
+  parts.push('| color_state | ' + m.color_state + ' |');
+  parts.push('| lastSpawnAt | ' + (m.lastSpawnAt || '—') + ' |');
+  parts.push('');
+
+  // §Per-spawn timeline
+  parts.push('## Per-spawn timeline');
+  parts.push('');
+  parts.push('| spawnId | kind | startedAt | endedAt | duration_s | tasks | status |');
+  parts.push('|---------|------|-----------|---------|------------|-------|--------|');
+  const filteredSpawns = spawnPlans
+    .filter((p) => p && (!wave || p.wave === wave))
+    .sort((a, b) => String(a.startedAt || '').localeCompare(String(b.startedAt || '')));
+  if (filteredSpawns.length === 0) {
+    parts.push('| _no spawn-plan files_ | — | — | — | — | — | — |');
+  } else {
+    for (const p of filteredSpawns) {
+      const dur = _durationSeconds(p, now);
+      const ntasks = Array.isArray(p.tasks) ? p.tasks.length : 0;
+      const status = p.endedAt ? 'ended' : 'active';
+      parts.push(
+        '| ' + (p.spawnId || '—') +
+        ' | ' + (p.kind || '—') +
+        ' | ' + (p.startedAt || '—') +
+        ' | ' + (p.endedAt || '—') +
+        ' | ' + (dur == null ? '—' : dur) +
+        ' | ' + ntasks +
+        ' | ' + status + ' |'
+      );
+    }
+  }
+  parts.push('');
+
+  // §Per-gate decisions
+  parts.push('## Per-gate decisions');
+  parts.push('');
+  const dg = m.gate_decisions;
+  parts.push('### Depgraph gate (dep_gate_veto)');
+  parts.push('- count: ' + dg.dep_gate_veto.count);
+  parts.push('- last reasons: ' + (dg.dep_gate_veto.last_reasons.length ? dg.dep_gate_veto.last_reasons.join('; ') : '—'));
+  parts.push('');
+  parts.push('### Disjointness gate (disjointness_fallback)');
+  parts.push('- count: ' + dg.disjointness_fallback.count);
+  parts.push('- last reasons: ' + (dg.disjointness_fallback.last_reasons.length ? dg.disjointness_fallback.last_reasons.join('; ') : '—'));
+  parts.push('');
+  parts.push('### Economics gate (economics_decision)');
+  parts.push('- count: ' + dg.economics_decision.count);
+  const cd = dg.economics_decision.confidence_distribution;
+  parts.push('- confidence distribution: HIGH=' + cd.HIGH + ' MEDIUM=' + cd.MEDIUM + ' LOW=' + cd.LOW + ' FALLBACK=' + cd.FALLBACK);
+  parts.push('');
+
+  // §Per-worker Gantt (ASCII)
+  parts.push('## Per-worker Gantt (ASCII)');
+  parts.push('');
+  const gantt = _renderAsciiGantt(filteredSpawns, now);
+  parts.push('```');
+  parts.push(gantt);
+  parts.push('```');
+  parts.push('');
+
+  // §Token cost vs. D6 estimate
+  parts.push('## Token cost vs. D6 estimate');
+  parts.push('');
+  const tokenRows = _collectTokenRowsForWave(projectDir, filteredSpawns, notes);
+  if (!tokenRows.length) {
+    parts.push('_no token-log rows found for this wave_');
+  } else {
+    parts.push('| spawnId | taskId | in | out | cr | cc | cost_usd |');
+    parts.push('|---------|--------|----|----|----|----|---------|');
+    for (const r of tokenRows) {
+      parts.push(
+        '| ' + r.spawnId +
+        ' | ' + (r.taskId || '—') +
+        ' | ' + (r.in == null ? '—' : r.in) +
+        ' | ' + (r.out == null ? '—' : r.out) +
+        ' | ' + (r.cr == null ? '—' : r.cr) +
+        ' | ' + (r.cc == null ? '—' : r.cc) +
+        ' | ' + (r.cost_usd == null ? '—' : r.cost_usd) + ' |'
+      );
+    }
+  }
+  parts.push('');
+
+  // §Notes
+  parts.push('## Notes');
+  parts.push('');
+  const allNotes = (m.notes || []).concat(notes);
+  if (!allNotes.length) parts.push('_none_');
+  else for (const n of allNotes) parts.push('- ' + n);
+  parts.push('');
+
+  return parts.join('\n');
+}
+
+// ── Internal helpers ────────────────────────────────────────────────────────
+
+function _readSpawnPlans(projectDir, notes) {
+  const dir = path.join(projectDir, '.gsd-t', 'spawns');
+  let files;
+  try {
+    if (!fs.existsSync(dir)) return [];
+    files = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
+  } catch (err) {
+    notes.push('spawns dir unreadable: ' + (err && err.message || err));
+    return [];
+  }
+  const plans = [];
+  for (const f of files) {
+    const full = path.join(dir, f);
+    let raw;
+    try {
+      raw = fs.readFileSync(full, 'utf8');
+    } catch (err) {
+      notes.push('spawn-plan read failed: ' + full);
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (err) {
+      notes.push('spawn-plan malformed JSON: ' + f);
+      continue;
+    }
+    if (!parsed || typeof parsed !== 'object') {
+      notes.push('spawn-plan not an object: ' + f);
+      continue;
+    }
+    plans.push(parsed);
+  }
+  return plans;
+}
+
+function _computeLastSpawnAt(spawnPlans) {
+  let best = null;
+  for (const p of spawnPlans) {
+    const s = _safeDate(p && p.startedAt);
+    if (!s) continue;
+    if (!best || s.getTime() > best.getTime()) best = s;
+  }
+  return best ? best.toISOString() : null;
+}
+
+function _safeDate(v) {
+  if (!v || typeof v !== 'string') return null;
+  const d = new Date(v);
+  if (isNaN(d.getTime())) return null;
+  return d;
+}
+
+function _durationSeconds(p, now) {
+  const start = _safeDate(p.startedAt);
+  if (!start) return null;
+  const end = p.endedAt ? _safeDate(p.endedAt) : now;
+  if (!end) return null;
+  return Math.max(0, Math.floor((end.getTime() - start.getTime()) / 1000));
+}
+
+function _countReadyTasks(projectDir, notes) {
+  const domainsDir = path.join(projectDir, '.gsd-t', 'domains');
+  let domainNames;
+  try {
+    if (!fs.existsSync(domainsDir)) return 0;
+    domainNames = fs.readdirSync(domainsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch (err) {
+    notes.push('domains dir unreadable: ' + (err && err.message || err));
+    return 0;
+  }
+
+  let total = 0;
+  for (const name of domainNames) {
+    const tasksFile = path.join(domainsDir, name, 'tasks.md');
+    if (!fs.existsSync(tasksFile)) continue;
+    let content;
+    try {
+      content = fs.readFileSync(tasksFile, 'utf8');
+    } catch (err) {
+      notes.push('tasks.md read failed: ' + tasksFile);
+      continue;
+    }
+    // Count pending tasks: bullets starting with `- [ ]` (Shape A/C) OR `### Mxx-Dx-Tx` with no `[x]`.
+    // For D9's purposes we count `- [ ]` markers — matches the existing task-graph parser.
+    const lines = content.split(/\r?\n/);
+    for (const line of lines) {
+      // Shape C: `- [ ] **M44-D9-T1** — ...`
+      if (/^\s*-\s*\[\s\]\s+\*\*[A-Z]+\d+-D\d+-T\d+\*\*/.test(line)) total++;
+      // Shape A: `- [ ] D1-T1` (legacy) or `- [ ] T-1:`
+      else if (/^\s*-\s*\[\s\]\s+(?:\*\*)?[A-Z]?\d?-?[DT]-?\d+/.test(line)) total++;
+    }
+  }
+  return total;
+}
+
+function _computeGateDecisions(projectDir, now, notes) {
+  const eventsDir = path.join(projectDir, '.gsd-t', 'events');
+  const out = {
+    dep_gate_veto: { count: 0, last_reasons: [] },
+    disjointness_fallback: { count: 0, last_reasons: [] },
+    economics_decision: { count: 0, confidence_distribution: { HIGH: 0, MEDIUM: 0, LOW: 0, FALLBACK: 0 } },
+  };
+  if (!fs.existsSync(eventsDir)) return out;
+
+  // Read last 14 days of events.
+  const days = [];
+  for (let i = 0; i < 14; i++) {
+    const d = new Date(now.getTime() - i * 86400000);
+    const iso = d.toISOString().slice(0, 10);
+    days.push(iso);
+  }
+
+  const rows = [];
+  for (const day of days) {
+    const f = path.join(eventsDir, day + '.jsonl');
+    if (!fs.existsSync(f)) continue;
+    let content;
+    try {
+      content = fs.readFileSync(f, 'utf8');
+    } catch (err) {
+      notes.push('events file unreadable: ' + f);
+      continue;
+    }
+    const lines = content.split(/\r?\n/).filter((l) => l.length > 0);
+    for (const line of lines) {
+      let obj;
+      try { obj = JSON.parse(line); }
+      catch (_) { continue; }
+      if (!obj || typeof obj !== 'object') continue;
+      rows.push(obj);
+    }
+  }
+
+  // Sort by ts ascending; take last 10 of each type.
+  rows.sort((a, b) => String(a.ts || '').localeCompare(String(b.ts || '')));
+
+  const depRows = rows.filter((r) => r.type === 'dep_gate_veto').slice(-10);
+  const disRows = rows.filter((r) => r.type === 'disjointness_fallback').slice(-10);
+  const ecoRows = rows.filter((r) => r.type === 'economics_decision').slice(-10);
+
+  out.dep_gate_veto.count = depRows.length;
+  out.dep_gate_veto.last_reasons = depRows.map((r) => r.reason || r.task_id || '—').slice(-5);
+
+  out.disjointness_fallback.count = disRows.length;
+  out.disjointness_fallback.last_reasons = disRows.map((r) => r.reason || r.task_id || '—').slice(-5);
+
+  out.economics_decision.count = ecoRows.length;
+  for (const r of ecoRows) {
+    const c = String(r.confidence || 'FALLBACK').toUpperCase();
+    if (Object.prototype.hasOwnProperty.call(out.economics_decision.confidence_distribution, c)) {
+      out.economics_decision.confidence_distribution[c]++;
+    } else {
+      out.economics_decision.confidence_distribution.FALLBACK++;
+    }
+  }
+
+  return out;
+}
+
+function _computeParallelismFactor({ active, spawnPlans, wave, now }) {
+  // Live mode: any active spawn.
+  if (active.length > 0) {
+    const ages = active
+      .map((p) => {
+        const s = _safeDate(p.startedAt);
+        if (!s) return 0;
+        return Math.max(1, (now.getTime() - s.getTime()) / 1000);
+      });
+    const sum = ages.reduce((a, b) => a + b, 0);
+    const max = Math.max(...ages);
+    if (max <= 0) return { value: 0, mode: 'live' };
+    return { value: sum / max, mode: 'live' };
+  }
+
+  // Post-wave mode: wave supplied, compute across all ended spawns in that wave.
+  if (wave) {
+    const inWave = spawnPlans.filter((p) => p && p.wave === wave);
+    if (inWave.length === 0) return { value: 0, mode: 'post-wave' };
+    const durations = inWave
+      .map((p) => _durationSeconds(p, now))
+      .filter((x) => x !== null);
+    if (durations.length === 0) return { value: 0, mode: 'post-wave' };
+    const starts = inWave.map((p) => _safeDate(p.startedAt)).filter(Boolean).map((d) => d.getTime());
+    const ends = inWave.map((p) => _safeDate(p.endedAt) || now).map((d) => d.getTime());
+    if (starts.length === 0 || ends.length === 0) return { value: 0, mode: 'post-wave' };
+    const span_s = (Math.max(...ends) - Math.min(...starts)) / 1000;
+    const sumDur = durations.reduce((a, b) => a + b, 0);
+    if (span_s <= 0) return { value: 0, mode: 'post-wave' };
+    return { value: sumDur / span_s, mode: 'post-wave' };
+  }
+
+  return { value: 0, mode: 'idle' };
+}
+
+function _computeColorState({ activeWorkers, readyTasks, gate, factor, activeSpawnAges_s, lastSpawnAt, now, noSpawns }) {
+  if (noSpawns) return 'dimmed';
+
+  const signals = [];
+
+  // Signal 1: activeWorkers vs readyTasks
+  if (readyTasks > 0) {
+    const ratio = activeWorkers / readyTasks;
+    const lastSpawn = _safeDate(lastSpawnAt);
+    const minutesSinceSpawn = lastSpawn
+      ? (now.getTime() - lastSpawn.getTime()) / 60000
+      : Infinity;
+    if (ratio >= 0.8) signals.push('green');
+    else if (ratio >= 0.5) signals.push('yellow');
+    else if (minutesSinceSpawn > 10) signals.push('red');
+    else signals.push('yellow');
+  }
+
+  // Signal 2: gate veto rate (dep_gate_veto count vs. total gate events)
+  const totalGate = gate.dep_gate_veto.count + gate.disjointness_fallback.count + gate.economics_decision.count;
+  if (totalGate > 0) {
+    const vetoRate = gate.dep_gate_veto.count / totalGate;
+    if (vetoRate < 0.1) signals.push('green');
+    else if (vetoRate <= 0.3) signals.push('yellow');
+    else signals.push('red');
+  }
+
+  // Signal 3: parallelism_factor vs. ideal (use activeWorkers as ideal — D6 estimate not yet wired)
+  if (factor.mode === 'live' && activeWorkers > 1) {
+    const ideal = activeWorkers;
+    const ratio = factor.value / ideal;
+    if (ratio >= 0.8) signals.push('green');
+    else if (ratio >= 0.5) signals.push('yellow');
+    else signals.push('red');
+  }
+
+  // Signal 4: spawn age (any active > 45 min = red, 30-45 yellow)
+  if (activeSpawnAges_s.length > 0) {
+    const maxAge_m = activeSpawnAges_s[0] / 60;
+    if (maxAge_m < 30) signals.push('green');
+    else if (maxAge_m <= 45) signals.push('yellow');
+    else signals.push('red');
+  }
+
+  // Signal 5: time since last spawn_started when ready>0
+  if (readyTasks > 0) {
+    const lastSpawn = _safeDate(lastSpawnAt);
+    const minutesSinceSpawn = lastSpawn
+      ? (now.getTime() - lastSpawn.getTime()) / 60000
+      : Infinity;
+    if (minutesSinceSpawn < 5) signals.push('green');
+    else if (minutesSinceSpawn <= 10) signals.push('yellow');
+    else signals.push('red');
+  }
+
+  if (signals.length === 0) return 'green';
+  if (signals.includes('red')) return 'red';
+  if (signals.includes('yellow')) return 'yellow';
+  return 'green';
+}
+
+function _renderAsciiGantt(spawns, now) {
+  if (spawns.length === 0) return '(no spawns in this wave)';
+  const valid = spawns
+    .map((p) => {
+      const s = _safeDate(p.startedAt);
+      if (!s) return null;
+      const e = p.endedAt ? _safeDate(p.endedAt) : now;
+      if (!e) return null;
+      return { id: p.spawnId || '—', start: s.getTime(), end: e.getTime() };
+    })
+    .filter(Boolean);
+  if (!valid.length) return '(no datable spawns)';
+
+  const minStart = Math.min(...valid.map((v) => v.start));
+  const maxEnd = Math.max(...valid.map((v) => v.end));
+  const span = Math.max(1, maxEnd - minStart);
+  const WIDTH = 60;
+
+  const lines = [];
+  lines.push('t=0' + ' '.repeat(WIDTH - 3) + 't=' + Math.floor(span / 1000) + 's');
+  for (const v of valid) {
+    const startCol = Math.floor(((v.start - minStart) / span) * WIDTH);
+    const endCol = Math.floor(((v.end - minStart) / span) * WIDTH);
+    const bar = ' '.repeat(startCol) + '#'.repeat(Math.max(1, endCol - startCol)) + ' '.repeat(Math.max(0, WIDTH - endCol));
+    const id = (v.id || '—').slice(0, 24).padEnd(24);
+    lines.push(id + ' |' + bar + '|');
+  }
+  return lines.join('\n');
+}
+
+function _collectTokenRowsForWave(projectDir, spawnPlans, notes) {
+  const rows = [];
+  for (const p of spawnPlans) {
+    if (!p || !Array.isArray(p.tasks)) continue;
+    for (const t of p.tasks) {
+      if (!t || !t.tokens || typeof t.tokens !== 'object') continue;
+      rows.push({
+        spawnId: p.spawnId || '—',
+        taskId: t.id || null,
+        in: t.tokens.in == null ? null : t.tokens.in,
+        out: t.tokens.out == null ? null : t.tokens.out,
+        cr: t.tokens.cr == null ? null : t.tokens.cr,
+        cc: t.tokens.cc == null ? null : t.tokens.cc,
+        cost_usd: t.tokens.cost_usd == null ? null : t.tokens.cost_usd,
+      });
+    }
+  }
+  return rows;
+}
+
+module.exports = {
+  computeParallelismMetrics,
+  buildFullReport,
+  SCHEMA_VERSION,
+  // Exposed for unit tests only; not part of the public contract.
+  _computeLastSpawnAt,
+  _countReadyTasks,
+  _computeGateDecisions,
+  _computeParallelismFactor,
+  _computeColorState,
+  _renderAsciiGantt,
+};

package/bin/spawn-plan-writer.cjs

@@ -41,7 +41,7 @@ const SPAWN_PLAN_SCHEMA_VERSION = 1;
  *
  * @param {object} opts
  * @param {string} opts.spawnId                       filesystem-safe id
- * @param {'unattended-worker'|'headless-detached'|'in-session-subagent'} opts.kind
+ * @param {'unattended-worker'|'headless-detached'|'in-session-subagent'|'unattended-worker-sub'} opts.kind
  * @param {string} [opts.milestone]                   e.g. 'M44'
  * @param {string} [opts.wave]                        e.g. 'wave-3'
  * @param {string[]} [opts.domains]                   domain names involved

package/commands/gsd-t-debug.md

@@ -316,24 +316,20 @@ Before touching any code:
 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-debug --step 3 --step-label "Debug (Solo or Team)" 2>/dev/null || true
 ```
 
-### Optional — Parallel Dispatch (M44, lightweight · conditional-only)
+### Parallel Dispatch (MANDATORY — single instrument)
 
-**This block is a no-op for single-domain debug sessions.** Most debug sessions touch one domain (within-domain bug, Category A in Step 2); for those, the sequential Solo Mode path below runs unchanged.
+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. This is a multi-domain debug session (Category B contract boundary bug OR Category C contract gap that spans more than one domain), AND
-2. The fix is decomposable into independent tasks across domains that pass D4 depgraph + D5 file-disjointness + D6 economics gates.
-
-**If either condition fails** — single-domain debug, or a fix that cannot be decomposed cleanly — skip this block entirely. The sequential Solo Mode / Team Mode flow below remains unchanged.
-
-**If BOTH conditions hold** — dispatch the independent fix tasks 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-debug && exit 0 || true
+# Exit 0  → multi-domain debug decomposable; N detached children handle fixes.
+# Exit 2+ → single-domain or non-decomposable (the common case for debug).
+#           Fall through to Solo / Team Mode below.
+```
 
-- Fallback is silent — any gate veto drops the affected tasks back to the sequential debug 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 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 > 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` 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.
+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-execute.md

@@ -125,27 +125,21 @@ If QA found issues, append each to `.gsd-t/qa-issues.md` (create with header `|
 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-execute --step 3 --step-label "Choose Execution Mode" 2>/dev/null || true
 ```
 
-### Optional — Parallel Dispatch (M44)
+### Parallel Dispatch (MANDATORY — single instrument)
 
-**Conditional check** — if `.gsd-t/domains/` contains more than one pending task that passes the D4 depgraph, D5 file-disjointness, and D6 economics gates, dispatch the ready batch via `gsd-t parallel` instead of the sequential task-dispatcher below. If the conditional fails (single pending task, or any gate vetoes, or disjointness is unprovable), fall through silently to the existing sequential path — there is no user prompt, no pause, no opt-out flag.
-
-- **Mode auto-detection** — mode is auto-detected by `bin/gsd-t-parallel.cjs` from `GSD_T_UNATTENDED=1`. Do not hardcode `--mode` in this command file. Explicit `--mode` overrides env; omitted flag falls back to env; missing env defaults to in-session.
-- **Fallback** — every gate veto (D4 `dep_gate_veto`, D5 `disjointness_fallback`, D6 estimated > threshold) removes the affected task(s) from the parallel batch. Tasks fall back to the sequential task-dispatcher silently; the dry-run plan table still lists them with decision `sequential` or `veto-deps` so the operator can see why.
-- **Observability** — D2 owns the spawn observability. The parallel path writes the same `.gsd-t/events/YYYY-MM-DD.jsonl` event stream (`gate_veto`, `parallelism_reduced`, `task_split`) and the same `.gsd-t/token-log.md` rows that sequential spawns produce via `captureSpawn`. D3 adds no new spawn machinery — integration is purely a dispatch decision.
-- **Zero-compaction invariant (unattended)** — for `[unattended]` runs, D2 enforces the zero-compaction contract by splitting tasks when D6 estimates per-worker CW > 60%. Mid-run compaction is not tolerated; the splitter slices before fan-out.
-- **In-session invariant** — the parallel path NEVER interrupts the user with a pause/resume prompt. If the in-session headroom check reduces the worker count below the requested N, D2 emits `parallelism_reduced` and proceeds at the reduced count. The final floor is N=1 (sequential). If all gates fail, D2 falls back to sequential silently — no opt-out flag exists (consistent with M43 D4: `--in-session` / `--headless` were never shipped).
-
-**Dispatch call** (example; resolve `--mode` via env):
+Delegate the parallel-vs-sequential decision to `gsd-t parallel --command` — do NOT re-implement probe-and-branch logic here. The CLI is the single instrument per M44 D9 Step 3 (user directive: "create 1 instrument that accomplishes this instead of implementing it in all the commands").
 
 ```bash
-# Dry-run first if you want to see the plan table without spawning:
-gsd-t parallel --milestone {milestone} --dry-run
-
-# Live dispatch (mode auto-detected from GSD_T_UNATTENDED):
-gsd-t parallel --milestone {milestone}
+node bin/gsd-t.js parallel --milestone {milestone} --command gsd-t-execute && exit 0 || true
+# Exit 0  → fan-out happened; N detached headless children are running
+#           disjoint task subsets. This agent is done.
+# Exit 2  → sequential (N<2 or gate veto). Fall through to Wave Scheduling below.
+# Exit 3+ → invalid/other; fall through to sequential.
 ```
 
-`runParallel` produces the validated worker plan; the existing M40 orchestrator machinery owns the actual worker spawn, retry policy, wave barriers, and state-file lifecycle. Contract: `.gsd-t/contracts/wave-join-contract.md` v1.1.0. When the conditional is not met — or when every candidate task falls back via veto — proceed to the existing Wave Scheduling + Solo/Team Mode flow below.
+The CLI internally runs `runDispatch()` which: (1) probes the planner via `runParallel({dryRun:true})`, (2) if `workerCount ≥ 2` with D4/D5/D6 gates green, partitions task ids round-robin and spawns N detached headless children via `autoSpawnHeadless()` — each gets `GSD_T_WORKER_TASK_IDS`/`_WORKER_INDEX`/`_WORKER_TOTAL` env vars so the child handles only its assigned subset, (3) else exits 2 so this agent falls through to the legacy single-worker path. Mode is auto-detected from `GSD_T_UNATTENDED=1`. No user prompt. No opt-out flag (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; `.gsd-t/contracts/headless-default-contract.md` v2.0.0.
 
 ### Wave Scheduling (read first)
 

package/commands/gsd-t-help.md

@@ -319,6 +319,7 @@ Use these when user asks for help on a specific command:
 - **Creates**: `.gsd-t/dashboard.pid` (when starting server)
 - **Use when**: Monitoring live agent activity during execute/wave phases; run `gsd-t-visualize stop` to stop the server
 - **Spawn-plan panel (M44 D8, v3.18.10+)**: the transcript viewer at `/transcript/{spawnId}` now includes a right-side two-layer task panel (Layer 1 project · Layer 2 active spawn). Status icons `☐` pending, `◐` in_progress, `✓` done. Done tasks show a right-aligned token cell `in=12.5k out=1.7k $0.42` (or `—` when attribution unavailable). Token attribution is sourced from `.gsd-t/token-log.md` via the post-commit hook `scripts/gsd-t-post-commit-spawn-plan.sh`. Endpoints: `GET /api/spawn-plans` + SSE `/api/spawn-plans/stream`. Contract: `.gsd-t/contracts/spawn-plan-contract.md` v1.0.0.
+- **Parallelism panel (M44 D9, v3.19.0+)**: below the spawn-plan panel, the transcript viewer shows `activeWorkers`, `readyTasks`, `parallelism_factor`, oldest-spawn age, gate-decision tallies (dep/disjoint/economics), a color-state border (green/yellow/red/dimmed), a `📄 Full Report` button that downloads a post-mortem markdown, and a `Stop Supervisor` button. Polls `GET /api/parallelism` every 5s (5s server-side cache). Endpoints: `GET /api/parallelism`, `GET /api/parallelism/report?wave=N`, `POST /api/unattended-stop`. Pure reader — zero added LLM token cost. Contract: `.gsd-t/contracts/parallelism-report-contract.md` v1.0.0.
 
 ### metrics
 - **Summary**: View task telemetry, process ELO, signal distribution, domain health, and cross-project comparison (with `--cross-project` flag)