@marcomigozzi/trailhead 0.16.1 → 0.18.0

package/plugins/trailhead/hooks/lib/model-route.test.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+// Test per model-route.js (#323). Run: node model-route.test.js
+// Niente framework: assert semplici, stesso stile degli altri test di hooks/lib.
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const LIB = path.join(__dirname, 'model-route.js');
+const root = path.resolve(__dirname, '..', '..', '..', '..');
+const { route, AGENT_OF, BALANCED, familyAlias, loadTierIds } = require(LIB);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+const throws = (fn) => { try { fn(); } catch (e) { return true; } return false; };
+const TIERS = loadTierIds('claude');
+const OPUS = 'claude-opus-5-5';
+const SONNET = 'claude-sonnet-5-5';
+
+const claude = (extra) => route({ key: 'grill', host: 'claude', models: {}, sessionModel: SONNET, subagents: true, tierIds: TIERS, ...extra });
+const codex = (extra) => route({ key: 'grill', host: 'codex', models: {}, sessionModel: 'gpt-5.6-terra', subagents: true, tierIds: TIERS, ...extra });
+
+// --- Claude --------------------------------------------------------------------
+{
+  const r = claude({});
+  ok('claude: sonnet session, key unset -> dispatch trailhead-grill on opus',
+    r.route === 'dispatch' && r.agent === 'trailhead-grill' && r.model === OPUS && r.alias === 'opus');
+  ok('claude: strong comes from the current model-defaults entry', TIERS.strong === OPUS);
+  ok('claude: opus session, key unset -> inline', claude({ sessionModel: OPUS }).route === 'inline');
+  ok('claude: sonnet pin in a sonnet session -> inline', claude({ models: { grill: SONNET } }).route === 'inline');
+  ok('claude: inherit session -> inline', claude({ models: { grill: 'inherit session' } }).route === 'inline');
+  for (const unset of [null, '', undefined]) {
+    ok(`claude: ${JSON.stringify(unset)} resolves like an unset key`, claude({ models: { grill: unset } }).route === 'dispatch');
+  }
+  const pinned = claude({ sessionModel: OPUS, models: { grill: 'claude-opus-5' } });
+  ok('claude: a different opus version dispatches with the opus alias', pinned.route === 'dispatch' && pinned.alias === 'opus' && pinned.model === 'claude-opus-5');
+  ok('claude: a suffixed opus session + unset key -> inline', claude({ sessionModel: 'claude-opus-5-5[1m]' }).route === 'inline');
+  const sfx = claude({ sessionModel: 'claude-sonnet-5-5[1m]' });
+  ok('claude: a suffixed sonnet session + unset key -> dispatch opus', sfx.route === 'dispatch' && sfx.model === OPUS && sfx.alias === 'opus');
+  ok('claude: a suffixed configured id equals the plain session id', claude({ sessionModel: SONNET, models: { grill: `${SONNET}[1m]` } }).route === 'inline');
+  ok('claude: no subagents, suffixed session already on the model -> no suggestion', !claude({ subagents: false, sessionModel: 'claude-opus-5-5[1m]' }).suggest);
+  const unk = claude({ models: { grill: 'my-custom-model' } });
+  ok('claude: an unknown id that differs from the session -> inline with warning', unk.route === 'inline' && unk.warning === 'unknown-id');
+  const unkEq = claude({ sessionModel: 'my-custom-model', models: { grill: 'my-custom-model' } });
+  ok('claude: an unknown id equal to the session -> inline, no warning', unkEq.route === 'inline' && !unkEq.warning);
+  const unknownSession = claude({ sessionModel: 'unknown' });
+  ok('claude: session unknown, key unset -> dispatch', unknownSession.route === 'dispatch');
+  ok('claude: a pin literally named unknown never equals the reserved value',
+    claude({ sessionModel: 'unknown', models: { grill: 'unknown' } }).route === 'inline' && claude({ sessionModel: 'unknown', models: { grill: 'unknown' } }).warning === 'unknown-id');
+  const ns = claude({ subagents: false });
+  ok('claude: no subagents -> inline with a suggestion of the resolved id', ns.route === 'inline' && ns.suggest === OPUS);
+  ok('claude: no subagents and already on that model -> no suggestion', !claude({ subagents: false, sessionModel: OPUS }).suggest);
+  ok('claude: no subagents and unknown session -> suggestion', claude({ subagents: false, sessionModel: 'unknown' }).suggest === OPUS);
+  ok('claude: alias families', familyAlias('claude-opus-5-5') === 'opus' && familyAlias('claude-sonnet-5') === 'sonnet' &&
+    familyAlias('claude-haiku-4-5-20251001') === 'haiku' && familyAlias('claude-fable-5') === 'fable' && familyAlias('gpt-5.6-sol') === null);
+  ok('claude: the config key for another activity uses its own Balanced tier',
+    route({ key: 'codebase-map', host: 'claude', models: {}, sessionModel: OPUS, subagents: true, tierIds: TIERS }).model === TIERS.fast);
+  ok('claude: models.codex.grill is ignored on the claude host',
+    claude({ models: { codex: { grill: 'gpt-5.6-sol' } } }).model === OPUS);
+}
+
+// --- #323: grill non impostato segue plan ---
+{
+  const g = claude({ sessionModel: OPUS, models: { plan: SONNET } });
+  ok('grill unset follows plan: plan sonnet in an opus session -> dispatch sonnet',
+    g.route === 'dispatch' && g.agent === 'trailhead-grill' && g.model === SONNET && g.alias === 'sonnet');
+  const bal = claude({ sessionModel: SONNET, models: {} });
+  ok('grill unset + plan unset in a sonnet session -> dispatch opus (plan Balanced default)', bal.route === 'dispatch' && bal.model === OPUS && bal.alias === 'opus');
+  ok('grill unset + plan equal to the session -> inline', claude({ sessionModel: SONNET, models: { plan: SONNET } }).route === 'inline');
+  const own = claude({ sessionModel: OPUS, models: { plan: SONNET, grill: 'claude-haiku-5-5' } });
+  ok('grill set overrides plan', own.route === 'dispatch' && own.model === 'claude-haiku-5-5');
+  ok('plan inherit session + grill unset -> inline', claude({ models: { plan: 'inherit session' } }).route === 'inline');
+  ok('grill inherit session wins over plan', claude({ models: { plan: OPUS, grill: 'inherit session' } }).route === 'inline');
+  for (const unset of [null, '']) {
+    ok(`grill ${JSON.stringify(unset)} follows plan`, claude({ sessionModel: OPUS, models: { plan: SONNET, grill: unset } }).model === SONNET);
+  }
+  const old = { plan: SONNET, execute: SONNET, research: SONNET, review: SONNET, debug: SONNET, verify: SONNET, 'codebase-map': 'claude-haiku-5-5' };
+  const legacy = claude({ sessionModel: OPUS, models: old });
+  ok('a config with the seven old keys and no grill grills on the plan id', legacy.route === 'dispatch' && legacy.model === SONNET);
+  ok('other keys do not follow plan', route({ key: 'research', host: 'claude', models: { plan: SONNET }, sessionModel: SONNET, subagents: true, tierIds: TIERS }).route === 'inline');
+  const noSub = claude({ sessionModel: OPUS, subagents: false, models: { plan: SONNET } });
+  ok('no subagents: suggests the plan id', noSub.route === 'inline' && noSub.suggest === SONNET);
+}
+
+// --- Codex ---------------------------------------------------------------------
+{
+  ok('codex: key unset -> inline', codex({}).route === 'inline');
+  ok('codex: inherit session -> inline', codex({ models: { codex: { grill: 'inherit session' } } }).route === 'inline');
+  ok('codex: models.grill (claude ids) is ignored', codex({ models: { grill: OPUS } }).route === 'inline');
+  const d = codex({ models: { codex: { grill: 'gpt-5.6-sol' } } });
+  ok('codex: a pin different from the session -> dispatch trailhead-grill', d.route === 'dispatch' && d.agent === 'trailhead-grill' && d.alias === null && d.model === 'gpt-5.6-sol');
+  ok('codex: a bare pin equal to the session -> inline', codex({ sessionModel: 'gpt-5.6-sol', models: { codex: { grill: 'gpt-5.6-sol' } } }).route === 'inline');
+  const pin = { model: 'gpt-5.6-sol', effort: 'high' };
+  const eq = { sessionModel: 'gpt-5.6-sol', models: { codex: { grill: pin } } };
+  ok('codex: equal model and equal effort -> inline', codex({ ...eq, sessionEffort: 'high' }).route === 'inline');
+  ok('codex: equal model, different effort -> dispatch', codex({ ...eq, sessionEffort: 'medium' }).route === 'dispatch');
+  ok('codex: equal model, effort pinned, session effort unknown -> dispatch', codex(eq).route === 'dispatch');
+  ok('codex: equal model, no pinned effort, any session effort -> inline',
+    codex({ sessionModel: 'gpt-5.6-sol', sessionEffort: 'low', models: { codex: { grill: { model: 'gpt-5.6-sol' } } } }).route === 'inline');
+  ok('codex: session unknown -> dispatch', codex({ sessionModel: 'unknown', models: { codex: { grill: 'gpt-5.6-sol' } } }).route === 'dispatch');
+  ok('codex: an object pin without a model stays inline', codex({ models: { codex: { grill: { effort: 'high' } } } }).route === 'inline');
+  ok('codex: execute dispatches the projected trailhead-execute',
+    route({ key: 'execute', host: 'codex', models: { codex: { execute: 'gpt-5.6-sol' } }, sessionModel: 'gpt-5.6-terra', subagents: true, tierIds: TIERS }).agent === 'trailhead-execute');
+}
+
+{
+  const cx = (extra) => codex({ ...extra });
+  const planPin = { codex: { plan: 'gpt-5.6-sol' } };
+  const d = cx({ models: planPin });
+  ok('codex: grill unset + codex.plan pinned -> dispatch trailhead-grill on the plan pin', d.route === 'dispatch' && d.agent === 'trailhead-grill' && d.model === 'gpt-5.6-sol');
+  ok('codex: grill unset + codex.plan equal to the session -> inline', cx({ sessionModel: 'gpt-5.6-sol', models: planPin }).route === 'inline');
+  ok('codex: plan pin with effort follows the same effort rules',
+    cx({ sessionModel: 'gpt-5.6-sol', models: { codex: { plan: { model: 'gpt-5.6-sol', effort: 'high' } } } }).route === 'dispatch' &&
+    cx({ sessionModel: 'gpt-5.6-sol', sessionEffort: 'high', models: { codex: { plan: { model: 'gpt-5.6-sol', effort: 'high' } } } }).route === 'inline');
+  ok('codex: grill set overrides plan', cx({ sessionModel: 'gpt-5.6-sol', models: { codex: { plan: 'gpt-5.6-terra', grill: 'gpt-5.6-sol' } } }).route === 'inline');
+  ok('codex: grill inherit session wins over plan', cx({ models: { codex: { plan: 'gpt-5.6-sol', grill: 'inherit session' } } }).route === 'inline');
+  for (const [label, pinv] of [['object form', { model: 'inherit session', effort: 'high' }], ['case variant', ' Inherit Session '], ['bare string', 'inherit session']]) {
+    ok(`codex: plan ${label} of inherit session + grill unset -> inline`, cx({ models: { codex: { plan: pinv } } }).route === 'inline');
+    ok(`codex: grill ${label} of inherit session wins over a plan pin -> inline`, cx({ models: { codex: { plan: 'gpt-5.6-sol', grill: pinv } } }).route === 'inline');
+  }
+  ok('claude: a case variant of inherit session routes inline', claude({ models: { grill: ' Inherit Session ' } }).route === 'inline' && claude({ models: { plan: 'INHERIT SESSION' } }).route === 'inline');
+  ok('codex: grill unset + plan unset -> inline', cx({ models: { codex: {} } }).route === 'inline');
+}
+
+// --- agent mapping -------------------------------------------------------------
+{
+  const { MODEL_KEYS, codexAgentTomlPlan } = require(path.join(root, 'bin', 'lib', 'codex-projection.js'));
+  const keys = [...MODEL_KEYS].sort();
+  ok('agents: both tables cover exactly the MODEL_KEYS',
+    JSON.stringify(Object.keys(AGENT_OF.claude).sort()) === JSON.stringify(keys) &&
+    JSON.stringify(Object.keys(AGENT_OF.codex).sort()) === JSON.stringify(keys));
+  for (const [key, name] of Object.entries(AGENT_OF.claude)) {
+    ok(`agents: claude ${key} -> ${name} exists under agents/`, fs.existsSync(path.join(root, 'plugins', 'trailhead', 'agents', `${name}.md`)));
+  }
+  const defs = fs.readdirSync(path.join(root, 'plugins', 'trailhead', 'agents'))
+    .filter((f) => /^trailhead-.*\.md$/.test(f)).sort()
+    .map((f) => ({ name: f.slice(0, -3), description: 'd', tools: 'Read', body: 'b' }));
+  const models = Object.fromEntries(keys.map((k) => [k, `pin-${k}`]));
+  const writes = codexAgentTomlPlan('/c', models, defs).writes;
+  for (const [key, name] of Object.entries(AGENT_OF.codex)) {
+    const w = writes.find((x) => x.content.includes(`model = "pin-${key}"`));
+    ok(`agents: codex ${key} -> ${name} is the name the projection emits`, !!w && w.name === name);
+  }
+  ok('agents: execute and review map to the distinct per-host names',
+    AGENT_OF.claude.execute === 'trailhead-executor' && AGENT_OF.codex.execute === 'trailhead-execute' &&
+    AGENT_OF.claude.review === 'trailhead-code-review' && AGENT_OF.codex.review === 'trailhead-review');
+  ok('agents: an unknown key throws', throws(() => route({ key: 'nope', host: 'claude', models: {}, sessionModel: 'unknown', subagents: true, tierIds: TIERS })));
+  ok('agents: an unknown host throws', throws(() => route({ key: 'grill', host: 'mars', models: {}, sessionModel: 'unknown', subagents: true, tierIds: TIERS })));
+}
+
+// --- BALANCED pinned to the profile table -----------------------------------------
+{
+  const ref = fs.readFileSync(path.join(root, 'plugins', 'trailhead', 'skills', '_shared', 'configuration-reference.md'), 'utf8').split('\n');
+  const cells = (l) => l.split('|').slice(1, -1).map((c) => c.trim());
+  const header = cells(ref.find((l) => l.startsWith('| profile |')));
+  const row = cells(ref.find((l) => l.startsWith('| **Balanced** |')));
+  const parsed = Object.fromEntries(header.slice(1).map((k, i) => [k, row[i + 1]]));
+  const { grill: tableGrill, ...tableRest } = parsed;
+  ok('BALANCED equals the Balanced row of the profile table, minus grill', JSON.stringify(BALANCED) === JSON.stringify(tableRest) && !('grill' in BALANCED));
+  ok('the grill column mirrors the plan column in every profile', ['High', 'Balanced', 'Low'].every((name) => {
+    const r = cells(ref.find((l) => l.startsWith(`| **${name}** |`)));
+    return r[header.indexOf('grill')] === r[header.indexOf('plan')];
+  }) && tableGrill === parsed.plan);
+}
+
+// --- CLI -----------------------------------------------------------------------
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-model-route-'));
+  const globalDir = path.join(tmp, 'claude');
+  fs.mkdirSync(path.join(globalDir, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { grill: 'claude-sonnet-5', plan: 'claude-haiku-5-5' } }));
+  const proj = path.join(tmp, 'proj');
+  fs.mkdirSync(path.join(proj, '.trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { grill: 'claude-opus-5' } }));
+  const env = { ...process.env, CLAUDE_CONFIG_DIR: globalDir, CODEX_HOME: path.join(tmp, 'codex') };
+  const run = (args) => spawnSync(process.execPath, [LIB, ...args], { encoding: 'utf8', env });
+  const r = run(['grill', '--session', SONNET, proj]);
+  const j = JSON.parse(r.stdout);
+  ok('cli: exit 0 and one JSON line with the six keys',
+    r.status === 0 && r.stdout.trim().split('\n').length === 1 &&
+    JSON.stringify(Object.keys(j)) === JSON.stringify(['route', 'agent', 'model', 'alias', 'suggest', 'warning']));
+  ok('cli: the project config wins over the global one key by key', j.route === 'dispatch' && j.model === 'claude-opus-5' && j.alias === 'opus' && j.agent === 'trailhead-grill');
+  const g = JSON.parse(run(['grill', '--session', SONNET, tmp]).stdout);
+  ok('cli: with no project above, the global config applies', g.route === 'dispatch' && g.model === 'claude-sonnet-5' && g.alias === 'sonnet');
+  const ns = JSON.parse(run(['grill', '--session', 'unknown', '--no-subagents', proj]).stdout);
+  ok('cli: --no-subagents inline with a suggestion', ns.route === 'inline' && ns.suggest === 'claude-opus-5');
+  const cx = JSON.parse(run(['grill', '--session', 'gpt-5.6-terra', '--host', 'codex', proj]).stdout);
+  ok('cli: --host codex ignores models.grill', cx.route === 'inline');
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { codex: { grill: { model: 'gpt-5.6-sol', effort: 'high' } } } }));
+  const ce = JSON.parse(run(['grill', '--session', 'gpt-5.6-sol', '--session-effort', 'high', '--host', 'codex', proj]).stdout);
+  ok('cli: --session-effort equal to the pinned effort -> inline', ce.route === 'inline');
+  const cd = JSON.parse(run(['grill', '--session', 'gpt-5.6-sol', '--session-effort', 'medium', '--host', 'codex', proj]).stdout);
+  ok('cli: a different --session-effort -> dispatch', cd.route === 'dispatch' && cd.agent === 'trailhead-grill');
+  for (const [name, args] of [
+    ['a missing --session', ['grill', proj]],
+    ['an empty --session', ['grill', '--session', '', proj]],
+    ['an unknown flag', ['grill', '--session', SONNET, '--bogus', proj]],
+    ['an unknown key', ['nope', '--session', SONNET, proj]],
+    ['no key', ['--session', SONNET]],
+    ['an unknown host', ['grill', '--session', SONNET, '--host', 'mars', proj]],
+  ]) {
+    const x = run(args);
+    ok(`cli: ${name} exits 2 with nothing on stdout`, x.status === 2 && x.stdout === '' && x.stderr.length > 0);
+  }
+  // implicit grill per layer (project plan beats a global grill)
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { grill: 'claude-haiku-5-5' } }));
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-sonnet-5' } }));
+  const lp = JSON.parse(run(['grill', '--session', OPUS, proj]).stdout);
+  ok('cli: project plan + no project grill beats a global grill', lp.route === 'dispatch' && lp.model === 'claude-sonnet-5');
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-sonnet-5', grill: 'claude-opus-5' } }));
+  ok('cli: a project grill always wins', JSON.parse(run(['grill', '--session', SONNET, proj]).stdout).model === 'claude-opus-5');
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-sonnet-5' } }));
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: {} }));
+  ok('cli: global plan + no grill anywhere -> global plan', JSON.parse(run(['grill', '--session', OPUS, proj]).stdout).model === 'claude-sonnet-5');
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { grill: 'claude-haiku-5-5', plan: 'claude-opus-5' } }));
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'inherit session' } }));
+  ok('cli: project plan inherit session + global grill -> inline', JSON.parse(run(['grill', '--session', SONNET, proj]).stdout).route === 'inline');
+  // codex
+  const codexHome = path.join(tmp, 'codex');
+  fs.mkdirSync(path.join(codexHome, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(codexHome, 'trailhead', 'config.json'), JSON.stringify({ models: { codex: { grill: 'gpt-5.6-luna' } } }));
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: { codex: { plan: 'gpt-5.6-sol' } } }));
+  const cxl = JSON.parse(run(['grill', '--session', 'gpt-5.6-terra', '--host', 'codex', proj]).stdout);
+  ok('cli codex: project codex.plan + no project grill beats a global codex.grill', cxl.route === 'dispatch' && cxl.model === 'gpt-5.6-sol');
+  fs.writeFileSync(path.join(proj, '.trailhead', 'config.json'), JSON.stringify({ models: {} }));
+  ok('cli codex: only a global grill pin -> that pin', JSON.parse(run(['grill', '--session', 'gpt-5.6-terra', '--host', 'codex', proj]).stdout).model === 'gpt-5.6-luna');
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`model-route.test.js: ${passed} assertions passed`);

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`);