@cerebriline/core 4.100.240

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

@@ -0,0 +1,304 @@
+import type { AgentTool, AgentToolDefinition } from "@cerebriline/shared";
+import type { CoreAtomicProtocolConfig } from "../../types/config";
+import { type RevisionOverlay } from "./base-revision-reads";
+import type { RevisionLog } from "./file-revisions";
+import { type Oracle } from "./oracle";
+import type { CheckApprover } from "./proposal";
+import { type SelfReport, TransactionController, type TransactionEvent } from "./transaction-controller";
+/**
+ * Changes a transaction may declare, unless the user says otherwise.
+ *
+ * Six. It was three, from the harness campaign that produced this protocol,
+ * where the models under test were large enough that three declared changes
+ * was a comfortable budget and the limit did what it was for -- stopping a
+ * shotgun rewrite. On a 9B it does something else. Measured on a JackDelta 9B
+ * session: the model made 56 editor calls in TX-01 against a ceiling of three
+ * declared changes, so the ceiling was not restraining the work, it was only
+ * making the declaration a fiction the model abandoned. A small model that
+ * needs four small edits to remove one symptom has to either under-declare or
+ * ignore the number, and it ignored it.
+ *
+ * Six leaves the limit meaning what it says while giving a model that works in
+ * smaller steps room to describe what it is actually going to do. It is still
+ * a ceiling and the prompt still says so.
+ */
+export declare const DEFAULT_MAX_CHANGES = 6;
+/**
+ * Attempts a task gets. Six, as the harness this comes from runs it: measured
+ * across that campaign the fix landed in the first three transactions or not at
+ * all, and the later ones bought re-readings of the same symptom.
+ */
+export declare const DEFAULT_MAX_TRANSACTIONS = 6;
+/**
+ * Empty submissions a transaction absorbs before it is spent.
+ *
+ * One, and bounded for the same reason the runtime bounds its no-tool-call
+ * nudge: asking a model that has stopped working to carry on is worth a turn,
+ * and asking a third time is a spin with a wall clock on it.
+ *
+ * Measured on the harness this protocol comes from. A run whose first
+ * transaction was discarded closed the remaining five in about nine minutes
+ * without a single edit between them — one iteration each, no tool calls, and
+ * the work file byte-identical to the seeded source at the end. It read as six
+ * failed attempts and it was one.
+ *
+ * What happens after the budget is spent is not the run ending. The transaction
+ * is settled like any other, which closes it, writes the retrospective and
+ * opens the next with the rules in full — so a model that keeps submitting
+ * nothing is stopped by running out of transactions rather than by a second
+ * rule nobody counted.
+ */
+export declare const DEFAULT_MAX_EMPTY_ATTEMPTS = 1;
+/**
+ * Empty submissions a transaction absorbs when **no tool was called in it at
+ * all**, before the run is stopped and told why.
+ *
+ * Separate from the budget above, and much larger, because it counts a
+ * different thing. A transaction the model worked in — read files, ran the
+ * check, had an edit refused — and then submitted with nothing changed is an
+ * attempt that failed, and spending it is fair. A transaction it spent
+ * thinking, calling nothing, is not an attempt at all, and spending it charges
+ * the model for work it never got to do.
+ *
+ * A reasoning model takes turns without calling tools; that is what reasoning
+ * models do. Under the old rule one nudge and two quiet turns spent a
+ * transaction, so roughly four turns of thinking cost an attempt and the whole
+ * six-transaction budget could go in about twenty turns without one edit ever
+ * being tried. The note on `DEFAULT_MAX_EMPTY_ATTEMPTS` describes that run
+ * exactly — "it read as six failed attempts and it was one" — and answers it by
+ * spending faster, which makes the misreading arrive sooner rather than
+ * removing it.
+ *
+ * So an unstarted transaction is no longer spent. It is held open, and the
+ * turn-level non-convergence guard in the runtime does the nudging, which is
+ * what that guard is for and why it is documented as nudging and never ending.
+ * This number is only the backstop that keeps a model which will never call a
+ * tool from holding a session open forever — and when it fires the run ends
+ * saying that, instead of leaving behind six discarded transactions that
+ * suggest six attempts were made.
+ */
+export declare const DEFAULT_MAX_UNSTARTED_ATTEMPTS = 6;
+/**
+ * Silent turns the boundary absorbs before it submits the transaction itself.
+ *
+ * The boundary used to BE the submission. `onCompletionAttempt` is reached from
+ * one place in the runtime — a turn that called no tools — so a model that
+ * thought a turn through and called nothing had, as far as the protocol was
+ * concerned, submitted. It was then told so, in those words, for something it
+ * had not done. Measured on pandorum 2026-09-12 under 4.100.103: ten turns, no
+ * tool calls, six boundary messages, and reasoning that reads "I keep failing
+ * to emit actual tool calls" and "I have called none of those yet". The model
+ * was not confused about the task; it was reacting to a report of an act it had
+ * not performed.
+ *
+ * It is also the one thing the rest of the contract forbids. The no-tool-call
+ * nudge exists to stop a turn ending without a call, and the protocol's only
+ * exit was to do exactly that. A model strong enough to hold both ideas at once
+ * absorbs the contradiction; a smaller one either breaks on it or calls tools
+ * it does not need in order to avoid ending a turn.
+ *
+ * So `submit_transaction` is the submission now, and the model decides when.
+ * This is what the boundary is demoted to: a guard for a run that has stopped
+ * calling anything at all. Three, because one silent turn is a model thinking
+ * and two is a model thinking twice — neither is a run that has stopped.
+ */
+export declare const DEFAULT_SILENT_TURNS_BEFORE_GUARD = 3;
+export interface AtomicProtocolSessionOptions {
+    /**
+     * The session's file-history log, shared rather than made here.
+     *
+     * See `TransactionControllerOptions.revisions`. The host keeps one per
+     * session so the ledger and recovery work with the protocol off.
+     */
+    revisions?: RevisionLog;
+    workspaceRoot: string;
+    config: CoreAtomicProtocolConfig | undefined;
+    onEvent?: (event: TransactionEvent) => void;
+    /**
+     * `log`, not `debug`. Which check a change will be judged by — and whether
+     * there is one at all — is operational rather than diagnostic, and on the
+     * CLI a debug line is below the default level: the first live check of this
+     * feature read as "the config never arrived" for exactly that reason.
+     */
+    logger?: {
+        log?: (message: string) => void;
+    };
+    /**
+     * Said to the user, not to the log: whether the protocol engaged, and why.
+     *
+     * A log line is the wrong place for this. Measured on the first live use:
+     * the protocol was on, the workspace held one HTML file and nothing
+     * that could be run, so the protocol stood down exactly as designed — and
+     * from the chat that is indistinguishable from a feature that is broken, or
+     * from one that is running and has had nothing to judge yet. The user's
+     * report was "I don't see any engagement of the atomic transaction even if
+     * it's enabled", which is the only thing they could have concluded.
+     */
+    onStatus?: (status: {
+        armed: boolean;
+        message: string;
+    }) => void;
+    /**
+     * Asks the user to approve a check the model proposed.
+     *
+     * Its presence is what makes a workspace with nothing to run worth arming
+     * at all: the alternative there is the model judging its own work, and
+     * a host with nobody to ask -- cron, automation, a CLI with no terminal --
+     * leaves this out and gets the old behaviour.
+     */
+    approveCheck?: CheckApprover;
+    /**
+     * A second file history that answers `revision` while it is live.
+     *
+     * The escalation's, when the host wired one up. Passed through rather than
+     * decorated on top, because `read_files` can only be widened once: an outer
+     * decoration would consume `revision` and the protocol's own would never
+     * see it. See `RevisionOverlay`.
+     */
+    revisionOverlay?: RevisionOverlay;
+    /**
+     * Whether the model may propose its own check where nothing can be run.
+     *
+     * Defaults on. Off restores the verdict that preceded it -- the model's own
+     * account of its work -- which is weaker evidence and measurably faster:
+     * across one workspace the proposed-check runs took four to six times the
+     * model time of the self-declared ones and closed nothing. This is here so
+     * the two can be compared on the same task rather than across releases.
+     */
+    proposeCheck?: boolean;
+    /** Proposals put to the user before the run gives up on having a check. */
+    maxCheckProposals?: number;
+    /**
+     * Discarded attempts before a check that has never passed may be replaced.
+     *
+     * Zero is off, and off is the freeze exactly as it was. See
+     * `TransactionController.checkIsUnderReconsideration`.
+     */
+    checkReconsideredAfter?: number;
+    /**
+     * Retires what the model had read about a file the protocol put back.
+     *
+     * Supplied by hosts that own the read receipts. `restore_file` moves every
+     * line in the file it restores, so a read taken before it no longer
+     * describes the file — and the editor's read-before-edit guard is the only
+     * thing between a stale line number and the file on disk. A host that
+     * leaves this out still gets the restore; what it loses is the guard
+     * noticing.
+     */
+    forgetReads?: (absolutePath: string) => void;
+    /**
+     * Something the host wants said on the last transaction's opening prompt.
+     *
+     * Opaque: the protocol does not know what it is for. The escalation path
+     * uses it to offer the expert while there is still a transaction to hold
+     * whatever it does.
+     */
+    describeLastTransaction?: () => string | undefined;
+}
+export interface AtomicProtocolSession {
+    readonly controller: TransactionController;
+    /**
+     * The check this task is judged by, or nothing when it has none.
+     *
+     * Read through the controller rather than captured, because a check the
+     * user approves mid-run arrives after this session was built.
+     */
+    readonly oracle: Oracle | undefined;
+    /**
+     * Tools this protocol adds to the session, if any.
+     *
+     * Only `propose_check`, and only where there is nothing to run and someone
+     * to ask. A tool the model cannot usefully call is a tool that gets called.
+     */
+    readonly tools: AgentTool[];
+    /**
+     * The session's other tools, with what the protocol adds to them.
+     *
+     * Only `read_files`, which gains a `revision` for reading the file as this
+     * transaction found it. A decoration rather than a tool of its own, and
+     * applied here rather than at the tool's definition, so that a host running
+     * without the protocol keeps byte-for-byte the schema it had: there is no
+     * base revision without an open transaction, and advertising one anyway
+     * teaches a call that can only be refused.
+     */
+    decorateTools<T extends AgentToolDefinition>(tools: readonly T[]): T[];
+    /**
+     * The first transaction's rules, to go out with the task itself, once.
+     *
+     * In the user's message rather than the system prompt, which is where this
+     * started. The harness this protocol comes from puts the identical text in
+     * the opening message, and this matches the arm the campaign was measured
+     * on; it is not a demonstrated improvement, and nothing here should be read
+     * as one.
+     *
+     * A warning for anyone measuring this, learned by getting it wrong: count
+     * applied edits, not editor calls. Two system-prompt runs looked like eight
+     * and twenty-six changes against a limit of three, which reads as a limit
+     * nobody honours. Read against the tool results, they applied seven and
+     * three: the twenty-six was twenty-three failed calls -- no-match, read
+     * before edit, wrong insert mode -- around three changes that landed, which
+     * is the limit exactly.
+     *
+     * Returns the text once and nothing after. Every later transaction's rules
+     * arrive the same way, on the message that reopens it.
+     */
+    takeOpeningRules(): string | undefined;
+    /**
+     * A clause for the no-tool-call nudge naming a transaction nothing has
+     * landed in, or undefined when there is nothing to say.
+     *
+     * The runtime's nudge tells a silent turn that it called nothing. That is
+     * the whole message, and with the protocol engaged it omits the state the
+     * model is actually in. Measured on pandorum session 1789230811792_qnyfa:
+     * TX-01 open, three turns of prose describing edits, two nudges, neither
+     * naming the transaction, and the run ended with the file untouched and no
+     * tool ever called. The transaction machinery could not intervene because
+     * every one of its entry points is a tool call.
+     */
+    describeUnstartedWork(): Promise<string | undefined>;
+    /** The boundary. Judges the open transaction and keeps it or puts it back. */
+    onCompletionAttempt(context: {
+        text?: string;
+        forced?: boolean;
+    }): Promise<string | undefined>;
+    /**
+     * The user turned the protocol off. Judge what is open and stand down.
+     *
+     * Whoever calls this owns the timing, and the timing is the hard part: a
+     * discarded transaction puts every file it touched back, and doing that
+     * while a tool call is open would rewrite a file underneath the call that is
+     * writing it. The host calls this where no call is in flight -- idle, or at
+     * the top of an agent-loop iteration -- and nowhere else.
+     *
+     * Returns what to tell the model, already written. After it returns, the
+     * protocol is inert: its tools refuse, and the completion boundary judges
+     * nothing, so the message's claim that the tools have gone is true for the
+     * rest of this session rather than only after the next rebuild.
+     *
+     * Calling it twice is a no-op and returns nothing: the second caller has
+     * nothing to tell the model that the first did not already say.
+     */
+    disengage(): Promise<string | undefined>;
+    /** Whether it has stood down. */
+    readonly disengaged: boolean;
+}
+/**
+ * Arm the protocol for a session, or decline and say why.
+ *
+ * `auto` engages only where a change can actually be judged — an oracle the
+ * user named, or something in the workspace that can be run. Without one the
+ * verdict would come from the model's own account of its work, and the whole
+ * reason the protocol exists is that this account and the program disagree.
+ * `always` engages anyway, and is honest in the prompt about what is judging.
+ */
+export declare function createAtomicProtocolSession(options: AtomicProtocolSessionOptions): Promise<AtomicProtocolSession | undefined>;
+/**
+ * What a model's closing message says about whether its change worked.
+ *
+ * A heuristic, and only reached where there is no oracle. It looks for doubt
+ * rather than for confidence: a model that ends a run is already asserting that
+ * it is done, so the thing worth finding is the sentence where it says it is
+ * not sure, and returning `undefined` means "it did not say otherwise" rather
+ * than "it said yes".
+ */
+export declare function readSelfReport(text: string | undefined): SelfReport | undefined;

package/dist/runtime/atomic/session-revisions.d.ts

@@ -0,0 +1,77 @@
+/**
+ * File history for a whole session, whether or not the change protocol is on.
+ *
+ * The log used to belong to the transaction: `createRevisionLog()` was a field
+ * on `TransactionController`, `withRevisionCapture` had two call sites and both
+ * were anchored to a base `Snapshot`, and `--atomic off` therefore recorded
+ * nothing at all. Two things that do not depend on the protocol depended on it
+ * anyway:
+ *
+ * - the compaction ledger's closing section, `src/parser.ts #1–#7`, which is
+ *   how a summary says "the content is not here, it is at this address". It
+ *   rendered empty in every one of the 36 compactions of the 12-run A/B,
+ *   because that arm ran with the protocol off;
+ * - and recovery, which is the reason the whole thing exists. A session that
+ *   destroys a file wants its earlier content back; whether a transaction was
+ *   open when it happened is not the model's question.
+ *
+ * So the log is the session's, and the transaction is one consumer of it. The
+ * protocol is handed this object instead of making its own, which also keeps
+ * the numbering continuous: a session that engages the protocol part-way
+ * through does not restart `#1` underneath a model that has already been told
+ * where `#4` is.
+ */
+import type { AgentTool, AgentToolDefinition } from "@cerebriline/shared";
+import type { CompactionRevisions } from "../../extensions/context/compaction-revisions";
+import { type RevisionLog } from "./file-revisions";
+export interface SessionRevisions {
+    /** The log itself, to hand to the change protocol so both share one. */
+    readonly log: RevisionLog;
+    /** What compaction reads and writes. */
+    readonly port: CompactionRevisions;
+    /**
+     * Tools that exist because the history does.
+     *
+     * Just `restore_file` today, and it is the reason any of this is worth
+     * having: it was added by the change protocol's `decorateTools` and by
+     * nothing else, so a session with the protocol off could record nothing and
+     * undo nothing. Added by the host only when the protocol is absent — with
+     * it, the protocol adds its own, bound to the transaction.
+     */
+    readonly tools: readonly AgentTool[];
+    /**
+     * Wrap the session's tools so writes are recorded.
+     *
+     * Called by the host **only when the protocol is not installed**: the
+     * protocol's own `decorateTools` already wraps the same list against the
+     * same log, and wrapping twice would record every write as two revisions.
+     */
+    decorate<T extends AgentToolDefinition>(tools: readonly T[]): T[];
+    /**
+     * Reads only: `read_files` learns `revision`, and nothing is recorded.
+     *
+     * For Checkpoints off. The lead's own writes are then not recorded, as the
+     * switch says, but a delegated agent's changes still come back as
+     * revisions in this log -- the only way they reach the lead -- and a lead
+     * with no tool to read or adopt them loses the agent's work.
+     */
+    decorateReads<T extends AgentToolDefinition>(tools: readonly T[]): T[];
+}
+export declare function createSessionRevisions(options: {
+    /** Where relative paths resolve, and the edge of what is tracked. */
+    root: string;
+    /** Supplied by tests; the default reads the real file. */
+    readFile?: (absolutePath: string) => Promise<Buffer | undefined>;
+    /** What the checker last said, appended to a revision's label. */
+    lastCheck?: () => string | undefined;
+    /** Supplied by tests that want to inspect the log they passed in. */
+    log?: RevisionLog;
+    /** Retires what the model had read about a file a restore has moved. */
+    forgetReads?: (absolutePath: string) => void;
+    /** For the host to say, in its own voice, that a file was put back. */
+    onRestored?: (event: {
+        path: string;
+        deleted: boolean;
+    }) => void;
+    onError?: (message: string, error: unknown) => void;
+}): SessionRevisions;

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

@@ -0,0 +1,77 @@
+/**
+ * The undo a transaction is built on.
+ *
+ * The rollback is the whole protocol: if the undo is unreliable, every
+ * transaction after the first measures wreckage rather than a fresh attempt.
+ * Cline's checkpoints cannot serve here — `beginWorktreeRestoreTransaction`
+ * runs `git rev-parse --is-inside-work-tree` and throws on anything that is
+ * not a repository, so a workspace that is a plain directory would have no
+ * undo at all. Worse is the quiet failure: a sibling project's git snapshot
+ * had `git add --sparse` fail on git 2.30, swallowed it, wrote the empty tree,
+ * and reported success while reverting nothing.
+ *
+ * So this is a copy with a checksum manifest and no git in it anywhere. It is
+ * slower than a commit and it cannot lie about what it holds.
+ */
+export interface Snapshot {
+    /** Absolute paths, with the content each held when the transaction opened. */
+    readonly files: ReadonlyMap<string, {
+        hash: string;
+        body: Buffer;
+    }>;
+    /** The root the snapshot covers. */
+    readonly root: string;
+    /** Files that existed but were too large to hold; never rolled back. */
+    readonly skipped: readonly string[];
+}
+export interface SnapshotLimits {
+    /** Most files a snapshot will hold before it gives up on covering the tree. */
+    maxFiles?: number;
+    /** Largest single file held, in bytes. */
+    maxFileBytes?: number;
+    /** Most bytes held in total. */
+    maxTotalBytes?: number;
+}
+/**
+ * Read every file under `root` that a transaction could plausibly change.
+ *
+ * Taken at the open of every transaction rather than once per task: a kept
+ * transaction becomes the base the next one rolls back to, which is what makes
+ * a sequence of them additive rather than a single undo point.
+ */
+export declare function takeSnapshot(root: string, limits?: SnapshotLimits): Promise<Snapshot>;
+export interface RestoreReport {
+    /** Files put back because their contents had changed. */
+    restored: string[];
+    /** Files the transaction created, and which are now gone again. */
+    removed: string[];
+    /** Files the transaction deleted, and which are now back. */
+    recreated: string[];
+    /** Paths the snapshot never held, listed so nobody assumes they reverted. */
+    uncovered: string[];
+}
+/**
+ * Put the tree back exactly as the snapshot found it.
+ *
+ * Deletions are undone as carefully as edits, which is not hypothetical: a
+ * model was measured deleting the file under test twelve times in one
+ * transaction to get a clean slate for a whole-file write, and the last
+ * deletion outlived the transaction.
+ */
+export declare function restoreSnapshot(snapshot: Snapshot, limits?: SnapshotLimits): Promise<RestoreReport>;
+/** A file that differs from the snapshot, with the content it holds now. */
+export interface SnapshotChange {
+    readonly path: string;
+    readonly body: Buffer;
+}
+/**
+ * What the open transaction has changed, as it stands right now.
+ *
+ * Files only, and only files that exist: a deletion is a change, but there is
+ * nothing to read back from one, and every caller of this is asking about the
+ * content. The order is the tree walk's, so the answer is stable between two
+ * calls that see the same disk.
+ */
+export declare function snapshotChanges(snapshot: Snapshot, limits?: SnapshotLimits): Promise<SnapshotChange[]>;
+/** Whether anything under the snapshot's root differs from it now. */
+export declare function snapshotIsClean(snapshot: Snapshot, limits?: SnapshotLimits): Promise<boolean>;

package/dist/runtime/atomic/stalled-checks.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Close a transaction whose check is being re-run over files nobody is changing.
+ *
+ * `run_check` settles nothing, by design: that is what makes it safe to run
+ * after every edit, and the protocol asks the model to do exactly that. The
+ * cost is that a model which never yields its turn never reaches
+ * `onCompletionAttempt`, which is the only place `settle` is called from -- so
+ * it never settles at all. That is the timeout signature: the three JackOD4-AC
+ * 9B timeouts closed zero transactions between them, over 308-428 iterations
+ * each.
+ *
+ * The trigger is deliberately *not* "three failed checks". Under the
+ * one-edit-one-check rule a healthy transaction fails its check repeatedly on
+ * the way to passing -- the check is the task's own oracle, so it keeps failing
+ * until the last fix lands, and the model is told to run it on the unmodified
+ * files first to see the failure in the check's own words. Three failures is
+ * the opening of a transaction that is working, and counting those would
+ * guillotine one that was an edit away from passing.
+ *
+ * What separates the two is whether anything changed between one check and the
+ * next. Longest run of checks with no edit in between, over the JackOD4-AC arm:
+ *
+ *     0207  FIXED    481s   1 check    streak 1
+ *     0208  FIXED   2649s  41 checks   streak 6
+ *     0209  broken   862s  21 checks   streak 6
+ *     0213  broken  2688s  49 checks   streak 4
+ *     0214  broken   615s  22 checks   streak 10
+ *     0215  broken  5014s  22 checks   streak 4
+ *
+ * The one run that fixed the task quickly never re-ran the check over untouched
+ * files at all. Every other run did, four to ten times over. Three sits above
+ * the working run and below all the rest, and it is defensible without the
+ * measurement too: a check re-run over bytes that have not moved cannot return
+ * anything the run before it did not.
+ */
+import type { AgentToolDefinition } from "@cerebriline/shared";
+/** Checks over untouched files before the model is told the check has stopped moving. */
+export declare const DEFAULT_MAX_CHECKS_WITHOUT_EDIT = 3;
+/**
+ * Checks over untouched files before the transaction is closed for the model.
+ *
+ * Two more after the nudge, and the gap is the point. Settling is a rollback --
+ * every change in the transaction goes back -- which is the most expensive
+ * possible answer to "that check told you nothing new", and the measured
+ * evidence says a sentence is usually enough. On the pandorum run of
+ * 2026-09-13, eleven of eighteen check runs returned the previous answer byte
+ * for byte; what ended the loop was the non-convergence guard quoting the
+ * model's own "I'm stuck in an infinite loop of edits that keep regressing"
+ * back at it, after which it converged in three minutes and one edit. Nothing
+ * was rolled back to achieve that.
+ *
+ * So the guard speaks first and cuts second. A model that ignores the sentence
+ * still reaches the same settlement it did before, two checks later.
+ */
+export declare const DEFAULT_MAX_CHECKS_BEFORE_SETTLING = 5;
+/** What the counter needs to know, and nothing more. */
+export interface StalledCheckSource {
+    /** Which transaction is open, so the count can reset when it changes. */
+    readonly transaction: number;
+    /** How many checks over untouched files earn the nudge. */
+    readonly max?: number;
+    /** How many end the transaction. Defaults to two more than the nudge. */
+    readonly settleAt?: number;
+}
+/**
+ * What a check over untouched files has earned.
+ *
+ * `nudge` is said once per transaction and judges nothing; `settle` closes the
+ * transaction the way this guard always did.
+ */
+export type StalledCheckVerdict = "ok" | "nudge" | "settle";
+export interface StalledChecks {
+    /** Record a check that has just run, and say what it has earned. */
+    checked(passed: boolean): StalledCheckVerdict;
+    /** Record a change: whatever the next check says, it is judging new bytes. */
+    changed(): void;
+    /** The current run of checks over untouched files. */
+    readonly streak: number;
+}
+export declare function createStalledChecks(source: StalledCheckSource): StalledChecks;
+/**
+ * Wrap the changing tools so the counter hears about them.
+ *
+ * Wrap *inside* `withCheckFirstEdits`, never outside: an edit that gate refuses
+ * never reaches the file, and letting a refused edit clear the count would hand
+ * the model a way to hold a stalled transaction open with edits that do not
+ * land.
+ *
+ * The signal is the call, not the write. A tool that reports a refusal of its
+ * own -- a range that matched nothing, one edit of a batch held back -- still
+ * clears the count, so the guard needs one more check than it strictly should
+ * before it fires. That is the right way round: a check re-run after a change
+ * that did land is the case this must never cut short.
+ */
+export declare function withChangeSignal<T extends AgentToolDefinition>(tools: readonly T[], onChange: () => void): T[];
+/**
+ * What the model is told the first time the check stops moving.
+ *
+ * It judges nothing and puts nothing back -- saying otherwise would have the
+ * model report a transaction that is still open. What it adds is the thing the
+ * re-run cannot give it: the check names where the parser gave up, and
+ * `check_file` names the line that is actually wrong.
+ */
+export declare function describeStalledCheckNudge(runs: number, label: string): string;
+/** What the model is told when the check is closed out from under it. */
+export declare function describeStalledChecks(runs: number, label: string): string;

package/dist/runtime/atomic/submit-transaction-tool.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Submit the open transaction, deliberately, when the model judges it done.
+ *
+ * Why it exists. Until now there was no way for a model to submit anything.
+ * `onCompletionAttempt` — the only path that judges a transaction — is reached
+ * from exactly one place in the runtime: a turn that called no tools. So the
+ * submission was never a decision. The model would think a turn through, call
+ * nothing, and be told "TX-01 was submitted", which is a report of something it
+ * had not done.
+ *
+ * And it is told the opposite everywhere else. The no-tool-call nudge exists
+ * precisely to stop a turn ending without a call; the protocol's only exit was
+ * to do that on purpose. Measured on pandorum 2026-09-12 under 4.100.103: ten
+ * turns, no tool calls, six boundary messages, and the model's own reasoning
+ * reading "I keep failing to emit actual tool calls", "I have called none of
+ * those yet", "this loop above shows exactly why things keep ending". It was
+ * not confused about the task. It was reacting to being told it had submitted.
+ *
+ * With this, submission is a tool call like everything else: the model decides
+ * when it is confident, the check runs, and the verdict comes back as the
+ * result. The completion boundary stays, demoted to what it should always have
+ * been — a guard for a run that has stopped calling anything at all.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+export declare const SUBMIT_TRANSACTION_TOOL_NAME = "submit_transaction";
+export declare const SUBMIT_TRANSACTION_TOOL_DESCRIPTION = "Submit this transaction for judging, when you have made the changes you planned and you are confident in them.\n\nThis is how a transaction ends. Nothing else submits it: finishing your turn without calling anything does not, and describing the work in your reply does not.\n\nWhat happens when you call it: the check runs, and the answer comes straight back to you. If it passes the transaction is kept and the task is done. If it does not, every change in this transaction is rolled back for you, and you are given the next transaction with a record of what this one tried.\n\nSo call it when you believe the work is finished \u2014 not to ask whether it is. Use `run_check` for that, as often as you like; it settles nothing. Submitting is the commitment.";
+export declare const SUBMIT_TRANSACTION_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly account: {
+            readonly type: "string";
+            readonly description: "What you changed and why you believe it works. One or two sentences. This is recorded with the transaction and, where nothing here can run a check, it is what the verdict is based on.";
+        };
+    };
+    readonly required: readonly [];
+};
+export interface SubmitTransactionToolOptions {
+    /**
+     * Settles the open transaction and returns what the model should be told:
+     * the verdict, and the next transaction's rules where there is one.
+     *
+     * Owned by the session rather than passed a controller, because settling
+     * touches per-session bookkeeping — whether the run has finished, how many
+     * empty submissions this transaction has absorbed — that does not live on
+     * the controller and would be bypassed by settling directly.
+     */
+    submit: (account: string | undefined) => Promise<string>;
+    onError?: (message: string, error: unknown) => void;
+}
+export declare function createSubmitTransactionTool(options: SubmitTransactionToolOptions): AgentTool;

package/dist/runtime/atomic/tool-activity.d.ts

@@ -0,0 +1,15 @@
+import type { AgentToolDefinition } from "@cerebriline/shared";
+/**
+ * Signal every tool call, whatever the tool and whatever it returns.
+ *
+ * `withChangeSignal` answers "did a file change in this transaction". This
+ * answers the question before it — "was this transaction ever attempted" — and
+ * the two are not the same. A transaction the model worked in for twenty turns
+ * and left with no net change was attempted and failed. A transaction it spent
+ * thinking, calling nothing, was not attempted at all, and the difference
+ * decides whether it is fair to spend it.
+ *
+ * Wrapped outermost, so it counts calls the check-first gate refuses. A refused
+ * edit is still the model reaching for a tool: it began.
+ */
+export declare function withAnyToolSignal<T extends AgentToolDefinition>(tools: readonly T[], onCall: (name: string) => void): T[];