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>
This commit is contained in:
Tom Boucher
2026-08-30 14:26:02 -04:00
committed by GitHub
parent 6eea00b707
commit 62b0d939b6
23 changed files with 518 additions and 11 deletions

View File

@@ -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')