argus-reviewer-e2e 0.1.2 → 0.1.3

package/README.md

@@ -10,6 +10,7 @@ Open-source, self-hosted vision-model E2E testing — the hundred-eyed watcher f
 - **Cache-first**: replay costs zero vision calls on an unchanged UI; heals re-spend only on drift and show up as reviewable cache diffs.
 - **Cost-explicit**: every call is metered from OpenRouter's per-call cost and rolled into a per-run dollar figure on the PR.
 - **Grounding specialist**: a `grounding_model` (e.g. a ui-tars-class model) can drive element location with its native coordinate output, verified against the DOM before any click executes.
+- **Execution-backed review**: `code-review` findings carry CI evidence, and with the opt-in sandbox lane (`sandbox: { enabled: true }`) Argus authors a test probe for unexercised findings and runs it in a hardened, network-less Docker container — a finding that fails on head and passes on base is stamped **reproduced**, not just suspected.
 
 ```bash
 npm i -D argus-reviewer-e2e        # or github:duketopceo/argus-reviewer

package/action/action.yml

@@ -42,6 +42,10 @@ inputs:
     description: Report output dir, passed to both run and code-review so the post step can find run.json/code-review.json regardless of config reportDir
     default: argus-reviewer-report
     required: false
+  sandbox:
+    description: Enable the B.2 probe lane — authored test probes for unexercised findings run in a hardened Docker container (no network, no secrets, read-only fs). Enable-only — 'false' does not override a config-enabled lane. Requires Docker on the runner; forced off on pull_request_target.
+    default: 'false'
+    required: false
 outputs:
   conclusion:
     description: 'Run conclusion: success, failure, or neutral'
@@ -99,6 +103,7 @@ runs:
       env:
         OPENROUTER_API_KEY: ${{ inputs.openrouter-api-key }}
         GITHUB_TOKEN: ${{ github.token }}
+        ARGUS_SANDBOX: ${{ inputs.sandbox == 'true' && '1' || '' }}
         ARGUS_DEBUG: '1'
         ARGUS_REVIEWER_TRACE: >-
           {"repo":"${{ github.repository }}",

package/action/sticky-comment.mjs

@@ -9,6 +9,11 @@ function formatUsd(n) {
   return `$${(n || 0).toFixed(6)}`
 }
 
+/** Escape a report string for one markdown table cell. */
+function cell(s) {
+  return String(s ?? '').replace(/\|/g, '\\|').replace(/[\r\n]+/g, ' ').slice(0, 200)
+}
+
 function renderMissingKeyBody() {
   const lines = []
   lines.push(SENTINEL)
@@ -193,18 +198,32 @@ function renderBody(report, codeReview, runUrl, ok) {
     lines.push('<summary>🧠 Code review</summary>')
     lines.push('')
     lines.push(`**Verdict:** ${codeReview.verdict} · ${codeReview.model} · ${codeReview.tokens}tok ${formatUsd(codeReview.visionCostUsd)}`)
+    if (Array.isArray(codeReview.probes) && codeReview.probes.length > 0) {
+      const reproduced = codeReview.probes.filter((p) => p.outcome === 'reproduced').length
+      lines.push(` · 🧪 ${codeReview.probes.length} probe${codeReview.probes.length === 1 ? '' : 's'} run, ${reproduced} reproduced`)
+    }
+    if (typeof codeReview.probeLaneSkipped === 'string') {
+      lines.push(` · 🧪 probe lane skipped — ${cell(codeReview.probeLaneSkipped)}`)
+    }
     lines.push('')
     lines.push(codeReview.summary)
     lines.push('')
     if (codeReview.findings.length > 0) {
-      const evidenceIcon = { exercised: '✅', corroborated: '🔴', not_exercised: '⚪', inconclusive: '❔' }
+      const evidenceIcon = { exercised: '✅', corroborated: '🔴', not_exercised: '⚪', inconclusive: '❔', reproduced: '🧪' }
       lines.push('| File | Severity | Evidence | Finding |')
       lines.push('| --- | --- | --- | --- |')
-      for (const f of codeReview.findings) {
+      // Findings/evidence strings are model- and probe-emitted — sanitize
+      // for the markdown table and bound the section so an oversized report
+      // can't push the body past GitHub's 65536-char comment limit.
+      const MAX_FINDING_ROWS = 25
+      for (const f of codeReview.findings.slice(0, MAX_FINDING_ROWS)) {
         const ev = f.evidence
-          ? `${evidenceIcon[f.evidence.status] ?? '❔'} ${f.evidence.detail}`
+          ? `${evidenceIcon[f.evidence.status] ?? '❔'} ${cell(f.evidence.detail)}`
           : '—'
-        lines.push(`| \`${f.file}\` | ${f.severity} | ${ev} | ${f.message} |`)
+        lines.push(`| \`${cell(f.file)}\` | ${cell(f.severity)} | ${ev} | ${cell(f.message)} |`)
+      }
+      if (codeReview.findings.length > MAX_FINDING_ROWS) {
+        lines.push(`| … | — | — | ${codeReview.findings.length - MAX_FINDING_ROWS} more findings in \`code-review.json\` |`)
       }
       lines.push('')
     }
@@ -281,14 +300,23 @@ async function postInlineComments(pr, codeReview) {
       path: f.file,
       line: f.line,
       side: 'RIGHT',
-      body: `**argus-reviewer ${f.severity}:** ${f.message}${f.evidence && f.evidence.status !== 'exercised' ? `\n\n*CI evidence: ${f.evidence.detail}*` : ''}`,
+      body: `**argus-reviewer ${f.severity}:** ${f.message}${
+        f.evidence && f.evidence.status === 'reproduced'
+          ? '\n\n*🧪 Reproduced by an Argus probe — fails on this PR head, clean on base. See workflow artifacts.*'
+          : f.evidence && f.evidence.status !== 'exercised'
+            ? `\n\n*CI evidence: ${f.evidence.detail}*`
+            : ''
+      }`,
     }))
   if (comments.length === 0) return
 
   // Re-runs on the same SHA must not duplicate inline comments — the sticky
   // body is upserted but review comments are not. Paginate fully (100/page)
   // and scope dedup to the current head: comments on older commits must not
-  // suppress findings that still apply to this head.
+  // suppress findings that still apply to this head. The key is the body's
+  // first line (the finding itself) — trailing evidence notes like the
+  // `reproduced` upgrade change the body but must not re-post a duplicate.
+  const dedupKey = (path, line, body) => `${path}:${line}:${body.split('\n')[0]}`
   const posted = new Set()
   let page = 1
   for (;;) {
@@ -301,13 +329,13 @@ async function postInlineComments(pr, codeReview) {
     })
     for (const c of existing) {
       if (c.body && c.body.startsWith('**argus-reviewer') && c.commit_id === pr.head.sha) {
-        posted.add(`${c.path}:${c.line}:${c.body}`)
+        posted.add(dedupKey(c.path, c.line, c.body))
       }
     }
     if (existing.length < 100) break
     page += 1
   }
-  const fresh = comments.filter((c) => !posted.has(`${c.path}:${c.line}:${c.body}`))
+  const fresh = comments.filter((c) => !posted.has(dedupKey(c.path, c.line, c.body)))
   if (fresh.length === 0) return
 
   // One batched review instead of N createReviewComment calls — avoids

package/dist/cli.js

@@ -17,8 +17,9 @@ import { buildReviewContext, CONTEXT_PREFIX } from './index/context.js';
 import { diffChangedFiles } from './index/diff.js';
 import { invalidateForDiff } from './index/invalidate.js';
 import { readIndex, scanRepo, writeIndex } from './index/scan.js';
-import { fetchCheckRuns, fetchPrHeadSha } from './evidence/ci.js';
+import { fetchCheckRuns, fetchPrMeta, ghGet } from './evidence/ci.js';
 import { linkFindings } from './evidence/link.js';
+import { runProbeLane } from './probe/queue.js';
 import { A0_DEFAULT_TIMEOUT_MS, a0TaskPrompt, runA0Task } from './executor/a0.js';
 import { buildJournalEntry } from './journal/build.js';
 import { newRunId, writeJournal } from './journal/store.js';
@@ -27,6 +28,7 @@ import { liveLog } from './live.js';
 import { writeJunitXml } from './report/junit.js';
 import { buildRunReport, writeRunReport } from './report/run.js';
 import { flowPath, loadFlow } from './cache/store.js';
+import { writeAtomicJson } from './fsutil.js';
 import { OpenRouterClient } from './vision/openrouter.js';
 import { Ledger } from './vision/ledger.js';
 const USAGE = `argus-reviewer — vision-model E2E testing harness (BYOK via OPENROUTER_API_KEY)
@@ -705,41 +707,13 @@ const CHUNK_FILE_OVERHEAD = 100;
 const MAX_PR_FILE_PAGES = 10;
 async function fetchPrFiles(repo, pr, token, ctx) {
     const files = [];
-    let page = 1;
-    while (page <= MAX_PR_FILE_PAGES) {
-        const url = `https://api.github.com/repos/${repo}/pulls/${pr}/files?per_page=100&page=${page}`;
-        const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), 30_000);
-        try {
-            const res = await fetch(url, {
-                signal: controller.signal,
-                headers: {
-                    Authorization: `Bearer ${token}`,
-                    Accept: 'application/vnd.github+json',
-                    'X-GitHub-Api-Version': '2022-11-28',
-                },
-            });
-            if (!res.ok) {
-                ctx.err(`failed to fetch PR files: ${res.status} ${res.statusText}`);
-                return undefined;
-            }
-            const batch = (await res.json());
-            const withPatches = batch.filter((f) => typeof f.patch === 'string' && f.patch.length > 0);
-            files.push(...withPatches);
-            if (batch.length < 100)
-                break;
-            page++;
-        }
-        catch (e) {
-            if (e instanceof Error && e.name === 'AbortError') {
-                ctx.err(`failed to fetch PR files: request timed out after 30s (page ${page})`);
-                return undefined;
-            }
-            throw e;
-        }
-        finally {
-            clearTimeout(timeout);
-        }
+    for (let page = 1; page <= MAX_PR_FILE_PAGES; page++) {
+        const batch = (await ghGet(`https://api.github.com/repos/${repo}/pulls/${pr}/files?per_page=100&page=${page}`, token, ctx));
+        if (batch === undefined)
+            return undefined;
+        files.push(...batch.filter((f) => typeof f.patch === 'string' && f.patch.length > 0));
+        if (batch.length < 100)
+            break;
     }
     return files;
 }
@@ -892,7 +866,7 @@ async function cmdCodeReview(args, ctx, deps) {
             model,
             budgetExceeded: false,
         };
-        await writeFile(codeReviewPath, `${JSON.stringify(skipped, null, 2)}\n`, 'utf8');
+        await writeAtomicJson(codeReviewPath, skipped);
         return 0;
     };
     if (!repo || !pr)
@@ -916,6 +890,9 @@ async function cmdCodeReview(args, ctx, deps) {
     try {
         const client = createClient(deps, config, ctx);
         const ledger = new Ledger(budget);
+        // Kick off PR metadata now — it only needs repo/pr/token and its
+        // round-trip hides behind the model calls. Degrades to undefined.
+        const prMetaPromise = fetchPrMeta(repo, pr, token, ctx).catch(() => undefined);
         const allFindings = [];
         const allCalls = [];
         let totalTokens = 0;
@@ -1003,25 +980,81 @@ async function cmdCodeReview(args, ctx, deps) {
         // exercised the implicated path. Post-pass annotation only — evidence
         // never downgrades a finding, and check-run names are sanitized before
         // they reach the comment.
-        const headSha = await fetchPrHeadSha(repo, pr, token, ctx);
+        // prMeta also carries isFork/authorAssociation/labels — the B.2 probe
+        // lane's fork gate (evidence/gate.ts) consumes them; only headSha feeds
+        // evidence linkage here.
+        const prMeta = await prMetaPromise;
+        const headSha = prMeta?.headSha;
         const checkRuns = headSha === undefined ? undefined : await fetchCheckRuns(repo, headSha, token, ctx);
         const linkedFindings = linkFindings(finalFindings, index, checkRuns);
         debug('code-review', `evidence: ${linkedFindings.map((f) => f.evidence.status).join(',')}`);
         const blockSeverities = config.severity ?? ['bug'];
-        const hasBlocker = finalFindings.some((f) => blockSeverities.includes(f.severity ?? ''));
+        // B.2 probe lane: authored tests executed in the Docker sandbox can
+        // upgrade a not_exercised finding to `reproduced`. Strictly additive —
+        // failures degrade to a detail note and the lane never changes verdict,
+        // ok, or the exit code (KTD8). Opt-in via config.sandbox.enabled or the
+        // ARGUS_SANDBOX=1 env flag (enable-only; other values leave config
+        // authoritative).
+        let probes;
+        let probeLaneSkipped;
+        const sandbox = { ...config.sandbox, enabled: config.sandbox.enabled || ctx.env.ARGUS_SANDBOX === '1' };
+        // pull_request_target runs with the base repo's write token and ambient
+        // secrets — the docs call the lane unsupported there; enforce it in
+        // code too so a miswired workflow fails closed instead of executing
+        // PR code beside real credentials.
+        if (ctx.env.GITHUB_EVENT_NAME === 'pull_request_target')
+            sandbox.enabled = false;
+        if (sandbox.enabled && !ledger.budgetExceeded) {
+            try {
+                const lane = await runProbeLane(linkedFindings, {
+                    cwd: ctx.cwd,
+                    reportDir,
+                    sandbox,
+                    meta: prMeta,
+                    token,
+                    client,
+                    model,
+                    provider: config.provider,
+                    ledger,
+                    budgetUsd: budget,
+                    severityGates: blockSeverities,
+                    index,
+                    calls: allCalls,
+                    exec: deps.exec,
+                    log: (line) => ctx.err(line),
+                });
+                if (lane !== undefined) {
+                    probes = lane.records;
+                    probeLaneSkipped = lane.skipReason;
+                    // Probe authoring spend lands on the shared ledger — the report's
+                    // headline cost fields must count it too or they understate the run.
+                    for (const p of lane.records) {
+                        totalCost += p.costUsd ?? 0;
+                        totalTokens += p.tokens ?? 0;
+                    }
+                }
+            }
+            catch (e) {
+                debug('code-review', `probe lane failed: ${e.message}`);
+                ctx.err(`code-review probe lane failed: ${e.message}`);
+            }
+        }
+        const hasBlocker = finalFindings.some((f) => blockSeverities.includes(f.severity));
         const report = {
             ok: !hasBlocker && !ledger.budgetExceeded,
             skipped: false,
             summary,
             verdict,
             findings: linkedFindings,
+            ...(probes !== undefined ? { probes } : {}),
+            ...(probeLaneSkipped !== undefined ? { probeLaneSkipped } : {}),
             calls: allCalls,
             visionCostUsd: totalCost,
             tokens: totalTokens,
             model: lastModel,
             budgetExceeded: ledger.budgetExceeded,
         };
-        await writeFile(codeReviewPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
+        await writeAtomicJson(codeReviewPath, report);
         ctx.out(`code review complete: ${finalFindings.length} findings, verdict ${verdict}, ` +
             `${totalTokens}tok $${totalCost.toFixed(6)}${ledger.budgetExceeded ? ' (budget exceeded)' : ''}`);
         return 0;
@@ -1199,10 +1232,16 @@ const INIT_WORKFLOW = `name: argus-reviewer
 
 on:
   pull_request:
+    # 'labeled' lets a maintainer re-trigger with the argus-probe label when
+    # sandbox probes are enabled for fork PRs.
+    types: [opened, synchronize, reopened, labeled]
 
 jobs:
   argus:
     runs-on: ubuntu-latest
+    # 'labeled' fires on EVERY label — only argus-probe is the fork-gate
+    # signal worth a full review run.
+    if: github.event.action != 'labeled' || github.event.label.name == 'argus-probe'
     permissions:
       contents: read
       issues: write
@@ -1210,7 +1249,11 @@ jobs:
       checks: write
       statuses: write
     steps:
+      # persist-credentials: false keeps the GITHUB_TOKEN out of .git/config —
+      # the probe sandbox masks .git regardless, but don't store it at all.
       - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
       # Pin a tag or commit for supply-chain safety once releases are cut.
       - uses: duketopceo/Argus/action@main
         with:

package/dist/config.d.ts

@@ -10,6 +10,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;
@@ -112,11 +147,18 @@ 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;
 }
-export type ConfigInput = Partial<Omit<Config, 'provider'>> & {
+export type ConfigInput = Partial<Omit<Config, 'provider' | 'sandbox'>> & {
     provider?: Partial<ProviderRules>;
+    sandbox?: Partial<Sandbox>;
 };
 export declare const DEFAULT_RECORD_STEP_CAP = 40;
+export declare const DEFAULT_SANDBOX: Sandbox;
 export declare function defineConfig(input: ConfigInput): ConfigInput;
 export declare function resolveConfig(input?: ConfigInput): Config;
 export declare function loadConfig(cwd: string): Promise<Config>;

package/dist/config.js

@@ -1,5 +1,15 @@
 import { pathToFileURL } from 'node:url';
 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',
@@ -27,18 +37,32 @@ const defaults = {
     recordStepCap: DEFAULT_RECORD_STEP_CAP,
     a0: undefined,
     heal: 'local',
+    sandbox: { ...DEFAULT_SANDBOX },
 };
 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;
+}
 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 resolved = { ...defaults, ...input, provider, sandbox };
+    resolved.recordStepCap = posInt(resolved.recordStepCap, DEFAULT_RECORD_STEP_CAP);
     if (resolved.heal !== 'a0')
         resolved.heal = 'local';
     return resolved;

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,44 @@ 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 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 {};