@opengsd/gsd-core 1.7.0 → 1.8.0

package/scripts/run-tests.cjs

@@ -15,9 +15,14 @@
 //   node scripts/run-tests.cjs --files-from /tmp/selected-tests.txt
 //   node scripts/run-tests.cjs --suite unit --shard 1/3   # shard 1 of 3 (#1212)
 //
-// Sharding (issue #1212): --shard <i>/<n> runs a deterministic, balanced
-// round-robin slice of the SORTED selected file list (file index k → shard
-// k % n). i is 1-based (1..n); n >= 1; n=1 is a pure no-op (all files). The
+// Sharding (issue #1212, reweighted #2472): --shard <i>/<n> runs a
+// deterministic, COST-balanced slice of the SORTED selected file list. Files
+// are partitioned by measured duration (tests/test-timings.json) using LPT —
+// the same packing the chunker uses one level down — because equal file COUNTS
+// are not equal file COST: the index-based split this replaced ran 12.4m /
+// 19.2m / 15.2m against a 20-minute job cap. With no timing data every file
+// weighs the same and the partition degenerates to the original k % n
+// round-robin. i is 1-based (1..n); n >= 1; n=1 is a pure no-op (all files). The
 // CI windows full-test lane shards across N parallel runners so per-job
 // wall-clock scales as O(total/N) and stops hitting the job time cap. Sharding
 // composes with --suite (it slices the post-filter selection) and preserves
@@ -29,7 +34,7 @@
 // See docs/TESTING-SUITES.md for full grouping policy.
 'use strict';
 
-const { readdirSync } = require('fs');
+const { readdirSync, readFileSync } = require('fs');
 const { join, basename } = require('path');
 const { execFileSync } = require('child_process');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
@@ -206,7 +211,8 @@ function parseShardArg(value) {
   return { index, total };
 }
 
-// Deterministic, balanced round-robin partition of an ALREADY-SORTED file list.
+// Deterministic partition of an ALREADY-SORTED file list. Without a weigher
+// this is the original round-robin (#1212):
 // Shard `index` (1-based) receives every file whose position k in the sorted
 // list satisfies k % total === index - 1. Round-robin (not contiguous blocks)
 // spreads duration variance across shards and guarantees shard sizes differ by
@@ -215,9 +221,269 @@ function parseShardArg(value) {
 // sorts the list with the same (locale-independent) comparator. `total=1`
 // returns the input unchanged (pure no-op). A shard with no files (total >
 // file count) returns [] and is a legitimate result, not an error.
-function selectShard(sortedFiles, { index, total }) {
+// `weightOf` (optional, #2472) switches the partition from equal COUNTS to
+// equal COST. Equal counts were only ever a proxy for equal duration, and on a
+// right-skewed suite the proxy fails: the real unit suite partitioned 12.4m /
+// 19.2m / 15.2m by index against a 20-minute job cap, and because assignment
+// keyed off array POSITION, inserting one test file re-indexed every file after
+// it and could tip the heaviest shard over. Weighting by measured cost fixes
+// both: LPT bounds the heaviest shard at 4/3 of optimal, and placement follows
+// a file's cost rather than its neighbours' names.
+//
+// This is the same algorithm packChunks uses one level down (#2456/#2463), so
+// both layers now share one cost model. Omitting `weightOf` keeps the legacy
+// round-robin byte-identical — callers with no timing data lose nothing.
+function selectShard(sortedFiles, { index, total }, weightOf) {
   if (total === 1) return sortedFiles;
-  return sortedFiles.filter((_, k) => k % total === index - 1);
+  if (typeof weightOf !== 'function') {
+    return sortedFiles.filter((_, k) => k % total === index - 1);
+  }
+  // A non-finite or negative weight must not poison bin arithmetic — one NaN
+  // would make every subsequent comparison false and pile the rest of the suite
+  // into bin 0. Mirrors packChunks' safeWeight for the same reason.
+  const safeWeight = (file) => {
+    const w = weightOf(file);
+    return Number.isFinite(w) && w >= 0 ? w : 0;
+  };
+  const bins = Array.from({ length: total }, () => ({ weight: 0, picks: [] }));
+  // LPT: heaviest first, each into the currently-lightest bin. Ties break on
+  // the caller's sort position, and the lightest-bin scan takes the FIRST
+  // minimum, so the partition is byte-identical across Windows/macOS/Linux —
+  // the same determinism guarantee the round-robin path carries.
+  const order = sortedFiles
+    .map((file, k) => ({ k, weight: safeWeight(file) }))
+    .sort((a, b) => b.weight - a.weight || a.k - b.k);
+  for (const entry of order) {
+    let lightest = 0;
+    for (let i = 1; i < total; i += 1) {
+      const bin = bins[i];
+      const best = bins[lightest];
+      // Weight first, then FILE COUNT. The count tiebreak is load-bearing, not
+      // cosmetic: adding a zero-weight file leaves its bin's weight unchanged,
+      // so on weight alone bin 0 stays tied-minimum forever and every
+      // zero-weight file lands on it — all-zero weights put the whole suite on
+      // shard 1 and leave the other runners idle. Zero weights are reachable
+      // via safeWeight's clamp (a NaN/negative/Infinity entry in a hand-edited
+      // or corrupted timings table) and via any genuinely 0ms measurement, so
+      // the clamp above would otherwise reproduce the exact pile-onto-bin-0
+      // failure it exists to prevent. Counting picks makes ties rotate.
+      if (bin.weight < best.weight
+        || (bin.weight === best.weight && bin.picks.length < best.picks.length)) {
+        lightest = i;
+      }
+    }
+    bins[lightest].weight += entry.weight;
+    bins[lightest].picks.push(entry.k);
+  }
+  // Restore the caller's order within the shard: downstream chunking and argv
+  // batching assume the list arrives sorted as the caller sorted it.
+  return bins[index - 1].picks.sort((a, b) => a - b).map((k) => sortedFiles[k]);
+}
+
+// Read an operator-supplied numeric env knob, falling back to the default for
+// anything that is not a positive finite number.
+//
+// This is a strict-input boundary (Postel's Law: a typo must fail SAFE, not
+// silently poison arithmetic downstream). `Number('abc')` is NaN and
+// `Number('')` is 0, and both are load-bearing here: a NaN chunk budget makes
+// the chunk-count computation NaN, which spins packChunks' retry loop forever
+// (a hung CI job with no output); a zero budget makes it Infinity, which throws
+// `RangeError: Invalid array length`. Neither is an acceptable response to a
+// mistyped environment variable.
+function positiveNumberEnv(raw, fallback) {
+  if (raw === undefined || raw === null || String(raw).trim() === '') return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+// Per-file measured durations, regenerated by scripts/gen-test-timings.cjs from
+// gsd-test reporter event streams. Overridable so tests can inject a synthetic
+// table instead of depending on the real suite's cost profile.
+const DEFAULT_TIMINGS_PATH = join(__dirname, '..', 'tests', 'test-timings.json');
+// Must track SCHEMA_VERSION in scripts/gen-test-timings.cjs.
+const SUPPORTED_TIMINGS_SCHEMA = 1;
+
+// Load the timing table and reduce it to what the packer needs.
+//
+// Weights are normalized by the table's MEAN duration, so an average-cost file
+// weighs exactly 1 and `MAX_FILES_PER_CHUNK` keeps its original meaning ("about
+// N average files per chunk"). When every file costs the same, total weight
+// equals file count, so the chunk COUNT matches count-based packing exactly.
+// The chunk COMPOSITION still differs — LPT balances where first-fit filled
+// greedily, so 7 uniform files at budget 3 pack {3,2,2} rather than {3,3,1}.
+//
+// `medianWeight` is the fallback for a file absent from the table (a new test,
+// or a table that has drifted). The median — not the mean — because the cost
+// distribution is heavily right-skewed (median 0.28s vs mean 4.6s across the
+// suite), so the median is the honest estimate for an unknown file.
+//
+// Returns null when the table is missing or unusable; the caller then treats
+// every file as weight 1, which reproduces the pre-#2456 count-based balance.
+function loadTestTimings(timingsPath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(timingsPath, 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  // Refuse a table written by a future generator: a v2 schema could change the
+  // unit or the key format, and consuming it under v1 semantics would silently
+  // mis-weight every file. Returning null falls back to uniform weight, which
+  // is the same graceful degradation as a missing table.
+  if (parsed.schema_version !== undefined && parsed.schema_version !== SUPPORTED_TIMINGS_SCHEMA) {
+    return null;
+  }
+  const timings = parsed.timings;
+  // Array.isArray guard: `typeof [] === 'object'`, so a hand-edit that turned
+  // the map into a list would pass a bare typeof check and be accepted as a
+  // valid table. It degrades harmlessly (no basename ever matches an array
+  // index, so every file takes medianWeight), but silently accepting a
+  // malformed table is worse than rejecting it — reject, and fall back to
+  // uniform weight the same way a missing file does.
+  if (!timings || typeof timings !== 'object' || Array.isArray(timings)) return null;
+  const values = Object.values(timings).filter(
+    (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0,
+  );
+  if (values.length === 0) return null;
+  const mean = values.reduce((sum, v) => sum + v, 0) / values.length;
+  if (!(mean > 0)) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = sorted.length >> 1;
+  const median = sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+  return { timings, mean, medianWeight: median / mean };
+}
+
+// Build the packer's weight function from a loaded timing table.
+//
+// A file present in the table weighs its measured duration relative to the
+// table mean. A file ABSENT from it weighs the table's median — this is the
+// "advisory, not gated" contract: a new test or a drifted table costs chunk
+// balance, never a red build. A null table (missing or unparseable file) makes
+// every file weigh 1, reproducing the pre-#2456 count-based balance exactly.
+function makeFileWeigher(timings) {
+  if (!timings) return () => 1;
+  return (f) => {
+    const key = basename(f);
+    // Own-property check before the lookup. This is defense-in-depth, NOT a
+    // behavior change: the table is JSON-parsed, so a bare `timings[key]` would
+    // walk the prototype chain, but the only keys that resolve there are
+    // Object.prototype members (`constructor`, `toString`, …) and every real
+    // selection is a `*.test.cjs` basename, which can never equal one. Even if
+    // it could, the `typeof ms === 'number'` guard below already rejects the
+    // function it would return. `Object.hasOwn` makes the intent explicit and
+    // keeps the lookup correct for arbitrary input, since this function is
+    // exported and does not control its caller's strings.
+    const ms = Object.hasOwn(timings.timings, key) ? timings.timings[key] : undefined;
+    return typeof ms === 'number' && Number.isFinite(ms) && ms >= 0
+      ? ms / timings.mean
+      : timings.medianWeight;
+  };
+}
+
+// Pack `files` into chunks using LPT (longest-processing-time-first): sort by
+// weight descending, then place each file into the currently-LIGHTEST chunk.
+//
+// #2456: the previous packer was a sequential first-fit that appended files in
+// selection order and closed a chunk once its weight budget was hit. Because
+// sorted-adjacent files land together, the two heaviest files in a shard packed
+// into the SAME chunk, leaving the slowest chunk ~3.9x the lightest and sitting
+// near the 600s per-chunk timeout while other chunks idled. LPT is the standard
+// greedy approximation for exactly this makespan problem and balanced the same
+// real shard to ~1.0x.
+//
+// Chunk COUNT is fixed before placement so LPT has bins to balance across:
+//   ceil(totalWeight / maxWeight)  — the weighted budget, and
+//   ceil(fileCount  / maxWeight)   — a floor that pins the count at what the
+//                                    old count-based packing would produce.
+// The floor is what makes a stale or missing timings table safe: unknown files
+// fall back to a small median weight, which on its own would collapse many files
+// into few fat chunks. With the floor, a degraded table can only ever reproduce
+// today's chunking, never something coarser.
+//
+// `maxChars` still bounds each chunk's argv (Windows CreateProcess caps
+// lpCommandLine at 32,767). A chunk that cannot fit the next file is skipped for
+// that file; when no chunk has room, the chunk count grows and packing restarts.
+// A single file longer than the budget lands alone rather than looping forever.
+//
+// Ordering is fully deterministic — ties break on the separator-normalized file
+// path, and each chunk's files are emitted in their original selection order —
+// so the packing is byte-identical across Windows/macOS/Linux.
+function packChunks(files, { weightOf, maxWeight, maxChars, fixedOverhead }) {
+  if (files.length === 0) return [];
+  // packChunks is exported, so it cannot assume its caller normalized these.
+  // A non-finite or non-positive budget makes the chunk-count arithmetic
+  // non-finite, which spins the retry loop below forever or throws from
+  // Array.from; a non-finite weight propagates into the same computation.
+  // Degrade to a safe bound instead.
+  const weightBudget = Number.isFinite(maxWeight) && maxWeight > 0 ? maxWeight : files.length;
+  const charBudget = Number.isFinite(maxChars) && maxChars > 0 ? maxChars : Number.MAX_SAFE_INTEGER;
+  const overhead = Number.isFinite(fixedOverhead) && fixedOverhead >= 0 ? fixedOverhead : 0;
+  const safeWeight = (file) => {
+    const w = weightOf(file);
+    return Number.isFinite(w) && w >= 0 ? w : 0;
+  };
+  const entries = files.map((file, index) => ({
+    file,
+    index,
+    weight: safeWeight(file),
+    chars: file.length + 1, // +1 for the inter-arg separator
+  }));
+  const totalWeight = entries.reduce((sum, e) => sum + e.weight, 0);
+  // Ties break on a SEPARATOR-NORMALIZED path so a subdir file orders the same
+  // on Windows as on POSIX: '/' is 0x2F and '\' is 0x5C, which straddle the
+  // uppercase range, so comparing raw paths can order `sub/x.test.cjs` against
+  // `subZ.test.cjs` differently per platform and silently produce a different
+  // (still valid, but non-reproducible) packing.
+  const sortKey = (f) => f.replace(/\\/g, '/');
+  const heaviestFirst = [...entries].sort((a, b) => {
+    if (b.weight !== a.weight) return b.weight - a.weight;
+    const ka = sortKey(a.file);
+    const kb = sortKey(b.file);
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+
+  // Termination: the empty-bin rule below guarantees every file is placeable
+  // once chunkCount reaches files.length, so the retry loop cannot run forever.
+  // The upper clamp matters as much as the lower bound: a legitimate but tiny
+  // budget (RUN_TESTS_MAX_FILES_PER_CHUNK=1e-9) would otherwise ask for
+  // 637,000,000,000 bins and throw `RangeError: Invalid array length`. More
+  // chunks than files is never useful — one file per chunk is the finest
+  // possible packing.
+  let chunkCount = Math.min(
+    files.length,
+    Math.max(1, Math.ceil(totalWeight / weightBudget), Math.ceil(files.length / weightBudget)),
+  );
+  for (;;) {
+    const bins = Array.from({ length: chunkCount }, () => ({
+      entries: [],
+      weight: 0,
+      chars: overhead,
+    }));
+    let overflowed = false;
+    for (const entry of heaviestFirst) {
+      let target = null;
+      for (const bin of bins) {
+        // An empty bin always accepts, so an over-long single file lands alone
+        // instead of growing the chunk count forever.
+        if (bin.entries.length > 0 && bin.chars + entry.chars > charBudget) continue;
+        if (target === null || bin.weight < target.weight) target = bin;
+      }
+      if (target === null) {
+        overflowed = true;
+        break;
+      }
+      target.entries.push(entry);
+      target.weight += entry.weight;
+      target.chars += entry.chars;
+    }
+    if (!overflowed) {
+      return bins
+        .filter((bin) => bin.entries.length > 0)
+        .map((bin) => bin.entries.sort((a, b) => a.index - b.index).map((e) => e.file));
+    }
+    chunkCount++;
+  }
 }
 
 function parseArgs(argv) {
@@ -448,7 +714,7 @@ function main() {
   }
 
   // Shard partitioning (#1212): when --shard i/n is given, keep only this
-  // shard's deterministic round-robin slice of the selected list. Applied
+  // shard's deterministic cost-balanced slice of the selected list. Applied
   // AFTER suite/explicit selection so it composes with --suite (each shard
   // runs i/n of the post-filter selection).
   //
@@ -463,11 +729,35 @@ function main() {
   // from a non-empty list" (total > file count — a valid no-op) from "the
   // selection was already empty before sharding" (a genuinely empty suite,
   // which must still hit the discovery hard-error below — Codex #1212 review).
+  // Loaded before sharding because BOTH layers weigh by it now (#2472): the
+  // shard partition below and the chunk packer further down share this one cost
+  // model. Advisory in both places — a missing table yields uniform weight 1,
+  // which makes the shard partition degenerate to the legacy equal-count split.
+  // Lazily memoized: BOTH layers weigh by it now (#2472) — the shard partition
+  // just below and the chunk packer further down share this one cost model —
+  // but neither should charge a readFileSync + JSON.parse to an invocation that
+  // exits before it needs one (an empty selection, or `--files` with nothing
+  // matched). Memoized so the two consumers still read the table at most once.
+  // Advisory in both places: a missing table yields uniform weight 1, under
+  // which the shard partition degenerates to the legacy equal-count split.
+  let weigherMemo = null;
+  const fileWeightOf = () => {
+    if (weigherMemo === null) {
+      const timingsPath = process.env.RUN_TESTS_TIMINGS_FILE || DEFAULT_TIMINGS_PATH;
+      weigherMemo = makeFileWeigher(loadTestTimings(timingsPath));
+    }
+    return weigherMemo;
+  };
+
   const usingShard = parsed.shard !== null;
   let emptyBeforeShard = false;
+  // The full pre-partition input, kept for the cross-job fingerprint below.
+  // It must be the list every shard job sees, not this job's slice.
+  let shardInput = null;
   if (usingShard) {
     emptyBeforeShard = selectedNames.length === 0;
-    selectedNames = selectShard([...selectedNames].sort(), parsed.shard);
+    shardInput = [...selectedNames].sort();
+    selectedNames = selectShard(shardInput, parsed.shard, fileWeightOf());
   }
 
   const selected = selectedNames.map(f => join(testDir, f));
@@ -536,6 +826,51 @@ function main() {
       .join(' ')}`,
   );
 
+  // Shard diagnostics (#2472). File COUNT stopped being a balance signal the
+  // moment the partition started weighing by cost — two shards can now hold
+  // very different counts by design — so the count line above can no longer be
+  // eyeballed to spot a bad split. Worse, each shard job computes its partition
+  // independently on its own runner: if the inputs differ between jobs (the
+  // file list, or this table), two jobs can place the same file in different
+  // shards, or in none, and every job still looks internally consistent. That
+  // failure is silent — a test simply never runs and CI stays green.
+  //
+  // `sig` is the defense: a cheap fingerprint of the exact inputs the partition
+  // consumed. Every shard job of a given run must print the SAME sig; a
+  // mismatch across jobs is proof the runners disagreed about the input and
+  // therefore about the partition. `weighed` reports how many of this shard's
+  // files matched a real measurement — a table that silently failed to parse
+  // shows weighed=0 instead of being indistinguishable from a healthy load.
+  if (usingShard) {
+    const weigher = fileWeightOf();
+    const table = loadTestTimings(process.env.RUN_TESTS_TIMINGS_FILE || DEFAULT_TIMINGS_PATH);
+    const mine = selectedNames.map(f => f.split(/[\\/]/).pop());
+    const weighed = table
+      ? mine.filter(n => Object.hasOwn(table.timings, n)).length
+      : 0;
+    const myWeight = mine.reduce((sum, n) => sum + weigher(n), 0);
+    // Fingerprint the FULL pre-partition input — the file list and the weight
+    // each file was assigned — NOT this shard's slice. Every shard job of one
+    // run must print an identical sig; a mismatch is proof the runners
+    // disagreed about the input, which is the only way the union of shards can
+    // silently drop or duplicate a file. Order-independent sum of per-file
+    // (name, weight) hashes: stable across platforms, cheap for ~600 files.
+    let sig = 0;
+    for (const n of shardInput.map(f => f.split(/[\\/]/).pop())) {
+      let h = 2166136261;
+      for (let i = 0; i < n.length; i += 1) {
+        h = Math.imul(h ^ n.charCodeAt(i), 16777619);
+      }
+      sig = (sig + (h >>> 0) + Math.round(weigher(n) * 1000)) % 0xffffffff;
+    }
+    console.error(
+      `run-tests: shard=${parsed.shard.index}/${parsed.shard.total} `
+      + `files=${mine.length}/${shardInput.length} weighed=${weighed} `
+      + `weight=${myWeight.toFixed(2)} table=${table ? 'loaded' : 'absent'} `
+      + `sig=${sig.toString(16)}`,
+    );
+  }
+
   // Default concurrency: 4 on Linux/macOS, 2 on Windows.
   //
   // Windows has significantly higher per-subprocess overhead than Linux/macOS:
@@ -559,9 +894,10 @@ function main() {
   // fine there. Split into chunks sized for the tightest target so behavior
   // is identical across platforms. (#3597)
   // Operator override (also used by tests to force chunking with short paths).
-  const MAX_CMDLINE_CHARS = process.env.RUN_TESTS_MAX_CMDLINE_CHARS
-    ? Number(process.env.RUN_TESTS_MAX_CMDLINE_CHARS)
-    : 28000; // headroom below the 32,767 Windows ceiling
+  const MAX_CMDLINE_CHARS = positiveNumberEnv(
+    process.env.RUN_TESTS_MAX_CMDLINE_CHARS,
+    28000, // headroom below the 32,767 Windows ceiling
+  );
   // A full-lane shard (~171 files) fit in ONE chunk at the old cap of 180, so the
   // entire shard's wall-clock ran against a single per-chunk timeout. On the slow
   // Windows runner the install-heavy files in a shard (e.g. install-minimal-hooks
@@ -574,26 +910,31 @@ function main() {
   // node process (also relieving per-process memory pressure from 170+ files at once).
   // Lowered from 90 to 60 after #1575 — macOS Node 22 shard 2/3 chunk 2 (~80 files
   // including state.test.cjs, perf-*, worktree-cleanup) exceeded 600s with 90.
-  const MAX_FILES_PER_CHUNK = process.env.RUN_TESTS_MAX_FILES_PER_CHUNK
-    ? Number(process.env.RUN_TESTS_MAX_FILES_PER_CHUNK)
-    : 60;
-  // #2088: file COUNT is a poor proxy for a chunk's wall-clock — install-heavy
-  // files (real installs; install-minimal-hooks.test.cjs alone runs ~250 cases
-  // doing dozens of installs) are ~10× a unit file. When several land in the SAME
-  // chunk — e.g. a PR touching the whole install surface, whose *targeted* lane is
-  // unsharded (13 install-heavy files → one chunk) — that chunk blows the 600s
-  // backstop while unit-only chunks finish in seconds. WEIGHT install-heavy files
-  // so they fill a chunk's budget faster and therefore SPREAD across chunks
-  // instead of clustering. Light files keep weight 1, so pure-unit chunking (and
-  // its harness tests) is byte-for-byte unchanged. `MAX_FILES_PER_CHUNK` is now a
-  // per-chunk WEIGHT budget (backwards-compatible: it equals the file count when
-  // every file is light). Tune via RUN_TESTS_HEAVY_FILE_WEIGHT; classify via the
-  // basename prefix (install*/installer*/codex-* are the real install-heavy suites).
-  const HEAVY_TEST_RE = /^(?:install|codex-)/;
-  const HEAVY_FILE_WEIGHT = process.env.RUN_TESTS_HEAVY_FILE_WEIGHT
-    ? Number(process.env.RUN_TESTS_HEAVY_FILE_WEIGHT)
-    : 12;
-  const fileWeight = (f) => (HEAVY_TEST_RE.test(basename(f)) ? HEAVY_FILE_WEIGHT : 1);
+  const MAX_FILES_PER_CHUNK = positiveNumberEnv(process.env.RUN_TESTS_MAX_FILES_PER_CHUNK, 60);
+  // #2088 established that file COUNT is a poor proxy for a chunk's wall-clock:
+  // install-heavy files (real installs) cost ~10x a unit file, and when several
+  // land in the SAME chunk it blows the 600s backstop while unit-only chunks
+  // finish in seconds. #2088 approximated cost from the filename — basename
+  // matching /^(?:install|codex-)/ scored 12, everything else 1.
+  //
+  // #2456: that approximation is miscalibrated in BOTH directions, so chunks were
+  // still balanced by file count rather than by cost. Measured durations show
+  // installer-migration-authoring.test.cjs scoring 12 while running ~0.1s, and the
+  // two heaviest files in the whole suite scoring 1 — run-tests-harness.test.cjs
+  // (never matched the prefix) and release-tarball-smoke.install.test.cjs (the
+  // regex is anchored to the START of the basename, so a mid-name "install" never
+  // matches). Both landed in the same chunk, leaving the slowest chunk ~3.9x the
+  // lightest and sitting near the timeout.
+  //
+  // Weight each file by its MEASURED duration instead. `MAX_FILES_PER_CHUNK`
+  // remains the per-chunk weight budget and keeps its scale — weights are
+  // normalized so an average-cost file weighs 1 — so an all-uniform suite chunks
+  // exactly as it did before. Timings are ADVISORY, never gated: an unknown file
+  // falls back to the table's median weight and a missing table falls back to
+  // uniform weight 1, so staleness degrades chunk BALANCE gracefully instead of
+  // failing CI. Regenerate via `node scripts/gen-test-timings.cjs <events.jsonl>`.
+  // The cost table is loaded lazily above and memoized; both the shard
+  // partition and this packer consume the same weigher (#2472).
 
   // node:test does not exit until the event loop drains. A unit test that leaks
   // an open handle (un-terminated Worker, un-killed child_process, ref'd timer)
@@ -609,35 +950,19 @@ function main() {
   const forceExit = nodeMajor >= 22 && !process.env.RUN_TESTS_NO_FORCE_EXIT;
 
   const FIXED_OVERHEAD = process.execPath.length + '--test'.length + concurrency.length + (forceExit ? '--test-force-exit'.length + 1 : 0) + 8;
-  const chunks = [];
-  let current = [];
-  let currentLen = FIXED_OVERHEAD;
-  let currentWeight = 0;
-  for (const file of selected) {
-    const add = file.length + 1; // +1 for the inter-arg separator
-    if (
-      current.length > 0 &&
-      (currentLen + add > MAX_CMDLINE_CHARS || currentWeight >= MAX_FILES_PER_CHUNK)
-    ) {
-      chunks.push(current);
-      current = [];
-      currentLen = FIXED_OVERHEAD;
-      currentWeight = 0;
-    }
-    current.push(file);
-    currentLen += add;
-    currentWeight += fileWeight(file); // heavy install files count for more
-  }
-  if (current.length > 0) chunks.push(current);
+  const chunks = packChunks(selected, {
+    weightOf: fileWeightOf(),
+    maxWeight: MAX_FILES_PER_CHUNK,
+    maxChars: MAX_CMDLINE_CHARS,
+    fixedOverhead: FIXED_OVERHEAD,
+  });
 
   // A chunk that still hangs (a leak the backstop somehow misses, or a wedged
   // subprocess) must fail loudly rather than silently burn the job's wall-clock
   // budget until the CI runner cancels the whole job. Default 10 min per chunk:
   // well above a healthy chunk (~4-5 min on the windows lane) but below the 20m
   // job cap. Operator/test override via RUN_TESTS_CHUNK_TIMEOUT_MS.
-  const chunkTimeoutMs = process.env.RUN_TESTS_CHUNK_TIMEOUT_MS
-    ? Number(process.env.RUN_TESTS_CHUNK_TIMEOUT_MS)
-    : 600000;
+  const chunkTimeoutMs = positiveNumberEnv(process.env.RUN_TESTS_CHUNK_TIMEOUT_MS, 600000);
 
   let firstFailureExit = 0;
   for (let i = 0; i < chunks.length; i++) {
@@ -673,9 +998,35 @@ function main() {
         );
       }
       const code = err.status || 1;
-      // Run every chunk so the operator sees all failures in one pass; report
-      // the first non-zero exit at the end.
       if (firstFailureExit === 0) firstFailureExit = code;
+      if (timedOut) {
+        // A timeout has already burned a large share of the job's budget
+        // (chunkTimeoutMs defaults to 600000ms, i.e. half the 20m CI job
+        // cap), so — unlike an ordinary test failure — letting the loop
+        // fall through to the remaining chunks risks the CI runner
+        // cancelling the whole job before they finish. That cancellation
+        // replaces the loud, specific diagnostic printed above with an
+        // opaque "The operation was canceled." buried at the very end of
+        // the log, thousands of lines past the real cause (observed live on
+        // CI run 29749380190: chunk 1/5 timed out, the loop pressed on
+        // through chunks 2-4, and the job was cancelled mid-chunk-5 — the
+        // timeout message was ~38,000 log lines from the end and
+        // `gh run view --log-failed` returned nothing). Abort the remaining
+        // chunks instead so the operator actually sees this message.
+        const skipped = chunks.length - (i + 1);
+        if (skipped > 0) {
+          console.error(
+            `run-tests: aborting — skipping the remaining ${skipped} chunk${skipped === 1 ? '' : 's'} ` +
+              `after the chunk ${i + 1}/${chunks.length} timeout rather than risk the CI runner ` +
+              `cancelling the job (and burying this diagnostic) before they finish.`,
+          );
+        }
+        break;
+      }
+      // A non-timeout failure is cheap in wall-clock terms (the child exits
+      // promptly on its own), so — unlike the timeout case above — run every
+      // remaining chunk anyway: the operator sees all failures in one pass,
+      // and the first non-zero exit is reported at the end.
     }
   }
   if (firstFailureExit !== 0) return firstFailureExit;
@@ -685,4 +1036,15 @@ if (require.main === module) {
   runMain(main);
 }
 
-module.exports = { suiteOf, ensureBuiltArtifacts, ensureBuiltHooks, parseShardArg, selectShard };
+module.exports = {
+  suiteOf,
+  ensureBuiltArtifacts,
+  ensureBuiltHooks,
+  parseShardArg,
+  selectShard,
+  positiveNumberEnv,
+  loadTestTimings,
+  makeFileWeigher,
+  packChunks,
+  DEFAULT_TIMINGS_PATH,
+};

package/skills/gsd-ai-integration-phase/SKILL.md

@@ -28,7 +28,7 @@ Flow: Select Framework → Research Docs → Research Domain → Design Eval Str
 </execution_context>
 
 <context>
-Phase number: $ARGUMENTS — optional, auto-detects next unplanned phase if omitted.
+Phase number: $ARGUMENTS — optional; when omitted, the orchestrating workflow reads ROADMAP.md and selects the next unplanned phase. This is not a `gsd-tools.cjs` CLI feature — the CLI's phase-lookup primitives require an explicit phase number.
 </context>
 
 <process>

package/skills/gsd-mempalace-capture/SKILL.md

@@ -64,12 +64,16 @@ On any error or timeout, stop and let the phase continue -- capture is best-effo
    # One-time: declare the GSD room taxonomy so detect_room() recognizes these folders
    mkdir -p "$STAGE"
    [ -f "$STAGE/mempalace.yaml" ] || cat > "$STAGE/mempalace.yaml" <<'YAML'
+   # Each entry MUST be a dict with a `name` key (the miner's detect_room()
+   # indexes room["name"] — a bare-string list crashes _mine_impl with
+   # TypeError: string indices must be integers, not 'str'). Optional fields:
+   # `description`, `keywords` (matched against folder-path segments).
    rooms:
-     - decisions
-     - planning
-     - milestones
-     - problems
-     - general
+     - name: decisions
+     - name: planning
+     - name: milestones
+     - name: problems
+     - name: general
    YAML
    # Suppress MemPalace cache artifacts written into the scanned tree
    [ -f "$STAGE/.gitignore" ] || echo "mempalace_embedder.json" > "$STAGE/.gitignore"

package/skills/gsd-new-milestone/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-new-milestone
 description: "Start a new milestone cycle — update PROJECT.md and route to requirements"
-argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
+argument-hint: "[milestone name, e.g., 'v1.1 Notifications'] [--ws <name>]"
 allowed-tools:
   - Read
   - Write

package/skills/gsd-plan-phase/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gsd-plan-phase
 description: "Create detailed phase plan (PLAN.md) with verification loop"
-argument-hint: "[phase] [--auto] [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--tdd] [--mvp]"
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--research-phase <N>] [--view] [--gaps] [--skip-verify] [--prd <file>] [--ingest <path-or-glob>] [--ingest-format <auto|nygard|madr|narrative>] [--reviews] [--text] [--tdd] [--mvp] [--no-tracer] [--no-reversibility-gates]"
 effort: max
 allowed-tools:
   - Read
@@ -40,7 +40,7 @@ Create executable phase prompts (PLAN.md files) for a roadmap phase with integra
 </runtime_note>
 
 <context>
-Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omitted)
+Phase number: $ARGUMENTS (optional — when omitted, the orchestrating workflow reads ROADMAP.md and selects the next unplanned phase; `gsd-tools.cjs` itself has no auto-detect feature and requires an explicit phase number)
 
 **Flags:**
 - `--research` — Force re-research even if RESEARCH.md exists
@@ -52,7 +52,9 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit
 - `--ingest-format <auto|nygard|madr|narrative>` — Optional ADR parser format override (`auto` default).
 - `--reviews` — Replan incorporating cross-AI review feedback from REVIEWS.md (produced by `/gsd-review`)
 - `--text` — Use plain-text numbered lists instead of TUI menus (required for `/rc` remote sessions)
-- `--mvp` — Vertical MVP mode. Planner organizes tasks as feature slices (UI→API→DB) instead of horizontal layers. On Phase 1 of a new project, also emits `SKELETON.md` (Walking Skeleton). Can be persisted on a phase via `**Mode:** mvp` in ROADMAP.md.
+- `--mvp` — MVP enrichment on top of the default tracer-first ordering: frames the phase goal as a user story and, on Phase 1 of a new project, also emits `SKELETON.md` (Walking Skeleton). Vertical slicing itself is now the default (see `--no-tracer`); `--mvp` no longer *turns it on*. Can be persisted on a phase via `**Mode:** mvp` in ROADMAP.md.
+- `--no-tracer` — Opt out of the default **tracer-first** decomposition and plan horizontal layers (the legacy default). By default every plan LEADS with one production-quality end-to-end `tracer` slice that is verified before any expansion task.
+- `--no-reversibility-gates` — Suppress the human checkpoint that a **one-way-door** decision normally earns, for runs you intend to leave unattended. By default a decision rated `one-way` (undo needs a migration, breaks a published contract, or is impossible) gets a `checkpoint:decision` before the task implementing it. Ratings are still recorded on tasks and `costly` items still flagged — the flag changes what stops the run, not what the plan remembers.
 
 Normalize phase input in step 2 before any directory lookups.
 </context>