@yagni-app/code 0.3.2 → 0.3.3

package/dist/extension/pipeline/headlessGo.js

@@ -0,0 +1,333 @@
+/**
+ * The headless front door to the /go pipeline (spec: sandbox harness parity).
+ *
+ * `/go` is an interactive pi slash command and pi's print mode ignores slash
+ * commands, so until now the ONLY way to drive the pipeline from a script was
+ * to import `runPipeline` directly (`scripts/eval-go-harness.ts` did exactly
+ * that). That gap is why the cloud mission sandbox ran a single flat model
+ * session instead of the product's staged pipeline. This module closes it:
+ *
+ *   yagni go --headless --ticket-file <p> [--plan-file <p>] [--memo-file <p>]
+ *            [--run-id <id>] [--cwd <p>] [--json]
+ *
+ * It is the SAME `runPipeline` path the interactive command drives (no forked
+ * driver) with the interactive-only machinery left out: no worktree, no run
+ * registry, no run session mint (the caller already owns the run row and passes
+ * its id with `--run-id`), no checkpoint journal, no terminal UI.
+ *
+ * MISSION MODE (`--plan-file`, optionally `--memo-file`): the factory already
+ * produced the plan and a human approved it at the mission's plan gate, so the
+ * pipeline skips its own map/plan stages and enters at implement on that plan,
+ * with the scoping memo as the repo context the map brief would have given (see
+ * mission.ts for the pure rules). Delivery is NOT ours in mission mode: the
+ * FINISH stage is a `/go`-session step and is never driven here, so a mission
+ * 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.
+ *
+ * Output contract:
+ *  - `--json`: one NDJSON line per event on stdout. Child events are the pi
+ *    `--mode json` objects VERBATIM plus an additive `yagni` attribution key
+ *    (stage / lens / round), so the event vocabulary is unchanged; pipeline-level
+ *    lines carry their own `pipeline_*` types.
+ *  - `{type:"pipeline_fanout", stage, phase, fanout?, children?, fixTurns?}`:
+ *    the implement diamond's recording beats. Interactive `/go` POSTs these to
+ *    its run session; headlessly there IS no session, so the SAME
+ *    `makeFanoutBeats` thread rides the stream instead and the mission
+ *    collector folds them back onto the Run. Without this a cloud mission would
+ *    record no partition decision, no per-workstream row, and no fix turn.
+ *  - 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.
+ *  - 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.
+ *
+ * `YAGNI_GO_TIER_CAP` (eval + template-smoke lanes) is resolved here for the
+ * result object and forwarded on the child env; the clamp itself is applied
+ * centrally in `runStage` (see tierCap.ts). `YAGNI_GO_FANOUT` is read the same
+ * way and pins the implement diamond for a benchmark lane (see fanout.ts).
+ */
+import { readFileSync } from "node:fs";
+import { resolveFanoutMode } from "./fanout.js";
+import { makeFanoutBeats } from "./fanoutBeats.js";
+import { normalizeMission } from "./mission.js";
+import { runPipeline as defaultRunPipeline } from "./orchestrator.js";
+import { parseTierCap, TIER_CAP_ENV } from "./tierCap.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>] [--run-id <id>] [--cwd <path>] [--json]";
+/**
+ * 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 };
+const VALUE_FLAGS = {
+    "--ticket-file": "ticketFile",
+    "--plan-file": "planFile",
+    "--memo-file": "memoFile",
+    "--run-id": "runId",
+    "--cwd": "cwd",
+};
+/** A token is flag-shaped when it looks like `--word` (mirrors goFlags.ts). */
+const FLAG_SHAPE = /^--[A-Za-z][\w-]*$/;
+/**
+ * Parse the argv remainder after `go`. Accepts both `--flag value` and
+ * `--flag=value`; unknown flags and stray positionals are collected rather than
+ * silently absorbed, so a typo fails loudly instead of running the wrong thing.
+ */
+export function parseHeadlessGoArgs(argv) {
+    const args = {
+        headless: false,
+        json: false,
+        unknownFlags: [],
+        positionals: [],
+        missingValues: [],
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token)
+            continue;
+        const eq = token.indexOf("=");
+        const name = eq > 0 ? token.slice(0, eq) : token;
+        const inlineValue = eq > 0 ? token.slice(eq + 1) : undefined;
+        if (name === "--headless") {
+            args.headless = true;
+            continue;
+        }
+        if (name === "--json") {
+            args.json = true;
+            continue;
+        }
+        const key = VALUE_FLAGS[name];
+        if (key) {
+            const next = inlineValue ?? argv[i + 1];
+            if (!next || FLAG_SHAPE.test(next)) {
+                args.missingValues.push(name);
+            }
+            else {
+                args[key] = next;
+                if (inlineValue === undefined)
+                    i++;
+            }
+            continue;
+        }
+        if (FLAG_SHAPE.test(name))
+            args.unknownFlags.push(name);
+        else
+            args.positionals.push(token);
+    }
+    return args;
+}
+/** The argument problem, or undefined when the invocation is usable. */
+export function validateHeadlessGoArgs(args) {
+    if (args.unknownFlags.length > 0) {
+        return `Unknown flag${args.unknownFlags.length === 1 ? "" : "s"}: ${args.unknownFlags.join(", ")}.`;
+    }
+    if (args.positionals.length > 0) {
+        return `Unexpected argument${args.positionals.length === 1 ? "" : "s"}: ${args.positionals.join(", ")}. The ticket is passed as a file.`;
+    }
+    if (args.missingValues.length > 0) {
+        return `Missing value for ${args.missingValues.join(", ")}.`;
+    }
+    if (!args.headless)
+        return "yagni go is headless-only: pass --headless (use /go inside a session for the interactive run).";
+    if (!args.ticketFile)
+        return "Missing --ticket-file.";
+    return undefined;
+}
+const isBlocking = (f) => f.severity === "critical" || f.severity === "high";
+/**
+ * Fold the pipeline result into the reported per-stage usage table. Build/fix
+ * stages come from `stages`, review lenses from each round's `lensResults`
+ * (tagged with their round). Rows are grouped, not strictly chronological: a
+ * later round's fix sits with the build stages, which is honest for a usage
+ * table and avoids inventing timestamps the pipeline never recorded.
+ */
+function stageRows(result) {
+    const rows = result.stages.map((s) => ({
+        stage: s.stageId,
+        ...(s.tier ? { tier: s.tier } : {}),
+        usage: s.usage,
+    }));
+    for (const round of result.rounds) {
+        for (const lensResult of round.lensResults) {
+            rows.push({
+                stage: lensResult.stageId,
+                ...(lensResult.tier ? { tier: lensResult.tier } : {}),
+                round: round.round,
+                usage: lensResult.usage,
+            });
+        }
+    }
+    return rows;
+}
+function buildResult(result, ctx) {
+    // FINISH is suppressed in mission mode (delivery belongs to the mission's
+    // prHandoff), so a mission result never carries a commit or a PR — and if some
+    // caller's pipeline produced one anyway, this run does not claim it as its
+    // delivery. Outside mission mode the FINISH info passes through untouched.
+    const finish = ctx.missionMode ? undefined : result.finish;
+    return {
+        ok: result.stopReason === "clean",
+        stopReason: result.stopReason,
+        rounds: result.rounds.length,
+        findings: result.findings.length,
+        blocking: result.findings.filter(isBlocking).length,
+        stages: stageRows(result),
+        ...(ctx.runId ? { runId: ctx.runId } : {}),
+        ...(ctx.tierCap ? { tierCap: ctx.tierCap } : {}),
+        ...(ctx.missionMode ? { missionMode: true } : {}),
+        ...(finish?.commitSha ? { commitSha: finish.commitSha } : {}),
+        ...(finish?.prUrl ? { prUrl: finish.prUrl } : {}),
+        ...(result.verifyNote ? { verifyNote: result.verifyNote } : {}),
+        ...(result.verifyCommand ? { verifyCommand: result.verifyCommand } : {}),
+    };
+}
+/** Attribution rider for a streamed child event (never overwrites pi's own keys). */
+function attribution(tag) {
+    return {
+        stage: tag.stageId,
+        ...(tag.lens ? { lens: tag.lens } : {}),
+        ...(tag.round ? { round: tag.round } : {}),
+    };
+}
+/**
+ * Run the pipeline headlessly. Never throws: every failure resolves to an exit
+ * code and an honest final line, so the sandbox harness and the smoke gate can
+ * read one contract.
+ */
+export async function runHeadlessGo(argv, deps = {}) {
+    const write = deps.write ?? ((line) => void process.stdout.write(`${line}\n`));
+    const writeErr = deps.writeErr ?? ((line) => void process.stderr.write(`${line}\n`));
+    const readFile = deps.readFile ?? ((path) => readFileSync(path, "utf8"));
+    const runPipeline = deps.runPipeline ?? defaultRunPipeline;
+    const env = deps.env ?? process.env;
+    const args = parseHeadlessGoArgs(argv);
+    const problem = validateHeadlessGoArgs(args);
+    if (problem) {
+        writeErr(problem);
+        writeErr(HEADLESS_GO_USAGE);
+        return { exitCode: HEADLESS_GO_EXIT.usage, error: problem };
+    }
+    // Read every named file up front: an unreadable plan is a hard stop, not a
+    // silent fall back to running the pipeline's own planning (which would
+    // discard the approved plan the mission gate produced).
+    const read = (path, label) => {
+        try {
+            return readFile(path);
+        }
+        catch (err) {
+            return { error: `Could not read the ${label} at ${path}: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    };
+    const files = {
+        ticket: undefined,
+        plan: undefined,
+        memo: undefined,
+    };
+    for (const [label, path] of [
+        ["ticket", args.ticketFile],
+        ["plan", args.planFile],
+        ["memo", args.memoFile],
+    ]) {
+        if (!path)
+            continue;
+        const contents = read(path, `${label} file`);
+        if (typeof contents !== "string") {
+            writeErr(contents.error);
+            return { exitCode: HEADLESS_GO_EXIT.usage, error: contents.error };
+        }
+        files[label] = contents.trim();
+    }
+    if (!files.ticket) {
+        const message = `The ticket file ${args.ticketFile} is empty; there is nothing to run.`;
+        writeErr(message);
+        return { exitCode: HEADLESS_GO_EXIT.usage, error: message };
+    }
+    const rawCap = env[TIER_CAP_ENV];
+    const tierCap = parseTierCap(rawCap);
+    if (rawCap?.trim() && !tierCap) {
+        writeErr(`Ignoring ${TIER_CAP_ENV}="${rawCap}": not a tier (peak, advanced, standard, efficient). Running uncapped.`);
+    }
+    const cwd = args.cwd ?? deps.cwd ?? process.cwd();
+    const emit = (obj) => write(JSON.stringify(obj));
+    const stream = args.json;
+    const childEnv = {
+        ...(deps.childEnv ?? env),
+        ...(tierCap ? { [TIER_CAP_ENV]: tierCap } : {}),
+    };
+    // 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 implement diamond's recording thread, per RUN. Interactive /go hands
+    // these beats to its run session; there is no session here, so they ride the
+    // NDJSON stream and the mission collector folds them onto the Run instead.
+    const fanoutBeats = makeFanoutBeats();
+    const pipelineDeps = {
+        cwd,
+        childEnv,
+        // `go.fanout` rides the same env surface as the tier cap, so a benchmark lane
+        // pins the implement diamond without a second flag (spec decision 8).
+        fanout: resolveFanoutMode(env),
+        checkpointMeta: {
+            // No journal is written headlessly (no checkpoint store is injected), so
+            // this key only identifies the run in the records the pipeline builds.
+            sessionKey: `headless:${args.runId ?? cwd}`,
+            ...(args.runId ? { runId: args.runId } : {}),
+        },
+        ...(deps.signal ? { signal: deps.signal } : {}),
+        ...(deps.budget ? { budget: deps.budget } : {}),
+        ...(deps.stages ? { stages: deps.stages } : {}),
+        ...(deps.grounded !== undefined ? { grounded: deps.grounded } : {}),
+        ...(mission ? { mission } : {}),
+        onEvent: (ev, tag) => {
+            deps.onEvent?.(ev, tag);
+            if (stream)
+                emit({ ...ev, yagni: attribution(tag) });
+        },
+        onProgress: (p) => {
+            if (!stream)
+                return;
+            emit({ type: "pipeline_progress", progress: p });
+            // Additive, and only for the diamond's own signals: a beat is emitted
+            // when the partition resolves, when a child changes state, and when a fix
+            // turn lands. Anything else produces no beat at all.
+            const beat = fanoutBeats.apply(p);
+            if (beat)
+                emit({ type: "pipeline_fanout", ...beat });
+        },
+        onStage: (s) => {
+            // `output` carries the plan stage's full text; the stream reports the
+            // boundary, never the body.
+            const { output: _output, ...boundary } = s;
+            if (stream)
+                emit({ type: "pipeline_stage", ...boundary });
+        },
+        logger: (event, data) => {
+            deps.logger?.(event, data);
+            if (stream)
+                emit({ type: "pipeline_log", event, ...(data === undefined ? {} : { data }) });
+        },
+    };
+    try {
+        const result = await runPipeline(files.ticket, pipelineDeps);
+        const headless = buildResult(result, {
+            ...(args.runId ? { runId: args.runId } : {}),
+            ...(tierCap ? { tierCap } : {}),
+            ...(mission ? { missionMode: true } : {}),
+        });
+        emit({ type: "pipeline_result", ...headless });
+        return {
+            exitCode: headless.ok ? HEADLESS_GO_EXIT.verified : HEADLESS_GO_EXIT.unverified,
+            result: headless,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const stage = err?.stageId;
+        emit({ type: "pipeline_error", ...(stage ? { stage } : {}), message });
+        writeErr(message);
+        return { exitCode: HEADLESS_GO_EXIT.unverified, error: message };
+    }
+}
+//# sourceMappingURL=headlessGo.js.map

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

@@ -24,7 +24,7 @@
  * `renderTemplate` does the {ticket}/{previous} substitution, mirroring the
  * chain's `step.task.replace(/{previous}/g, …)`.
  */
-import type { PipelineStage, ReviewLens } from "./types.js";
+import type { ModelTier, PipelineStage, ReviewLens } from "./types.js";
 /**
  * Anti-fabrication preamble injected as the first `--append-system-prompt` on
  * every child pi process (both /go stages and subagent tool calls). The
@@ -47,12 +47,18 @@ export declare function renderTemplate(tmpl: string, vars: {
 /**
  * Build the pi passthrough argv for one stage (from `--mode` onward). The
  * positional rendered prompt is always the last arg, prefixed `Task: `.
+ *
+ * `ctx.tierCap` (the resolved `YAGNI_GO_TIER_CAP` ceiling, absent on a normal
+ * run) lowers the emitted `--model` to the cap; it never promotes a stage above
+ * its own tier. Passed IN rather than read from the environment here so this
+ * builder stays pure — `runStage` owns the env read.
  */
 export declare function buildStageInvocation(stage: PipelineStage, ctx: {
     ticket: string;
     previous?: string;
     promptFilePath: string;
     lens?: ReviewLens;
+    tierCap?: ModelTier;
 }): string[];
 /**
  * Prepend the grounding args (the pi cli script, our extension, and the default

package/dist/extension/pipeline/invocation.js

@@ -24,6 +24,7 @@
  * `renderTemplate` does the {ticket}/{previous} substitution, mirroring the
  * chain's `step.task.replace(/{previous}/g, …)`.
  */
+import { clampTier } from "./tierCap.js";
 /**
  * Anti-fabrication preamble injected as the first `--append-system-prompt` on
  * every child pi process (both /go stages and subagent tool calls). The
@@ -51,6 +52,11 @@ export function renderTemplate(tmpl, vars) {
 /**
  * Build the pi passthrough argv for one stage (from `--mode` onward). The
  * positional rendered prompt is always the last arg, prefixed `Task: `.
+ *
+ * `ctx.tierCap` (the resolved `YAGNI_GO_TIER_CAP` ceiling, absent on a normal
+ * run) lowers the emitted `--model` to the cap; it never promotes a stage above
+ * its own tier. Passed IN rather than read from the environment here so this
+ * builder stays pure — `runStage` owns the env read.
  */
 export function buildStageInvocation(stage, ctx) {
     const task = renderTemplate(stage.taskTemplate, {
@@ -63,7 +69,7 @@ export function buildStageInvocation(stage, ctx) {
         "-p",
         "--no-session",
         "--model",
-        stage.model,
+        clampTier(stage.model, ctx.tierCap),
         "--tools",
         stage.tools.join(","),
         "--append-system-prompt",

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

@@ -0,0 +1,55 @@
+/**
+ * PURE mission-mode rules for the /go pipeline (spec: sandbox harness parity).
+ *
+ * A cloud mission arrives with work the factory has ALREADY done: a plan a human
+ * approved at the mission's plan gate, and (when the work item was scoped) a
+ * cached scoping memo written against the base commit the run starts from.
+ * Re-running the pipeline's own map/plan stages would silently discard the
+ * approved plan and hollow out that gate, so an injected plan makes the pipeline
+ * enter at implement instead.
+ *
+ * The three rules, each one line:
+ *  - an injected PLAN skips map and plan; the plan itself seeds implement,
+ *  - an injected MEMO stands in for the map stage's repo brief, so map is
+ *    skipped whenever either input is present,
+ *  - a memo WITHOUT a plan seeds the (still running) plan stage as its repo map.
+ *
+ * Repo context is OPTIONAL by contract: with a plan and no memo, implement runs
+ * from the plan alone and the seed says nothing about a repo brief that does not
+ * exist. Stages must never assume a map brief was produced in mission mode.
+ *
+ * Delivery is NOT this module's business, but the invariant lives with it: in
+ * mission mode the pipeline's FINISH stage does not run (the mission's own
+ * prHandoff owns the commit, the push and the PR), so a mission run ends at the
+ * reviewed candidate diff.
+ */
+import type { StageId } from "./types.js";
+/**
+ * The mission inputs, as read from `--plan-file` / `--memo-file`. Both optional:
+ * a mission may carry a plan with no memo, and (rarely) a memo with no plan.
+ */
+export interface MissionInputs {
+    /** The plan markdown a human approved at the mission's plan gate. */
+    plan?: string;
+    /** The cached scoping memo for the work item at the approved base SHA. */
+    memo?: string;
+}
+/** Trim the inputs and drop the blank ones; undefined when nothing usable is left. */
+export declare function normalizeMission(mission: MissionInputs | undefined): MissionInputs | undefined;
+/** True when the run carries mission inputs at all (already-normalized or not). */
+export declare function isMissionMode(mission: MissionInputs | undefined): boolean;
+/**
+ * The build stages this mission does NOT run. Map goes whenever there is mission
+ * context to enter on; plan goes only when a real approved plan was injected, so
+ * a memo-only mission still gets a planning pass (grounded on the memo) rather
+ * than sending the worker in with no plan at all.
+ */
+export declare function missionSkippedStages(mission: MissionInputs | undefined): StageId[];
+/**
+ * The `{previous}` handoff the first surviving build stage is seeded with: the
+ * approved plan (implement's "Plan:" slot), with the memo appended as clearly
+ * labelled repo context when there is one; or the memo alone when the plan stage
+ * still runs and the memo is its repo map.
+ */
+export declare function missionSeed(mission: MissionInputs | undefined): string | undefined;
+//# sourceMappingURL=mission.d.ts.map

package/dist/extension/pipeline/mission.js

@@ -0,0 +1,70 @@
+/**
+ * PURE mission-mode rules for the /go pipeline (spec: sandbox harness parity).
+ *
+ * A cloud mission arrives with work the factory has ALREADY done: a plan a human
+ * approved at the mission's plan gate, and (when the work item was scoped) a
+ * cached scoping memo written against the base commit the run starts from.
+ * Re-running the pipeline's own map/plan stages would silently discard the
+ * approved plan and hollow out that gate, so an injected plan makes the pipeline
+ * enter at implement instead.
+ *
+ * The three rules, each one line:
+ *  - an injected PLAN skips map and plan; the plan itself seeds implement,
+ *  - an injected MEMO stands in for the map stage's repo brief, so map is
+ *    skipped whenever either input is present,
+ *  - a memo WITHOUT a plan seeds the (still running) plan stage as its repo map.
+ *
+ * Repo context is OPTIONAL by contract: with a plan and no memo, implement runs
+ * from the plan alone and the seed says nothing about a repo brief that does not
+ * exist. Stages must never assume a map brief was produced in mission mode.
+ *
+ * Delivery is NOT this module's business, but the invariant lives with it: in
+ * mission mode the pipeline's FINISH stage does not run (the mission's own
+ * prHandoff owns the commit, the push and the PR), so a mission run ends at the
+ * reviewed candidate diff.
+ */
+const REPO_CONTEXT_HEADING = "## Repo context (cached scoping memo)";
+const REPO_CONTEXT_NOTE = "This run entered at implement, so no map stage ran. The memo below is the repo brief that stands in for it: " +
+    "it was cached when this work item was scoped, against the base commit this run started from. " +
+    "Treat it as a starting point and verify anything you lean on.";
+/** Trim the inputs and drop the blank ones; undefined when nothing usable is left. */
+export function normalizeMission(mission) {
+    const plan = mission?.plan?.trim();
+    const memo = mission?.memo?.trim();
+    if (!plan && !memo)
+        return undefined;
+    return { ...(plan ? { plan } : {}), ...(memo ? { memo } : {}) };
+}
+/** True when the run carries mission inputs at all (already-normalized or not). */
+export function isMissionMode(mission) {
+    return normalizeMission(mission) !== undefined;
+}
+/**
+ * The build stages this mission does NOT run. Map goes whenever there is mission
+ * context to enter on; plan goes only when a real approved plan was injected, so
+ * a memo-only mission still gets a planning pass (grounded on the memo) rather
+ * than sending the worker in with no plan at all.
+ */
+export function missionSkippedStages(mission) {
+    const normalized = normalizeMission(mission);
+    if (!normalized)
+        return [];
+    return normalized.plan ? ["map", "plan"] : ["map"];
+}
+/**
+ * The `{previous}` handoff the first surviving build stage is seeded with: the
+ * approved plan (implement's "Plan:" slot), with the memo appended as clearly
+ * labelled repo context when there is one; or the memo alone when the plan stage
+ * still runs and the memo is its repo map.
+ */
+export function missionSeed(mission) {
+    const normalized = normalizeMission(mission);
+    if (!normalized)
+        return undefined;
+    if (!normalized.plan)
+        return normalized.memo;
+    if (!normalized.memo)
+        return normalized.plan;
+    return `${normalized.plan}\n\n${REPO_CONTEXT_HEADING}\n\n${REPO_CONTEXT_NOTE}\n\n${normalized.memo}`;
+}
+//# sourceMappingURL=mission.js.map

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

@@ -3,7 +3,11 @@
  *
  * Sequences `runStage` for the build stages (map → plan → implement), threading
  * each stage's `finalOutput` into the next as `{previous}` (mirrors the subagent
- * example's chain). Then it runs the bounded review→fix LOOP: each round fans the
+ * example's chain). In MISSION mode (`deps.mission`, from the headless entry's
+ * `--plan-file` / `--memo-file`) the build half is entered part-way: an approved
+ * plan skips map + plan and seeds implement, an injected memo stands in for the
+ * map brief, and the review→fix loop below runs exactly as it always does — see
+ * mission.ts. Then it runs the bounded review→fix LOOP: each round fans the
  * review stage out across the 3 lenses (parallel, bounded by MAX_CONCURRENCY),
  * parses each lens with `parseFindings` (with ONE cheap format-recovery re-ask
  * for a healthy lens that broke the findings contract — spec §3e), unions them,
@@ -21,10 +25,11 @@
  * findings — i.e. a false "reviewed and clean").
  */
 import { type RunBudget } from "./budget.js";
+import { type MissionInputs } from "./mission.js";
 import { runStage as defaultRunStage } from "./runner.js";
-import { type VerifyOutcome } from "./verify.js";
+import { type VerifyOutcome, type WorkstreamCheckResult, type WorkstreamCheckTarget } from "./verify.js";
 import { snapshotWorkspace as defaultSnapshotWorkspace } from "./workspace.js";
-import { type CheckpointStore, type PipelineStage, type JsonEvent, type PipelineProgress, type PipelineResult, type ResumePlan, type StageId, type StageResult, type StageTag } from "./types.js";
+import { type CheckpointStore, type FanoutBudgetVerdict, type FanoutMode, type PipelineStage, type JsonEvent, type PipelineProgress, type PipelineResult, type ResumePlan, type StageId, type StageResult, type StageTag } from "./types.js";
 export interface RunPipelineDeps {
     cwd: string;
     signal?: AbortSignal;
@@ -38,6 +43,15 @@ export interface RunPipelineDeps {
      * and records an honest note. Injected as a whole for unit testing.
      */
     runVerify?: (cwd: string, signal?: AbortSignal, baselinePaths?: string[]) => Promise<VerifyOutcome>;
+    /**
+     * The implement diamond's per-workstream scoped typecheck (spec decision 6):
+     * each workstream's claims resolved to package dirs and checked THERE, so a
+     * broken workstream is attributed by name before the merged tree is verified as
+     * a whole. Defaults to the real `makeWorkstreamCheck`; injected as a whole for
+     * unit testing, exactly like `runVerify`. Never consulted on the single-writer
+     * path (one builder owns everything, so there is nothing to attribute).
+     */
+    runWorkstreamCheck?: (cwd: string, targets: WorkstreamCheckTarget[], signal?: AbortSignal) => Promise<WorkstreamCheckResult[]>;
     /**
      * The REAL ticket brief (verbatim title + description) resolved from the ticket
      * reference, injected into every stage's `{ticket}` prompt slot so the agents plan
@@ -112,6 +126,37 @@ export interface RunPipelineDeps {
      * tree) and re-enters the bounded review→fix loop at `resumeFrom.round`.
      */
     resumeFrom?: ResumePlan;
+    /**
+     * Mission-mode inputs, populated by the headless entry point's `--plan-file`
+     * / `--memo-file` (spec: sandbox harness parity). `plan` is the plan the
+     * human already approved at the mission's plan gate, and `memo` is the cached
+     * scoping memo that stands in for the map stage's repo brief. Both are
+     * OPTIONAL by contract: mission mode must degrade honestly when repo context
+     * is absent rather than assume a map brief exists. Carried as one object so
+     * the mission-mode path reads a single field; absent on every interactive run.
+     * The stage-skipping and seeding rules are pure and live in `mission.ts`.
+     */
+    mission?: MissionInputs;
+    /**
+     * `go.fanout` (spec decision 8). `auto` (the default) runs the partitioner and
+     * lets its conservative verdict stand; `always` pins the diamond for benchmark
+     * lanes — it biases the partition prompt and overrides a budget denial, but it
+     * still cannot fan without a partition the orchestrator actually produced.
+     */
+    fanout?: FanoutMode;
+    /**
+     * The fan-out budget seam (spec decision 8). Consulted ONCE, only when the
+     * partition came back `fan`: a denial degrades the stage to single-writer with
+     * the seam's own reason recorded. The machinery behind it is a separate
+     * workstream; an ABSENT seam allows, so nothing here waits on it.
+     */
+    fanoutBudget?: () => Promise<FanoutBudgetVerdict> | FanoutBudgetVerdict;
+    /**
+     * Live ultra-mode probe (/ultra), mirroring the general subagent tool's seam:
+     * it widens the diamond's concurrent-builder ceiling from 4 to 8. It changes
+     * NOTHING else — not the width the partitioner may choose, not a tier.
+     */
+    isUltra?: () => boolean;
     /** Identity stamped onto every checkpoint record (run key + backend handle). */
     checkpointMeta?: {
         sessionKey: string;