@opengsd/gsd-core 1.12.0 → 1.13.0

package/gsd-core/bin/lib/review-lane-descriptor.cjs

@@ -45,6 +45,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
@@ -69,7 +72,7 @@ exports.checkReviewerDocsParity = checkReviewerDocsParity;
  * 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).
  */
@@ -82,6 +85,9 @@ exports.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}}',
 });
 const SPAWN_STDIN_STDOUT = {
     promptChannel: 'stdin',
@@ -107,12 +113,15 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'none',
         },
         timeoutFloorMs: 900_000,
+        timeoutConfigKey: 'review.timeouts.gemini',
         emptyOutput: 'stub-with-stderr',
         reviewsSection: 'Gemini',
         evidenceClass: 'source-grounded',
         requiresBinaries: [],
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.gemini',
         modelConfigKey: 'review.models.gemini',
+        effortConfigKey: null,
+        defaultEffort: null,
         handler: null,
     },
     {
@@ -139,12 +148,15 @@ exports.REVIEWER_LANES = 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',
         requiresBinaries: [],
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.claude',
         modelConfigKey: 'review.models.claude',
+        effortConfigKey: 'review.effort.claude',
+        defaultEffort: 'high',
         handler: null,
     },
     {
@@ -167,12 +179,15 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'argv',
         },
         timeoutFloorMs: 1_200_000,
+        timeoutConfigKey: 'review.timeouts.codex',
         emptyOutput: 'stub-with-stderr',
         reviewsSection: 'Codex',
         evidenceClass: 'source-grounded',
         requiresBinaries: [],
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.codex',
         modelConfigKey: 'review.models.codex',
+        effortConfigKey: 'review.effort.codex',
+        defaultEffort: 'high',
         handler: null,
     },
     {
@@ -192,6 +207,7 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'none',
         },
         timeoutFloorMs: 360_000,
+        timeoutConfigKey: null,
         emptyOutput: 'stub-with-stderr',
         reviewsSection: 'CodeRabbit',
         evidenceClass: 'diff-only',
@@ -199,6 +215,8 @@ exports.REVIEWER_LANES = Object.freeze([
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.coderabbit',
         // Accepts no model flag at all (review.md:367) — not merely "none configured".
         modelConfigKey: null,
+        effortConfigKey: null,
+        defaultEffort: null,
         handler: null,
     },
     {
@@ -217,6 +235,7 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'argv',
         },
         timeoutFloorMs: 660_000,
+        timeoutConfigKey: 'review.timeouts.opencode',
         emptyOutput: 'stub-with-stderr',
         reviewsSection: 'OpenCode',
         evidenceClass: 'source-grounded',
@@ -225,6 +244,8 @@ exports.REVIEWER_LANES = Object.freeze([
         requiresBinaries: [],
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.opencode',
         modelConfigKey: 'review.models.opencode',
+        effortConfigKey: 'review.effort.opencode',
+        defaultEffort: 'high',
         // Phase 5b (#2799): was `null`. The review is REBUILT from assistant `text` parts; a plain
         // stdout copy would write the raw JSON envelope as the review (#1936). See LaneHandler.
         handler: 'opencode',
@@ -242,12 +263,15 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'none',
         },
         timeoutFloorMs: 900_000,
+        timeoutConfigKey: null,
         emptyOutput: 'stub-with-stderr',
         reviewsSection: 'Qwen',
         evidenceClass: 'source-grounded',
         requiresBinaries: [],
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.qwen',
         modelConfigKey: null,
+        effortConfigKey: null,
+        defaultEffort: null,
         handler: null,
     },
     {
@@ -260,19 +284,23 @@ exports.REVIEWER_LANES = Object.freeze([
         probe: { kind: 'command-exists', binary: 'cursor-agent' },
         invoke: {
             binary: 'cursor-agent',
-            args: ['-p', '--mode', 'ask', '--trust', '--output-format', 'text', '{{prompt}}'],
+            args: ['-p', '{{model}}', '--mode', 'ask', '--trust', '--output-format', 'text', '{{prompt}}'],
             promptChannel: 'argv-file-ref',
             outputChannel: 'stdout',
-            modelArg: null,
+            modelArg: '--model',
             effortChannel: 'none',
         },
         timeoutFloorMs: 900_000,
+        timeoutConfigKey: null,
         emptyOutput: 'stub-with-stderr',
         reviewsSection: 'Cursor',
         evidenceClass: 'source-grounded',
         requiresBinaries: [],
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.cursor',
-        modelConfigKey: null,
+        // #3653: cursor-agent exposes --model (204 selectable models); wired the same as codex.
+        modelConfigKey: 'review.models.cursor',
+        effortConfigKey: null,
+        defaultEffort: null,
         handler: null,
     },
     {
@@ -286,13 +314,19 @@ exports.REVIEWER_LANES = 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',
@@ -302,6 +336,8 @@ exports.REVIEWER_LANES = Object.freeze([
         // NOT `review.models.antigravity` — the shipped key is `review.models.agy` (review.md:291) and
         // Phase 4 federated it under that name. This lane is why the key is declared, not derived.
         modelConfigKey: 'review.models.agy',
+        effortConfigKey: null,
+        defaultEffort: null,
         handler: 'antigravity',
     },
     {
@@ -323,6 +359,7 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'none',
         },
         timeoutFloorMs: 120_000,
+        timeoutConfigKey: 'review.timeouts.ollama',
         emptyOutput: 'stub-with-stderr',
         reviewsSection: 'Ollama',
         evidenceClass: 'source-grounded',
@@ -331,6 +368,8 @@ exports.REVIEWER_LANES = Object.freeze([
         requiresBinaries: [],
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.ollama',
         modelConfigKey: 'review.models.ollama',
+        effortConfigKey: null,
+        defaultEffort: null,
         handler: 'openai-compatible',
     },
     {
@@ -352,12 +391,15 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'none',
         },
         timeoutFloorMs: 120_000,
+        timeoutConfigKey: 'review.timeouts.lm_studio',
         emptyOutput: 'stub-with-stderr',
         reviewsSection: 'LM Studio',
         evidenceClass: 'source-grounded',
         requiresBinaries: [],
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.lm_studio',
         modelConfigKey: 'review.models.lm_studio',
+        effortConfigKey: null,
+        defaultEffort: null,
         handler: 'openai-compatible',
     },
     {
@@ -379,12 +421,15 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'none',
         },
         timeoutFloorMs: 120_000,
+        timeoutConfigKey: 'review.timeouts.llama_cpp',
         emptyOutput: 'stub-with-stderr',
         reviewsSection: 'llama.cpp',
         evidenceClass: 'source-grounded',
         requiresBinaries: [],
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.llama_cpp',
         modelConfigKey: 'review.models.llama_cpp',
+        effortConfigKey: null,
+        defaultEffort: null,
         handler: 'openai-compatible',
     },
     {
@@ -424,12 +469,15 @@ exports.REVIEWER_LANES = Object.freeze([
             effortChannel: 'none',
         },
         timeoutFloorMs: 900_000,
+        timeoutConfigKey: 'review.timeouts.kimi-code',
         emptyOutput: 'stub-with-stderr',
         reviewsSection: 'Kimi Code',
         evidenceClass: 'source-grounded',
         requiresBinaries: [],
         promptBudgetKey: 'review.max_prompt_tokens_per_reviewer.kimi-code',
         modelConfigKey: 'review.models.kimi-code',
+        effortConfigKey: null,
+        defaultEffort: null,
         handler: null,
     },
 ].map((lane) => Object.freeze(lane)));

package/gsd-core/bin/lib/review-lane-invocation.cjs

@@ -26,6 +26,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LANE_UNAVAILABLE = void 0;
 exports.configString = configString;
 exports.normalizeHost = normalizeHost;
+exports.resolveLaneEffort = resolveLaneEffort;
+exports.resolveTimeoutMs = resolveTimeoutMs;
+exports.nativeTimeoutToken = nativeTimeoutToken;
 exports.isEmptyReview = isEmptyReview;
 exports.fileRefPrompt = fileRefPrompt;
 exports.resolveLanePlan = resolveLanePlan;
@@ -122,6 +125,73 @@ function normalizeHost(raw) {
     const pathPart = u.pathname.replace(/\/+$/, '');
     return `${scheme}//${host}${port ? `:${port}` : ''}${pathPart}`;
 }
+/** Levels GSD's effort axis accepts (#3533). `inherit` selects the no-argument path. */
+const EFFORT_LEVELS = new Set([
+    'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'inherit',
+]);
+/**
+ * Resolve one lane's reasoning effort from REVIEW configuration (#4255).
+ *
+ * Resolution order, highest first:
+ *   1. `lane.effortConfigKey` — the per-lane review effort the operator set
+ *   2. `lane.defaultEffort` — the lane's declared review default (`high` for prompt-fed,
+ *      source-grounded lanes)
+ *   3. nothing — no effort argument is emitted and the reviewer CLI's own configuration decides
+ *
+ * A configured `'inherit'` selects (3) explicitly. An unrecognized level is REFUSED rather than
+ * passed to the host: it falls back to the lane default, because forwarding a typo would render an
+ * argument the CLI rejects and kill the lane outright.
+ *
+ * What this function deliberately does NOT do is consult any agent's execution settings. Before
+ * #4255 the level came from `gsd-plan-checker`'s installed frontmatter through a hardcoded agent
+ * id, so every lane ran at a fast structural verifier's `low` — and, because the rendered argument
+ * is a CLI config override, it silently beat the effort the operator had configured for that CLI
+ * itself. A value inherited from an unrelated agent is worse than no value at all, which is why
+ * (3) emits nothing rather than falling back to some other agent's number.
+ *
+ * `renderArgv` is injected (the host table and the ADR-2481 surface negotiation live in
+ * `model-catalog` / `commands`, above this module's layer) so this stays a pure function of its
+ * inputs and the golden lane table can assert it without a spawn.
+ */
+function resolveLaneEffort(lane, configGet, renderArgv) {
+    const none = { argv: [], value: null, source: 'none' };
+    if (!lane || typeof lane !== 'object')
+        return none;
+    const configured = lane.effortConfigKey ? configString(configGet(lane.effortConfigKey)) : null;
+    const valid = configured !== null && EFFORT_LEVELS.has(configured) ? configured : null;
+    const level = valid ?? configString(lane.defaultEffort);
+    if (level === null || level === 'inherit')
+        return none;
+    const rendered = renderArgv(lane.slug, level);
+    const argv = (rendered.argv ?? []).filter((a) => typeof a === 'string' && a !== '');
+    if (argv.length === 0)
+        return none;
+    return {
+        argv,
+        value: configString(rendered.value) ?? level,
+        source: valid !== null ? 'config' : 'lane-default',
+    };
+}
+function resolveTimeoutMs(timeoutConfigKey, floorMs, configGet) {
+    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.
+ */
+function nativeTimeoutToken(timeoutMs) {
+    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.
  *
@@ -212,9 +282,10 @@ function resolveLanePlan(input) {
         return fail(exports.LANE_UNAVAILABLE.UNKNOWN_HANDLER, `lane '${slug}' names handler '${String(handler)}', which this GSD version does not provide`);
     }
     const { promptPath, reviewPath, errPath } = artifactPaths(input.runDir, slug);
-    const timeoutMs = typeof lane.timeoutFloorMs === 'number' && Number.isFinite(lane.timeoutFloorMs) && lane.timeoutFloorMs > 0
+    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 = 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 —
@@ -319,6 +390,7 @@ function resolveLanePlan(input) {
         '{{effort}}': effortExpansion,
         '{{output}}': outputExpansion,
         '{{prompt}}': promptExpansion,
+        '{{nativeTimeout}}': [nativeTimeoutToken(timeoutMs)],
     };
     const template = Array.isArray(inv.args)
         ? inv.args.filter((a) => typeof a === 'string')

package/gsd-core/bin/lib/review-lane-runner.cjs

@@ -27,12 +27,13 @@
  * "failed" and "ran cleanly with nothing to report" IS the defect this epic closes (#2494/#2605).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MODEL_VALUE_MAX = exports.BANNER_SCAN_LINES = exports.UNRESOLVED_MODEL = exports.MODEL_SOURCE = void 0;
+exports.ANTIGRAVITY_FAILURE_MODE = exports.MODEL_VALUE_MAX = exports.BANNER_SCAN_LINES = exports.UNRESOLVED_MODEL = exports.MODEL_SOURCE = void 0;
 exports.parseModelBanner = parseModelBanner;
 exports.parseTranscriptModel = parseTranscriptModel;
 exports.checkEgressHost = checkEgressHost;
 exports.probeLane = probeLane;
 exports.writeReviewOrStub = writeReviewOrStub;
+exports.emptyOutputDiagnosis = emptyOutputDiagnosis;
 exports.handleOpencodeOutput = handleOpencodeOutput;
 exports.antigravityWatermark = antigravityWatermark;
 exports.antigravityTranscriptFallback = antigravityTranscriptFallback;
@@ -40,6 +41,7 @@ exports.antigravityModel = antigravityModel;
 exports.resolveSpawnModel = resolveSpawnModel;
 exports.antigravityPrompt = antigravityPrompt;
 exports.antigravityArgv = antigravityArgv;
+exports.antigravityFailureMode = antigravityFailureMode;
 exports.antigravityDiagnostic = antigravityDiagnostic;
 exports.stampBlindReview = stampBlindReview;
 exports.stampUngroundedReview = stampUngroundedReview;
@@ -354,8 +356,15 @@ async function probeLane(plan, deps) {
  * `extraDiagnostics` carries the raw HTTP response body for the OpenAI-compatible lanes: an error
  * from such a server arrives with HTTP 4xx/5xx and the JSON in the BODY, so stderr alone is empty
  * and the body is the only evidence.
+ *
+ * `outcome` (#4255) carries the spawn's exit status so the stub can say WHICH empty it is. The
+ * header alone cannot: a crash, a timeout kill and a model that ended its turn without writing a
+ * final message all reach here as the same zero bytes, and the third is what a too-low reasoning
+ * effort produces on a large source-grounded prompt. A clean exit inside the timeout with no
+ * output is a stopped-short model, and the stub now says so — with the effort it ran at, which is
+ * the value the operator would change.
  */
-function writeReviewOrStub(plan, content, deps, extraDiagnostics) {
+function writeReviewOrStub(plan, content, deps, extraDiagnostics, outcome) {
     if (!(0, review_lane_invocation_cjs_1.isEmptyReview)(content)) {
         deps.writeFile(plan.reviewPath, content.endsWith('\n') ? content : `${content}\n`);
         return { stubbed: false };
@@ -364,9 +373,53 @@ function writeReviewOrStub(plan, content, deps, extraDiagnostics) {
     const parts = [`${plan.slug} review failed or returned empty output. stderr:`, stderr];
     if (extraDiagnostics)
         parts.push('Raw response body:', extraDiagnostics);
+    parts.push(emptyOutputDiagnosis(plan, outcome));
     deps.writeFile(plan.reviewPath, `${parts.join('\n')}\n`);
     return { stubbed: true };
 }
+/**
+ * One line naming the effort the lane ran at and how the process ended (#4255).
+ *
+ * Kept out of the header so the `failed or returned empty output` string every downstream reader
+ * greps for is untouched — this is an added line, not a reworded one.
+ */
+function emptyOutputDiagnosis(plan, outcome) {
+    // `effort` lives on the spawn plan only. An HTTP lane reaches a server directly and has no
+    // reviewer CLI at all, so naming one there would be a lie about what ran (Codex review of
+    // #4255) — the two transports get different, accurate wording.
+    const spawned = plan.transport === 'spawn';
+    const level = spawned ? plan.effort : null;
+    const effort = level
+        ? `ran at effort=${level}`
+        : spawned
+            ? "ran with no effort argument, so the reviewer CLI's own configuration applied"
+            : 'is an HTTP lane and carries no reasoning-effort setting';
+    if (!outcome)
+        return `Diagnosis: ${plan.slug} ${effort}.`;
+    // Four endings, not two. `status` is null for BOTH a timeout kill and a process that never
+    // ran or died on a signal (ENOENT, SIGKILL) — reporting the latter as "status null" said
+    // nothing, and folding them together would attach the stopped-short hint to a crash.
+    const timedOut = outcome.errorCode === 'ETIMEDOUT';
+    const neverRan = !timedOut && outcome.status === null;
+    const cleanExit = outcome.status === 0;
+    const ending = timedOut
+        ? 'was killed by the outer timeout'
+        : neverRan
+            ? `did not exit normally (${outcome.errorCode ?? 'killed by a signal'})`
+            : cleanExit
+                ? 'exited cleanly inside the timeout'
+                : `exited with status ${String(outcome.status)}`;
+    // Hedged deliberately. A clean exit with no output is CONSISTENT with a model ending its turn
+    // without a final message — which is what too low an effort produces on a large prompt — but it
+    // is equally consistent with the CLI writing its output somewhere this lane did not read. The
+    // line points at the likeliest cause without asserting it.
+    const tail = cleanExit
+        ? ' — a clean exit that produced no output is most often a model ending its turn without'
+            + ' writing a final message rather than a crash; if this lane carries a reasoning effort,'
+            + ' raising it is the usual fix.'
+        : '.';
+    return `Diagnosis: ${plan.slug} ${effort} and ${ending}${tail}`;
+}
 /* ------------------------------------------------------------------ *
  * Handlers (D6) — named first-party code, never conditionals in data
  * ------------------------------------------------------------------ */
@@ -677,9 +730,13 @@ function antigravityPrompt(promptPath, repoRoot) {
  *    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.
  */
 function antigravityArgv(argv, promptPath, repoRoot, deps) {
     const standard = (0, review_lane_invocation_cjs_1.fileRefPrompt)(promptPath, repoRoot);
@@ -710,8 +767,54 @@ function antigravityArgv(argv, promptPath, repoRoot, deps) {
  *
  * Mode 3 (a pre-session stall, which `--print-timeout` cannot bound because it cannot fire before a
  * session exists) leaves no log line at all, so its tell is stated rather than searched for.
+ *
+ * #3996 mode 4 (a headless tool-permission denial) exits 0 with empty stdout and a POPULATED
+ * transcript, and reports the cause only on stderr — so the stub carries the run's stderr
+ * (`evidence.stderr`, the same `plan.errPath` content the generic stub reads), and the mode-3
+ * tell is stated only when `antigravityFailureMode` rules a session out (a fresh conv-id or
+ * transcript growth past the watermark means one verifiably started). Asserting mode 3 over a
+ * transcript this code just read inverts who is better placed to know.
  */
-function antigravityDiagnostic(deps) {
+/**
+ * What actually failed, as a typed fact rather than a guess baked into prose. #3996.
+ *
+ * The session-started question is decidable at diagnostic time with the same staleness rule the
+ * layer-2 fallback uses: re-resolve the workspace's CURRENT conv-id and compare against the
+ * pre-spawn watermark. A conv-id that changed, or a transcript that grew past the watermark
+ * line count, means THIS invocation demonstrably reached a session — a pre-launch stall is
+ * ruled out. An unchanged conv-id with no growth means nothing new happened, which is the
+ * #2073 mode-3 shape even when a PRIOR session's transcript still exists on disk (existence
+ * alone would mis-diagnose mode 3 as mode 4 in any workspace with history).
+ */
+exports.ANTIGRAVITY_FAILURE_MODE = Object.freeze({
+    /** A session ran this invocation (fresh conv-id, or transcript growth) but no review was recovered. */
+    SESSION_STARTED: 'session_started',
+    /** No session this invocation — the #2073 mode-3 stall tell is the right signpost. */
+    PRE_SESSION_STALL: 'pre_session_stall',
+});
+function antigravityFailureMode(workspace, mark, deps) {
+    const convId = resolveWorkspaceConvId(workspace, deps);
+    if (!convId)
+        return exports.ANTIGRAVITY_FAILURE_MODE.PRE_SESSION_STALL;
+    // A different conv-id than the watermark saw = a fresh session this run, transcript or not.
+    if (convId !== mark.convId)
+        return exports.ANTIGRAVITY_FAILURE_MODE.SESSION_STARTED;
+    const tx = transcriptPath(deps.homeDir, convId);
+    if (!deps.exists(tx))
+        return exports.ANTIGRAVITY_FAILURE_MODE.PRE_SESSION_STALL;
+    try {
+        const lines = deps.readFile(tx).split(/\r?\n/).filter((l) => l.trim()).length;
+        return lines > mark.lines
+            ? exports.ANTIGRAVITY_FAILURE_MODE.SESSION_STARTED
+            : exports.ANTIGRAVITY_FAILURE_MODE.PRE_SESSION_STALL;
+    }
+    catch {
+        // #3118 fail-closed shape: the transcript indisputably exists but cannot be read — do not
+        // assert the stall case over a file this code cannot check.
+        return exports.ANTIGRAVITY_FAILURE_MODE.SESSION_STARTED;
+    }
+}
+function antigravityDiagnostic(deps, evidence = {}) {
     const lines = [
         'Antigravity review failed or returned empty output.',
     ];
@@ -731,8 +834,28 @@ function antigravityDiagnostic(deps) {
             /* an unreadable log is not worth failing the lane over */
         }
     }
-    lines.push('If no agy run started, that is the pre-session-stall case: check whether a new ' +
-        '~/.gemini/antigravity-cli/brain/<conv-id>/ dir appeared within ~30s of launch.');
+    // #3996: the stub carries agy's stderr, as the generic lane stub already does — mode 4 (a
+    // headless tool-permission denial) exits 0 with empty stdout and a populated transcript, and
+    // the stderr line is the only signal that names its cause.
+    const stderr = (evidence.stderr ?? '').trim();
+    if (stderr)
+        lines.push('stderr:', stderr);
+    // #3996: mode 3's tell is stated only when its precondition holds — the mode is computed from
+    // the watermark (#3996 mode 3 in a workspace with history is a no-growth transcript, not an
+    // absent one), never guessed from prose.
+    if (evidence.mode === exports.ANTIGRAVITY_FAILURE_MODE.SESSION_STARTED) {
+        lines.push('An agy session started this run but no review was recovered, so a pre-launch stall is ' +
+            'ruled out.' +
+            (stderr
+                ? ' See stderr above; a headless run that was auto-denied a tool permission reports ' +
+                    'the cause and its fix there.'
+                : ' agy reported nothing on its error stream; inspect the transcript under ' +
+                    '~/.gemini/antigravity-cli/brain/<conv-id>/ for where the session stopped.'));
+    }
+    else {
+        lines.push('If no agy run started, that is the pre-session-stall case: check whether a new ' +
+            '~/.gemini/antigravity-cli/brain/<conv-id>/ dir appeared within ~30s of launch.');
+    }
     return lines.join('\n');
 }
 /**
@@ -948,7 +1071,10 @@ function runSpawnLane(plan, deps, repoRoot) {
             // pinned model that 404s server-side and exits 0 with empty output, so the model IS the
             // diagnosis — dropping it here would throw away the one piece of evidence the stub exists
             // to preserve.
-            deps.writeFile(plan.reviewPath, `${antigravityDiagnostic(deps)}\n`);
+            deps.writeFile(plan.reviewPath, `${antigravityDiagnostic(deps, {
+                stderr: errContent,
+                mode: antigravityFailureMode(repoRoot, mark, deps),
+            })}\n`);
             return { slug: plan.slug, ok: true, stubbed: true, model };
         }
     }
@@ -959,7 +1085,7 @@ function runSpawnLane(plan, deps, repoRoot) {
     // folded in as a diff observation, and the citation check must not change that surface.
     if (plan.evidenceClass !== 'diff-only')
         review = stampUngroundedReview(review);
-    const { stubbed } = writeReviewOrStub(plan, review, deps, extra);
+    const { stubbed } = writeReviewOrStub(plan, review, deps, extra, out);
     return { slug: plan.slug, ok: true, stubbed, model };
 }
 async function runHttpLane(plan, deps) {