@tekyzinc/gsd-t 3.18.13 → 3.18.17

package/bin/gsd-t-unattended.cjs

@@ -62,6 +62,19 @@ function _emit(projectDir, ev) {
   try { _esAppendEvent(projectDir, ev); } catch (_) { /* never halt the loop */ }
 }
 
+// M44 D9 (v1.5.0) — planner-driven multi-worker fan-out. Lazy-loaded so unit
+// tests can stub via deps._runParallel without touching the real module.
+let _parallelModule = null;
+function _loadRunParallel() {
+  if (_parallelModule) return _parallelModule;
+  try {
+    _parallelModule = require("./gsd-t-parallel.cjs");
+  } catch {
+    _parallelModule = { runParallel: () => ({ workerCount: 0, parallelTasks: [], plan: [] }) };
+  }
+  return _parallelModule;
+}
+
 // M42 D1 — transcript tee. Captures each worker's stdout lines to an ndjson
 // file and registers the spawn so the dashboard sidebar can list + render it.
 // Best-effort: every call is swallowed so tee failures never halt the loop.
@@ -73,7 +86,7 @@ const { checkHeartbeat: _checkHeartbeat } = require("./gsd-t-unattended-heartbea
 
 // ── Constants ───────────────────────────────────────────────────────────────
 
-const CONTRACT_VERSION = "1.4.0";
+const CONTRACT_VERSION = "1.5.0";
 const UNATTENDED_DIR_REL = path.join(".gsd-t", ".unattended");
 const PID_FILE = "supervisor.pid";
 const STATE_FILE = "state.json";
@@ -122,6 +135,8 @@ module.exports = {
   releaseSleepPrevention,
   runMainLoop,
   _spawnWorker,
+  _spawnWorkerFanOut,
+  _partitionTasks,
   _appendRunLog,
   CONTRACT_VERSION,
   UNATTENDED_DIR_REL,
@@ -927,6 +942,10 @@ async function runMainLoop(state, dir, opts, deps, ctx) {
     deps._spawnWorker || (useTestStub ? _testModeSpawnWorker : _spawnWorker);
   const milestoneComplete =
     deps._isMilestoneComplete || (useTestStub ? () => true : isMilestoneComplete);
+  // M44 D9 (v1.5.0) — planner injected for multi-worker iter fan-out.
+  // Tests stub via deps._runParallel; production lazy-loads from gsd-t-parallel.cjs.
+  const runParallelImpl =
+    deps._runParallel || ((o) => _loadRunParallel().runParallel(o));
   const stopCheck = deps._stopRequested || stopRequested;
   const workerTimeoutMs = opts.workerTimeoutMs || DEFAULT_WORKER_TIMEOUT_MS;
   const staleHeartbeatMs =
@@ -1001,15 +1020,61 @@ async function runMainLoop(state, dir, opts, deps, ctx) {
           heartbeatPollMs,
         }
       : {};
+
+    // M44 D9 (v1.5.0) — planner-driven fan-out decision for this iter.
+    // Ask runParallel whether the current task graph supports ≥2 concurrent
+    // workers. Any failure in the planner path MUST fall back to the single-
+    // worker spawn — the parallel path is purely additive.
+    let iterPlan = null;
     try {
-      res = spawnWorker(state, {
-        cwd: projectDir,
-        timeout: workerTimeoutMs,
-        verbose: !!opts.verbose,
-        ...hbOpts,
+      iterPlan = runParallelImpl({
+        projectDir,
+        mode: "unattended",
+        milestone: state.milestone || null,
+        dryRun: true,
       });
-      if (res && typeof res.then === "function") {
-        res = await res;
+    } catch (e) {
+      iterPlan = null;
+      _emit(projectDir, {
+        iter: state.iter,
+        type: "parallelism_reduced",
+        source: "supervisor",
+        original_count: null,
+        reduced_count: 1,
+        reason: `planner_error:${(e && e.message) || "unknown"}`,
+      });
+    }
+    const fanOutCount = iterPlan && Number(iterPlan.workerCount) >= 2 ? Number(iterPlan.workerCount) : 1;
+    const parallelTaskIds = iterPlan && Array.isArray(iterPlan.parallelTasks) ? iterPlan.parallelTasks : [];
+    const subsets = fanOutCount >= 2 ? _partitionTasks(parallelTaskIds, fanOutCount) : null;
+    const useFanOut = !!(subsets && subsets.length >= 2);
+
+    try {
+      if (useFanOut) {
+        _emit(projectDir, {
+          ts: workerStart.toISOString(),
+          iter: state.iter,
+          type: "fan_out",
+          source: "supervisor",
+          worker_count: subsets.length,
+          task_ids: parallelTaskIds,
+        });
+        res = await _spawnWorkerFanOut(state, {
+          cwd: projectDir,
+          timeout: workerTimeoutMs,
+          verbose: !!opts.verbose,
+          ...hbOpts,
+        }, spawnWorker, subsets);
+      } else {
+        res = spawnWorker(state, {
+          cwd: projectDir,
+          timeout: workerTimeoutMs,
+          verbose: !!opts.verbose,
+          ...hbOpts,
+        });
+        if (res && typeof res.then === "function") {
+          res = await res;
+        }
       }
     } catch (e) {
       // Defensive: a real spawnSync shouldn't throw, but a shim could.
@@ -1083,6 +1148,26 @@ async function runMainLoop(state, dir, opts, deps, ctx) {
     } else {
       state.lastExitReason = `exit_${exitCode}`;
     }
+    // M44 D9 (v1.5.0) — per-iter multi-worker aggregates. Present only when the
+    // planner selected fan-out; single-worker iters omit these fields so the
+    // state schema stays backward-compatible with v1.4.x readers.
+    if (useFanOut && Array.isArray(res.workerResults)) {
+      state.lastExits = res.workerResults.map((w) => ({
+        idx: w.idx,
+        code: typeof w.status === "number" ? w.status : null,
+        taskIds: w.taskIds || [],
+        elapsedMs: w.elapsedMs,
+        spawnId: w.spawnId || null,
+      }));
+      state.workerPids = res.workerResults.map((w) => w.spawnId || null);
+      state.lastFanOutCount = res.workerResults.length;
+    } else {
+      // Clear stale multi-worker fields on single-worker iters so readers
+      // never see a mix of regimes.
+      if (state.lastExits) delete state.lastExits;
+      if (state.workerPids) delete state.workerPids;
+      if (state.lastFanOutCount) delete state.lastFanOutCount;
+    }
     writeState(state, dir);
 
     // Event-stream: task_complete on success, error on non-zero.
@@ -1285,11 +1370,24 @@ function _spawnWorker(state, opts) {
   // id as parent, so shims inside the worker write state files that the tree
   // builder can attach under the supervisor root.
   workerEnv.GSD_T_AGENT_ID =
-    "supervisor-iter-" + (state && state.iter ? state.iter : Date.now());
+    "supervisor-iter-" + (state && state.iter ? state.iter : Date.now()) +
+    (state && typeof state._workerIndex === "number" ? `-w${state._workerIndex}` : "");
   if (process.env.GSD_T_AGENT_ID) {
     workerEnv.GSD_T_PARENT_AGENT_ID = process.env.GSD_T_AGENT_ID;
   }
 
+  // M44 D9 (v1.5.0) — planner-driven fan-out: when the supervisor partitions
+  // the iter's task graph across N workers, each worker carries its disjoint
+  // task-id subset via env var. The worker prompt consumes this to (a) skip
+  // the intra-worker Team Mode block (the fan-out is the team), (b) restrict
+  // itself to its assigned task IDs.
+  const assignedTaskIds = Array.isArray(opts && opts.taskIds) ? opts.taskIds : null;
+  if (assignedTaskIds && assignedTaskIds.length > 0) {
+    workerEnv.GSD_T_WORKER_TASK_IDS = assignedTaskIds.join(",");
+    workerEnv.GSD_T_WORKER_INDEX = String((state && state._workerIndex) || 0);
+    workerEnv.GSD_T_WORKER_TOTAL = String((state && state._workerTotal) || 1);
+  }
+
   // M42 D1 — allocate a spawn-id + open transcript before spawning. parentId
   // is the supervisor's own spawn-id (set once at supervisor start via
   // GSD_T_SPAWN_ID env) so the sidebar can render parent-indented trees.
@@ -1353,6 +1451,18 @@ function _spawnWorker(state, opts) {
         "",
         "# Team Mode (Intra-Wave Parallelism)",
         "",
+        "M44 D9 (v1.5.0+) — check env `GSD_T_WORKER_TASK_IDS` FIRST. If SET, you",
+        "are one of N planner-assigned workers in a supervisor-level fan-out.",
+        "The value is your disjoint task-id subset. DO NOT spawn Task subagents",
+        "to re-fan-out (the supervisor already did). Execute ONLY your assigned",
+        "task IDs sequentially in this worker, then return. Skip the rest of",
+        "this block.",
+        "",
+        "If GSD_T_WORKER_TASK_IDS is UNSET, the supervisor's planner decided",
+        "N=1 for this iter (sequential fallback: gates vetoed, file-disjointness",
+        "unprovable, or est CW% too high). Proceed with the legacy worker-level",
+        "Team Mode below:",
+        "",
         "Before executing tasks for this iteration, read `.gsd-t/partition.md` to",
         "identify the current wave and which domains belong to it.",
         "",
@@ -1427,6 +1537,97 @@ function _spawnWorker(state, opts) {
   return finalize(spawnResult);
 }
 
+// ── _spawnWorkerFanOut (M44 D9, contract v1.5.0) ────────────────────────────
+
+/**
+ * Planner-driven multi-worker fan-out. Spawns N concurrent workers via the
+ * injected `spawnWorker` shim, each receiving a disjoint subset of the iter's
+ * parallel task IDs (passed through `opts.taskIds`). Waits on all via
+ * Promise.all before returning a merged result shape compatible with the
+ * single-worker path.
+ *
+ * Merge semantics:
+ *   - `status`        — 0 if every worker cleanly returned 0, else the first
+ *                       non-zero status encountered (worst exit wins).
+ *   - `stdout`        — per-worker blocks joined by `[WORKER i/N tasks=...]` headers.
+ *   - `stderr`        — concatenated.
+ *   - `staleHeartbeat`/`timedOut` — true if any worker triggered them.
+ *   - `workerResults` — array of per-worker {status, taskIds, pid, spawnId, elapsedMs}
+ *                       for state.json aggregation.
+ *
+ * The caller (runMainLoop) treats this result exactly like a single-worker
+ * result for downstream classification. Multi-worker observability lives in
+ * the `workerResults` array, not in new control-flow branches.
+ */
+async function _spawnWorkerFanOut(state, opts, spawnWorker, subsets) {
+  const launches = subsets.map((taskIds, i) => {
+    const subState = { ...state, _workerIndex: i, _workerTotal: subsets.length, _workerTaskIds: taskIds };
+    const started = Date.now();
+    return Promise.resolve()
+      .then(() => spawnWorker(subState, { ...opts, taskIds }))
+      .then((r) => ({ r: r || {}, taskIds, started, ended: Date.now(), idx: i }))
+      .catch((e) => ({
+        r: { status: 3, stdout: "", stderr: String((e && e.message) || e), signal: null },
+        taskIds, started, ended: Date.now(), idx: i,
+      }));
+  });
+  const outcomes = await Promise.all(launches);
+  outcomes.sort((a, b) => a.idx - b.idx);
+
+  let mergedStatus = 0;
+  let stale = false;
+  let timedOut = false;
+  let heartbeatReason = null;
+  const stdoutBlocks = [];
+  const stderrBlocks = [];
+  const workerResults = [];
+
+  for (const o of outcomes) {
+    const s = typeof o.r.status === "number" ? o.r.status : null;
+    if (mergedStatus === 0 && s !== 0) mergedStatus = s === null ? 1 : s;
+    if (o.r.staleHeartbeat) stale = true;
+    if (o.r.timedOut) timedOut = true;
+    if (!heartbeatReason && o.r.heartbeatReason) heartbeatReason = o.r.heartbeatReason;
+    const tag = `[WORKER ${o.idx + 1}/${outcomes.length} tasks=${(o.taskIds || []).join(",") || "-"}]`;
+    stdoutBlocks.push(`${tag}\n${o.r.stdout || ""}`);
+    if (o.r.stderr) stderrBlocks.push(`${tag}\n${o.r.stderr}`);
+    workerResults.push({
+      idx: o.idx,
+      status: s,
+      taskIds: o.taskIds,
+      spawnId: o.r.spawnId || null,
+      signal: o.r.signal || null,
+      elapsedMs: o.ended - o.started,
+      staleHeartbeat: !!o.r.staleHeartbeat,
+      timedOut: !!o.r.timedOut,
+    });
+  }
+
+  return {
+    status: mergedStatus,
+    stdout: stdoutBlocks.join("\n"),
+    stderr: stderrBlocks.join("\n"),
+    signal: null,
+    timedOut,
+    staleHeartbeat: stale,
+    heartbeatReason,
+    workerResults,
+    fanOutCount: outcomes.length,
+  };
+}
+
+/**
+ * Partition a task-id list into `workerCount` roughly-equal subsets. Simple
+ * round-robin — each subset is non-empty as long as `tasks.length >= workerCount`.
+ */
+function _partitionTasks(tasks, workerCount) {
+  if (!Array.isArray(tasks) || tasks.length === 0 || workerCount < 1) return [];
+  const n = Math.min(workerCount, tasks.length);
+  const subsets = Array.from({ length: n }, () => []);
+  for (let i = 0; i < tasks.length; i++) subsets[i % n].push(tasks[i]);
+  return subsets;
+}
+
 // ── _testModeSpawnWorker ────────────────────────────────────────────────────
 
 /**

package/bin/headless-auto-spawn.cjs

@@ -73,7 +73,8 @@ let _deprecatedWatchWarned = false;
  *   sessionContext?: object,
  *   sessionId?: string,
  *   watch?: boolean,
- *   spawnType?: 'primary' | 'validation'
+ *   spawnType?: 'primary' | 'validation',
+ *   env?: object
  * }} opts
  * @returns {{ id: string | null, pid: number | null, logPath: string | null, timestamp: string, mode: 'headless' | 'in-context' }}
  */
@@ -83,6 +84,12 @@ function autoSpawnHeadless(opts) {
   const continue_from = opts.continue_from || ".";
   const projectDir = opts.projectDir || process.cwd();
   const context = opts.context || opts.sessionContext || null;
+  // M44 D9 Step 3 — optional per-call env overrides layered over the inherited
+  // process.env. Used by `runDispatch` in gsd-t-parallel.cjs to forward
+  // GSD_T_WORKER_TASK_IDS / _WORKER_INDEX / _WORKER_TOTAL to each fan-out
+  // child so the child knows which task subset to handle. Purely additive —
+  // callers that don't pass `env` get the pre-M44-D9 behavior unchanged.
+  const envOverride = (opts.env && typeof opts.env === "object") ? opts.env : null;
   // M43 D4 — `watch` is accepted for caller backward-compat but IGNORED.
   // `inSession` was never shipped; accept+ignore for the same reason.
   // Under headless-default-contract v2.0.0 every spawn goes headless; the
@@ -195,6 +202,15 @@ function autoSpawnHeadless(opts) {
     if (process.env.GSD_T_AGENT_ID) {
       workerEnv.GSD_T_PARENT_AGENT_ID = process.env.GSD_T_AGENT_ID;
     }
+    // M44 D9 Step 3 — caller-supplied env overrides (e.g., fan-out task ids).
+    // Applied AFTER the canonical GSD_T_* keys so a caller can override any
+    // of them if needed; opaque for everything else.
+    if (envOverride) {
+      for (const [k, v] of Object.entries(envOverride)) {
+        if (v == null) continue;
+        workerEnv[k] = String(v);
+      }
+    }
 
     const child = spawn("node", childArgs, {
       cwd: projectDir,

package/bin/headless-exit-codes.cjs

@@ -19,29 +19,47 @@
 
 "use strict";
 
+// Match terminal markers, not narration. A bare "tests failed" substring will
+// appear in healthy output ("0 tests failed", "no tests failed", quoted as an
+// example in prose). Require either a non-zero count prefix or a structured
+// terminal marker (start of line, uppercase-FAIL prefix, Jest-style summary).
+// Bug history: M45 worker output contained "tests failed" 6× in narration,
+// causing the supervisor to map exit 0 → exit 1 and halt a successful run.
+
+const NONZERO_FAILURE_COUNT_RE =
+  /(?:^|\b)([1-9]\d*)\s+(?:tests?|specs?|assertions?|examples?|suites?)\s+failed\b/i;
+const STRUCTURED_FAIL_RE = /^FAIL[:\s]/m;
+const JEST_SUMMARY_FAIL_RE = /^Tests:\s+\d+\s+failed/im;
+
+// Verification-phrase matchers: require the phrase at a line boundary or
+// preceded by a sentence-start punctuation — not mid-prose. Each phrase is
+// distinctive enough that start-of-line / post-punctuation is a reliable
+// terminal-marker signal.
+const VERIFICATION_FAILED_RE =
+  /(?:^|[.!?]\s+)(?:verification|verify|quality gate)\s+failed\b/im;
+
+// Context-budget phrases — same polarity discipline. Tolerant of surrounding
+// punctuation (— / :) but requires the phrase at a line boundary.
+const CONTEXT_BUDGET_RE =
+  /(?:^|[.!?]\s+)(?:context budget exceeded|context window exceeded|budget exceeded|token limit)\b/im;
+
+// Blocker compound: "blocked" within 80 chars of a human-gate phrase, both
+// anchored to recognizable boundaries. The 80-char proximity keeps unrelated
+// mentions from compounding.
+const BLOCKED_HUMAN_RE =
+  /\bblocked\b[\s\S]{0,80}?\b(?:needs? human|human input|human approval)\b/i;
+
 function mapHeadlessExitCode(processExitCode, output) {
   if (processExitCode !== 0 && processExitCode !== null) return 3;
   const raw = output || "";
-  const lower = raw.toLowerCase();
   if (/^unknown command:/im.test(raw)) return 5;
+  if (CONTEXT_BUDGET_RE.test(raw)) return 2;
+  if (BLOCKED_HUMAN_RE.test(raw)) return 4;
   if (
-    lower.includes("context budget exceeded") ||
-    lower.includes("context window exceeded") ||
-    lower.includes("budget exceeded") ||
-    lower.includes("token limit")
-  ) return 2;
-  if (
-    lower.includes("blocked") &&
-    (lower.includes("needs human") ||
-      lower.includes("need human") ||
-      lower.includes("human input") ||
-      lower.includes("human approval"))
-  ) return 4;
-  if (
-    lower.includes("verification failed") ||
-    lower.includes("verify failed") ||
-    lower.includes("quality gate failed") ||
-    lower.includes("tests failed")
+    VERIFICATION_FAILED_RE.test(raw) ||
+    NONZERO_FAILURE_COUNT_RE.test(raw) ||
+    STRUCTURED_FAIL_RE.test(raw) ||
+    JEST_SUMMARY_FAIL_RE.test(raw)
   ) return 1;
   return 0;
 }

package/bin/m44-proof-measure.cjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * M44 Proof Measurement Driver (backlog #15 — T/2 criterion)
+ *
+ * Goal: prove v3.19.00's parallel dispatcher actually fans out concurrently.
+ *
+ * Method:
+ *   1. Build a temp project with a 4-task file-disjoint tasks.md fixture.
+ *   2. Inject a synthetic spawner into bin/gsd-t-parallel.cjs::runDispatch
+ *      that launches test/fixtures/m44-proof/worker-sim.js as a detached
+ *      child (same contract as the real autoSpawnHeadless).
+ *   3. Measure:
+ *        T_seq = sum of per-worker durations when called sequentially.
+ *        T_par = wall-clock span from first spawn_started to last .done
+ *                marker when dispatched via runDispatch.
+ *   4. Criterion: T_par ≤ T_seq / 2   ( = parallelism_factor ≥ 2 for N=4 )
+ *
+ * This proves the DISPATCHER. It does NOT prove that 4 Claude workers
+ * produce correct code in T/2. That is a separate, API-budget-intensive
+ * experiment (backlog #15 follow-up). The dispatcher is the shipped code
+ * in v3.19.00, and its mechanics are what the tag certifies.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { spawn } = require('child_process');
+
+const { runDispatch } = require(path.join(__dirname, 'gsd-t-parallel.cjs'));
+const { writeSpawnPlan } = require(path.join(__dirname, 'spawn-plan-writer.cjs'));
+const { markTaskDone, markSpawnEnded } = require(path.join(__dirname, 'spawn-plan-status-updater.cjs'));
+
+// When invoked with --visualize, write spawn-plan files into the REAL project
+// directory (not the temp fixture dir) so the live dashboard at :7455 can
+// render the fan-out in real time. Off by default to keep the measurement
+// directory clean.
+const VISUALIZE = process.argv.includes('--visualize');
+const REAL_PROJECT_DIR = path.resolve(__dirname, '..');
+
+// ── fixture setup ───────────────────────────────────────────────────────────
+
+function buildFixtureProject(workDurationMs) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'm44-proof-'));
+  fs.mkdirSync(path.join(root, '.gsd-t', 'domains', 'm99-d1-proof'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.gsd-t', 'spawns'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.gsd-t', 'events'), { recursive: true });
+
+  const tasksMd = fs.readFileSync(
+    path.join(__dirname, '..', 'test', 'fixtures', 'm44-proof', 'fixture.tasks.md'),
+    'utf8',
+  );
+  fs.writeFileSync(path.join(root, '.gsd-t', 'domains', 'm99-d1-proof', 'tasks.md'), tasksMd);
+
+  const partitionMd = [
+    '# Partition — M99',
+    '',
+    '## Wave 1',
+    '- m99-d1-proof (all tasks disjoint, no deps)',
+    '',
+  ].join('\n');
+  fs.writeFileSync(path.join(root, '.gsd-t', 'partition.md'), partitionMd);
+
+  return root;
+}
+
+function cleanup(root) {
+  try { fs.rmSync(root, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+}
+
+// ── spawner (injected into runDispatch) ────────────────────────────────────
+
+function makeSpawner({ outDir, workerDurationMs }) {
+  const launched = [];
+  const spawner = ({ env }) => {
+    const childEnv = Object.assign({}, process.env, env, {
+      OUT_DIR: outDir,
+      WORKER_DURATION_MS: String(workerDurationMs),
+    });
+    const workerPath = path.join(__dirname, '..', 'test', 'fixtures', 'm44-proof', 'worker-sim.js');
+    const child = spawn(process.execPath, [workerPath], {
+      env: childEnv, detached: true, stdio: 'ignore',
+    });
+    child.unref();
+    const spawnId = 'm44-proof-' + env.GSD_T_WORKER_INDEX + '-' + Date.now();
+    const taskIds = env.GSD_T_WORKER_TASK_IDS.split(',');
+
+    if (VISUALIZE) {
+      try {
+        writeSpawnPlan({
+          spawnId,
+          kind: 'headless-detached',
+          milestone: 'M99',
+          wave: 'wave-1',
+          domains: ['m99-d1-proof'],
+          tasks: taskIds.map((id) => ({ id, title: 'Proof ' + id, status: 'in_flight' })),
+          projectDir: REAL_PROJECT_DIR,
+        });
+      } catch (e) { process.stderr.write('[visualize] writeSpawnPlan failed: ' + e.message + '\n'); }
+    }
+
+    launched.push({
+      spawnId, pid: child.pid,
+      taskIds,
+      launchedAt: process.hrtime.bigint(),
+    });
+    return { id: spawnId, pid: child.pid, logPath: null };
+  };
+  return { spawner, launched };
+}
+
+function markLaunchedDone(launched) {
+  if (!VISUALIZE) return;
+  for (const l of launched) {
+    try {
+      for (const id of l.taskIds) {
+        markTaskDone({ spawnId: l.spawnId, taskId: id, projectDir: REAL_PROJECT_DIR, commit: 'proof-sim', tokens: null });
+      }
+      markSpawnEnded({ spawnId: l.spawnId, projectDir: REAL_PROJECT_DIR });
+    } catch (e) { process.stderr.write('[visualize] mark-done failed: ' + e.message + '\n'); }
+  }
+}
+
+// ── wait for all .done markers ─────────────────────────────────────────────
+
+async function waitForMarkers(outDir, expectedCount, timeoutMs = 60000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    let present;
+    try { present = fs.readdirSync(outDir).filter((n) => n.endsWith('.done')); }
+    catch { present = []; }
+    if (present.length >= expectedCount) return present;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw new Error('timeout waiting for ' + expectedCount + ' .done markers in ' + outDir);
+}
+
+function readMarkers(outDir) {
+  return fs.readdirSync(outDir)
+    .filter((n) => n.endsWith('.done'))
+    .map((n) => JSON.parse(fs.readFileSync(path.join(outDir, n), 'utf8')))
+    .sort((a, b) => a.workerIndex - b.workerIndex);
+}
+
+// ── runs ────────────────────────────────────────────────────────────────────
+
+async function runParallelPass(workerDurationMs) {
+  const projectDir = buildFixtureProject(workerDurationMs);
+  const outDir = path.join(projectDir, 'worker-out');
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const { spawner, launched } = makeSpawner({ outDir, workerDurationMs });
+
+  const t0 = process.hrtime.bigint();
+  const result = runDispatch({
+    projectDir,
+    command: 'gsd-t-execute',
+    mode: 'unattended',
+    env: { GSD_T_UNATTENDED: '1' },
+    spawnHeadlessImpl: spawner,
+  });
+  const dispatchReturnedAt = process.hrtime.bigint();
+
+  if (result.fanOutCount < 2) {
+    cleanup(projectDir);
+    throw new Error('parallel dispatch did not fan out (decision=' + result.decision + ', fanOutCount=' + result.fanOutCount + ')');
+  }
+
+  await waitForMarkers(outDir, result.fanOutCount);
+  const t1 = process.hrtime.bigint();
+
+  markLaunchedDone(launched);
+
+  const markers = readMarkers(outDir);
+  const wallClockMs = Number(t1 - t0) / 1e6;
+  const dispatchOverheadMs = Number(dispatchReturnedAt - t0) / 1e6;
+  const perWorkerDurationMs = markers.map((m) => m.durationMs);
+  const sumWorkerDurationMs = perWorkerDurationMs.reduce((a, b) => a + b, 0);
+
+  cleanup(projectDir);
+  return {
+    mode: 'parallel',
+    fanOutCount: result.fanOutCount,
+    launched: launched.length,
+    wallClockMs,
+    dispatchOverheadMs,
+    perWorkerDurationMs,
+    sumWorkerDurationMs,
+    workerPids: markers.map((m) => m.pid),
+    markers,
+  };
+}
+
+async function runSequentialPass(workerDurationMs, taskCount = 4) {
+  // Sequential baseline: run N workers back-to-back, same worker-sim.js.
+  // This is what a single-worker supervisor would do before v3.19.00.
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'm44-proof-seq-'));
+  const outDir = path.join(tmp, 'worker-out');
+  fs.mkdirSync(outDir, { recursive: true });
+
+  const t0 = process.hrtime.bigint();
+  for (let i = 0; i < taskCount; i++) {
+    await new Promise((resolve, reject) => {
+      const child = spawn(process.execPath, [
+        path.join(__dirname, '..', 'test', 'fixtures', 'm44-proof', 'worker-sim.js'),
+      ], {
+        env: Object.assign({}, process.env, {
+          OUT_DIR: outDir,
+          WORKER_DURATION_MS: String(workerDurationMs),
+          GSD_T_WORKER_INDEX: String(i),
+          GSD_T_WORKER_TOTAL: String(taskCount),
+          GSD_T_WORKER_TASK_IDS: 'M99-D1-T' + (i + 1),
+        }),
+        stdio: 'ignore',
+      });
+      child.on('exit', (code) => code === 0 ? resolve() : reject(new Error('worker exit ' + code)));
+      child.on('error', reject);
+    });
+  }
+  const t1 = process.hrtime.bigint();
+  const markers = readMarkers(outDir);
+  const wallClockMs = Number(t1 - t0) / 1e6;
+  cleanup(tmp);
+
+  return {
+    mode: 'sequential',
+    taskCount,
+    wallClockMs,
+    perWorkerDurationMs: markers.map((m) => m.durationMs),
+    sumWorkerDurationMs: markers.map((m) => m.durationMs).reduce((a, b) => a + b, 0),
+  };
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const workerDurationMs = parseInt(process.env.WORKER_DURATION_MS || '8000', 10);
+  process.stdout.write('M44 Proof Measurement (worker duration=' + workerDurationMs + 'ms)\n');
+  process.stdout.write('─'.repeat(60) + '\n');
+
+  const seq = await runSequentialPass(workerDurationMs);
+  process.stdout.write('Sequential (N=4 workers run back-to-back)\n');
+  process.stdout.write('  T_seq (wall-clock):   ' + seq.wallClockMs.toFixed(1) + ' ms\n');
+  process.stdout.write('  sum(worker durations): ' + seq.sumWorkerDurationMs.toFixed(1) + ' ms\n');
+  process.stdout.write('\n');
+
+  const par = await runParallelPass(workerDurationMs);
+  process.stdout.write('Parallel (runDispatch, N=' + par.fanOutCount + ' concurrent workers)\n');
+  process.stdout.write('  T_par (wall-clock):   ' + par.wallClockMs.toFixed(1) + ' ms\n');
+  process.stdout.write('  dispatch overhead:     ' + par.dispatchOverheadMs.toFixed(1) + ' ms\n');
+  process.stdout.write('  sum(worker durations): ' + par.sumWorkerDurationMs.toFixed(1) + ' ms\n');
+  process.stdout.write('  per-worker durations:  [' + par.perWorkerDurationMs.map((x) => x.toFixed(0)).join(', ') + '] ms\n');
+  process.stdout.write('  worker pids:           [' + par.workerPids.join(', ') + ']\n');
+  process.stdout.write('\n');
+
+  const ratio = par.wallClockMs / seq.wallClockMs;
+  const speedup = seq.wallClockMs / par.wallClockMs;
+  const parallelismFactor = par.sumWorkerDurationMs / par.wallClockMs;
+  const criterion = par.wallClockMs <= seq.wallClockMs / 2;
+
+  process.stdout.write('─'.repeat(60) + '\n');
+  process.stdout.write('Result\n');
+  process.stdout.write('  T_par / T_seq        = ' + ratio.toFixed(3) + '\n');
+  process.stdout.write('  speedup              = ' + speedup.toFixed(2) + '×\n');
+  process.stdout.write('  parallelism_factor   = ' + parallelismFactor.toFixed(2) + '  (ideal = ' + par.fanOutCount + ')\n');
+  process.stdout.write('  T/2 criterion        = ' + (criterion ? 'MET ✓' : 'NOT MET ✗') + '  (T_par ≤ T_seq/2)\n');
+
+  const report = {
+    generatedAt: new Date().toISOString(),
+    workerDurationMs,
+    sequential: seq,
+    parallel: par,
+    ratio, speedup, parallelismFactor,
+    criterionMet: criterion,
+  };
+  const reportPath = path.join(process.cwd(), '.gsd-t', 'm44-proof-report.json');
+  fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+  fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+  process.stdout.write('\nReport written: ' + reportPath + '\n');
+
+  process.exit(criterion ? 0 : 1);
+}
+
+main().catch((e) => { process.stderr.write('ERROR: ' + (e && e.stack || e) + '\n'); process.exit(2); });