feat(#3274): make reviewer-lane timeout configurable via timeoutConfigKey (#4083)

* feat(#3274): make reviewer-lane timeout configurable via timeoutConfigKey

Add an optional `timeoutConfigKey` field to the reviewer lane descriptor,
resolved in `resolveLanePlan` at invocation time and falling back to the
frozen `timeoutFloorMs` when unset or invalid, in the same spirit as the
existing `promptBudgetKey`/`modelConfigKey` fields. All 12 shipped lanes
declare `review.timeouts.<slug>` on both surfaces (the descriptor and their
capability.json manifest), validated by capability-validator.cjs.

For the antigravity lane, the native `agy --print-timeout` flag — previously
a second hardcoded literal (`540s`) independent of the outer cap — is now
derived from the same resolved outer timeout in `antigravityArgv`, preserving
the existing 60-second buffer relationship (ADR-2782 D6: the outer bound is
declared data, the inner one is handler-owned).

The antigravity default timeoutFloorMs stays at 600s per the maintainer's
disposition; users raise it through the new config key instead.

* docs(#3274): document review.timeouts.* and extract resolveTimeoutMs helper

Address code-review findings on the timeoutConfigKey change: extract the
inline timeout-resolution logic into a named, exported, directly-tested
resolveTimeoutMs helper (matching the file's existing configString/
normalizeHost convention); document the new review.timeouts.* federated
config keys in docs/CONFIGURATION.md, docs/reference/capability-manifest.md,
and docs/how-to/ship-a-reviewer-lane.md; add the changeset fragment.

* fix(#3274): resolve native antigravity timeout in resolveLanePlan, not the runner

gsd-test caught two design mistakes in the prior commits:

1. SpawnPlan.argv is documented and tested as fully resolved by
   resolveLanePlan (model/effort/output/prompt already folded in) — leaving
   the antigravity '{{nativeTimeout}}' marker unresolved until the runner's
   antigravityArgv violated that contract and broke tests that read
   plan.argv directly (tests/antigravity-reviewer.test.cjs,
   tests/review-default-reviewers-workflow.test.cjs). Fix: '{{nativeTimeout}}'
   is now a fifth ARGV_PLACEHOLDER member, resolved by resolveLanePlan itself
   via the new nativeTimeoutToken() helper, exactly like the other four.
   antigravityArgv reverts to its pre-#3274 four-argument form. Also missed
   updating capabilities/antigravity/capability.json's invoke.args to match
   the descriptor, which broke the manifest/descriptor parity test.

2. tests/reviewer-config-federation.test.cjs enforces a deliberate, narrow
   invariant (#3691 narrows #2797): qwen, cursor, and coderabbit — the three
   lanes with neither a model flag nor a host — may own no config key beyond
   their own prompt-budget key. Adding review.timeouts.<slug> to all 12 lanes
   violated it. Fix: those three keep timeoutConfigKey: null and own no
   review.timeouts.* key, matching their existing modelConfigKey: null. The
   other 9 lanes are unaffected.

* chore(#3274): backfill changeset PR number (pr:0 -> 4083)

---------

Co-authored-by: sim <sim@local>

tests/review-lane-invocation.test.cjs

@@ -26,6 +26,7 @@ const {
 } = require('../gsd-core/bin/lib/review-lane-descriptor.cjs');
 const {
   resolveLanePlan,
+  resolveTimeoutMs,
   isEmptyReview,
   normalizeHost,
   fileRefPrompt,
@@ -85,6 +86,8 @@ const GOLDEN = [
   { slug: 'opencode', binary: 'opencode', argv: ['run', '--model', 'O', '--effort', 'high', '--format', 'json', '-'], stdin: true, out: 'stdout', timeout: 660000 },
   { slug: 'qwen', binary: 'qwen', argv: ['-'], stdin: true, out: 'stdout', timeout: 900000 },
   { slug: 'cursor', binary: 'cursor-agent', argv: ['-p', '--mode', 'ask', '--trust', '--output-format', 'text', FILE_REF], stdin: false, out: 'stdout', timeout: 900000 },
+  // resolveLanePlan fully resolves {{nativeTimeout}} itself (#3274) — this row proves the
+  // unconfigured default reproduces the original literal exactly.
   { slug: 'antigravity', binary: 'agy', argv: ['--print-timeout', '540s', '--model', 'A', '-p', FILE_REF], stdin: false, out: 'stdout', timeout: 600000 },
   { slug: 'kimi-code', binary: 'kimi', argv: ['-m', 'K', '-p', FILE_REF], stdin: false, out: 'stdout', timeout: 900000 },
 ];
@@ -137,6 +140,130 @@ describe('reviewer lane invocation — golden plans (the strangler-fig contract)
   });
 });
 
+describe('#3274 — timeoutConfigKey resolves the outer wall-clock cap', () => {
+  const AGY_FLOOR = REVIEWER_LANES.find((l) => l.slug === 'antigravity').timeoutFloorMs;
+  const AGY_KEY = REVIEWER_LANES.find((l) => l.slug === 'antigravity').timeoutConfigKey;
+
+  test('an absent config key falls back to timeoutFloorMs (row 1)', () => {
+    const r = resolve('antigravity', { config: {} });
+    assert.equal(r.plan.timeoutMs, AGY_FLOOR);
+  });
+
+  test('a configured positive number overrides timeoutFloorMs, seconds -> ms (row 2)', () => {
+    const r = resolve('antigravity', { config: { [AGY_KEY]: 900 } });
+    assert.equal(r.plan.timeoutMs, 900_000);
+  });
+
+  test('0 is treated as unset, not a zero-length timeout (row 3)', () => {
+    const r = resolve('antigravity', { config: { [AGY_KEY]: 0 } });
+    assert.equal(r.plan.timeoutMs, AGY_FLOOR);
+  });
+
+  test('a negative configured timeout is treated as unset (row 4)', () => {
+    const r = resolve('antigravity', { config: { [AGY_KEY]: -5 } });
+    assert.equal(r.plan.timeoutMs, AGY_FLOOR);
+  });
+
+  test('NaN and Infinity are treated as unset (row 5)', () => {
+    assert.equal(resolve('antigravity', { config: { [AGY_KEY]: NaN } }).plan.timeoutMs, AGY_FLOOR);
+    assert.equal(resolve('antigravity', { config: { [AGY_KEY]: Infinity } }).plan.timeoutMs, AGY_FLOOR);
+  });
+
+  test('a non-number configured value is never coerced, falls back (row 6)', () => {
+    for (const bad of ['900', true, {}, [], 'null']) {
+      const r = resolve('antigravity', { config: { [AGY_KEY]: bad } });
+      assert.equal(r.plan.timeoutMs, AGY_FLOOR, `value ${JSON.stringify(bad)} must not resolve to a timeout`);
+    }
+  });
+
+  test('a lane with no timeoutConfigKey field falls back like an unset key (row 7)', () => {
+    const lane = { ...REVIEWER_LANES.find((l) => l.slug === 'gemini') };
+    delete lane.timeoutConfigKey;
+    const r = resolveLanePlan({ lane, configGet: () => 900, runDir: RUN, repoRoot: ROOT });
+    assert.equal(r.ok, true);
+    assert.equal(r.plan.timeoutMs, lane.timeoutFloorMs);
+  });
+
+  test('resolveTimeoutMs: direct unit — unset falls back to floorMs', () => {
+    assert.equal(resolveTimeoutMs(null, 5000, () => undefined), 5000);
+    assert.equal(resolveTimeoutMs('some.key', 5000, () => undefined), 5000);
+  });
+
+  test('resolveTimeoutMs: direct unit — configured value overrides, seconds -> ms', () => {
+    assert.equal(resolveTimeoutMs('some.key', 5000, (k) => (k === 'some.key' ? 30 : undefined)), 30000);
+  });
+
+  test('boundary: 0 vs 1 vs a fractional second (row 8)', () => {
+    assert.equal(resolve('antigravity', { config: { [AGY_KEY]: 0 } }).plan.timeoutMs, AGY_FLOOR);
+    assert.equal(resolve('antigravity', { config: { [AGY_KEY]: 1 } }).plan.timeoutMs, 1000);
+    assert.equal(resolve('antigravity', { config: { [AGY_KEY]: 0.5 } }).plan.timeoutMs, 500);
+  });
+
+  test("a non-antigravity lane's configured timeout does not touch argv (row 13)", () => {
+    const key = REVIEWER_LANES.find((l) => l.slug === 'gemini').timeoutConfigKey;
+    const unset = resolve('gemini', { config: {} });
+    const configured = resolve('gemini', { config: { [key]: 300 } });
+    assert.deepStrictEqual(configured.plan.argv, unset.plan.argv);
+    assert.notEqual(configured.plan.timeoutMs, unset.plan.timeoutMs);
+  });
+
+  test('property: any positive-second config resolves to exactly seconds * 1000 ms (row 20)', () => {
+    fc.assert(
+      fc.property(fc.integer({ min: 1, max: 1_000_000 }), (seconds) => {
+        const r = resolve('antigravity', { config: { [AGY_KEY]: seconds } });
+        assert.equal(r.plan.timeoutMs, seconds * 1000);
+      }),
+      FC,
+    );
+  });
+
+  test('property: any hostile config value degrades to timeoutFloorMs, never throws (row 21)', () => {
+    const hostile = fc.oneof(
+      fc.string(),
+      fc.boolean(),
+      fc.object(),
+      fc.array(fc.anything()),
+      fc.constant(0),
+      fc.integer({ max: 0 }),
+      fc.constant(NaN),
+      fc.constant(Infinity),
+      fc.constant(-Infinity),
+    );
+    fc.assert(
+      fc.property(hostile, (value) => {
+        const r = resolve('antigravity', { config: { [AGY_KEY]: value } });
+        assert.equal(r.ok, true);
+        assert.equal(r.plan.timeoutMs, AGY_FLOOR);
+      }),
+      FC,
+    );
+  });
+
+  test('a configured antigravity timeout derives both the outer cap and the native flag (row 10)', () => {
+    const r = resolve('antigravity', { config: { [AGY_KEY]: 900 } });
+    assert.equal(r.plan.timeoutMs, 900_000);
+    const i = r.plan.argv.indexOf('--print-timeout');
+    assert.equal(r.plan.argv[i + 1], '840s');
+  });
+
+  test('a native timeout below the 60s buffer clamps to 1s, never 0 or negative (row 11)', () => {
+    const r = resolve('antigravity', { config: { [AGY_KEY]: 30 } });
+    const i = r.plan.argv.indexOf('--print-timeout');
+    assert.equal(r.plan.argv[i + 1], '1s');
+  });
+
+  test('boundary around the 60-second native buffer (row 12)', () => {
+    const nativeFor = (seconds) => {
+      const r = resolve('antigravity', { config: { [AGY_KEY]: seconds } });
+      return r.plan.argv[r.plan.argv.indexOf('--print-timeout') + 1];
+    };
+    assert.equal(nativeFor(59), '1s');   // floor(59)-60 = -1 -> clamped
+    assert.equal(nativeFor(60), '1s');   // floor(60)-60 = 0 -> clamped
+    assert.equal(nativeFor(61), '1s');   // floor(61)-60 = 1
+    assert.equal(nativeFor(121), '61s'); // floor(121)-60 = 61
+  });
+});
+
 describe('reviewer lane invocation — model resolution', () => {
   test("antigravity resolves its model from review.models.agy, not the slug", () => {
     // The regression this locks: antigravity's slug is `antigravity` but its shipped key is

tests/reviewer-manifest-body.test.cjs

@@ -1178,6 +1178,49 @@ describe('F. Lane scalars', () => {
   });
 });
 
+// ─── F2. timeoutConfigKey (#3274) — mirrors modelConfigKey's D4 forward/backward-compat shape ──
+
+describe('F2. timeoutConfigKey (#3274)', () => {
+  test('reviewer.timeoutConfigKey is optional — absent is valid (row 14)', () => {
+    const lane = laneOverride(() => {});
+    assert.equal(lane.timeoutConfigKey, undefined, 'fixture must not declare timeoutConfigKey');
+    const errs = validateReviewerBody({ id: 'x', reviewer: lane });
+    assert.deepEqual(errs, [], `expected no errors, got: ${JSON.stringify(errs)}`);
+  });
+
+  test('reviewer.timeoutConfigKey: null is valid (row 15)', () => {
+    const lane = laneOverride((l) => { l.timeoutConfigKey = null; });
+    const errs = validateReviewerBody({ id: 'x', reviewer: lane });
+    assert.deepEqual(errs, [], `expected no errors, got: ${JSON.stringify(errs)}`);
+  });
+
+  test('reviewer.timeoutConfigKey: a dotted string is valid (row 16)', () => {
+    const lane = laneOverride((l) => { l.timeoutConfigKey = 'review.timeouts.acme'; });
+    const errs = validateReviewerBody({ id: 'x', reviewer: lane });
+    assert.deepEqual(errs, [], `expected no errors, got: ${JSON.stringify(errs)}`);
+  });
+
+  test('reviewer.timeoutConfigKey: empty string is rejected (row 17)', () => {
+    const lane = laneOverride((l) => { l.timeoutConfigKey = ''; });
+    const errs = validateReviewerBody({ id: 'x', reviewer: lane });
+    assert.ok(
+      errs.some((e) => e.includes('reviewer.timeoutConfigKey must be a dotted config key or null') && e.includes('(got: "")')),
+      `expected an empty-string-is-not-none error, got: ${JSON.stringify(errs)}`,
+    );
+  });
+
+  test('reviewer.timeoutConfigKey: non-string, non-null is rejected (row 18)', () => {
+    for (const bad of [42, {}, []]) {
+      const lane = laneOverride((l) => { l.timeoutConfigKey = bad; });
+      const errs = validateReviewerBody({ id: 'x', reviewer: lane });
+      assert.ok(
+        errs.some((e) => e.includes('reviewer.timeoutConfigKey must be a dotted config key or null')),
+        `timeoutConfigKey=${JSON.stringify(bad)}: expected a type-rejection error, got: ${JSON.stringify(errs)}`,
+      );
+    }
+  });
+});
+
 // ─── G. Uniqueness (D8) — validateCrossCapability(Map, Set) ────────────────
 
 describe('G. Uniqueness (D8) — validateCrossCapability(Map, Set)', () => {