argus-reviewer-e2e 0.1.2 → 0.1.3

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,93 @@ 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,
+    };
+}
+/**
+ * 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;

package/dist/evidence/link.js

@@ -2,13 +2,15 @@
 const TEST_FILE_RE = /(?:^|\/)(?:tests?|e2e|__tests__|__spec__)\/|\.(?:test|spec|e2e-spec)\.[jt]sx?$/i;
 /** Check-run names that look like test jobs (lint/build/status lanes don't count). */
 const TEST_RUN_RE = /\b(test|tests|spec|specs|e2e|smoke|jest|vitest|pytest|rspec|mocha|ava|unittest)\b/i;
-/** Argus's own check-runs are the reporter, not consumer CI evidence. */
-const ARGUS_RUN_RE = /argus/i;
+/** Argus's own check-runs are the reporter, not consumer CI evidence.
+ * Anchored to our own names — a consumer's `argus-unit-tests` lane must
+ * still count. */
+const ARGUS_RUN_RE = /^argus(?:-reviewer)?[\s/]/i;
 /** Check-run conclusions that mean "didn't actually run" — never evidence. */
 const DID_NOT_RUN = new Set(['neutral', 'skipped', 'cancelled', 'action_required', 'stale', 'startup_failure']);
 /** Strip comment-hostile characters — check-run names are repo-controlled and reach the PR comment. */
 export function sanitizeForComment(s, max = 80) {
-    return s.replace(/[|\r\n<>]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
+    return s.replace(/[|\r\n<>`]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, max);
 }
 export function isTestFile(path) {
     return TEST_FILE_RE.test(path);
@@ -23,8 +25,8 @@ export function testReachableFiles(index) {
     const roots = index.entries.filter((e) => isTestFile(e.path)).map((e) => e.path);
     const seen = new Set(roots);
     const queue = [...roots];
-    while (queue.length > 0) {
-        const cur = queue.shift();
+    for (let i = 0; i < queue.length; i++) {
+        const cur = queue[i];
         for (const dep of byPath.get(cur)?.imports ?? []) {
             if (!seen.has(dep)) {
                 seen.add(dep);

package/dist/executor/sandbox.d.ts

@@ -0,0 +1,105 @@
+import type { Sandbox } from '../config.js';
+import { type ExecFn } from '../detect.js';
+/**
+ * Docker sandbox for the B.2 probe lane — the security boundary around
+ * executing PR-contributed probe code on the consumer's runner.
+ *
+ * Invariants (KTD2 / R4): no ambient env, no network, read-only root,
+ * non-root, all capabilities dropped, no-new-privileges, resource + PID
+ * limits, `.git` masked inside the container, exactly one writable bind
+ * mount (the probes scratch dir), and a wall-clock timeout enforced by
+ * daemon-side `docker rm -f` — killing the `docker` CLI alone does not
+ * guarantee the container dies when its PID 1 traps the forwarded signal.
+ */
+/** Output cap per stream — probe output is attacker-controlled. */
+export declare const SANDBOX_OUTPUT_CAP: number;
+/** Filesystem path inside the container where the workspace lands. */
+export declare const CONTAINER_WORKDIR = "/work";
+/** Name of the single writable mount — lives under reportDir/probes-out. */
+export declare const SCRATCH_DIR_NAME = "probes-out";
+export interface SandboxRunOptions {
+    /** Absolute host path of the PR checkout — bind-mounted at /work:ro. */
+    workdir: string;
+    /**
+     * Absolute host path of the writable scratch dir. Must resolve (after
+     * realpath) to a strict descendant of workdir — a checked-in symlink must
+     * never turn this into a writable bind of an arbitrary host path.
+     */
+    scratchDir: string;
+    /** In-container command argv. */
+    cmd: string[];
+    /** Resolved image (`config.sandbox.image` or `node:<host major>-slim`). */
+    image: string;
+    /** Container name suffix — becomes `argus-probe-<pid>-<name>`. */
+    name: string;
+    timeoutMs: number;
+    memory: string;
+    cpus: string;
+    pidsLimit: number;
+    /**
+     * Extra host dirs bind-mounted read-only at the given container path —
+     * the base run borrows head's node_modules since a git worktree has none.
+     */
+    roMounts?: {
+        host: string;
+        container: string;
+    }[] | undefined;
+    /** Extra container paths (under /work) masked with tmpfs. */
+    masks?: string[] | undefined;
+    exec?: ExecFn;
+}
+export interface SandboxRunResult {
+    /** -1 when the run never started (path check, spawn failure). */
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    durationMs: number;
+    timedOut: boolean;
+}
+/** Strict C0/control-byte strip — applied before output leaves the module. */
+export declare function stripControlChars(s: string): string;
+/**
+ * Resolve the probe image: an explicit `sandbox.image` always wins;
+ * otherwise pin to the host's own Node major so native `node_modules`
+ * (ABI-bound to the installing Node) load inside the container.
+ */
+export declare function resolveSandboxImage(image: string | undefined): string;
+/**
+ * Filesystem safety check before any `docker run`: the scratch dir must
+ * realpath-resolve to a strict descendant of the real workdir. Rejects a
+ * reportDir symlinked out of the tree or configured outside the checkout —
+ * both would turn the rw bind-mount into a write primitive on the host.
+ */
+export declare function checkSandboxPaths(workdir: string, scratchDir: string): Promise<{
+    ok: true;
+    realWork: string;
+    realScratch: string;
+    relMount: string;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/**
+ * Docker is usable AND resolves the runner's workspace path — bind-mount
+ * sources are evaluated by the daemon, so a remote/containerized daemon can
+ * silently mount an empty dir. The smoke run uses the SAME hardening
+ * profile as probe runs (plus `--pull always` and an entrypoint override) —
+ * an availability check that ran the image unhardened would bypass every
+ * invariant this module exists to enforce.
+ */
+export declare function dockerAvailable(exec: ExecFn, image: string, workdir: string): Promise<boolean>;
+/** How `.git` presents on disk — dir (normal checkout), file (worktree), or absent. */
+type GitMode = 'dir' | 'file' | 'absent';
+/**
+ * The full `docker run` argv (KTD2). Every flag is pinned here — this is the
+ * single place the sandbox boundary lives. `name` is the full container name.
+ */
+export declare function buildSandboxArgv(opts: Pick<SandboxRunOptions, 'image' | 'cmd' | 'memory' | 'cpus' | 'pidsLimit' | 'roMounts' | 'masks'>, name: string, checked: {
+    realWork: string;
+    realScratch: string;
+    relMount: string;
+}, gitMode: GitMode, secretFiles: string[]): string[];
+export declare function runProbeInSandbox(opts: SandboxRunOptions): Promise<SandboxRunResult>;
+/** Limits convenience — what `runProbeInSandbox` needs from config.sandbox. */
+export declare function sandboxLimits(sandbox: Sandbox): Pick<SandboxRunOptions, 'timeoutMs' | 'memory' | 'cpus' | 'pidsLimit'>;
+export {};

package/dist/executor/sandbox.js

@@ -0,0 +1,231 @@
+import { realpath, stat } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { defaultExec } from '../detect.js';
+/**
+ * Docker sandbox for the B.2 probe lane — the security boundary around
+ * executing PR-contributed probe code on the consumer's runner.
+ *
+ * Invariants (KTD2 / R4): no ambient env, no network, read-only root,
+ * non-root, all capabilities dropped, no-new-privileges, resource + PID
+ * limits, `.git` masked inside the container, exactly one writable bind
+ * mount (the probes scratch dir), and a wall-clock timeout enforced by
+ * daemon-side `docker rm -f` — killing the `docker` CLI alone does not
+ * guarantee the container dies when its PID 1 traps the forwarded signal.
+ */
+/** Output cap per stream — probe output is attacker-controlled. */
+export const SANDBOX_OUTPUT_CAP = 32 * 1024;
+/** Filesystem path inside the container where the workspace lands. */
+export const CONTAINER_WORKDIR = '/work';
+/** Name of the single writable mount — lives under reportDir/probes-out. */
+export const SCRATCH_DIR_NAME = 'probes-out';
+/** Strict C0/control-byte strip — applied before output leaves the module. */
+export function stripControlChars(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+}
+/**
+ * Resolve the probe image: an explicit `sandbox.image` always wins;
+ * otherwise pin to the host's own Node major so native `node_modules`
+ * (ABI-bound to the installing Node) load inside the container.
+ */
+export function resolveSandboxImage(image) {
+    return image ?? `node:${process.versions.node.split('.')[0]}-slim`;
+}
+/**
+ * Filesystem safety check before any `docker run`: the scratch dir must
+ * realpath-resolve to a strict descendant of the real workdir. Rejects a
+ * reportDir symlinked out of the tree or configured outside the checkout —
+ * both would turn the rw bind-mount into a write primitive on the host.
+ */
+export async function checkSandboxPaths(workdir, scratchDir) {
+    try {
+        const realWork = await realpath(resolve(workdir));
+        const realScratch = await realpath(resolve(scratchDir));
+        const rel = relative(realWork, realScratch);
+        if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+            return { ok: false, reason: `scratch dir ${scratchDir} is not inside ${workdir}` };
+        }
+        return { ok: true, realWork, realScratch, relMount: rel };
+    }
+    catch (e) {
+        return { ok: false, reason: `path check failed: ${e.message}` };
+    }
+}
+/**
+ * Docker is usable AND resolves the runner's workspace path — bind-mount
+ * sources are evaluated by the daemon, so a remote/containerized daemon can
+ * silently mount an empty dir. The smoke run uses the SAME hardening
+ * profile as probe runs (plus `--pull always` and an entrypoint override) —
+ * an availability check that ran the image unhardened would bypass every
+ * invariant this module exists to enforce.
+ */
+export async function dockerAvailable(exec, image, workdir) {
+    const name = containerName('avail');
+    let probe;
+    try {
+        const version = await exec('docker', ['version', '--format', '{{.Server.Version}}'], 10_000);
+        if (version.code !== 0)
+            return false;
+        probe = await exec('docker', [
+            'run',
+            '--rm',
+            '--name',
+            name,
+            '--pull',
+            'always',
+            '--network',
+            'none',
+            '--read-only',
+            '--cap-drop',
+            'ALL',
+            '--security-opt',
+            'no-new-privileges',
+            '--user',
+            '65534:65534',
+            '--entrypoint',
+            'test',
+            '-v',
+            `${workdir}:${CONTAINER_WORKDIR}:ro`,
+            image,
+            '-d',
+            CONTAINER_WORKDIR,
+        ], 
+        // Cold-pull headroom: on a daemon that has never seen the image,
+        // `--pull always` downloads it inside this call — 60s under-runs a
+        // first pull and falsely reports docker as unusable.
+        300_000);
+    }
+    catch {
+        // Spawn failure (no docker binary, daemon gone) → unavailable, and the
+        // named container may still be half-created — remove it best-effort.
+        await forceRemove(exec, name);
+        return false;
+    }
+    if (probe.timedOut === true)
+        await forceRemove(exec, name);
+    return probe.code === 0;
+}
+/**
+ * Container name — shared by `docker run --name` and the `rm -f` teardown.
+ * Includes the pid so two concurrent review jobs on one daemon can't
+ * collide names (or force-remove each other's containers).
+ */
+function containerName(name) {
+    return `argus-probe-${process.pid}-${name}`;
+}
+/**
+ * The full `docker run` argv (KTD2). Every flag is pinned here — this is the
+ * single place the sandbox boundary lives. `name` is the full container name.
+ */
+export function buildSandboxArgv(opts, name, checked, gitMode, secretFiles) {
+    const argv = [
+        'run',
+        '--rm',
+        '--name',
+        name,
+        // Mutable tags on a persistent runner can be poisoned by earlier jobs —
+        // always resolve from the registry (daemon-side network; the container
+        // itself stays offline).
+        '--pull',
+        'always',
+        '--network',
+        'none',
+        '--read-only',
+        '--cap-drop',
+        'ALL',
+        '--security-opt',
+        'no-new-privileges',
+        '--user',
+        '65534:65534',
+        '--pids-limit',
+        String(opts.pidsLimit),
+        '--memory',
+        opts.memory,
+        '--cpus',
+        opts.cpus,
+        '--tmpfs',
+        '/tmp:rw,nosuid,nodev,noexec',
+        '-v',
+        `${checked.realWork}:${CONTAINER_WORKDIR}:ro`,
+    ];
+    // Shadow .git — actions/checkout persists a base64 GITHUB_TOKEN in
+    // .git/config; PR code must not read it. tmpfs masks a *directory*; a
+    // worktree's `.git` pointer file (or any root-level secret file staged by
+    // earlier steps) is masked with a read-only /dev/null bind.
+    if (gitMode === 'dir')
+        argv.push('--tmpfs', `${CONTAINER_WORKDIR}/.git`);
+    for (const f of gitMode === 'file' ? ['.git', ...secretFiles] : secretFiles) {
+        argv.push('-v', `/dev/null:${CONTAINER_WORKDIR}/${f}:ro`);
+    }
+    for (const mask of opts.masks ?? [])
+        argv.push('--tmpfs', `${CONTAINER_WORKDIR}/${mask}`);
+    for (const m of opts.roMounts ?? [])
+        argv.push('-v', `${m.host}:${m.container}:ro`);
+    argv.push('-v', `${checked.realScratch}:${CONTAINER_WORKDIR}/${checked.relMount}:rw`, '-w', CONTAINER_WORKDIR, 
+    // Declared env allowlist only — no host env is inherited. HOME=/tmp
+    // because `nobody`'s passwd home is /nonexistent on a read-only root.
+    '--env', 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', '--env', 'HOME=/tmp', '--env', 'npm_config_cache=/tmp/.npm', opts.image, ...opts.cmd);
+    return argv;
+}
+/** Daemon-side kill — the non-ignorable half of the R4 wall-clock bound. */
+async function forceRemove(exec, name) {
+    await exec('docker', ['rm', '-f', name], 15_000).catch(() => undefined);
+}
+/**
+ * Run one command in the hardened container. On timeout the docker client
+ * is killed first, then `docker rm -f` guarantees teardown — SIGKILL via
+ * the daemon is non-ignorable, which is what makes the R4 wall-clock bound
+ * real. Path-check and spawn failures return a `exitCode: -1` result
+ * carrying the reason; this function never throws past its callers.
+ */
+/** Workspace-root files that commonly carry credentials — masked when present. */
+const SECRET_FILE_NAMES = ['.env', '.npmrc', '.netrc', '.git-credentials'];
+export async function runProbeInSandbox(opts) {
+    const exec = opts.exec ?? defaultExec;
+    const checked = await checkSandboxPaths(opts.workdir, opts.scratchDir);
+    if (!checked.ok) {
+        return { exitCode: -1, stdout: '', stderr: checked.reason, durationMs: 0, timedOut: false };
+    }
+    const gitStat = await stat(join(checked.realWork, '.git')).catch(() => undefined);
+    const gitMode = gitStat === undefined ? 'absent' : gitStat.isDirectory() ? 'dir' : 'file';
+    const secretFiles = (await Promise.all(SECRET_FILE_NAMES.map(async (f) => (await stat(join(checked.realWork, f)).catch(() => undefined))?.isFile() === true
+        ? f
+        : undefined))).filter((f) => f !== undefined);
+    const name = containerName(opts.name);
+    const argv = buildSandboxArgv(opts, name, checked, gitMode, secretFiles);
+    const started = Date.now();
+    let res;
+    try {
+        res = await exec('docker', argv, opts.timeoutMs);
+    }
+    catch (e) {
+        await forceRemove(exec, name);
+        return {
+            exitCode: -1,
+            stdout: '',
+            stderr: e.message,
+            durationMs: Date.now() - started,
+            timedOut: false,
+        };
+    }
+    const durationMs = Date.now() - started;
+    if (res.timedOut === true) {
+        await forceRemove(exec, name);
+    }
+    return {
+        exitCode: res.code,
+        stdout: stripControlChars(res.stdout).slice(0, SANDBOX_OUTPUT_CAP),
+        stderr: stripControlChars(res.stderr).slice(0, SANDBOX_OUTPUT_CAP),
+        durationMs,
+        timedOut: res.timedOut === true,
+    };
+}
+/** Limits convenience — what `runProbeInSandbox` needs from config.sandbox. */
+export function sandboxLimits(sandbox) {
+    return {
+        timeoutMs: sandbox.timeoutMs,
+        memory: sandbox.memory,
+        cpus: sandbox.cpus,
+        pidsLimit: sandbox.pidsLimit,
+    };
+}

package/dist/probe/author.d.ts

@@ -0,0 +1,50 @@
+import type { JsonSchema, Message } from '../vision/openrouter.js';
+import type { Harness } from './harness.js';
+/**
+ * Probe authoring (KTD7): one bounded model call per `not_exercised`
+ * finding produces a single test file asserting the *correct* behavior —
+ * so the defect's presence fails the test on head while the base checkout
+ * passes. The file is written on the HOST (inside the ro workspace mount),
+ * so `filename` and `content` are validated hard: the model's input includes
+ * PR-controlled file contents, and a prompt-injected traversal or secret
+ * read would escape the sandbox's whole purpose.
+ */
+export declare const PROBE_SCHEMA: JsonSchema;
+export interface ProbeTarget {
+    file?: string | undefined;
+    line?: number | undefined;
+    severity: string;
+    message: string;
+}
+export interface AuthoredProbe {
+    filename: string;
+    content: string;
+    reasoning: string;
+    /** Import specifiers extracted at parse time — checked against the write path in the queue. */
+    imports: string[];
+}
+export type ProbeParseResult = {
+    ok: true;
+    probe: AuthoredProbe;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Basename-only, forced test extension — no separators, no `..`. The write
+ * happens on the host, so this is the traversal boundary.
+ */
+export declare const PROBE_FILENAME_RE: RegExp;
+/** Probe files are bounded — a runaway generation is rejected, not truncated. */
+export declare const PROBE_CONTENT_CAP: number;
+export declare function parseProbe(raw: string): ProbeParseResult;
+/**
+ * Verify every relative import in a probe resolves inside the repo, given
+ * the probe's repo-relative write path. `../../etc/passwd` from a shallow
+ * dir escapes the checkout — reject.
+ */
+export declare function probeImportsSafe(probe: AuthoredProbe, relProbePath: string): boolean;
+export declare function buildProbeMessages(target: ProbeTarget, fileContents: string | undefined, exemplarTest: {
+    path: string;
+    content: string;
+} | undefined, harness: Harness): Message[];