@yagni-app/code 0.3.1 → 0.3.3

package/dist/extension/pipeline/fanout.js

@@ -0,0 +1,248 @@
+/**
+ * PURE partition contract for the implement diamond — the analogue of
+ * `findings.ts` for the fan-out orchestrator's output.
+ *
+ * `parsePartition` reads the orchestrator child's fenced ```partition JSON block
+ * and validates it against the contract (spec "Partition contract"): mode legal,
+ * width in {2,4,8} with a matching workstream count, per-workstream tier legal
+ * (absent defaults to `standard`), every workstream named + tasked with at least
+ * one file claim, and claims pairwise DISJOINT across workstreams.
+ *
+ * Two failure kinds, deliberately distinct because the pipeline treats them
+ * differently:
+ *  - SOFT (`hard: false`): malformed block, illegal field, missing reason. The
+ *    caller gets one cheap-tier format re-ask and then degrades to single-writer.
+ *    A partition is never guessed.
+ *  - HARD (`hard: true`): overlapping claims. Two writers on one file is the one
+ *    thing the design refuses to discover at merge time, so it fails the stage at
+ *    partition time with the colliding paths and workstreams named. The caller
+ *    (orchestrator) raises it as a `PipelineStageError`; keeping the throw out of
+ *    here keeps this module pure and free of an import cycle.
+ *
+ * `auditClaims` is the post-fan check: claims are path PREFIXES (a directory
+ * claims its whole subtree), so a file a builder legitimately created inside its
+ * claimed directory is in-claim, and anything else is named as a violation for
+ * the synthesizer to reconcile.
+ */
+/**
+ * The `go.fanout` knob's environment surface (spec decision 8), named the way
+ * `YAGNI_GO_TIER_CAP` is (see tierCap.ts): a run-wide /go setting an eval or
+ * benchmark lane pins from the outside. `always` forces the diamond attempt;
+ * unset (everywhere else) leaves the partitioner's own conservative verdict as
+ * the only thing that decides.
+ */
+export const FANOUT_MODE_ENV = "YAGNI_GO_FANOUT";
+/**
+ * Parse a raw env value into a mode. Unset, empty, or unrecognized all yield
+ * undefined so a caller can warn about a typo; {@link resolveFanoutMode} is what
+ * turns that into the safe `auto` default. A typo must never pin a lane.
+ */
+export function parseFanoutMode(raw) {
+    const normalized = raw?.trim().toLowerCase();
+    if (normalized === "auto" || normalized === "always")
+        return normalized;
+    return undefined;
+}
+/** The run's fan-out mode from an environment. Defaults to `auto`. */
+export function resolveFanoutMode(env) {
+    return parseFanoutMode(env[FANOUT_MODE_ENV]) ?? "auto";
+}
+/** The only legal fan widths (execution concurrency is capped separately by the session). */
+export const PARTITION_WIDTHS = [2, 4, 8];
+const TIERS = ["standard", "efficient"];
+function soft(reason) {
+    return { ok: false, hard: false, reason };
+}
+/** Extract the inner text of a fenced ```partition block, if present. */
+export function extractPartitionBlock(raw) {
+    const m = raw.match(/```partition[^\n]*\n([\s\S]*?)```/i);
+    return m ? m[1] : null;
+}
+/**
+ * Normalize a claim or changed path for prefix comparison: trim, convert
+ * backslashes, collapse doubled slashes, drop interior `.` segments, a leading
+ * `./`, and trailing slashes. Purely lexical — no filesystem access. Without
+ * the collapse, `packages//backend` and `packages/./backend` pass disjointness
+ * against `packages/backend` while claiming the same directory — the exact
+ * two-writers-one-file outcome the partition-time hard error exists to prevent.
+ */
+export function normalizeClaimPath(path) {
+    return path
+        .trim()
+        .replace(/\\/g, "/")
+        .split("/")
+        .filter((segment) => segment.length > 0 && segment !== ".")
+        .join("/");
+}
+/** True when `claim` is the path itself or a directory containing it. */
+export function claimCovers(claim, path) {
+    const c = normalizeClaimPath(claim);
+    const p = normalizeClaimPath(path);
+    if (!c || !p)
+        return false;
+    return p === c || p.startsWith(`${c}/`);
+}
+/** Reject claims that escape the repo, are absolute, or claim everything. */
+function claimIsLegal(claim) {
+    if (!claim || claim === "." || claim.startsWith("/") || claim.startsWith("\\"))
+        return false;
+    return !normalizeClaimPath(claim).split("/").includes("..");
+}
+function readWorkstream(value, index) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return `workstream ${index + 1} is not an object`;
+    }
+    const obj = value;
+    const name = typeof obj.name === "string" ? obj.name.trim() : "";
+    if (!name)
+        return `workstream ${index + 1} has no name`;
+    const task = typeof obj.task === "string" ? obj.task.trim() : "";
+    if (!task)
+        return `workstream "${name}" has no task`;
+    if (!Array.isArray(obj.files))
+        return `workstream "${name}" has no file claims`;
+    const files = [];
+    for (const entry of obj.files) {
+        if (typeof entry !== "string")
+            return `workstream "${name}" has a non-string file claim`;
+        // Legality reads the RAW entry: normalization collapses the leading `/`
+        // (and `\`) markers legality has to see.
+        const claim = normalizeClaimPath(entry);
+        if (!claim || !claimIsLegal(entry.trim())) {
+            return `workstream "${name}" has an illegal file claim: ${entry}`;
+        }
+        if (!files.includes(claim))
+            files.push(claim);
+    }
+    if (files.length === 0)
+        return `workstream "${name}" has no file claims`;
+    let tier = "standard";
+    if (obj.tier !== undefined) {
+        if (typeof obj.tier !== "string" || !TIERS.includes(obj.tier)) {
+            return `workstream "${name}" has an illegal tier: ${String(obj.tier)}`;
+        }
+        tier = obj.tier;
+    }
+    return { name, task, files, tier };
+}
+/**
+ * Find every pair of claims that collide across two workstreams. Prefix nesting
+ * counts: a workstream claiming `packages/backend/src` collides with a sibling
+ * claiming `packages/backend/src/routes/x.ts`.
+ */
+function findCollisions(workstreams) {
+    const collisions = [];
+    for (let i = 0; i < workstreams.length; i += 1) {
+        for (let j = i + 1; j < workstreams.length; j += 1) {
+            for (const a of workstreams[i].files) {
+                for (const b of workstreams[j].files) {
+                    if (claimCovers(a, b) || claimCovers(b, a)) {
+                        collisions.push({
+                            path: a,
+                            otherPath: b,
+                            workstreams: [workstreams[i].name, workstreams[j].name],
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return collisions;
+}
+function collisionReason(collisions) {
+    const parts = collisions.map((c) => c.path === c.otherPath
+        ? `${c.path} claimed by both ${c.workstreams[0]} and ${c.workstreams[1]}`
+        : `${c.path} (${c.workstreams[0]}) contains ${c.otherPath} (${c.workstreams[1]})`);
+    return `Overlapping file claims: ${parts.join("; ")}`;
+}
+/** Pull the JSON payload out of a partition fence, a json fence, or bare output. */
+function extractPayload(raw) {
+    const partition = extractPartitionBlock(raw);
+    if (partition !== null)
+        return partition.trim();
+    const json = raw.match(/```json[^\n]*\n([\s\S]*?)```/i);
+    if (json)
+        return json[1].trim();
+    const trimmed = raw.trim();
+    return trimmed.startsWith("{") ? trimmed : null;
+}
+/**
+ * Parse the orchestrator's raw output into a {@link PartitionDecision}. Never
+ * throws: an unusable block is a soft rejection (re-ask, then single-writer) and
+ * overlapping claims are the hard rejection the caller turns into a stage error.
+ */
+export function parsePartition(raw) {
+    if (!raw || !raw.trim())
+        return soft("empty partition output");
+    const payload = extractPayload(raw);
+    if (payload === null)
+        return soft("no ```partition block in the output");
+    let parsed;
+    try {
+        parsed = JSON.parse(payload);
+    }
+    catch {
+        return soft("the partition block is not valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return soft("the partition block is not a JSON object");
+    }
+    const obj = parsed;
+    const mode = obj.mode;
+    if (mode !== "fan" && mode !== "single") {
+        return soft(`illegal partition mode: ${String(mode)}`);
+    }
+    const reason = typeof obj.reason === "string" ? obj.reason.trim() : "";
+    if (!reason)
+        return soft("the partition block has no reason");
+    if (mode === "single")
+        return { ok: true, decision: { mode: "single", reason } };
+    const width = obj.width;
+    if (typeof width !== "number" || !PARTITION_WIDTHS.includes(width)) {
+        return soft(`illegal fan width: ${String(width)}`);
+    }
+    if (!Array.isArray(obj.workstreams))
+        return soft("a fan partition has no workstreams");
+    const workstreams = [];
+    for (const [index, entry] of obj.workstreams.entries()) {
+        const read = readWorkstream(entry, index);
+        if (typeof read === "string")
+            return soft(read);
+        if (workstreams.some((w) => w.name === read.name)) {
+            return soft(`duplicate workstream name: ${read.name}`);
+        }
+        workstreams.push(read);
+    }
+    if (workstreams.length !== width) {
+        return soft(`fan width ${width} does not match ${workstreams.length} workstreams`);
+    }
+    const collisions = findCollisions(workstreams);
+    if (collisions.length > 0) {
+        return { ok: false, hard: true, reason: collisionReason(collisions), collisions };
+    }
+    return {
+        ok: true,
+        decision: { mode: "fan", width: width, reason, workstreams },
+    };
+}
+/**
+ * Post-fan claim audit: the changed paths not covered by any workstream's claims,
+ * normalized, deduped, in first-seen order. Claims are prefixes, so a file created
+ * under a claimed directory is in-claim; anything else is a named violation the
+ * synthesizer reconciles.
+ */
+export function auditClaims(changedPaths, workstreams) {
+    const claims = workstreams.flatMap((w) => w.files);
+    const violations = [];
+    for (const raw of changedPaths) {
+        const path = normalizeClaimPath(raw);
+        if (!path)
+            continue;
+        if (claims.some((claim) => claimCovers(claim, path)))
+            continue;
+        if (!violations.includes(path))
+            violations.push(path);
+    }
+    return violations;
+}
+//# sourceMappingURL=fanout.js.map

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

@@ -0,0 +1,31 @@
+/**
+ * The implement diamond's RECORDING thread: pipeline progress in, run-session
+ * stage beats out (spec "Recording and the run surface").
+ *
+ * The pipeline already says everything the run surface needs — the partition
+ * verdict, each builder starting and finishing, each bounded fix turn — on the
+ * `onProgress` channel. This folds that stream into the additive
+ * `fanout` / `children` / `fixTurns` payloads on `POST /runs/:id/stages`, so the
+ * web run surface can render per-workstream rows without the pipeline growing a
+ * second reporting path.
+ *
+ * PURE and I/O-free, like `findings.ts` and `fanout.ts`: `apply` returns the beat
+ * to send (or null when the signal is not the diamond's), and the caller decides
+ * whether to POST it. Two properties are load-bearing:
+ *
+ *  1. **Recorded states only.** A child row exists only once its `stage_start`
+ *     arrives, and it is `failed` only when the pipeline said the child died.
+ *     There is no invented "pending", and no tick nobody earned.
+ *  2. **Every beat is a copy.** The roster keeps mutating as children finish, so
+ *     a beat already handed to the (async, fail-soft) session must never change
+ *     underneath it.
+ */
+import type { StageArgs } from "./runSession.js";
+import type { PipelineProgress } from "./types.js";
+/** Folds the diamond's progress signals into the stage beats that record them. */
+export interface FanoutBeats {
+    /** The beat this signal produces, or null when it is not the diamond's. */
+    apply(p: PipelineProgress): StageArgs | null;
+}
+export declare function makeFanoutBeats(): FanoutBeats;
+//# sourceMappingURL=fanoutBeats.d.ts.map

package/dist/extension/pipeline/fanoutBeats.js

@@ -0,0 +1,86 @@
+/**
+ * The implement diamond's RECORDING thread: pipeline progress in, run-session
+ * stage beats out (spec "Recording and the run surface").
+ *
+ * The pipeline already says everything the run surface needs — the partition
+ * verdict, each builder starting and finishing, each bounded fix turn — on the
+ * `onProgress` channel. This folds that stream into the additive
+ * `fanout` / `children` / `fixTurns` payloads on `POST /runs/:id/stages`, so the
+ * web run surface can render per-workstream rows without the pipeline growing a
+ * second reporting path.
+ *
+ * PURE and I/O-free, like `findings.ts` and `fanout.ts`: `apply` returns the beat
+ * to send (or null when the signal is not the diamond's), and the caller decides
+ * whether to POST it. Two properties are load-bearing:
+ *
+ *  1. **Recorded states only.** A child row exists only once its `stage_start`
+ *     arrives, and it is `failed` only when the pipeline said the child died.
+ *     There is no invented "pending", and no tick nobody earned.
+ *  2. **Every beat is a copy.** The roster keeps mutating as children finish, so
+ *     a beat already handed to the (async, fail-soft) session must never change
+ *     underneath it.
+ */
+/** The stage every fan-out beat belongs to: the diamond lives INSIDE implement. */
+const IMPLEMENT = "implement";
+export function makeFanoutBeats() {
+    // Name -> tier + claim count from the partition verdict, so a child row can
+    // carry them the moment that child starts.
+    const shape = new Map();
+    const children = [];
+    const fixTurns = [];
+    const roster = () => children.map((c) => ({ ...c }));
+    const upsert = (name, state) => {
+        const existing = children.find((c) => c.name === name);
+        if (existing) {
+            existing.state = state;
+        }
+        else {
+            const meta = shape.get(name) ?? {};
+            children.push({
+                name,
+                ...(meta.tier ? { tier: meta.tier } : {}),
+                ...(meta.files !== undefined ? { files: meta.files } : {}),
+                state,
+            });
+        }
+        return { stage: IMPLEMENT, phase: "start", children: roster() };
+    };
+    return {
+        apply(p) {
+            switch (p.kind) {
+                case "fanout": {
+                    for (const w of p.workstreams ?? [])
+                        shape.set(w.name, { tier: w.tier, files: w.files });
+                    return {
+                        stage: IMPLEMENT,
+                        phase: "start",
+                        fanout: {
+                            mode: p.mode,
+                            ...(p.width ? { width: p.width } : {}),
+                            reason: p.reason,
+                        },
+                    };
+                }
+                case "stage_start":
+                    if (p.stageId !== IMPLEMENT || !p.workstream)
+                        return null;
+                    return upsert(p.workstream, "running");
+                case "stage_done":
+                    if (p.stageId !== IMPLEMENT || !p.workstream)
+                        return null;
+                    return upsert(p.workstream, p.degraded === "failed" ? "failed" : "done");
+                case "fix_turn": {
+                    fixTurns.push({ turn: p.turn, findings: p.findings, reengaged: [...p.reengaged] });
+                    return {
+                        stage: IMPLEMENT,
+                        phase: "start",
+                        fixTurns: fixTurns.map((t) => ({ ...t, reengaged: [...t.reengaged] })),
+                    };
+                }
+                default:
+                    return null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=fanoutBeats.js.map

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

@@ -114,6 +114,20 @@ export interface RegisterGoDeps {
     exists?: (path: string) => boolean;
     /** Clock seam for registry rows + staleness. */
     now?: () => number;
+    /**
+     * Environment the run-wide /go settings are read from (today: `go.fanout` via
+     * YAGNI_GO_FANOUT). Defaults to `process.env`; injected so a test can pin a
+     * benchmark lane without mutating the process.
+     */
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Is /ultra on right now? The same holder the subagent tool reads (wired in
+     * index.ts), consulted per call because /ultra can flip mid-session. It is the
+     * implement diamond's parallel ceiling: ultra runs the fan (and its fix turns)
+     * up to 8 wide, everything else stays at 4. Absent (an unwired embedder or a
+     * test) simply means "not ultra", which is today's behavior.
+     */
+    isUltra?: () => boolean;
     baseUrl?: string;
     getToken?: () => string | undefined;
     /**

package/dist/extension/pipeline/goCommand.js

@@ -63,6 +63,8 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { eventToLine } from "./activity.js";
 import { ActivityFeed, SPINNER_FRAMES } from "./activityFeed.js";
+import { resolveFanoutMode } from "./fanout.js";
+import { makeFanoutBeats } from "./fanoutBeats.js";
 import { RunState } from "./runState.js";
 import { aggregateRunUsage } from "./budget.js";
 import { formatRunCostTable } from "./runCostTable.js";
@@ -78,7 +80,7 @@ import { runPipeline as defaultRunPipeline } from "./orchestrator.js";
 import { composeAbortSignal } from "./resilience.js";
 import { planResume } from "./resume.js";
 import { activeRunCount, beginRun, classifyRunLiveness, findActiveRunByTicket, isRunInFlight, isTerminalStatus, lastJournalTs, loadRegistryRows, resolveMaxConcurrentRuns, settleRun, trackRunAbort, trackRunPromise, worktreesDir, } from "./runRegistry.js";
-import { makeRunSession as defaultMakeRunSession } from "./runSession.js";
+import { makeRunSession as defaultMakeRunSession, } from "./runSession.js";
 import { recordSessionRun } from "../sessionRuns.js";
 import { resolveTicketBrief as defaultResolveTicketBrief } from "./ticketResolution.js";
 import { snapshotWorkspace as defaultSnapshotWorkspace } from "./workspace.js";
@@ -422,6 +424,13 @@ export function registerGoCommand(pi, deps = {}) {
     const loadJournal = deps.loadJournal ?? ((sessionKey) => makeFileCheckpointStore(sessionKey).load());
     const exists = deps.exists ?? existsSync;
     const now = deps.now ?? Date.now;
+    // `go.fanout` (spec decision 8): `always` pins the implement diamond for
+    // benchmark / eval lanes; unset leaves the partitioner's conservative verdict
+    // as the only thing that decides.
+    const fanoutMode = resolveFanoutMode(deps.env ?? process.env);
+    // The dial is held, never its value: /ultra can be toggled between runs, so
+    // the pipeline calls it when it needs the ceiling rather than reading it here.
+    const isUltra = deps.isUltra;
     // Task 8: no default — see the RegisterGoDeps doc comment for why (only
     // index.ts's real wiring makes sense here; absent, `resolveCostText` falls
     // back to the local client estimate).
@@ -559,6 +568,10 @@ export function registerGoCommand(pi, deps = {}) {
             const feed = ctx.hasUI && !desktop ? new ActivityFeed(ticket) : undefined;
             const startedAt = Date.now();
             const run = ctx.hasUI && desktop ? new RunState({ runId: runShortId, ticket, startedAt }) : undefined;
+            // The implement diamond's recording thread. Per RUN (never module-scoped):
+            // it holds this run's child roster and fix turns. Independent of `feed` /
+            // `run`, because the Work page's run surface is fed on headless runs too.
+            const fanoutBeats = makeFanoutBeats();
             const stateKey = `${STATE_KEY_PREFIX}${runShortId}`;
             let paintTimer;
             let animationTimer;
@@ -639,6 +652,21 @@ export function registerGoCommand(pi, deps = {}) {
                 baseUrl: deps.baseUrl ?? resolveBaseUrl(),
                 getToken: deps.getToken ?? defaultGetToken,
             });
+            // The diamond's own recording channel is STRICTLY ORDERED, and it is the
+            // only one that has to be. Every roster beat carries the WHOLE roster and
+            // the run surface derives it last-one-wins (FanoutSection's `readFanout`),
+            // so two beats in flight at once can land in either order and a "running"
+            // that overtakes its own "done" paints a finished builder as running for
+            // the rest of the run. Chaining them through one promise makes the order
+            // the surface reads the order the pipeline produced. Still fire-and-forget
+            // (nothing on the run's critical path waits on it) and still fail-soft: a
+            // rejected beat never breaks the chain. The other stage beats stay
+            // unserialized on purpose — each names its own boundary, so their arrival
+            // order carries no state a later beat can undo.
+            let fanBeatChain = Promise.resolve();
+            const recordFanBeat = (b) => {
+                fanBeatChain = fanBeatChain.then(() => session.stage(b)).catch(() => { });
+            };
             const repoCtx = await resolveRepoContext(runCwd, ctx.signal);
             // Durable resilience journal, keyed by the RUN tree (the worktree path for
             // a default run; ctx.cwd for --here). Detect an interrupted prior /go for
@@ -880,10 +908,19 @@ export function registerGoCommand(pi, deps = {}) {
                     let result = await runPipeline(ticket, {
                         cwd: runCwd,
                         signal: runSignal,
+                        fanout: fanoutMode,
+                        ...(isUltra ? { isUltra } : {}),
                         ...(ticketBrief ? { ticketBrief } : {}),
                         onProgress: (p) => {
                             feed?.applyProgress(p);
                             run?.applyProgress(p, Date.now());
+                            // The implement diamond's own beats (the partition verdict, each
+                            // child's state, each fix turn) ride the SAME fail-soft stage
+                            // channel as every other boundary, additively: a signal that is not
+                            // the diamond's produces no beat at all.
+                            const fanBeat = fanoutBeats.apply(p);
+                            if (fanBeat)
+                                recordFanBeat(fanBeat);
                             // The ribbon replaces the status chip on the desktop, so the chip is
                             // only set for the terminal's status-line fallback.
                             if (ctx.hasUI && !desktop) {

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

@@ -0,0 +1,163 @@
+/**
+ * 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 { runPipeline as defaultRunPipeline } from "./orchestrator.js";
+import type { RunBudget } from "./budget.js";
+import type { JsonEvent, ModelTier, PipelineStage, StageId, StageTag, StageUsage, StopReason } from "./types.js";
+/** One-line usage copy, shared by every argument error. */
+export declare 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 declare const HEADLESS_GO_EXIT: {
+    readonly verified: 0;
+    readonly unverified: 1;
+    readonly usage: 2;
+};
+/** The parsed flag surface (pure; no fs, no env). */
+export interface HeadlessGoArgs {
+    headless: boolean;
+    json: boolean;
+    ticketFile?: string;
+    planFile?: string;
+    memoFile?: string;
+    runId?: string;
+    cwd?: string;
+    /** Any `--flag`-shaped token we do not know: refused, never folded in. */
+    unknownFlags: string[];
+    /** Bare tokens: the ticket is a FILE here, so a stray positional is refused. */
+    positionals: string[];
+    /**
+     * Value flags whose value was missing, empty, or another flag: refused, so
+     * `--ticket-file --json` fails naming the real problem instead of trying to
+     * read a file called `--json` with JSON mode silently off.
+     */
+    missingValues: string[];
+}
+/** One row of the result's per-stage usage table. */
+export interface HeadlessStageRow {
+    stage: StageId;
+    /** The tier the stage actually ran on (capped when `YAGNI_GO_TIER_CAP` is set). */
+    tier?: ModelTier;
+    /** Present on review rows: which review round produced them. */
+    round?: number;
+    usage: StageUsage;
+}
+/** The final result object written to stdout and returned to the caller. */
+export interface HeadlessGoResult {
+    /** True ONLY for a verified candidate (a `clean` stop) — mirrors exit 0. */
+    ok: boolean;
+    stopReason: StopReason;
+    rounds: number;
+    findings: number;
+    blocking: number;
+    stages: HeadlessStageRow[];
+    runId?: string;
+    /** The resolved `YAGNI_GO_TIER_CAP` ceiling; absent when the run is uncapped. */
+    tierCap?: ModelTier;
+    /**
+     * True when a plan or memo was injected: the pipeline entered at implement on
+     * the approved plan and FINISH did not run, so `commitSha` / `prUrl` are never
+     * reported (the mission's prHandoff delivers the candidate). Absent otherwise.
+     */
+    missionMode?: true;
+    commitSha?: string;
+    prUrl?: string;
+    /** Honest note when the deterministic verify gate gave no verdict. */
+    verifyNote?: string;
+    verifyCommand?: string;
+}
+export interface HeadlessGoOutcome {
+    exitCode: number;
+    result?: HeadlessGoResult;
+    /** Set when the run ended on a thrown error or an argument problem. */
+    error?: string;
+}
+/** Injectable seams: no fs, no stdout, no pipeline in a unit test. */
+export interface HeadlessGoDeps {
+    /** Repo to run in. `--cwd` wins; defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Environment the tier cap is read from. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Environment for spawned stage children. Defaults to `env`. */
+    childEnv?: NodeJS.ProcessEnv;
+    runPipeline?: typeof defaultRunPipeline;
+    readFile?: (path: string) => string;
+    /** stdout sink; one call per NDJSON line, newline added by the caller. */
+    write?: (line: string) => void;
+    /** stderr sink for human-readable problems. */
+    writeErr?: (line: string) => void;
+    signal?: AbortSignal;
+    budget?: RunBudget;
+    /** Stage-list override (the blind eval lane's grounding-stripped copy). */
+    stages?: PipelineStage[];
+    /** False runs the blind eval lane; defaults to grounded like every real run. */
+    grounded?: boolean;
+    /** Additive tap on every child event (the eval lane's retrieval telemetry). */
+    onEvent?: (ev: JsonEvent, tag: StageTag) => void;
+    /** Additive tap on the pipeline's own log events. */
+    logger?: (event: string, data?: unknown) => void;
+}
+/**
+ * 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 declare function parseHeadlessGoArgs(argv: string[]): HeadlessGoArgs;
+/** The argument problem, or undefined when the invocation is usable. */
+export declare function validateHeadlessGoArgs(args: HeadlessGoArgs): string | undefined;
+/**
+ * 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 declare function runHeadlessGo(argv: string[], deps?: HeadlessGoDeps): Promise<HeadlessGoOutcome>;
+//# sourceMappingURL=headlessGo.d.ts.map