@opengsd/gsd-core 1.12.0 → 1.14.0

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) {

package/gsd-core/bin/lib/reviewer-step-dispatch.cjs

@@ -0,0 +1,337 @@
+"use strict";
+/**
+ * Reviewer Step Dispatch (#4209 Phase 1 Plan 2, ADR-2782 seam).
+ *
+ * ONE interpreter for "a step declares `supportsReviewerLanes: true`" — see
+ * `gsd-core/references/loop-hook-dispatch.md` for the canonical explanation of the trait and how
+ * `review-lane dispatch-step` re-derives it. This module trusts `trait` exactly as given: it is
+ * the CALLER's job to have derived it correctly. Every direct or lifecycle caller routes through
+ * `dispatchReviewerLanes` so selection/plan/invoke logic is owned once, not re-derived per
+ * feature. This module owns NONE of those primitives — it wires `resolveReviewerSelection`
+ * (selection) and `resolveLanePlan` (planning), the same building blocks
+ * `gsd-core/bin/gsd-tools.cjs`'s `review-lane plan` subcommand uses. Invocation (`runLane`) needs
+ * OS-aware spawn/probe plumbing this module does not own, so `deps.invoke` is the one required,
+ * caller-supplied seam (wired for real in `gsd-core/bin/gsd-tools.cjs`'s `review-lane
+ * dispatch-step` route).
+ *
+ * Fail-closed contract:
+ * - Trait not exactly `true`, or nothing selected → inert. Zero plan/invoke calls.
+ * - Missing/unsafe request-level input (paths escaping `repoRoot`, absent depth/base SHA) stops
+ *   the WHOLE dispatch before any lane is planned or invoked.
+ * - An explicitly requested lane the selector could not resolve does not silently narrow the
+ *   result to only what worked: lanes that DID resolve still run and their results are kept,
+ *   but the aggregate `ok` is `false` so no caller mistakes a partial run for a clean one.
+ * - Once a lane is planned, a per-lane plan/budget/invoke failure never displaces or cancels a
+ *   sibling lane already run.
+ * - A lane whose `promptChannel` is `'none'` (it reviews the working tree on its own terms, fed
+ *   nothing — e.g. `coderabbit`) cannot receive the bounded prompt below and is rejected before
+ *   plan/invoke, same as an unresolved slug.
+ *
+ * The bounded source-review prompt built here is METADATA ONLY — repository root, canonical
+ * file paths, review depth, base SHA, and four fixed prohibitions. It never embeds file
+ * contents. If the assembled prompt exceeds a lane's resolved budget, that lane's dispatch
+ * hard-fails before `invoke` runs for it — no silent truncation of the file list.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOURCE_REVIEW_PROHIBITIONS = exports.DISPATCH_REASON = void 0;
+exports.buildSourceReviewPrompt = buildSourceReviewPrompt;
+exports.dispatchReviewerLanes = dispatchReviewerLanes;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const prompt_budget_cjs_1 = require("./prompt-budget.cjs");
+const security_cjs_1 = require("./security.cjs");
+const review_lane_invocation_cjs_1 = require("./review-lane-invocation.cjs");
+const review_reviewer_selection_cjs_1 = require("./review-reviewer-selection.cjs");
+/** Closed set of request-level (not per-lane) halt reasons. Mirrors `LANE_UNAVAILABLE`'s shape. */
+exports.DISPATCH_REASON = Object.freeze({
+    TRAIT_NOT_ENABLED: 'trait_not_enabled',
+    NO_LANES_SELECTED: 'no_lanes_selected',
+    SELECTION_FAILED: 'selection_failed',
+    INVALID_PATHS: 'invalid_paths',
+    PATH_ESCAPES_REPO_ROOT: 'path_escapes_repo_root',
+    MISSING_PROVENANCE: 'missing_provenance',
+    INVALID_PROVENANCE: 'invalid_provenance',
+    PROMPT_WRITE_FAILED: 'prompt_write_failed',
+});
+/** Fixed, non-negotiable prompt constraints (SAFE-03..SAFE-06). Order is the display order. */
+exports.SOURCE_REVIEW_PROHIBITIONS = Object.freeze([
+    'Do not modify any source file.',
+    'Do not run tests.',
+    'Do not start background processes.',
+    'Do not poll or wait — return findings from a single read-only pass.',
+]);
+// #4209 RQ-04: a control character (newline, CR, NUL, ...) in ANY string this module embeds
+// into the external prompt (`buildSourceReviewPrompt`) lets it inject a fabricated section —
+// not just via `paths` (agy-F1's original finding), since `depth`, `baseSha`, and `repoRoot` land
+// in that same markdown. Every embedded string is checked against this ONE shared boundary.
+const CONTROL_CHAR = /[\x00-\x1f\x7f\u2028\u2029]/;
+function defaultWritePromptFile(filePath, content) {
+    node_fs_1.default.writeFileSync(filePath, content, 'utf8');
+}
+/**
+ * Validate that every path is a non-empty string resolving INSIDE `repoRoot` — blocks `..`
+ * traversal and absolute paths pointing elsewhere before any lane sees them.
+ */
+function validatePaths(repoRoot, paths) {
+    if (!Array.isArray(paths) || paths.length === 0) {
+        return { ok: false, reason: exports.DISPATCH_REASON.INVALID_PATHS };
+    }
+    const root = node_path_1.default.resolve(String(repoRoot ?? ''));
+    // repoRoot itself may be a symlink (e.g. a `/tmp`-based worktree on macOS, where `/tmp` is
+    // itself a symlink to `/private/tmp`) — realpath it once so the per-path comparison below
+    // compares like with like, not a resolved child path against an unresolved root.
+    let realRoot;
+    try {
+        realRoot = node_fs_1.default.realpathSync(root);
+    }
+    catch {
+        realRoot = root;
+    }
+    // #4209 agy-F1: a control character (newline, CR, NUL, ...) in a path lets a maliciously
+    // named repo file inject a fabricated section into the markdown prompt built from `paths`
+    // below (buildSourceReviewPrompt) — reject it here, at the shared trust boundary, rather than
+    // relying on the incidental quoting `git diff --name-only` happens to apply upstream.
+    for (const p of paths) {
+        if (typeof p !== 'string' || p.length === 0 || CONTROL_CHAR.test(p)) {
+            return { ok: false, reason: exports.DISPATCH_REASON.INVALID_PATHS };
+        }
+        // ADR-4650 decision 6: lexical family — this is the first of the two
+        // deliberate halves (#4209 WR-05); the ENOENT-tolerant realpath half
+        // below cannot be folded into a single `tryWithinRoot` call (its
+        // ancestor-walk would accept a deleted path via the nearest existing
+        // ancestor, not the explicit `continue` this code requires).
+        const resolved = node_path_1.default.resolve(root, p);
+        if ((0, security_cjs_1.tryWithinRootLexical)(p, root) === null) {
+            return { ok: false, reason: exports.DISPATCH_REASON.PATH_ESCAPES_REPO_ROOT };
+        }
+        // #4209 WR-05: `path.resolve` is lexical only — a symlink whose OWN path sits inside
+        // repoRoot can still point outside it, passing the check above while listing an
+        // out-of-repo file for the external lane to read. `fs.realpathSync` follows the link;
+        // ENOENT is expected and benign here (a `git diff --name-only` path can legitimately name
+        // a file already deleted in a stale worktree) and is not itself an escape.
+        let real;
+        try {
+            real = node_fs_1.default.realpathSync(resolved);
+        }
+        catch {
+            continue;
+        }
+        if ((0, security_cjs_1.tryWithinRootLexical)(real, realRoot) === null) {
+            return { ok: false, reason: exports.DISPATCH_REASON.PATH_ESCAPES_REPO_ROOT };
+        }
+    }
+    return { ok: true };
+}
+// `resolveLaneBudget` (review-lane-invocation.cjs) resolves the number; `null` and a resolved
+// `0` both mean unbounded (#2797) — the caller's overflow check must test both `!== null` and
+// `!== 0`. See the call site below.
+/**
+ * One-line depth definition for an external reviewer lane, condensed from `<depth_levels>` in
+ * `agents/gsd-code-reviewer.md` (#4209 review: a bare `quick`/`standard`/`deep` label means
+ * nothing to a third-party CLI that never sees that agent's system prompt — unlike the internal
+ * reviewer, whose own persona fully defines these three terms). Every category named here must
+ * stay a strict subset of what `<depth_levels>` actually does — `tests/reviewer-step-dispatch
+ * .test.cjs`'s "depthMeaning tracks depth_levels" tests assert each case against the real agent
+ * file, not just against this function, so the two cannot silently drift again. An unrecognised
+ * depth normalizes to `standard`'s text, matching `agents/gsd-code-reviewer.md`'s own "if depth
+ * is not one of quick/standard/deep, default to standard" rule — the raw label is not repeated
+ * here since `buildSourceReviewPrompt` already states it once, verbatim, earlier in the prompt.
+ */
+function depthMeaning(depth) {
+    switch (depth) {
+        case 'quick':
+            return 'pattern-scan without reading full file contents: hardcoded secrets, dangerous functions, debug artifacts, empty catch blocks, commented-out code';
+        case 'standard':
+            return 'read each changed file in context for bugs, security, and quality problems; cross-reference imports and exports';
+        case 'deep':
+            return 'standard, plus cross-file analysis: trace call chains, check type consistency at API boundaries, verify error propagation, check state mutation consistency, detect circular dependencies';
+        default:
+            return depthMeaning('standard');
+    }
+}
+/**
+ * Build the bounded source-review prompt. Metadata only — repoRoot, paths, depth, base SHA, and
+ * the four fixed prohibitions. NEVER embeds file contents.
+ */
+function buildSourceReviewPrompt(input) {
+    // Base SHA is identical for every file and already stated once above — repeating it per line
+    // (as an earlier version of this prompt did) wastes real tokens at O(files), for zero
+    // information gain, on every dispatched lane.
+    const fileLines = input.paths.map((p) => `- ${p}`).join('\n');
+    const ruleLines = exports.SOURCE_REVIEW_PROHIBITIONS.map((r, i) => `${i + 1}. ${r}`).join('\n');
+    return [
+        '## Source Review Request',
+        '',
+        `Repository root: ${input.repoRoot}`,
+        `Review depth: ${input.depth}`,
+        `Base SHA: ${input.baseSha}`,
+        '',
+        'Review the changes introduced in each file below relative to the base SHA above, at the',
+        `requested depth (${depthMeaning(input.depth)}). Report every bug, security issue, and`,
+        'code-quality problem you find. For every claim you make, cite the exact file path and line',
+        'number(s) it applies to — a claim with no file:line citation cannot be independently',
+        're-verified and will be discarded by the consolidating reviewer. Performance issues',
+        '(O(n²), memory leaks) are out of scope unless also correctness issues (e.g. an infinite',
+        'loop) — do not flag them otherwise.',
+        '',
+        '### Files in scope',
+        fileLines,
+        '',
+        '### Rules',
+        ruleLines,
+    ].join('\n');
+}
+/**
+ * Dispatch every selected reviewer lane for one opted-in step. See module docstring for scope.
+ */
+async function dispatchReviewerLanes(input, deps) {
+    if (input.trait !== true) {
+        return { dispatched: false, ok: true, reason: exports.DISPATCH_REASON.TRAIT_NOT_ENABLED, results: [] };
+    }
+    const resolveSelection = deps.resolveSelection ?? review_reviewer_selection_cjs_1.resolveReviewerSelection;
+    const selection = resolveSelection(input.selection);
+    if (selection.selected.length === 0) {
+        // Distinguish "explicitly requested but every candidate was unavailable" (a real failure —
+        // `errors` is non-empty) from "nothing was ever requested" (a clean, inert no-op).
+        const reason = selection.errors.length > 0
+            ? exports.DISPATCH_REASON.SELECTION_FAILED
+            : exports.DISPATCH_REASON.NO_LANES_SELECTED;
+        return { dispatched: false, ok: selection.errors.length === 0, reason, selection, results: [] };
+    }
+    const pathCheck = validatePaths(input.repoRoot, input.paths);
+    if (!pathCheck.ok) {
+        return { dispatched: false, ok: false, reason: pathCheck.reason, selection, results: [] };
+    }
+    // #4209 RQ-04: depth/baseSha/repoRoot/runDir land in the SAME markdown prompt `paths` does
+    // (buildSourceReviewPrompt, `dispatchReviewerLanes`'s `runDir`-derived promptPath write) — a
+    // control character in any of them is the identical injection vector agy-F1 found in `paths`,
+    // so this trust boundary must reject it here too, not just for the file list.
+    if (typeof input.depth !== 'string' || input.depth.length === 0
+        || typeof input.baseSha !== 'string' || input.baseSha.length === 0
+        || typeof input.repoRoot !== 'string' || input.repoRoot.length === 0
+        || typeof input.runDir !== 'string' || input.runDir.length === 0) {
+        return { dispatched: false, ok: false, reason: exports.DISPATCH_REASON.MISSING_PROVENANCE, selection, results: [] };
+    }
+    // #4209 WR-04: a present-but-malicious field (control character) is a different failure mode
+    // than an absent one — MISSING_PROVENANCE above means "the caller never supplied this"; this
+    // branch means "the caller supplied something and it's an injection attempt," which a caller
+    // handling the two reasons differently (e.g. surfacing one as a config problem, the other as
+    // a security event) must be able to tell apart.
+    if (CONTROL_CHAR.test(input.depth) || CONTROL_CHAR.test(input.baseSha)
+        || CONTROL_CHAR.test(input.repoRoot) || CONTROL_CHAR.test(input.runDir)) {
+        return { dispatched: false, ok: false, reason: exports.DISPATCH_REASON.INVALID_PROVENANCE, selection, results: [] };
+    }
+    // #4209 WR-03 (considered, declined): gating `depth` to code-review's quick/standard/deep
+    // enum here would reject the deliberately capability-neutral case this function supports —
+    // see "a second, unrelated synthetic step context dispatches through the same function
+    // identically" below, which passes a wholly different depth vocabulary on purpose to prove
+    // this dispatcher has no code-review-specific special-casing. `depthMeaning()`'s `standard`
+    // fallback for an off-enum value is accepted, not a bug, for that reason.
+    const { configGet, getLane, plan } = deps;
+    const writePromptFile = deps.writePromptFile ?? defaultWritePromptFile;
+    const prompt = buildSourceReviewPrompt(input);
+    const estimatedTokens = (0, prompt_budget_cjs_1.estimateTokens)(prompt);
+    // Written once, before any lane's plan() runs: `promptPath` is derived from `runDir` alone
+    // (see `artifactPaths`), constant across every lane in this dispatch by construction — there
+    // is no per-lane variance to defend against, so writing it per-lane (as an earlier version of
+    // this function did) was pure redundancy, not a real safeguard.
+    // A hoisted, whole-dispatch write (see the doc comment above) that throws must not escape as
+    // an uncaught exception — no lane can succeed anyway if the shared prompt file was never
+    // written, so this is a dispatch-level halt like `validatePaths`/`MISSING_PROVENANCE` above,
+    // not a per-lane failure.
+    try {
+        writePromptFile((0, review_lane_invocation_cjs_1.artifactPaths)(input.runDir, '').promptPath, prompt);
+    }
+    catch {
+        return { dispatched: false, ok: false, reason: exports.DISPATCH_REASON.PROMPT_WRITE_FAILED, selection, results: [] };
+    }
+    const results = [];
+    // Never narrow the requested set: an explicit reviewer the selector could not resolve is
+    // already surfaced in `selection.errors` — reflect that in the aggregate `ok` even though
+    // lanes that DID resolve still run below and keep their own results.
+    let anyFailed = selection.errors.length > 0;
+    // Tracks whether any lane actually reached plan() — `dispatched` must stay false when every
+    // selected slug turned out to be unresolvable, even though a `results` entry was still pushed.
+    let planned = false;
+    for (const slug of selection.selected) {
+        const lane = getLane(slug);
+        if (!lane) {
+            results.push({ slug, ok: false, reason: 'malformed_lane', detail: 'no such declared lane' });
+            anyFailed = true;
+            continue;
+        }
+        // #4209 review: a `promptChannel: 'none'` lane (coderabbit) is fed nothing and reviews
+        // whatever it independently sees fit (its own working-tree diff, review.md:367) rather than
+        // the bounded `paths`/`depth`/`baseSha` scope `buildSourceReviewPrompt` promises — silently
+        // dispatching it here would violate this interpreter's own scoped, metadata-only review
+        // contract. Reject before plan()/invoke() rather than let the mismatch surface as an
+        // unexplained out-of-scope review.
+        if (lane.transport === 'spawn' && lane.invoke.promptChannel === 'none') {
+            results.push({
+                slug,
+                ok: false,
+                reason: 'prompt_channel_unsupported',
+                detail: `lane '${slug}' declares promptChannel 'none' and cannot receive a scoped source-review prompt`,
+            });
+            anyFailed = true;
+            continue;
+        }
+        // A single throwing plan()/invoke() must not take down every sibling lane already collected
+        // in `results` — same rationale as gsd-tools.cjs's resolveLanePlan guard
+        // (#2494/#2605/#1698/#1936/#2073/#2176/#2589/#2794): belt and braces on purpose.
+        let planOutcome;
+        try {
+            planOutcome = plan(lane, { configGet, runDir: input.runDir, repoRoot: input.repoRoot });
+        }
+        catch (e) {
+            results.push({ slug, ok: false, reason: 'malformed_lane', detail: e instanceof Error ? e.message : String(e) });
+            anyFailed = true;
+            continue;
+        }
+        if (!planOutcome.ok) {
+            results.push({ slug, ok: false, reason: planOutcome.reason, detail: planOutcome.detail });
+            anyFailed = true;
+            continue;
+        }
+        const budget = (0, review_lane_invocation_cjs_1.resolveLaneBudget)(lane, configGet);
+        if (budget !== null && budget !== 0 && estimatedTokens > budget) {
+            results.push({
+                slug,
+                ok: false,
+                reason: 'budget_exceeded',
+                detail: `estimated ${estimatedTokens} tokens exceeds resolved budget ${budget} for lane '${slug}'`,
+            });
+            anyFailed = true;
+            continue;
+        }
+        planned = true;
+        let invokeOutcome;
+        try {
+            invokeOutcome = await deps.invoke(lane, planOutcome.plan);
+        }
+        catch (e) {
+            results.push({ slug, ok: false, reason: 'invoke_failed', detail: e instanceof Error ? e.message : String(e) });
+            anyFailed = true;
+            continue;
+        }
+        if (!invokeOutcome.ok)
+            anyFailed = true;
+        results.push({
+            slug,
+            ok: invokeOutcome.ok,
+            reason: invokeOutcome.reason,
+            detail: invokeOutcome.detail,
+            reviewPath: invokeOutcome.reviewPath,
+            errPath: invokeOutcome.errPath,
+        });
+    }
+    return {
+        dispatched: planned,
+        ok: !anyFailed,
+        selection,
+        results,
+    };
+}