looply-cli 0.0.0-stage → 0.2.0

package/dist/round-runner.d.ts

@@ -0,0 +1,924 @@
+import { type EventData, type Evidence, type Exemption, type Item, type PartialAnswer, type ProofVerdict, type RunTotals, type TrailerInput, type FailureFacts, type ItemCrossRepoContext } from '@looply/core';
+import type { ImplementerRunResult } from './agent-driver';
+import type { LooplyConfig } from './config';
+import type { EvidenceLookup } from './evidence-cache';
+import { type CommandResult, type CommandRunner, type GateStepDiagnostic } from './gate';
+import { type RejectedAttemptInput, type RejectedEvidenceSink } from './rejected-evidence';
+import type { AnyEventInput } from './ledger-store';
+import type { RunProgressNotifier } from './notify-cadence';
+import type { ItemPatch, QueueWriteResult } from './queue-store';
+import { type CountCommitsTouching } from './reverify';
+import type { ControlSource } from './control-file';
+import type { VerifyOutcome } from './verifier';
+/**
+ * The round runner: pick → implement → gate → prove → commit or discard, one
+ * ledger event per transition, until a budget limit fires or the queue is empty.
+ *
+ * Every effectful collaborator is injected, so the whole loop runs in a test
+ * with no git, no agent and no filesystem. The runner owns *sequencing and
+ * outcomes*; what a gate step or an agent invocation actually does lives in the
+ * modules it is handed. Round-state changes go through core's `transition`, so
+ * an illegal path (say, committing out of `gating`) throws instead of shipping.
+ */
+export interface RunnerLedger {
+    append(input: AnyEventInput): Promise<unknown>;
+}
+export interface RunnerQueue {
+    list(): Item[];
+    get(id: string): Item | undefined;
+    update(id: string, expectedVersion: number, patch: ItemPatch): Promise<QueueWriteResult>;
+}
+export interface RunnerGit {
+    changedPaths(): Promise<string[]>;
+    createBranch(name: string, from?: string): Promise<void>;
+    headSha(): Promise<string>;
+    stageAll(): Promise<void>;
+    commit(subject: string, trailer: TrailerInput): Promise<string>;
+    discard(): Promise<void>;
+    /**
+     * Whether anything is staged — asked so that "already done" is not an abort.
+     *
+     * ⚠️ OPTIONAL FOR THE SAME REASON `headTreeSha` IS: the runtime object is a
+     * full `GitDriver` and answers it; the suite's fakes need not. A caller that
+     * cannot answer simply commits as it always did, so no existing behaviour
+     * changes — and the production path gets the check.
+     */
+    hasStagedChanges?(): Promise<boolean>;
+    /**
+     * The tree this round ended on, as a fingerprint of what changed.
+     *
+     * ⚠️ OPTIONAL, AND THE DETECTOR IS THE REASON. `oscillation` returns null the
+     * moment ANY of its four fingerprints is null, so a half-wired tree does not
+     * degrade the detector — it silently switches it off. Optional here means the
+     * per-round record simply is not collected when a caller cannot answer, which
+     * is visible, rather than collected as nulls, which is not.
+     *
+     * The runtime object is a full `GitDriver` and answers it; the fakes in the
+     * suite do not, which is exactly the distinction this optionality expresses.
+     */
+    headTreeSha?(): Promise<string>;
+    /**
+     * The three verbs a rejected candidate needs — its manifest, its patch, and
+     * the way back. All optional for the same reason `headTreeSha` is: a caller
+     * that cannot answer retains less and says so, rather than failing the round.
+     */
+    changedEntries?(): Promise<Array<{
+        path: string;
+        status: string;
+    }>>;
+    patch?(maxBytes: number): Promise<{
+        text: string;
+        bytes: number;
+        truncated: boolean;
+    }>;
+    applyPatch?(patchFile: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        because: string;
+    }>;
+}
+/**
+ * What one round did, kept so the caller can be told about rounds rather than
+ * about runs.
+ *
+ * 🔴 THE DENOMINATOR WAS WRONG, AND THAT IS THE WHOLE DEFECT. There was one
+ * record per RUN, so a four-hour run that discarded forty rounds on
+ * the identical failure was ONE observation — and `MAX_SAME_FAILURE_REPEATS = 3`
+ * then needed three such RUNS before it would say anything. Meanwhile
+ * `MAX_ITEM_EXECUTION_ATTEMPTS = 3` is spent per round. The two numbers read as
+ * if they agreed and were measuring different things by a factor of the round
+ * count.
+ */
+export interface RoundFact {
+    readonly round: number;
+    /**
+     * ⚠️ A BOOLEAN, NOT THE OUTCOME WORD. A reachability proof in the CLI reads
+     * the one `outcome:` expression in the tree and asserts it names exactly two
+     * values; carrying the word here would move that expression into this file
+     * and the proof would quietly stop covering anything. `run-cmd.ts` explains
+     * it where the expression lives.
+     */
+    readonly worked: boolean;
+    /**
+     * WHERE this round failed, when it failed.
+     *
+     * 🔴 THE PRODUCER COLLAPSED FOUR OUTCOMES TO TWO, AND NOBODY COULD SEE IT.
+     *
+     * The one producer computed `committed > 0 ? 'worked' : 'gate_failed'`, so
+     * two of the four outcome values had no production producer at all. A
+     * four-value enum with two unreachable values makes every observation coarser
+     * than it looks: a round the PROVER refused was recorded as "a deterministic
+     * gate refused it", which is a different fact about a different mechanism,
+     * and any later reader deciding what kept going wrong was reading a category
+     * that had been flattened.
+     *
+     * ⚠️ `null` WHEN THE ROUND DID NOT FAIL, so "worked" and "failed somewhere we
+     * did not classify" stay different answers.
+     *
+     * 🔴 AND THE FIX ABOVE WAS ITSELF HALF DONE, WHICH IS WHY THIS PARAGRAPH IS
+     * HERE. Only a prover CRASH ever set `'verifier'`. A prover that ran fine and
+     * returned `refuted` left this null — and null maps to `gate_failed`, so the
+     * commonest and most informative disagreement in the system was recorded as
+     * "a deterministic gate refused it", in a record that simultaneously listed
+     * both gate steps as PASSED. A docblock claiming a defect was fixed sat
+     * directly above the code that still had it.
+     *
+     * ⚠️ `'action'` HAS NO PRODUCER, AND THAT IS A STATEMENT RATHER THAN A GAP.
+     * A run stopped by an outstanding approval or an ambiguous governed action is
+     * recorded as an EXCLUDED observation — `awaiting_approval` and
+     * `awaiting_human_resolution`, see `run-cmd` — because a round waiting on a
+     * person has not failed at anything and must not feed a stuck-detector. So
+     * there is deliberately no path that sets this, and the value is kept only
+     * because durable records already carry the union.
+     */
+    readonly failedAt: 'gate' | 'verifier' | 'action' | null;
+    /**
+     * Gate steps that passed in this round, by name.
+     *
+     * 🔴 THE ROUND WHERE THIS MATTERS IS THE ONE THAT DID NOT FINISH. A gate that
+     * goes green on the way to a commit has already moved the item, so recording
+     * it changes nothing. A gate that goes green and whose PROVER then refuses
+     * moves nothing at all — and without this the observation is byte-identical
+     * to the round before it, so real progress counts as none.
+     */
+    readonly passingGates: readonly string[];
+    readonly treeFingerprint: string | null;
+    readonly failure: FailureFacts | null;
+    /** True when this round hit an environment it could not use. */
+    readonly metUnavailableEnvironment: boolean;
+    /**
+     * The work list AS IT STOOD when this round ended.
+     *
+     * 🔴 WITHOUT THIS, EVERY ROUND OF ONE RUN LOOKED IDENTICAL, AND A RUN THAT
+     * COMMITTED EVERY ITEM RAISED A HOLD ON ITSELF.
+     *
+     * MEASURED. The caller built all N records from ONE snapshot taken after the
+     * run had finished, so every record carried the same progress fingerprint —
+     * and the detector that reads those compares them for EQUALITY and never
+     * looks at the outcome. Three rounds was therefore sufficient,
+     * unconditionally: pick three items, gate them green, commit all three, end
+     * queue-empty, and the machine records that it achieved nothing three times
+     * and stops working on the whole pursuit. Such a hold has no expiry.
+     *
+     * ⚠️ SNAPSHOTTED HERE BECAUSE ONLY HERE CAN. The queue is finished changing by
+     * the time the run ends; what each round achieved is only observable while
+     * that round is the present one.
+     */
+    readonly work: readonly Item[];
+}
+export interface ProofOutcome {
+    verdict: ProofVerdict;
+    reason: string;
+    confidence: number;
+}
+/**
+ * Everything the pick-time re-verification route needs (§12 case 19, the caller
+ * half of `decideReverify`). All-or-nothing on purpose: a cache read without a
+ * verifier would detect stale evidence and then implement on it anyway.
+ */
+export interface ReverifyDeps {
+    /** The evidence cache, both halves: read at pick, refill on a confirming verdict. */
+    cache: {
+        lookup(itemId: string, head: string): EvidenceLookup;
+        put(itemId: string, head: string, evidence: readonly Evidence[]): Promise<void>;
+    };
+    /** Real backend: `GitDriver.countCommitsTouching`. */
+    countCommitsTouching: CountCommitsTouching;
+    /** Runs the verifier for one item; `runVerifier` → `toVerifyOutcome` lives with the caller. */
+    verify(item: Item): Promise<VerifyOutcome>;
+}
+export interface RoundRunnerDeps {
+    ledger: RunnerLedger;
+    queue: RunnerQueue;
+    /**
+     * What other repositories have published, for items that declare a need on one.
+     *
+     * 🔴 ASKED PER PICK, NOT ONCE PER RUN. A sibling repository publishes while
+     * this run is working; an item blocked at round 3 can be pickable at round 9,
+     * and a context captured at startup would keep it waiting for the rest of the
+     * night. It is a function for that reason and no other.
+     *
+     * ⚠️ OPTIONAL, AND UNDEFINED IS NOT "EVERYTHING IS MET". A project with no
+     * declared repositories has no context to give, and no item in it can declare
+     * a need — but an item that somehow does is BLOCKED rather than waved
+     * through, because `itemCrossRepoBlockedBy` reads an empty declared list as
+     * `undeclared`. Absent context means nothing has been established, which is
+     * the same thing every other fold in this package says about absence.
+     */
+    crossRepo?(): Promise<ItemCrossRepoContext | undefined>;
+    /**
+     * Extra facts the composition root wants on this run's header.
+     *
+     * Deliberately opaque: a flat bag of primitives, spread into `run.started`
+     * before the six fields this file owns, so it can add attribution without
+     * being able to overwrite `runId`, `branch`, `baseSha`, `minHours`,
+     * `maxRounds` or `lane`. Omitted by every manual run, and `...undefined`
+     * spreads nothing — so a run with no context emits the exact event it always
+     * did, byte for byte.
+     *
+     * This file knows nothing about what the keys MEAN, and must not: whatever is
+     * in here is the caller's vocabulary, not the runner's.
+     */
+    runContext?: Readonly<Record<string, string | number>>;
+    git: RunnerGit;
+    /**
+     * Collect one {@link RoundFact} per round onto the summary.
+     *
+     * ⚠️ OFF BY DEFAULT, AND THAT IS A COMPATIBILITY DECISION RATHER THAN
+     * TIMIDITY. Turning it on changes the DENOMINATOR every brake threshold in
+     * core was calibrated against — from one record per run to one per round —
+     * which retunes behaviour for existing projects that asked for none of it.
+     *
+     * ⚠️ AND THE REASONING LIVES IN `core`, NOT HERE, DELIBERATELY. This file may
+     * not name the brake: a confinement test forbids it, because logic that
+     * judges a run sharing a code path with the run is how you get a run that
+     * suppresses its own record. All this does is collect facts.
+     */
+    perRoundSafety?: boolean;
+    /**
+     * Called ONCE, after every precondition has passed and immediately before the
+     * first round does any work. A refusal here ends the run having done nothing.
+     *
+     * 🔴 THIS EXISTS BECAUSE "JUST BEFORE `run()`" IS NOT "JUST BEFORE WORK", AND
+     * A MEASUREMENT PROVED IT.
+     *
+     * A caller needed to spend something that only a real attempt could justify,
+     * and moved the spend to the statement immediately before `run()`. That was
+     * still too early: `run()`'s FIRST statement is the dirty-tree check, and a
+     * person with uncommitted edits — which is how people at terminals live —
+     * watched the thing be spent and the command die in the same second, with no
+     * round started and nothing bought. A second shape reached the same end with
+     * a clean tree, when the pre-pick verification demoted the last ready item
+     * and the loop stopped `queue-empty` at zero rounds.
+     *
+     * Only the runner knows when work is actually beginning. So it says so.
+     */
+    beforeFirstRound?: () => Promise<{
+        ok: boolean;
+        because?: string;
+    }>;
+    /**
+     * The path prefixes this run said it would touch, when it said any.
+     *
+     * 🔴 A DECLARATION IS A HOPE; `changedPaths` IS FACT. What a round actually
+     * wrote is compared against what was leased, and a write outside it means the
+     * DECLARATION is wrong — so the round is discarded and the run ends. It is
+     * deliberately NOT retried: a retry would run the same wrong declaration.
+     *
+     * ⚠️ EMPTY OR ABSENT IS NO CONSTRAINT. A run that declared nothing is in
+     * violation of nothing, which is exactly how every run behaved before
+     * surfaces existed.
+     */
+    declaredSurfaces?: readonly string[];
+    /**
+     * Is this run still the current holder of the surfaces it declared?
+     *
+     * 🔴 THE FENCE HAD NO PRODUCTION CALLER. `surface-lease.ts` opens with
+     * "EXPIRY EXISTS ONLY HERE, AND ONLY BECAUSE OF THE FENCE" — and
+     * `checkFence` was called by nothing but its own unit test, so the expiry
+     * shipped and the thing that made expiry safe did not. A holder whose
+     * lease lapsed while a newer run took the surface could commit with no
+     * comparison anywhere in the path.
+     *
+     * Optional, because a run that declared no surfaces has no fence to check
+     * and must not gain a new failure mode.
+     */
+    checkFence?: () => {
+        ok: true;
+    } | {
+        ok: false;
+        because: string;
+    };
+    /**
+     * Has the ground moved under this checkout? A reason, or null.
+     *
+     * 🔴 CHECKED BETWEEN ROUNDS, WHICH IS THE ONLY PLACE IT MAY BE. A round in
+     * flight always finishes — that is the invariant recovery rests on, and it is
+     * why there is no hard cancel anywhere in this product. So a stale base stops
+     * the run at the NEXT boundary, and the round that was running when the
+     * ground moved is completed and kept.
+     *
+     * ⚠️ AND THE RUNNER DOES NOTHING ABOUT IT BUT STOP. It does not rebase, it
+     * does not re-cut, it does not merge. Deciding what happens to the pursuit is
+     * the coordinator's business; this only ends the run honestly.
+     */
+    /**
+     * WHERE A NEW RUN'S BRANCH SHOULD BE CUT FROM, when anything has an opinion.
+     *
+     * ⚠️ THE SIBLING OF `baseStale`, gated by the same flag. Absent means
+     * "wherever HEAD is" — every run before Phase 5, and every run with
+     * `run.integration` off.
+     */
+    integrationBase?: () => Promise<string | null>;
+    /**
+     * F29 (corr-7): asked about `cutAt`, the commit this run was CUT from — what "has the ground
+     * moved under me" is about. It used to be asked about the checkout's HEAD from BEFORE the cut,
+     * which in a reused checkout is the previous run's tip: every lane move read as a stale base
+     * and every working Start there halted after its first round.
+     */
+    baseStale?: (cutAt: string) => Promise<string | null>;
+    /** Executes gate steps; the real backend runs them CONTAINED. */
+    gateRunner: CommandRunner;
+    /**
+     * Whether this machine can still make a container, asked BEFORE the model turn.
+     *
+     * 🔴 THE GATE'S `blocked` VERDICT WAS ONLY HALF THE ANSWER. It protects an
+     * item whose round REACHED a gate. On a machine with no containment the round
+     * never gets there: every agent tool call is refused by the bridge, the
+     * transcript carries no structured result, `runImplementer` returns
+     * `abandoned`, and this file writes `{state:'closed'}` with `attempts` still
+     * 0 — an item closed on round one, unreachable by any later attempt, for a
+     * fault in the machine. Measured end to end against the real code: four items,
+     * four paid model turns, four closed, `stopReason: queue-empty`, and the run
+     * recorded as `gate_failed` with nothing excluded, which raises a
+     * `no_progress` hold on the third such run.
+     *
+     * Optional, because a runner without it behaves exactly as before — the
+     * convention `evidence` and `reverify` already use. Production wiring is
+     * pinned by `production-routing.spec.ts` so "optional" cannot become
+     * "forgotten".
+     */
+    environmentReady?(): Promise<CommandResult>;
+    /** Runs the implementer for one item. Prompt/command construction lives with the caller. */
+    /**
+     * `repair` is present on an attempt that follows a rejection IN THIS RUN:
+     * what the previous attempt changed, what refused it and what it printed,
+     * and whether that candidate was put back into the tree first. Absent on a
+     * first attempt and on an item whose last rejection belongs to another run —
+     * the item's `lastFailure` still carries the one-line reason either way.
+     */
+    implement(item: Item, attempt: number, repair?: RepairContext): Promise<ImplementerRunResult>;
+    /** The second key (DESIGN §2.2). Required whenever `proof.enabled` is true. */
+    prove?(input: {
+        item: Item;
+        changedPaths: readonly string[];
+    }): Promise<ProofOutcome>;
+    /**
+     * Resolves a `partial` verdict when `proof.on_partial: ask` — whatever can
+     * reach a human (daemon → phone). It owns emitting question.asked/answered.
+     */
+    resolvePartial?(item: Item, proof: ProofOutcome): Promise<PartialAnswer>;
+    /**
+     * Drops an item's cached evidence (see `EvidenceCache.invalidate`). Called
+     * after every discard — §12 case 19's second trigger. Optional because a run
+     * without a cache wired is merely slower, never wrong.
+     */
+    evidence?: {
+        invalidate(itemId: string): Promise<void>;
+    };
+    /**
+     * Where a rejected candidate is kept before the tree is reset.
+     *
+     * 🔴 WITHOUT IT A DISCARD DESTROYS THE ONLY COPY OF THE WORK. Optional so
+     * every existing fixture keeps constructing; the production root wires
+     * `makeRejectedEvidenceStore`. When absent, `round.ended` carries
+     * `evidenceIncomplete` naming the absence — a reader must never take a
+     * missing path for a round that had nothing to retain.
+     */
+    rejectedEvidence?: RejectedEvidenceSink;
+    /**
+     * Routes picking through the re-verification triggers (§12 case 19): the
+     * topmost item is only handed to a round once `decideReverify` judges its
+     * cached evidence fresh; otherwise it goes back through verification first.
+     * Optional — a runner without it picks blind, the pre-cache behaviour.
+     */
+    reverify?: ReverifyDeps;
+    /**
+     * Granted exemptions for an item (§8); validity is judged at the interlock.
+     * Optional: a runner with no grant source simply keeps every rail shut.
+     */
+    exemptionsFor?(itemId: string): Exemption[];
+    /**
+     * Persists the spent copy of a grant after a committed round (§8 "one
+     * round"). Required whenever `exemptionsFor` is wired — the constructor
+     * refuses a grant source with no spend sink, because that wiring is exactly
+     * the bug this closes: one grant reopening the same rail every round until
+     * it expires.
+     */
+    spendExemption?(spent: Exemption): Promise<void>;
+    /**
+     * Progress reporting hooks (§5.3). The runner reports every transition and
+     * never checks `every_min` itself — whether anything is actually sent is the
+     * notifier's decision (`CadenceNotifier`), so §12 case 35's "0 means silence"
+     * lives in one testable place. Implementations must not throw (§12 case 33).
+     */
+    notifier?: RunProgressNotifier;
+    /** Contents of an env file, or null when it does not exist (not an error). */
+    readEnvFile(path: string): string | null;
+    /** The live environment; values are matched against `rails.prod_patterns`. */
+    env: Readonly<Record<string, string | undefined>>;
+    now(): number;
+    /** Cooldown between rounds; omit to skip sleeping (tests, cooldown_s: 0). */
+    sleep?(ms: number): Promise<void>;
+    /** Polled between rounds; true once HUP/INT/TERM arrived. See signals.ts. */
+    stopRequested?(): boolean;
+    /**
+     * The phone's pause/stop, read from `control.json` between rounds. Optional:
+     * a runner with no control source cannot be reached from a phone, which is
+     * the local-only case rather than a failure. See control-file.ts.
+     */
+    control?: ControlSource;
+    /**
+     * Whether beginning this run consumes the control request on disk.
+     *
+     * DEFAULTS TO TRUE, which is what every caller before 6D2C did implicitly
+     * and what a person tapping Start still means.
+     *
+     * The reason it is now a question at all: `consume()` writes `resume` over
+     * whatever is in `control.json`, and the justification for doing that at
+     * every run start was "starting a run is itself the human saying go". That
+     * sentence is true of a tap and FALSE of a run a machine decided to begin.
+     * With it applied unconditionally, a person who taps Pause between runs has
+     * their pause erased by the next automatic run — and the sharpest case is a
+     * pause aimed at that very run, eaten by it minutes after it started.
+     *
+     * Deliberately a plain boolean and deliberately named for what it DOES. The
+     * runner has no business knowing what a controller is, which grant
+     * authorized this, or that autonomy exists at all; it needs to know one
+     * thing, and this is that thing. Translating an origin into this policy is
+     * the composition root's job and happens exactly once.
+     */
+    consumeControlOnStart?: boolean;
+    /** How long a paused run waits before re-reading the control file. */
+    pausePollMs?: number;
+    /**
+     * Asked the instant a model turn returns: has something outside this loop
+     * made the rest of the run impossible?
+     *
+     * The sibling of `stopRequested`, and generic for the same reason. That one
+     * answers "a person hit Ctrl-C"; this one answers "the thing that invoked the
+     * model met a boundary the round protocol has no vocabulary for". The runner
+     * does not learn what the boundary was. It is handed a reason to write down,
+     * a sentence for the item, and — like `runContext` on the header — an opaque
+     * bag of attribution it spreads without reading.
+     *
+     * WHY IT IS ASKED WHERE IT IS. Between rounds would be too late. A boundary
+     * met during a turn must stop the round it was met in, before the gate runs
+     * the project's tests over half-finished work and before a prover is paid to
+     * grade it — the run is over, and everything after the turn would be work
+     * done past the point where stopping was the answer.
+     */
+    haltRequested?(): RunHalt | null;
+}
+/**
+ * A reason the run cannot continue, from outside the round protocol.
+ *
+ * Deliberately says nothing about what happened. A runner that could tell one
+ * kind of halt from another would eventually be asked to behave differently for
+ * one of them, and then the round protocol would have a second author.
+ */
+/**
+ * WHAT A REPAIR ATTEMPT IS TOLD.
+ *
+ * 🔴 THE PREVIOUS TRIAL'S SECOND ATTEMPT WOULD HAVE BEEN TOLD "gate red: step
+ * typecheck failed" AND HANDED A CLEAN TREE. That is the whole of what
+ * `item.lastFailure` carries, and it is the whole of what a retry used to
+ * receive: no diagnostics, no patch, and no explanation of why the work it did
+ * last round is not there. A worker in that position starts over, differently
+ * or identically, and nothing about the loop is a repair.
+ *
+ * This is the rest of it. It is built by the runner from the evidence retained
+ * at the previous discard, bounded, and handed to `implement` — which renders
+ * it into the prompt as prose. The evidence directory itself is
+ * `protectedPaths` for the contained worker, so this is the only route.
+ */
+export interface RepairContext {
+    previous: {
+        round: number;
+        attempt: number;
+        /** The one-line reason, as carried on the item. */
+        why: string;
+        stage: RejectedAttemptInput['stage'];
+        failedStep: string | null;
+        /** Where the full evidence sits, for the report; the worker cannot open it. */
+        evidencePath: string | null;
+        /** Every step that ran, with bounded output. */
+        diagnostics: readonly GateStepDiagnostic[];
+        manifest: ReadonlyArray<{
+            path: string;
+            status: string;
+        }>;
+        /** The candidate's patch, when it was retained and not withheld. */
+        patch: {
+            text: string;
+            truncated: boolean;
+        } | null;
+        patchWithheld: string | null;
+        /**
+         * Set when this context was RECOVERED from an earlier run’s retained
+         * evidence — a restart between the rejection and this attempt — rather
+         * than held in this run’s memory. Absent for a rejection this run saw.
+         */
+        recoveredFrom?: {
+            runId: string;
+            evidencePath: string;
+        };
+    };
+    /**
+     * Whether the previous candidate was put back into the tree before this
+     * attempt. `ok: false` carries the exact reason, and the worker is told it
+     * is starting from the base — explained, never silent.
+     */
+    restored: {
+        ok: true;
+        paths: readonly string[];
+    } | {
+        ok: false;
+        because: string;
+    };
+    /** This attempt's number and the item's cap, so the limit is visible. */
+    attempt: number;
+    maxAttempts: number;
+}
+export interface RunHalt {
+    /** Recorded on `run.ended`. Chosen by the caller; not derived here. */
+    stopReason: StopReason;
+    /** One sentence, carried onto the item like any other reason. Never parsed. */
+    because: string;
+    /**
+     * Extra attribution for `run.ended`, spread exactly like `runContext` is on
+     * `run.started`: the caller may add to the event and can never overwrite the
+     * run's own facts, because those are written after the spread.
+     */
+    endedContext?: Readonly<Record<string, unknown>>;
+}
+export interface RunIdentity {
+    runId: string;
+    projectId: string;
+    lane: string;
+    branch: string;
+}
+export type StopReason = EventData['run.ended']['stopReason'];
+/**
+ * How many rounds may fail to run their gate before the run gives up.
+ *
+ * A blocked round costs the item nothing, which is the point — and which is
+ * also why the loop needs its own floor: without one, a machine with no
+ * containment would pick, implement, fail to gate and return the item, for ever
+ * and at full model cost.
+ */
+export declare const MAX_CONSECUTIVE_BLOCKED_ROUNDS = 3;
+/**
+ * WHAT THE GATE'S COMMANDS RESOLVE THROUGH, AND WHAT ITS STEPS FIND FOR THEMSELVES.
+ *
+ * `judgedBy` refuses to guess either, and this is where the guessing is done
+ * instead — in one named place that can be read and argued with, rather than
+ * inside a pure fold where it would look like a fact.
+ *
+ * `defining` is short on purpose. A config that MATTERS to a step is almost
+ * always named by that step's own command — `npx tsc --noEmit -p
+ * packages/cli/tsconfig.json` names its tsconfig, and `judgedBy` establishes
+ * that exactly, from two texts. What is left is the handful a command reaches
+ * through without ever writing down: `npm run x` and `npx x` both resolve
+ * through `package.json`, and a runner reads its own config by convention.
+ * Every basename added here widens a claim, so the bar is that the file
+ * decides what a gate step DOES.
+ *
+ * ⚠️ `discovered` IS THE WEAKER TIER AND `judgedBy` KEEPS IT APART FROM THE
+ * REST. `npx --no-install jest --ci` names no spec file; jest globs for them,
+ * and this repository declares the shape in `jest.config.js` rather than in
+ * any gate step. So a changed spec file is a claim from the file NAME, not
+ * from a step's declaration, and the sentence a person reads says so. That is
+ * "make the weaker claim and say so" — never "the suite is unchanged", which
+ * is the one thing no path pattern can establish.
+ */
+export declare const GATE_MACHINERY: {
+    readonly defining: readonly ["package.json", "jest.config.js", "jest.config.ts", "jest.config.cjs", "jest.config.mjs"];
+    readonly discovered: readonly [".spec.ts", ".spec.tsx", ".test.ts", ".test.tsx", ".spec.js", ".test.js"];
+};
+/**
+ * THE ALERT A RUN WRITES WHEN IT HALTS ITSELF (M6-12), immediately before
+ * `run.ended`. Every {@link RunHalt} carries a `because`, and until M6-12
+ * that sentence reached nothing: `run.ended` carries `stopReason` and totals,
+ * the crash path wrote `run-aborted`, the halt path wrote nothing, and the run
+ * child has no log. A person's Start placed under the umbrella in a repo
+ * without `looply/integration` ended `aborted` after one round and nobody
+ * could read why (found live in M6-11). The reason is one sentence, never
+ * parsed; `warn` when the halt is an abort, `info` for any other halt.
+ */
+export declare const RUN_HALTED_CODE = "run-halted";
+/**
+ * THE ALERT A RUN WRITES WHEN A CHECKER WAS NOT SURE AND NOBODY COULD BE ASKED (M6-20).
+ *
+ * `proof.on_partial` defaults to `ask`, and nothing in this build can ask: no
+ * CLI code produces a `question.asked`, so `looply run`'s asker answers
+ * `discard` and says so to a terminal nobody is watching (the audit's F-03).
+ * The work a checker was unsure about was therefore thrown away in silence —
+ * the item's failure line said "proof partial: …", which reads as the checker
+ * having refused, and nothing anywhere said that the configured answer was to
+ * ASK and that asking was impossible.
+ *
+ * ⚠️ ONLY WHEN THE POLICY IS `ask`. A project that configured `discard` chose
+ * this; saying it back to them on every partial verdict would be noise. And the
+ * run still discards — making it ask is a change to the round protocol and the
+ * owner's decision, not this alert's business.
+ */
+export declare const PARTIAL_DISCARDED_CODE = "proof-partial-discarded";
+/** What a partial proof discarded for want of anyone to ask says, in one sentence. */
+export declare function partialDiscardedText(itemTitle: string, reason: string): string;
+export interface RunSummary {
+    stopReason: StopReason;
+    totals: RunTotals;
+    elapsedMs: number;
+    /**
+     * The last deterministic failure this run hit, or undefined if it hit none.
+     *
+     * Carried out so loop safety can tell "the same failure three times" from
+     * "three different failures" — a distinction that decides whether a pursuit is
+     * stuck or simply working through problems, and one nothing else on this
+     * summary can make. `totals.discarded` counts reds; it cannot say whether they
+     * were the SAME red.
+     *
+     * ⚠️ THE DIGEST IS A HASH, NOT OUTPUT. See `failureOutputDigest`.
+     */
+    lastFailure?: FailureFacts;
+    /**
+     * WHERE THE LAST UNSUCCESSFUL ROUND FAILED — the gate, the prover, or an
+     * action.
+     *
+     * 🔴 CARRIED OUT BECAUSE THE RUN-LEVEL ROLLUP WAS GUESSING, AND GUESSING ONE
+     * PARTICULAR WRONG THING. Without per-round facts the composition root wrote
+     * `failedAt: null`, and null maps to `gate_failed` — so a run whose rounds
+     * were all PROVER refusals was recorded as a gate failure, in the DEFAULT
+     * configuration, which is the one almost every project runs.
+     *
+     * `failedAtThisRound` is maintained on every round regardless of
+     * `run.per_round_safety`; only the FACTS array is gated. So this costs
+     * nothing and needs no flag turned on to make the record honest.
+     *
+     * ⚠️ IT IS THE LAST ONE, AND SAYS SO. A run summarises many rounds and cannot
+     * claim they all failed the same way; what it can say truthfully is where the
+     * last unsuccessful one stopped.
+     */
+    lastFailedAt?: 'gate' | 'verifier' | 'action';
+    /**
+     * This run met an environment it could not use — at least once, at any point.
+     *
+     * ⚠️ "MET", NOT "ENDED BECAUSE OF". The first version set this only when the
+     * run aborted at the three-round bound, which left three other endings
+     * reachable first — `max-rounds` (config allows 1), `queue-empty`,
+     * `min-hours` — each then recorded as `gate_failed`, the outcome list's words
+     * for "a deterministic gate refused it", with an unchanged tree fingerprint
+     * feeding `noProgress`. That is the exact poisoning the `blocked` verdict
+     * exists to prevent, reached by simply configuring a short run.
+     *
+     * ⚠️ IT IS NOT BY ITSELF A REASON TO EXCLUDE. A run that met a broken
+     * container, recovered and committed work made real progress and must be
+     * observed normally. The caller pairs this with `totals.committed`; see
+     * `run-cmd.ts`. Carried out separately from `stopReason` because that cannot
+     * say it — this path ends as `aborted`, and so does an ordinary crash-out.
+     */
+    metUnavailableEnvironment?: true;
+    /**
+     * One record per round, in order, when the caller asked for them.
+     *
+     * ⚠️ COLLECTED, NOT ACTED ON. The runner does not consult the brake and
+     * must not start: a runner that could stop itself on such a verdict would
+     * be a second brake with none of the first one's evidence. `run-cmd` turns
+     * these into observations after the run, which is the same producer it has
+     * always been — only counting rounds instead of runs.
+     */
+    rounds?: RoundFact[];
+    /** Set when `beforeFirstRound` refused. The run did nothing at all. */
+    refusedBeforeFirstRound?: string;
+    /**
+     * Set when a round wrote outside the surfaces this run declared.
+     *
+     * The round was discarded where the trespass was seen — before the gate,
+     * before any commit — and the run ends. The caller flags the pursuit; it is
+     * deliberately not retried, because the declaration is what is wrong.
+     */
+    surfaceViolation?: {
+        paths: string[];
+        declared: readonly string[];
+    };
+}
+export declare class RunnerError extends Error {
+}
+/** How often a paused run re-reads control.json. Overridable via `pausePollMs`. */
+export declare const DEFAULT_PAUSE_POLL_MS = 5000;
+export declare class RoundRunner {
+    private readonly cfg;
+    private readonly deps;
+    private readonly id;
+    /**
+     * `proverRejected: 0` is set HERE rather than left absent, and the difference
+     * matters: this runner always counts, so a run in which the prover rejected
+     * nothing reports a PROVEN zero. Absent stays reserved for a producer that
+     * did not count at all — see {@link RunTotals.proverRejected}.
+     */
+    private readonly totals;
+    /** The most recent deterministic failure; see {@link RunSummary.lastFailure}. */
+    private lastFailure;
+    /**
+     * The last rejection of each item IN THIS RUN, kept for the repair attempt.
+     * In memory on purpose: the durable copy is the evidence directory, and a
+     * later run that picks the item up again reads `lastFailure` off the item —
+     * it does not restore a candidate from a run it did not see rejected.
+     */
+    private readonly rejections;
+    /**
+     * Set only on the path that ends the loop through {@link RoundRunnerDeps.haltRequested},
+     * and read only when writing `run.ended`. Held rather than threaded because
+     * `loop()` returns a stop reason and nothing else — widening that return to
+     * carry a payload only one of its eight answers can have would put the
+     * exception in the type every other caller reads.
+     */
+    private halt;
+    /** F29: the commit this run was cut from, set once, before the first round. */
+    private cutBase;
+    /**
+     * Consecutive rounds whose gate could not run. Reset by any gate that reached
+     * a verdict, so it counts a machine that is broken now rather than one that
+     * was ever briefly unhealthy.
+     */
+    private consecutiveBlocked;
+    /**
+     * Whether the round now running ended blocked.
+     *
+     * ⚠️ THE RESET LIVES IN THE LOOP, NOT IN THE ROUND, and that is the whole
+     * point of this second field. `runRound` has six exits before the gate — an
+     * implementer throw, `abandoned`, a railed path, a no-op, an external halt —
+     * and a reset placed anywhere inside it is a reset those exits skip. The
+     * counter would then read three blocked gates with ordinary rounds between
+     * them as "three in a row", and the halt sentence would be a false statement
+     * about the machine.
+     */
+    private blockedThisRound;
+    /** See {@link RunSummary.metUnavailableEnvironment}. */
+    private metUnavailableEnvironment;
+    constructor(cfg: LooplyConfig, deps: RoundRunnerDeps, id: RunIdentity);
+    run(): Promise<RunSummary>;
+    /**
+     * One record per round, or null when nothing asked for them.
+     *
+     * ⚠️ NULL RATHER THAN EMPTY, so "nobody asked" and "no rounds happened" stay
+     * different answers. A caller handed `[]` cannot tell which it got.
+     */
+    private roundFacts;
+    /** Why `beforeFirstRound` said no, so `run()` can put it on the summary. */
+    private refusedBeforeFirstRound;
+    /** Set when a round wrote outside what this run declared. */
+    private surfaceViolation;
+    /**
+     * Where THIS round failed. Reset at the top of every round, like
+     * `blockedThisRound` — a latched value would sign round N+1 with round N's
+     * failure, which is the shape that makes a detector fire on one real failure
+     * repeated by the recorder.
+     */
+    private failedAtThisRound;
+    /** Gate steps that passed in THIS round. Reset with everything else per-round. */
+    private passingGatesThisRound;
+    /**
+     * The implementer's sentence about the round in flight, on its way to the
+     * ledger (DESIGN §9, `round.ended.note`).
+     *
+     * HELD ON THE RUNNER RATHER THAN THREADED THROUGH, because every one of the
+     * seven ways a round can end goes through `endRound` and the note belongs on
+     * all of them — most of all on the ones that threw the work away, where it is
+     * the only record of what was attempted. A parameter would have to be added to
+     * each exit and the next exit somebody writes would silently omit it.
+     *
+     * ⚠️ CLEARED AT THE TOP OF EVERY ROUND. A stale note is worse than none: it
+     * would attribute one round's account of itself to the next round's outcome.
+     */
+    private roundNote;
+    /** What this round’s repair was, for `round.ended`. Reset with {@link roundNote}. */
+    private roundRepair;
+    /**
+     * WHAT THIS ROUND DID, FROM THE DIFFERENCE THE ROUND MADE.
+     *
+     * 🔴 THREE FIELDS ARE RUN-LEVEL ROLLUPS AND MUST NOT BE READ DIRECTLY.
+     *
+     * `this.lastFailure` is assigned when a failure happens and NEVER cleared, so
+     * reading it per round signs round N+1's record with round N's failure — the
+     * exact shape that would make `repeated_failure` fire on ONE real failure
+     * repeated by the recorder rather than by the machine. Same for
+     * `metUnavailableEnvironment`, which latches true for the rest of the run,
+     * and `totals.committed`, which only grows. The environment flag is read
+     * from `blockedThisRound`, which IS per-round, rather than compared.
+     *
+     * So each is compared against its value BEFORE the round: what changed during
+     * this round is this round's, and what did not is not.
+     */
+    private recordRoundFact;
+    /** The round loop itself, so `run()` can put an honest ending on a throw. */
+    private loop;
+    /**
+     * Consult the control file, holding here for as long as it says `pause`.
+     *
+     * Returns `continue` to start the next round, or the reason the run should
+     * wind down. `stop` ends the run; `pause` keeps it alive on its branch with
+     * its queue intact, so resuming continues the same run instead of paying for
+     * a fresh one — that is the whole difference between the two.
+     */
+    private awaitControl;
+    /** Topmost pickable item. Order IS priority (core `Item`), so the sort is the pick. */
+    private topPickable;
+    /**
+     * The pick, routed through the re-verification triggers (§12 case 19): the
+     * topmost item is handed to a round only when `decideReverify` judges its
+     * cached evidence fresh. A `reverify` decision — HEAD moved past the threshold,
+     * or no cache entry at all, which is the post-discard and never-verified state
+     * — sends the item back through verification instead, and the queue is re-read
+     * because the verdict may have routed the item out of `ready`, promoting the
+     * next one.
+     */
+    private pickNext;
+    /**
+     * Send an item back through verification and apply the verdict to the queue
+     * (§10, §12 cases 17–19). Confirmed/amended refills the evidence cache at the
+     * HEAD the verifier judged against, so the next lookup is a hit; every other
+     * verdict routes the item out of `ready` and the pick moves on.
+     */
+    private reverifyItem;
+    /**
+     * Returns how the round ended plus the item's title, for the notifier — and
+     * the halt, when this round is also the last one.
+     */
+    private runRound;
+    /**
+     * Discard the tree, and with it the item's cached evidence — §12 case 19's
+     * "always after a discard". Unconditional across every discard path: a
+     * requeued or later-unblocked item will be picked again, and its next attempt
+     * must not start from the very file:line claims that just led into a wall.
+     * (For an item closed by the same call the entry is merely dead weight.)
+     */
+    private discardTree;
+    /**
+     * Discard the tree and requeue: back to `ready` with attempt++ and the reason
+     * carried, so the next attempt starts knowing why this one failed (§2.2).
+     */
+    private discardAndRequeue;
+    /**
+     * Write the candidate and its verdict where the reset cannot reach, and
+     * answer the fields `round.ended` carries about it.
+     *
+     * NEVER THROWS. A failure to keep evidence is a fact about the round
+     * (`evidenceIncomplete`), not a reason to leave the tree dirty — the discard
+     * that follows this must run whatever happened here.
+     */
+    private retainRejected;
+    private rejectionInput;
+    /**
+     * What this attempt is told about the last one, and whether that candidate
+     * was put back first.
+     *
+     * RESTORED ONLY WHEN ALL OF THESE HOLD, and each refusal names itself:
+     *   - the driver can apply a patch and one was retained, whole
+     *   - HEAD is the base the candidate was written against
+     *   - every path it touched is inside the project's declared scope and
+     *     outside its rails — the candidate is re-gated afterwards regardless,
+     *     but a restore must not put a change somewhere the worker itself may
+     *     not write
+     * A restore that fails leaves the tree as it was (`applyPatch` is
+     * all-or-nothing, and the tree is discarded again to be sure) and the
+     * worker is told it starts from the base, and why.
+     */
+    private prepareRepair;
+    /** Records what this round’s repair was, for `round.ended`, and hands the context back unchanged. */
+    private noteRepair;
+    /**
+     * The item’s last rejection from an EARLIER run, when the evidence store can
+     * vouch for it — see `RejectedEvidenceSink.latestFor` for every check.
+     *
+     * ⚠️ A REFUSAL IS RECORDED, NOT SILENT. The attempt then goes ahead briefed
+     * from `lastFailure` and starting from the base, exactly as before recovery
+     * existed — but `round.ended` says a restart found evidence and why it was
+     * not used, so "no repair context" can be told apart from "refused one".
+     */
+    private recoverRejection;
+    /**
+     * Discard the tree and put the item back exactly as it was found.
+     *
+     * THE ATTEMPT IS NOT SPENT, and that is the whole difference from
+     * `discardAndRequeue`. An attempt is the budget for an item's implementation
+     * FAILING, and nothing failed here — the loop was stopped from outside before
+     * this round could reach a verdict. Spending one anyway would mean an item
+     * that keeps meeting the same external boundary is `closed` by
+     * `afterSpentAttempt` after three interruptions, without a single check ever
+     * having gone red, and while whatever the run was waiting for may since have
+     * been answered.
+     *
+     * The tree is still discarded, because every path in this file discards
+     * un-gated work: `run()` refuses to start on a dirty tree, and leftovers
+     * would fold into the next round's diff.
+     *
+     * The reason still travels on the item, which is what a person or a later
+     * attempt reads to find out why this round produced nothing.
+     */
+    private discardAndReturn;
+    private endRound;
+    /**
+     * Queue writes ride the store's optimistic concurrency. When the phone edited
+     * the item mid-round the runner loses the version race — its write records
+     * what physically happened to the round, so it refetches and lands on top of
+     * the curation edit rather than crashing an overnight run over the race.
+     */
+    private patchItem;
+    /** Same inputs `doctor` probes: prod env files that exist, plus the live env. */
+    private collectEnvValues;
+    private emit;
+}
+//# sourceMappingURL=round-runner.d.ts.map