@cerebriline/core 4.100.240

package/dist/runtime/atomic/protocol.d.ts

@@ -0,0 +1,233 @@
+import { type Oracle, type OracleVerdict } from "./oracle";
+/**
+ * How a transaction was judged, and by whom.
+ *
+ * `self-declared` is not a lesser flavour of the same thing and is never
+ * presented as one. An oracle answers about the program; a model answers about
+ * the edit it meant to make, and across the atomic campaign those disagreed
+ * routinely — transactions that reported success and failed the oracle were
+ * the normal case, because the model had fixed the error it was looking at and
+ * not the one the program still had.
+ *
+ * `undeclared` is a third thing and the weakest of the three: nothing could
+ * check the change and the model never said whether it worked. The files are
+ * kept, because discarding real work over a sentence nobody wrote is the
+ * failure this boundary exists to avoid -- but calling that `self-declared`
+ * would report a judgement that was never made.
+ */
+export type TransactionVerdictSource = "oracle" | "self-declared" | "undeclared";
+export interface TransactionOutcome {
+    /** One-based, in the order they were opened. */
+    transaction: number;
+    kept: boolean;
+    /**
+     * Not kept, and not rolled back either.
+     *
+     * The check said something it had never said before in this run, which is
+     * the one observable that separates an attempt that moved the problem from
+     * one that failed on the same wall. The changes stayed on disk and the next
+     * transaction opened on top of them, with the rollback target unchanged.
+     */
+    carried?: boolean;
+    source: TransactionVerdictSource;
+    /** What the model said it would change, as it declared it. */
+    plan?: string;
+    /** What the model said about the change when it tried to end the turn. */
+    account?: string;
+    /** The oracle's output, or the model's own account when there was none. */
+    evidence: string;
+}
+export interface ProtocolPromptInput {
+    /** One-based number of the transaction about to open. */
+    transaction: number;
+    /** Hard limit on declared changes. Three, unless the host says otherwise. */
+    maxChanges: number;
+    /** Last transaction this task will get, so the model knows the budget. */
+    maxTransactions: number;
+    /**
+     * Something the host wants said on the last transaction only.
+     *
+     * The escalation offer uses it. Kept as opaque text because the protocol
+     * has no business knowing what an expert is.
+     */
+    lastTransactionNotice?: string;
+    /** The check that will decide, when there is one. */
+    oracle?: Oracle;
+    /**
+     * Whether the model may name its own check, for a workspace with none.
+     *
+     * Only ever true where `oracle` is absent and there is a user to approve
+     * one: the alternative in that case is the model's own account of its work,
+     * which is the verdict every wrong outcome measured so far came from.
+     */
+    canProposeCheck?: boolean;
+    /**
+     * Whether the check this run adopted has yet to pass on any files at all.
+     *
+     * Changes what the record of earlier transactions is allowed to conclude.
+     */
+    checkNeverPassed?: boolean;
+    /** Whether the model may replace that check, this transaction, once. */
+    canReplaceCheck?: boolean;
+    /**
+     * Whether the check came from the host rather than from the model.
+     *
+     * A different situation from `checkNeverPassed`, which only ever describes
+     * a check the model proposed and may replace. This one cannot be replaced:
+     * the user named it, so a run that keeps failing it is not evidence against
+     * the check.
+     */
+    hostSuppliedCheck?: boolean;
+    /** What earlier transactions tried, in order. */
+    history: readonly TransactionOutcome[];
+}
+/**
+ * The rules, restated in full at the open of every transaction.
+ *
+ * Repeated rather than referred back to, the way the harness does it: a
+ * transaction the model experiences as a continuation of a conversation still
+ * has to be one it can see the rules of, and a rule that scrolled out of the
+ * window is a rule that is not followed. The cost is a few hundred tokens per
+ * transaction against a protocol that only works if it is understood.
+ */
+export declare function buildProtocolPrompt(input: ProtocolPromptInput): string;
+/**
+ * What the model is told when it ends a transaction it never changed.
+ *
+ * Not the protocol rules again. The rules are already in the window — it read
+ * them when the transaction opened and followed none of them — so restating
+ * them buys another few hundred tokens of the same. What is new is that the
+ * submission was empty, that it cost nothing, and how much budget is left.
+ *
+ * IT MUST NOT OFFER AN EXIT. The first version ended with "if you have run out
+ * of ideas, say so plainly in one sentence and stop... it is not counted
+ * against you". Measured on pandorum session 1789114968332_v7fsq
+ * (JackDeltaCoder 9B, 4.100.92): the model took that offer on its first empty
+ * attempt and closed the run, reporting that "all my edits failed to match any
+ * lines" — which the transcript contradicts, since one edit had applied and it
+ * had used `restore_file` six times to undo its own work. A model facing a task
+ * it finds hard reads a sanctioned, unpenalised exit as permission, and a small
+ * one takes it immediately.
+ *
+ * So this says the opposite: the budget is counted out loud, an empty
+ * submission is named as an attempt that has not happened rather than a failed
+ * one, and the next step is concrete. Stopping is still possible — nothing
+ * here prevents it — but it is no longer suggested, and no longer described as
+ * worth more than trying again.
+ */
+export declare function buildEmptyAttemptPrompt(input: {
+    transaction: number;
+    maxChanges: number;
+    maxTransactions: number;
+    /**
+     * The check, run at the boundary, that disagrees with the model's decision
+     * to stop. Present only when it failed: a completion on top of a failing
+     * check is a fix being reported rather than made, and the model is told so
+     * in the same message that tells it the transaction is still open.
+     */
+    check?: {
+        label: string;
+        output?: string;
+    };
+    /**
+     * No tool was called in this transaction at all. Worth saying, because the
+     * advice that follows assumes edits were tried and refused, and here
+     * nothing has been tried — the useful next move is the first tool call, not
+     * a better plan.
+     */
+    neverBegan?: boolean;
+}): string;
+/**
+ * The line an empty submission ends on, for the user and for the log.
+ *
+ * Worth a line of its own precisely because it is not a verdict: no check ran,
+ * nothing was put back, and a run where this happened reads — from the
+ * transcript alone — like a transaction that quietly went missing.
+ *
+ * `continued` says which of the two things is about to happen: the transaction
+ * is held open for another attempt, or it has come back empty often enough
+ * that it is spent and closed like any other. Neither of them ends the run.
+ */
+export declare function describeEmptyAttempt(transaction: number, continued: boolean, neverBegan?: boolean): string;
+/**
+ * What a turn that called nothing is told, while the guard is still holding.
+ *
+ * Deliberately not phrased as a submission. The message this replaces opened
+ * "TX-01 was submitted with…", which was a report of something the model had
+ * not done — it had thought a turn through and called nothing, and the protocol
+ * treated that as an act. On a model that could not reconcile the two, that
+ * produced six identical boundary messages and reasoning reading "I keep
+ * failing to emit actual tool calls".
+ *
+ * So this says what actually happened, names the tool that does submit, and is
+ * honest that the guard exists and when it fires.
+ */
+export declare function describeSilentTurn(input: {
+    transaction: number;
+    silent: number;
+    before: number;
+    untouched: boolean;
+    check?: {
+        label: string;
+        output?: string;
+    };
+}): string;
+/**
+ * The line a run ends on when the model never called a tool.
+ *
+ * The backstop for an unstarted transaction, and it says what actually
+ * happened. The alternative this replaces — spending a transaction per pair of
+ * quiet turns — left six discarded transactions behind and read as six failed
+ * attempts when nothing had been attempted once.
+ */
+export declare function describeNeverStarted(transaction: number, attempts: number): string;
+/**
+ * The line a transaction ends on, for the user and for the log.
+ *
+ * Says which of the two things happened to their files, because "discarded" is
+ * the word that matters and it has to be unmissable.
+ */
+export declare function describeVerdict(transaction: number, kept: boolean, source: TransactionVerdictSource, verdict?: OracleVerdict, forced?: boolean, carried?: boolean): string;
+/**
+ * What the model is told when the user turns the protocol off mid-run.
+ *
+ * Sent as a steer, not a queued message, and so delivered after the previous
+ * turn's tool results and before the next model request -- the one window in
+ * the loop where no edit is in flight. That matters for more than tidiness: a
+ * discarded transaction puts every file it touched back, and doing that while
+ * an `editor` call is open would rewrite the file underneath the call that is
+ * writing it. So the rollback happens at this same boundary, and this message
+ * reports what has *already* happened rather than warning about what is about
+ * to.
+ *
+ * Three things it has to get right, each learned from a way a model reads a
+ * message like this wrongly:
+ *
+ * 1. **Whose decision this was.** A model told only that the protocol stopped
+ *    reads it as a verdict on its work and starts apologising or re-doing the
+ *    change. It is the user's choice about how the session runs, and saying so
+ *    first is what stops that.
+ * 2. **That the files on disk may have moved.** A rollback invalidates every
+ *    read the model is holding. The host forgets the receipts mechanically
+ *    (`forgetReads`), so the next edit is refused until the file is read again
+ *    -- but a model that does not know why reads the refusal as a bug and
+ *    retries the same call. Saying it here turns a confusing refusal into an
+ *    expected one.
+ * 3. **That the tools are gone.** The protocol's tools leave with it. A model
+ *    that calls `submit_transaction` afterwards gets an unknown-tool error and
+ *    no explanation, and unknown-tool errors are the kind a model repeats.
+ *
+ * The verdict line is passed in already written rather than rebuilt here, so
+ * the sentence the model reads is character for character the one it would have
+ * read had the transaction closed on its own.
+ */
+export declare function describeDisengagement(input: {
+    /** The transaction that was open, if one was. */
+    transaction?: number;
+    /** `describeVerdict` for that transaction, if one was judged. */
+    verdict?: string;
+    /** Files put back by the rollback. Absent or zero means nothing moved. */
+    filesPutBack?: number;
+    /** Whether the judged transaction was kept. */
+    kept?: boolean;
+}): string;

package/dist/runtime/atomic/restore-file-tool.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Put one file back to what it said when this transaction opened.
+ *
+ * The rollback the protocol already performs, made available before the
+ * transaction ends and narrowed to a single file. The model that has just
+ * broken something can undo exactly that, keep everything else it got right,
+ * and carry on.
+ *
+ * Why it is worth a tool. Measured on the run that prompted it (pandorum,
+ * 2026-09-05): three discarded transactions, 7328s, and 22 of 43 edits went to
+ * a line the same transaction had already edited. The model announced it had
+ * damaged the file nineteen times — "I accidentally deleted the entire `dDec`
+ * method", "I accidentally merged dGrid and dDec into one line!" — and each
+ * time set about rebuilding a 400-character minified line from memory. 91% of
+ * that run's wall clock came after the first of those.
+ *
+ * What it takes with it. The base is the whole file as the transaction found
+ * it, so a restore discards anything changed in that file since the
+ * transaction opened — including an edit the user made in their own editor
+ * while it was open. That is not new: the rollback at the transaction boundary
+ * has always had exactly this reach, and this only brings it forward and
+ * narrows it to one file. It is worth knowing rather than discovering.
+ *
+ * Why it is bounded. The same model class has been measured issuing twelve
+ * `rm` of the file under test in one transaction, recreating it whole each
+ * time, and losing the file when the twelfth outlived the transaction. A cheap
+ * undo lowers the price of a reckless edit, so this one counts itself, says so
+ * every time, and stops. A restore loop that announces itself is the point:
+ * the failure it replaces was silent and cost two hours.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+import { type RevisionLog } from "./file-revisions";
+import type { Snapshot } from "./snapshot";
+export declare const RESTORE_FILE_TOOL_NAME = "restore_file";
+/**
+ * Restores one transaction is allowed before it is told to stop.
+ *
+ * Nine. It was three, on the reasoning that a fourth restore in one
+ * transaction is not a recovery but the loop -- and for a model that edits
+ * accurately it still is. For one that does not, the cap turned out to be the
+ * thing that ended the run rather than the thing that saved it.
+ *
+ * Measured on a JackDelta 9B session: 19 restore attempts, 8 of them refused
+ * because the cap was already spent, and the model then named the cap as its
+ * reason for giving up in three separate transactions -- "exhausted restore
+ * slots (3/3)" in TX-02, and the same again in TX-03 and TX-05. Faced with a
+ * mangled file it could neither restore nor repair, it submitted an apology
+ * instead of a change. The cap was doing the opposite of its job: the
+ * transaction still gets rolled back wholesale if the check fails, so a
+ * restore costs nothing but the tokens, while refusing one costs the
+ * transaction.
+ *
+ * It was then nine, for the same reason, and nine was still too few. Measured
+ * on pandorum session 1789122866533_br1d0 (JackOD 9B, 4.100.94): the
+ * transaction spent all nine and was refused twice more, and the model's own
+ * account of why it stopped names the state it could not get out of -- "this
+ * transaction has accumulated 14+ failed/rolled-back attempts with no clean fix
+ * landing on disk", ending in a question to the user rather than a change.
+ * Twenty-seven is three times the last figure and, unlike it, is not a number
+ * the measured runs reach.
+ *
+ * The cap costs more than it saves at small sizes and the asymmetry is not
+ * close. A restore cannot lose the file -- it writes the base revision back, so
+ * the worst case is tokens -- while refusing one strands a model in a file it
+ * mangled, and the transaction is rolled back wholesale anyway if the check
+ * fails. The looping this was meant to catch is caught better elsewhere now:
+ * `MAX_NOOP_RESTORES_PER_TRANSACTION` stops the degenerate case where nothing
+ * is being undone at all, which is what the 102-restore run actually was, and
+ * the repeated-call guard stops an identical call being retried. This number
+ * only has to stop a model restoring real work in circles forever, and it is
+ * the last line rather than the first.
+ */
+export declare const MAX_RESTORES_PER_TRANSACTION = 27;
+/**
+ * No-op restores answered before the tool stops answering them.
+ *
+ * A restore of a file that already matches the base changes nothing, so it
+ * never touched the budget above and never refused. That made it free, and a
+ * free call that returns a reassuring sentence is a loop waiting to happen.
+ *
+ * Measured on pandorum session 1789117848964_zhbk5 (JackOD 9B, 4.100.93):
+ * 108 `restore_file` calls in a single transaction, of which **102 were
+ * no-ops** and 6 were real -- against a cap of 9 that was therefore never
+ * reached. The model was told "that is 102 times you have asked" and asked
+ * again. 212 tool calls and 33 minutes went to a transaction that never
+ * closed.
+ *
+ * Three, and they are counted across the transaction rather than
+ * consecutively: while the file matches the base there is nothing to undo, and
+ * that is equally true whatever the model did in between. Three leaves room
+ * for the honest case -- an edit that did not apply, restored out of caution --
+ * without leaving the door open on a hundred.
+ */
+export declare const MAX_NOOP_RESTORES_PER_TRANSACTION = 3;
+export declare const RESTORE_FILE_TOOL_DESCRIPTION = "Put one file back exactly as it was when this transaction opened, discarding every change you have made to it since.\n\nUse it the moment an edit goes wrong in a way you would otherwise have to undo by hand \u2014 you deleted more than you meant to, you merged two lines together, you have rewritten the same line four times and it is further from working than when you started. Restoring is exact. Retyping the original from memory is not, and on a long or minified line it is where runs go to die.\n\nIt affects one file. Anything you changed in other files this transaction stays. If the file did not exist when the transaction opened, restoring it deletes it.\n\n**You do not have to go all the way back.** Every time a tool writes a file, that version is kept and numbered, and `revision` says which one to return to:\n\n- `revision: \"last\"` undoes only your most recent change to the file, keeping everything before it. This is almost always the one you want after a single edit goes wrong.\n- `revision: \"#3\"` (or `3`) returns to that numbered version. Every edit's result tells you the number it just made, and every read of the file lists the ones you can go back to.\n- `revision: \"original\"` is the file as this transaction opened, which is what you get if you say nothing.\n\nGoing back one step is not the same as starting again. If you have fixed three things and broken the fourth, `last` keeps the three.\n\nThis is not the end of the transaction and it does not spend one \u2014 you carry on, from the file as it was. Read the file again afterwards: its line numbers are back to what they were at that revision, and any range you read earlier no longer addresses the same code.\n\nIf you only want to *see* what the file said before your changes, do not restore it \u2014 call `read_files` with `revision: \"base\"` and it is shown to you with the file left alone.";
+/**
+ * The same tool, described for a session that has no transactions.
+ *
+ * Written separately rather than templated, because almost every sentence in
+ * the transaction version is about the transaction: what the base is, what
+ * survives, what a restore does not spend. Here the base is the file as this
+ * session first found it, there is nothing to spend, and the one thing that
+ * carries over unchanged is the part that matters — going back is exact and
+ * retyping from memory is not.
+ */
+export declare const RESTORE_FILE_TOOL_SESSION_DESCRIPTION = "Put one file back to a version of it you had earlier, discarding what you have written to it since.\n\nUse it the moment an edit goes wrong in a way you would otherwise have to undo by hand \u2014 you deleted more than you meant to, you merged two lines together, you replaced the file with something that was never meant to be its contents. Restoring is exact. Retyping the original from memory is not, and on a long or minified line it is where runs go to die.\n\nEvery time a tool writes a file, that version is kept and numbered, and `revision` says which one to return to:\n\n- `revision: \"last\"` undoes only your most recent change to the file, keeping everything before it. This is almost always the one you want after a single edit goes wrong.\n- `revision: \"#3\"` (or `3`) returns to that numbered version. Every edit's result tells you the number it just made, and every read of the file lists the ones you can go back to.\n- `revision: \"original\"` is the file as it stood before this session first wrote to it, which is what you get if you say nothing.\n\nIt affects one file, and only files this session has written: a file nothing has touched has no earlier version held, and this will say so rather than guess.\n\nRead the file again afterwards: its line numbers are back to what they were at that revision, and any range you read earlier no longer addresses the same code.\n\nIf you only want to *see* what the file said before your changes, do not restore it \u2014 call `read_files` with `revision: \"original\"` (or a number) and it is shown to you with the file left alone.";
+export declare const RESTORE_FILE_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly path: {
+            readonly type: "string";
+            readonly description: "The file to put back, absolute or relative to the workspace root.";
+        };
+        readonly revision: {
+            readonly type: "string";
+            readonly description: "Which version to return to: \"last\" to undo only your most recent change to this file, a number such as \"#3\" for that version, or \"original\" for the file as this transaction opened. Defaults to \"original\".";
+        };
+        readonly find: {
+            readonly type: "string";
+            readonly description: "Search this file's revisions instead of restoring anything: the text you are looking for, matched against each revision's note and its contents. Nothing is written and no restore is spent. Use it when you know what you want back but not which number holds it — a method you deleted, a line that used to read differently, or your own note about a change.";
+        };
+        readonly reason: {
+            readonly type: "string";
+            readonly description: "One sentence: what went wrong with this file that restoring it undoes.";
+        };
+    };
+    readonly required: readonly ["path"];
+};
+/** The part of the controller this tool drives. */
+export interface RestoreFileSource {
+    /** The open transaction's base, or nothing when none is open. */
+    readonly pending: Snapshot | undefined;
+    /** Which transaction is open, or 0 when there is no protocol. */
+    readonly transaction: number;
+    /** Every version of every file a tool has written. */
+    readonly revisions: RevisionLog;
+    /**
+     * Where paths resolve when no transaction is open.
+     *
+     * Supplying it is what makes the tool work with the change protocol off.
+     * The base then comes from the log -- `#1`, seeded from the file itself at
+     * first touch -- rather than from a snapshot, so the undo covers this
+     * session's writes to that one file instead of the whole tree. Left out,
+     * a call with no transaction open is refused exactly as it was.
+     */
+    readonly root?: string;
+}
+export interface RestoreFileToolOptions {
+    controller: RestoreFileSource;
+    /**
+     * Retires what the model had read about this file.
+     *
+     * A restore moves every line in the file, so the reads that justify an edit
+     * by line number no longer describe it. Without this the editor's
+     * read-before-edit guard — the one thing standing between a stale line
+     * number and the file on disk — waves through an edit aimed at code that
+     * has since moved. Hosts that own the receipts supply it; one that does not
+     * gets a restore whose warning is only words.
+     */
+    forgetReads?: (absolutePath: string) => void;
+    /** For the host to say, in its own voice, that a file was put back. */
+    onRestored?: (event: {
+        path: string;
+        transaction: number;
+        deleted: boolean;
+    }) => void;
+    onError?: (message: string, error: unknown) => void;
+    /**
+     * Which world this instance is describing.
+     *
+     * `session` swaps the description for one that does not talk about
+     * transactions. The execute path already tells them apart from
+     * `controller.pending`; this is the half that is fixed at creation time.
+     */
+    scope?: "transaction" | "session";
+}
+export declare function createRestoreFileTool(options: RestoreFileToolOptions): AgentTool;
+/**
+ * Real restores in one transaction before the tool says what that many means.
+ *
+ * Measured on the JackOD4-AC 9B arm: 13.6 `restore_file` calls per run against
+ * 0.23 for qwen3.6 27B over 40 runs, a factor of 59. Within the arm the count
+ * is near-monotonic with wall time -- the three runs that restored nothing were
+ * the three fastest successes, and the three highest counts (28, 30, 36) were
+ * the three timeouts. One of them deleted 4,939 bytes, 35% of the file, before
+ * it reached the cap.
+ *
+ * Three is early on purpose, because this is a sentence and not a refusal. The
+ * cap that refuses is `MAX_RESTORES_PER_TRANSACTION` and it is deliberately
+ * generous: a restore is the right call for an edit that went wrong, and a
+ * model told to stop restoring goes back to retyping the original from memory,
+ * which is how the runs this came from actually lost files.
+ */
+export declare const RESTORE_HABIT_AFTER = 3;
+/** Where the same sentence stops being a nudge and starts being the answer. */
+export declare const RESTORE_HABIT_INSISTS_AFTER = 6;

package/dist/runtime/atomic/revision-capture.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Capture a revision of every file a tool writes.
+ *
+ * The choke point the change protocol never had. `withChangeSignal` next door
+ * answers "did something change" for the stalled-check counter; this answers
+ * "what did it say afterwards", which is what makes going back to a particular
+ * point possible at all.
+ *
+ * Coverage is deliberately not "re-walk the tree after every call". A snapshot
+ * reads every file under the root, and doing that per edit makes a real
+ * repository unusable. Instead the tools that name what they write are asked
+ * what they wrote, and `run_commands` -- which can write anything -- re-checks
+ * the files the model has already touched. That is where the realistic desync
+ * is: a `sed -i` or a shell redirect over the file being edited, which would
+ * otherwise leave the log claiming a revision that is no longer on disk and
+ * make a later restore resurrect stale content.
+ *
+ * What is NOT covered, stated so it is known rather than discovered: a
+ * `run_commands` that writes a file the model has never touched with a tool.
+ * That file has no revisions, `restore_file` says so, and the transaction
+ * rollback still covers it because the base snapshot does.
+ */
+import type { AgentToolDefinition } from "@cerebriline/shared";
+import { type RevisionLog } from "./file-revisions";
+import type { Snapshot } from "./snapshot";
+export interface RevisionCaptureSource {
+    /** The open transaction's base, or nothing when none is open. */
+    readonly pending: Snapshot | undefined;
+    /**
+     * Where paths resolve and what counts as inside, when there is no
+     * transaction.
+     *
+     * Supplying it is what makes capture session-scoped: `#1` is seeded from the
+     * file's own content at first touch instead of from a base snapshot, and the
+     * log outlives every transaction because it never belonged to one. Left out,
+     * a session with no open transaction captures nothing, which is what every
+     * caller did before this existed.
+     *
+     * The promise changes with it and the label says so. Inside a transaction
+     * `#1` is what a rollback returns the whole tree to; outside one it is what
+     * this one file said before this session touched it. "Can the rollback reach
+     * this path" stops being a precondition of recording history and becomes a
+     * question the rollback asks -- which is the point, since the history is
+     * worth having in a session that has no rollback at all.
+     */
+    readonly root?: string;
+    /** Which transaction is open. */
+    readonly transaction: number;
+    /** Where the revisions go. */
+    readonly log: RevisionLog;
+}
+export interface RevisionCaptureOptions {
+    readonly source: RevisionCaptureSource;
+    /** Read a file as it stands, or nothing when it does not exist. */
+    readFile(absolutePath: string): Promise<Buffer | undefined>;
+    /**
+     * What the checker last said, when it has run and said anything.
+     *
+     * Appended to the label rather than used as it: it answers "was this
+     * working here", which is a different question from "what changed here",
+     * and for plenty of files -- a README, anything the checker does not look
+     * at -- it has nothing to say at all.
+     */
+    lastCheck?(): string | undefined;
+}
+/**
+ * Every path an `apply_patch` payload names.
+ *
+ * The paths are in the patch grammar rather than in a field, so they are read
+ * out of the text. A payload whose header this does not match captures
+ * nothing, which is the same position a `run_commands` write is in — covered
+ * by the transaction rollback, not by a revision.
+ */
+export declare function patchTargets(payload: string): string[];
+export declare function withRevisionCapture<T extends AgentToolDefinition>(tools: readonly T[], options: RevisionCaptureOptions): T[];

package/dist/runtime/atomic/run-check-tool.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Run the check that judges this run, on demand, without settling anything.
+ *
+ * Why it exists. The check reached the model from exactly one place — `settle`,
+ * at the completion attempt — while the tool that proposes it told the model
+ * the opposite: "it is run for you, unattended, every time your turn ends, and
+ * its result comes back to you". So the model believed it had a feedback loop,
+ * did not build one of its own, and got no verdict at all until the transaction
+ * was over. Measured on pandorum 2026-09-05 under 4.100.68: TX-01 ran 341
+ * messages and 65 edits with nothing judged, then one `SyntaxError: missing )
+ * after argument list` at the end, then a full rollback — after which the model
+ * copied the original file back over its work and started again.
+ *
+ * The arm that works has never had this problem, and not because its check is
+ * better. There the check is a shell line named in the opening prompt, so the
+ * model simply reruns it whenever it wants — 88 `run_commands` in one run that
+ * ended FIXED. A check the model cannot type is a check it cannot consult, and
+ * the only remedy is to hand it one.
+ *
+ * It settles nothing and rolls nothing back. A failing result here is
+ * information, not a verdict: the transaction is still open and the files are
+ * still the model's.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+import type { Oracle, OracleVerdict } from "./oracle";
+export declare const RUN_CHECK_TOOL_NAME = "run_check";
+/**
+ * Runs per transaction before the model is told to stop.
+ *
+ * Ten, which is deliberately generous next to the protocol's other budgets:
+ * this is the one call that is *supposed* to be made repeatedly, and a model
+ * that checks after every edit is doing exactly what the check is for. The
+ * ceiling exists for the loop that checks without editing — measured on the
+ * same class of run as `restore_file`'s — not to ration the loop that works.
+ */
+export declare const MAX_CHECKS_PER_TRANSACTION = 10;
+export declare const RUN_CHECK_TOOL_DESCRIPTION = "Run the check that decides whether this task is done, right now, against the files as they currently stand.\n\nThis is your feedback loop. Nothing is settled and nothing is rolled back: the result is information, the transaction stays open, and your changes stay in place whatever it says.\n\nRun it early, on the unmodified files, so you see the failure you are fixing in the check's own words rather than inferring it. Run it after each change. A change you have not run it against is a change you are guessing about, and your own reading of the code is the weakest evidence available to you.\n\nTake no output as no output. If the check passes, say so and finish; the same check runs once more when you do.";
+export declare const RUN_CHECK_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {};
+    readonly required: readonly [];
+};
+/** The part of the controller this tool drives. */
+export interface CheckRunner {
+    readonly oracle: Oracle | undefined;
+    readonly transaction: number;
+    runCheck(): Promise<OracleVerdict>;
+}
+export interface RunCheckToolOptions {
+    controller: CheckRunner;
+    /** Whether a check could still arrive, for the message when there is none. */
+    canProposeCheck?: boolean;
+    /**
+     * Told about every run, and given the chance to add to what the model is
+     * told about it. Anything returned is appended to the result -- which is how
+     * a transaction closed out from under a stalled check gets its settlement
+     * and the next transaction's rules into the same reply as the verdict.
+     */
+    onRun?: (verdict: OracleVerdict, oracle: Oracle) => string | void | Promise<string | void>;
+    onError?: (message: string, error: unknown) => void;
+}
+/** What the model is told, so a passing and a failing run read differently. */
+export declare function describeCheckRun(verdict: OracleVerdict, label: string): string;
+export declare function createRunCheckTool(options: RunCheckToolOptions): AgentTool;