@expo/code-review-cli 0.6.0 → 0.8.0

package/build/core/schema.js

@@ -1,3 +1,4 @@
+// @ref LLP 0005#finding-identity-fingerprints
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { normalizeCode } from "./util.js";
@@ -21,7 +22,45 @@ export const FindingSchema = z.object({
      * the finding is treated as hallucinated and dropped.
      */
     evidence: z.string().optional(),
+    /**
+     * Set by the coordinator (and then ground-checked, see groundStackRequalification)
+     * when a later, stacked-on-top PR already addresses this absence-style finding:
+     * `prNumber` + the EXACT upstack manifest `file` relied on + a one-line `reason`.
+     * A requalified finding is never dropped — it renders in its own section, is
+     * counted, and is only excluded from the blocking decision. Never part of the
+     * fingerprint, so dismissal identity is stable across re-reviews.
+     */
+    // @ref LLP 0010#requalification-schema-and-fingerprints [constrained-by] — annotate-only; excluded from fingerprintFinding so dismissal identity never lapses on requalification
+    requalifiedBy: z
+        .object({ prNumber: z.number().int(), file: z.string(), reason: z.string() })
+        .optional(),
+    /**
+     * Which reviewer agent produced this finding. Engine-populated, never the model:
+     * `ModelFindingSchema` omits it, so an `agent` in model JSON is dropped at the parse
+     * boundary and only the engine's fingerprint lookup can set it. Excluded from the
+     * fingerprint like `requalifiedBy`, so attribution appearing on a finding can never
+     * lapse an existing dismissal.
+     */
+    // @ref LLP 0011#attribution-and-identity [constrained-by] — attribution is annotation-only; never part of fingerprintFinding
+    agent: z.string().optional(),
 });
+/**
+ * Title of the internal "overall PR risk" handoff finding. The cross-cutting
+ * reviewer (or the always-run security reviewer on a PR small enough to skip the
+ * cross-cutting pass) rides the ordinary finding channel to hand the coordinator
+ * a whole-PR risk assessment — see the "Overall PR risk handoff" section in
+ * `templates/shared.md`. It is prompt-level metadata, never a defect.
+ */
+// @ref LLP 0009#prompt-rules-for-adopters [implements] — the deterministic strip that makes the handoff independent of policy.includeSuggestions
+export const OVERALL_PR_RISK_TITLE = "__overall_pr_risk__";
+/**
+ * Is this the internal risk handoff rather than a real finding? Matched on the
+ * exact title the prompt specifies. Reported findings must never include it: it
+ * would surface to PR authors as a nonsense bullet, and it is not a defect.
+ */
+export function isOverallRiskHandoff(finding) {
+    return finding.title.trim() === OVERALL_PR_RISK_TITLE;
+}
 /** A verifier's verdict on whether a finding is real (adversarial refute pass). */
 export const VerdictSchema = z.object({
     verified: z.boolean(),
@@ -30,14 +69,36 @@ export const VerdictSchema = z.object({
 export function parseVerdict(text) {
     return VerdictSchema.parse(extractJsonObject(text));
 }
+/**
+ * A stack verifier's verdict on whether a later stacked PR's patch actually
+ * addresses an absence-style finding (v2 patch confirmation). Fails toward
+ * blocking: anything but a clear `addressed: true` strips the requalification.
+ */
+// @ref LLP 0010#patch-level-confirmation-v2 [constrained-by] — addressed !== true keeps the finding blocking
+export const StackVerdictSchema = z.object({
+    addressed: z.boolean(),
+    reason: z.string().default(""),
+});
+export function parseStackVerdict(text) {
+    return StackVerdictSchema.parse(extractJsonObject(text));
+}
+// @ref LLP 0011#attribution-and-identity [implements] — `agent` is engine-populated, so the model-facing schema drops it at the parse boundary instead of trusting call sites to strip it
+/**
+ * The finding shape a MODEL may emit: `FindingSchema` minus the engine-only `agent`.
+ * Both model outputs parse through this, so an `agent` a reviewer pass or the
+ * coordinator invented is dropped where model JSON becomes typed data — the engine's own
+ * fingerprint lookup is then the only thing that can set it. The transform re-widens the
+ * result to `Finding` so downstream code (which does set `agent`) needs no change.
+ */
+const ModelFindingSchema = FindingSchema.omit({ agent: true }).transform((finding) => finding);
 /** Shape each sub-reviewer must emit. */
 export const ReviewerOutputSchema = z.object({
-    findings: z.array(FindingSchema).default([]),
+    findings: z.array(ModelFindingSchema).default([]),
 });
 /** Mode-agnostic coordinator result; each Reporter decides how to render it. */
 export const CoordinatorOutputSchema = z.object({
     decision: z.enum(DECISIONS),
-    findings: z.array(FindingSchema).default([]),
+    findings: z.array(ModelFindingSchema).default([]),
     summary: z.string(),
     /**
      * Human-readable notes about reduced coverage (e.g. a review pass that hit its
@@ -55,9 +116,158 @@ export const CoordinatorOutputSchema = z.object({
      */
     couldNotComplete: z.boolean().optional(),
 });
+/** How an author's reply to a finding held up against the source. */
+export const FEEDBACK_VERDICTS = ["accepted", "refuted", "unclear"];
+/** The kinds of pushback authors actually write, as a closed set. */
+export const FEEDBACK_REASONS = [
+    "pre-existing", // the PR only continues a pattern already in the repo
+    "deliberate-scope", // a bounded, intentional limitation of new code
+    "fixed", // the author says they addressed it
+    "disagree", // the author disputes the analysis itself
+    "other",
+];
+// @ref LLP 0011#never-echo-reply-text [constrained-by] — no free-text field: reply prose never reaches the comment body, so it can never carry a forged state marker
+/**
+ * One author reply matched to one finding, keyed by fingerprint. Everything here
+ * is either engine-derived or enum-valued — deliberately NO free-text field. The
+ * reply's own prose is never stored and never rendered; adding a field for it
+ * would put attacker-written text back into the comment body.
+ */
+export const FeedbackRecordSchema = z.object({
+    fp: z.string(),
+    by: z.string(),
+    commentId: z.number().int(),
+    url: z.string().optional(),
+    maintainer: z.boolean().default(false),
+    /**
+     * True when the replying login is the PR author. Re-derived from the live comment
+     * every run (never trusted from stored state), so it is unspoofable like `maintainer`.
+     * Only a maintainer OR the PR author may clear a finding via a reply — an untrusted
+     * third-party commenter is annotated but can never be counted as an adjudicatable
+     * rebuttal (feedbackApplied gates the adjudicated path on this).
+     */
+    // @ref LLP 0011#hard-floors-in-code [constrained-by] — the adjudicated clear path is for the PR author only; a third-party commenter's rebuttal never clears
+    author: z.boolean().optional(),
+    /**
+     * True when the reply cites this finding's `id:<fp>` token in the replier's OWN words
+     * (outside every blockquote). Re-derived from the live comment every run by
+     * `matchReplies`, never trusted from stored state, exactly like `maintainer`/`author`.
+     * A quote-only match still ANNOTATES the finding; only a cited id may CLEAR it, on
+     * both clear paths. Absent ⇒ false ⇒ clears nothing, so a record written before this
+     * field parses fine and fails closed until its reply is matched again.
+     */
+    // @ref LLP 0011#a-quote-annotates-an-id-clears [constrained-by] — a quoted line can be text the untrusted PR author planted for a maintainer to quote-reply, so a quote may annotate but never clear
+    citedId: z.boolean().optional(),
+    verdict: z.enum(FEEDBACK_VERDICTS).optional(),
+    reason: z.enum(FEEDBACK_REASONS).optional(),
+    /**
+     * The reviewed head commit the verdict above was judged against (the PR head OID of
+     * the run whose adjudicator answered). A verdict is a statement about SOURCE, and a
+     * fingerprint deliberately excludes the line number, so a finding keeps its identity
+     * while the code that justified the rebuttal is edited away. Binding the verdict to
+     * the revision it judged is what lets mergeFeedback drop it once the head moves.
+     * Absent ⇒ unknown source (a record from before this field, or a run with no
+     * resolvable head OID): the verdict never carries, so a missing SHA can never pin a
+     * decision forever.
+     */
+    // @ref LLP 0011#suppression-is-never-silent [constrained-by] — a carried verdict must be re-judged when the source it judged changes; unknown source fails safe to re-judging
+    sourceSha: z.string().optional(),
+    /** True when this reply actually removed the finding from the blocking set. */
+    applied: z.boolean().default(false),
+    /**
+     * Set when a human ran `/undismiss <id>` on a finding a reply had cleared: the
+     * finding returns to the active list and no live reply may re-apply it, so a later
+     * re-review recomputing `applied` from the still-present reply keeps it un-cleared.
+     *
+     * DERIVED, never the storage: the pin itself lives in the comment state's own `pins`
+     * set (see FeedbackPinSchema), which survives a run where no reply matches the
+     * finding at all. This flag is stamped back onto the record by `applyPins` on every
+     * render so `feedbackApplied` stays a pure record-local decision — and so a comment
+     * written by this version is still read correctly by an older one.
+     */
+    // @ref LLP 0011#suppression-is-never-silent [constrained-by] — /undismiss must actually restore a reply-cleared finding, and the untrusted PR author must not be able to lift that restore by removing or replacing their reply
+    unclearedByHuman: z.boolean().optional(),
+});
+// @ref LLP 0011#the-pin-belongs-to-the-finding [implements] — the pin is state about a FINDING, stored outside the reply record so a vanishing reply can never drop it
+/**
+ * One maintainer `/undismiss` pin: the finding they restored, plus the reply comment
+ * the pin was applied against (absent when the finding had no reply record). The
+ * comment id is what makes "a maintainer's own NEWER reply lifts the pin" decidable
+ * without the pin having to live on a reply record: only a maintainer reply posted
+ * AFTER the pin (a strictly greater comment id — GitHub issue comment ids increase)
+ * releases it.
+ */
+export const FeedbackPinSchema = z.object({
+    fp: z.string(),
+    commentId: z.number().int().optional(),
+});
+/**
+ * The pin set to work with: the state's own `pins` plus any record-level
+ * `unclearedByHuman` flag. The second half is the migration for a comment written
+ * before `pins` existed — its pins live only on the records, and dropping them would
+ * silently lift a maintainer's restore on the first render by this version. Idempotent.
+ */
+export function collectPins(pins, records) {
+    const byFp = new Map();
+    for (const pin of pins ?? []) {
+        byFp.set(pin.fp, pin);
+    }
+    for (const record of records) {
+        if (record.unclearedByHuman === true && !byFp.has(record.fp)) {
+            byFp.set(record.fp, { fp: record.fp, commentId: record.commentId });
+        }
+    }
+    return [...byFp.values()];
+}
+// @ref LLP 0011#the-pin-belongs-to-the-finding [implements] — the pin set is the single source of truth; the record flag is stamped from it, never the other way round
+/**
+ * Carry the pin set across one render and stamp the records it covers. A pinned
+ * record can never be `applied` (the finding stays in the active list), and a record
+ * the set does NOT pin loses any stale flag — the set decides, so a flag left on a
+ * record could never resurrect a lifted pin.
+ *
+ * The only lift here is a maintainer's own newer reply: a reply record for the pinned
+ * finding, from a maintainer, posted after the pin. Everything else (a newer reply from
+ * the untrusted PR author, an edited or deleted reply, a re-review that matched no
+ * reply at all) leaves the pin exactly where it is. The other lift — a maintainer's
+ * `/dismiss` on that finding — happens in applyDismissalToState, the same trusted hand
+ * deciding the opposite way.
+ */
+export function applyPins(records, pins) {
+    const kept = pins.filter((pin) => 
+    // A pin with no recorded commentId is never lifted by a reply: "unknown" must not
+    // read as "older than every comment", which would let any maintainer reply lift it.
+    pin.commentId === undefined ||
+        !records.some((record) => record.fp === pin.fp && record.maintainer === true && record.commentId > pin.commentId));
+    const pinnedFps = new Set(kept.map((pin) => pin.fp));
+    const stamped = records.map((record) => {
+        if (pinnedFps.has(record.fp)) {
+            return { ...record, unclearedByHuman: true, applied: false };
+        }
+        if (record.unclearedByHuman === undefined) {
+            return record;
+        }
+        const { unclearedByHuman: _lifted, ...rest } = record;
+        return rest;
+    });
+    return { records: stamped, pins: kept };
+}
+/**
+ * The adjudicator's verdict on one rebuttal, re-derived from the source. Both
+ * fields are enum-constrained: the judgment is a classification, never prose the
+ * model could smuggle instructions (or a state marker) through.
+ */
+export const AdjudicationSchema = z.object({
+    verdict: z.enum(FEEDBACK_VERDICTS),
+    reason: z.enum(FEEDBACK_REASONS).default("other"),
+});
+export function parseAdjudication(text) {
+    return AdjudicationSchema.parse(extractJsonObject(text));
+}
 /** Minimum normalized evidence length to key a fingerprint on the code (below
  * this we fall back to the title). */
 const MIN_FP_EVIDENCE_LEN = 12;
+// @ref LLP 0005#finding-identity-fingerprints [implements] — keys on evidence (v2) not the LLM-written title; excludes line number
 /**
  * Stable identifier for a finding — dedupes across re-reviews and is the key for
  * dismissals. Excludes the line number (which shifts as a PR grows). Keys on the
@@ -73,6 +283,7 @@ export function fingerprintFinding(finding) {
     const normalized = ["v2", finding.file, finding.category, key].join("|");
     return createHash("sha1").update(normalized).digest("hex").slice(0, 12);
 }
+// @ref LLP 0005#finding-identity-fingerprints [implements] — default scope passes null so pre-routing dismissals still resolve (risk 9)
 /**
  * Namespace a finding's fingerprint by scope so cross-scope dismissals never
  * collide. The DEFAULT scope (config '.') passes `null` and keeps the plain
@@ -112,7 +323,12 @@ export function extractJsonObject(text) {
             lastError = error;
         }
     }
-    throw new Error(`Could not extract JSON from model response: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+    throw new Error(lastError === undefined
+        ? // No candidate was even tried: the response held no {...} block at all —
+            // empty output, or prose/pseudo-tool-call text with no JSON in it.
+            `Could not extract JSON from model response: no JSON object found in ` +
+                `${text.trim() === "" ? "an EMPTY response" : `a ${text.length}-char response with no {...}`}`
+        : `Could not extract JSON from model response: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
 }
 /** The router's choice of which agent ids to run. */
 export const RouteOutputSchema = z.object({

package/build/core/scrub.js

@@ -1,4 +1,5 @@
-import { readdir, rm } from "node:fs/promises";
+// @ref LLP 0001#read-root-scrubbing [implements] — strips ambient config + escaping symlinks before the model runtime roots here
+import { readdir, realpath, rm } from "node:fs/promises";
 import path from "node:path";
 /**
  * Ambient runtime configuration the OpenCode server (and the Claude-compatible
@@ -29,6 +30,7 @@ export const AMBIENT_RUNTIME_CONFIG_NAMES = new Set([
     ".cursor",
     ".cursorrules",
 ]);
+// @ref LLP 0001#read-root-scrubbing [constrained-by] — .git skipped here for a different reason than node_modules is skipped below
 /** Names never descended into (and never scrubbed as a unit — `.git` is the worktree link). */
 const SKIP_DIRS = new Set([".git", "node_modules"]);
 /** Whether a directory entry is ambient runtime config that must not reach the model runtime. */
@@ -41,6 +43,7 @@ export function isAmbientRuntimeConfig(name) {
  * extracted archive) — never on the user's checkout. Returns the repo-relative
  * paths removed so callers can log them.
  */
+// @ref LLP 0001#read-root-scrubbing [implements] — closes the fork-reachable code-execution path (601b19a)
 export async function scrubAmbientRuntimeConfig(root) {
     const removed = [];
     const walk = async (dir) => {
@@ -60,3 +63,62 @@ export async function scrubAmbientRuntimeConfig(root) {
     await walk(root);
     return removed.sort();
 }
+/**
+ * Remove symlinks whose fully resolved target lies outside the materialized tree.
+ *
+ * The model runtime's read tools are path-scoped by the LITERAL path argument
+ * (buildClaudeArgs' permission rules, and equally OpenCode's project-root
+ * containment), but the fs layer underneath follows symlinks — so a PR-committed
+ * link (`docs/notes.md -> ~/.claude/.credentials.json`) passes the in-tree check
+ * and reads the out-of-tree target. Git can only materialize regular files,
+ * directories, and symlinks, so stripping escaping symlinks here closes the whole
+ * class.
+ *
+ * Fail closed: a link whose target cannot be resolved (broken, or a chain that
+ * leaves the tree at any hop) is removed too — the target could come into
+ * existence later, and a broken link has no legitimate review value. In-tree
+ * links survive (realpath resolves chains, so an in-tree alias of an in-tree
+ * file is provably contained). Unlike the config scrub, this walk descends into
+ * node_modules (a committed one is attacker content); `.git` stays skipped — in
+ * a worktree it is an ECR-created gitdir link, not PR content.
+ *
+ * Must only ever run on a tree ECR created and will delete. Returns the
+ * repo-relative paths removed so callers can log them.
+ */
+// @ref LLP 0001#read-root-scrubbing [implements] — out-of-tree/broken/cyclic symlinks removed fail-closed
+export async function removeEscapingSymlinks(root) {
+    // realpath the boundary itself: tmpdir-based roots are often behind symlinks
+    // (macOS /var -> /private/var), and containment must compare resolved paths.
+    const boundary = await realpath(root);
+    const removed = [];
+    const walk = async (dir) => {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isSymbolicLink()) {
+                let contained = false;
+                try {
+                    const target = await realpath(full);
+                    contained = target === boundary || target.startsWith(boundary + path.sep);
+                }
+                catch {
+                    // Unresolvable link: leave `contained` false (fail closed).
+                }
+                if (!contained) {
+                    await rm(full, { force: true });
+                    // Relative to the RESOLVED boundary — the walk runs there, and the
+                    // caller's `root` may itself sit behind a symlink (macOS /var).
+                    removed.push(path.relative(boundary, full));
+                }
+                // In-tree directory links are kept but never descended: their contents
+                // are walked once via the real path, and descending would loop on cycles.
+                continue;
+            }
+            if (entry.isDirectory() && entry.name !== ".git") {
+                await walk(full);
+            }
+        }
+    };
+    await walk(boundary);
+    return removed.sort();
+}

package/build/core/stack-confirm.js

@@ -0,0 +1,137 @@
+// @ref LLP 0010#patch-level-confirmation-v2 [implements] — path membership is not semantic proof; read the addressing patch, fail toward keeping the finding blocking
+import { addTokenUsage, promptAndParse, STACK_VERIFIER_AGENT } from "./opencode.js";
+import { buildStackVerifierSystem, buildStackVerifierTask } from "./prompts.js";
+import { fingerprintFinding, parseStackVerdict } from "./schema.js";
+import { manifestKey } from "./stack.js";
+import { errorMessage } from "./util.js";
+// Confirmation runs after coordination (a serial tail step), in parallel over unique
+// candidates. A confirmation that runs long is stripped (fail toward blocking), so this
+// timeout is a hard "give up and keep the finding" bound, not a retry trigger.
+const STACK_CONFIRM_TIMEOUT_MS = 3 * 60 * 1000;
+// @ref LLP 0010#patch-level-confirmation-v2 [constrained-by] — one verdict PER FINDING (only the patch fetch is shared); overflow past maxConfirmations is STRIPPED, not skipped; addressed!==true / error / timeout all STRIP
+/**
+ * Confirm every surviving requalification against the addressing PR's real patch and
+ * strip any that is not clearly addressed. Pure orchestration over an injected
+ * `confirmOne` so the per-finding / overflow / fail-open logic is unit-testable
+ * without gh or a live model:
+ *  - every requalified finding gets its OWN verdict — the verdict question is
+ *    finding-specific ("does this patch supply what THIS finding says is missing"),
+ *    so a shared verdict would let one confirmed finding clear an unrelated one
+ *    citing the same `(prNumber, file)`. Only the patch FETCH is shared (memoized in
+ *    `patchConfirmer`); identical findings (same fingerprint + citation) collapse;
+ *  - only the first `maxConfirmations` candidates are confirmed — any beyond that
+ *    cap have their requalification STRIPPED (fail toward blocking), never silently
+ *    kept;
+ *  - a candidate is kept ONLY on `addressed === true`; `false`, any thrown error, or a
+ *    timeout strips it.
+ * A stripped requalification leaves the finding fully intact and blocking.
+ */
+export async function confirmStackRequalifications(findings, maxConfirmations, confirmOne, debug = () => { }) {
+    // One candidate per requalified finding, in first-seen order. The key pairs the
+    // citation with the finding's fingerprint so only true duplicates share a verdict.
+    const candidateKey = (finding, prNumber, file) => `${manifestKey(prNumber, file)}|${fingerprintFinding(finding)}`;
+    const candidates = new Map();
+    for (const finding of findings) {
+        const requalified = finding.requalifiedBy;
+        if (!requalified) {
+            continue;
+        }
+        const key = candidateKey(finding, requalified.prNumber, requalified.file);
+        if (!candidates.has(key)) {
+            candidates.set(key, { prNumber: requalified.prNumber, file: requalified.file, finding });
+        }
+    }
+    const keys = [...candidates.keys()];
+    const withinCap = new Set(keys.slice(0, maxConfirmations));
+    const overflow = keys.slice(maxConfirmations);
+    // Per-candidate strip reason, for the run-log audit trail the caller persists.
+    const stripReasons = new Map();
+    for (const key of overflow) {
+        stripReasons.set(key, `over maxConfirmations=${maxConfirmations} — stripped unconfirmed`);
+    }
+    if (overflow.length > 0) {
+        debug(`Stack: ${overflow.length} requalification(s) over maxConfirmations=${maxConfirmations} — stripped unconfirmed.`);
+    }
+    // Confirm the within-cap candidates in parallel; each call is independently guarded.
+    const addressed = new Set();
+    let cost = 0;
+    let model;
+    const tokens = {};
+    await Promise.all([...withinCap].map(async (key) => {
+        const candidate = candidates.get(key);
+        try {
+            const result = await confirmOne(candidate);
+            cost += result.cost;
+            addTokenUsage(tokens, result.tokens);
+            model = result.model ?? model;
+            if (result.addressed) {
+                addressed.add(key);
+            }
+            else {
+                stripReasons.set(key, "patch does not address it");
+                debug(`Stack: stripped requalification on "${candidate.finding.file}" (patch does not address it).`);
+            }
+        }
+        catch (error) {
+            // Fail toward blocking: a fetch/verify error keeps the finding blocking.
+            stripReasons.set(key, `confirmation failed: ${errorMessage(error)}`);
+            debug(`Stack: stripped requalification on "${candidate.finding.file}" (confirmation failed: ${errorMessage(error)}).`);
+        }
+    }));
+    let stripped = 0;
+    const strippedFindings = [];
+    const out = findings.map((finding) => {
+        const requalified = finding.requalifiedBy;
+        if (!requalified) {
+            return finding;
+        }
+        const key = candidateKey(finding, requalified.prNumber, requalified.file);
+        if (addressed.has(key)) {
+            return finding;
+        }
+        stripped++;
+        const { requalifiedBy: _dropped, ...rest } = finding;
+        strippedFindings.push({ finding: rest, reason: stripReasons.get(key) ?? "not confirmed" });
+        return rest;
+    });
+    return { findings: out, stripped, strippedFindings, cost, tokens, model };
+}
+// @ref LLP 0010#patch-level-confirmation-v2 [implements] — real confirmer: fetch just the cited file's patch (fail-open null → strip), inline it into the no-tools stack verifier
+/**
+ * Build the real per-candidate confirmer: fetch just the cited file's patch from the
+ * addressing PR (the source fails open to `null` → treated as "not addressed"), inline
+ * it into the no-tools stack verifier, and require `addressed: true`. The patch is
+ * inlined, never materialized — there is no disk read and no tool use at all.
+ */
+export function patchConfirmer(handle, source) {
+    // Per-run patch memo: distinct findings citing the same (prNumber, file) each get
+    // their own verdict but share one gh fetch. The source fails open to null (never
+    // rejects), so memoizing the promise is safe.
+    const patches = new Map();
+    return async ({ prNumber, file, finding }) => {
+        const patchKey = manifestKey(prNumber, file);
+        let patchPromise = patches.get(patchKey);
+        if (!patchPromise) {
+            patchPromise = source.getStackFilePatchAsync
+                ? source.getStackFilePatchAsync(prNumber, file)
+                : Promise.resolve(null);
+            patches.set(patchKey, patchPromise);
+        }
+        const patch = await patchPromise;
+        if (patch == null) {
+            // No patch for the cited file (or the source can't fetch it): not confirmable.
+            return { addressed: false, cost: 0, tokens: {} };
+        }
+        const { value, cost, tokens, model } = await promptAndParse(handle, {
+            agent: STACK_VERIFIER_AGENT,
+            system: buildStackVerifierSystem(),
+            text: buildStackVerifierTask(finding, prNumber, patch),
+            title: `stack-verify-${prNumber}`,
+            maxWaitMs: STACK_CONFIRM_TIMEOUT_MS,
+            // A timeout here throws AgentTimeoutError, which the caller catches and STRIPS
+            // (fail toward blocking) — so no finalize salvage, unlike the main verifier.
+            finalizeOnTimeout: false,
+        }, parseStackVerdict);
+        return { addressed: value.addressed === true, cost, tokens, model };
+    };
+}

package/build/core/stack.js

@@ -0,0 +1,25 @@
+/**
+ * Repo-root-relative normalization for exact manifest membership: strip a leading
+ * `./` or `/`, trim. No substrings, no basenames — the unsound-matching critique
+ * (`a.ts` must not match `data.ts`). Grounding and confirmation both key on this.
+ */
+export function normalizeManifestPath(file) {
+    return file
+        .trim()
+        .replace(/^\.\/+/, "")
+        .replace(/^\/+/, "");
+}
+/** Membership/dedupe key for a cited `(prNumber, file)`. */
+export function manifestKey(prNumber, file) {
+    return `${prNumber} ${normalizeManifestPath(file)}`;
+}
+/** The set of every `(prNumber, file)` the manifest actually lists. */
+export function buildManifestMembership(manifest) {
+    const members = new Set();
+    for (const pr of manifest.upstackPRs) {
+        for (const file of pr.files) {
+            members.add(manifestKey(pr.number, file));
+        }
+    }
+    return members;
+}

package/build/core/step-summary.js

@@ -1,3 +1,4 @@
+// @ref LLP 0002#run-log-and-observability-sinks [implements] — swallows append errors; observability must never break a review
 import { appendFile } from "node:fs/promises";
 /**
  * Append a markdown section to the GitHub Actions step summary, so a run's

package/build/core/suppress.js

@@ -1,6 +1,8 @@
+// @ref LLP 0005#inline-suppression-backstop — deterministic backstop for expo-code-review-ignore; used to be prompt-only
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 const DIRECTIVE = "expo-code-review-ignore";
+// @ref LLP 0005#inline-suppression-backstop [constrained-by] — critical/secrets findings are never suppressed this way
 /**
  * Deterministic backstop for the inline `expo-code-review-ignore` directive (which
  * was previously prompt-only, i.e. honored only if the model chose to). Drops a

package/build/core/throttle.js

@@ -1,3 +1,4 @@
+// @ref LLP 0003#retry-taxonomy [implements] — rate-limit evidence: explicit 429 log lines are hard signal; stall + recent evidence means wait, not retry
 import { open } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -46,6 +47,7 @@ const EVIDENCE_WINDOW_MS = 5 * 60 * 1000;
  * is the signal the stall path consults. Fails soft everywhere: a missing or
  * unreadable log yields "no evidence", never an error.
  */
+// @ref LLP 0003#retry-taxonomy [implements] — fails soft (missing/unreadable log = no evidence, never an error); scans only ERROR lines so a chatty INFO "retry" mention doesn't count
 export class RateLimitWatch {
     file;
     /** Total rate-limit ERROR lines seen this run. */
@@ -56,6 +58,16 @@ export class RateLimitWatch {
     constructor(file = opencodeLogFile()) {
         this.file = file;
     }
+    /**
+     * Record rate-limit evidence directly, for an engine that has no log file to
+     * scan (the Claude Code CLI surfaces limits per-invocation, not in a log the
+     * way the OpenCode server does). Feeds the same `events`/`recentlyLimited`
+     * signals `check()` would.
+     */
+    note(count = 1) {
+        this.events += count;
+        this.lastSeenAt = Date.now();
+    }
     /** Scan newly-appended log lines for rate-limit evidence. */
     async check() {
         try {

package/build/core/util.js

@@ -5,6 +5,24 @@ export function sleep(ms) {
 export function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * A failure reason safe to post into a PUBLIC PR comment (see `ecr ci`'s failure
+ * notices). `run` (core/exec.ts) throws "Command failed: <cmd> <argv>\n<stderr>" (and
+ * "Command output exceeded …"), which embeds a subprocess's full command line, its
+ * stderr, and absolute runner paths — CI-internal detail of no use to a PR author and
+ * exactly the kind of thing that must not leak into an attacker-visible artifact. Those
+ * shapes collapse to a generic pointer at the workflow log; our own (argv/path-free)
+ * error messages pass through, since they are the actionable ones the fail-fast design
+ * means to surface. Every call site still writes the FULL reason to the job's stderr.
+ */
+// @ref LLP 0002#run-log-and-observability-sinks [implements] — subprocess argv/stderr must never leak into PR-facing comments
+export function publicFailureReason(error) {
+    const message = errorMessage(error);
+    if (/^Command (failed|output exceeded)\b/.test(message)) {
+        return "a subprocess (gh, git, or the model CLI) failed — see the workflow logs for details";
+    }
+    return message;
+}
 /** Collapse whitespace + lowercase — for tolerant code matching / fingerprinting. */
 export function normalizeCode(text) {
     return text.replace(/\s+/g, " ").trim().toLowerCase();

package/build/core/verify.js

@@ -1,5 +1,8 @@
+// @ref LLP 0005#evidence-grounding-escalate-never-hard-drop
+// @ref LLP 0005#verifier-confinement-and-fail-open
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { pathInside } from "./exec.js";
 import { parseVerdict } from "./schema.js";
 import { addTokenUsage, promptAndParse, VERIFIER_AGENT } from "./opencode.js";
 import { buildVerifierSystem, buildVerifierTask } from "./prompts.js";
@@ -9,6 +12,7 @@ import { errorMessage, normalizeCode } from "./util.js";
 const VERIFY_TIMEOUT_MS = 3 * 60 * 1000;
 // Evidence shorter than this (normalized) is too weak to conclude "hallucinated".
 const MIN_EVIDENCE_LEN = 12;
+// @ref LLP 0005#evidence-grounding-escalate-never-hard-drop [implements] — exact-substring is a good positive but poor negative signal (33a970a revert)
 /**
  * Break `evidence` into normalized, substantive fragments for fuzzy matching:
  * split on newlines AND ellipses (the model often elides with `…`/`...`), strip
@@ -48,17 +52,30 @@ export function matchEvidence(evidence, content) {
     }
     return fragments.some((fragment) => normContent.includes(fragment)) ? "present" : "absent";
 }
+// @ref LLP 0005#verifier-confinement-and-fail-open [implements] — pathInside gate: out-of-tree reads (and their present/absent verdict) refused
 /** Read the cited file and grade the evidence against it (see matchEvidence). */
 async function evidencePresence(finding, cwd) {
+    // finding.file is an unconstrained, LLM-authored string produced over untrusted PR
+    // content, so a prompt-injected finding could point it at a host secret. path.resolve
+    // IGNORES cwd when finding.file is already absolute (e.g. ~/.claude/.credentials.json),
+    // and `..` segments escape upward — either would make this raw readFile reach outside
+    // the reviewed tree with the host user's privileges, and the present/absent grading
+    // would leak a content-oracle back into the review. Confine the read to cwd (the
+    // materialized PR-head tree); anything outside is uncheckable, never read.
+    const resolved = path.resolve(cwd, finding.file);
+    if (!pathInside(resolved, cwd)) {
+        return "unknown";
+    }
     let content;
     try {
-        content = await readFile(path.resolve(cwd, finding.file), "utf8");
+        content = await readFile(resolved, "utf8");
     }
     catch {
         return "unknown";
     }
     return matchEvidence(finding.evidence ?? "", content);
 }
+// @ref LLP 0005#verifier-confinement-and-fail-open [constrained-by] — fails open: a verify error/timeout keeps the finding, never drops it
 /**
  * Guard against hallucinated findings before they're surfaced, WITHOUT silently
  * dropping real ones on an imperfect quote: