argus-reviewer-e2e 0.1.2 → 0.2.0

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[];

package/dist/probe/author.js

@@ -0,0 +1,149 @@
+import { posix } from 'node:path';
+import ts from 'typescript';
+/**
+ * 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 const PROBE_SCHEMA = {
+    name: 'argus-probe',
+    strict: true,
+    schema: {
+        type: 'object',
+        properties: {
+            filename: {
+                type: 'string',
+                description: 'Bare test filename matching the repo convention, e.g. probe-xyz.test.ts',
+            },
+            content: { type: 'string', description: 'Complete test file contents' },
+            reasoning: { type: 'string' },
+        },
+        required: ['filename', 'content', 'reasoning'],
+        additionalProperties: false,
+    },
+};
+/**
+ * Basename-only, forced test extension — no separators, no `..`. The write
+ * happens on the host, so this is the traversal boundary.
+ */
+export const PROBE_FILENAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]*\.test\.[jt]sx?$/;
+/** Probe files are bounded — a runaway generation is rejected, not truncated. */
+export const PROBE_CONTENT_CAP = 32 * 1024;
+/** Reads of secret-looking env vars are forbidden — defense in depth on the stripped container env. */
+const SECRET_ENV_RE = /process\.env\s*(?:\.|\[)\s*['"]?\w*(KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL)/i;
+/**
+ * Import specifiers via the TypeScript scanner (same seam as the index) —
+ * a regex misses bare side-effect imports like `import '/abs/x'`. Returns
+ * undefined when the scanner itself fails — fail closed, never silently
+ * skip the import check.
+ */
+function importSpecifiers(content) {
+    try {
+        const info = ts.preProcessFile(content, true, true);
+        return [...info.importedFiles, ...info.referencedFiles].map((f) => f.fileName);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseProbe(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, reason: 'unparseable model response' };
+    }
+    if (typeof parsed.filename !== 'string' || !PROBE_FILENAME_RE.test(parsed.filename)) {
+        return { ok: false, reason: `unsafe filename: ${String(parsed.filename)}` };
+    }
+    if (typeof parsed.content !== 'string' || parsed.content.trim() === '') {
+        return { ok: false, reason: 'missing or empty content' };
+    }
+    if (parsed.content.length > PROBE_CONTENT_CAP) {
+        return { ok: false, reason: `content exceeds ${PROBE_CONTENT_CAP} bytes` };
+    }
+    if (SECRET_ENV_RE.test(parsed.content)) {
+        return { ok: false, reason: 'probe reads secret-looking env vars' };
+    }
+    const imports = importSpecifiers(parsed.content);
+    if (imports === undefined) {
+        return { ok: false, reason: 'probe content failed import scanning' };
+    }
+    for (const spec of imports) {
+        // Reject anything that isn't a bare specifier or plain relative path:
+        // absolute paths, drive letters, UNC, and scheme-prefixed specifiers
+        // (`file:///etc/passwd` is a host read, `data:` smuggles a module).
+        // `node:` builtins stay allowed — node-test probes need `node:test`.
+        if (spec.startsWith('/') ||
+            /^[a-zA-Z]:/.test(spec) ||
+            spec.startsWith('\\\\') ||
+            (/^[a-z][a-z0-9+.-]*:/i.test(spec) && !spec.startsWith('node:'))) {
+            return { ok: false, reason: `unsafe import: ${spec}` };
+        }
+    }
+    return {
+        ok: true,
+        probe: {
+            filename: parsed.filename,
+            content: parsed.content,
+            reasoning: typeof parsed.reasoning === 'string' ? parsed.reasoning : '',
+            imports,
+        },
+    };
+}
+/**
+ * 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 function probeImportsSafe(probe, relProbePath) {
+    // Repo-relative paths are always `/`-separated — compute in posix so a
+    // Windows host can't turn `../x` into `..\x` and slip the `../` check.
+    const dir = posix.dirname(relProbePath);
+    return probe.imports.every((spec) => {
+        if (!spec.startsWith('.'))
+            return true; // bare package specifier — resolved from node_modules
+        const resolved = posix.normalize(posix.join(dir, spec));
+        return resolved !== '..' && !resolved.startsWith('../') && !posix.isAbsolute(resolved);
+    });
+}
+export function buildProbeMessages(target, fileContents, exemplarTest, harness) {
+    const exemplar = exemplarTest === undefined
+        ? '(no existing test file was available as an exemplar — follow standard idiom)'
+        : `Exemplar test file (${exemplarTest.path}) — match its imports, naming, and assertion style:\n\n${exemplarTest.content}`;
+    const implicated = fileContents === undefined
+        ? `(file contents unavailable; the finding references ${target.file ?? 'unknown'})`
+        : `Contents of ${target.file}:\n\n${fileContents}`;
+    return [
+        {
+            role: 'system',
+            content: [
+                {
+                    type: 'text',
+                    text: `You author a single failing test — a "probe" — that reproduces a suspected defect ` +
+                        `found by code review. The probe runs under ${harness.kind} in an offline sandbox. ` +
+                        `Write a self-contained ${harness.kind} test that asserts the CORRECT behavior: if the ` +
+                        `defect is real, the test fails; if the code is fine, it passes. Import only repo ` +
+                        `modules via relative paths and packages the repo already uses. No network, no ` +
+                        `filesystem outside the repo, no timers, no process.env reads. filename must be a ` +
+                        `bare filename ending in .test.ts/.test.js matching the exemplar's convention.`,
+                },
+            ],
+        },
+        {
+            role: 'user',
+            content: [
+                {
+                    type: 'text',
+                    text: `Finding (${target.severity}) in ${target.file ?? 'unknown'}${target.line ? `:${target.line}` : ''}:\n` +
+                        `${target.message}\n\n${implicated}\n\n${exemplar}`,
+                },
+            ],
+        },
+    ];
+}

package/dist/probe/harness.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Test-harness detection + result classification for the B.2 probe lane
+ * (KTD3). v1 is deliberately Node-only: vitest, jest, and `node --test`.
+ *
+ * Two implementation details carry the weight:
+ *  - Positional file args are *filters* intersected with the consumer's
+ *    configured include/testMatch/roots, so probes must live where the
+ *    runner already looks (the queue writes them beside an exemplar test).
+ *  - Invocations bypass `npx` — as `nobody` on a read-only root there is no
+ *    writable HOME, so the installed binary is invoked directly and each
+ *    runner's cache is redirected into the /tmp tmpfs.
+ */
+export type ProbeOutcome = 'failed-test' | 'load-error' | 'not-collected' | 'clean';
+export interface Harness {
+    kind: 'vitest' | 'jest' | 'node-test';
+    /** In-container argv running exactly one probe file (path relative to /work). */
+    runCmd(probeRelPath: string): string[];
+    /** Map captured output to the report vocabulary. */
+    classify(res: {
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }): ProbeOutcome;
+}
+/**
+ * Detect the consumer's test harness from package.json. Returns undefined
+ * when no supported harness exists — the probe lane degrades to a detail
+ * note, not a failure.
+ */
+export declare function detectHarness(cwd: string): Promise<Harness | undefined>;