@tekyzinc/gsd-t 3.18.17 → 3.19.0

package/bin/gsd-t-worker-dispatch.cjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * GSD-T Worker Sub-Dispatch (M46 D2 T2)
+ *
+ * Thin adapter that lets an unattended supervisor worker fan out its own
+ * file-disjoint tasks by reusing the M44-verified `runDispatch` instrument.
+ * This module is a new CONSUMER of `bin/gsd-t-parallel.cjs::runDispatch` —
+ * not a modifier. The in-session dispatch path is byte-identical post-D2.
+ *
+ * Contract: .gsd-t/contracts/headless-default-contract.md v2.1.0 §Worker Sub-Dispatch
+ *
+ * Public API:
+ *   dispatchWorkerTasks({projectDir, parentSessionId, tasks, maxParallel})
+ *     → { parallel, taskResults, wallClockMs, reason }
+ *
+ * Triggers sub-dispatch when all hold:
+ *   - tasks.length > 1
+ *   - tasks are file-disjoint (pairwise no overlap on `task.files`)
+ * Otherwise returns `{parallel: false, …}` and the caller falls through to
+ * its current serial behavior.
+ */
+
+const path = require('path');
+
+const SPAWN_PLAN_KIND = 'unattended-worker-sub';
+const DEFAULT_MAX_PARALLEL = 4;
+
+/**
+ * Pairwise file-disjointness across a task set. Returns true iff no two
+ * tasks share any file in their `files` arrays. Tasks without a `files`
+ * array (or empty) are treated as having no declared file scope and
+ * therefore never overlap with anyone — callers upstream should not
+ * pass such tasks to sub-dispatch, but we remain conservative: a task
+ * with no `files` is considered disjoint from every other task only
+ * when every counterpart also has files declared. When both sides lack
+ * `files`, we conservatively report NOT disjoint so the caller falls
+ * back to serial — an undeclared scope is an unknown scope.
+ */
+function _areFileDisjoint(tasks) {
+  if (!Array.isArray(tasks) || tasks.length < 2) return true;
+  for (let i = 0; i < tasks.length; i++) {
+    const a = tasks[i];
+    const aFiles = (a && Array.isArray(a.files)) ? a.files : null;
+    for (let j = i + 1; j < tasks.length; j++) {
+      const b = tasks[j];
+      const bFiles = (b && Array.isArray(b.files)) ? b.files : null;
+      if (!aFiles || !bFiles) return false;
+      const set = new Set(aFiles);
+      for (const f of bFiles) {
+        if (set.has(f)) return false;
+      }
+    }
+  }
+  return true;
+}
+
+/**
+ * Emit a spawn-plan frame for this sub-dispatch. Best-effort; writer
+ * failures never propagate (per spawn-plan-writer.cjs §Hard rules).
+ */
+function _writeSubDispatchSpawnPlan({ projectDir, parentSessionId, tasks }) {
+  try {
+    const writer = require(path.join(__dirname, 'spawn-plan-writer.cjs'));
+    const spawnId = `worker-sub-${parentSessionId}-${Date.now()}`;
+    const planTasks = tasks.map((t) => ({
+      id: (t && typeof t.taskId === 'string') ? t.taskId : String((t && t.taskId) || ''),
+      title: (t && typeof t.title === 'string') ? t.title : '',
+      status: 'pending',
+    }));
+    writer.writeSpawnPlan({
+      spawnId,
+      kind: SPAWN_PLAN_KIND,
+      projectDir,
+      tasks: planTasks,
+    });
+  } catch (_e) {
+    /* best-effort; never block dispatch */
+  }
+}
+
+/**
+ * dispatchWorkerTasks — the M46 D2 sub-dispatch entry point.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.projectDir        absolute project root
+ * @param {string}   opts.parentSessionId   $GSD_T_PARENT_AGENT_ID from worker env
+ * @param {Array}    opts.tasks             [{taskId, files, command, ...}]
+ * @param {number}   [opts.maxParallel=4]   concurrency cap (default matches M44)
+ * @returns {Promise<{parallel: boolean, taskResults: Array, wallClockMs: number, reason: string}>}
+ */
+async function dispatchWorkerTasks(opts) {
+  const projectDir = (opts && opts.projectDir) || process.cwd();
+  const parentSessionId = (opts && opts.parentSessionId) || '';
+  const tasks = (opts && Array.isArray(opts.tasks)) ? opts.tasks : [];
+  const maxParallel = Number.isFinite(opts && opts.maxParallel) && opts.maxParallel > 0
+    ? Math.floor(opts.maxParallel)
+    : DEFAULT_MAX_PARALLEL;
+
+  if (tasks.length === 0) {
+    return { parallel: false, taskResults: [], wallClockMs: 0, reason: 'no-tasks' };
+  }
+  if (tasks.length === 1) {
+    return { parallel: false, taskResults: [], wallClockMs: 0, reason: 'single-task' };
+  }
+  if (!_areFileDisjoint(tasks)) {
+    return { parallel: false, taskResults: [], wallClockMs: 0, reason: 'file-overlap' };
+  }
+
+  _writeSubDispatchSpawnPlan({ projectDir, parentSessionId, tasks });
+
+  const startedAt = Date.now();
+  try {
+    const parallel = require(path.join(__dirname, 'gsd-t-parallel.cjs'));
+    const result = await parallel.runDispatch({
+      projectDir,
+      tasks,
+      maxWorkers: maxParallel,
+      mode: 'worker-subdispatch',
+    });
+    const wallClockMs = Date.now() - startedAt;
+    const taskResults = (result && Array.isArray(result.workerResults))
+      ? result.workerResults
+      : (result && Array.isArray(result.taskResults) ? result.taskResults : []);
+    return {
+      parallel: true,
+      taskResults,
+      wallClockMs,
+      reason: 'dispatched',
+    };
+  } catch (e) {
+    const wallClockMs = Date.now() - startedAt;
+    const msg = (e && e.message) ? e.message : String(e);
+    return {
+      parallel: false,
+      taskResults: [],
+      wallClockMs,
+      reason: `dispatch-error: ${msg}`,
+    };
+  }
+}
+
+module.exports = {
+  dispatchWorkerTasks,
+  _areFileDisjoint,
+  SPAWN_PLAN_KIND,
+};
+
+if (require.main === module) {
+  (async () => {
+    const fs = require('fs');
+    const argv = process.argv.slice(2);
+    let parentSessionId = null;
+    let tasksPath = null;
+    let maxParallel = DEFAULT_MAX_PARALLEL;
+    for (let i = 0; i < argv.length; i++) {
+      const a = argv[i];
+      if (a === '--parent-session') {
+        parentSessionId = argv[++i];
+      } else if (a === '--tasks') {
+        tasksPath = argv[++i];
+      } else if (a === '--max-parallel') {
+        const n = parseInt(argv[++i], 10);
+        if (Number.isFinite(n) && n > 0) maxParallel = n;
+      }
+    }
+    if (!parentSessionId) {
+      process.stderr.write('error: --parent-session required\n');
+      process.exit(2);
+    }
+    if (!tasksPath) {
+      process.stderr.write('error: --tasks required\n');
+      process.exit(2);
+    }
+    let raw;
+    try {
+      raw = fs.readFileSync(tasksPath, 'utf8');
+    } catch (e) {
+      process.stderr.write(`error: cannot read tasks file ${tasksPath}: ${(e && e.message) || e}\n`);
+      process.exit(2);
+    }
+    let tasks;
+    try {
+      tasks = JSON.parse(raw);
+    } catch (e) {
+      process.stderr.write(`error: malformed tasks JSON: ${(e && e.message) || e}\n`);
+      process.exit(2);
+    }
+    if (!Array.isArray(tasks)) {
+      process.stderr.write('error: tasks JSON must be an array\n');
+      process.exit(2);
+    }
+    const projectDir = process.cwd();
+    try {
+      const result = await dispatchWorkerTasks({
+        projectDir,
+        parentSessionId,
+        tasks,
+        maxParallel,
+      });
+      process.stdout.write(JSON.stringify(result) + '\n');
+      const anyFailed = Array.isArray(result && result.taskResults)
+        && result.taskResults.some((r) => r && (r.exitCode !== 0 && r.exitCode != null));
+      process.exit(anyFailed ? 1 : 0);
+    } catch (e) {
+      process.stderr.write(`error: dispatch threw: ${(e && e.message) || e}\n`);
+      process.exit(1);
+    }
+  })();
+}

package/bin/headless-auto-spawn.cjs

@@ -74,7 +74,8 @@ let _deprecatedWatchWarned = false;
  *   sessionId?: string,
  *   watch?: boolean,
  *   spawnType?: 'primary' | 'validation',
- *   env?: object
+ *   env?: object,
+ *   workerModel?: string
  * }} opts
  * @returns {{ id: string | null, pid: number | null, logPath: string | null, timestamp: string, mode: 'headless' | 'in-context' }}
  */
@@ -136,6 +137,24 @@ function autoSpawnHeadless(opts) {
     /* best-effort; fall through without banner port info */
   }
 
+  // M46 follow-up — Date + version banner. Printed before the transcript URL
+  // so multi-day-old read-backs are immediately dated. Best-effort.
+  try {
+    const { dateStamp } = require("../scripts/gsd-t-update-check.js");
+    const fsLocal = require("fs");
+    const osLocal = require("os");
+    const pathLocal = require("path");
+    let v = "unknown";
+    try {
+      v = fsLocal.readFileSync(
+        pathLocal.join(osLocal.homedir(), ".claude/.gsd-t-version"), "utf8"
+      ).trim();
+    } catch (_) { /* fall through with "unknown" */ }
+    process.stdout.write(`${dateStamp()}GSD-T v${v} — CURRENT\n`);
+  } catch (_) {
+    /* best-effort — never crash the spawn on banner failure */
+  }
+
   // M43 D6-T3 — Live transcript URL banner. Printed for every spawn so the
   // viewer at :PORT is "the" primary watching surface. Never throws.
   // Text is coordinated with D4 — exact line shape is part of
@@ -211,6 +230,14 @@ function autoSpawnHeadless(opts) {
         workerEnv[k] = String(v);
       }
     }
+    // Worker-model override (v3.18.18) — let `runDispatch` fan-outs default to
+    // Sonnet while the orchestrator stays on whatever the parent runs (often
+    // Opus). Moves mechanical fan-out work onto a separate rate-limit bucket,
+    // raising the provider concurrency ceiling from ~3 to ~6+ per the
+    // Max-subscription concurrency analysis (2026-04-23).
+    if (typeof opts.workerModel === "string" && opts.workerModel) {
+      workerEnv.ANTHROPIC_MODEL = opts.workerModel;
+    }
 
     const child = spawn("node", childArgs, {
       cwd: projectDir,

package/bin/m46-iter-proof.cjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * M46-D1 Iter-Parallel Proof Harness (T10)
+ *
+ * Measures the parallelism speedup of `_runIterParallel` vs. a serial
+ * baseline using a synthetic 10-iter workload where each iter sleeps
+ * 200ms and returns a successful IterResult.
+ *
+ * Method:
+ *   1. Serial baseline (batchSize=1): run 10 iters one at a time via
+ *      `_runIterParallel(..., batchSize=1)` in a loop. Expect ~2000ms.
+ *   2. Parallel (batchSize=4): run 10 iters in batches of 4+4+2 via the
+ *      same helper. Expect ~600ms (3 batches × 200ms).
+ *   3. Compute speedup = T_serial / T_par,
+ *      parallelism_factor = (10 × 200) / T_par.
+ *   4. Pass iff T_par/T_serial ≤ 0.35 AND speedup ≥ 3.0.
+ *
+ * Output: .gsd-t/metrics/m46-iter-proof.json + human summary on stdout.
+ * Exit: 0 on pass, 1 on fail.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ITER_COUNT = 10;
+const ITER_SLEEP_MS = 200;
+const BATCH_SERIAL = 1;
+const BATCH_PARALLEL = 4;
+const THRESHOLD_RATIO = 0.35;
+const THRESHOLD_SPEEDUP = 3.0;
+
+const { _runIterParallel } = require(path.join(__dirname, 'gsd-t-unattended.cjs')).__test__;
+
+// ── synthetic iterFn ───────────────────────────────────────────────────────
+
+let iterSeq = 0;
+function makeIterFn(sleepMs) {
+  return async function fakeIter(_state, _opts) {
+    const id = iterSeq++;
+    await new Promise((r) => setTimeout(r, sleepMs));
+    return {
+      status: 'ok',
+      tasksDone: ['t' + id],
+      verifyNeeded: false,
+      artifacts: [],
+    };
+  };
+}
+
+// ── runners ────────────────────────────────────────────────────────────────
+
+async function runSerial(total, sleepMs) {
+  const iterFn = makeIterFn(sleepMs);
+  const state = {};
+  const opts = {};
+  const t0 = process.hrtime.bigint();
+  const results = [];
+  for (let i = 0; i < total; i++) {
+    const batch = await _runIterParallel(state, opts, iterFn, BATCH_SERIAL);
+    results.push(...batch);
+  }
+  const t1 = process.hrtime.bigint();
+  return {
+    wallClockMs: Number(t1 - t0) / 1e6,
+    results,
+  };
+}
+
+async function runParallel(total, batchSize, sleepMs) {
+  const iterFn = makeIterFn(sleepMs);
+  const state = {};
+  const opts = {};
+  const t0 = process.hrtime.bigint();
+  const results = [];
+  let remaining = total;
+  while (remaining > 0) {
+    const n = Math.min(batchSize, remaining);
+    const batch = await _runIterParallel(state, opts, iterFn, n);
+    results.push(...batch);
+    remaining -= n;
+  }
+  const t1 = process.hrtime.bigint();
+  return {
+    wallClockMs: Number(t1 - t0) / 1e6,
+    results,
+  };
+}
+
+// ── main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  process.stdout.write(
+    `M46-D1 Iter-Parallel Proof (N=${ITER_COUNT} iters, sleep=${ITER_SLEEP_MS}ms each)\n`,
+  );
+  process.stdout.write('─'.repeat(60) + '\n');
+
+  iterSeq = 0;
+  const serial = await runSerial(ITER_COUNT, ITER_SLEEP_MS);
+  process.stdout.write(`Serial baseline (batchSize=${BATCH_SERIAL}, ${ITER_COUNT} iters sequentially)\n`);
+  process.stdout.write(`  T_serial (wall-clock): ${serial.wallClockMs.toFixed(1)} ms\n`);
+  process.stdout.write(`  results:               ${serial.results.length} (ok=${serial.results.filter((r) => r.status === 'ok').length})\n\n`);
+
+  iterSeq = 0;
+  const parallel = await runParallel(ITER_COUNT, BATCH_PARALLEL, ITER_SLEEP_MS);
+  process.stdout.write(`Parallel (batchSize=${BATCH_PARALLEL}, batches of 4+4+2)\n`);
+  process.stdout.write(`  T_par (wall-clock):    ${parallel.wallClockMs.toFixed(1)} ms\n`);
+  process.stdout.write(`  results:               ${parallel.results.length} (ok=${parallel.results.filter((r) => r.status === 'ok').length})\n\n`);
+
+  const ratio = parallel.wallClockMs / serial.wallClockMs;
+  const speedup = serial.wallClockMs / parallel.wallClockMs;
+  const parallelismFactor = (ITER_COUNT * ITER_SLEEP_MS) / parallel.wallClockMs;
+  const passed = ratio <= THRESHOLD_RATIO && speedup >= THRESHOLD_SPEEDUP;
+
+  process.stdout.write('─'.repeat(60) + '\n');
+  process.stdout.write('Result\n');
+  process.stdout.write(`  T_par / T_serial     = ${ratio.toFixed(3)} (threshold ≤ ${THRESHOLD_RATIO})\n`);
+  process.stdout.write(`  speedup              = ${speedup.toFixed(2)}× (threshold ≥ ${THRESHOLD_SPEEDUP})\n`);
+  process.stdout.write(`  parallelism_factor   = ${parallelismFactor.toFixed(2)} (ideal ≈ ${BATCH_PARALLEL})\n`);
+  process.stdout.write(`  verdict              = ${passed ? 'PASS ✓' : 'FAIL ✗'}\n`);
+
+  const report = {
+    timestamp: new Date().toISOString(),
+    iter_count: ITER_COUNT,
+    iter_sleep_ms: ITER_SLEEP_MS,
+    batch_size_serial: BATCH_SERIAL,
+    batch_size_parallel: BATCH_PARALLEL,
+    T_serial_ms: serial.wallClockMs,
+    T_par_ms: parallel.wallClockMs,
+    speedup,
+    parallelism_factor: parallelismFactor,
+    threshold_T_par_over_T_serial: THRESHOLD_RATIO,
+    threshold_speedup: THRESHOLD_SPEEDUP,
+    passed,
+  };
+  const reportDir = path.join(process.cwd(), '.gsd-t', 'metrics');
+  fs.mkdirSync(reportDir, { recursive: true });
+  const reportPath = path.join(reportDir, 'm46-iter-proof.json');
+  fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+  process.stdout.write(`\nReport written: ${reportPath}\n`);
+
+  process.exit(passed ? 0 : 1);
+}
+
+main().catch((e) => {
+  process.stderr.write(`ERROR: ${(e && e.stack) || e}\n`);
+  process.exit(2);
+});

package/bin/m46-worker-proof.cjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * M46-D2 Worker Sub-Dispatch Proof Harness (T7)
+ *
+ * Measures the parallelism speedup of `dispatchWorkerTasks` vs. a serial
+ * baseline using a synthetic 6-task file-disjoint workload.
+ *
+ * Method:
+ *   1. Serial baseline: run 6 `sleep 2 && echo done > …` tasks one by one
+ *      via `child_process.execSync`. Record `T_serial` (wall-clock ms).
+ *   2. Parallel via `dispatchWorkerTasks`: stub the dispatcher's
+ *      `runDispatch` boundary (via a mocked `gsd-t-parallel.cjs` in
+ *      require.cache) to execute tasks concurrently with
+ *      `child_process.exec` + `Promise.all`. This measures the dispatch
+ *      SCHEDULER's fan-out behaviour, not real headless claude-p spawns.
+ *   3. Compute speedup and parallelism_factor. Pass iff speedup ≥ 2.5.
+ *
+ * Output: .gsd-t/metrics/m46-worker-proof.json + human summary on stdout.
+ * Exit: 0 on pass, 1 on fail.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { exec, execSync } = require('child_process');
+
+const THRESHOLD = 2.5;
+const TASK_COUNT = 6;
+const PID = process.pid;
+const TMP_DIR = path.join(os.tmpdir(), `m46-proof-${PID}`);
+
+function ensureTmpDir() {
+  fs.mkdirSync(TMP_DIR, { recursive: true });
+}
+
+function cleanupTmpDir() {
+  try { fs.rmSync(TMP_DIR, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+}
+
+function buildTasks() {
+  const tasks = [];
+  for (let i = 0; i < TASK_COUNT; i++) {
+    const outPath = path.join(TMP_DIR, `task-${i}.out`);
+    tasks.push({
+      taskId: `T-${i}`,
+      files: [outPath],
+      command: `sleep 2 && echo done > ${outPath}`,
+    });
+  }
+  return tasks;
+}
+
+// ── serial baseline ────────────────────────────────────────────────────────
+
+function runSerial(tasks) {
+  const perTaskMs = [];
+  const t0 = process.hrtime.bigint();
+  for (const task of tasks) {
+    const ts = process.hrtime.bigint();
+    execSync(task.command, { stdio: 'ignore' });
+    const te = process.hrtime.bigint();
+    perTaskMs.push(Number(te - ts) / 1e6);
+  }
+  const t1 = process.hrtime.bigint();
+  return {
+    wallClockMs: Number(t1 - t0) / 1e6,
+    perTaskMs,
+    meanTaskMs: perTaskMs.reduce((a, b) => a + b, 0) / perTaskMs.length,
+  };
+}
+
+// ── parallel via stubbed runDispatch ──────────────────────────────────────
+
+function installParallelStub() {
+  // Pre-populate require.cache for bin/gsd-t-parallel.cjs with a stub whose
+  // `runDispatch` executes the task `command` field concurrently via exec +
+  // Promise.all. This isolates measurement to the dispatcher scheduler and
+  // avoids invoking real claude-p children.
+  const parallelPath = require.resolve(path.join(__dirname, 'gsd-t-parallel.cjs'));
+  const stubModule = {
+    exports: {
+      runDispatch: async ({ tasks }) => {
+        const workerResults = await Promise.all(tasks.map((task) => new Promise((resolve) => {
+          const started = Date.now();
+          exec(task.command, (err) => {
+            resolve({
+              taskId: task.taskId,
+              exitCode: err ? (err.code || 1) : 0,
+              durationMs: Date.now() - started,
+            });
+          });
+        })));
+        return {
+          decision: 'fan-out',
+          fanOutCount: tasks.length,
+          workerResults,
+        };
+      },
+    },
+    loaded: true,
+    id: parallelPath,
+    filename: parallelPath,
+    paths: [],
+    children: [],
+  };
+  require.cache[parallelPath] = stubModule;
+}
+
+async function runParallel(tasks) {
+  installParallelStub();
+  // Fresh require after stub install, in case worker-dispatch was pre-loaded.
+  const dispatchPath = require.resolve(path.join(__dirname, 'gsd-t-worker-dispatch.cjs'));
+  delete require.cache[dispatchPath];
+  const { dispatchWorkerTasks } = require(dispatchPath);
+
+  const t0 = process.hrtime.bigint();
+  const result = await dispatchWorkerTasks({
+    projectDir: TMP_DIR,
+    parentSessionId: `m46-proof-${PID}`,
+    tasks,
+    maxParallel: TASK_COUNT,
+  });
+  const t1 = process.hrtime.bigint();
+
+  return {
+    wallClockMs: Number(t1 - t0) / 1e6,
+    parallel: result.parallel,
+    reason: result.reason,
+    taskResults: result.taskResults,
+  };
+}
+
+// ── main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  ensureTmpDir();
+  process.stdout.write(`M46-D2 Worker Sub-Dispatch Proof (N=${TASK_COUNT} tasks, tmp=${TMP_DIR})\n`);
+  process.stdout.write('─'.repeat(60) + '\n');
+
+  const tasks = buildTasks();
+
+  const serial = runSerial(tasks);
+  process.stdout.write('Serial baseline (execSync, tasks run back-to-back)\n');
+  process.stdout.write(`  T_serial (wall-clock): ${serial.wallClockMs.toFixed(1)} ms\n`);
+  process.stdout.write(`  per-task durations:    [${serial.perTaskMs.map((x) => x.toFixed(0)).join(', ')}] ms\n`);
+  process.stdout.write(`  mean(task duration):   ${serial.meanTaskMs.toFixed(1)} ms\n\n`);
+
+  // Reset task output files before parallel run so exec doesn't race on
+  // leftovers (each task writes its own file so this is just hygiene).
+  for (let i = 0; i < TASK_COUNT; i++) {
+    const p = path.join(TMP_DIR, `task-${i}.out`);
+    try { fs.unlinkSync(p); } catch (_) { /* ignore */ }
+  }
+
+  const parallel = await runParallel(tasks);
+  process.stdout.write(`Parallel via dispatchWorkerTasks (runDispatch stub, concurrent exec)\n`);
+  process.stdout.write(`  T_par (wall-clock):    ${parallel.wallClockMs.toFixed(1)} ms\n`);
+  process.stdout.write(`  parallel dispatched:   ${parallel.parallel} (reason=${parallel.reason})\n`);
+  process.stdout.write(`  per-task results:      ${parallel.taskResults.length} tasks\n\n`);
+
+  const speedup = serial.wallClockMs / parallel.wallClockMs;
+  const parallelismFactor = (TASK_COUNT * serial.meanTaskMs) / parallel.wallClockMs;
+  const passed = speedup >= THRESHOLD;
+
+  process.stdout.write('─'.repeat(60) + '\n');
+  process.stdout.write('Result\n');
+  process.stdout.write(`  speedup              = ${speedup.toFixed(2)}× (threshold ≥ ${THRESHOLD})\n`);
+  process.stdout.write(`  parallelism_factor   = ${parallelismFactor.toFixed(2)} (ideal = ${TASK_COUNT})\n`);
+  process.stdout.write(`  verdict              = ${passed ? 'PASS ✓' : 'FAIL ✗'}\n`);
+
+  const report = {
+    timestamp: new Date().toISOString(),
+    task_count: TASK_COUNT,
+    T_serial_ms: serial.wallClockMs,
+    T_par_ms: parallel.wallClockMs,
+    speedup,
+    parallelism_factor: parallelismFactor,
+    threshold: THRESHOLD,
+    passed,
+  };
+  const reportDir = path.join(process.cwd(), '.gsd-t', 'metrics');
+  fs.mkdirSync(reportDir, { recursive: true });
+  const reportPath = path.join(reportDir, 'm46-worker-proof.json');
+  fs.writeFileSync(reportPath, JSON.stringify(report, null, 2));
+  process.stdout.write(`\nReport written: ${reportPath}\n`);
+
+  cleanupTmpDir();
+  process.exit(passed ? 0 : 1);
+}
+
+process.on('exit', cleanupTmpDir);
+process.on('SIGINT', () => { cleanupTmpDir(); process.exit(130); });
+process.on('SIGTERM', () => { cleanupTmpDir(); process.exit(143); });
+
+main().catch((e) => {
+  process.stderr.write(`ERROR: ${(e && e.stack) || e}\n`);
+  cleanupTmpDir();
+  process.exit(2);
+});

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-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: