argus-reviewer-e2e 0.3.1 → 0.4.0

package/dist/executor/a0.js

@@ -1,4 +1,7 @@
-import { defaultExec } from '../detect.js';
+import { buildA0ChildEnv, defaultExec, defaultProbe, resolveA0Host, } from '../detect.js';
+// The allowlist lives in detect.ts beside the exec seam — re-exported here
+// so `executor/a0` stays the single import site for delegation internals.
+export { buildA0ChildEnv };
 /**
  * Agent Zero delegation — the thin seam that hands a natural-language task to
  * an `a0` instance (`a0 headless -p`). The instance runs autonomously inside
@@ -8,8 +11,18 @@ import { defaultExec } from '../detect.js';
  * non-deterministic agent run. Fingerprint replay stays local and ~free; A0 is
  * for healing, second opinions on failures, and exploratory tasks that were
  * never recorded.
+ *
+ * The `verify --a0` lane caps completed delegations at `inconclusive`: the
+ * host round-trip is proven (#53), but the agent's answer is self-reported
+ * evidence, never a `passed` verdict.
  */
 export const A0_DEFAULT_TIMEOUT_MS = 600_000;
+/** Delegations a `verify --a0` lane may run — config.a0.maxTasks overrides. */
+export const A0_LANE_MAX_TASKS = 1;
+/** Lane detail file the a0 runner writes and `runVerify` reads back. */
+export const A0_LANE_REPORT = 'a0-lane.json';
+/** Reported posture: the round-trip is verified (#53); the answer is not. */
+export const A0_LIVE_LABEL = 'self-reported';
 export function buildA0Args(prompt, host) {
     const args = ['headless', '--new-chat', '--output', 'text'];
     if (host !== undefined && host !== '')
@@ -19,16 +32,28 @@ export function buildA0Args(prompt, host) {
 }
 export async function runA0Task(prompt, opts = {}) {
     const exec = opts.exec ?? defaultExec;
+    // The allowlisted child env is the default, not the opt-in — every
+    // delegation path (lane, heal, delegate) gets the R12 sanitization
+    // unless a caller deliberately passes a different env.
+    const baseEnv = opts.env ?? buildA0ChildEnv(process.env);
     let res;
     try {
-        res = await exec(opts.cli ?? 'a0', buildA0Args(prompt, opts.host), opts.timeoutMs ?? A0_DEFAULT_TIMEOUT_MS);
+        res = await exec(opts.cli ?? 'a0', buildA0Args(prompt, opts.host), opts.timeoutMs ?? A0_DEFAULT_TIMEOUT_MS, undefined, { baseEnv });
     }
     catch (e) {
         // Spawn rejection (ENOENT when a0 is absent, hard timeout) must degrade
         // to a failed delegation, not abort the calling command.
-        return { ok: false, output: e.message };
+        return { ok: false, output: e.message, spawnError: true };
     }
-    return { ok: res.code === 0, output: res.stdout.trim() || res.stderr.trim() };
+    return {
+        ok: res.code === 0,
+        output: res.stdout.trim() || res.stderr.trim(),
+        timedOut: res.timedOut,
+        // ExecResult.spawnError is authoritative when the executor sets it —
+        // a completed run that merely prints "not found" to stderr must not
+        // misclassify. The sniff remains for injected execs without the field.
+        spawnError: res.spawnError ?? /ENOENT|not found|no such file/i.test(res.stderr),
+    };
 }
 /** Prompt wrapper: bind the task to an app URL when one is known. */
 export function a0TaskPrompt(task, url) {
@@ -36,3 +61,190 @@ export function a0TaskPrompt(task, url) {
         ? task
         : `Open ${url} in your browser, then do this task: ${task}`;
 }
+/** Render the typed payload into the delegated prompt — sanitized surface. */
+export function buildA0LanePrompt(payload) {
+    const lines = [
+        'You are an escalation agent for the Argus PR reviewer.',
+        `Task: ${payload.task}`,
+    ];
+    if (payload.targetUrl !== undefined && payload.targetUrl !== '') {
+        lines.push(`Target: open ${payload.targetUrl} and work against that application.`);
+    }
+    if (payload.intendedHeadSha !== undefined && payload.intendedHeadSha !== '') {
+        lines.push(`The evidence must describe the PR head ${payload.intendedHeadSha}.`);
+    }
+    if (payload.failureSummary !== undefined && payload.failureSummary !== '') {
+        lines.push(`Local failure being escalated: ${payload.failureSummary}`);
+    }
+    if (payload.evidenceRefs !== undefined && payload.evidenceRefs.length > 0) {
+        lines.push(`Local evidence you may consult: ${payload.evidenceRefs.join(', ')}`);
+    }
+    lines.push('Report concisely what you observed and whether the task goal is met.', 'Do not attempt to access provider keys, tokens, or repository secrets.');
+    return lines.join('\n');
+}
+/**
+ * Whether `url` names a loopback target — the remote-a0/loopback-target
+ * refusal depends on this being complete: the whole 127.0.0.0/8 range,
+ * wildcard/zero hosts, `*.localhost`, and IPv4-mapped forms, not just the
+ * canonical `127.0.0.1`/`localhost` literals. `file:` URLs count too — a
+ * remote host's filesystem is not this machine's. DNS names that merely
+ * resolve to loopback are not caught (no lookup by design — fail-open on
+ * hostnames is deliberate here).
+ */
+export function isLoopback(url) {
+    try {
+        if (new URL(url).protocol === 'file:')
+            return true;
+        const host = new URL(url).hostname.replace(/\.$/, '').toLowerCase();
+        if (host === 'localhost' || host.endsWith('.localhost'))
+            return true;
+        // Node keeps IPv6 brackets in .hostname and normalizes mapped forms:
+        // [::1] stays, [::ffff:127.0.0.1] arrives as [::ffff:7f00:1], and
+        // short/integer IPv4 (127.1, 2130706433) normalizes to dotted-quad.
+        if (host === '[::1]' || host === '[::]')
+            return true;
+        const mapped = host.match(/^\[::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})\]$/i);
+        if (mapped !== null) {
+            const hi = parseInt(mapped[1] ?? 'x', 16);
+            const lo = parseInt(mapped[2] ?? 'x', 16);
+            const first = (hi >> 8) & 0xff;
+            if (first === 127 || (hi === 0 && lo === 0))
+                return true;
+        }
+        const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+        if (v4 !== null) {
+            const octets = v4.slice(1).map((g) => Number(g ?? ''));
+            if (octets.every((n) => Number.isInteger(n) && n <= 255) && (octets[0] === 127 || octets[0] === 0)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `verify --a0` lane: explicit selection only, every preflight outcome
+ * recorded, zero spend before the host is proven reachable, and a hard
+ * `inconclusive` ceiling — a completed delegation is evidence, and the
+ * agent's report of what it saw is self-reported, not a verdict.
+ */
+export async function runA0Lane(input) {
+    const started = Date.now();
+    const deps = input.deps ?? {};
+    const note = deps.note ?? (() => undefined);
+    const done = (status, reason, extra) => ({
+        lane: 'a0',
+        status,
+        reason,
+        summary: status === 'inconclusive' ? `delegation returned — ${A0_LIVE_LABEL}` : reason,
+        host: undefined,
+        hostSource: undefined,
+        targetReachable: undefined,
+        task: input.task,
+        output: undefined,
+        tasks: 0,
+        durationMs: Date.now() - started,
+        metered: false,
+        ...extra,
+    });
+    // Executable lanes are gated on the same trust resolution as config
+    // loading (SECURITY.md): an untrusted checkout never resolves a host or
+    // spawns the a0 CLI — blocked before any preflight.
+    if (!input.trusted) {
+        return done('blocked', 'verify --a0 is an executable lane — requires a trusted checkout');
+    }
+    if (input.task === undefined || input.task.trim() === '') {
+        return done('blocked', 'no delegated task configured — set a0 task via config app.task or the app lane');
+    }
+    // Preflight 1: host resolution — config wins, then the CLI's own chain
+    // (env, ~/.agent-zero/.env, localhost probe). Missing both ends = nothing
+    // to reach. A configured a0.url skips the probe chain entirely.
+    const resolveHost = deps.resolveHost ??
+        (async () => {
+            const r = await resolveA0Host(input.env, {
+                ...(deps.probe !== undefined ? { probe: deps.probe } : {}),
+            });
+            return { host: r.host, source: r.source };
+        });
+    const cliVersion = deps.cliVersion ??
+        (async () => {
+            // The presence probe spawns the a0 binary too — it gets the same
+            // allowlisted env as the delegation or the whole contract is moot.
+            const res = await (deps.exec ?? defaultExec)(deps.cli ?? 'a0', ['--version'], 5_000, undefined, { baseEnv: buildA0ChildEnv(input.env) });
+            return res.code === 0 ? res.stdout.trim() : undefined;
+        });
+    const configured = input.a0?.url !== undefined && input.a0.url !== '';
+    const [resolved, version] = await Promise.all([
+        configured ? Promise.resolve({ host: undefined, source: undefined }) : resolveHost(),
+        cliVersion(),
+    ]);
+    const host = input.a0?.url ?? resolved.host;
+    const hostSource = input.a0?.url !== undefined ? 'config' : resolved.source;
+    if (version === undefined && host === undefined) {
+        return done('unavailable', 'no Agent Zero found — install the a0 CLI or set a0.url / AGENT_ZERO_HOST');
+    }
+    if (host === undefined) {
+        // CLI present, host unresolved — the CLI may still self-resolve, but the
+        // lane must prove a host before spending: record the gap honestly.
+        return done('unavailable', 'a0 CLI is installed but no host resolved — set AGENT_ZERO_HOST or a0.url');
+    }
+    // Preflight 2: the host must answer as Agent Zero — a URL that serves
+    // something else is worse than no host.
+    const probe = deps.probe ?? defaultProbe;
+    if (!(await probe(host, 5_000))) {
+        return done('unavailable', `a0 host did not answer as Agent Zero: ${host}`, {
+            host,
+            hostSource,
+        });
+    }
+    // Preflight 3: can the host reach the target? A remote a0 cannot drive a
+    // loopback app on this machine — that's a scope refusal, not a failure.
+    if (input.targetUrl !== undefined &&
+        isLoopback(input.targetUrl) &&
+        !isLoopback(host)) {
+        return done('blocked', `a0 host ${host} is remote but the target ${input.targetUrl} is loopback — the host cannot reach it`, { host, hostSource, targetReachable: 'refused' });
+    }
+    const maxTasks = input.a0?.maxTasks ?? A0_LANE_MAX_TASKS;
+    const timeoutMs = input.a0?.timeoutMs ?? A0_DEFAULT_TIMEOUT_MS;
+    note(`a0 lane: delegating 1 task to ${host} (max ${maxTasks}, ` +
+        `${Math.round(timeoutMs / 1000)}s wall-clock, usage unmetered, ${A0_LIVE_LABEL})`);
+    const payload = buildA0LanePrompt({
+        task: input.task,
+        targetUrl: input.targetUrl,
+        intendedHeadSha: input.intendedHeadSha,
+        failureSummary: input.failureSummary ?? undefined,
+        evidenceRefs: undefined,
+    });
+    const res = await runA0Task(payload, {
+        host,
+        timeoutMs,
+        env: buildA0ChildEnv(input.env),
+        ...(deps.exec !== undefined ? { exec: deps.exec } : {}),
+        ...(deps.cli !== undefined ? { cli: deps.cli } : {}),
+    });
+    if (res.spawnError === true) {
+        return done('unavailable', `a0 delegation could not start: ${res.output}`, {
+            host,
+            hostSource,
+        });
+    }
+    if (res.timedOut === true) {
+        return done('inconclusive', `a0 delegation timed out after ${timeoutMs}ms`, {
+            host,
+            hostSource,
+            output: res.output !== '' ? res.output : undefined,
+            tasks: 1,
+        });
+    }
+    // Every completed delegation — success or reported failure — is evidence
+    // whose truth rests on the agent's own report: inconclusive, never passed.
+    return done('inconclusive', res.ok ? undefined : `a0 delegation reported failure: ${res.output}`, {
+        host,
+        hostSource,
+        targetReachable: input.targetUrl !== undefined ? 'assumed' : 'unchecked',
+        output: res.output !== '' ? res.output : undefined,
+        tasks: 1,
+    });
+}

package/dist/fsutil.d.ts

@@ -1,5 +1,6 @@
 /**
- * Atomic JSON write via tmp+rename — the one place the pattern lives.
- * Callers: cache store, journal store, repo index.
+ * Atomic text write via tmp+rename — the one place the pattern lives.
+ * Callers: cache store, journal store, repo index, evidence report.
  */
+export declare function writeAtomicText(path: string, text: string): Promise<void>;
 export declare function writeAtomicJson(path: string, value: unknown, replacer?: (key: string, v: unknown) => unknown): Promise<void>;

package/dist/fsutil.js

@@ -1,12 +1,15 @@
 import { mkdir, rename, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 /**
- * Atomic JSON write via tmp+rename — the one place the pattern lives.
- * Callers: cache store, journal store, repo index.
+ * Atomic text write via tmp+rename — the one place the pattern lives.
+ * Callers: cache store, journal store, repo index, evidence report.
  */
-export async function writeAtomicJson(path, value, replacer) {
+export async function writeAtomicText(path, text) {
     await mkdir(dirname(path), { recursive: true });
     const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
-    await writeFile(tmp, `${JSON.stringify(value, replacer, 2)}\n`, 'utf8');
+    await writeFile(tmp, text, 'utf8');
     await rename(tmp, path);
 }
+export async function writeAtomicJson(path, value, replacer) {
+    await writeAtomicText(path, `${JSON.stringify(value, replacer, 2)}\n`);
+}

package/dist/journal/schema.d.ts

@@ -5,7 +5,7 @@
  */
 export declare const JOURNAL_SCHEMA_VERSION = 1;
 export interface ErrorRecord {
-    /** Pipeline stage: boot | target | locate | assert | heal | report | index */
+    /** Pipeline stage: boot | target | locate | assert | heal | explore | report | index */
     stage: string;
     message: string;
     /** Minimal context: step instruction, model, page URL — never secrets. */

package/dist/log.d.ts

@@ -3,6 +3,7 @@
  * default 'warn'. Debug emits model call excerpts and recovery paths —
  * never secret values.
  */
+import { type Styler } from './ui/style.js';
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 export interface Logger {
     level: LogLevel;
@@ -13,5 +14,5 @@ export interface Logger {
 }
 export declare function createLogger(level: LogLevel, sink: {
     err: (line: string) => void;
-}, live?: (level: LogLevel, msg: string) => void): Logger;
+}, live?: (level: LogLevel, msg: string) => void, style?: Styler): Logger;
 export declare function resolveLogLevel(env: Record<string, string | undefined>, configured?: string): LogLevel;

package/dist/log.js

@@ -1,8 +1,16 @@
+/**
+ * Tiny leveled logger. Level comes from ARGUS_DEBUG=1 or config.logLevel;
+ * default 'warn'. Debug emits model call excerpts and recovery paths —
+ * never secret values.
+ */
+import { PLAIN } from './ui/style.js';
 const ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
-export function createLogger(level, sink, live) {
+export function createLogger(level, sink, live, style = PLAIN) {
+    // DESIGN.md 7.7: a dim level word (bold for error) instead of `[level]`.
+    const prefix = (l) => (l === 'error' ? style.bold(l) : style.dim(l));
     const emit = (l, msg) => {
         if (ORDER[l] >= ORDER[level])
-            sink.err(`[${l}] ${msg}`);
+            sink.err(`${prefix(l)}: ${msg}`);
         live?.(l, msg);
     };
     // `live` receives every level regardless of `level` — the local dashboard

package/dist/mention.d.ts

@@ -0,0 +1,45 @@
+import { type PrMeta } from './evidence/ci.js';
+/**
+ * `@argus` mention commands on PR comments (roadmap E3.U5). The mention
+ * lane runs on `issue_comment` events — strictly more privileged than
+ * `pull_request` (repo secrets + write-capable GITHUB_TOKEN are present),
+ * so it NEVER checks out the PR head. Review operates on a base-ref
+ * checkout with the PR diff fetched via the API — the same diff-only
+ * posture `code-review` already uses.
+ */
+export type MentionName = 'review' | 'record' | 'persist' | 'help';
+export interface MentionCommand {
+    name: MentionName;
+    /** `record` flow description, quotes already stripped. */
+    arg?: string;
+}
+/**
+ * Parse a comment body into a whitelisted mention command. The mention must
+ * open the comment — a bare `@argus` in the middle of prose is not a command.
+ * `@argus` alone and `@argus help` both yield `help`; anything that isn't a
+ * whitelisted verb yields `unknown` so the caller can reply with the menu.
+ */
+export declare function parseMention(body: string): MentionCommand | 'unknown' | undefined;
+export interface MentionGate {
+    allowed: boolean;
+    /** Reply text for denials the commenter should see; undefined → silent. */
+    reply?: string;
+}
+/**
+ * Two-part gate. `association` is the *commenter's* `author_association`
+ * (not the PR author's): only MEMBER/OWNER/COLLABORATOR may drive Argus.
+ * For fork-head PRs every command additionally needs the `argus-probe`
+ * label covering the current head SHA, and `record`/`persist` are disabled
+ * outright — they would execute or persist artifacts derived from code the
+ * label was meant to bound. `help` needs no label: it replies with a fixed
+ * menu and executes nothing.
+ */
+export declare function mayRunMention(cmd: MentionCommand, association: string | undefined, meta: PrMeta | undefined): MentionGate;
+export declare const MENTION_HELP: string;
+/**
+ * Post the mention reply as an issue comment. Best-effort — a failed reply
+ * logs and returns false rather than failing the dispatch.
+ */
+export declare function postIssueComment(repo: string, issue: string, body: string, token: string, ctx: {
+    err: (line: string) => void;
+}): Promise<boolean>;

package/dist/mention.js

@@ -0,0 +1,107 @@
+import { isTrustedAssociation, PROBE_LABEL } from './evidence/ci.js';
+import { labelCoversHead } from './evidence/gate.js';
+const NAMES = new Set(['review', 'record', 'persist', 'help']);
+/**
+ * Parse a comment body into a whitelisted mention command. The mention must
+ * open the comment — a bare `@argus` in the middle of prose is not a command.
+ * `@argus` alone and `@argus help` both yield `help`; anything that isn't a
+ * whitelisted verb yields `unknown` so the caller can reply with the menu.
+ */
+export function parseMention(body) {
+    const first = body.trimStart().split('\n', 1)[0]?.trim() ?? '';
+    const m = /^@argus\b\s*(.*)$/i.exec(first);
+    if (m === null)
+        return undefined;
+    const rest = (m[1] ?? '').trim();
+    if (rest === '')
+        return { name: 'help' };
+    const verb = rest.split(/\s+/, 1)[0]?.toLowerCase() ?? '';
+    if (!NAMES.has(verb))
+        return 'unknown';
+    const name = verb;
+    if (name !== 'record')
+        return { name };
+    // `record "sign in with google"` — quotes optional; cap the flow text.
+    // Newlines/backticks are stripped: the arg is commenter-controlled text
+    // echoed into a public reply.
+    const arg = rest
+        .slice(verb.length)
+        .trim()
+        .replace(/^["']|["']$/g, '')
+        .replace(/[\r\n`]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 200);
+    return { name, ...(arg !== '' ? { arg } : {}) };
+}
+/**
+ * Two-part gate. `association` is the *commenter's* `author_association`
+ * (not the PR author's): only MEMBER/OWNER/COLLABORATOR may drive Argus.
+ * For fork-head PRs every command additionally needs the `argus-probe`
+ * label covering the current head SHA, and `record`/`persist` are disabled
+ * outright — they would execute or persist artifacts derived from code the
+ * label was meant to bound. `help` needs no label: it replies with a fixed
+ * menu and executes nothing.
+ */
+export function mayRunMention(cmd, association, meta) {
+    if (!isTrustedAssociation(association))
+        return { allowed: false };
+    if (cmd.name === 'help')
+        return { allowed: true };
+    if (meta === undefined) {
+        return { allowed: false, reply: "I can't see this PR's metadata — try again in a moment." };
+    }
+    if (!meta.isFork)
+        return { allowed: true };
+    if (cmd.name === 'record' || cmd.name === 'persist') {
+        return {
+            allowed: false,
+            reply: `\`@argus ${cmd.name}\` isn't available on fork PRs — record and persist run inside the repo's trust boundary.`,
+        };
+    }
+    if (!meta.labels.includes(PROBE_LABEL) || !labelCoversHead(meta)) {
+        return {
+            allowed: false,
+            reply: `This PR comes from a fork — a maintainer can enable review by applying \`${PROBE_LABEL}\` to the current head.`,
+        };
+    }
+    return { allowed: true };
+}
+export const MENTION_HELP = 'Commands: `@argus review` — re-run code review on the latest head · ' +
+    '`@argus record "<flow>"` — record a test flow against the app · ' +
+    '`@argus persist` — turn a reproduced probe into a regression-test PR · ' +
+    '`@argus help` — this menu.';
+const GH_API = 'https://api.github.com';
+/**
+ * Post the mention reply as an issue comment. Best-effort — a failed reply
+ * logs and returns false rather than failing the dispatch.
+ */
+export async function postIssueComment(repo, issue, body, token, ctx) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 30_000);
+    try {
+        const res = await fetch(`${GH_API}/repos/${repo}/issues/${issue}/comments`, {
+            method: 'POST',
+            signal: controller.signal,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/vnd.github+json',
+                'X-GitHub-Api-Version': '2022-11-28',
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({ body }),
+        });
+        if (!res.ok) {
+            ctx.err(`mention: reply post failed — github ${res.status} ${res.statusText}`);
+            return false;
+        }
+        return true;
+    }
+    catch (e) {
+        ctx.err(`mention: reply post failed — ${e.message}`);
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}

package/dist/pipeline/app.d.ts

@@ -0,0 +1,126 @@
+import type { AppExpectation, Config, Target } from '../config.js';
+import type { BrowserDriver, PageCapture } from '../driver/browser.js';
+import { TargetProcess } from '../driver/target.js';
+import { Actions } from '../engine/actions.js';
+import { type ExpectationContext, type ExploreResult } from '../engine/explore.js';
+import type { VisionClient } from '../engine/loop.js';
+import type { ErrorRecord } from '../journal/schema.js';
+import type { Logger } from '../log.js';
+import type { LaneStatus } from '../report/manifest.js';
+import type { CallCost } from '../vision/cost.js';
+import { Ledger } from '../vision/ledger.js';
+/** Lane detail file the app runner writes and `runVerify` reads back. */
+export declare const APP_LANE_REPORT = "app-lane.json";
+/** Wall-clock bound when config.app.timeoutMs is unset. */
+export declare const APP_LANE_DEFAULT_TIMEOUT_MS = 120000;
+/**
+ * Lane detail record written to `app-lane.json`. `runVerify` merges `status`,
+ * `reason`, `summary`, `model`, and the call records into the manifest lane;
+ * the rest is evidence for the operator surfaces (TUI, dashboard, comment).
+ */
+export interface AppLaneReport {
+    lane: 'app';
+    status: LaneStatus;
+    reason: string | undefined;
+    summary: string | undefined;
+    task: string | undefined;
+    expected: AppExpectation | undefined;
+    targetUrl: string | undefined;
+    finalUrl: string | undefined;
+    expectedMet: boolean;
+    stopReason: string | undefined;
+    steps: {
+        action: string;
+        url: string;
+        note?: string;
+    }[];
+    visited: number;
+    anomalies: PageCapture[];
+    notes: ErrorRecord[];
+    artifacts: {
+        video: string | undefined;
+    };
+    calls: CallCost[];
+    visionCalls: number;
+    visionCostUsd: number;
+    durationMs: number;
+    model: string | undefined;
+}
+interface ExpectationCheck {
+    check: (ctx: ExpectationContext) => Promise<boolean>;
+    /** Human-readable form for the lane record, e.g. `text "Done"` + url /x/. */
+    describe: string;
+}
+/**
+ * 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 declare function buildExpectationCheck(expected: AppExpectation): ExpectationCheck;
+export interface AppTaskInput {
+    driver: BrowserDriver;
+    actions: Actions;
+    client: VisionClient;
+    ledger: Ledger;
+    config: Config;
+    targetUrl: string;
+    task: string;
+    expected: AppExpectation;
+    timeoutMs: number;
+    maxSteps?: number | undefined;
+    /**
+     * The lane's own spend bound, forwarded to the explore loop — without it
+     * `explore.budgetUsd` (a different lane's knob) throttles the app lane.
+     */
+    budgetLimitUsd?: number | undefined;
+    logger?: Logger | undefined;
+}
+/**
+ * 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 declare function runAppTask(input: AppTaskInput): Promise<{
+    result: ExploreResult;
+    expectedMet: boolean;
+    verifyError: string | undefined;
+}>;
+export interface AppLaneDeps {
+    /** Browser launch — default Chromium with error-capture taps on. */
+    launchDriver?: (config: Config) => Promise<BrowserDriver>;
+    /** Vision client factory — lazy key resolution stays with the caller. */
+    createClient?: (config: Config) => VisionClient;
+    /** URL readiness probe. */
+    waitForReady?: (url: string, timeoutMs: number) => Promise<void>;
+    /** Target-command boot. */
+    startTarget?: (spec: Target) => Promise<TargetProcess>;
+    /** Consumer page-setup hook (config.pageSetup module) — trusted only. */
+    applyPageSetup?: (driver: BrowserDriver) => Promise<void>;
+    logger?: Logger;
+}
+export interface AppLaneInput {
+    config: Config;
+    /** Resolved target URL — `--url` or `config.target.url`. */
+    url: string | undefined;
+    /** The checkout's trust lane — gates the whole executable lane. */
+    trusted: boolean;
+    /** `--task` override wins over `config.app.task`. */
+    task: string | undefined;
+    /** Flag-level expected-state markers win over `config.app.expected`. */
+    expected: AppExpectation | undefined;
+    /**
+     * Fully-resolved lane cap (`app.budgetUsd ?? ARGUS_BUDGET_USD ??
+     * budgetUsd`) — the caller resolves precedence so the enforced Ledger
+     * bound is exactly the one the manifest reports.
+     */
+    budgetLimitUsd?: number;
+    deps?: AppLaneDeps;
+}
+/**
+ * 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 declare function runAppLane(input: AppLaneInput): Promise<AppLaneReport>;
+export {};