@marcomigozzi/trailhead 0.17.0 → 0.18.0

package/plugins/trailhead/hooks/lib/issue-body.test.js

@@ -207,6 +207,87 @@ const EMPTY_DECISIONS = ['Intro line for the map, long enough.', '', '## Decisio
   ok('remove numbered: an all-same-number list is not renumbered', lazy.body === sec('1. b', '1. c'));
 }
 
+// --- applyOp: facet stamp ----------------------------------------------------
+{
+  const FACETS = [
+    '# Codebase',
+    '',
+    '## Layout',
+    '',
+    '_as of aaaaaaa_',
+    '',
+    '- `src/` the code',
+    '',
+    '## Stack',
+    '',
+    '- node',
+    '',
+    '## Empty',
+    '',
+    '## Pending',
+    '',
+    '_as of bbbbbbb_',
+    '',
+    '_none yet_',
+    '',
+  ].join('\n');
+  const STAMP = 'abc1234';
+  const stamped = (r) => r.body.split('\n');
+  const section = (body, name) => mod.facetsOf(body).find((f) => f.name === name);
+
+  const ins = applyOp(FACETS, { kind: 'append', section: 'Stack', line: '- more', stamp: STAMP });
+  ok('stamp: insert when the section has none', !ins.error && section(ins.body, 'Stack').sha === STAMP);
+  ok('stamp: inserted as first content, blank line after', /## Stack\n\n_as of abc1234_\n\n- node\n- more\n/.test(ins.body));
+  const rep = applyOp(FACETS, { kind: 'append', section: 'Layout', line: '- `lib/` helpers', stamp: STAMP });
+  ok('stamp: replaces the old stamp', section(rep.body, 'Layout').sha === STAMP && !rep.body.includes('aaaaaaa'));
+  ok('stamp: one stamp line per section', stamped(rep).filter((l) => /^_as of /.test(l)).length === 2);
+  const again = applyOp(rep.body, { kind: 'append', section: 'Layout', line: '- `x/` x', stamp: 'def5678' });
+  ok('stamp: repeat patch never duplicates the stamp', (again.body.match(/_as of def5678_/g) || []).length === 1 && !again.body.includes('abc1234_\n\n- `src/'));
+  ok('stamp: other sections untouched', section(rep.body, 'Stack').text === section(FACETS, 'Stack').text && section(rep.body, 'Pending').sha === 'bbbbbbb');
+  const keep = applyOp(FACETS, { kind: 'append', section: 'Layout', line: '- `lib/` helpers' });
+  ok('stamp: no --stamp keeps the old stamp', section(keep.body, 'Layout').sha === 'aaaaaaa' && (keep.body.match(/_as of aaaaaaa_/g) || []).length === 1);
+  const bare = applyOp(FACETS, { kind: 'append', section: 'Stack', line: '- more' });
+  ok('stamp: no old stamp and no --stamp leaves the section as before', bare.body === FACETS.replace('- node\n', '- node\n- more\n'));
+  const empty = applyOp(FACETS, { kind: 'append', section: 'Empty', line: '- first', stamp: STAMP });
+  ok('stamp: empty section gains stamp and line', section(empty.body, 'Empty').sha === STAMP && /## Empty\n\n_as of abc1234_\n\n- first\n/.test(empty.body));
+  const ph = applyOp(FACETS, { kind: 'append', section: 'Pending', line: '- real', stamp: STAMP });
+  ok('stamp: placeholder under an existing stamp is dropped', !/none yet/.test(ph.body) && section(ph.body, 'Pending').sha === STAMP && /_as of abc1234_\n\n- real\n/.test(ph.body));
+  const phKeep = applyOp(FACETS, { kind: 'append', section: 'Pending', line: '- real' });
+  ok('stamp: placeholder dropped and old stamp kept without --stamp', !/none yet/.test(phKeep.body) && section(phKeep.body, 'Pending').sha === 'bbbbbbb');
+
+  const r1 = applyOp(FACETS, { kind: 'replace', section: 'Layout', text: '- `new/` fresh\n', stamp: STAMP });
+  ok('stamp: replace writes the new content under the supplied stamp', section(r1.body, 'Layout').sha === STAMP && /_as of abc1234_\n\n- `new\/` fresh\n/.test(r1.body) && !r1.body.includes('src/'));
+  const r2 = applyOp(FACETS, { kind: 'replace', section: 'Layout', text: '_as of 1111111_\n\n- `new/` fresh\n', stamp: STAMP });
+  ok('stamp: replace file carrying its own stamp does not duplicate it', (r2.body.match(/_as of /g) || []).length === 2);
+  ok('stamp: replace file stamp is overridden by --stamp', section(r2.body, 'Layout').sha === STAMP && !r2.body.includes('1111111'));
+  const r3 = applyOp(FACETS, { kind: 'replace', section: 'Layout', text: '- `new/` fresh\n' });
+  ok('stamp: replace without --stamp keeps the old stamp', section(r3.body, 'Layout').sha === 'aaaaaaa');
+
+  const rm = applyOp(FACETS.replace('- node\n', '- node\n- go\n'), { kind: 'remove', section: 'Stack', match: '- go', stamp: STAMP });
+  ok('stamp: remove stamps the section', !rm.error && rm.changed && section(rm.body, 'Stack').sha === STAMP && !rm.body.includes('- go'));
+  const noop = applyOp(FACETS, { kind: 'remove', section: 'Stack', match: 'absent', stamp: STAMP });
+  ok('stamp: a no-op remove writes nothing and does not stamp', noop.changed === false && noop.body === FACETS);
+
+  const bad = applyOp(FACETS, { kind: 'append', section: 'Stack', line: 'x', stamp: 'XYZ' });
+  ok('stamp: invalid value is an error', !!bad.error);
+  const pre = applyOp(FACETS, { kind: 'append', section: ':preamble', line: 'x', stamp: STAMP });
+  ok('stamp: preamble is an error', !!pre.error);
+
+  const fenced = ['# C', '', '## Real', '', '_as of aaaaaaa_', '', '```', '## Not a facet', '```', ''].join('\n');
+  const fs2 = mod.facetsOf(fenced);
+  ok('facetsOf: fence-aware, one facet with its sha', fs2.length === 1 && fs2[0].name === 'Real' && fs2[0].sha === 'aaaaaaa');
+  const fl = mod.facetsOf(FACETS);
+  ok('facetsOf: names, shas and null for unstamped', fl.map((f) => f.name).join() === 'Layout,Stack,Empty,Pending' && fl[1].sha === null && fl[0].sha === 'aaaaaaa');
+
+  for (const stamp of ['XYZ', 'ABCDEF1', 'abc12', 'a'.repeat(41), '']) {
+    const r = mod.parseArgs(['append', '--issue', '1', '--section', 'x', '--line', 'y', '--stamp', stamp]);
+    ok(`stamp: parseArgs rejects "${stamp}"`, !!r.error);
+  }
+  ok('stamp: parseArgs rejects :preamble', !!mod.parseArgs(['append', '--issue', '1', '--section', ':preamble', '--line', 'y', '--stamp', 'abc1234']).error);
+  ok('stamp: parseArgs accepts 7 to 40 hex', mod.parseArgs(['append', '--issue', '1', '--section', 'x', '--line', 'y', '--stamp', 'abc1234']).stamp === 'abc1234'
+    && mod.parseArgs(['remove', '--issue', '1', '--section', 'x', '--match', 'y', '--stamp', 'a'.repeat(40)]).stamp === 'a'.repeat(40));
+}
+
 // --- fake tracker ------------------------------------------------------------
 function makeTracker(init = {}) {
   const t = {

package/plugins/trailhead/hooks/lib/needs-you.test.js

@@ -134,8 +134,52 @@ for (const [failOn, later] of [['ensure', ['view', 'comment', 'unassign', 'label
   ok('clear errors on unparseable JSON', run(makeTracker({ badJson: true }), clear).code === 1);
 }
 
+// --- sweep ----------------------------------------------------------------------
+// Tracker con più issue: closed [numeri chiusi con la label], failList, failRemove [numeri].
+function makeSweepTracker(init = {}) {
+  const t = { closed: [...(init.closed || [])], failList: !!init.failList, badJson: !!init.badJson, failRemove: init.failRemove || [], calls: [] };
+  const res = (stdout, status = 0) => ({ status, stdout, stderr: status ? 'forced failure' : '' });
+  t.gh = (args) => {
+    t.calls.push(args.join(' '));
+    const [a, b] = args;
+    if (a === 'issue' && b === 'list') {
+      if (t.failList) return res('', 1);
+      return t.badJson ? res('not json') : res(JSON.stringify(t.closed.map((number) => ({ number }))));
+    }
+    if (a === 'issue' && b === 'edit' && args.includes('--remove-label')) {
+      const n = Number(args[2]);
+      if (t.failRemove.includes(n)) return res('', 1);
+      t.closed = t.closed.filter((x) => x !== n);
+      return res('');
+    }
+    return res('', 1);
+  };
+  return t;
+}
+const sweep = ['sweep', '--repo', 'o/r'];
+{
+  const t = makeSweepTracker({ closed: [85, 12] });
+  const r = run(t, sweep);
+  ok('sweep ok, one JSON line', r.code === 0 && r.json.status === 'ok' && r.out.trim().split('\n').length === 1);
+  ok('sweep clears every closed labelled ticket', JSON.stringify(r.json.cleared) === '[12,85]' && t.closed.length === 0);
+  ok('sweep lists only closed tickets with the label', /^issue list --state closed --label trailhead:needs-you --json number --limit \d+ -R o\/r$/.test(t.calls[0]));
+  ok('sweep passes -R on every call', t.calls.every((c) => c.includes('-R o/r')));
+  const r2 = run(t, sweep);
+  ok('sweep is a no-op when nothing is left', r2.code === 0 && r2.json.cleared.length === 0 && t.calls.filter((c) => /--remove-label/.test(c)).length === 2);
+}
+{
+  const t = makeSweepTracker({ failList: true });
+  const r = run(t, sweep);
+  ok('sweep errors on a failed list, writes nothing', r.code === 1 && r.json.status === 'error' && !t.calls.some((c) => /issue edit/.test(c)));
+  ok('sweep errors on unparseable JSON', run(makeSweepTracker({ badJson: true }), sweep).code === 1);
+  const tp = makeSweepTracker({ closed: [3, 4, 5], failRemove: [4] });
+  const rp = run(tp, sweep);
+  ok('a failed removal is an error naming it, the others still cleared', rp.code === 1 && rp.json.status === 'error' && /#4/.test(rp.json.reason) && JSON.stringify(rp.json.cleared) === '[3,5]');
+}
+
 // --- usage ----------------------------------------------------------------------
-for (const argv of [[], ['bogus'], ['park'], ['park', '--issue', '7', '--repo', 'o/r'], ['park', '--issue', 'x', '--reason', 'r', '--repo', 'o/r'],
+for (const argv of [['sweep'], ['sweep', '--repo', 'nope'], ['sweep', '--repo', 'o/r', '--issue', '7'],
+  [], ['bogus'], ['park'], ['park', '--issue', '7', '--repo', 'o/r'], ['park', '--issue', 'x', '--reason', 'r', '--repo', 'o/r'],
   ['park', '--issue', '7', '--reason', '  ', '--repo', 'o/r'], ['park', '--issue', '7', '--reason', 'r'], ['clear', '--issue', '7'], ['clear', '--repo', 'o/r'],
   ['clear', '--issue', '7', '--repo', 'nope'], ['clear', '--issue', '7', '--repo', 'o/r', '--reason', 'r'], ['clear', '--issue']]) {
   const t = makeTracker();

package/plugins/trailhead/hooks/lib/plan-review-rounds.test.js

@@ -7,6 +7,8 @@
 //   2. round: converged / continue / exhausted / no-progress / ceiling and their precedence.
 //   3. Usage errors (exit 2).
 //   4. End-to-end: the script itself through spawnSync.
+//   5. budget (pre-check of a reviewer prompt) and overflow (post-check of its output). #353.
+//   6. run (a reviewer call under a wall-clock deadline), real stub scripts through spawnSync. #368.
 const assert = require('assert');
 const { spawnSync } = require('child_process');
 const path = require('path');
@@ -316,4 +318,274 @@ ok('round: output is one status ok JSON line with the round count', round([[c('a
   bad.done(); s.done(); rm(bin); rm(dir);
 }
 
+// --- budget ------------------------------------------------------------------
+// A prompt file of exactly n bytes (ASCII), inside its own temp dir.
+function promptFile(n, name = 'brief.md') {
+  const dir = tmp();
+  const file = path.join(dir, name);
+  fs.writeFileSync(file, 'x'.repeat(n));
+  return { dir, file };
+}
+function budget(s, reviewer, n, extra = {}, name) {
+  const p = promptFile(n, name);
+  const r = run(['budget', '--repo', s.root, '--reviewer', reviewer, '--prompt', p.file], { env: { CLAUDE_CONFIG_DIR: s.gdir, PATH: '/nowhere' }, ...extra });
+  rm(p.dir);
+  return { ...r, file: p.file };
+}
+{
+  const s = setup({}, null);
+  const r = budget(s, 'claude', 1000);
+  ok('budget: a small prompt is arg, exit 0, one JSON line', r.code === 0 && r.json.status === 'ok' && r.json.decision === 'arg' && r.out.trim().split('\n').length === 1);
+  ok('budget: reports reviewer, bytes, tokens, window, cap, windowSource', r.json.reviewer === 'claude' && r.json.bytes === 1000 && r.json.tokens === 334 && r.json.window === 200000 && r.json.cap === 130000 && r.json.windowSource === 'default');
+  ok('budget: arg carries no reason and no pointer, and warnings is empty', !('reason' in r.json) && !('pointer' in r.json) && Array.isArray(r.json.warnings) && r.json.warnings.length === 0);
+  ok('budget: bytes === 102400 is still arg', budget(s, 'claude', 102400).json.decision === 'arg');
+  ok('budget: bytes 102401 is file', budget(s, 'claude', 102401).json.decision === 'file');
+  const atCap = budget(s, 'claude', 390000);
+  ok('budget: tokens === cap is not skipped (file for a large prompt)', atCap.json.tokens === 130000 && atCap.json.decision === 'file');
+  const over = budget(s, 'claude', 390001);
+  ok('budget: tokens === cap + 1 is skip', over.json.tokens === 130001 && over.json.decision === 'skip');
+  ok('budget: skip carries a reason naming estimated tokens, cap and window', /130001/.test(over.json.reason) && /130000/.test(over.json.reason) && /200000/.test(over.json.reason) && !('pointer' in over.json));
+  ok('budget: skip wins over file', over.json.bytes > 102400 && over.json.decision === 'skip');
+  const f = budget(s, 'gemini', 200000);
+  ok('budget: file carries the pointer to the absolute prompt path', f.json.decision === 'file' && f.json.pointer === 'Read the complete review brief in ' + f.file + ' and answer it exactly as it asks.');
+  const sp = budget(s, 'gemini', 200000, {}, 'my brief.md');
+  ok('budget: a pointer keeps a path with spaces whole', sp.file.includes(' ') && sp.json.pointer === 'Read the complete review brief in ' + sp.file + ' and answer it exactly as it asks.');
+  const windows = { claude: 200000, gemini: 1000000, codex: 272000, qwen: 256000, kimi: 256000, agy: 1000000, opencode: 128000, 'cursor-agent': 128000, coderabbit: 128000 };
+  for (const [name, w] of Object.entries(windows)) {
+    const r2 = budget(s, name, 10);
+    ok('budget: default window for ' + name + ' is ' + w, r2.json.window === w && r2.json.cap === Math.floor(w * 0.65));
+  }
+  const custom = budget(s, 'my-local', 10);
+  ok('budget: an unknown reviewer gets the 128000 fallback window', custom.json.window === 128000 && custom.json.windowSource === 'default');
+  s.done();
+}
+{
+  const s = setup({ 'plan_review.context': { codex: 1000 } }, { 'plan_review.context': { gemini: 5000, codex: 2000 } });
+  const c1 = budget(s, 'codex', 10);
+  ok('budget: the project window wins for a CLI both layers name', c1.json.window === 1000 && c1.json.cap === 650 && c1.json.windowSource === 'config');
+  const g1 = budget(s, 'gemini', 10);
+  ok('budget: a CLI only the global layer names is honoured', g1.json.window === 5000 && g1.json.windowSource === 'config');
+  ok('budget: a CLI neither layer names keeps the default', budget(s, 'claude', 10).json.windowSource === 'default');
+  const sk = budget(s, 'codex', 2000);
+  ok('budget: a configured small window skips an oversized prompt', sk.json.tokens === 667 && sk.json.decision === 'skip');
+  s.done();
+}
+{
+  const s = setup({ 'plan_review.context': { codex: 0 } }, { 'plan_review.context': { codex: 2000 } });
+  const r = budget(s, 'codex', 10);
+  ok('budget: an invalid project entry warns and falls through to the global value', r.json.window === 2000 && r.json.windowSource === 'config' && r.json.warnings.some((w) => w.includes('plan_review.context') && w.includes('codex')));
+  s.done();
+}
+{
+  const s = setup({ 'plan_review.context': 'big' }, null);
+  const r = budget(s, 'codex', 10);
+  ok('budget: a non-object plan_review.context warns and is ignored', r.code === 0 && r.json.window === 272000 && r.json.windowSource === 'default' && r.json.warnings.some((w) => w.includes('plan_review.context')));
+  s.done();
+  const arr = setup({ 'plan_review.context': [1] }, null);
+  ok('budget: an array plan_review.context is not an object, warned', budget(arr, 'codex', 10).json.warnings.length === 1);
+  arr.done();
+}
+for (const bad of [0, -5, 1.5, '1000', 10000001, null]) {
+  const s = setup({ 'plan_review.context': { codex: bad } }, null);
+  const r = budget(s, 'codex', 10);
+  ok('budget: context entry ' + JSON.stringify(bad) + ' is rejected with a warning', r.code === 0 && r.json.window === 272000 && r.json.windowSource === 'default' && r.json.warnings.length === 1);
+  s.done();
+}
+{
+  const s = setup({ 'plan_review.context': { codex: 10000000 } }, null);
+  ok('budget: 10000000 is the largest accepted window', budget(s, 'codex', 10).json.window === 10000000);
+  s.done();
+  const multi = setup({ 'plan_review.context': { codex: 4000 } }, null);
+  ok('budget: bytes are counted as UTF-8, not characters', (() => {
+    const dir = tmp();
+    const file = path.join(dir, 'u.md');
+    fs.writeFileSync(file, 'é'.repeat(10));
+    const r = run(['budget', '--repo', multi.root, '--reviewer', 'codex', '--prompt', file], { env: { CLAUDE_CONFIG_DIR: multi.gdir, PATH: '/nowhere' } });
+    rm(dir);
+    return r.json.bytes === 20 && r.json.tokens === 7;
+  })());
+  multi.done();
+}
+{
+  const s = setup({}, null);
+  const env = { env: { CLAUDE_CONFIG_DIR: s.gdir, PATH: '/nowhere' } };
+  ok('usage: budget without --repo exits 2', run(['budget', '--reviewer', 'codex', '--prompt', '/x'], env).code === 2);
+  ok('usage: budget without --reviewer exits 2', run(['budget', '--repo', s.root, '--prompt', '/x'], env).code === 2);
+  ok('usage: budget without --prompt exits 2', run(['budget', '--repo', s.root, '--reviewer', 'codex'], env).code === 2);
+  const u = run(['budget', '--repo', s.root], env);
+  ok('usage: budget errors go to stderr, stdout stays empty', u.errOut.startsWith('usage:') && u.out === '');
+  const missing = run(['budget', '--repo', s.root, '--reviewer', 'codex', '--prompt', '/nowhere/brief.md'], env);
+  ok('budget: an unreadable prompt file is status error, exit 1', missing.code === 1 && missing.json.status === 'error' && /cannot read/.test(missing.json.reason));
+  const bad = setup('{nope', null);
+  const p = promptFile(10);
+  const e = run(['budget', '--repo', bad.root, '--reviewer', 'codex', '--prompt', p.file], { env: { CLAUDE_CONFIG_DIR: bad.gdir, PATH: '/nowhere' } });
+  ok('budget: an invalid config is status error, exit 1', e.code === 1 && e.json.status === 'error');
+  rm(p.dir); bad.done(); s.done();
+}
+
+// --- overflow ----------------------------------------------------------------
+function overflow(text, brief) {
+  const dir = tmp();
+  const file = path.join(dir, 'codex.out');
+  fs.writeFileSync(file, text);
+  const extra = [];
+  if (brief !== undefined) {
+    const pf = path.join(dir, 'brief.md');
+    fs.writeFileSync(pf, brief);
+    extra.push('--prompt', pf);
+  }
+  const r = run(['overflow', '--output', file, ...extra]);
+  rm(dir);
+  return r;
+}
+{
+  const msgs = ['context_length_exceeded', 'This model\'s Maximum Context Length is 128000 tokens', 'Error: prompt is too long: 250000 tokens', 'input exceeds the context window of the model', 'Input is too long for requested model', 'The input token count (300000) exceeds the maximum number of tokens allowed (128000)', 'spawn E2BIG: Argument list too long'];
+  for (const m of msgs) {
+    const r = overflow('some output\n  ' + m + '  \nmore');
+    ok('overflow: matches "' + m + '"', r.code === 0 && r.json.status === 'ok' && r.json.overflow === true && r.json.reason.includes(m) && r.json.reason === r.json.reason.trim());
+  }
+  ok('overflow: matching is case-insensitive', overflow('PROMPT IS TOO LONG').json.overflow === true);
+  ok('overflow: the quoted reason is length-capped', overflow('prompt is too long ' + 'y'.repeat(5000)).json.reason.length <= 300);
+  ok('overflow: ordinary output is not an overflow', (() => { const r = overflow('1. Risk: the plan is too long to read\nblocking: none'); return r.code === 0 && r.json.overflow === false && !('reason' in r.json); })());
+  ok('overflow: a timeout is not an overflow', overflow('Error: request timed out after 540s').json.overflow === false);
+  ok('overflow: an auth failure is not an overflow', overflow('401 Unauthorized: invalid API key').json.overflow === false);
+  ok('overflow: a rate-limit error is not an overflow', overflow('429 Too Many Requests: rate limit reached, too many tokens per minute').json.overflow === false);
+  ok('overflow: a line of the brief echoed back is not an overflow', overflow('user\n- prompt is too long -> skip\nError: request timed out', 'The PLAN:\n- prompt is too long -> skip\n').json.overflow === false);
+  ok('overflow: a real error still matches with the brief passed', overflow('- prompt is too long -> skip\nError: prompt is too long: 250000 tokens', '- prompt is too long -> skip\n').json.overflow === true);
+  ok('overflow: an unreadable brief file is status error, exit 1', (() => { const d = tmp(); const f = path.join(d, 'x.out'); fs.writeFileSync(f, 'prompt is too long'); const r = run(['overflow', '--output', f, '--prompt', path.join(d, 'none.md')]); rm(d); return r.code === 1 && r.json.status === 'error'; })());
+  ok('overflow: an empty output file is not an overflow', overflow('').json.overflow === false);
+  ok('overflow: the helper\'s own spawn E2BIG launch error is an overflow', overflow('trailhead run: cannot launch codex: spawn E2BIG\n').json.overflow === true);
+  ok('overflow: an E2BIG line in the stderr part of a combined file is caught', overflow('partial stdout review text\n--- stderr ---\nbash: /usr/bin/codex: Argument list too long\n').json.overflow === true);
+  ok('usage: overflow without --output exits 2', run(['overflow']).code === 2);
+  const miss = run(['overflow', '--output', '/nowhere/x.out']);
+  ok('overflow: an unreadable output file is status error, exit 1', miss.code === 1 && miss.json.status === 'error');
+}
+
+// --- budget and overflow end-to-end ------------------------------------------
+{
+  const s = setup({}, null);
+  const p = promptFile(200000, 'brief.md');
+  const res = spawnSync(process.execPath, [scriptPath, 'budget', '--repo', s.root, '--reviewer', 'gemini', '--prompt', p.file], { encoding: 'utf8', env: { ...process.env, CLAUDE_CONFIG_DIR: s.gdir } });
+  const j = JSON.parse(res.stdout.trim());
+  ok('e2e: budget prints one JSON line with the file decision and exits 0', res.status === 0 && j.decision === 'file' && j.pointer.includes(p.file));
+  const huge = promptFile(500000);
+  const sk = spawnSync(process.execPath, [scriptPath, 'budget', '--repo', s.root, '--reviewer', 'claude', '--prompt', huge.file], { encoding: 'utf8', env: { ...process.env, CLAUDE_CONFIG_DIR: s.gdir } });
+  ok('e2e: budget skip is still exit 0 with a reason', sk.status === 0 && JSON.parse(sk.stdout.trim()).decision === 'skip');
+  ok('e2e: budget usage error exits 2', spawnSync(process.execPath, [scriptPath, 'budget', '--repo', s.root], { encoding: 'utf8' }).status === 2);
+  const out = path.join(p.dir, 'o.out');
+  fs.writeFileSync(out, 'oops\ncontext_length_exceeded\n');
+  const ov = spawnSync(process.execPath, [scriptPath, 'overflow', '--output', out], { encoding: 'utf8' });
+  const oj = JSON.parse(ov.stdout.trim());
+  ok('e2e: overflow prints the verdict and exits 0', ov.status === 0 && oj.overflow === true && oj.reason.includes('context_length_exceeded'));
+  fs.writeFileSync(out, 'all good');
+  ok('e2e: overflow false on ordinary output', JSON.parse(spawnSync(process.execPath, [scriptPath, 'overflow', '--output', out], { encoding: 'utf8' }).stdout.trim()).overflow === false);
+  rm(p.dir); rm(huge.dir); s.done();
+}
+
+// --- run: a reviewer call under a deadline (#368) -------------------------------
+{
+  const dir = tmp();
+  const out = path.join(dir, 'r.out');
+  const stub = (name, body) => { const f = path.join(dir, name); fs.writeFileSync(f, body); return f; };
+  const helper = (extra, cmd, env = {}) => {
+    const t0 = Date.now();
+    const res = spawnSync(process.execPath, [scriptPath, 'run', '--output', out, ...extra, '--', ...cmd], { encoding: 'utf8', env: { ...process.env, ...env }, timeout: 30000 });
+    let json = null;
+    try { json = JSON.parse(res.stdout.trim()); } catch { /* not json */ }
+    return { res, json, ms: Date.now() - t0, text: fs.existsSync(out) ? fs.readFileSync(out, 'utf8') : null };
+  };
+  const node = (f, ...a) => [process.execPath, f, ...a];
+  const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+  const sleepMs = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+  const fast = helper([], node(stub('fast.js', "console.log('review text'); console.error('warn text');")));
+  ok('run: fast exit 0 is status ok, exit 0, one JSON line', fast.res.status === 0 && fast.json.status === 'ok' && fast.json.exitCode === 0 && fast.json.signal === null && fast.json.timeoutSeconds === 600 && fast.json.output === out && !('reason' in fast.json) && fast.res.stdout.trim().split('\n').length === 1);
+  ok('run: stdout and stderr both land in the output file', fast.text.includes('review text') && fast.text.includes('warn text'));
+
+  const bad = helper([], node(stub('bad.js', "console.log('partial'); process.exit(3);")));
+  ok('run: a non-zero exit is failed with its code, still exit 0', bad.res.status === 0 && bad.json.status === 'failed' && bad.json.exitCode === 3 && /3/.test(bad.json.reason) && bad.text.includes('partial'));
+
+  const stdinStub = stub('stdin.js', "process.stdin.on('data', () => {}); process.stdin.on('end', () => { console.log('EOF'); });");
+  const eof = helper(['--timeout', '5'], node(stdinStub));
+  ok('run: stdin is closed (a reader gets EOF at once)', eof.json.status === 'ok' && eof.text.includes('EOF') && eof.ms < 4000);
+
+  const missing = helper([], [path.join(dir, 'no-such-cli'), 'x']);
+  ok('run: a missing command is status error, exit 0, text in the file', missing.res.status === 0 && missing.json.status === 'error' && missing.json.exitCode === null && /ENOENT/.test(missing.json.reason) && /ENOENT/.test(missing.text));
+  const noexec = helper([], [stub('plain.txt', 'x')]);
+  ok('run: a non-executable command is status error', noexec.res.status === 0 && noexec.json.status === 'error' && /EACCES/.test(noexec.text));
+
+  const pass = helper([], node(stub('argv.js', "console.log(JSON.stringify(process.argv.slice(2)));"), '--foo', '', '--timeout', 'a b'));
+  ok('run: argv after -- is passed verbatim, flags and empty strings included', pass.json.status === 'ok' && pass.text.trim() === JSON.stringify(['--foo', '', '--timeout', 'a b']));
+
+  const sleeper = helper(['--timeout', '1'], node(stub('sleep.js', "console.log('Reading additional input from stdin...'); setTimeout(() => {}, 300000);")));
+  ok('run: a silent sleeper is timeout within the bound, exit 0', sleeper.res.status === 0 && sleeper.json.status === 'timeout' && sleeper.json.timeoutSeconds === 1 && /1s/.test(sleeper.json.reason) && sleeper.ms < 6000);
+  ok('run: the partial output of a timed-out call stays in the file', sleeper.text.includes('Reading additional input from stdin...'));
+  const ov = run(['overflow', '--output', out]);
+  ok('run: overflow on that partial output is not what classifies a timeout', ov.json.overflow === false && sleeper.json.status === 'timeout');
+  const ovText = stub('ov.js', "console.log('context_length_exceeded'); setTimeout(() => {}, 300000);");
+  const slow = helper(['--timeout', '1'], node(ovText));
+  ok('run: timeout wins even when the output looks like an overflow', slow.json.status === 'timeout' && run(['overflow', '--output', out]).json.overflow === true);
+
+  const pidFile = path.join(dir, 'gc.pid');
+  const grand = stub('grand.js', `
+const { spawn } = require('child_process');
+const fs = require('fs');
+process.on('SIGTERM', () => {});
+const gc = spawn(process.execPath, ['-e', "process.on('SIGTERM', () => {}); setTimeout(() => {}, 300000);"], { stdio: 'ignore' });
+fs.writeFileSync(${JSON.stringify(pidFile)}, String(gc.pid));
+setTimeout(() => {}, 300000);
+`);
+  const stubborn = helper(['--timeout', '1'], node(grand), { TRAILHEAD_REVIEW_GRACE_MS: '400' });
+  ok('run: a child ignoring SIGTERM still ends as timeout, killed by SIGKILL', stubborn.json.status === 'timeout' && stubborn.json.signal === 'SIGKILL' && stubborn.ms < 8000);
+  const gcPid = Number(fs.readFileSync(pidFile, 'utf8'));
+  for (let i = 0; i < 20 && alive(gcPid); i++) sleepMs(100);
+  ok('run: the grandchild does not survive the timeout', gcPid > 0 && !alive(gcPid));
+
+  // Signals sent to the helper kill the reviewer's group: SIGHUP 129, SIGTERM 143, SIGINT 130.
+  // A driver process signals the helper once the sleeper has written its pid, then reports.
+  const sigPid = path.join(dir, 'sig.pid');
+  const sigStub = stub('sigsleep.js', `require('fs').writeFileSync(${JSON.stringify(sigPid)}, String(process.pid)); setTimeout(() => {}, 300000);`);
+  const driver = stub('sigdriver.js', `
+const { spawn } = require('child_process');
+const fs = require('fs');
+const [script, output, pidFile, stubFile, sig] = process.argv.slice(2);
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+const h = spawn(process.execPath, [script, 'run', '--output', output, '--timeout', '60', '--', process.execPath, stubFile], { stdio: 'ignore' });
+let code = null;
+h.on('exit', (c) => { code = c; });
+let n = 0;
+const wait = setInterval(() => {
+  if (!fs.existsSync(pidFile) || ++n > 100) { if (n > 100) { clearInterval(wait); console.log('{}'); h.kill('SIGKILL'); } return; }
+  clearInterval(wait);
+  const pid = Number(fs.readFileSync(pidFile, 'utf8'));
+  h.kill(sig);
+  let m = 0;
+  const settle = setInterval(() => {
+    if ((code !== null && !alive(pid)) || ++m > 50) {
+      clearInterval(settle);
+      const dead = !alive(pid);
+      if (!dead) process.kill(pid, 'SIGKILL');
+      console.log(JSON.stringify({ code, dead }));
+    }
+  }, 100);
+}, 100);
+`);
+  for (const [sig, code] of [['SIGHUP', 129], ['SIGTERM', 143], ['SIGINT', 130]]) {
+    try { fs.unlinkSync(sigPid); } catch { /* none yet */ }
+    const r = spawnSync(process.execPath, [driver, scriptPath, out, sigPid, sigStub, sig], { encoding: 'utf8', timeout: 30000 });
+    let d = {};
+    try { d = JSON.parse(r.stdout.trim()); } catch { /* not json */ }
+    ok(`run: ${sig} to the helper kills the reviewer and exits ${code}`, d.code === code && d.dead === true);
+  }
+
+  const usage = (argv) => spawnSync(process.execPath, [scriptPath, 'run', ...argv], { encoding: 'utf8' });
+  ok('usage: run without --output exits 2', usage(['--', 'true']).status === 2);
+  ok('usage: run without a command exits 2', usage(['--output', out]).status === 2 && usage(['--output', out, '--']).status === 2);
+  ok('usage: run with a bad --timeout exits 2', ['0', '-1', '1.5', 'abc'].every((v) => usage(['--output', out, '--timeout', v, '--', 'true']).status === 2));
+  ok('usage: run with an unknown helper flag exits 2', usage(['--output', out, '--bogus', 'x', '--', 'true']).status === 2);
+  const unwritable = spawnSync(process.execPath, [scriptPath, 'run', '--output', path.join(dir, 'no', 'such', 'dir', 'x.out'), '--', 'true'], { encoding: 'utf8' });
+  ok('run: an unwritable output file exits 1 with status error', unwritable.status === 1 && JSON.parse(unwritable.stdout.trim()).status === 'error');
+  rm(dir);
+}
+
 console.log(`plan-review-rounds.test.js: ${passed} checks passed`);