@yagni-app/code-staging 1.2.6-staging.1951.1 → 1.2.6-staging.1956.1

package/dist/extension/pipeline/headlessGo.js

@@ -24,6 +24,17 @@
  * run ends at the reviewed candidate and never commits, pushes, opens a PR, or
  * reports one. The mission's own prHandoff owns all of that.
  *
+ * CLOUD (`--cloud`, the one-attempt lane; cloud.ts): the session runs the
+ * cloud lane (stages.ts `cloudLane`: plan, implement, review, fix, then verify
+ * and finish; one writer, one reviewer, four rounds) on the host's input
+ * folder beside the ticket and its env (`YAGNI_ATTEMPT_ID`, `YAGNI_EXECUTION_ID`,
+ * `YAGNI_GENERATION`, `YAGNI_MISSION_OUT_DIR`, `YAGNI_GO_STAGE_TIERS`). A fresh
+ * attempt plans and stops, writing `plan.md` and `plan.json`; a plan file
+ * starts implement; a continue file names its stage. Every execution but a
+ * plan commits its work locally on the branch the host checked out, whatever
+ * its stop, and never pushes. Its last act is `result.json`, mirrored on the
+ * last `pipeline_result` line. Mission mode below is untouched by it.
+ *
  * CONTINUATION (`--continue-file`, mission mode only): the run continues an
  * earlier attempt whose change is already in the tree as uncommitted edits. The
  * build baselines the clean base, and an attempt that stopped in review, fix or
@@ -45,7 +56,8 @@
  *  - Always, as the last line: the result object
  *    `{type:"pipeline_result", ok, stopReason, rounds, findings, stages:[{stage,
  *    tier, usage}], …}` — or `{type:"pipeline_error", …}` when a build stage
- *    threw.
+ *    threw. `preexistingFailures` (absent at 0) counts the gate's own
+ *    typecheck, lint and test failures the clean tree already had (YAG-1003).
  *  - Exit codes: 0 ONLY on a verified candidate (a `clean` stop), 1 for any
  *    other outcome or a thrown pipeline error, 2 for a usage/input problem.
  *
@@ -59,8 +71,12 @@
  * ceilings (`SANDBOX_RUN_BUDGET`), not interactive /go's.
  */
 import { readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { continuationResumePlan, parseContinuation } from "./continuation.js";
+import { dirname, join, relative } from "node:path";
+import { CLOUD_SESSION_ENV, completeCloudSession, prepareCloudLane, readCloudEnv, } from "./cloud.js";
+import { scanChange } from "./changeScan.js";
+import { continuationResumePlan, parseContinuation, } from "./continuation.js";
+import { finishExec } from "./finish.js";
+import { snapshotWorkspace } from "./workspace.js";
 import { resolveFanoutMode } from "./fanout.js";
 import { makeFanoutBeats } from "./fanoutBeats.js";
 import { isBlockingFinding } from "./findings.js";
@@ -68,20 +84,25 @@ import { MISSION_FIX_ROUND_FILE_NAME, readFixRoundFile } from "./fixRound.js";
 import { normalizeMission } from "./mission.js";
 import { MISSION_CHECKS_FILE_NAME, MISSION_CI_RESULTS_FILE_NAME, readMissionChecksFile, renderCiResults, } from "./missionChecks.js";
 import { startTreeSnapshots } from "./treeSnapshot.js";
-import { runPipeline as defaultRunPipeline } from "./orchestrator.js";
-import { makeRunVerify } from "./verify.js";
+import { PipelineStageError, runPipeline as defaultRunPipeline, } from "./orchestrator.js";
+import { baselineDirs, makeRunVerify, makeTakeVerifyBaseline, makeWorkstreamCheck, parseChangedPaths, planPaths, } from "./verify.js";
 import { loadGroundingEnabled } from "../grounding.js";
 import { codeStateHome } from "../stateHome.js";
 import { parseTierCap, TIER_CAP_ENV } from "./tierCap.js";
-import { parsePipelineTimeLeft, PIPELINE_TIME_LEFT_ENV, SANDBOX_RUN_BUDGET } from "./budget.js";
+import { parsePipelineTimeLeft, PIPELINE_TIME_LEFT_ENV, SANDBOX_RUN_BUDGET, } from "./budget.js";
 /** One-line usage copy, shared by every argument error. */
-export const HEADLESS_GO_USAGE = "Usage: yagni go --headless --ticket-file <path> [--plan-file <path>] [--memo-file <path>] [--continue-file <path>] [--run-id <id>] [--cwd <path>] [--json]";
+export const HEADLESS_GO_USAGE = "Usage: yagni go --headless [--cloud] --ticket-file <path> [--plan-file <path>] [--memo-file <path>] [--continue-file <path>] [--run-id <id>] [--cwd <path>] [--json]";
+/** With a deadline, the final verify of a cloud session needs at least this much of it left. */
+const FINAL_VERIFY_MIN_LEFT_MS = 5 * 60_000;
 /**
  * Exit codes. `verified` is deliberately narrow: only a `clean` stop means the
  * run produced a reviewed candidate, so a round_cap / no_changes / failed run
  * can never read as success to a script, a smoke gate, or CI.
  */
 export const HEADLESS_GO_EXIT = { verified: 0, unverified: 1, usage: 2 };
+/** The verify baseline's share of a deadline run's time left, and the least it is worth starting with. */
+const BASELINE_SHARE_OF_TIME_LEFT = 6;
+const MIN_BASELINE_BUDGET_MS = 60_000;
 const VALUE_FLAGS = {
     "--ticket-file": "ticketFile",
     "--plan-file": "planFile",
@@ -101,6 +122,7 @@ export function parseHeadlessGoArgs(argv) {
     const args = {
         headless: false,
         json: false,
+        cloud: false,
         unknownFlags: [],
         positionals: [],
         missingValues: [],
@@ -120,6 +142,10 @@ export function parseHeadlessGoArgs(argv) {
             args.json = true;
             continue;
         }
+        if (name === "--cloud") {
+            args.cloud = true;
+            continue;
+        }
         const key = VALUE_FLAGS[name];
         if (key) {
             const next = inlineValue ?? argv[i + 1];
@@ -195,7 +221,9 @@ function buildResult(result, ctx) {
         rounds: result.rounds.length,
         findings: result.findings.length,
         blocking: result.findings.filter(isBlocking).length,
-        finalFindings: [...result.findings].sort((a, b) => Number(isBlocking(b)) - Number(isBlocking(a))).slice(0, 10),
+        finalFindings: [...result.findings]
+            .sort((a, b) => Number(isBlocking(b)) - Number(isBlocking(a)))
+            .slice(0, 10),
         stages: stageRows(result),
         ...(ctx.runId ? { runId: ctx.runId } : {}),
         ...(ctx.tierCap ? { tierCap: ctx.tierCap } : {}),
@@ -204,6 +232,7 @@ function buildResult(result, ctx) {
         ...(finish?.prUrl ? { prUrl: finish.prUrl } : {}),
         ...(result.verifyNote ? { verifyNote: result.verifyNote } : {}),
         ...(result.verifyCommand ? { verifyCommand: result.verifyCommand } : {}),
+        ...(ctx.preexistingFailures ? { preexistingFailures: ctx.preexistingFailures } : {}),
     };
 }
 /** Attribution rider for a streamed child event (never overwrites pi's own keys). */
@@ -245,7 +274,9 @@ export async function runHeadlessGo(argv, deps = {}) {
             return readFile(path);
         }
         catch (err) {
-            return { error: `Could not read the ${label} at ${path}: ${err instanceof Error ? err.message : String(err)}` };
+            return {
+                error: `Could not read the ${label} at ${path}: ${err instanceof Error ? err.message : String(err)}`,
+            };
         }
     };
     const files = {
@@ -289,22 +320,35 @@ export async function runHeadlessGo(argv, deps = {}) {
     const deadlineMs = timeLeftMs === undefined ? undefined : (deps.now ?? Date.now)() + timeLeftMs;
     const budget = deadlineMs === undefined
         ? deps.budget
-        : { ...(deps.budget ?? SANDBOX_RUN_BUDGET), deadlineMs: deps.budget?.deadlineMs ?? deadlineMs };
+        : {
+            ...(deps.budget ?? SANDBOX_RUN_BUDGET),
+            deadlineMs: deps.budget?.deadlineMs ?? deadlineMs,
+        };
     const cwd = args.cwd ?? deps.cwd ?? process.cwd();
     const emit = (obj) => write(JSON.stringify(obj));
     const stream = args.json;
+    // A blank plan or memo file is NOT mission context: it must never read as an
+    // approved plan (which would skip the pipeline's planning on nothing at all).
+    const mission = normalizeMission({ plan: files.plan, memo: files.memo });
+    // The cloud session (cloud.ts): its identity and output folder from the
+    // host's env, read before anything runs, since its result must carry them.
+    const cloudEnv = args.cloud ? readCloudEnv(env) : undefined;
+    if (cloudEnv && "problem" in cloudEnv) {
+        writeErr(cloudEnv.problem);
+        writeErr(HEADLESS_GO_USAGE);
+        return { exitCode: HEADLESS_GO_EXIT.usage, error: cloudEnv.problem };
+    }
     const childEnv = {
         ...(deps.childEnv ?? env),
         ...(tierCap ? { [TIER_CAP_ENV]: tierCap } : {}),
+        ...(cloudEnv ? { [CLOUD_SESSION_ENV]: "1" } : {}),
     };
-    // A blank plan or memo file is NOT mission context: it must never read as an
-    // approved plan (which would skip the pipeline's planning on nothing at all).
-    const mission = normalizeMission({ plan: files.plan, memo: files.memo });
     // The continue file fails soft on every path: a continuation the run cannot
     // read still has the saved change in its tree, and a normal mission on it beats
-    // no run at all.
+    // no run at all. A cloud session's continue file needs no plan: a fix or
+    // verify execution resumes from the attempt's branch.
     let continuation;
-    if (args.continueFile && !mission) {
+    if (args.continueFile && !mission && !cloudEnv) {
         writeErr(`Ignoring --continue-file ${args.continueFile}: a continuation needs a mission (--plan-file or --memo-file).`);
     }
     else if (args.continueFile) {
@@ -317,9 +361,27 @@ export async function runHeadlessGo(argv, deps = {}) {
         else if (parsed)
             writeErr(`Ignoring --continue-file ${args.continueFile}: ${parsed.reason}. Running as a normal mission.`);
     }
-    const resumeFrom = continuation
-        ? continuationResumePlan(continuation, { ticket: files.ticket, ...(args.runId ? { runId: args.runId } : {}), ...(mission ? { mission } : {}) })
-        : undefined;
+    // The cloud lane and the stage this execution starts at.
+    let cloud;
+    let lane;
+    if (cloudEnv) {
+        const prepared = prepareCloudLane({
+            inputDir: dirname(args.ticketFile ?? ""),
+            env,
+            ...(args.continueFile ? { continueFile: args.continueFile } : {}),
+            ...(continuation ? { continuation } : {}),
+            hasPlan: Boolean(mission?.plan),
+            readFile,
+            writeErr,
+        });
+        if ("problem" in prepared) {
+            writeErr(prepared.problem);
+            return { exitCode: HEADLESS_GO_EXIT.usage, error: prepared.problem };
+        }
+        cloud = { ...cloudEnv, stage: prepared.stage };
+        lane = prepared.lane;
+    }
+    const cloudStage = cloud?.stage;
     // The implement diamond's recording thread, per RUN. The beats ride the
     // NDJSON stream as `pipeline_fanout` records, and the mission collector
     // folds them onto the Run.
@@ -327,16 +389,16 @@ export async function runHeadlessGo(argv, deps = {}) {
     // A mission's approved checks and its pull request's CI jobs, written by the
     // host beside the ticket: the verify gate runs them inside the loop. No file
     // (a host that predates it) leaves the gate as it was.
-    let runVerify;
-    if (mission && args.ticketFile) {
+    let gateOpts;
+    if ((mission || cloud) && args.ticketFile) {
         const checksPath = join(dirname(args.ticketFile), MISSION_CHECKS_FILE_NAME);
         const read = readMissionChecksFile(checksPath, readFile);
         if (read.file) {
             const checks = read.file;
             // How the failed CI checks' jobs went, for the host, beside the checks
-            // file. A write that fails is said once; the host then trusts the
-            // round's own account, as before.
-            const resultsPath = join(dirname(args.ticketFile), MISSION_CI_RESULTS_FILE_NAME);
+            // file (a cloud session's outputs folder). A write that fails is said
+            // once; the host then trusts the round's own account, as before.
+            const resultsPath = join(cloud?.outDir ?? dirname(args.ticketFile), MISSION_CI_RESULTS_FILE_NAME);
             let resultsWriteFailed = false;
             const onFailedChecks = (results) => {
                 try {
@@ -349,7 +411,7 @@ export async function runHeadlessGo(argv, deps = {}) {
                     writeErr(`Could not write ${resultsPath}: ${err instanceof Error ? err.message : String(err)}`);
                 }
             };
-            runVerify = (deps.makeRunVerify ?? makeRunVerify)({ repoChecks: () => checks, onFailedChecks });
+            gateOpts = { repoChecks: () => checks, onFailedChecks };
         }
         else if (read.problem !== "missing") {
             const why = read.problem === "malformed" ? "not a version 1 checks file" : "it could not be read";
@@ -361,7 +423,7 @@ export async function runHeadlessGo(argv, deps = {}) {
     // is an ordinary mission; an unreadable one is reported and the run goes on
     // the full path, which is slower but never wrong.
     let fixRound;
-    if (mission && args.ticketFile) {
+    if ((cloud ? cloudStage === "fix" : mission) && args.ticketFile) {
         const fixPath = join(dirname(args.ticketFile), MISSION_FIX_ROUND_FILE_NAME);
         const read = readFixRoundFile(fixPath, readFile);
         if (read.file)
@@ -371,6 +433,91 @@ export async function runHeadlessGo(argv, deps = {}) {
             writeErr(`Ignoring ${fixPath}: ${why}. The fix round runs the full pipeline.`);
         }
     }
+    // A continuation past implement re-enters the review loop. A cloud fix
+    // execution with the round's findings in `fix-round.json` runs fix mode
+    // instead, which the loop's re-entry would otherwise override.
+    const resumeFrom = continuation && !(cloud && fixRound)
+        ? continuationResumePlan(continuation, {
+            ticket: files.ticket,
+            ...(args.runId ? { runId: args.runId } : {}),
+            ...(mission ? { mission } : {}),
+        }, lane ? { maxRounds: lane.maxReviewRounds, committed: true } : {})
+        : undefined;
+    // The gate's own checks, once on the clean tree before the build (YAG-1003),
+    // in the packages the approved plan names: what already failed there is a
+    // note, never a finding. Only a fresh build's tree is the clean base; a
+    // continuation or a fix round already carries a change, so it takes none (a
+    // cloud continuation's earlier work is committed on its branch, and taking
+    // the baseline there would excuse the attempt's own breakage). It then leans
+    // on `checks.json`, whose base standing the host took on the real base.
+    let baseline;
+    const logBaseline = (data) => {
+        deps.logger?.("verify_baseline", data);
+        if (stream)
+            emit({ type: "pipeline_log", event: "verify_baseline", data });
+    };
+    // With a deadline, the baseline gets at most a sixth of the run's time left,
+    // and none below a minute: the build itself must still fit.
+    const deadlineLeftMs = budget?.deadlineMs === undefined ? undefined : budget.deadlineMs - (deps.now ?? Date.now)();
+    const baselineBudgetMs = deadlineLeftMs === undefined
+        ? undefined
+        : Math.floor(deadlineLeftMs / BASELINE_SHARE_OF_TIME_LEFT);
+    if (mission?.plan && !continuation && !fixRound && !deps.signal?.aborted) {
+        const dirs = baselineDirs(cwd, planPaths(mission.plan), readFile);
+        if (dirs.length > 0 &&
+            baselineBudgetMs !== undefined &&
+            baselineBudgetMs < MIN_BASELINE_BUDGET_MS) {
+            logBaseline({
+                skipped: "too little of the run's time left",
+                deadlineLeftMs,
+                baselineBudgetMs,
+            });
+        }
+        else if (dirs.length > 0) {
+            try {
+                const taken = await (deps.takeVerifyBaseline ?? makeTakeVerifyBaseline())(cwd, dirs, deps.signal, baselineBudgetMs);
+                logBaseline({ ran: taken.ran, failures: taken.failures, notes: taken.notes });
+                if (taken.baseline.size > 0)
+                    baseline = taken.baseline;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logBaseline({ error: message });
+                writeErr(`The verify baseline could not run (every failure counts): ${message}`);
+            }
+        }
+    }
+    // The last gate verdict's count of failures the clean tree already had, for the result.
+    let preexistingFailures = 0;
+    let runVerify;
+    // A cloud session reports the checks of the tree it commits: the gate's last
+    // verdict, with the tree it judged.
+    const snapshot = deps.snapshotWorkspace ?? snapshotWorkspace;
+    let gate;
+    let lastVerify;
+    // A cloud session's gate also runs the host's secret and binary scans on
+    // what it added (YAG-1000), its own run token among the secrets it looks for.
+    const exec = deps.exec ?? finishExec;
+    const sessionSecrets = [env.YAGNI_TOKEN, env.GH_ENTERPRISE_TOKEN].filter((value) => Boolean(value));
+    const scan = cloud
+        ? (scanCwd, signal, skip) => scanChange(scanCwd, { exec, sessionSecrets }, skip, signal)
+        : undefined;
+    if (gateOpts || baseline || cloud) {
+        const made = (deps.makeRunVerify ?? makeRunVerify)({
+            ...gateOpts,
+            ...(baseline ? { baseline } : {}),
+            ...(scan ? { scanChange: scan } : {}),
+        });
+        gate = made;
+        runVerify = async (verifyCwd, signal, baselinePaths) => {
+            const outcome = await made(verifyCwd, signal, baselinePaths);
+            if (outcome.ran)
+                preexistingFailures = outcome.preexisting ?? 0;
+            if (cloud)
+                lastVerify = { outcome, tree: treeKey(await snapshot(verifyCwd, signal)) };
+            return outcome;
+        };
+    }
     const pipelineDeps = {
         cwd,
         ...(fixRound ? { fixRound } : {}),
@@ -389,9 +536,13 @@ export async function runHeadlessGo(argv, deps = {}) {
         ...(budget ? { budget } : {}),
         ...(deps.stages ? { stages: deps.stages } : {}),
         grounded: deps.grounded ?? grounding,
+        ...(lane ? { lane } : {}),
         ...(mission ? { mission } : {}),
         ...(runVerify ? { runVerify } : {}),
-        ...(continuation ? { continuation: { stageAtStop: continuation.stageAtStop } } : {}),
+        ...(baseline ? { runWorkstreamCheck: makeWorkstreamCheck({ baseline }) } : {}),
+        // A cloud execution never starts on an earlier attempt's uncommitted
+        // edits: that work is on the branch, so its tree baselines as it is.
+        ...(continuation && !cloud ? { continuation: { stageAtStop: continuation.stageAtStop } } : {}),
         ...(resumeFrom ? { resumeFrom } : {}),
         onEvent: (ev, tag) => {
             deps.onEvent?.(ev, tag);
@@ -424,19 +575,83 @@ export async function runHeadlessGo(argv, deps = {}) {
                 emit({ type: "pipeline_log", event, ...(data === undefined ? {} : { data }) });
         },
     };
+    // A cloud session's start: the commit it builds on (its result's `baseSha`)
+    // and the tree's pre-run dirt (an install's lockfile churn), which never
+    // lands in its commit.
+    const startTree = cloud ? await snapshot(cwd, deps.signal) : undefined;
+    const baseSha = startTree?.head ?? "";
+    const preRunDirt = startTree ? parseChangedPaths(startTree.status) : [];
+    /** The cloud session's last act (cloud.ts `completeCloudSession`), mirrored on the stream. */
+    const completeCloud = async (session, ran) => {
+        const verifyGate = gate;
+        const done = await completeCloudSession({
+            identity: session.identity,
+            outDir: session.outDir,
+            stage: session.stage,
+            cwd,
+            baseSha,
+            preRunDirt,
+            ...(mission?.plan ? { plan: mission.plan } : {}),
+            roundsDone: continuation?.reviewRoundsDone ?? 0,
+            ...(lastVerify ? { lastVerify } : {}),
+            tree: async () => treeKey(await snapshot(cwd, deps.signal)),
+            // The checks run commands and may take minutes: with a deadline they
+            // need some of it left. The scan below runs no model and always runs.
+            ...(verifyGate
+                ? {
+                    reverify: async () => {
+                        const left = budget?.deadlineMs === undefined
+                            ? undefined
+                            : budget.deadlineMs - (deps.now ?? Date.now)();
+                        if (deps.signal?.aborted || (left !== undefined && left < FINAL_VERIFY_MIN_LEFT_MS))
+                            return null;
+                        return verifyGate(cwd, deps.signal, preRunDirt);
+                    },
+                }
+                : {}),
+            scan: () => scanChange(cwd, { exec, sessionSecrets }, preRunDirt),
+            planPaths: (planText) => baselineDirs(cwd, planPaths(planText), readFile).map((dir) => relative(cwd, dir) || "."),
+            exec,
+            writeFile: deps.writeFile ?? writeFileSync,
+        }, ran);
+        const result = "result" in ran ? ran.result : undefined;
+        const headless = result
+            ? buildResult(result, {
+                ...(args.runId ? { runId: args.runId } : {}),
+                ...(tierCap ? { tierCap } : {}),
+                preexistingFailures,
+            })
+            : undefined;
+        emit({ type: "pipeline_result", ...headless, ...done.attempt });
+        return {
+            exitCode: done.ok ? HEADLESS_GO_EXIT.verified : HEADLESS_GO_EXIT.unverified,
+            ...(headless ? { result: headless } : {}),
+            ...("error" in ran ? { error: ran.error } : {}),
+        };
+    };
     // A mission's tree is the only copy of its work until the host commits it,
-    // so it is snapshotted for the host to recover from (treeSnapshot.ts).
-    const stopSnapshots = mission
+    // so it is snapshotted for the host to recover from (treeSnapshot.ts). A
+    // cloud execution that builds is snapshotted the same way until it commits.
+    // It stops before a cloud session commits, so its last snapshot is the
+    // tree being committed, and only once.
+    const snapshots = (cloud ? cloudStage !== "plan" : mission)
         ? (deps.startTreeSnapshots ?? startTreeSnapshots)(cwd, {
             onError: (message) => writeErr(`Working-tree checkpoint failed (the run continues without it): ${message}`),
         })
         : null;
+    let stopping;
+    const stopSnapshots = () => (stopping ??= snapshots?.() ?? Promise.resolve());
     try {
         const result = await runPipeline(files.ticket, pipelineDeps);
+        if (cloud) {
+            await stopSnapshots();
+            return await completeCloud(cloud, { result });
+        }
         const headless = buildResult(result, {
             ...(args.runId ? { runId: args.runId } : {}),
             ...(tierCap ? { tierCap } : {}),
             ...(mission ? { missionMode: true } : {}),
+            preexistingFailures,
         });
         emit({ type: "pipeline_result", ...headless });
         return {
@@ -449,10 +664,19 @@ export async function runHeadlessGo(argv, deps = {}) {
         const stage = err?.stageId;
         emit({ type: "pipeline_error", ...(stage ? { stage } : {}), message });
         writeErr(message);
+        if (cloud) {
+            await stopSnapshots();
+            const partial = err instanceof PipelineStageError ? err.partial : [];
+            return await completeCloud(cloud, { error: message, partial });
+        }
         return { exitCode: HEADLESS_GO_EXIT.unverified, error: message };
     }
     finally {
-        await stopSnapshots?.();
+        await stopSnapshots();
     }
 }
+/** A tree as the cloud session compares it: HEAD and the porcelain status. */
+function treeKey(snapshot) {
+    return `${snapshot.head}\n${snapshot.status}`;
+}
 //# sourceMappingURL=headlessGo.js.map

package/dist/extension/pipeline/orchestrator.d.ts

@@ -32,7 +32,7 @@ import { type ResilienceAttemptRecord, type RunStageFn } from "./resilience.js";
 import { runStage as defaultRunStage } from "./runner.js";
 import { type VerifyOutcome, type WorkstreamCheckResult, type WorkstreamCheckTarget } from "./verify.js";
 import { snapshotWorkspace as defaultSnapshotWorkspace } from "./workspace.js";
-import { type CheckpointStore, type FanoutBudgetVerdict, type FanoutMode, type Finding, type PipelineStage, type JsonEvent, type PipelineProgress, type PipelineResult, type ResiliencePolicy, type ResumePlan, type StageId, type StageResult, type StageTag } from "./types.js";
+import { type CheckpointStore, type FanoutBudgetVerdict, type FanoutMode, type Finding, type PipelineStage, type JsonEvent, type PipelineLane, type PipelineProgress, type PipelineResult, type ResiliencePolicy, type ResumePlan, type StageId, type StageResult, type StageTag } from "./types.js";
 /** Each review round's findings as the host stores them: bounded, messages clipped. */
 export declare const MAX_ROUND_ITEMS = 20;
 export interface RoundFindingItem {
@@ -87,10 +87,16 @@ export interface RunPipelineDeps {
     /** Wall clock for the budget's deadline checks (epoch ms). Defaults to `Date.now`; injected in tests. */
     now?: () => number;
     /**
-     * M6 eval: the stage list to run. Defaults to selectStages("full"); the blind
+     * M6 eval: the stage list to run. Defaults to the lane's; the blind
      * lane passes a grounding-tool-stripped copy (see eval.ts#blindStages).
      */
     stages?: PipelineStage[];
+    /**
+     * The lane's stage list and loop rules (stages.ts). Defaults to `FULL_LANE`
+     * (the diamond, three lenses, two rounds); headless `--cloud` passes the
+     * cloud lane (one writer, one reviewer, four rounds, a plan that ends the run).
+     */
+    lane?: PipelineLane;
     /**
      * M6 eval: when false, run the BLIND lane (grounding-free personas via
      * personaBody's grounded flag, paired with grounding-stripped stages). Defaults