argus-reviewer-e2e 0.3.1 → 0.4.0

package/dist/pipeline/app.js

@@ -0,0 +1,250 @@
+import { BrowserDriver as launchBrowserDriver } from '../driver/browser.js';
+import { TargetProcess, waitForReady } from '../driver/target.js';
+import { Actions } from '../engine/actions.js';
+import { runExplore, } from '../engine/explore.js';
+import { Ledger } from '../vision/ledger.js';
+/** Lane detail file the app runner writes and `runVerify` reads back. */
+export const APP_LANE_REPORT = 'app-lane.json';
+/** Wall-clock bound when config.app.timeoutMs is unset. */
+export const APP_LANE_DEFAULT_TIMEOUT_MS = 120_000;
+/** Reachability preflight bound — short enough to fail fast on dead targets. */
+const APP_PREFLIGHT_TIMEOUT_MS = 10_000;
+/**
+ * Compile the configured expected state into one AND-ed predicate. An
+ * invalid url regex throws here — caught at preflight so a broken marker
+ * blocks the lane instead of failing mid-run.
+ */
+export function buildExpectationCheck(expected) {
+    const parts = [];
+    if (expected.text !== undefined) {
+        const needle = expected.text.toLowerCase();
+        parts.push({
+            describe: `text "${expected.text}"`,
+            test: async (ctx) => ctx.observation.a11yYaml.toLowerCase().includes(needle),
+        });
+    }
+    if (expected.url !== undefined) {
+        const re = new RegExp(expected.url);
+        parts.push({ describe: `url /${expected.url}/`, test: async (ctx) => re.test(ctx.url) });
+    }
+    if (expected.selector !== undefined) {
+        const selector = expected.selector;
+        parts.push({
+            describe: `selector "${selector}"`,
+            test: async (ctx) => (await ctx.page.locator(selector).count()) > 0,
+        });
+    }
+    return {
+        describe: parts.map((p) => p.describe).join(' AND '),
+        check: async (ctx) => {
+            for (const part of parts) {
+                if (!(await part.test(ctx)))
+                    return false;
+            }
+            return parts.length > 0;
+        },
+    };
+}
+/**
+ * The bounded task loop: ExploreLoop substrate + task + expectation +
+ * wall-clock deadline. The lane — not the model's `done` — decides pass:
+ * the expected-state predicate is re-verified on a fresh observation after
+ * the loop stops, so a page that merely loads can never pass.
+ */
+export async function runAppTask(input) {
+    const expectation = buildExpectationCheck(input.expected);
+    const result = await runExplore({
+        driver: input.driver,
+        actions: input.actions,
+        client: input.client,
+        ledger: input.ledger,
+        config: input.config,
+        targetUrl: input.targetUrl,
+        task: input.task,
+        deadlineAt: Date.now() + input.timeoutMs,
+        expectation: (ctx) => expectation.check(ctx),
+        ...(input.maxSteps !== undefined ? { maxSteps: input.maxSteps } : {}),
+        ...(input.budgetLimitUsd !== undefined ? { budgetUsd: input.budgetLimitUsd } : {}),
+        ...(input.logger !== undefined ? { logger: input.logger } : {}),
+    });
+    // Mid-loop 'expectation' already verified on a real observation — no
+    // second screenshot. Every other stop re-verifies against fresh state.
+    let expectedMet = result.stopReason === 'expectation';
+    let verifyError;
+    if (!expectedMet) {
+        try {
+            const observation = await input.driver.observe({ grid: true });
+            expectedMet = await expectation.check({
+                observation,
+                url: input.driver.rawPage.url(),
+                page: input.driver.rawPage,
+            });
+        }
+        catch (e) {
+            verifyError = e.message;
+        }
+    }
+    return { result, expectedMet, verifyError };
+}
+/**
+ * Full `verify --app` lifecycle: contract preflight → trust/reachability →
+ * bounded task loop → lane record. Every status path produces a report —
+ * the lane can fail loudly, never silently.
+ */
+export async function runAppLane(input) {
+    const started = Date.now();
+    const config = input.config;
+    const deps = input.deps ?? {};
+    const task = input.task ?? config.app.task;
+    const expected = input.expected ?? config.app.expected;
+    const targetUrl = input.url ?? config.target?.url;
+    const base = {
+        lane: 'app',
+        task,
+        expected,
+        targetUrl,
+        finalUrl: undefined,
+        expectedMet: false,
+        stopReason: undefined,
+        steps: [],
+        visited: 0,
+        anomalies: [],
+        notes: [],
+        artifacts: { video: undefined },
+        calls: [],
+        visionCalls: 0,
+        visionCostUsd: 0,
+        durationMs: 0,
+        model: config.model,
+    };
+    const done = (status, reason, summary, extra) => ({
+        ...base,
+        ...extra,
+        status,
+        reason,
+        summary: summary ?? (status === 'passed' ? 'task verified' : reason),
+        durationMs: Date.now() - started,
+    });
+    // Executable lanes are gated on the same trust resolution as config
+    // loading (SECURITY.md): an untrusted checkout never reaches the task,
+    // the browser, or a PR-controlled expectation — blocked before any
+    // preflight, not just before `target.command`.
+    if (!input.trusted) {
+        return done('blocked', 'verify --app is an executable lane — requires a trusted checkout');
+    }
+    // Contract preflight — a lane without a task or a verifiable marker
+    // blocks before touching the network or the provider (R8).
+    if (task === undefined || task.trim() === '') {
+        return done('blocked', 'no task configured — set app.task or pass --task');
+    }
+    if (expected === undefined) {
+        return done('blocked', 'app lane needs an expected-state marker (app.expected.text/url/selector or --expect-*) — page load alone cannot pass a task');
+    }
+    try {
+        buildExpectationCheck(expected);
+    }
+    catch (e) {
+        return done('blocked', `invalid expected-state marker: ${e.message}`);
+    }
+    if (targetUrl === undefined || targetUrl === '') {
+        return done('blocked', 'no application target configured; set target.url or pass --url');
+    }
+    let target;
+    let driver;
+    try {
+        if (config.target?.command !== undefined && config.target.command !== '') {
+            const start = deps.startTarget ?? ((spec) => TargetProcess.start(spec));
+            try {
+                target = await start(config.target);
+            }
+            catch (e) {
+                return done('unavailable', `target command failed to boot: ${e.message}`);
+            }
+        }
+        else {
+            // No boot command — the target must already serve. Probe before any
+            // model call so an unreachable app costs zero provider spend.
+            const ready = deps.waitForReady ?? waitForReady;
+            try {
+                await ready(targetUrl, config.target?.readyTimeoutMs ?? APP_PREFLIGHT_TIMEOUT_MS);
+            }
+            catch (e) {
+                return done('unavailable', `target unreachable before any model call: ${e.message}`);
+            }
+        }
+        const launch = deps.launchDriver ??
+            ((cfg) => 
+            // The lane's evidence contract needs anomaly taps regardless of the
+            // observe-only explore toggle.
+            launchBrowserDriver.launch({
+                browser: cfg.browser,
+                browserTimeoutMs: cfg.browserTimeoutMs,
+                captureErrors: true,
+            }));
+        try {
+            driver = await launch(config);
+        }
+        catch (e) {
+            return done('unavailable', `browser failed to launch: ${e.message}`);
+        }
+        if (deps.applyPageSetup !== undefined)
+            await deps.applyPageSetup(driver);
+        try {
+            await driver.goto(targetUrl);
+        }
+        catch (e) {
+            return done('unavailable', `target navigation failed: ${e.message}`);
+        }
+        const ledger = new Ledger(input.budgetLimitUsd ?? config.app.budgetUsd ?? config.budgetUsd);
+        const client = deps.createClient?.(config) ?? missingClient();
+        const { result, expectedMet, verifyError } = await runAppTask({
+            driver,
+            actions: new Actions(driver),
+            client,
+            ledger,
+            config,
+            targetUrl,
+            task,
+            expected,
+            timeoutMs: config.app.timeoutMs ?? APP_LANE_DEFAULT_TIMEOUT_MS,
+            maxSteps: config.app.maxSteps,
+            budgetLimitUsd: input.budgetLimitUsd ?? config.app.budgetUsd ?? config.budgetUsd,
+            logger: deps.logger,
+        });
+        // Captures + video must be lifted before close() — the taps and the
+        // webm path die with the context.
+        const anomalies = driver.pageCaptures();
+        const video = await driver.close();
+        driver = undefined;
+        const summary = expectedMet
+            ? `expected state verified (${result.steps.length} steps, ${result.visited} page(s))`
+            : `expected state unmet after ${result.stopReason} (${result.steps.length} steps)`;
+        return done(expectedMet ? 'passed' : verifyError !== undefined ? 'inconclusive' : 'failed', expectedMet
+            ? undefined
+            : verifyError !== undefined
+                ? `expected-state verification failed: ${verifyError}`
+                : `task did not reach its expected state — stopped on ${result.stopReason}`, summary, {
+            finalUrl: result.finalUrl,
+            expectedMet,
+            stopReason: result.stopReason,
+            steps: result.steps,
+            visited: result.visited,
+            anomalies,
+            notes: result.notes,
+            artifacts: { video },
+            calls: ledger.calls,
+            visionCalls: result.visionCalls,
+            visionCostUsd: result.visionCostUsd,
+        });
+    }
+    finally {
+        await driver?.close().catch(() => undefined);
+        await target?.stop().catch(() => undefined);
+    }
+}
+/** Default client when the caller supplies none — fails loudly on first call. */
+function missingClient() {
+    return {
+        complete: () => Promise.reject(new Error('no vision client wired into the app lane')),
+    };
+}

package/dist/pipeline/budget.d.ts

@@ -6,6 +6,7 @@ export interface BudgetOptions {
     maxTasks?: number;
 }
 export declare function createBudget(lane: LaneId, options?: BudgetOptions): BudgetSummary;
+export declare function overLimit(spentUsd: number, limitUsd: number): boolean;
 export declare function addProviderCalls(budget: BudgetSummary, calls: CallCost[] | undefined): BudgetSummary;
 export declare function addA0Task(budget: BudgetSummary, elapsedMs: number, metered: boolean): BudgetSummary;
 export declare function budgetCanSpend(budget: BudgetSummary, nextCostUsd: number): boolean;

package/dist/pipeline/budget.js

@@ -17,7 +17,7 @@ export function createBudget(lane, options = {}) {
  * far below the 1e-6 precision reports render, and far above double noise here.
  */
 const USD_EPSILON = 1e-9;
-function overLimit(spentUsd, limitUsd) {
+export function overLimit(spentUsd, limitUsd) {
     return spentUsd > limitUsd + USD_EPSILON;
 }
 export function addProviderCalls(budget, calls) {

package/dist/pipeline/verify.d.ts

@@ -1,6 +1,6 @@
 import { type LaneId, type RunIdentity, type RunManifest } from '../report/manifest.js';
 import { type BudgetOptions } from './budget.js';
-import { type LaneSelection } from './contracts.js';
+import type { LaneSelection } from './contracts.js';
 export interface VerifyRunners {
     review: () => Promise<number>;
     flow?: (url: string) => Promise<number>;
@@ -22,6 +22,23 @@ export interface VerifyResult {
     manifest: RunManifest;
     exitCode: number;
 }
-/** Run selected lanes and return one stable manifest without owning subprocesses. */
+/**
+ * Run selected lanes and return one stable manifest without owning
+ * subprocesses. Lanes run sequentially on purpose: flow/app can both boot
+ * `target.command` (port collision) and serial execution keeps budget
+ * accounting and lane timing honest — each lane's startedAt is its own
+ * start, not the run's.
+ */
 export declare function runVerify(input: VerifyInput): Promise<VerifyResult>;
-export declare function selectedManifestLanes(selection: LaneSelection): LaneId[];
+/** Package version for report footers; dist/ and src/ both sit two levels deep. */
+export declare function argusVersion(): string;
+/**
+ * Write the offline HTML evidence report (U14) beside run-manifest.json.
+ * Lane reports are read only when the manifest points at them: a runner that
+ * threw leaves `reportPath` unset, and its stale file must not reach the
+ * report (same contract as the manifest's own reads).
+ */
+export declare function writeEvidenceReport(reportDir: string, manifest: RunManifest, meta?: {
+    version?: string;
+    runUrl?: string;
+}): Promise<string>;

package/dist/pipeline/verify.js

@@ -1,8 +1,10 @@
 import { readFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
 import { join, relative } from 'node:path';
-import { aggregateLanes, addProviderUsage, emptyLane, emptyUsage, isHeadBindingConclusive, MANIFEST_SCHEMA_VERSION, } from '../report/manifest.js';
-import { addProviderCalls, createBudget } from './budget.js';
-import { selectedLanes } from './contracts.js';
+import { writeAtomicText } from '../fsutil.js';
+import { renderReportHtml, REPORT_HTML } from '../report/html.js';
+import { aggregateLanes, addProviderUsage, emptyLane, emptyUsage, isHeadBindingConclusive, LANE_IDS, LANE_STATUSES, MANIFEST_SCHEMA_VERSION, } from '../report/manifest.js';
+import { addProviderCalls, createBudget, overLimit, } from './budget.js';
 async function readJson(path) {
     try {
         return JSON.parse(await readFile(path, 'utf8'));
@@ -39,15 +41,42 @@ function flowCalls(report) {
 function flowUsage(report) {
     const calls = flowCalls(report);
     const usage = providerUsageFromCalls(calls);
-    if (report?.totals !== undefined && calls.length === 0) {
-        return {
-            ...usage,
-            calls: report.totals.visionCalls ?? 0,
-            tokens: 0,
-            costUsd: report.totals.visionCostUsd ?? 0,
-        };
-    }
-    return usage;
+    const totals = report?.totals;
+    if (totals === undefined)
+        return usage;
+    // totals are the authoritative rollup — they fold in lane-level calls the
+    // per-test reports never own (e.g. the explore pass). visionTokens is the
+    // same rollup for tokens; older run.json files lack it and fall back to
+    // the per-test call records.
+    return {
+        ...usage,
+        calls: totals.visionCalls ?? usage.calls,
+        costUsd: totals.visionCostUsd ?? usage.costUsd,
+        tokens: totals.visionTokens ?? usage.tokens,
+    };
+}
+function flowCache(report) {
+    const totals = report?.totals;
+    if (totals === undefined)
+        return undefined;
+    return {
+        hits: totals.cacheHits ?? 0,
+        misses: totals.cacheMisses ?? 0,
+        heals: totals.cacheHeals ?? 0,
+        staleEntries: totals.staleEntries ?? 0,
+        assertionHits: totals.assertionHits ?? 0,
+        assertionMisses: totals.assertionMisses ?? 0,
+    };
+}
+/** A green `ok` is only evidence when a test executed or the explore lane
+ * actually ran as the evidence source — an enabled-but-skipped/errored
+ * explore pass proves nothing, so the lane must still fail closed. */
+function flowEvidenceRan(report) {
+    if (report === undefined)
+        return false;
+    if (report.explore?.enabled === true && report.explore.skipped === undefined)
+        return true;
+    return (report.totals?.tests ?? report.tests?.length ?? 0) > 0;
 }
 function budgetFor(lane, input, report) {
     const options = input.budgets?.[lane] ?? {};
@@ -56,23 +85,75 @@ function budgetFor(lane, input, report) {
         budget = addProviderCalls(budget, report?.calls);
     }
     else if (lane === 'flow') {
-        budget = addProviderCalls(budget, flowCalls(report));
+        const flowReport = report;
+        budget = addProviderCalls(budget, flowCalls(flowReport));
+        // totals fold in lane-level calls the per-test reports never own (the
+        // explore pass) — the budget must count the same spend usage reports.
+        const totalUsd = flowReport?.totals?.visionCostUsd;
+        if (totalUsd !== undefined && totalUsd > budget.spentUsd) {
+            budget = {
+                ...budget,
+                spentUsd: totalUsd,
+                exceeded: budget.exceeded ||
+                    (budget.limitUsd !== undefined && overLimit(totalUsd, budget.limitUsd)),
+            };
+        }
     }
     return budget;
 }
 function baseLane(lane, selected) {
     return emptyLane(lane, selected);
 }
-/** Run selected lanes and return one stable manifest without owning subprocesses. */
+/**
+ * Usage from a runner's lane-detail file. Per-call records are authoritative
+ * for tokens/model; `visionCalls`/`visionCostUsd` scalars cover runners that
+ * only know totals. An `a0` host without usage telemetry reports
+ * `metered: false` — never a fabricated dollar amount (R13).
+ */
+function laneDetailUsage(lane, detail) {
+    const provider = lane === 'a0' ? 'a0' : 'openrouter';
+    const base = addProviderUsage(emptyUsage(provider), detail?.calls);
+    return {
+        ...base,
+        provider,
+        model: detail?.model ?? base.model,
+        calls: detail?.calls === undefined ? (detail?.visionCalls ?? base.calls) : base.calls,
+        costUsd: detail?.calls === undefined ? (detail?.visionCostUsd ?? base.costUsd) : base.costUsd,
+        metered: lane === 'a0' ? detail?.metered === true : base.metered,
+    };
+}
+/**
+ * Lane budget from options plus what the runner's detail actually consumed —
+ * provider calls, delegated tasks, and elapsed wall-clock each count against
+ * their configured bound.
+ */
+function laneDetailBudget(lane, input, detail) {
+    let budget = addProviderCalls(createBudget(lane, input.budgets?.[lane] ?? {}), detail?.calls);
+    const tasks = detail?.tasks ?? 0;
+    const elapsedMs = detail?.durationMs ?? 0;
+    const exceeded = budget.exceeded ||
+        (budget.maxTasks !== undefined && tasks > budget.maxTasks) ||
+        (budget.maxDurationMs !== undefined && elapsedMs > budget.maxDurationMs) ||
+        (budget.limitUsd !== undefined &&
+            detail?.calls === undefined &&
+            detail?.visionCostUsd !== undefined &&
+            overLimit(detail.visionCostUsd, budget.limitUsd));
+    budget = { ...budget, tasks, elapsedMs, exceeded };
+    return budget;
+}
+/**
+ * Run selected lanes and return one stable manifest without owning
+ * subprocesses. Lanes run sequentially on purpose: flow/app can both boot
+ * `target.command` (port collision) and serial execution keeps budget
+ * accounting and lane timing honest — each lane's startedAt is its own
+ * start, not the run's.
+ */
 export async function runVerify(input) {
     const startedAt = new Date();
-    const lanes = Object.fromEntries(['review', 'flow', 'app', 'a0'].map((lane) => [
-        lane,
-        baseLane(lane, input.selection[lane]),
-    ]));
+    const lanes = Object.fromEntries(LANE_IDS.map((lane) => [lane, baseLane(lane, input.selection[lane])]));
     const reviewSelected = input.selection.review;
     if (reviewSelected) {
-        lanes.review = laneStart(lanes.review, startedAt);
+        lanes.review = laneStart(lanes.review);
         let code = 1;
         let runnerError;
         try {
@@ -82,7 +163,12 @@ export async function runVerify(input) {
             runnerError = error instanceof Error ? error.message : String(error);
             ctxError(runnerError);
         }
-        const report = await readJson(join(input.reportDir, 'code-review.json'));
+        // A runner that threw before writing leaves a stale report behind —
+        // ignore it or the manifest inherits another run's usage, head binding,
+        // and evidence links (same contract as the <lane>-lane.json guard).
+        const report = runnerError === undefined
+            ? await readJson(join(input.reportDir, 'code-review.json'))
+            : undefined;
         const inconclusive = report !== undefined &&
             report.skipped !== true &&
             !isHeadBindingConclusive(report.headBinding);
@@ -107,7 +193,7 @@ export async function runVerify(input) {
         });
     }
     if (input.selection.flow) {
-        lanes.flow = laneStart(lanes.flow, startedAt);
+        lanes.flow = laneStart(lanes.flow);
         if (input.runners.flow === undefined) {
             lanes.flow = laneEnd({
                 ...lanes.flow,
@@ -132,20 +218,36 @@ export async function runVerify(input) {
                 runnerError = error instanceof Error ? error.message : String(error);
                 ctxError(runnerError);
             }
-            const report = await readJson(join(input.reportDir, 'run.json'));
+            const report = runnerError === undefined
+                ? await readJson(join(input.reportDir, 'run.json'))
+                : undefined;
+            // A run.json claiming ok with zero executed tests carries no evidence —
+            // fail closed instead of letting it pass the lane.
+            const noEvidence = report !== undefined && report.ok === true && code === 0 && !flowEvidenceRan(report);
             lanes.flow = laneEnd({
                 ...lanes.flow,
-                status: runnerError !== undefined ? 'failed' : reportStatus(code, report, false),
+                status: runnerError !== undefined || noEvidence
+                    ? 'failed'
+                    : reportStatus(code, report, false),
                 reportPath: report === undefined ? undefined : relativeReport(input.cwd, input.reportDir, 'run.json'),
-                summary: report === undefined ? undefined : report.ok === true ? 'flow passed' : 'flow failed',
-                reason: runnerError ??
-                    (report === undefined
-                        ? 'run.json was not produced'
+                summary: report === undefined
+                    ? undefined
+                    : noEvidence
+                        ? 'flow ran zero tests'
                         : report.ok === true
-                            ? undefined
-                            : 'flow failed'),
+                            ? 'flow passed'
+                            : 'flow failed',
+                reason: runnerError ??
+                    (noEvidence
+                        ? 'run.json reports ok but executed zero tests'
+                        : report === undefined
+                            ? 'run.json was not produced'
+                            : report.ok === true
+                                ? undefined
+                                : 'flow failed'),
                 usage: flowUsage(report),
                 budget: budgetFor('flow', input, report),
+                cache: flowCache(report),
             });
         }
     }
@@ -153,7 +255,7 @@ export async function runVerify(input) {
         if (!input.selection[lane])
             continue;
         const runner = input.runners[lane];
-        lanes[lane] = laneStart(lanes[lane], startedAt);
+        lanes[lane] = laneStart(lanes[lane]);
         if (runner === undefined) {
             lanes[lane] = laneEnd({
                 ...lanes[lane],
@@ -171,10 +273,34 @@ export async function runVerify(input) {
             runnerError = error instanceof Error ? error.message : String(error);
             ctxError(runnerError);
         }
+        // Runners write their own lane detail (`<lane>-lane.json`); a valid
+        // status there wins over the exit-code mapping, so preflight outcomes
+        // (blocked/unavailable/inconclusive) reach the manifest faithfully.
+        // A runner that threw before writing leaves a stale detail file behind
+        // — ignore it or the manifest inherits another run's usage and summary.
+        const detail = runnerError === undefined
+            ? await readJson(join(input.reportDir, `${lane}-lane.json`))
+            : undefined;
+        const detailStatus = detail?.status !== undefined && LANE_STATUSES.includes(detail.status)
+            ? detail.status
+            : undefined;
+        const status = runnerError !== undefined
+            ? 'failed'
+            : (detailStatus ?? (code === 0 ? 'passed' : 'failed'));
+        const usage = laneDetailUsage(lane, detail);
         lanes[lane] = laneEnd({
             ...lanes[lane],
-            status: code === 0 ? 'passed' : 'failed',
-            reason: runnerError ?? (code === 0 ? undefined : `${lane} runner exited ${code}`),
+            status,
+            reportPath: detail === undefined
+                ? undefined
+                : relativeReport(input.cwd, input.reportDir, `${lane}-lane.json`),
+            model: detail?.model,
+            summary: detail?.summary,
+            reason: runnerError ??
+                detail?.reason ??
+                (code === 0 ? undefined : `${lane} runner exited ${code}`),
+            usage,
+            budget: laneDetailBudget(lane, input, detail),
         });
     }
     const aggregate = aggregateLanes(lanes);
@@ -189,9 +315,37 @@ export async function runVerify(input) {
     };
     return { manifest, exitCode: aggregate.ok ? 0 : 1 };
 }
+/** Package version for report footers; dist/ and src/ both sit two levels deep. */
+export function argusVersion() {
+    try {
+        return createRequire(import.meta.url)('../../package.json').version;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Write the offline HTML evidence report (U14) beside run-manifest.json.
+ * Lane reports are read only when the manifest points at them: a runner that
+ * threw leaves `reportPath` unset, and its stale file must not reach the
+ * report (same contract as the manifest's own reads).
+ */
+export async function writeEvidenceReport(reportDir, manifest, meta = {}) {
+    const [codeReview, run] = await Promise.all([
+        manifest.lanes.review.reportPath !== undefined ? readJson(join(reportDir, 'code-review.json')) : undefined,
+        manifest.lanes.flow.reportPath !== undefined ? readJson(join(reportDir, 'run.json')) : undefined,
+    ]);
+    const html = renderReportHtml({
+        manifestText: JSON.stringify(manifest),
+        codeReview,
+        run,
+        version: meta.version ?? argusVersion(),
+        ...(meta.runUrl !== undefined ? { runUrl: meta.runUrl } : {}),
+    });
+    const path = join(reportDir, REPORT_HTML);
+    await writeAtomicText(path, html);
+    return path;
+}
 function ctxError(message) {
     console.error(`verify lane error: ${message}`);
 }
-export function selectedManifestLanes(selection) {
-    return selectedLanes(selection);
-}

package/dist/probe/persist.d.ts

@@ -0,0 +1,68 @@
+import { type ProbeRecord } from './queue.js';
+interface Ctx {
+    err: (line: string) => void;
+}
+/**
+ * `@argus persist` — reproduced probes become regression tests (roadmap
+ * E1.U3). Probe files are written transiently and deleted during review,
+ * so `reproduced` records carry their source + suggested path in
+ * code-review.json. The sticky comment embeds them as a base64 HTML-comment
+ * payload (`PERSIST_MARKER`) — a later `issue_comment` run on a base-only
+ * checkout decodes it and commits the probes to a new branch via the
+ * contents API, then opens one regression-test PR per source PR.
+ *
+ * Trust: payload content is model-authored. It passed the probe lane's
+ * validation once (forced `argus-probe-` filename, safe repo path, bounded
+ * imports), but the sticky comment is editable — decode() re-validates
+ * every path and bound before any write, and writes go to a dedicated
+ * branch, never the base ref.
+ */
+export interface PersistableProbe {
+    /** Repo-relative write path — `argus-probe-*` basename, validated. */
+    path: string;
+    /** Probe source (bounded). */
+    content: string;
+    /** Probe filename for messaging. */
+    file: string;
+    /** Finding file the probe covers, when known. */
+    findingFile?: string | undefined;
+}
+export declare const PERSIST_MARKER = "<!-- argus-probe-persist ";
+/** Reproduced probes carrying serialized content + a safe suggested path. */
+export declare function selectPersistable(records: ProbeRecord[] | undefined): PersistableProbe[];
+/**
+ * Serialize the payload for the sticky comment — the full marker string,
+ * or undefined when nothing persistable exists or the payload would bust
+ * the cap (the copy-paste tier still renders probes that don't fit).
+ */
+export declare function encodeProbePayload(records: ProbeRecord[] | undefined, headSha: string | undefined): string | undefined;
+export interface DecodedPayload {
+    head?: string | undefined;
+    probes: PersistableProbe[];
+}
+/**
+ * Parse a sticky comment body back into probes. Strict: exactly one
+ * marker, alphabet-checked base64, shaped JSON, and every entry through
+ * the same selectPersistable validation — a hand-edited comment fails
+ * closed to undefined rather than persisting attacker-controlled paths.
+ */
+export declare function decodeProbePayload(body: string): DecodedPayload | undefined;
+export interface PersistResult {
+    /** Opened (or reused) regression-test PR URL. */
+    prUrl?: string;
+    /** Probe paths committed to the branch. */
+    written: string[];
+    /** Probe paths skipped because they already exist on the branch. */
+    skipped: string[];
+    /** Failure message when the lane couldn't complete. */
+    error?: string;
+}
+/**
+ * Commit persistable probes to `argus/probe-regression-pr-<pr>` and open a
+ * regression-test PR against `baseRef`. Idempotent: an existing branch is
+ * reused, an existing file is skipped (never overwritten — contents API
+ * exclusive create), and an already-open PR on the branch is returned
+ * rather than duplicated.
+ */
+export declare function persistProbes(repo: string, pr: string, baseRef: string, probes: PersistableProbe[], token: string, ctx: Ctx): Promise<PersistResult>;
+export {};