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>

src/review-lane-descriptor.cts

@@ -44,6 +44,9 @@
  *   4. `flags: string[]` — Antigravity is selected by BOTH `--antigravity` and
  *      `--agy`, which a single-valued field cannot express. This also flattens
  *      D8's uniqueness invariant across every lane's flags.
+ *   5. `NATIVE_TIMEOUT` — a lane whose CLI takes its own native inner timeout flag (today only
+ *      antigravity's `--print-timeout`) declares where the resolved value goes; `resolveLanePlan`
+ *      computes what it is from the same resolved outer `timeoutMs` (#3274).
  *
  * Phase 2 (#2795) implements the manifest validator against the amended
  * vocabulary, which is the point of amending rather than leaving it to be
@@ -110,7 +113,7 @@ export type LaneProbe =
  * and vanishes when it has nothing to contribute (no model configured, no effort channel, prompt on
  * stdin), which is what lets one template serve the configured and unconfigured cases.
  *
- * This is a closed four-member vocabulary with no expressions, no nesting and no conditionals — a
+ * This is a closed five-member vocabulary with no expressions, no nesting and no conditionals — a
  * placeholder set, deliberately not a template language. The moment it needs a conditional, the
  * lane wants a `handler` instead (D6).
  */
@@ -123,6 +126,9 @@ export const ARGV_PLACEHOLDER = Object.freeze({
   OUTPUT: '{{output}}',
   /** The argv-borne prompt, or nothing unless `promptChannel` is `argv`/`argv-file-ref`. */
   PROMPT: '{{prompt}}',
+  /** A lane's own CLI-native inner timeout duration, derived from the resolved outer `timeoutMs`
+   * (never independently configured) — see `resolveLanePlan`'s expansion of this token. */
+  NATIVE_TIMEOUT: '{{nativeTimeout}}',
 } as const);
 
 export interface SpawnInvoke {
@@ -178,6 +184,23 @@ interface ReviewerLaneCommon {
   probe: LaneProbe;
   /** Outer wall-clock bound. An inner tool-native timeout lives in the handler (D6). */
   timeoutFloorMs: number;
+  /**
+   * Dotted config key holding this lane's outer timeout override, in SECONDS, or null when the
+   * lane accepts none.
+   *
+   * Added by #3274 in the same spirit as `promptBudgetKey`/`modelConfigKey`: the frozen
+   * `timeoutFloorMs` table has no reachable override, and a review duration is a property of the
+   * user's repository and model, not of the lane — a cap right for a three-plan phase is wrong
+   * for a fifteen-plan one. Resolved at invocation time (`resolveLanePlan`); an unset key, or a
+   * config value that is not a positive finite number, falls back to `timeoutFloorMs` unchanged.
+   * For a lane whose `args` template ALSO carries a native tool-side timeout (antigravity's
+   * `--print-timeout`, via the `{{nativeTimeout}}` ARGV_PLACEHOLDER), the resolved value feeds both
+   * levels — see `resolveLanePlan`'s expansion of that token. Three lanes — `qwen`, `cursor`,
+   * `coderabbit` — accept neither a model flag nor a host and own no `review.timeouts.<slug>` key
+   * either, matching the same narrow key-ownership invariant `modelConfigKey` already follows for
+   * them (#3691 narrows #2797).
+   */
+  timeoutConfigKey: string | null;
   emptyOutput: EmptyOutputPolicy;
   /** The `## <reviewsSection> Review` heading in write_reviews. Unique (D8). */
   reviewsSection: string;
@@ -249,6 +272,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       effortChannel: 'none',
     },
     timeoutFloorMs: 900_000,
+    timeoutConfigKey: 'review.timeouts.gemini',
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'Gemini',
     evidenceClass: 'source-grounded',
@@ -281,6 +305,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       env: { CLAUDE_CODE_DISABLE_CLAUDE_MDS: '1', CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1' },
     },
     timeoutFloorMs: 1_200_000,
+    timeoutConfigKey: 'review.timeouts.claude',
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'Claude',
     evidenceClass: 'source-grounded',
@@ -309,6 +334,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       effortChannel: 'argv',
     },
     timeoutFloorMs: 1_200_000,
+    timeoutConfigKey: 'review.timeouts.codex',
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'Codex',
     evidenceClass: 'source-grounded',
@@ -334,6 +360,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       effortChannel: 'none',
     },
     timeoutFloorMs: 360_000,
+    timeoutConfigKey: null,
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'CodeRabbit',
     evidenceClass: 'diff-only',
@@ -359,6 +386,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       effortChannel: 'argv',
     },
     timeoutFloorMs: 660_000,
+    timeoutConfigKey: 'review.timeouts.opencode',
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'OpenCode',
     evidenceClass: 'source-grounded',
@@ -384,6 +412,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       effortChannel: 'none',
     },
     timeoutFloorMs: 900_000,
+    timeoutConfigKey: null,
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'Qwen',
     evidenceClass: 'source-grounded',
@@ -409,6 +438,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       effortChannel: 'none',
     },
     timeoutFloorMs: 900_000,
+    timeoutConfigKey: null,
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'Cursor',
     evidenceClass: 'source-grounded',
@@ -428,13 +458,19 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
     probe: { kind: 'command-exists', binary: 'agy' },
     invoke: {
       binary: 'agy',
-      args: ['--print-timeout', '540s', '{{model}}', '-p', '{{prompt}}'],
+      // `{{nativeTimeout}}` is the fifth ARGV_PLACEHOLDER member (#3274) — `resolveLanePlan`
+      // (review-lane-invocation.cts) expands it to a value DERIVED from this same lane's resolved
+      // outer `timeoutMs`, so the native `--print-timeout` and the outer wall-clock cap can never
+      // drift apart. No other shipped lane's `args` template contains this token, so the expansion
+      // is inert everywhere else.
+      args: ['--print-timeout', '{{nativeTimeout}}', '{{model}}', '-p', '{{prompt}}'],
       promptChannel: 'argv-file-ref',
       outputChannel: 'stdout',
       modelArg: '--model',
       effortChannel: 'none',
     },
     timeoutFloorMs: 600_000,
+    timeoutConfigKey: 'review.timeouts.antigravity',
     emptyOutput: 'handler-owned',
     reviewsSection: 'Antigravity',
     evidenceClass: 'source-grounded',
@@ -465,6 +501,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       effortChannel: 'none',
     },
     timeoutFloorMs: 120_000,
+    timeoutConfigKey: 'review.timeouts.ollama',
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'Ollama',
     evidenceClass: 'source-grounded',
@@ -494,6 +531,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       effortChannel: 'none',
     },
     timeoutFloorMs: 120_000,
+    timeoutConfigKey: 'review.timeouts.lm_studio',
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'LM Studio',
     evidenceClass: 'source-grounded',
@@ -521,6 +559,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       effortChannel: 'none',
     },
     timeoutFloorMs: 120_000,
+    timeoutConfigKey: 'review.timeouts.llama_cpp',
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'llama.cpp',
     evidenceClass: 'source-grounded',
@@ -566,6 +605,7 @@ export const REVIEWER_LANES: ReadonlyArray<ReviewerLane> = Object.freeze([
       effortChannel: 'none',
     },
     timeoutFloorMs: 900_000,
+    timeoutConfigKey: 'review.timeouts.kimi-code',
     emptyOutput: 'stub-with-stderr',
     reviewsSection: 'Kimi Code',
     evidenceClass: 'source-grounded',

src/review-lane-invocation.cts

@@ -254,6 +254,44 @@ export function normalizeHost(raw: string): string {
   return `${scheme}//${host}${port ? `:${port}` : ''}${pathPart}`;
 }
 
+/**
+ * Resolve a lane's outer wall-clock timeout in milliseconds (#3274).
+ *
+ * `timeoutConfigKey` resolves in SECONDS — the user-facing convention this repo already uses for
+ * timeout-shaped config keys (`workflow.cross_ai_timeout`, `graphify.build_timeout`), distinct from
+ * the internal millisecond unit `timeoutFloorMs` carries. Anything that is not a positive finite
+ * number is treated as unset and falls back to `floorMs`, never coerced: a wrong-typed config value
+ * silently becoming a wrong-but-plausible timeout is worse than falling back cleanly. `0` and
+ * negative values are deliberately treated as unset too — a timeout has no legitimate zero or
+ * negative value, so no second sentinel (unlike the prompt-budget keys, which use -1) is needed.
+ */
+export function resolveTimeoutMs(
+  timeoutConfigKey: string | null | undefined,
+  floorMs: number,
+  configGet: (key: string) => unknown,
+): number {
+  const configuredSeconds = typeof timeoutConfigKey === 'string' ? configGet(timeoutConfigKey) : undefined;
+  return typeof configuredSeconds === 'number' && Number.isFinite(configuredSeconds) && configuredSeconds > 0
+    ? configuredSeconds * 1000
+    : floorMs;
+}
+
+/** Buffer (seconds) a lane's native inner timeout sits under its resolved outer wall-clock cap
+ * (#3274). Matches the shipped 600s outer / 540s native relationship exactly when unconfigured:
+ * floor(600000/1000) - 60 = 540. */
+const NATIVE_TIMEOUT_BUFFER_SECONDS = 60;
+
+/**
+ * Render the `{{nativeTimeout}}` argv placeholder from a lane's resolved outer timeout (#3274).
+ *
+ * Clamped to a 1-second floor so a very small configured (or, today, only-ever-default) outer
+ * timeout never produces a zero or negative duration string a CLI would reject or misinterpret.
+ */
+export function nativeTimeoutToken(timeoutMs: number): string {
+  const seconds = Math.max(1, Math.floor(timeoutMs / 1000) - NATIVE_TIMEOUT_BUFFER_SECONDS);
+  return `${seconds}s`;
+}
+
 /**
  * Classify a lane's output as a review or as empty.
  *
@@ -362,10 +400,11 @@ export function resolveLanePlan(input: ResolveInput): ResolveResult {
   }
 
   const { promptPath, reviewPath, errPath } = artifactPaths(input.runDir, slug);
-  const timeoutMs =
+  const floorMs =
     typeof lane.timeoutFloorMs === 'number' && Number.isFinite(lane.timeoutFloorMs) && lane.timeoutFloorMs > 0
       ? lane.timeoutFloorMs
       : 900_000;
+  const timeoutMs = resolveTimeoutMs(lane.timeoutConfigKey, floorMs, input.configGet);
   const emptyOutput: EmptyOutputPolicy = lane.emptyOutput === 'handler-owned' ? 'handler-owned' : 'stub-with-stderr';
   // #3194: only an EXACT 'diff-only' declaration exempts a lane from evidence verification.
   // Anything else — including a missing or garbage value on a third-party overlay body —
@@ -503,6 +542,7 @@ export function resolveLanePlan(input: ResolveInput): ResolveResult {
     '{{effort}}': effortExpansion,
     '{{output}}': outputExpansion,
     '{{prompt}}': promptExpansion,
+    '{{nativeTimeout}}': [nativeTimeoutToken(timeoutMs)],
   };
   const template = Array.isArray(inv.args)
     ? inv.args.filter((a): a is string => typeof a === 'string')

src/review-lane-runner.cts

@@ -817,9 +817,13 @@ export function antigravityPrompt(promptPath: string, repoRoot: string): string
  *    lane that fails to start is worse than one that runs on the prompt anchor alone.
  * 2. The self-report prompt variant above, swapped in for the standard file-ref text.
  *
- * Both are argv shape, so they belong here rather than in the descriptor: expressing "add this flag
- * only if the binary's --help mentions it" as data would need a conditional, which is precisely
- * what the named-handler seam exists to absorb (ADR-2782 D6).
+ * Both are argv shape, so they belong here rather than in the descriptor: expressing "add this
+ * flag only if the binary's --help mentions it" as data would need a conditional, which is
+ * precisely what the named-handler seam exists to absorb (ADR-2782 D6). The native
+ * `--print-timeout` VALUE (#3274) is NOT this handler's job — `resolveLanePlan`
+ * (review-lane-invocation.cts) resolves the `{{nativeTimeout}}` ARGV_PLACEHOLDER itself, exactly
+ * like `{{model}}`/`{{effort}}`/`{{output}}`/`{{prompt}}`, so `plan.argv` arrives here already fully
+ * resolved.
  */
 export function antigravityArgv(
   argv: readonly string[],