argus-reviewer-e2e 0.1.2 → 0.2.0

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { Trust } from './trust.js';
 export interface ProviderRules {
     only?: string[];
     ignore?: string[];
@@ -10,6 +11,41 @@ export interface Target {
     url: string;
     readyTimeoutMs: number;
 }
+/**
+ * Sandbox probe lane (Phase B.2, KTD5): runs authored test probes against
+ * `not_exercised` code-review findings inside a hardened Docker container.
+ * Opt-in — `enabled` defaults to false. Fork PRs are gated by `allowForks`,
+ * the `argus-probe` label, or a trusted author_association (see
+ * `evidence/gate.ts`).
+ */
+export interface Sandbox {
+    /** Master switch for the probe lane. Default false. */
+    enabled: boolean;
+    /**
+     * Docker image probes run in — trusted maintainer config (a custom image
+     * extends the sandbox's trusted computing base). Default undefined →
+     * resolved at probe time as `node:<host Node major>-slim`, because native
+     * `node_modules` are ABI-bound to the Node version that installed them.
+     */
+    image: string | undefined;
+    /** Max probes authored/executed per code-review run. Default 3. */
+    maxProbes: number;
+    /** Hard wall-clock timeout per probe in milliseconds. Default 120_000. */
+    timeoutMs: number;
+    /** Container memory limit (`--memory`). Default '2g'. */
+    memory: string;
+    /** Container CPU limit (`--cpus`). Default '2'. */
+    cpus: string;
+    /** Container PID limit (`--pids-limit`). Default 256. */
+    pidsLimit: number;
+    /**
+     * When true, probes run on fork PRs without further approval. When false,
+     * fork PRs require a head-bound `argus-probe` label (the labeled event must
+     * postdate the head's pushed_at) or a MEMBER/OWNER/COLLABORATOR
+     * author_association. Same-repo PRs are unaffected either way.
+     */
+    allowForks: boolean;
+}
 export interface Config {
     model: string;
     escalation_model: string;
@@ -24,6 +60,13 @@ export interface Config {
      * PR diffs and post findings. Defaults to the primary `model` if not set.
      */
     code_model: string | undefined;
+    /**
+     * OpenRouter Decisions API model for typed adjudication (Jev). Defaults
+     * to the pinned `typesafe/jev-1.13-20260917` — alias slugs like
+     * `~typesafe/jev-latest` drift silently and thresholds are calibrated
+     * to a version. Set to `''` to disable adjudication (regex-only mode).
+     */
+    decisionModel: string | undefined;
     /**
      * Hard budget for the `argus-reviewer code-review` lane. When set, the
      * review stops early if the cumulative OpenRouter cost exceeds this cap.
@@ -112,14 +155,74 @@ export interface Config {
      * the app or the expectation is wrong.
      */
     heal: 'local' | 'a0' | undefined;
+    /**
+     * Sandbox probe lane for `code-review` (Phase B.2). Always populated after
+     * `resolveConfig` — `enabled: false` by default so the lane is opt-in.
+     */
+    sandbox: Sandbox;
+    /**
+     * Code-review policy knobs. Always populated after `resolveConfig`.
+     * `secretsThreshold`: Jev `noul` probability at/above which a
+     * secret-shaped diff literal is reported as a finding (below →
+     * suppressed but audit-recorded). Default 0.3 — tune after dogfooding.
+     * `maxComments`: cap on inline review comments posted per run
+     * (default 20) — overflow is summarized count-only in the sticky.
+     * `severityGate`: consumer-facing alias over `severity` — 'bug'
+     * fails on bugs only, 'risk' fails on bug|risk. Unset → `severity`
+     * list is authoritative.
+     * `triage`: Jev pre-review lane — 'off' no call, 'annotate' (default)
+     * records risk/deep-review/area into the report + sticky, 'route'
+     * additionally swaps the code model to `lowRiskModel` on low-risk
+     * diffs. Jev routes/annotates, never gates — coverage is constant.
+     * `lowRiskModel`: the cheap code-model slug 'route' falls to; unset →
+     * route keeps `code_model` (annotate-equivalent).
+     * `findingThreshold`: P(false-positive) required to suppress a nit/q
+     * finding after Jev adjudication — 1.0 (default) is annotate-only,
+     * lowering it suppresses progressively more low-confidence nits.
+     * bug/risk are never suppressed.
+     */
+    review: {
+        secretsThreshold: number;
+        maxComments: number;
+        severityGate: 'bug' | 'risk' | undefined;
+        triage: 'off' | 'annotate' | 'route';
+        lowRiskModel: string | undefined;
+        findingThreshold: number;
+    };
 }
-export type ConfigInput = Partial<Omit<Config, 'provider'>> & {
+export type ConfigInput = Partial<Omit<Config, 'provider' | 'sandbox' | 'review'>> & {
     provider?: Partial<ProviderRules>;
+    sandbox?: Partial<Sandbox>;
+    review?: Partial<Config['review']>;
 };
 export declare const DEFAULT_RECORD_STEP_CAP = 40;
+export declare const DEFAULT_SANDBOX: Sandbox;
 export declare function defineConfig(input: ConfigInput): ConfigInput;
+/**
+ * Which severities fail the review status. `review.severityGate` is the
+ * consumer-facing alias over `severity` — 'risk' fails on bug|risk,
+ * 'bug' on bugs only; unset → the `severity` list is authoritative.
+ */
+export declare function resolveBlockSeverities(config: Config): string[];
+/**
+ * Inline-comment cap: `ARGUS_MAX_COMMENTS` (the action's `max-comments`
+ * input) wins when it parses as a non-negative integer — it's set by the
+ * workflow author, so an untrusted PR config can't reach it (`review`
+ * isn't on the untrusted allowlist). Anything else → `review.maxComments`.
+ */
+export declare function resolveMaxComments(env: Record<string, string | undefined>, config: Config): number;
 export declare function resolveConfig(input?: ConfigInput): Config;
-export declare function loadConfig(cwd: string): Promise<Config>;
+export interface LoadConfigOpts {
+    /**
+     * Required — there is no default. Every call site must state the
+     * checkout's trust so a missed or future caller can't silently execute
+     * config code on a hostile tree (see src/trust.ts).
+     */
+    trust: Trust;
+    /** Human-readable note on security-relevant load decisions (e.g. ctx.err). */
+    note?: (line: string) => void;
+}
+export declare function loadConfig(cwd: string, opts: LoadConfigOpts): Promise<Config>;
 /**
  * Provider slugs the harness recognizes for `provider.only/ignore/order`
  * (KTD4). Unknown slugs warn but do not fail — OpenRouter's catalog changes

package/dist/config.js

@@ -1,10 +1,22 @@
 import { pathToFileURL } from 'node:url';
+import { JEV_DEFAULT_MODEL } from './vision/decisions.js';
 export const DEFAULT_RECORD_STEP_CAP = 40;
+export const DEFAULT_SANDBOX = {
+    enabled: false,
+    image: undefined,
+    maxProbes: 3,
+    timeoutMs: 120_000,
+    memory: '2g',
+    cpus: '2',
+    pidsLimit: 256,
+    allowForks: false,
+};
 const defaults = {
     model: 'google/gemini-2.5-flash-lite',
     escalation_model: 'moonshotai/kimi-k2.5',
     grounding_model: undefined,
     code_model: 'deepseek/deepseek-v4.1-flash',
+    decisionModel: JEV_DEFAULT_MODEL,
     codeReviewBudgetUsd: undefined,
     provider: {
         ignore: ['siliconflow', 'novitaai', 'atlascloud', 'streamlake', 'chutes'],
@@ -27,28 +39,138 @@ const defaults = {
     recordStepCap: DEFAULT_RECORD_STEP_CAP,
     a0: undefined,
     heal: 'local',
+    sandbox: { ...DEFAULT_SANDBOX },
+    review: {
+        secretsThreshold: 0.3,
+        maxComments: 20,
+        severityGate: undefined,
+        triage: 'annotate',
+        lowRiskModel: undefined,
+        findingThreshold: 1.0,
+    },
 };
 export function defineConfig(input) {
     return input;
 }
+/** Positive-integer config values fall back to their default, floored. */
+function posInt(v, dflt) {
+    return v !== undefined && Number.isFinite(v) && v >= 1 ? Math.floor(v) : dflt;
+}
+/** Probability config values (must be in [0,1]) fall back to their default. */
+function prob01(v, dflt) {
+    return v !== undefined && Number.isFinite(v) && v >= 0 && v <= 1 ? v : dflt;
+}
+/**
+ * Which severities fail the review status. `review.severityGate` is the
+ * consumer-facing alias over `severity` — 'risk' fails on bug|risk,
+ * 'bug' on bugs only; unset → the `severity` list is authoritative.
+ */
+export function resolveBlockSeverities(config) {
+    if (config.review.severityGate === 'risk')
+        return ['bug', 'risk'];
+    if (config.review.severityGate === 'bug')
+        return ['bug'];
+    return config.severity ?? ['bug'];
+}
+/**
+ * Inline-comment cap: `ARGUS_MAX_COMMENTS` (the action's `max-comments`
+ * input) wins when it parses as a non-negative integer — it's set by the
+ * workflow author, so an untrusted PR config can't reach it (`review`
+ * isn't on the untrusted allowlist). Anything else → `review.maxComments`.
+ */
+export function resolveMaxComments(env, config) {
+    const raw = env.ARGUS_MAX_COMMENTS?.trim();
+    // ^\d+$ — Number() would also accept '0x10', '1e2', ' 4 ', 'Infinity'.
+    if (raw !== undefined && /^\d+$/.test(raw)) {
+        return Number(raw);
+    }
+    return config.review.maxComments;
+}
 export function resolveConfig(input = {}) {
     const provider = { ...defaults.provider, ...(input.provider ?? {}) };
-    const resolved = { ...defaults, ...input, provider };
-    const cap = resolved.recordStepCap;
-    resolved.recordStepCap =
-        cap !== undefined && Number.isFinite(cap) && cap >= 1
-            ? Math.floor(cap)
-            : DEFAULT_RECORD_STEP_CAP;
+    // Wrong-typed sandbox values (e.g. `sandbox: true`, `enabled: 'yes'`,
+    // `memory: 2048`) degrade silently to defaults — the lane is opt-in and a
+    // mis-typed flag must never feed docker argv or self-enable.
+    const raw = typeof input.sandbox === 'object' && input.sandbox !== null ? input.sandbox : {};
+    const sandbox = { ...defaults.sandbox, ...raw };
+    sandbox.enabled = raw.enabled === true;
+    sandbox.allowForks = raw.allowForks === true;
+    sandbox.image = typeof raw.image === 'string' && raw.image !== '' ? raw.image : undefined;
+    sandbox.memory =
+        typeof raw.memory === 'string' && raw.memory !== '' ? raw.memory : DEFAULT_SANDBOX.memory;
+    sandbox.cpus = typeof raw.cpus === 'string' && raw.cpus !== '' ? raw.cpus : DEFAULT_SANDBOX.cpus;
+    sandbox.maxProbes = posInt(sandbox.maxProbes, DEFAULT_SANDBOX.maxProbes);
+    sandbox.timeoutMs = posInt(sandbox.timeoutMs, DEFAULT_SANDBOX.timeoutMs);
+    sandbox.pidsLimit = posInt(sandbox.pidsLimit, DEFAULT_SANDBOX.pidsLimit);
+    const rawReview = typeof input.review === 'object' && input.review !== null ? input.review : {};
+    const review = { ...defaults.review, ...rawReview };
+    // Thresholds must be probabilities — anything else (NaN, >1,
+    // negative) would silently suppress or flood the Jev lanes.
+    review.secretsThreshold = prob01(review.secretsThreshold, defaults.review.secretsThreshold);
+    review.maxComments =
+        typeof review.maxComments === 'number' &&
+            Number.isInteger(review.maxComments) &&
+            review.maxComments >= 0
+            ? review.maxComments
+            : defaults.review.maxComments;
+    if (review.severityGate !== 'bug' && review.severityGate !== 'risk') {
+        review.severityGate = undefined;
+    }
+    if (review.triage !== 'off' && review.triage !== 'annotate' && review.triage !== 'route') {
+        review.triage = defaults.review.triage;
+    }
+    if (typeof review.lowRiskModel !== 'string' || review.lowRiskModel === '') {
+        review.lowRiskModel = undefined;
+    }
+    review.findingThreshold = prob01(review.findingThreshold, defaults.review.findingThreshold);
+    const resolved = { ...defaults, ...input, provider, sandbox, review };
+    resolved.recordStepCap = posInt(resolved.recordStepCap, DEFAULT_RECORD_STEP_CAP);
     if (resolved.heal !== 'a0')
         resolved.heal = 'local';
+    // '' is the documented opt-out — an empty slug would send a broken
+    // model id to the decisions endpoint on every adjudication call.
+    if (resolved.decisionModel === '')
+        resolved.decisionModel = undefined;
     return resolved;
 }
-export async function loadConfig(cwd) {
+/**
+ * Config keys honored on untrusted checkouts — policy-free fields only.
+ * Everything else (exec-bearing fields, model/budget/provider selection,
+ * severity/verdict policy, credentials maps, network endpoints, write
+ * locations) is ignored: the review policy over hostile code must not be
+ * authored by that code.
+ */
+const UNTRUSTED_CONFIG_KEYS = new Set(['logLevel', 'sourceGlobs']);
+function filterUntrustedConfig(input) {
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (UNTRUSTED_CONFIG_KEYS.has(key))
+            out[key] = value;
+    }
+    return out;
+}
+export async function loadConfig(cwd, opts) {
     const fs = await import('node:fs/promises');
     const path = await import('node:path');
+    const untrusted = opts.trust === 'untrusted';
     const names = ['argus-reviewer.config', 'vision-e2e.config'];
     for (const name of names) {
-        for (const ext of ['.ts', '.json']) {
+        if (untrusted) {
+            // Surface skipped .ts candidates — otherwise a hostile config (or a
+            // legit consumer debugging "why is my config ignored") is invisible.
+            try {
+                if ((await fs.stat(path.join(cwd, `${name}.ts`))).isFile()) {
+                    opts.note?.(`config: ${name}.ts ignored — untrusted checkouts load JSON config only`);
+                }
+            }
+            catch {
+                // no .ts candidate — nothing to note
+            }
+        }
+        // .ts is tried before .json, so an untrusted checkout must skip the .ts
+        // candidate *before* it can shadow a committed .json — importing it
+        // executes arbitrary code beside the runner's secrets (#58).
+        for (const ext of untrusted ? ['.json'] : ['.ts', '.json']) {
             const file = path.join(cwd, `${name}${ext}`);
             try {
                 const stat = await fs.stat(file);
@@ -56,7 +178,12 @@ export async function loadConfig(cwd) {
                     continue;
                 if (ext === '.json') {
                     const raw = await fs.readFile(file, 'utf8');
-                    return resolveConfig(JSON.parse(raw));
+                    const parsed = JSON.parse(raw);
+                    if (untrusted) {
+                        opts.note?.(`config: ${name}.json loaded untrusted — honoring ${[...UNTRUSTED_CONFIG_KEYS].join(', ')} only`);
+                        return resolveConfig(filterUntrustedConfig(parsed));
+                    }
+                    return resolveConfig(parsed);
                 }
                 // Always transpile .ts to a temp .mjs rather than importing natively:
                 // Node's built-in type stripping resolves the module type from the

package/dist/debug.d.ts

@@ -1 +1,2 @@
+export declare function setLiveDir(dir: string | undefined): void;
 export declare function debug(kind: string, ...args: unknown[]): void;

package/dist/debug.js

@@ -1,8 +1,14 @@
 import { join } from 'node:path';
 import { liveLog } from './live.js';
 const DEBUG = process.env.ARGUS_DEBUG === '1' || process.env.ARGUS_DEBUG === 'true';
-// debug() has no config access — it lives under the default cache dir.
-const LIVE_DIR = join(process.cwd(), '.argus-reviewer-cache');
+// debug() has no config access — it defaults to the conventional cache dir,
+// and callers that resolve a config set the real live dir once it's known
+// (otherwise debug lines and stage lines would split across two dirs).
+const DEFAULT_LIVE_DIR = join(process.cwd(), '.argus-reviewer-cache');
+let liveDir = DEFAULT_LIVE_DIR;
+export function setLiveDir(dir) {
+    liveDir = dir ?? DEFAULT_LIVE_DIR;
+}
 function toMsg(arg) {
     if (typeof arg === 'string')
         return arg;
@@ -18,7 +24,7 @@ export function debug(kind, ...args) {
     if (!DEBUG)
         return; // keep debug() free of fs work on the hot path
     for (const arg of args) {
-        liveLog(LIVE_DIR, kind, 'debug', toMsg(arg));
+        liveLog(liveDir, kind, 'debug', toMsg(arg));
         const prefix = `[argus-reviewer:${kind}]`;
         if (typeof arg === 'string') {
             console.error(`${prefix} ${arg}`);

package/dist/detect.d.ts

@@ -7,8 +7,18 @@ export interface ExecResult {
     code: number;
     stdout: string;
     stderr: string;
+    /**
+     * The timeout kill fired — execFile killed the process for exceeding
+     * timeoutMs (`err.killed`). Without this a timed-out command is
+     * indistinguishable from a nonzero exit.
+     */
+    timedOut?: boolean;
+    /** Signal the process was terminated by, when killed (e.g. 'SIGTERM'). */
+    signal?: string | undefined;
 }
-export type ExecFn = (cmd: string, args: string[], timeoutMs: number) => Promise<ExecResult>;
+export type ExecFn = (cmd: string, args: string[], timeoutMs: number, 
+/** Extra env merged over process.env — keeps secrets out of `ps`/`/proc` argv. */
+env?: Record<string, string>) => Promise<ExecResult>;
 export declare const defaultExec: ExecFn;
 export type ProbeFn = (url: string, timeoutMs: number) => Promise<boolean>;
 /**

package/dist/detect.js

@@ -2,12 +2,28 @@ import { execFile } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { readdir, readFile } from 'node:fs/promises';
-export const defaultExec = (cmd, args, timeoutMs) => new Promise((resolve) => {
-    execFile(cmd, args, { timeout: timeoutMs }, (err, stdout, stderr) => {
+export const defaultExec = (cmd, args, timeoutMs, env) => new Promise((resolve) => {
+    // 4 MiB headroom — the sandbox caps output itself after capture, and a
+    // chatty probe hitting execFile's 1 MiB default would error instead of
+    // reaching the harness classifier.
+    execFile(cmd, args, {
+        timeout: timeoutMs,
+        maxBuffer: 4 * 1024 * 1024,
+        ...(env !== undefined ? { env: { ...process.env, ...env } } : {}),
+    }, (err, stdout, stderr) => {
         if (err) {
             // stderr is '' (not undefined) on spawn ENOENT — fall back to the
             // error message so callers can distinguish "missing" from "failed".
-            resolve({ code: 1, stdout: String(stdout), stderr: String(stderr) || err.message });
+            resolve({
+                code: 1,
+                stdout: String(stdout),
+                stderr: String(stderr) || err.message,
+                // killed is also true on maxBuffer overflow — that's an output
+                // problem, not a timeout; classify by the error code.
+                timedOut: err.killed === true &&
+                    err.code !== 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+                signal: typeof err.signal === 'string' ? err.signal : undefined,
+            });
         }
         else {
             resolve({ code: 0, stdout: String(stdout), stderr: String(stderr) });

package/dist/evidence/ci.d.ts

@@ -1,6 +1,14 @@
 interface Ctx {
     err: (line: string) => void;
 }
+/** Maintainer-applied PR label that opts a fork PR into sandbox probes. */
+export declare const PROBE_LABEL = "argus-probe";
+/**
+ * GitHub `author_association` values trusted to run probes on fork PRs —
+ * repo members/owners/collaborators. CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR,
+ * FIRST_TIMER, MANNEQUIN, and NONE are not.
+ */
+export declare function isTrustedAssociation(association: string | undefined): boolean;
 export interface CheckRun {
     name: string;
     /** GitHub check-run conclusion once status === 'completed'; undefined while pending. */
@@ -9,10 +17,47 @@ export interface CheckRun {
     url: string | undefined;
 }
 export interface PrMeta {
+    /** PR head SHA — the commit the PR's check-runs are attached to. */
     headSha: string | undefined;
+    /** PR base SHA — the merge base probes run against for the double-run. */
+    baseSha: string | undefined;
+    /** `head.repo.fork` — true when the PR head branch lives in a fork. */
+    isFork: boolean;
+    /**
+     * Raw `author_association` for the PR (OWNER, MEMBER, COLLABORATOR,
+     * CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR, FIRST_TIMER, MANNEQUIN, NONE).
+     */
+    authorAssociation: string | undefined;
+    /** Names of labels currently applied to the PR. */
+    labels: string[];
+    /**
+     * `head.repo.pushed_at` — the freshest push timestamp the probe label gate
+     * can compare against (head commits arrive via pushes; comparing against
+     * this is what binds label approval to the current head).
+     */
+    pushedAt: string | undefined;
+    /**
+     * Timestamp of the newest `argus-probe` `labeled` event on the PR, from the
+     * issue timeline — undefined when the label was never applied or the
+     * timeline fetch failed (the gate fails closed either way).
+     */
+    labelApprovedAt: string | undefined;
+    /** PR title/body — triage state only (untrusted text; feeds Jev, never gates). */
+    title: string | undefined;
+    body: string | undefined;
 }
-/** PR head SHA — the commit the PR's check-runs are attached to. */
-export declare function fetchPrHeadSha(repo: string, pr: string, token: string, ctx: Ctx): Promise<string | undefined>;
+/**
+ * Shared GitHub GET scaffold — Bearer auth, API headers, 30s abort timeout,
+ * `ctx.err` on non-ok/timeout, undefined on failure. Reuse for any
+ * api.github.com read (fetchPrFiles in cli.ts paginates over it).
+ */
+export declare function ghGet(url: string, token: string, ctx: Ctx): Promise<unknown | undefined>;
+/**
+ * PR metadata for the evidence + probe lanes — the head SHA check-runs attach
+ * to, plus the fork/association/label signals the sandbox fork gate (KTD5)
+ * evaluates. One `/pulls/{pr}` request; undefined when the request fails.
+ */
+export declare function fetchPrMeta(repo: string, pr: string, token: string, ctx: Ctx): Promise<PrMeta | undefined>;
 /** Check-runs on a commit — the consumer's own CI signal. */
 export declare function fetchCheckRuns(repo: string, sha: string, token: string, ctx: Ctx): Promise<CheckRun[] | undefined>;
 export {};

package/dist/evidence/ci.js

@@ -1,6 +1,21 @@
+/** Maintainer-applied PR label that opts a fork PR into sandbox probes. */
+export const PROBE_LABEL = 'argus-probe';
+/**
+ * GitHub `author_association` values trusted to run probes on fork PRs —
+ * repo members/owners/collaborators. CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR,
+ * FIRST_TIMER, MANNEQUIN, and NONE are not.
+ */
+export function isTrustedAssociation(association) {
+    return association === 'MEMBER' || association === 'OWNER' || association === 'COLLABORATOR';
+}
 const GH_API = 'https://api.github.com';
 const MAX_CHECK_RUN_PAGES = 5;
-async function ghGet(url, token, ctx) {
+/**
+ * Shared GitHub GET scaffold — Bearer auth, API headers, 30s abort timeout,
+ * `ctx.err` on non-ok/timeout, undefined on failure. Reuse for any
+ * api.github.com read (fetchPrFiles in cli.ts paginates over it).
+ */
+export async function ghGet(url, token, ctx) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 30_000);
     try {
@@ -21,18 +36,95 @@ async function ghGet(url, token, ctx) {
     catch (e) {
         if (e instanceof Error && e.name === 'AbortError') {
             ctx.err(`evidence: github request timed out — ${url}`);
-            return undefined;
         }
-        throw e;
+        else {
+            // DNS/socket/protocol failures — same contract: undefined, never throw.
+            ctx.err(`evidence: github request failed — ${url} (${e.message})`);
+        }
+        return undefined;
     }
     finally {
         clearTimeout(timeout);
     }
 }
-/** PR head SHA — the commit the PR's check-runs are attached to. */
-export async function fetchPrHeadSha(repo, pr, token, ctx) {
+/**
+ * PR metadata for the evidence + probe lanes — the head SHA check-runs attach
+ * to, plus the fork/association/label signals the sandbox fork gate (KTD5)
+ * evaluates. One `/pulls/{pr}` request; undefined when the request fails.
+ */
+export async function fetchPrMeta(repo, pr, token, ctx) {
     const data = (await ghGet(`${GH_API}/repos/${repo}/pulls/${pr}`, token, ctx));
-    return data?.head?.sha;
+    if (data === undefined)
+        return undefined;
+    const labels = Array.isArray(data.labels)
+        ? data.labels.map((l) => l?.name).filter((n) => typeof n === 'string')
+        : [];
+    // The timeline call only matters when the label is the deciding signal —
+    // forks from untrusted authors carrying the label. Skip it otherwise.
+    const needsTimeline = data.head?.repo?.fork === true &&
+        !isTrustedAssociation(data.author_association) &&
+        labels.includes(PROBE_LABEL);
+    const labelApprovedAt = needsTimeline
+        ? await fetchLabelApprovedAt(repo, pr, token, ctx)
+        : undefined;
+    // The pulls payload has NO merge-base field — derive it from the compare
+    // API (merge_base_commit.sha). Base-branch tip is the fallback: it can
+    // contain fixes the PR never saw and misattribute them to the change.
+    const headSha = data.head?.sha;
+    const baseSha = data.base?.sha;
+    const mergeBase = headSha !== undefined && baseSha !== undefined
+        ? await fetchMergeBase(repo, baseSha, headSha, token, ctx)
+        : undefined;
+    return {
+        headSha,
+        baseSha: mergeBase ?? baseSha,
+        // head.repo is null when the source fork was deleted — fail closed and
+        // treat it as a fork so the probe gate still applies.
+        isFork: data.head?.repo?.fork !== false,
+        authorAssociation: typeof data.author_association === 'string' ? data.author_association : undefined,
+        labels,
+        pushedAt: data.head?.repo?.pushed_at,
+        labelApprovedAt,
+        title: typeof data.title === 'string' ? data.title : undefined,
+        body: typeof data.body === 'string' ? data.body : undefined,
+    };
+}
+/**
+ * Merge base via the compare API — `GET /compare/{base}...{head}` returns
+ * `merge_base_commit.sha`, the commit the PR actually diverged from.
+ */
+async function fetchMergeBase(repo, base, head, token, ctx) {
+    const data = (await ghGet(`${GH_API}/repos/${repo}/compare/${base}...${head}`, token, ctx));
+    return data?.merge_base_commit?.sha;
+}
+/**
+ * Newest `labeled` event for `argus-probe` on the PR's issue events feed.
+ * The label on the payload proves it's currently applied; the event
+ * timestamp is what binds approval to the current head (a `synchronize`
+ * push after the label must not inherit it). Uses the *events* endpoint —
+ * not timeline — because it carries only state events (no comments), so a
+ * busy PR's `labeled` event isn't drowned past page one. Pages are
+ * oldest-first with no reverse sort, so we take the newest within a
+ * bounded 3-page scan; a still-busier PR fails closed.
+ */
+async function fetchLabelApprovedAt(repo, pr, token, ctx) {
+    let latest;
+    for (let page = 1; page <= 3; page++) {
+        const events = (await ghGet(`${GH_API}/repos/${repo}/issues/${pr}/events?per_page=100&page=${page}`, token, ctx));
+        if (!Array.isArray(events))
+            return undefined;
+        for (const e of events) {
+            if (e?.event === 'labeled' &&
+                e.label?.name === PROBE_LABEL &&
+                typeof e.created_at === 'string') {
+                if (latest === undefined || e.created_at > latest)
+                    latest = e.created_at;
+            }
+        }
+        if (events.length < 100)
+            break;
+    }
+    return latest;
 }
 /** Check-runs on a commit — the consumer's own CI signal. */
 export async function fetchCheckRuns(repo, sha, token, ctx) {

package/dist/evidence/gate.d.ts

@@ -0,0 +1,10 @@
+import type { Sandbox } from '../config.js';
+import { type PrMeta } from './ci.js';
+/**
+ * Fork gate for the sandbox probe lane (KTD5). Evaluation order: the lane
+ * must be `enabled`; `allowForks: true` runs everywhere; same-repo PRs run
+ * unconditionally; fork PRs require a per-head `argus-probe` label or a
+ * trusted author_association. Fails closed — missing PR metadata, deleted
+ * forks (`isFork` forced true in fetchPrMeta), and stale labels all deny.
+ */
+export declare function mayProbePr(meta: PrMeta | undefined, sandbox: Sandbox): boolean;

package/dist/evidence/gate.js

@@ -0,0 +1,29 @@
+import { isTrustedAssociation, PROBE_LABEL } from './ci.js';
+/**
+ * The label approves only the head it was applied to: the `labeled` event
+ * must postdate `head.repo.pushed_at`. A `synchronize` push after approval
+ * requires a fresh label — otherwise approval silently carries to code the
+ * maintainer never saw. Either timestamp missing → label doesn't approve
+ * (fail closed).
+ */
+function labelCoversHead(meta) {
+    return (meta.labelApprovedAt !== undefined &&
+        meta.pushedAt !== undefined &&
+        meta.labelApprovedAt > meta.pushedAt);
+}
+/**
+ * Fork gate for the sandbox probe lane (KTD5). Evaluation order: the lane
+ * must be `enabled`; `allowForks: true` runs everywhere; same-repo PRs run
+ * unconditionally; fork PRs require a per-head `argus-probe` label or a
+ * trusted author_association. Fails closed — missing PR metadata, deleted
+ * forks (`isFork` forced true in fetchPrMeta), and stale labels all deny.
+ */
+export function mayProbePr(meta, sandbox) {
+    if (!sandbox.enabled || meta === undefined)
+        return false;
+    if (sandbox.allowForks || !meta.isFork)
+        return true;
+    if (isTrustedAssociation(meta.authorAssociation))
+        return true;
+    return meta.labels.includes(PROBE_LABEL) && labelCoversHead(meta);
+}

package/dist/evidence/link.d.ts

@@ -1,6 +1,11 @@
 import type { RepoIndex } from '../index/scan.js';
 import type { CheckRun } from './ci.js';
-export type EvidenceStatus = 'exercised' | 'corroborated' | 'not_exercised' | 'inconclusive';
+/**
+ * `reproduced` is emitted only by the B.2 probe stage — a sandboxed test probe
+ * demonstrated the defect (KTD4). `linkFindings` never produces it; the probe
+ * stage is the only writer and can only move `not_exercised` → `reproduced`.
+ */
+export type EvidenceStatus = 'exercised' | 'corroborated' | 'not_exercised' | 'inconclusive' | 'reproduced';
 export interface Evidence {
     status: EvidenceStatus;
     detail: string;