@opengsd/gsd-core 1.17.0 → 1.18.0

package/scripts/diagnose-validate-commit-phases.cjs

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * #5473 — where does hooks/gsd-validate-commit.sh spend its time on a 112KB
+ * whitespace-padded command under /bin/bash 3.2 (macOS)?
+ *
+ * tests/hooks-opt-in.test.cjs's "suffix window still sees an option after a
+ * 112KB command" row costs ~5s on the macOS conformance job against a 10s
+ * kill bound, and ~12x the same-size unpadded row. This script runs the real
+ * hook two ways per scenario and prints where the time goes:
+ *
+ *   - untraced: wall time of the hook exactly as the test runs it, repeated
+ *               (min / median / max), because the effect under study is
+ *               noisy on a shared runner;
+ *   - traced:   a copy of the hooks directory whose hook has one line inserted
+ *               after its shebang (PS4 assigned, xtrace on), so every command
+ *               is stamped with an epoch millisecond, its line number and its
+ *               function (scripts/xtrace-phase-timing.cjs turns the stamps
+ *               into per-line and per-region costs, shifted back to the
+ *               hook's own line numbers).
+ *
+ * Reading the traced numbers: every traced command pays one stamp (a perl
+ * spawn), measured and reported below, and xtrace prints each 112KB expansion,
+ * a cost the untraced run does not have. The traced span is therefore NOT
+ * comparable to the untraced wall time; use it to RANK lines, not to total them.
+ * A gap is the previous command's execution plus the next command's expansion,
+ * so each line carries two numbers (see xtrace-phase-timing.cjs).
+ *
+ * `--load N` runs N processes that fork node in a loop alongside the hook,
+ * standing in for the conformance tier's `--test-concurrency=4` (four test
+ * files, most of them spawning subprocesses) on a small runner.
+ *
+ * It exits 1 if it could not produce a usable trace (so a broken diagnostic
+ * is a red step, not a silent empty report); it asserts nothing about the
+ * numbers. A hook run that exceeds its bound is killed and reported, not thrown.
+ */
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+const {
+  stampPs4,
+  TRACE_PS4_FILE,
+  INJECTED_LINES,
+  injectTracing,
+  parseTimedXtrace,
+  shiftLines,
+  phaseCosts,
+  slowestLines,
+  rollupByRegion,
+  abbreviate,
+} = require('./xtrace-phase-timing.cjs');
+
+const HOOKS_DIR = path.join(__dirname, '..', 'hooks');
+const HOOK_NAME = 'gsd-validate-commit.sh';
+const HOOK = path.join(HOOKS_DIR, HOOK_NAME);
+const BASH = '/bin/bash';
+const HOOK_BOUND_MS = 30000;
+const PROBE_BOUND_MS = 10000;
+const MAX_TRACE_BYTES = 256 * 1024 * 1024;
+const MAX_LOAD = 64;
+const UNTRACED_RUNS = 3;
+const CALIBRATION_COMMANDS = 200;
+const REGION_LINES = 50;
+const LOAD_LIFETIME_MS = 5 * 60 * 1000;
+// Mirrors the test: 112KB stays under Linux's MAX_ARG_STRLEN (131072).
+const PAD_BYTES = 112 * 1024;
+// Millisecond clock for bash 3.2, which has neither EPOCHREALTIME nor printf %(%s)T.
+// perl, not node: it is stamped once per traced command, and node's ~40ms startup
+// would dwarf the costs being measured.
+// LC_ALL=C and 2>/dev/null: perl prints a locale warning to stderr on EVERY stamp
+// when the inherited LANG/LC_* names a locale the machine lacks, and stderr is
+// the trace stream, so each warning would corrupt the command it follows.
+const STAMP_COMMAND = "LC_ALL=C perl -MTime::HiRes=time -e 'printf \"%d\", time*1000' 2>/dev/null";
+
+const bodyOf = (kb) =>
+  Array.from({ length: Math.ceil((kb * 1024) / 63) }, () => 'x'.repeat(62)).join('\n');
+
+/** Same command shapes as tests/hooks-opt-in.test.cjs (#4492 rows). */
+function scenarios() {
+  const base = `git commit -m "$(cat${' '.repeat(PAD_BYTES)} <<'EOF'\nfeat: x\nEOF\n)"`;
+  return [
+    { name: 'padded control (no trailing option)', command: base },
+    { name: 'padded + trailing --cleanup=verbatim', command: `${base} --cleanup=verbatim` },
+    {
+      name: 'unpadded 112KB body (comparison)',
+      command: `git commit --allow-empty -m "$(cat <<'EOF'\nfeat: ${'x'.repeat(66)}\n${bodyOf(112)}\nEOF\n)"`,
+    },
+  ];
+}
+
+function parseArgs(argv) {
+  const opts = { load: 0, top: 15 };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg !== '--load' && arg !== '--top') {
+      throw new ExitError(2, `diagnose-validate-commit-phases: unknown argument "${arg}"`);
+    }
+    const value = Number(argv[++i]);
+    if (!Number.isInteger(value) || value < 0) {
+      throw new ExitError(2, `diagnose-validate-commit-phases: ${arg} needs a non-negative integer`);
+    }
+    if (arg === '--load' && value > MAX_LOAD) {
+      throw new ExitError(2, `diagnose-validate-commit-phases: --load is capped at ${MAX_LOAD}`);
+    }
+    opts[arg === '--load' ? 'load' : 'top'] = value;
+  }
+  return opts;
+}
+
+function makeProject() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-5473-'));
+  fs.mkdirSync(path.join(dir, '.planning', 'phases'), { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, '.planning', 'config.json'),
+    JSON.stringify({ model_profile: 'balanced', hooks: { community: true } }),
+  );
+  return dir;
+}
+
+/**
+ * A copy of the hooks directory whose hook carries the tracing line, the PS4
+ * text beside it, and a no-op script for calibrating the stamp. Returns the
+ * paths of the traced hook and the no-op.
+ *
+ * The hook's lib/git-cmd.js requires `../../gsd-core/bin/lib/token-scanner.cjs`
+ * relative to itself, so the copy sits at `<project>/hooks` with `<project>/gsd-core`
+ * linked to the real one. Without that link the classifier fails to load and the
+ * hook FAILS OPEN: a traced run would take a different path than the real one
+ * (the parity test in tests/xtrace-phase-timing.test.cjs pins this).
+ */
+function prepareTracedHooks(project, ps4) {
+  const dir = path.join(project, 'hooks');
+  fs.cpSync(HOOKS_DIR, dir, { recursive: true });
+  fs.symlinkSync(path.join(HOOKS_DIR, '..', 'gsd-core'), path.join(project, 'gsd-core'), 'dir');
+  const hook = path.join(dir, HOOK_NAME);
+  fs.writeFileSync(hook, injectTracing(fs.readFileSync(HOOK, 'utf8')));
+  fs.writeFileSync(path.join(dir, TRACE_PS4_FILE), ps4);
+  const noop = path.join(dir, 'noop.sh');
+  const colons = Array.from({ length: CALIBRATION_COMMANDS }, () => ':').join('\n');
+  fs.writeFileSync(noop, injectTracing(`#!/bin/bash\n${colons}\n`));
+  return { hook, noop };
+}
+
+function hookEnv() {
+  return {
+    ...process.env,
+    PATH: `${path.dirname(process.execPath)}:${process.env.PATH || '/usr/bin:/bin'}`,
+  };
+}
+
+/** bash with the options every call here shares; `options` overrides them. */
+function spawnBash(args, options, bin = BASH) {
+  return spawnSync(bin, args, { encoding: 'utf8', killSignal: 'SIGKILL', timeout: PROBE_BOUND_MS, ...options });
+}
+
+/**
+ * Run the hook script at `script` on `command`. stdout is discarded and a
+ * traced run's stderr goes to a FILE, never a pipe: the hook's node classifier
+ * inherits both, and a grandchild that outlives the kill would otherwise hold
+ * the pipe open and hang this process past its bound (the real test avoids that
+ * with a process-group kill; spawnSync cannot).
+ */
+function runHook(project, command, script, traced, env = hookEnv(), bin = BASH) {
+  const traceFile = path.join(project, 'trace.err');
+  const traceFd = traced ? fs.openSync(traceFile, 'w') : null;
+  const started = process.hrtime.bigint();
+  let r;
+  try {
+    r = spawnBash([script], {
+      cwd: project,
+      env,
+      input: JSON.stringify({ tool_input: { command } }),
+      stdio: ['pipe', 'ignore', traceFd === null ? 'ignore' : traceFd],
+      timeout: HOOK_BOUND_MS,
+    }, bin);
+  } finally {
+    if (traceFd !== null) fs.closeSync(traceFd);
+  }
+  const wallMs = Number((process.hrtime.bigint() - started) / 1000000n);
+  let trace = '';
+  let error = r.error ? r.error.code || r.error.message : null;
+  if (traced) {
+    if (fs.statSync(traceFile).size > MAX_TRACE_BYTES) error = error || 'trace exceeds the size cap';
+    else trace = fs.readFileSync(traceFile, 'utf8');
+  }
+  return { wallMs, status: r.status, signal: r.signal, error, trace };
+}
+
+/** Cost of one stamp: a run of no-op commands under the same PS4. */
+function calibrateStampMs(noop, nonce) {
+  const r = spawnBash([noop], { env: hookEnv() });
+  const { totalMs } = phaseCosts(parseTimedXtrace(r.stderr || '', nonce));
+  return totalMs / CALIBRATION_COMMANDS;
+}
+
+function median(sorted) {
+  return sorted[Math.floor(sorted.length / 2)];
+}
+
+/** Processes that keep forking node, like a tier of subprocess-spawning test files. */
+function startLoad(count) {
+  const churn =
+    "const {spawnSync}=require('node:child_process');" +
+    `const end=Date.now()+${LOAD_LIFETIME_MS};` +
+    "while(Date.now()<end){spawnSync(process.execPath,['-e','0'],{stdio:'ignore'});}";
+  return Array.from({ length: count }, () => spawn(process.execPath, ['-e', churn], { stdio: 'ignore' }));
+}
+
+function stopLoad(children) {
+  for (const child of children) child.kill('SIGKILL');
+}
+
+function bashVersionLine() {
+  return (spawnBash(['--version']).stdout || 'unknown').split('\n')[0];
+}
+
+/** Escape a value for a markdown table cell: backslash first, then the pipe. */
+const cell = (s) => String(s).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+
+/** Where a cost row points: the hook line and its source, or the function. */
+function whereCell(c, source) {
+  if (c.fn) return { line: `${c.fn}():${c.line}`, text: '(line may be function-relative)' };
+  return { line: String(c.line), text: abbreviate(source[c.line - 1] || '', 70) };
+}
+
+/** Run one scenario untraced (repeated) and traced; no formatting. */
+function measureScenario(project, scenario, hooks, nonce, bin = BASH) {
+  const walls = [];
+  let last = null;
+  for (let i = 0; i < UNTRACED_RUNS; i++) {
+    last = runHook(project, scenario.command, HOOK, false, hookEnv(), bin);
+    walls.push(last.wallMs);
+  }
+  walls.sort((a, b) => a - b);
+  const traced = runHook(project, scenario.command, hooks.hook, true, hookEnv(), bin);
+  const entries = shiftLines(parseTimedXtrace(traced.trace, nonce), INJECTED_LINES);
+  const { costs, totalMs } = phaseCosts(entries);
+  return { scenario, walls, last, traced, entries: entries.length, costs, totalMs };
+}
+
+function renderScenario(m, source, opts) {
+  const { scenario, walls, last, traced } = m;
+  const out = [`## ${scenario.name}`, ''];
+  out.push(
+    `untraced wall ms (${UNTRACED_RUNS} runs): min ${walls[0]} / median ${median(walls)} / max ${walls[walls.length - 1]}` +
+    ` (last exit ${last.status}${last.signal ? `, ${last.signal}` : ''}${last.error ? `, ${last.error}` : ''}); ` +
+    `traced span ${m.totalMs} ms over ${m.entries} commands${traced.signal ? ` (${traced.signal})` : ''}${traced.error ? ` (${traced.error})` : ''}; ` +
+    `command ${scenario.command.length} bytes`,
+    '',
+  );
+  if (m.entries === 0) {
+    out.push('**TRACE EMPTY** — no stamped commands were parsed; the numbers below do not exist.', '');
+    return out;
+  }
+  out.push(`Elapsed per ${REGION_LINES}-line region of the hook (ms):`, '');
+  out.push('| region | ms |', '|---|---:|');
+  for (const r of rollupByRegion(m.costs, REGION_LINES)) out.push(`| ${r.label} | ${r.afterMs} |`);
+  out.push('');
+  out.push('Slowest lines. `after` = gap following the line (slow EXECUTION); `before` = gap preceding it (slow EXPANSION):', '');
+  out.push('| hook line | after ms | before ms | runs | source | traced value |');
+  out.push('|---:|---:|---:|---:|---|---|');
+  for (const c of slowestLines(m.costs, opts.top)) {
+    const where = whereCell(c, source);
+    out.push(`| ${cell(where.line)} | ${c.afterMs} | ${c.beforeMs} | ${c.count} | \`${cell(where.text)}\` | \`${cell(abbreviate(c.sample, 60))}\` |`);
+  }
+  out.push('');
+  return out;
+}
+
+/**
+ * The full report. `scenarioList` is injectable so the tests can drive the
+ * whole pipeline on a cheap command; the CLI uses the three #4492 rows.
+ *
+ * @returns {{ text: string, ok: boolean }} ok is false if any scenario's trace was empty.
+ */
+function report(opts, scenarioList = scenarios()) {
+  const project = makeProject();
+  const source = fs.readFileSync(HOOK, 'utf8').split('\n');
+  const nonce = crypto.randomBytes(6).toString('hex');
+  const hooks = prepareTracedHooks(project, stampPs4(STAMP_COMMAND, nonce));
+  const versionLine = bashVersionLine();
+  const out = ['# validate-commit phase timing (#5473)', ''];
+  out.push(`- shell: \`${BASH}\` (${versionLine})`);
+  if (!/version 3\.2/.test(versionLine)) {
+    out.push('- **WARNING: this is not bash 3.2, the shell the macOS failure occurs under; numbers do not reproduce it.**');
+  }
+  out.push(`- platform: ${process.platform}/${process.arch}, ${os.cpus().length} cpus, node ${process.version}`);
+  out.push(`- background load: ${opts.load} process(es) forking node`);
+  out.push(`- stamp overhead: ${calibrateStampMs(hooks.noop, nonce).toFixed(1)} ms per traced command (measured over ${CALIBRATION_COMMANDS} no-ops)`);
+  out.push('- traced numbers rank lines; they are not comparable to untraced wall time (every command pays a stamp and xtrace prints each 112KB expansion)', '');
+  const load = startLoad(opts.load);
+  const measured = [];
+  try {
+    for (const scenario of scenarioList) measured.push(measureScenario(project, scenario, hooks, nonce));
+  } finally {
+    stopLoad(load);
+    fs.rmSync(project, { recursive: true, force: true });
+  }
+  if (measured.length >= 2) {
+    const first = measured[0];
+    const last = measured[measured.length - 1];
+    const ratio = median(last.walls) > 0 ? (median(first.walls) / median(last.walls)).toFixed(1) : 'n/a';
+    out.push(`- untraced median: "${first.scenario.name}" ${median(first.walls)} ms vs "${last.scenario.name}" ${median(last.walls)} ms (ratio ${ratio}x)`, '');
+  }
+  for (const m of measured) out.push(...renderScenario(m, source, opts));
+  return { text: out.join('\n'), ok: measured.every((m) => m.entries > 0) };
+}
+
+function run(argv = process.argv.slice(2)) {
+  if (process.platform === 'win32') {
+    throw new ExitError(2, 'diagnose-validate-commit-phases: needs a unix /bin/bash (macOS or Linux)');
+  }
+  if (!fs.existsSync(BASH)) {
+    throw new ExitError(2, `diagnose-validate-commit-phases: ${BASH} not found`);
+  }
+  const { text, ok } = report(parseArgs(argv));
+  process.stdout.write(`${text}\n`);
+  const summary = process.env.GITHUB_STEP_SUMMARY;
+  if (summary) fs.appendFileSync(summary, `${text}\n`);
+  return ok ? 0 : 1;
+}
+
+module.exports = {
+  scenarios,
+  parseArgs,
+  whereCell,
+  renderScenario,
+  report,
+  prepareTracedHooks,
+  makeProject,
+  hookEnv,
+  runHook,
+  median,
+  measureScenario,
+  MAX_LOAD,
+  STAMP_COMMAND,
+  HOOKS_DIR,
+  HOOK,
+  HOOK_NAME,
+  HOOK_BOUND_MS,
+};
+
+if (require.main === module) runMain(run);

package/scripts/diagnose-windows-spawn-watcher.cjs

@@ -0,0 +1,317 @@
+'use strict';
+
+/**
+ * #5473 — a job-long watcher for the Windows conformance tier's bounded-child stalls.
+ *
+ * In one Windows run (job 39083981500) three different tests each hit their
+ * bound EXACTLY: the #4784 `sh -c 'printf | sed | head -1'` at 10 s, an
+ * `echo | grep | awk` bash pipeline at 5 s, and `npm ls` through cmd.exe at 30 s.
+ * Measured inside the tier, a bare `bash` starts in ~35 ms, Defender real-time
+ * protection is off, and 2,407 pipeline calls under 6-way concurrency never
+ * stalled past 2 s. So the stall is rare and does not reproduce on demand. This
+ * watcher runs beside the whole test step on the same VM and writes down, with a
+ * UTC wall-clock timestamp, every moment the VM itself stops making progress:
+ *
+ *   - `loop-gap`: this process's own timer fired more than LOOP_GAP_MS late
+ *     (the whole VM, or at least this process, was not scheduled);
+ *   - `probe-slow`: a probe child (the #4784 sh pipeline, or `cmd /c exit`)
+ *     took more than PROBE_SLOW_MS, or hit its bound;
+ *   - `procs`: a snapshot of the live node/sh/bash/cmd/npm/git processes (name,
+ *     parent, age, CPU time so far, and the *.test.cjs names in their
+ *     arguments), taken after either anomaly and every two minutes, so a stall
+ *     can be lined up with what else was running in the chunk. Earlier red
+ *     `next`s (see defaultMaxUnmeasuredPerChunk in scripts/run-tests.cjs) lost
+ *     whole chunks at 600000 ms with zero failing tests; the periodic snapshots
+ *     show which test file a killed chunk was inside and whether it was idle.
+ *
+ * Timestamps are ISO UTC, the same clock as the lines in the job log, so a
+ * failing test's end time minus its duration can be lined up against these
+ * events: a stall that is the VM freezing shows up here at the same instant; a
+ * stall that is only that one child hanging does not.
+ *
+ *   node scripts/diagnose-windows-spawn-watcher.cjs start [dir]   spawn detached, return at once
+ *   node scripts/diagnose-windows-spawn-watcher.cjs report [dir]  stop it, print and summarize the events
+ *
+ * `dir` defaults to RUNNER_TEMP/spawn-watcher. No environment variable or value
+ * is read into the report. TEMPORARY: delete
+ * with scripts/diagnose-validate-commit-*.cjs once #5473 is resolved.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+const { ExitError, runMain } = require('./lib/cli-exit.cjs');
+
+const TICK_MS = 250;
+const LOOP_GAP_MS = 750;
+// The watcher must not become the load it is looking for: a stall that shows up once in
+// thousands of calls is easy to shift with extra spawn churn, so probes are sparse (one
+// sh and one cmd every 5 s, about 480 pairs over a 40 minute job) and the CIM query,
+// the heavy part, runs every 5 minutes plus at most once a minute after an anomaly.
+const PROBE_EVERY_MS = 5000;
+const PROBE_BOUND_MS = 15_000;
+const PROBE_SLOW_MS = 1500;
+const MAX_LIFETIME_MS = 40 * 60_000;
+const PIPELINE = "printf '%s\\n' x | sed -n 's/x/y/p' | head -1";
+
+const REPORT_WAIT_MS = 20_000;
+const EVENTS_FILE = 'events.log';
+const STOP_FILE = 'stop';
+const SUMMARY_FILE = 'summary.json';
+
+/** One event line: `<ISO UTC> <kind> <ms> <detail>`. */
+function formatEvent(at, kind, ms, detail) {
+  return `${new Date(at).toISOString()} ${kind} ${ms} ${detail}`;
+}
+
+const SHELL_NAMES = new Set(['sh', 'bash', 'cmd']);
+const LINGER_AGE_S = 30;
+
+/**
+ * One compact line for a process snapshot. `rows` are `{pid, ppid, name, born, cpuMs, cmd}`
+ * (born = epoch ms, cmd = the command line). Only what identifies the work is kept: the
+ * process name, its age, its CPU time so far, and the `*.test.cjs` file names in its
+ * arguments (the node:test chunk children carry them). Nothing else from a command line
+ * is reported, because the job environment carries tokens and a report is public.
+ */
+function formatProcs(rows, now) {
+  return rows
+    .map((r) => {
+      const tests = [...new Set(String(r.cmd || '').match(/[\w.-]+\.test\.cjs/g) || [])].slice(0, 3);
+      const age = Math.max(0, Math.round((now - r.born) / 1000));
+      const cpu = Math.round(r.cpuMs / 1000);
+      // A shell that outlives every bound the tests set is the signature of a descendant
+      // still holding a spawnSync stdio pipe: node's timer then reports ETIMEDOUT at the
+      // exact bound although the direct child already exited (node src/spawn_sync.cc).
+      const lingering = SHELL_NAMES.has(r.name) && age > LINGER_AGE_S ? ' LINGERING' : '';
+      return `${r.name}#${r.pid}<${r.ppid} age ${age}s cpu ${cpu}s${lingering}${tests.length ? ` [${tests.join(' ')}]` : ''}`;
+    })
+    .join(' | ');
+}
+
+/** Inverse of formatEvent; null for a line that is not an event. */
+function parseEvent(line) {
+  const m = /^(\d{4}-\d{2}-\d{2}T[\d:.]+Z) (loop-gap|probe-slow|probe-error|procs) (\d+) (.*)$/.exec(line);
+  if (!m) return null;
+  return { at: m[1], kind: m[2], ms: Number(m[3]), detail: m[4] };
+}
+
+/** Counts and extremes per kind, over parsed events. */
+function summarizeEvents(events) {
+  const out = {};
+  for (const e of events) {
+    const s = out[e.kind] || (out[e.kind] = { count: 0, maxMs: 0 });
+    s.count += 1;
+    if (e.ms > s.maxMs) s.maxMs = e.ms;
+  }
+  return out;
+}
+
+/** Percentile (0..1) of numbers, nearest-rank on a sorted copy; null when empty. */
+function percentile(values, p) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
+}
+
+/**
+ * Run one probe child. `onDone(label, ms, timedOut, started, error)`: `error` is the spawn
+ * error code (or the thrown message) when the probe never ran, else null. A probe that
+ * never ran must not look like a fast success, so callers keep it out of the latencies.
+ */
+function probe(label, bin, args, onDone) {
+  const started = Date.now();
+  let timedOut = false;
+  let settled = false;
+  let timer = null;
+  const finish = (error) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    onDone(label, Date.now() - started, timedOut, started, error || null);
+  };
+  let child;
+  try {
+    child = spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+  } catch (e) {
+    finish(`threw ${e && e.code ? e.code : 'error'}`);
+    return;
+  }
+  timer = setTimeout(() => { timedOut = true; try { child.kill('SIGKILL'); } catch { /* gone */ } finish(); }, PROBE_BOUND_MS);
+  child.stdout.resume();
+  child.stderr.resume();
+  child.on('error', (e) => finish(`spawn ${e && e.code ? e.code : 'error'}`));
+  child.on('close', () => finish());
+}
+
+const PS_PROCS = "Get-CimInstance Win32_Process | Where-Object { $_.Name -match '^(node|sh|bash|cmd|npm|git)\\.exe$' } | ForEach-Object { [pscustomobject]@{ pid = $_.ProcessId; ppid = $_.ParentProcessId; name = $_.Name -replace '\\.exe$', ''; born = [int64](([datetime]$_.CreationDate).ToUniversalTime() - [datetime]'1970-01-01').TotalMilliseconds; cpuMs = [int64](($_.KernelModeTime + $_.UserModeTime) / 10000); cmd = $_.CommandLine } } | ConvertTo-Json -Compress";
+const SNAPSHOT_EVERY_MS = 300_000;
+const SNAPSHOT_COOLDOWN_MS = 60_000;
+const SNAPSHOT_BOUND_MS = 30_000;
+
+/** Snapshot the live node/sh/bash/cmd/npm/git processes; calls back with the compact line. */
+function snapshotProcs(onDone) {
+  const started = Date.now();
+  let out = '';
+  let err = '';
+  let child;
+  try {
+    child = spawn('powershell', ['-NoProfile', '-NonInteractive', '-Command', PS_PROCS], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+  } catch (e) {
+    onDone(Date.now() - started, `snapshot unavailable (threw ${e && e.code ? e.code : 'error'})`);
+    return;
+  }
+  const timer = setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, SNAPSHOT_BOUND_MS);
+  child.stdout.on('data', (d) => { out += d; });
+  // PowerShell's own error text carries no command lines; a short head tells a failure from a timeout.
+  child.stderr.on('data', (d) => { if (err.length < 200) err += d; });
+  child.on('error', (e) => { clearTimeout(timer); onDone(Date.now() - started, `snapshot unavailable (spawn ${e && e.code ? e.code : 'error'})`); });
+  child.on('close', (code, signal) => {
+    clearTimeout(timer);
+    let rows = [];
+    try { const parsed = JSON.parse(out); rows = Array.isArray(parsed) ? parsed : [parsed]; } catch { /* no rows */ }
+    // The watcher's own process and its probe/snapshot children are not what we are lining up against.
+    rows = rows.filter((r) => r.pid !== process.pid && r.ppid !== process.pid);
+    const why = signal ? `killed ${signal}` : `exit ${code}`;
+    onDone(
+      Date.now() - started,
+      rows.length ? `${rows.length} procs: ${formatProcs(rows, Date.now())}` : `snapshot unavailable (${why}${err ? `: ${err.replace(/\s+/g, ' ').trim().slice(0, 200)}` : ''})`,
+    );
+  });
+}
+
+function run(dir) {
+  const eventsPath = path.join(dir, EVENTS_FILE);
+  const record = (at, kind, ms, detail) => {
+    try { fs.appendFileSync(eventsPath, `${formatEvent(at, kind, ms, detail)}\n`); } catch { /* dir gone: nothing to do */ }
+  };
+  let lastSnapshotAt = 0;
+  let snapshotting = false;
+  const takeSnapshot = (why) => {
+    const now = Date.now();
+    if (snapshotting || now - lastSnapshotAt < SNAPSHOT_COOLDOWN_MS) return;
+    snapshotting = true;
+    lastSnapshotAt = now;
+    snapshotProcs((ms, detail) => { snapshotting = false; record(Date.now(), 'procs', ms, `${why}: ${detail}`); });
+  };
+  const snapshotTimer = setInterval(() => takeSnapshot('periodic'), SNAPSHOT_EVERY_MS);
+  const lifetimeEnd = Date.now() + MAX_LIFETIME_MS;
+  const probeMs = { sh: [], cmd: [] };
+  let probeCount = 0;
+  let last = Date.now();
+
+  const tick = setInterval(() => {
+    const now = Date.now();
+    const late = now - last - TICK_MS;
+    if (late > LOOP_GAP_MS) { record(now, 'loop-gap', late, `timer fired ${late}ms late`); takeSnapshot('after loop-gap'); }
+    last = now;
+    if (now > lifetimeEnd || fs.existsSync(path.join(dir, STOP_FILE))) finishRun();
+  }, TICK_MS);
+
+  const probeErrors = { sh: 0, cmd: 0 };
+  const onProbe = (label, ms, timedOut, started, error) => {
+    if (error) {
+      probeErrors[label] += 1;
+      record(Date.now(), 'probe-error', ms, `${label} never ran: ${error}`);
+      return;
+    }
+    probeCount += 1;
+    probeMs[label].push(ms);
+    if (ms > PROBE_SLOW_MS || timedOut) {
+      record(Date.now(), 'probe-slow', ms, `${label} started ${new Date(started).toISOString()}${timedOut ? ' hit the bound' : ''}`);
+      takeSnapshot('after probe-slow');
+    }
+  };
+
+  let probing = true;
+  let loopTimer = null;
+  // Run the two probes one after the other, then wait out the rest of the interval.
+  const loop = () => {
+    if (!probing) return;
+    const cycleStart = Date.now();
+    probe('sh', 'sh', ['-c', PIPELINE], (l, ms, to, st, er) => {
+      onProbe(l, ms, to, st, er);
+      probe('cmd', 'cmd', ['/c', 'exit', '0'], (l2, ms2, to2, st2, er2) => {
+        onProbe(l2, ms2, to2, st2, er2);
+        loopTimer = setTimeout(loop, Math.max(0, PROBE_EVERY_MS - (Date.now() - cycleStart)));
+      });
+    });
+  };
+  loop();
+
+  function finishRun() {
+    probing = false;
+    clearInterval(tick);
+    clearInterval(snapshotTimer);
+    clearTimeout(loopTimer);
+    const summary = {
+      probes: probeCount,
+      sh: { n: probeMs.sh.length, errors: probeErrors.sh, median: percentile(probeMs.sh, 0.5), p99: percentile(probeMs.sh, 0.99), max: percentile(probeMs.sh, 1) },
+      cmd: { n: probeMs.cmd.length, errors: probeErrors.cmd, median: percentile(probeMs.cmd, 0.5), p99: percentile(probeMs.cmd, 0.99), max: percentile(probeMs.cmd, 1) },
+    };
+    // Write then rename, so report never sees the file before its content has landed.
+    try {
+      const target = path.join(dir, SUMMARY_FILE);
+      fs.writeFileSync(`${target}.tmp`, JSON.stringify(summary));
+      fs.renameSync(`${target}.tmp`, target);
+    } catch { /* best effort */ }
+    // No process.exit (ADR-3889): every timer is cleared above, so the process ends when the
+    // probe or snapshot child still in flight (each bounded) has exited; report has already
+    // been released by the summary file, so nothing waits on this.
+  }
+}
+
+function start(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  const child = spawn(process.execPath, [__filename, 'run', dir], { detached: true, stdio: 'ignore', windowsHide: true });
+  child.unref();
+}
+
+function report(dir) {
+  try { fs.writeFileSync(path.join(dir, STOP_FILE), ''); } catch { /* start never ran */ }
+  // The stop file is only seen on the watcher's 250ms tick, so a VM stall longer than this
+  // wait (the very case under study) leaves no summary: say so below instead of "crashed".
+  const deadline = Date.now() + REPORT_WAIT_MS;
+  while (!fs.existsSync(path.join(dir, SUMMARY_FILE)) && Date.now() < deadline) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+  }
+  let events = [];
+  try {
+    events = fs.readFileSync(path.join(dir, EVENTS_FILE), 'utf8').split('\n').map(parseEvent).filter(Boolean);
+  } catch { /* no events file: nothing recorded */ }
+  let summary = null;
+  try { summary = JSON.parse(fs.readFileSync(path.join(dir, SUMMARY_FILE), 'utf8')); } catch { /* watcher did not finish */ }
+  const lines = [
+    '### #5473 Windows spawn-stall watcher (whole test step, same VM)',
+    '',
+    summary
+      ? `probes: ${summary.probes} ; sh pipeline median ${summary.sh.median} / p99 ${summary.sh.p99} / max ${summary.sh.max} ms (n=${summary.sh.n}, never ran ${summary.sh.errors}) ; cmd /c exit median ${summary.cmd.median} / p99 ${summary.cmd.p99} / max ${summary.cmd.max} ms (n=${summary.cmd.n}, never ran ${summary.cmd.errors})`
+      : `watcher summary missing after ${REPORT_WAIT_MS / 1000}s: it either crashed or was stalled past the wait (the events below show which: a stall leaves loop-gap/probe-slow lines up to the last tick)`,
+    `events: ${JSON.stringify(summarizeEvents(events))}`,
+    '',
+    ...events.map((e) => `- ${e.at} ${e.kind} ${e.ms}ms ${e.detail}`),
+  ];
+  const text = lines.join('\n');
+  process.stdout.write(`${text}\n`);
+  if (process.env.GITHUB_STEP_SUMMARY) {
+    try { fs.appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${text}\n`); } catch { /* best effort */ }
+  }
+}
+
+// CONTRIBUTING forbids `${{ }}` inside a workflow `run:` block, so the workflow
+// passes no directory: GitHub sets RUNNER_TEMP itself, and start and report agree on it here.
+function defaultDir() {
+  return path.join(process.env.RUNNER_TEMP || require('node:os').tmpdir(), 'spawn-watcher');
+}
+
+function main() {
+  const [, , mode, dirArg] = process.argv;
+  if (!['start', 'run', 'report'].includes(mode)) {
+    throw new ExitError(2, 'usage: diagnose-windows-spawn-watcher.cjs start|report [dir]');
+  }
+  ({ start, run, report })[mode](path.resolve(dirArg || defaultDir()));
+}
+
+if (require.main === module) runMain(main);
+
+module.exports = { formatEvent, formatProcs, parseEvent, summarizeEvents, percentile, LOOP_GAP_MS, PROBE_SLOW_MS };

package/scripts/docs-guard-registry.cjs

@@ -338,12 +338,14 @@ const DOCS_GUARD_TESTS = {
   // (no-pending-3212-markers.test.cjs:37-46), which includes all of docs/ —
   // cannot be resolved to a fixed docs/ path set.
   'tests/no-pending-3212-markers.test.cjs': ['*'],
+  'tests/pause-work-improvements.test.cjs': ['docs/zh-CN/references/git-integration.md'],
   'tests/phase6-capability-docs.test.cjs': ['docs/how-to/develop-a-capability.md', 'docs/README.md'],
   'tests/phase6-review-capabilities.test.cjs': [
     'docs/reference/review-verification-capabilities.md',
     'docs/how-to/develop-a-capability.md',
     'docs/README.md',
   ],
+  'tests/plan-authoring-verification-gaps.test.cjs': ['docs/reference/plan-md.md'],
   'tests/plan-checker-coupling.test.cjs': ['docs/AGENTS.md'],
   'tests/plan-phase-drift-guard.test.cjs': [
     'docs/CONFIGURATION.md',