looply-cli 0.0.0-stage → 0.2.0

package/dist/round-runner.js

@@ -0,0 +1,1693 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoundRunner = exports.DEFAULT_PAUSE_POLL_MS = exports.RunnerError = exports.PARTIAL_DISCARDED_CODE = exports.RUN_HALTED_CODE = exports.GATE_MACHINERY = exports.MAX_CONSECUTIVE_BLOCKED_ROUNDS = void 0;
+exports.partialDiscardedText = partialDiscardedText;
+const core_1 = require("@looply/core");
+const gate_1 = require("./gate");
+const glob_1 = require("./glob");
+const scope_rule_1 = require("./scope-rule");
+const rejected_evidence_1 = require("./rejected-evidence");
+const verify_apply_1 = require("./verify-apply");
+const reverify_1 = require("./reverify");
+/**
+ * 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.
+ */
+exports.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.
+ */
+exports.GATE_MACHINERY = {
+    defining: ['package.json', 'jest.config.js', 'jest.config.ts', 'jest.config.cjs', 'jest.config.mjs'],
+    discovered: ['.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.
+ */
+exports.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.
+ */
+exports.PARTIAL_DISCARDED_CODE = 'proof-partial-discarded';
+/** What a partial proof discarded for want of anyone to ask says, in one sentence. */
+function partialDiscardedText(itemTitle, reason) {
+    return (`the checker was not sure about "${itemTitle}" — ${reason} — and nothing on this machine can be asked, ` +
+        'so the work was discarded (proof.on_partial: ask)');
+}
+class RunnerError extends Error {
+}
+exports.RunnerError = RunnerError;
+/** How often a paused run re-reads control.json. Overridable via `pausePollMs`. */
+exports.DEFAULT_PAUSE_POLL_MS = 5_000;
+class RoundRunner {
+    cfg;
+    deps;
+    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}.
+     */
+    totals = { rounds: 0, committed: 0, discarded: 0, abandoned: 0, proverRejected: 0 };
+    /** The most recent deterministic failure; see {@link RunSummary.lastFailure}. */
+    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.
+     */
+    rejections = new Map();
+    /**
+     * 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.
+     */
+    halt = null;
+    /** F29: the commit this run was cut from, set once, before the first round. */
+    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.
+     */
+    consecutiveBlocked = 0;
+    /**
+     * 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.
+     */
+    blockedThisRound = false;
+    /** See {@link RunSummary.metUnavailableEnvironment}. */
+    metUnavailableEnvironment = false;
+    constructor(cfg, deps, id) {
+        this.cfg = cfg;
+        this.deps = deps;
+        this.id = id;
+        // Wiring mismatches surface here, not at hour three of an overnight run:
+        // proof enabled with no prover would discard (or worse, commit) every round,
+        // and `on_partial: ask` with nobody to ask has no honest fallback.
+        if (cfg.proof.enabled && !deps.prove) {
+            throw new RunnerError('proof.enabled is true but no prover is wired');
+        }
+        if (cfg.proof.enabled && cfg.proof.onPartial === 'ask' && !deps.resolvePartial) {
+            throw new RunnerError("proof.on_partial is 'ask' but nothing is wired to ask");
+        }
+        if (deps.exemptionsFor && !deps.spendExemption) {
+            throw new RunnerError('exemptionsFor is wired but no spendExemption sink — grants would never be spent');
+        }
+        if (deps.reverify && !deps.evidence) {
+            // §12 case 19's second trigger depends on the discard invalidating the
+            // cache. Without it a discarded round leaves a `hit` behind, and the next
+            // pick would reuse the exact evidence that just led into a wall.
+            throw new RunnerError('reverify is wired but no evidence.invalidate — a discard would leave stale evidence hittable');
+        }
+    }
+    async run() {
+        // Set here rather than as a field initialiser: `deps` is a constructor
+        // parameter property and is not initialised when field initialisers run.
+        if (this.deps.perRoundSafety === true)
+            this.roundFacts = [];
+        const dirty = await this.deps.git.changedPaths();
+        if (dirty.length > 0) {
+            // §12 case 1: a dirty tree at start would fold uncommitted human work into
+            // round 1's diff — and the first discard would destroy it.
+            throw new RunnerError(`working tree has ${dirty.length} changed path(s) — refusing to start (commit or stash first)`);
+        }
+        /**
+         * WHERE THIS RUN STARTS, WHEN SOMETHING HAS AN OPINION ABOUT IT.
+         *
+         * ⚠️ THE RUNNER STILL KNOWS NOTHING ABOUT INTEGRATION. It asks the
+         * composition root for a start point and is handed one or not — the same
+         * arrangement as every other seam here. Absent means "wherever HEAD is",
+         * which is what every run has always done.
+         */
+        const cutFromRef = (await this.deps.integrationBase?.()) ?? undefined;
+        await this.deps.git.createBranch(this.id.branch, cutFromRef);
+        const baseSha = await this.deps.git.headSha();
+        this.cutBase = baseSha;
+        if (cutFromRef !== undefined) {
+            // Both halves recorded on the ledger the run already owns: what was
+            // chosen, and what the run actually got.
+            await this.emit('alert', {
+                code: 'run_cut_from',
+                severity: 'info',
+                text: `cut from ${cutFromRef} at ${baseSha}`,
+            });
+        }
+        const startedAt = this.deps.now();
+        await this.emit('run.started', {
+            // Spread FIRST, on purpose. Whatever the composition root supplied is
+            // overwritten by the six authoritative values below, so context can add to
+            // the header but can never lie about the run's own identity.
+            ...this.deps.runContext,
+            runId: this.id.runId,
+            branch: this.id.branch,
+            baseSha,
+            minHours: this.cfg.run.minHours,
+            maxRounds: this.cfg.run.maxRounds,
+            lane: this.id.lane,
+        });
+        await this.deps.notifier?.runStarted({ minHours: this.cfg.run.minHours, baseSha });
+        // A control request belongs to the run it was aimed at. Clearing it here
+        // means last night's pause cannot wedge tonight's run before its first
+        // round — a hold nobody remembers setting is indistinguishable from a hang.
+        //
+        // ONLY WHEN BEGINNING THIS RUN WAS ITSELF A PERSON SAYING GO. That was the
+        // stated justification and it was applied unconditionally, which was
+        // correct while every run began with a tap. A run this machine decided to
+        // begin has no such authority: erasing a pause a person set would be the
+        // machine overruling them with an act they never performed.
+        if (this.deps.consumeControlOnStart !== false)
+            await this.deps.control?.consume();
+        let stopReason;
+        try {
+            stopReason = await this.loop(startedAt);
+        }
+        catch (e) {
+            // The loop threw where nothing caught it — a git failure, a ledger write
+            // that could not land, a queue write that lost its retry. Before this the
+            // run simply stopped: no `run.ended`, so `status.json` said `live` for
+            // ever, the phone showed a run that never finished, and the server's Run
+            // row never closed.
+            //
+            // `aborted` rather than any ordinary reason, because this run did not end
+            // its own loop. The totals are still exact — this process counted them —
+            // which is what separates it from the `crashed` a later process writes on
+            // a dead run's behalf.
+            //
+            // Emitting is best-effort and deliberately swallowed: if the ledger is
+            // what threw, trying to write the ending would replace the real error
+            // with a confusing one.
+            const elapsedMs = this.deps.now() - startedAt;
+            try {
+                await this.emit('alert', {
+                    code: 'run-aborted',
+                    severity: 'critical',
+                    text: `the run stopped on an error: ${e.message}`,
+                });
+                await this.emit('run.ended', {
+                    runId: this.id.runId,
+                    elapsedMs,
+                    stopReason: 'aborted',
+                    totals: this.totals,
+                });
+            }
+            catch {
+                /* the ledger is the likeliest thing to have thrown; keep the original */
+            }
+            throw e;
+        }
+        const elapsedMs = this.deps.now() - startedAt;
+        /**
+         * A RUN THAT HALTS ITSELF SAYS WHY (M6-12) — one `alert` immediately
+         * before `run.ended`, carrying the halt's own sentence, exactly as the
+         * crash path above writes `run-aborted`. Only a halt: an ordinary ending
+         * (`command`, `max-rounds`, `queue-empty`, …) has nothing to explain.
+         * Best-effort like the crash path's: a ledger that refuses the alert must
+         * not stop the ending being written — and if the ledger is dead, the
+         * `run.ended` below says so by throwing where it always has.
+         */
+        if (this.halt !== null && this.halt.because.length > 0) {
+            try {
+                await this.emit('alert', {
+                    code: exports.RUN_HALTED_CODE,
+                    severity: this.halt.stopReason === 'aborted' ? 'warn' : 'info',
+                    text: this.halt.because,
+                });
+            }
+            catch {
+                /* the ending below is the record; the alert was the courtesy */
+            }
+        }
+        await this.emit('run.ended', {
+            // Spread FIRST, for the reason `run.started` spreads `runContext` first:
+            // the caller may add attribution to the ending and can never restate the
+            // run's own facts, because the four below are written over whatever it
+            // sent.
+            ...this.halt?.endedContext,
+            runId: this.id.runId,
+            elapsedMs,
+            stopReason,
+            totals: this.totals,
+        });
+        await this.deps.notifier?.runEnded({ totals: this.totals, elapsedMs, branch: this.id.branch, stopReason });
+        const summary = { stopReason, totals: this.totals, elapsedMs };
+        if (this.roundFacts !== null)
+            summary.rounds = this.roundFacts;
+        if (this.refusedBeforeFirstRound !== null)
+            summary.refusedBeforeFirstRound = this.refusedBeforeFirstRound;
+        if (this.surfaceViolation !== null)
+            summary.surfaceViolation = this.surfaceViolation;
+        if (this.metUnavailableEnvironment)
+            summary.metUnavailableEnvironment = true;
+        // Only when there was one: an absent field says "no deterministic failure",
+        // which is different from "a failure nobody could identify".
+        if (this.lastFailure !== undefined)
+            summary.lastFailure = this.lastFailure;
+        if (this.failedAtThisRound !== null)
+            summary.lastFailedAt = this.failedAtThisRound;
+        return summary;
+    }
+    /**
+     * 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.
+     */
+    roundFacts = null;
+    /** Why `beforeFirstRound` said no, so `run()` can put it on the summary. */
+    refusedBeforeFirstRound = null;
+    /** Set when a round wrote outside what this run declared. */
+    surfaceViolation = null;
+    /**
+     * 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.
+     */
+    failedAtThisRound = null;
+    /** Gate steps that passed in THIS round. Reset with everything else per-round. */
+    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.
+     */
+    roundNote;
+    /** What this round’s repair was, for `round.ended`. Reset with {@link roundNote}. */
+    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.
+     */
+    async recordRoundFact(round, committedBefore, failureBefore) {
+        if (this.roundFacts === null)
+            return;
+        const worked = this.totals.committed > committedBefore;
+        /**
+         * ⚠️ AND THE TREE IS ASKED FOR ONCE PER ROUND, NOT DERIVED. `oscillation`
+         * compares four consecutive fingerprints and returns null if any is null,
+         * so a fingerprint this cannot obtain switches the detector off rather than
+         * weakening it — which is why a failure here is recorded as null and the
+         * caller is left to see a run whose rounds carry no tree.
+         */
+        const treeFingerprint = this.deps.git.headTreeSha === undefined ? null : await this.deps.git.headTreeSha().catch(() => null);
+        this.roundFacts.push({
+            round,
+            worked,
+            failedAt: worked ? null : this.failedAtThisRound,
+            passingGates: this.passingGatesThisRound,
+            treeFingerprint,
+            failure: this.lastFailure !== failureBefore ? (this.lastFailure ?? null) : null,
+            /**
+             * 🔴 `blockedThisRound`, NOT THE LATCHED RUN-LEVEL FLAG.
+             *
+             * This was `this.metUnavailableEnvironment && !metBefore`, which is true
+             * for the FIRST blocked round and false for every one after it, because
+             * the run-level flag latches and never clears. MEASURED: with containment
+             * broken from round 2 onward, rounds 3 and 4 were recorded as ordinary
+             * `gate_failed` attempts — two observations per run asserting the MODEL
+             * achieved nothing, for a fault in the MACHINE. That is precisely the
+             * poisoning the `blocked` verdict exists to prevent.
+             *
+             * `blockedThisRound` is reset at the top of every round, so it answers
+             * about this round and nothing else.
+             */
+            metUnavailableEnvironment: this.blockedThisRound,
+            work: this.deps.queue.list(),
+        });
+    }
+    /** The round loop itself, so `run()` can put an honest ending on a throw. */
+    async loop(startedAt) {
+        for (let round = 1;; round++) {
+            // A signal is checked first: when a human killed the run, `run.ended`
+            // must say `signal`, not claim a budget limit happened to expire at the
+            // same moment (§12 case 11). Like the budget checks below it sits between
+            // rounds, so the in-flight round finishes before the run winds down.
+            if (this.deps.stopRequested?.())
+                return 'signal';
+            // AND BEFORE THE PICK, not only after the model turn. `pickNext` can
+            // route an item back through verification, which is a second full model
+            // invocation — so a halt armed by anything other than this loop's own
+            // last round would otherwise pay for one more before noticing. Nothing
+            // arms it that way today; the fence is here because the day something
+            // does, this is where the cost would land.
+            const armed = this.deps.haltRequested?.() ?? null;
+            if (armed !== null) {
+                this.halt = armed;
+                return armed.stopReason;
+            }
+            // The phone's pause/stop, read from control.json. It sits next to the
+            // signal check and for the same reason: both are a human's intent, and
+            // `run.ended` must say `command` rather than name whichever budget limit
+            // happened to expire at the same moment. Being here also means the
+            // in-flight round finishes first, exactly like a budget limit.
+            const control = await this.awaitControl(startedAt);
+            if (control !== 'continue')
+                return control;
+            // Budget checks sit between rounds, never inside one: a limit reached
+            // mid-round finishes that round first (§12 case 10).
+            if (this.totals.rounds >= this.cfg.run.maxRounds)
+                return 'max-rounds';
+            if (this.deps.now() - startedAt >= this.cfg.run.minHours * 3_600_000)
+                return 'min-hours';
+            const item = await this.pickNext();
+            if (item === undefined)
+                return 'queue-empty';
+            /**
+             * ⚠️ AFTER `pickNext`, NOT BEFORE. An empty work set ends the run at zero
+             * rounds, and a caller that had already spent something by then spent it
+             * on nothing. This is the first line at which a round is certain.
+             */
+            if (round === 1 && this.deps.beforeFirstRound !== undefined) {
+                const may = await this.deps.beforeFirstRound();
+                if (!may.ok) {
+                    this.refusedBeforeFirstRound = may.because ?? 'the first round was refused';
+                    // A reasoned halt like any other: `run()` says why before it ends.
+                    this.halt = { stopReason: 'aborted', because: this.refusedBeforeFirstRound };
+                    return 'aborted';
+                }
+            }
+            this.blockedThisRound = false;
+            this.failedAtThisRound = null;
+            this.passingGatesThisRound = [];
+            const committedBefore = this.totals.committed;
+            const failureBefore = this.lastFailure;
+            const ended = await this.runRound(round, item);
+            // ⚠️ BEFORE `consecutiveBlocked` IS RESET, because `blockedThisRound` is
+            // what the record reads and the line below does not touch it.
+            await this.recordRoundFact(round, committedBefore, failureBefore);
+            /**
+             * A round that wrote outside its lease ends the RUN, not just the round.
+             * The round itself was already discarded where the trespass was seen —
+             * before the gate, before any commit. See `runRound`.
+             */
+            if (this.surfaceViolation !== null) {
+                // The same facts the item's own failure line carries, so the ending
+                // and the item say one thing; `run()` writes it before `run.ended`.
+                const { paths, declared } = this.surfaceViolation;
+                this.halt = {
+                    stopReason: 'aborted',
+                    because: `a round wrote outside the surfaces this run declared (${declared.join(', ')}): ` +
+                        `${paths.slice(0, 3).join(', ')}${paths.length > 3 ? ', …' : ''} — the run ends here`,
+                };
+                return 'aborted';
+            }
+            if (!this.blockedThisRound)
+                this.consecutiveBlocked = 0;
+            this.totals.rounds += 1;
+            const soFar = this.deps.now() - startedAt;
+            await this.deps.notifier?.roundFinished({
+                outcome: ended.outcome,
+                itemTitle: ended.title,
+                elapsedMs: soFar,
+                remainingMs: Math.max(0, this.cfg.run.minHours * 3_600_000 - soFar),
+            });
+            // AFTER the round is counted and reported, and BEFORE the cooldown. The
+            // round genuinely happened and belongs in the totals; the pause exists to
+            // space out the next one, and there is no next one.
+            if (ended.halt) {
+                this.halt = ended.halt;
+                return ended.halt.stopReason;
+            }
+            /**
+             * ⚠️ AFTER THE ROUND IS COUNTED AND REPORTED. The round genuinely
+             * happened and belongs in the totals; what has changed is that there
+             * should not be another one.
+             */
+            if (this.deps.baseStale !== undefined) {
+                const because = await this.deps.baseStale(this.cutBase);
+                if (because !== null) {
+                    this.halt = { stopReason: 'aborted', because };
+                    return 'aborted';
+                }
+            }
+            if (this.cfg.run.cooldownS > 0 && this.deps.sleep) {
+                await this.deps.sleep(this.cfg.run.cooldownS * 1000);
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async awaitControl(startedAt) {
+        const control = this.deps.control;
+        if (!control)
+            return 'continue';
+        let announced = false;
+        for (;;) {
+            const req = await control.read();
+            if (req === null || req.kind === 'resume') {
+                // Only when this run actually held. `resume` is also the cleared state
+                // of the control file, so it is the ordinary reading between rounds —
+                // announcing it unconditionally would put a line in the ledger for
+                // every round of every run, into an alerts array nothing trims.
+                if (announced) {
+                    await this.emit('alert', {
+                        code: 'run-resumed',
+                        severity: 'info',
+                        text: `resumed${req?.actor ? ` by ${req.actor}` : ''} — picking up the next round`,
+                    });
+                }
+                return 'continue';
+            }
+            if (req.kind === 'stop') {
+                /**
+                 * NOT CONSUMED — BY ANY RUN (M6-14). A person's own run used to clear
+                 * the file the instant it acted on it, and the reason given was that a
+                 * stop left on disk would end the person's next `looply run` before
+                 * its first round — which stopped being true the day a person's run
+                 * began consuming the file on START (`consumeControlOnStart`, above):
+                 * their next Start clears it before its first poll. What the clear
+                 * still did was speak for them to the autonomy tick. Found live
+                 * (M6-13): the stand-in's stop ended the placed run, the run wrote
+                 * `resume` over it, and the next tick found no hold and reserved a
+                 * Start for the pursuit it was still permitted; only the cancel's timing
+                 * prevented a machine run.
+                 *
+                 * An autonomous run never consumed it (nobody is standing there, and
+                 * wiping the instruction is how a tap meant to stop the night came to
+                 * stop one run out of eight). Now no run does. The run still stops;
+                 * the instruction stays where the person left it, for the tick to
+                 * hold on, until a person's own Start or resume says otherwise.
+                 */
+                return 'command';
+            }
+            // A hold that cannot sleep is a spin, so a runner with no sleep wired
+            // treats pause as the end of the run rather than burning a core.
+            if (!this.deps.sleep)
+                return 'command';
+            if (!announced) {
+                announced = true;
+                // There is no pause event in the schema, and a run that simply stops
+                // emitting looks identical to a dead one from the phone. This is the
+                // difference between "paused" and "hung".
+                await this.emit('alert', {
+                    code: 'run-paused',
+                    severity: 'info',
+                    text: `paused${req.actor ? ` by ${req.actor}` : ''} — resume from the app to continue this run`,
+                });
+            }
+            // A paused run still answers Ctrl-C and still ends at its budget: a hold
+            // only the phone can lift is a wedged process the moment the phone is flat.
+            if (this.deps.stopRequested?.())
+                return 'signal';
+            if (this.deps.now() - startedAt >= this.cfg.run.minHours * 3_600_000)
+                return 'min-hours';
+            await this.deps.sleep(this.deps.pausePollMs ?? exports.DEFAULT_PAUSE_POLL_MS);
+        }
+    }
+    /** Topmost pickable item. Order IS priority (core `Item`), so the sort is the pick. */
+    async topPickable() {
+        /**
+         * `pickableItems` replaces the bare `isPickable` filter and does the same job
+         * plus one more: an item whose prerequisites are not satisfied never reaches
+         * the sort. That ordering is the enforcement — a priority cannot promote an
+         * item past an unmet prerequisite, because such an item is not in the list.
+         *
+         * ⚠️ THE SORT IS UNCHANGED. An item that names no prerequisites, which is
+         * every item written before `after` existed, is picked exactly as before.
+         *
+         * The same sentence now covers an item's cross-repo needs: one that declares
+         * none is picked exactly as before, and one that declares an unmet need is
+         * not in the list. A blocked sibling therefore delays nothing but the work
+         * that actually depends on it.
+         */
+        return (0, core_1.pickableItems)(this.deps.queue.list(), await this.deps.crossRepo?.()).sort((a, b) => a.orderKey < b.orderKey ? -1 : a.orderKey > b.orderKey ? 1 : 0)[0];
+    }
+    /**
+     * 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.
+     */
+    async pickNext() {
+        const verified = new Set();
+        for (;;) {
+            const top = await this.topPickable();
+            if (top === undefined || this.deps.reverify === undefined)
+                return top;
+            // Already verified within this pick: the premise is current even when the
+            // verdict carried nothing to cache (an injected verifier is not forced
+            // through the parser's evidence check) — asking again would loop forever
+            // on the same answer.
+            if (verified.has(top.id))
+                return top;
+            const head = await this.deps.git.headSha();
+            const decision = await (0, reverify_1.decideReverify)(this.deps.reverify.cache.lookup(top.id, head), head, this.deps.reverify.countCommitsTouching);
+            if (decision.kind === 'reuse')
+                return top;
+            verified.add(top.id);
+            await this.reverifyItem(top, head);
+        }
+    }
+    /**
+     * 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.
+     */
+    async reverifyItem(picked, head) {
+        const routing = this.deps.reverify;
+        if (routing === undefined)
+            throw new RunnerError('reverifyItem called without reverify wired');
+        const item = await this.patchItem(picked.id, { state: 'verifying' });
+        const outcome = await routing.verify(item);
+        // Shared with the verification pass over a scan's drafts (verify-apply.ts),
+        // so an item becoming pickable never depends on which route reached it.
+        const decided = (0, verify_apply_1.applyVerifyVerdict)(item, outcome, (id) => this.deps.queue.get(id));
+        await this.emit('item.verified', { itemId: item.id, ...decided.outcome });
+        await this.patchItem(item.id, decided.patch);
+        if (decided.cacheEvidence) {
+            await routing.cache.put(item.id, head, decided.cacheEvidence);
+        }
+    }
+    /**
+     * Returns how the round ended plus the item's title, for the notifier — and
+     * the halt, when this round is also the last one.
+     */
+    async runRound(round, picked) {
+        const attempt = picked.attempts + 1;
+        let state = 'picked';
+        // Before anything can end this round. See {@link roundNote}.
+        this.roundNote = undefined;
+        this.roundRepair = undefined;
+        await this.emit('round.picked', { round, itemId: picked.id, attempt, title: picked.title });
+        const item = await this.patchItem(picked.id, { state: 'in_progress' });
+        state = (0, core_1.transition)(state, 'implementing');
+        await this.emit('round.phase', { round, phase: 'implementing' });
+        /**
+         * BEFORE THE PAID TURN, AND AFTER THE TRANSITION TO `implementing`.
+         *
+         * Both halves of that position are load-bearing. Before, because the whole
+         * point is not to buy a model turn a broken machine cannot use. After,
+         * because `TRANSITIONS` allows `implementing → discarded` and does NOT
+         * allow `picked → discarded`; moving this one line up throws
+         * `RoundTransitionError` and takes the run down.
+         *
+         * The blocked machinery is reused verbatim rather than re-decided: no
+         * attempt spent, item back to `ready` rather than `closed`, no failure
+         * signature, no `gate.result` and so no false `gate_failed`, the same bound
+         * of three, and `metUnavailableEnvironment` reaching the unchanged exclusion in
+         * `run-cmd.ts`.
+         */
+        /**
+         * WRAPPED, because this was the ONE un-try'd await in `runRound` — sitting
+         * directly above the `implement` call that IS wrapped, for the reason the
+         * comment there gives. The preflight closure can throw: `containedRoot()`
+         * does an unguarded `mkdirSync`, and the backend's own `mkdtempSync` sits
+         * outside its `try`. A full or locked `%TEMP%` would therefore take the run
+         * down with no `run.ended`, strand the item `in_progress`, and let recovery
+         * spend an attempt — the exact inversion of what this check is for.
+         */
+        let ready;
+        try {
+            ready = await this.deps.environmentReady?.();
+        }
+        catch (err) {
+            ready = {
+                ok: false,
+                unavailable: true,
+                timedOut: false,
+                ms: 0,
+                output: `the environment check itself failed: ${err.message}`,
+            };
+        }
+        if (ready?.unavailable === true) {
+            const why = 'round blocked: a container could not be made — the environment is unavailable, ' +
+                'not the change. No attempt was spent';
+            this.blockedThisRound = true;
+            this.consecutiveBlocked += 1;
+            /**
+             * ⚠️ ON THE FIRST BLOCKED ROUND, NOT AT THE BOUND. Setting this only when
+             * the run aborts left three other endings reachable first — `max-rounds`
+             * (which config allows as low as 1), `queue-empty`, `min-hours` — and each
+             * of those is then recorded as `gate_failed` with an unchanged tree
+             * fingerprint, which is what feeds `noProgress`. The bound governs the
+             * ABORT; the exclusion governs any run that met an unavailable
+             * environment, whenever it happens to stop.
+             */
+            this.metUnavailableEnvironment = true;
+            state = (0, core_1.transition)(state, 'discarded');
+            const outcome = await this.discardAndReturn(round, state, item.id, why, false);
+            if (this.consecutiveBlocked >= exports.MAX_CONSECUTIVE_BLOCKED_ROUNDS) {
+                return {
+                    outcome,
+                    title: item.title,
+                    halt: {
+                        stopReason: 'aborted',
+                        endedContext: { blockedReason: why },
+                        because: `${exports.MAX_CONSECUTIVE_BLOCKED_ROUNDS} rounds in a row could not make a container — ` +
+                            'nothing was charged to the queue; fix the machine and start again',
+                    },
+                };
+            }
+            return { outcome, title: item.title };
+        }
+        /**
+         * A repair attempt starts from what the last one left, explained. Built
+         * BEFORE the model is invoked and after the environment check, so a
+         * restored candidate is never put into a tree no container can gate.
+         */
+        const repair = await this.prepareRepair(item, attempt);
+        let impl;
+        try {
+            impl = await this.deps.implement(item, attempt, repair);
+        }
+        catch (err) {
+            // The prover-error's sibling: `runImplementer` already returns `abandoned`
+            // for a timeout or an unparseable result, so a *throw* here is the process
+            // itself failing (spawn ENOENT, transport down) — and it used to escape
+            // runRound and kill the whole overnight run. The round ends `abandoned`
+            // with the tree discarded, but the item goes back to `ready`, not
+            // `closed`: the crash says nothing about the item, and closing it would
+            // cost the item as well as the round. Critical alert for the same reason
+            // as the prover's — a dead agent binary abandons every round until
+            // someone hears.
+            const why = err instanceof Error ? err.message : String(err);
+            await this.emit('alert', {
+                code: 'implementer-error',
+                severity: 'critical',
+                text: `implementer invocation failed: ${why}`,
+            });
+            state = (0, core_1.transition)(state, 'abandoned');
+            const outcome = await this.discardAndRequeue(round, state, item.id, attempt, `implementer error: ${why}`, undefined, { stage: 'implementer' });
+            return { outcome, title: item.title };
+        }
+        /**
+         * ASKED BEFORE THE RESULT IS READ, and that ordering is the invariant.
+         *
+         * The turn came back across a boundary the composition root recognises and
+         * this loop does not. Everything after this line — the gate, the commit
+         * permit, the prover, the commit itself — is work done on the far side of a
+         * point where stopping was the answer, so none of it happens.
+         *
+         * `discarded`, and it is a statement about the ROUND'S LOCAL WORK rather
+         * than about why the run stopped. Nothing here passed a gate and nothing was
+         * proven, and un-gated work has never been kept by any path in this file;
+         * calling it `abandoned` would additionally say the item taught us nothing
+         * and close it, which is false — the item is exactly as workable as it was,
+         * and the next attempt should have it back.
+         */
+        const halt = this.deps.haltRequested?.() ?? null;
+        if (halt !== null) {
+            state = (0, core_1.transition)(state, 'discarded');
+            const outcome = await this.discardAndReturn(round, state, item.id, halt.because);
+            return { outcome, title: item.title, halt };
+        }
+        if (impl.kind === 'abandoned') {
+            // §12 case 4. The tree is cleaned, never consulted: §2.4 forbids deciding
+            // from it, but a dead agent's half-written edits must not leak into the
+            // next round's diff. `closed`, not `ready`: nothing was learned, and a
+            // requeue here is the "same item forever" loop.
+            await this.discardTree(item.id);
+            state = (0, core_1.transition)(state, 'abandoned');
+            const outcome = await this.endRound(round, state, item.id, { state: 'closed', lastFailure: impl.reason });
+            return { outcome, title: item.title };
+        }
+        const result = impl.result;
+        // From here every exit is an `endRound`, and every one of them carries this.
+        this.roundNote = (0, core_1.normalizeRoundNote)(result.note);
+        if (result.outcome === 'blocked') {
+            // §8: emit the exemption request and move to the next item. The runner
+            // never waits for the phone — the question outlives the round.
+            const blocked = result.blocked ?? { path: '(unknown)', reason: 'blocked with no details' };
+            // 🔴 `rails.exemptions: 'never'` MEANS IT DOES NOT ASK — and until now
+            // nothing branched on it. The setting was parsed, validated as one of two
+            // words, and offered on the phone, while an agent that reported a block
+            // produced this request under either value. Somebody who had said "never
+            // ask me" was asked anyway.
+            //
+            // ⚠️ IT STILL BLOCKS. `never` is about the QUESTION, not the outcome: the
+            // item is blocked either way, the tree is discarded either way, and the
+            // run picks the next item either way. Suppressing `item.blocked` too
+            // would turn a preference about interruptions into silently losing work.
+            if (this.cfg.rails.exemptions === 'ask') {
+                await this.emit('exemption.requested', {
+                    itemId: item.id,
+                    path: blocked.path,
+                    reason: blocked.reason,
+                });
+            }
+            await this.emit('item.blocked', { itemId: item.id, reason: `${blocked.path}: ${blocked.reason}` });
+            await this.discardTree(item.id);
+            state = (0, core_1.transition)(state, 'abandoned');
+            const outcome = await this.endRound(round, state, item.id, { state: 'blocked', blockedReason: blocked.reason });
+            return { outcome, title: item.title };
+        }
+        if (result.outcome === 'no-op') {
+            // §2.4: "nothing to do" is a statement the agent makes; the tree is not
+            // asked for a second opinion. The discard clears any stray writes anyway.
+            await this.discardTree(item.id);
+            state = (0, core_1.transition)(state, 'abandoned');
+            const outcome = await this.endRound(round, state, item.id, { state: 'closed' });
+            return { outcome, title: item.title };
+        }
+        state = (0, core_1.transition)(state, 'gating');
+        await this.emit('round.phase', { round, phase: 'gating' });
+        const changed = await this.deps.git.changedPaths();
+        /**
+         * 🔴 A DECLARATION IS A HOPE; THIS LIST IS FACT — AND IT IS CHECKED HERE,
+         * BEFORE THE GATE AND BEFORE ANY COMMIT.
+         *
+         * The obvious place is after the round, and it is the wrong one twice over:
+         * a successful round has COMMITTED by then, so "discard the round" would
+         * mean rewriting a commit — the one thing this codebase never does — and
+         * `changedPaths` after a commit is empty, so the check would silently only
+         * ever see rounds that had already failed.
+         *
+         * Here the writes are still in the working tree, and the existing discard
+         * path applies unchanged.
+         *
+         * ⚠️ AND IT ENDS THE RUN RATHER THAN RETRYING THE ITEM. A run that wrote
+         * outside its lease has demonstrated its DECLARATION is wrong; a retry
+         * would run the same wrong declaration again.
+         */
+        const declaredSurfaces = this.deps.declaredSurfaces ?? [];
+        if (declaredSurfaces.length > 0) {
+            const trespass = (0, core_1.surfaceViolations)(changed, declaredSurfaces);
+            if (trespass.length > 0) {
+                const paths = trespass.map((v) => v.path);
+                this.surfaceViolation = { paths, declared: declaredSurfaces };
+                const why = `it wrote outside the surfaces it declared (${declaredSurfaces.join(', ')}): ` +
+                    `${paths.slice(0, 3).join(', ')}${paths.length > 3 ? ', …' : ''}`;
+                /**
+                 * 🔴 THE TRANSITION, WHICH THIS SITE ALONE WAS MISSING — SO THE SAFETY
+                 * CHECK'S OWN SUCCESS PATH THREW.
+                 *
+                 * `state` is `gating` here, `endRound` calls `outcomeOf(state)`, and a
+                 * non-terminal state makes that null and throws `RunnerError: round
+                 * ended in non-terminal state gating`. The throw happens BEFORE
+                 * `patchItem`, so the item is never moved off `in_progress`: the item
+                 * is stranded, the run dies with a stack trace instead of the sentence
+                 * explaining the trespass, and the next run finds an item claimed by a
+                 * process that is gone.
+                 *
+                 * MEASURED: a round writing one path outside its declared surface threw
+                 * rather than discarding. Every other `discardAndReturn` caller — the
+                 * environment block, the external halt, the blocked round — transitions
+                 * first; this one was written last and did not.
+                 */
+                state = (0, core_1.transition)(state, 'discarded');
+                const outcome = await this.discardAndReturn(round, state, item.id, why, false);
+                return { outcome, title: item.title };
+            }
+        }
+        // The declaration is a hope; the diff is fact (E-04). What the agent said
+        // it touched against what `git status` shows — new, untracked files
+        // included — goes to the front of the round's note, counts first, where a
+        // person reads it. Recorded, not acted on: the gate decides this round
+        // exactly as before. A truthful account adds nothing.
+        const touched = (0, core_1.describeTouched)((0, core_1.touchedVsChanged)(result.filesTouched, changed));
+        /**
+         * AND WHAT THIS ROUND DID TO THE THINGS THAT JUDGED IT (the audit's G-03).
+         *
+         * A round is kept or discarded by a gate it is permitted to edit — its spec
+         * files sit inside the scope it is told it may change, and `package.json` is
+         * on no rail — and until now the result said nothing about whether it had
+         * edited them. Same seam and the same rule as E-04 above: RECORDED, NOT
+         * ACTED ON. The gate decides this round exactly as before, adding a test is
+         * the point rather than a suspicion, and a round that touched nothing that
+         * judges it adds no characters at all.
+         *
+         * ⚠️ `changedEntries` CARRIES THE STATUS AND `changedPaths` DOES NOT, which is
+         * the difference between a test that was deleted and a test that was added —
+         * the two ends of what this exists to tell apart. It is optional on
+         * `RunnerGit` for the reason stated there, so a driver that cannot answer
+         * yields paths with no status and the sentence says `touched` rather than
+         * inventing one.
+         */
+        const statusesAreReal = this.deps.git.changedEntries !== undefined;
+        const entries = statusesAreReal
+            ? await this.deps.git.changedEntries()
+            : changed.map((path) => ({ path, status: '' }));
+        const judged = (0, core_1.describeJudged)((0, core_1.judgedBy)(entries, { steps: this.cfg.gates, ...exports.GATE_MACHINERY, matches: glob_1.matchesGlob }));
+        /**
+         * E-04 first, then G-03, then the implementer's own sentence. Both
+         * machine-made facts keep their counts ahead of the prose, where a
+         * truncation cannot hide them, and neither displaces the other; with
+         * nothing to report from either, this composes the note it composed before.
+         */
+        const facts = [touched, judged].filter((s) => s !== '').join(' — ');
+        if (facts !== '') {
+            this.roundNote = (0, core_1.normalizeRoundNote)(this.roundNote === undefined ? facts : `${facts} — ${this.roundNote}`);
+        }
+        // What each step printed, for the evidence of a rejection. Collected here
+        // and nowhere else: the result object stays digest-only by contract.
+        const diagnostics = [];
+        const gate = await (0, gate_1.runGate)({
+            steps: this.cfg.gates,
+            changedPaths: changed,
+            runner: this.deps.gateRunner,
+            diagnostics: (d) => diagnostics.push(d),
+            interlocks: {
+                changedPaths: changed,
+                rails: this.cfg.rails,
+                envValues: this.collectEnvValues(),
+                itemId: item.id,
+                now: this.deps.now(),
+                exemptions: this.deps.exemptionsFor?.(item.id) ?? [],
+                /**
+                 * The scope interlock (ABORT_SCOPE, 93).
+                 *
+                 * 🔴 `changedEntries` IS PASSED ONLY WHEN THE STATUSES ARE REAL. A git
+                 * driver that cannot report them yields `status: ''` for every path,
+                 * and `''` is not a pure addition — so handing those over would abort
+                 * every round under an additive grant, on the strength of a field the
+                 * driver never filled in. An unmeasurable diff leaves the check unrun,
+                 * which `checkScope` treats as absence of input rather than a finding.
+                 */
+                ...(statusesAreReal ? { changedEntries: entries } : {}),
+                scope: this.cfg.scope,
+            },
+        });
+        /**
+         * A GATE THAT COULD NOT RUN IS NOT A GATE THAT WENT RED.
+         *
+         * `blocked` means the step never executed — no contained toolchain, or
+         * containment could not be made — so nothing about this item's code was
+         * measured. Charging it would spend an attempt and, three rounds later,
+         * close an item nothing ever examined.
+         *
+         * It also records no failure signature, which matters beyond this file: the
+         * signature is what a later reader uses to decide that the same failure
+         * keeps coming back, and a machine with no containment would otherwise
+         * produce a perfectly repeatable one on every item it touched.
+         */
+        const blocked = gate.verdict === 'blocked';
+        const blockedStep = blocked ? gate.steps.find((s) => !s.skipped && !s.ok) : undefined;
+        const blockedWhy = blocked
+            ? `gate blocked: step ${blockedStep?.step ?? '(unknown)'} could not run — ` +
+                `the environment is unavailable, not the change. No attempt was spent`
+            : undefined;
+        for (const s of gate.steps)
+            await this.emit('gate.step', { round, ...s });
+        const gateData = {
+            round,
+            // The wire never carries `blocked` (see `GateVerdict`): an older reader
+            // must see the red it would have seen, and `blockedReason` is the widened
+            // field that tells a newer one why nothing was charged.
+            verdict: blocked ? 'red' : gate.verdict,
+            steps: gate.steps,
+        };
+        if (gate.abort)
+            gateData.abortCode = gate.abort.code;
+        if (blockedWhy !== undefined)
+            gateData.blockedReason = blockedWhy;
+        await this.emit('gate.result', gateData);
+        if (blocked) {
+            this.blockedThisRound = true;
+            this.consecutiveBlocked += 1;
+            // Same rule as the preflight branch above: the exclusion is about having
+            // met an unavailable environment, not about how the run happened to end.
+            this.metUnavailableEnvironment = true;
+            state = (0, core_1.transition)(state, (0, core_1.afterGate)(gate.verdict));
+            // `discardAndReturn`, not `discardAndRequeue`: the tree is still cleaned,
+            // the reason still travels on the item, and the attempt is NOT spent —
+            // the same distinction an external halt already earns.
+            const outcome = await this.discardAndReturn(round, state, item.id, blockedWhy, false);
+            if (this.consecutiveBlocked >= exports.MAX_CONSECUTIVE_BLOCKED_ROUNDS) {
+                /**
+                 * BOUNDED, because "spends nothing" and "retries for ever" together are
+                 * an unbounded loop against a machine that is not going to get better on
+                 * its own. `aborted` is the honest existing reason — the run was alive
+                 * and met a boundary it could not get over — and it keeps `stopReason`
+                 * off the wire-change list.
+                 */
+                return {
+                    outcome,
+                    title: item.title,
+                    halt: {
+                        stopReason: 'aborted',
+                        /**
+                         * `endedContext` because `because` reaches nothing on this path:
+                         * it is read only where an EXTERNAL halt ends a round, and
+                         * `run.ended` spreads `endedContext` and nothing else. Without it
+                         * the operator sees three red gates and an unexplained abort.
+                         */
+                        endedContext: { blockedReason: blockedWhy },
+                        because: `${exports.MAX_CONSECUTIVE_BLOCKED_ROUNDS} rounds in a row could not run their gate — ` +
+                            `${blockedStep?.step === undefined ? 'the environment is unavailable' : `step ${blockedStep.step} never executed`}. ` +
+                            `Nothing was charged to the queue; fix the machine and start again`,
+                    },
+                };
+            }
+            return { outcome, title: item.title };
+        }
+        /**
+         * ⚠️ RECORDED WHATEVER THE VERDICT. A gate that went green on three of five
+         * steps and red on the fourth still proved those three, and a later round
+         * that proves a different three is progress the fingerprint must be able to
+         * see.
+         */
+        this.passingGatesThisRound = gate.steps.filter((s) => !s.skipped && s.ok).map((s) => s.step);
+        if (gate.verdict !== 'green') {
+            /**
+             * ⚠️ RECORDED WHERE IT HAPPENED. `gate_failed` was the producer's default
+             * for every non-committing round, which made it the answer for rounds
+             * that never reached a gate at all. Setting it here means the word means
+             * what the outcome list says it means: a deterministic gate refused it.
+             */
+            this.failedAtThisRound = 'gate';
+            if (gate.verdict === 'abort') {
+                // §12 cases 8–9: an abort is an alert, not just a tallied red — the gate
+                // itself may be broken, and someone should hear tonight, not at review.
+                await this.emit('alert', {
+                    code: 'gate-abort',
+                    severity: 'critical',
+                    text: gate.abort?.reason ?? 'interlock tripped',
+                });
+            }
+            const failed = gate.steps.find((s) => !s.skipped && !s.ok);
+            const failedStep = failed?.step;
+            if (failed !== undefined) {
+                /**
+                 * Held for the SUMMARY, not for this round's decision — the round is
+                 * already being discarded. Loop safety needs to know whether the same
+                 * failure keeps coming back, and only the runner sees the gate result.
+                 *
+                 * `exitCode` is null because the gate's step result does not carry one:
+                 * `CommandResult` reports `ok`, not a code. The field stays in
+                 * `FailureFacts` because it is part of what identifies a failure where a
+                 * caller does have it, and null is honest about not having it here.
+                 */
+                this.lastFailure = {
+                    step: failed.step,
+                    exitCode: null,
+                    outputDigest: failed.outputDigest ?? null,
+                };
+            }
+            const why = gate.verdict === 'abort'
+                ? `gate abort: ${gate.abort?.reason ?? 'interlock tripped'}`
+                : `gate red: step ${failedStep ?? '(unknown)'} failed`;
+            state = (0, core_1.transition)(state, (0, core_1.afterGate)(gate.verdict));
+            const outcome = await this.discardAndRequeue(round, state, item.id, attempt, why, result.testsAdded, {
+                stage: 'gate',
+                gate,
+                diagnostics,
+                implementer: impl,
+            });
+            return { outcome, title: item.title };
+        }
+        // The gate-side half of the commit permit, checked before proof so a round
+        // that can never commit does not pay for a prover call. `proofEnabled: false`
+        // because the proof key is turned below via the state machine — a `partial`
+        // answered "keep" is a human turning it, which a strict verdict check here
+        // would wrongly veto. The load-bearing case: a *required* step skipped by its
+        // `when:` filter leaves the gate green and must still block the commit —
+        // tabsy stamped 166 trailers with a check that never once ran.
+        const permit = (0, core_1.mayCommit)({
+            steps: gate.steps,
+            requiredSteps: (0, gate_1.requiredSteps)(this.cfg.gates),
+            proofEnabled: false,
+        });
+        if (!permit.ok) {
+            state = (0, core_1.transition)(state, 'discarded');
+            const outcome = await this.discardAndRequeue(round, state, item.id, attempt, `commit refused: ${permit.reason ?? 'unknown'}`, result.testsAdded, { stage: 'commit', gate, diagnostics, implementer: impl });
+            return { outcome, title: item.title };
+        }
+        state = (0, core_1.transition)(state, 'proving');
+        await this.emit('round.phase', { round, phase: 'proving' });
+        let proof;
+        if (this.cfg.proof.enabled && this.deps.prove) {
+            try {
+                proof = await this.deps.prove({ item, changedPaths: changed });
+            }
+            catch (err) {
+                // §12 case 15's harder sibling: an unparseable verdict is a rejection,
+                // and a prover that *crashes* (spawn failure, transport down) must be
+                // no kinder — this throw used to escape runRound and kill the whole
+                // overnight run. Without the second key the round may never commit, so
+                // the tree is discarded and the item requeued unproven: one lost
+                // round, not the night. The alert is critical because a down prover
+                // discards every round until someone hears.
+                const why = err instanceof Error ? err.message : String(err);
+                await this.emit('alert', {
+                    code: 'prover-error',
+                    severity: 'critical',
+                    text: `prover invocation failed: ${why}`,
+                });
+                /**
+                 * ⚠️ THE VERIFIER, NOT THE GATE. Recorded as its own kind because "a
+                 * deterministic gate refused it" is a different fact about a different
+                 * mechanism, and a later reader deciding what keeps going wrong was
+                 * being handed a category that had been flattened.
+                 */
+                this.failedAtThisRound = 'verifier';
+                state = (0, core_1.transition)(state, 'discarded');
+                const outcome = await this.discardAndRequeue(round, state, item.id, attempt, `prover error: ${why}`, result.testsAdded, { stage: 'proof', gate, diagnostics, implementer: impl });
+                return { outcome, title: item.title };
+            }
+            await this.emit('proof.result', { round, verdict: proof.verdict, reason: proof.reason, confidence: proof.confidence }, 'prover');
+            const resolution = (0, core_1.afterProof)(proof.verdict);
+            let final;
+            /** M6-20: set when the policy was `ask`, nothing could ask, and the answer was therefore `discard`. */
+            let askedAndDiscarded = null;
+            if (resolution.kind === 'decided') {
+                final = resolution.state;
+            }
+            else {
+                // `partial`: the round stays in `proving` until an answer exists.
+                // on_partial keep/discard IS the answer; 'ask' delegates to whoever can
+                // reach a human. The 'discard' fallback is unreachable (constructor
+                // refuses ask-with-nothing-wired) but keeps the safe default explicit.
+                const ask = this.deps.resolvePartial;
+                const answer = this.cfg.proof.onPartial !== 'ask' ? this.cfg.proof.onPartial : ask ? await ask(item, proof) : 'discard';
+                /**
+                 * M6-20: A DISCARD THE PROJECT DID NOT CHOOSE IS SAID OUT LOUD.
+                 *
+                 * Best-effort, like every other alert here: a ledger that refuses it
+                 * must not change what happens to the round. Written before the
+                 * outcome is applied so it sits with the round it belongs to.
+                 */
+                if (this.cfg.proof.onPartial === 'ask' && answer === 'discard') {
+                    askedAndDiscarded = partialDiscardedText(item.title, proof.reason);
+                    try {
+                        await this.emit('alert', {
+                            code: exports.PARTIAL_DISCARDED_CODE,
+                            severity: 'warn',
+                            text: askedAndDiscarded,
+                        });
+                    }
+                    catch {
+                        /* the round's own record below is the one that must land */
+                    }
+                }
+                final = (0, core_1.afterAnswer)(answer);
+            }
+            if (final !== 'committed') {
+                /**
+                 * 🔴 THE VERIFIER REFUSED, AND THIS RECORDED IT AS A GATE FAILURE — the
+                 * exact case the producer's own docblock says it fixed.
+                 *
+                 * Only a prover CRASH ever set `'verifier'`. A prover that ran fine and
+                 * said `refuted` left `failedAtThisRound` at null, and null maps to
+                 * `gate_failed` — so the record asserted that a deterministic gate
+                 * refused the round, in a record that simultaneously said both gate
+                 * steps PASSED. Two contradictory statements in one row, and the
+                 * loop-safety detectors and the person both read the wrong one.
+                 *
+                 * A refusal is the prover doing its job, which is what makes recording
+                 * it as a gate failure so misleading: it is the single most important
+                 * signal that the model and the checker disagree, and it was filed
+                 * under the mechanism that had nothing to say.
+                 */
+                this.failedAtThisRound = 'verifier';
+                state = (0, core_1.transition)(state, final);
+                const outcome = await this.discardAndRequeue(round, state, item.id, attempt, 
+                // M6-20: the same sentence the alert carries, so the ITEM says why
+                // too — "proof partial: …" alone reads as the checker refusing.
+                askedAndDiscarded ?? `proof ${proof.verdict}: ${proof.reason}`, result.testsAdded, { stage: 'proof', gate, diagnostics, proof, implementer: impl });
+                return { outcome, title: item.title };
+            }
+        }
+        /**
+         * 🔴 THE LAST LOOK, BECAUSE EVERY CHECK ABOVE RAN ON A PRE-GATE SNAPSHOT
+         * AND THE NEXT LINE IS `git add -A`.
+         *
+         * `changed` was read once, before the gate. The gate then runs the
+         * PROJECT'S OWN COMMANDS — a build, a formatter, a codegen step, a test
+         * suite that writes fixtures — and the prover runs after it. Anything any
+         * of them wrote lands in the working tree, is staged by `stageAll`, and is
+         * committed without ever having been shown to the rails interlock or the
+         * surface check. Forbidden paths, production env files, CI workflow files:
+         * all of them ride in through a window the checks were never told about.
+         *
+         * So the tree is read AGAIN here, and the two checks that guard a commit
+         * are re-asked on what is actually about to be committed.
+         *
+         * ⚠️ AND THE FENCE IS ASKED HERE, WHICH IS THE ONLY PLACE IT MEANS
+         * ANYTHING. `surface-lease.ts` says "EXPIRY EXISTS ONLY HERE, AND ONLY
+         * BECAUSE OF THE FENCE" — and `checkFence` had NO production caller at all,
+         * 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. Two integers, at the moment of
+         * the write, exactly as the design said.
+         */
+        const atCommit = await this.deps.git.changedPaths();
+        const lateTrespass = (0, core_1.surfaceViolations)(atCommit, this.deps.declaredSurfaces ?? []);
+        if (lateTrespass.length > 0) {
+            const paths = lateTrespass.map((v) => v.path);
+            this.surfaceViolation = { paths, declared: this.deps.declaredSurfaces ?? [] };
+            state = (0, core_1.transition)(state, 'discarded');
+            const outcome = await this.discardAndReturn(round, state, item.id, `the gate or the prover wrote outside the surfaces this run declared ` +
+                `(${(this.deps.declaredSurfaces ?? []).join(', ')}): ` +
+                `${paths.slice(0, 3).join(', ')}${paths.length > 3 ? ', …' : ''}`, false);
+            return { outcome, title: item.title };
+        }
+        const fenceTrouble = this.deps.checkFence?.();
+        if (fenceTrouble !== undefined && !fenceTrouble.ok) {
+            state = (0, core_1.transition)(state, 'discarded');
+            const outcome = await this.discardAndReturn(round, state, item.id, fenceTrouble.because, false);
+            return { outcome, title: item.title };
+        }
+        const lateRails = (0, gate_1.checkInterlocks)({
+            changedPaths: atCommit,
+            rails: this.cfg.rails,
+            // The environment was judged before the gate and cannot have changed by
+            // the gate writing files. Only the DIFF is re-asked here.
+            envValues: [],
+            itemId: item.id,
+            now: this.deps.now(),
+            exemptions: this.deps.exemptionsFor?.(item.id) ?? [],
+        });
+        if (lateRails !== null) {
+            state = (0, core_1.transition)(state, 'discarded');
+            const outcome = await this.discardAndReturn(round, state, item.id, `the gate or the prover wrote somewhere the rails forbid: ${lateRails.reason}` +
+                (lateRails.paths?.length ? ` (${lateRails.paths.slice(0, 3).join(', ')})` : ''), false);
+            return { outcome, title: item.title };
+        }
+        /**
+         * 🔴 THE CROSS-REPO NEEDS ARE ASKED AGAIN HERE, AND THIS IS THE SECOND OF
+         * THE TWO PLACES THE CHARTER NAMES.
+         *
+         * `OWNER_CHARTER.md` §6.D: *"Enforce at pick/admission where the decision is
+         * used; check again at relevant acceptance boundaries if dependencies
+         * changed."* The pick is the first; this is the second, and it exists
+         * because a round is long. The item was pickable when it was picked; by the
+         * time its work is about to be kept, the accepted set can have drifted, a
+         * repository can have moved off the revision this item was written against,
+         * or the set can have been replaced entirely. Keeping the work anyway would
+         * commit code written against a state that no longer exists — which is the
+         * same failure `checkFence` and the late rails guard, arriving from a
+         * different direction.
+         *
+         * ⚠️ IT FAILS CLOSED. An item that declares needs and whose context cannot
+         * be read now reaches `undeclared` and is discarded, exactly as it would at
+         * the pick. "Could not establish" is not "still fine".
+         *
+         * ⚠️ AND THE EVIDENCE IS KEPT (`false`). Nothing about the item's own claim
+         * was disproved — a sibling moved. Invalidating would route the item back
+         * through the verifier for a reason that has nothing to do with it, which is
+         * the mistake `discardAndReturn`'s own docblock records about environment
+         * blocks.
+         */
+        if ((item.needs?.length ?? 0) > 0) {
+            const dependenciesNow = (await this.deps.crossRepo?.()) ?? { declared: [], set: null, current: new Map() };
+            const moved = (0, core_1.itemCrossRepoBlockedBy)(item, dependenciesNow);
+            if (moved.length > 0) {
+                state = (0, core_1.transition)(state, 'discarded');
+                const outcome = await this.discardAndReturn(round, state, item.id, `a repository this item depends on moved while the round was running: ${(0, core_1.describeItemCrossRepoBlockers)(moved)}`, false);
+                return { outcome, title: item.title };
+            }
+        }
+        await this.deps.git.stageAll();
+        const trailer = { steps: gate.steps };
+        if (proof)
+            trailer.proof = proof;
+        if (gate.exemptionsUsed?.length) {
+            // The grant appears on the commit itself, so a reader of the log can see
+            // the door was opened — a silently-exempted rail defeats the audit (§8).
+            trailer.exemptions = gate.exemptionsUsed.map((e) => ({ path: e.path, actor: e.actor }));
+        }
+        /**
+         * 🔴 ALREADY DONE IS NOT AN ERROR, AND IT USED TO END THE RUN.
+         *
+         * An item whose behaviour a previous round already delivered leaves nothing
+         * staged. `git commit` then exits 1, which becomes a `GitError`, which the
+         * crash path turns into `run-aborted` — critical, run over, every remaining
+         * item dropped. Measured live: gate green in 2,148 ms, prover `proven` at
+         * 0.83, run killed.
+         *
+         * The honest reading is the one the evidence supports. The gate passed and
+         * the prover affirmed this item's claim against the tree, so the behaviour
+         * IS present — it simply arrived in an earlier commit. So the item is
+         * marked `done` on that evidence, and the round ends without inventing a
+         * commit that does not exist.
+         *
+         * ⚠️ `discarded`, NOT `committed`, because no new commit was made and a sha
+         * would have to be borrowed from a round that already reported it. The item
+         * is `done`, so `shouldRequeue` cannot spin it: a done item is not pickable.
+         */
+        if (this.deps.git.hasStagedChanges !== undefined && !(await this.deps.git.hasStagedChanges())) {
+            this.roundNote =
+                `nothing left to commit — the gate and the prover both passed, so this item's work is ` +
+                    `already in the tree from an earlier round. Marked done rather than ending the run.`;
+            state = (0, core_1.transition)(state, 'discarded');
+            const outcome = await this.endRound(round, state, item.id, { state: 'done' }, { files: 0 });
+            return { outcome, title: item.title };
+        }
+        const sha = await this.deps.git.commit(item.title, trailer);
+        // Spend on commit, not on check: a discarded round left nothing behind, and
+        // burning the grant on a failure would strand the retry outside its own
+        // door. Spending happens after the commit exists, so the round the copy
+        // names is a round that really landed; a spend-persist failure throws — a
+        // grant we cannot record as spent would silently become a many-round door.
+        for (const e of gate.exemptionsUsed ?? []) {
+            await this.deps.spendExemption?.((0, core_1.markExemptionUsed)(e, round));
+        }
+        state = (0, core_1.transition)(state, 'committed');
+        const outcome = await this.endRound(round, state, item.id, { state: 'done' }, { sha, files: changed.length, testsAdded: result.testsAdded });
+        return { outcome, title: item.title };
+    }
+    /**
+     * 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.)
+     */
+    async discardTree(itemId, invalidateEvidence = true) {
+        await this.deps.git.discard();
+        if (invalidateEvidence)
+            await this.deps.evidence?.invalidate(itemId);
+    }
+    /**
+     * 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).
+     */
+    async discardAndRequeue(round, state, itemId, attempt, why, testsAdded, context = { stage: 'implementer' }) {
+        /**
+         * 🔴 RETAINED BEFORE THE RESET, NOT AFTER. `discardTree` is `reset --hard`
+         * and the only copy of the candidate is the working tree. Every path that
+         * spends an attempt comes through here, so every rejected candidate is
+         * kept — or its absence is recorded on the round, by name.
+         */
+        const kept = await this.retainRejected(round, itemId, attempt, why, context);
+        await this.discardTree(itemId);
+        return this.endRound(round, state, itemId, 
+        // Back to the queue, unless that was the last attempt this item gets.
+        // `afterSpentAttempt` owns that decision so this and recovery — the only
+        // two places an attempt is ever spent — cannot come to disagree about it.
+        { state: (0, core_1.afterSpentAttempt)(attempt), attempts: attempt, lastFailure: why }, { ...(testsAdded === undefined ? {} : { testsAdded }), ...kept });
+    }
+    /**
+     * 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.
+     */
+    async retainRejected(round, itemId, attempt, why, context) {
+        const failedStep = context.gate?.steps.find((s) => !s.skipped && !s.ok)?.step;
+        const named = failedStep === undefined ? {} : { failedStep };
+        const sink = this.deps.rejectedEvidence;
+        if (sink === undefined) {
+            return { ...named, evidenceIncomplete: 'no evidence store is wired for this run' };
+        }
+        let input;
+        try {
+            input = await this.rejectionInput(round, itemId, attempt, why, context);
+        }
+        catch (e) {
+            return { ...named, evidenceIncomplete: `evidence could not be gathered: ${e.message}` };
+        }
+        let outcome;
+        try {
+            outcome = await sink.retain(input);
+        }
+        catch (e) {
+            outcome = { retained: false, because: `evidence store threw: ${e.message}` };
+        }
+        this.rejections.set(itemId, { input, outcome });
+        return outcome.retained
+            ? { ...named, evidencePath: outcome.path }
+            : { ...named, evidenceIncomplete: outcome.because };
+    }
+    async rejectionInput(round, itemId, attempt, why, context) {
+        const git = this.deps.git;
+        const item = this.deps.queue.get(itemId);
+        const manifest = git.changedEntries !== undefined
+            ? await git.changedEntries()
+            : (await git.changedPaths()).map((path) => ({ path, status: '??' }));
+        /**
+         * ⚠️ AN ABORTED CANDIDATE'S PATCH IS WITHHELD. The rails fired because the
+         * change touched a path the project forbids; its content is precisely what
+         * must not be copied into a record. The manifest still names the paths.
+         */
+        const aborted = context.gate?.verdict === 'abort';
+        let patch = null;
+        let patchWithheld;
+        if (aborted) {
+            patchWithheld =
+                'the rails aborted this candidate: it touched a forbidden path, and the content of ' +
+                    'such a change is not retained';
+        }
+        else if (git.patch === undefined) {
+            patchWithheld = 'this git driver cannot produce a patch';
+        }
+        else {
+            patch = await git.patch(rejected_evidence_1.REJECTED_PATCH_MAX_BYTES);
+        }
+        const impl = context.implementer;
+        return {
+            run: { runId: this.id.runId, projectId: this.id.projectId, lane: this.id.lane, branch: this.id.branch },
+            round,
+            attempt,
+            itemId,
+            itemTitle: item?.title ?? '',
+            baseSha: await git.headSha(),
+            why,
+            stage: context.stage,
+            ...(context.gate === undefined
+                ? {}
+                : {
+                    gate: {
+                        verdict: context.gate.verdict,
+                        steps: context.gate.steps,
+                        diagnostics: context.diagnostics ?? [],
+                        ...(context.gate.abort === undefined ? {} : { abort: context.gate.abort }),
+                    },
+                }),
+            ...(context.proof === undefined ? {} : { proof: context.proof }),
+            ...(impl === undefined
+                ? {}
+                : {
+                    implementer: {
+                        result: impl.kind === 'result' ? impl.result : null,
+                        abandoned: impl.kind === 'abandoned' ? impl.reason : null,
+                        transcript: impl.transcript,
+                    },
+                }),
+            manifest,
+            patch,
+            ...(patchWithheld === undefined ? {} : { patchWithheld }),
+        };
+    }
+    /**
+     * 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.
+     */
+    async prepareRepair(item, attempt) {
+        let last = this.rejections.get(item.id);
+        let recoveredFrom;
+        if (last === undefined) {
+            // A restart between the rejection and this attempt: the memory is gone,
+            // the retained evidence is not. See `recoverRejection`.
+            const recovered = await this.recoverRejection(item);
+            if (recovered === undefined)
+                return undefined;
+            last = recovered.last;
+            recoveredFrom = recovered.from;
+        }
+        const { input, outcome } = last;
+        const previous = {
+            round: input.round,
+            attempt: input.attempt,
+            why: input.why,
+            stage: input.stage,
+            failedStep: input.gate?.steps.find((s) => !s.skipped && !s.ok)?.step ?? null,
+            evidencePath: outcome.retained ? outcome.path : null,
+            diagnostics: input.gate?.diagnostics ?? [],
+            manifest: input.manifest,
+            patch: input.patch === null ? null : { text: input.patch.text, truncated: input.patch.truncated },
+            patchWithheld: input.patchWithheld ?? null,
+            ...(recoveredFrom === undefined ? {} : { recoveredFrom }),
+        };
+        const base = { attempt, maxAttempts: core_1.MAX_ITEM_EXECUTION_ATTEMPTS, previous };
+        const refuse = (because) => this.noteRepair({ ...base, restored: { ok: false, because } });
+        const git = this.deps.git;
+        if (git.applyPatch === undefined)
+            return refuse('this git driver cannot restore a patch');
+        if (!outcome.retained || outcome.patchFile === null) {
+            return refuse(input.patchWithheld ?? 'the previous candidate was not retained');
+        }
+        if (input.patch === null || input.patch.truncated) {
+            return refuse('the retained patch is truncated and cannot be applied whole');
+        }
+        const head = await git.headSha();
+        if (head !== input.baseSha) {
+            return refuse(`the tree has moved on: the candidate was written against ${input.baseSha}, HEAD is ${head}`);
+        }
+        const paths = input.manifest.map((m) => m.path);
+        /**
+         * 🔴 THIS USED TO PERMIT `[...scope.free, ...scope.additive]`, WHICH IS
+         * THE ONE THING `additive` PROMISES NOT TO MEAN. Restoring a candidate
+         * writes its patch back into the tree, so a manifest that MODIFIED a file
+         * under an additive-only grant was put back by the check that existed to
+         * stop it — and this was the only place in the product where scope was
+         * compared against anything at all.
+         *
+         * It now asks the same fold the gate interlock asks, so a restore cannot
+         * be more permissive than the gate that will re-judge it.
+         */
+        const restoreEntries = input.manifest.map((m) => ({ path: m.path, status: m.status }));
+        const scopeFails = (0, scope_rule_1.scopeViolations)(restoreEntries, this.cfg.scope);
+        if (scopeFails.length > 0) {
+            const named = scopeFails.map((v) => `${v.path} (${v.because})`).join(', ');
+            return refuse(`the candidate touched paths outside the declared scope: ${named}`);
+        }
+        const railed = (0, glob_1.filterMatching)(paths, this.cfg.rails.forbiddenPaths);
+        if (railed.length > 0)
+            return refuse(`the candidate touched railed paths: ${railed.join(', ')}`);
+        const applied = await git.applyPatch(outcome.patchFile);
+        if (!applied.ok) {
+            await git.discard();
+            return refuse(applied.because);
+        }
+        return this.noteRepair({ ...base, restored: { ok: true, paths } });
+    }
+    /** Records what this round’s repair was, for `round.ended`, and hands the context back unchanged. */
+    noteRepair(ctx) {
+        this.roundRepair = {
+            previousAttempt: ctx.previous.attempt,
+            restored: ctx.restored.ok,
+            ...(ctx.restored.ok ? { restoredPaths: [...ctx.restored.paths] } : { notRestored: ctx.restored.because }),
+            ...(ctx.previous.recoveredFrom === undefined ? {} : { recoveredFrom: ctx.previous.recoveredFrom }),
+        };
+        return ctx;
+    }
+    /**
+     * 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".
+     */
+    async recoverRejection(item) {
+        const sink = this.deps.rejectedEvidence;
+        if (sink?.latestFor === undefined)
+            return undefined;
+        const found = await sink.latestFor({
+            itemId: item.id,
+            projectId: this.id.projectId,
+            lane: this.id.lane,
+            runId: this.id.runId,
+            attemptsSpent: item.attempts,
+            lastFailure: item.lastFailure,
+        });
+        if (!found.found) {
+            if (found.because !== null) {
+                this.roundRepair = { previousAttempt: null, restored: false, recoveryRefused: found.because };
+            }
+            return undefined;
+        }
+        return {
+            last: { input: found.input, outcome: found.outcome },
+            from: { runId: found.input.run.runId, evidencePath: found.outcome.path },
+        };
+    }
+    /**
+     * 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.
+     */
+    async discardAndReturn(round, state, itemId, why, 
+    /**
+     * Whether to drop the item's cached evidence along with the tree.
+     *
+     * ⚠️ FALSE FOR AN ENVIRONMENT BLOCK, and that is not an optimisation.
+     * §12 case 19's rationale for invalidating is "its next attempt must not
+     * start from the very file:line claims that just led into a wall" — and
+     * nothing ran, so no wall was met. Invalidating anyway makes the item a
+     * guaranteed cache miss, and `pickNext` then routes it through the VERIFIER
+     * before the next round: a paid model call, on the machine the preflight
+     * just declared unusable. Measured at one verifier turn per blocked round.
+     */
+    invalidateEvidence = true) {
+        await this.discardTree(itemId, invalidateEvidence);
+        return this.endRound(round, state, itemId, { state: 'ready', lastFailure: why });
+    }
+    async endRound(round, state, itemId, patch, extra = {}) {
+        const outcome = (0, core_1.outcomeOf)(state);
+        if (outcome === null)
+            throw new RunnerError(`round ended in non-terminal state ${state}`);
+        await this.patchItem(itemId, patch);
+        // The note goes on before `extra`, so a caller that has something better to
+        // say about this particular ending can still say it.
+        await this.emit('round.ended', {
+            round,
+            outcome,
+            itemId,
+            ...(this.roundNote === undefined ? {} : { note: this.roundNote }),
+            ...(this.roundRepair === undefined ? {} : { repair: this.roundRepair }),
+            ...extra,
+        });
+        this.totals[outcome] += 1;
+        /**
+         * WHERE THIS RED CAME FROM, counted — see {@link RunTotals.proverRejected}.
+         *
+         * `failedAtThisRound` is already maintained on every round regardless of
+         * `run.per_round_safety`, so this costs nothing and needs no flag. It is
+         * set to `'verifier'` exactly where the prover refutes or returns an
+         * unusable verdict, and to `'gate'` where a check went red — which is the
+         * distinction the summary was inventing.
+         */
+        if (outcome === 'discarded' && this.failedAtThisRound === 'verifier') {
+            this.totals.proverRejected = (this.totals.proverRejected ?? 0) + 1;
+        }
+        return outcome;
+    }
+    /**
+     * 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.
+     */
+    async patchItem(id, patch) {
+        const current = this.deps.queue.get(id);
+        if (current === undefined)
+            throw new RunnerError(`item ${id} vanished from the queue mid-round`);
+        const first = await this.deps.queue.update(id, current.version, patch);
+        if (first.ok)
+            return first.item;
+        if (first.reason === 'stale-version') {
+            const again = this.deps.queue.get(id);
+            if (again !== undefined) {
+                const second = await this.deps.queue.update(id, again.version, patch);
+                if (second.ok)
+                    return second.item;
+            }
+        }
+        throw new RunnerError(`queue write failed for ${id}: ${first.reason}`);
+    }
+    /** Same inputs `doctor` probes: prod env files that exist, plus the live env. */
+    collectEnvValues() {
+        const values = [];
+        for (const file of this.cfg.rails.prodEnvFiles) {
+            const text = this.deps.readEnvFile(file);
+            if (text !== null)
+                values.push(text);
+        }
+        for (const v of Object.values(this.deps.env)) {
+            if (v)
+                values.push(v);
+        }
+        return values;
+    }
+    async emit(kind, data, actor = 'runner') {
+        const input = {
+            ts: new Date(this.deps.now()).toISOString(),
+            runId: this.id.runId,
+            projectId: this.id.projectId,
+            lane: this.id.lane,
+            kind,
+            actor,
+            data,
+        };
+        await this.deps.ledger.append(input);
+    }
+}
+exports.RoundRunner = RoundRunner;
+//# sourceMappingURL=round-runner.js.map