@cerebriline/core 4.100.240

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

@@ -0,0 +1,178 @@
+/**
+ * The thing that decides whether a transaction is kept.
+ *
+ * The harness this protocol comes from runs its oracle from the shell and
+ * reads only the exit code, deliberately: a model asked whether its own edit
+ * worked answers about the edit it meant to make. Measured across the atomic
+ * campaign, transactions that reported success and failed the oracle were
+ * routine — the model had fixed the error it was looking at and not the one
+ * the program still had.
+ *
+ * So the verdict is a command's exit status wherever a command can be found,
+ * and the model's own word only where none can.
+ */
+interface OracleCommon {
+    /** Shown to the model, and to the user, as what will judge the change. */
+    label: string;
+    /** Where it runs. */
+    cwd: string;
+    /** Why this one was chosen, for the log. */
+    reason: string;
+}
+export interface CommandOracle extends OracleCommon {
+    kind?: "command";
+    /** The executable and its arguments. Never a shell string. */
+    command: string;
+    args: string[];
+    /**
+     * A pattern the output must match, on top of exiting zero.
+     *
+     * For the large class of checks that report their verdict and exit zero
+     * anyway. The harness's own oracle is one: `run_game.js` prints
+     * `{"ok":false,"error":"…"}` and exits 0 whether the game runs or not, so a
+     * protocol reading only the exit status would keep every transaction it was
+     * ever pointed at. Read as a regular expression against stdout and stderr
+     * together, in this process — never through a shell.
+     */
+    expect?: string;
+    /**
+     * Whether the output must match `expect` (the default) or must not.
+     *
+     * `not_match` is for the check that names its failure rather than its
+     * success -- a linter's `ERROR`, a test runner's `FAIL` -- where "it exited
+     * zero and did not say that" is the pass. The exit status still has to be
+     * zero either way.
+     */
+    must?: "match" | "not_match";
+}
+/**
+ * How a command is started somewhere other than straight on the host: the
+ * shape of `ShellExecutorOptions.wrapSpawn`, which is how a delegated agent's
+ * shell is rooted at the sandbox launcher.
+ */
+export type OracleSpawnWrapper = (spec: {
+    executable: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+}) => {
+    executable: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+};
+/**
+ * A check the harness runs itself, with no external program involved.
+ *
+ * The reason this kind exists: every other oracle is a command, and a command
+ * only judges anything where one is installed. The workspaces this protocol
+ * falls back to self-declaration on are exactly the ones with no test runner
+ * and no build — a single page, a script, a game — and telling the model to
+ * name a command there produces one that may not exist on the machine. This
+ * one always does. See `page-check.ts`.
+ */
+export interface PageOracle extends OracleCommon {
+    kind: "page";
+    /** The file to load, absolute or relative to `cwd`. */
+    path: string;
+    /** How many animation frames to pump before calling it working. */
+    frames?: number;
+}
+export type Oracle = CommandOracle | PageOracle;
+/** Whether this oracle is one the harness runs itself. */
+export declare function isPageOracle(oracle: Oracle): oracle is PageOracle;
+export interface OracleVerdict {
+    passed: boolean;
+    /** Exit status, or `null` when the oracle could not be run at all. */
+    exitCode: number | null;
+    /** Combined output, truncated. The record a failed transaction carries. */
+    output: string;
+    /** Set when the oracle exceeded its budget: an unfinished run is not a pass. */
+    timedOut: boolean;
+    /**
+     * Set when the command succeeded but its output did not say the change did.
+     * A different failure from a non-zero exit and reported as one, because "it
+     * ran and reported a problem" reads nothing like "it crashed".
+     */
+    unmatched?: boolean;
+    /**
+     * What went wrong, where the check can say it better than an exit code can.
+     *
+     * A check the harness runs itself has no exit status worth reporting, and
+     * "the check failed (exit 1)" would be the least informative true thing
+     * available about a page that threw a ReferenceError on frame 2.
+     */
+    summary?: string;
+}
+/** Longest an oracle may run before the transaction is judged on nothing. */
+export declare const DEFAULT_ORACLE_TIMEOUT_MS = 120000;
+/**
+ * Directories a workspace scan must not descend into.
+ *
+ * Not a nicety: a snapshot or a scan that walks `node_modules` on a real
+ * project reads hundreds of thousands of files and the feature becomes slower
+ * than the change it is protecting.
+ */
+export declare const SCAN_IGNORED_DIRECTORIES: ReadonlySet<string>;
+/**
+ * Where an oracle may come from, strongest claim first.
+ *
+ * `manual` is the one the user writes for the task in front of them, and it is
+ * the answer to a failure mode the rest of the ladder cannot reach: an oracle
+ * chosen by detection judges whether the workspace still holds together, not
+ * whether the thing the user asked for now works. A model can leave a
+ * typecheck green and the feature broken, and detection would keep that
+ * transaction.
+ */
+export interface OracleSources {
+    /** Written by the user for this task. Beats everything below it. */
+    manual?: string;
+    /** A default the user set once, in settings, for every task. */
+    explicit?: string;
+    /**
+     * What the output must say for a user-named check to count as passed.
+     *
+     * Applies to a named command only. A check found by looking at the
+     * workspace is a test runner or a compiler, and those already answer with
+     * their exit status; a command the user wrote may be neither.
+     */
+    expect?: string;
+}
+/**
+ * Flags an `expect` pattern is compiled with: `s`, so `.` crosses line ends.
+ *
+ * A check's output is several lines more often than one, and a pattern written
+ * as `"ok":true.*"passed":23` means "this, then later that" to whoever wrote
+ * it. Without the flag it only held while the program printed one line (the
+ * wlafh lead noticed it had been lucky).
+ */
+export declare const ORACLE_EXPECT_FLAGS = "s";
+export declare function shellOracle(line: string, cwd: string, reason: string, expect?: string): CommandOracle;
+/**
+ * Find something in this workspace that can say whether a change is good.
+ *
+ * Returns `undefined` when nothing does — a documentation edit, a config file,
+ * a repository with no runnable anything. That is not a failure: it is the
+ * case where the verdict falls to the model, and the caller says so out loud
+ * rather than pretending a check happened.
+ */
+export declare function discoverOracle(workspaceRoot: string, options?: OracleSources): Promise<Oracle | undefined>;
+/**
+ * Run the oracle and read its exit status.
+ *
+ * A non-zero exit, a signal, a timeout and a command that could not be started
+ * are all failures. The last of those is the one worth naming: an oracle that
+ * cannot run has judged nothing, and treating "not found" as a pass would keep
+ * every transaction it was pointed at.
+ */
+export declare function runOracle(oracle: Oracle, options?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    /**
+     * Start the command through this instead of directly: a delegated
+     * agent's check runs under the same launcher as its shell, so it sees
+     * the agent's own files. Absent is the host, as before.
+     */
+    wrapSpawn?: OracleSpawnWrapper;
+}): Promise<OracleVerdict>;
+export {};

package/dist/runtime/atomic/page-check.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A check the harness provides, for the workspaces that have none.
+ *
+ * `discoverOracle` finds a check by looking for a test runner, a compiler or a
+ * build. A single-file page has none of those, and that is exactly the shape
+ * of task this protocol keeps failing on: the model edits a game, cannot run
+ * it, and the verdict falls back to its own word.
+ *
+ * Asking the model to name a shell command instead does not fix it — the
+ * command it names may not be installed, and a check that cannot run judges
+ * nothing. So this one is ours: no external program, no browser, nothing to
+ * install. It builds a stub DOM, executes every `<script>` in the file and
+ * pumps a bounded number of animation frames. A page that throws while
+ * loading, throws in a frame, or never schedules a frame at all did not work.
+ *
+ * Ported from the harness oracle the atomic campaign was measured with, where
+ * it decided every verdict across ~90 runs.
+ */
+/** Frames pumped by default: enough for a game to have run its loop. */
+export declare const DEFAULT_PAGE_FRAMES = 30;
+export interface PageCheckResult {
+    ok: boolean;
+    /** Why it failed, in the form the transaction's message quotes. */
+    error?: string;
+    framesRun: number;
+    /** Whether the page had to be told to start rather than starting itself. */
+    started: boolean;
+}
+/**
+ * Load a page the way a browser would, and say whether it ran.
+ *
+ * `source` is passed in rather than read here so the caller decides which
+ * copy of the file is being judged — the working tree, or a snapshot restored
+ * behind it, which is what validating a proposed check against the unmodified
+ * files needs.
+ */
+export declare function checkPage(filePath: string, source: string, options?: {
+    frames?: number;
+}): PageCheckResult;

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

@@ -0,0 +1,40 @@
+/**
+ * Notice the plan the moment it is written, wherever it was written.
+ *
+ * The protocol asks for the plan in the reply. A 9B put it in its reasoning
+ * four times out of four (session 1789032320523_q29ta, assistant messages 7,
+ * 61, 77 and 79 — one of them a WHERE/WHAT/WHY table — every one of them with
+ * a reply of zero characters). The instruction was followed; the clause about
+ * where to put it was not, and nothing downstream reads reasoning, so the plan
+ * reached neither the user nor the transaction record.
+ *
+ * Rather than ask again in stronger words, read it. The assistant message for
+ * the current turn is already in `context.snapshot.messages` by the time its
+ * tool calls execute -- the runtime pushes it before running them -- so any
+ * tool call is a place to look, and the first one of the turn is the earliest
+ * moment the plan can be surfaced.
+ *
+ * Every tool is wrapped, not only the editing ones: a turn that states a plan
+ * and then reads a file before editing is stating a plan just as much as one
+ * that edits immediately, and the gate that asked for it fires on edits alone.
+ *
+ * Reported once per transaction. A plan is what opens a transaction; repeating
+ * it on every later tool call would turn one message into forty.
+ */
+import type { AgentToolDefinition } from "@cerebriline/shared";
+/** Where the plan was found, which decides whether the user needs telling. */
+export type PlanSource = "reply" | "reasoning";
+export interface PlanCaptureSource {
+    /** Which transaction is open, so a new one can be given its own plan. */
+    readonly transaction: number;
+    /** Called at most once per transaction, with the plan as the model wrote it. */
+    readonly onPlan: (plan: string, from: PlanSource) => void;
+}
+/**
+ * Wrap every tool so the first plan of each transaction is reported once.
+ *
+ * The reply is preferred over the reasoning, and the source is passed on:
+ * a plan the model already put in its reply is on screen, and repeating it
+ * back to the user would be noise.
+ */
+export declare function withPlanCapture<T extends AgentToolDefinition>(tools: readonly T[], source: PlanCaptureSource): T[];

package/dist/runtime/atomic/plan-text.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Find the plan in what a model wrote, wherever it wrote it.
+ *
+ * The protocol asks for a plan before the first edit -- a numbered list, each
+ * entry naming WHERE, WHAT and WHY -- and says to put it in the reply "so it
+ * is on the record and the user can see it, not only in your reasoning". A 9B
+ * measured on a manic_miner session complied with the instruction and ignored
+ * that last clause, four times out of four: assistant messages 7, 61, 77 and
+ * 79 each carried a full `TX-01 Plan` with WHERE/WHAT/WHY -- one of them as a
+ * table -- and every one of them had a reply of exactly zero characters.
+ *
+ * That costs twice. The user never sees the plan, and `report.plan` is read
+ * off the reply, so the transaction record carries none either and the next
+ * transaction is told nothing about what the last one intended.
+ *
+ * Asking harder is not the fix at this size. Reading the reasoning is: the
+ * plan is there, in full, and it only has to be found.
+ *
+ * The danger in doing that is a false positive -- reasoning is long and
+ * discursive, and pasting the wrong part of it into the chat and into the
+ * transaction record would be worse than showing nothing. So recognition is
+ * deliberately strict: a plan must name all three of WHERE, WHAT and WHY, and
+ * must have list or table structure. Prose that merely discusses a plan does
+ * not qualify.
+ */
+/**
+ * The plan stated in `text`, or nothing.
+ *
+ * Returns the block verbatim, trimmed. Verbatim matters: this is shown to the
+ * user as the model's own words and stored as the transaction's plan, and a
+ * summary of a plan is not a plan.
+ */
+export declare function readPlan(text: string | undefined): string | undefined;

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

@@ -0,0 +1,159 @@
+/**
+ * Hold the plan, so that what worked is not lost the next time the model looks.
+ *
+ * The protocol asks for a numbered list of changes before the first edit, and
+ * `plan-text.ts` next door finds that list wherever the model wrote it. Both
+ * treat the plan as *text stated once*. Measured, that is not how a small model
+ * uses it.
+ *
+ * Session 1789139763721_ive21 on pandorum, 2026-09-11, a 9B on manic_miner:
+ * eleven separate blocks headed `## TX-01 Plan` or `## TX-02 Plan`, each one
+ * written from scratch against whatever the last check had just reported. Three
+ * things went wrong, and they compound:
+ *
+ *   * **The header disagreed with the list.** Six of the eleven announced "2
+ *     changes" or "4 changes" and then listed one. Nothing counted them.
+ *
+ *   * **Nothing was carried forward.** Message 37 says, in prose, "I've already
+ *     made two edits that landed" — and then plans four more as if starting
+ *     from the original file. The two that landed are named nowhere.
+ *
+ *   * **The same line was re-planned five times.** Line 90 at messages 7, 9 and
+ *     11, then again at 144 after the transaction boundary. It was re-deriving
+ *     one fix from one error, repeatedly, because the fix existed only as a
+ *     side effect on disk and never as something it could read back.
+ *
+ * When TX-01 was discarded, the disk side effects went with it and there was
+ * nothing left at all. The user's words for it: "the banked wins are lost".
+ *
+ * So this is a place to put them. Three things follow from the failure above
+ * and are the whole design:
+ *
+ *   * **The tool numbers the items**, so a count can never disagree with a
+ *     list — there is no count to write.
+ *   * **Every call returns the whole plan**, so the current state is in front
+ *     of the model at the moment it is deciding what to do next, rather than
+ *     forty messages up.
+ *   * **A discard does not erase the record.** The items survive with their
+ *     history: an item that landed in TX-01 comes back marked `pending` (the
+ *     file really was rolled back) but reads `landed in TX-01, rolled back`,
+ *     which is the sentence the model needed and never had.
+ *
+ * There is a second failure the same session showed, and it is why this tool
+ * writes the retrospective rather than only holding the plan.
+ *
+ * From TX-02 onward the protocol asks for four lines before the plan — WORKED,
+ * DID NOT, RE-USE, DIFFERENT. The model obliged, and then **stopped writing
+ * plans altogether**: every later block is headed "TX-02 Retrospective & Plan"
+ * and the plan half has collapsed into the DIFFERENT line as prose ("Make ONE
+ * precise editor call replacing line 89..."). The retrospective displaced the
+ * thing it was meant to precede.
+ *
+ * It is also the half the model is worst at. WORKED and DID NOT are questions
+ * about what happened, asked of a model whose recollection of what happened is
+ * exactly what failed — the same session reported "I've exhausted my 71
+ * restore_file attempts" when nothing had been exhausted. But this tool knows
+ * what happened: it recorded it. So when a transaction rolls over it writes
+ * WORKED, DID NOT and RE-USE itself, from the record, and asks the model only
+ * for DIFFERENT — which is the new plan, and is the one part no record can
+ * supply.
+ *
+ * It stores nothing about the files and changes nothing on disk. A plan is a
+ * statement of intent, and this keeps the statement.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+export declare const PLAN_TOOL_NAME = "plan";
+/** Where an item stands in the transaction that is open now. */
+export type PlanItemStatus = "pending" | "done" | "failed";
+/** What happened to an item in a transaction that has since closed. */
+interface PlanItemAttempt {
+    readonly transaction: number;
+    readonly status: Exclude<PlanItemStatus, "pending">;
+    readonly note?: string;
+}
+export interface PlanItem {
+    /** 1-based, assigned here, and stable for the life of the run. */
+    readonly id: number;
+    readonly where: string;
+    readonly what: string;
+    readonly why: string;
+    status: PlanItemStatus;
+    note?: string;
+    /** Every closed transaction this item was touched in, oldest first. */
+    readonly history: PlanItemAttempt[];
+}
+/** Declarations allowed per transaction, so re-planning is bounded. */
+export declare const MAX_DECLARATIONS_PER_TRANSACTION = 3;
+export declare const PLAN_TOOL_DESCRIPTION = "Keep the plan for this task: what you intend to change, and which of those changes have landed.\n\nCall it three ways.\n\nTo state the plan, send `changes`: a list, each entry naming WHERE (the function, or the exact text you will match on), WHAT (the single concrete edit) and WHY (the symptom it removes). Numbering is done for you \u2014 send the list, not a count.\n\nTo record that an item landed, send `done` with its number, and optionally `note`. Do this the moment the edit applies, not at the end. An item you do not mark is an item you will plan again.\n\nTo record that an item did not work, send `failed` with its number and a `note` saying what happened.\n\nEvery call returns the whole plan with its current state, so you never have to remember it or scroll back for it. Read what comes back before deciding what to do next.\n\nThe plan survives a discarded transaction. An item that landed and was then rolled back comes back as work still to do, but it is still on the record as something that once worked \u2014 which is the fastest route back to a working file.";
+export declare const PLAN_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly changes: {
+            readonly type: "array";
+            readonly description: "The plan, as a list. Each entry names where, what and why. Replaces any plan already stated.";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly where: {
+                        readonly type: "string";
+                        readonly description: "The function, or the exact text you will match on.";
+                    };
+                    readonly what: {
+                        readonly type: "string";
+                        readonly description: "The single concrete edit you will make there.";
+                    };
+                    readonly why: {
+                        readonly type: "string";
+                        readonly description: "The specific symptom it removes.";
+                    };
+                };
+                readonly required: readonly ["where", "what", "why"];
+            };
+        };
+        readonly done: {
+            readonly type: "number";
+            readonly description: "The number of an item whose edit has just landed.";
+        };
+        readonly failed: {
+            readonly type: "number";
+            readonly description: "The number of an item that did not work.";
+        };
+        readonly note: {
+            readonly type: "string";
+            readonly description: "What happened, for the item named by `done` or `failed`.";
+        };
+    };
+    readonly required: readonly [];
+};
+/**
+ * The part of the controller this tool reads.
+ *
+ * Only the transaction number. The change budget arrives as an option instead
+ * of being read off the controller, because the controller does not publish it
+ * and widening its surface for one number is the wrong trade.
+ */
+export interface PlanTransactionSource {
+    /** Which transaction is open. A change here means the last one closed. */
+    readonly transaction: number;
+}
+export interface PlanToolOptions {
+    controller: PlanTransactionSource;
+    /** The protocol's change budget, which bounds the list. */
+    maxChanges: number;
+    /** Called when the plan changes, so a host can show it. */
+    onPlan?: (items: readonly PlanItem[]) => void;
+}
+/**
+ * What the closed transaction actually did, in the protocol's own four heads.
+ *
+ * Written from the record rather than from recollection. WORKED is what landed
+ * before the rollback, DID NOT is what was tried and refused, RE-USE is both of
+ * those together — they are the findings that survive a rollback even though
+ * the edits do not. DIFFERENT is left blank on purpose: it is the new plan, and
+ * asking for it is the point.
+ */
+export declare function renderRetrospective(items: readonly PlanItem[], closed: number): string;
+/** The whole plan as the model reads it back. */
+export declare function renderPlan(items: readonly PlanItem[], transaction: number): string;
+export declare function createPlanTool(options: PlanToolOptions): AgentTool;
+export {};

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

@@ -0,0 +1,112 @@
+/**
+ * A check the model proposes and the user approves.
+ *
+ * `discoverOracle` answers "what can this workspace run", and where the answer
+ * is nothing the protocol falls back to the model's own account of its work —
+ * which is the weakest thing in this area and the source of every wrong
+ * verdict measured so far. The model, though, has just read the code and knows
+ * what would demonstrate the fix. What it cannot do is decide that its own
+ * exam is fair, so the user approves it.
+ *
+ * Two properties hold this together, and neither is optional:
+ *
+ * 1. *The user approves the exact text.* A proposed command is arbitrary shell
+ *    that the host will then run repeatedly and trust as a judge, so approval
+ *    is a security boundary rather than a convenience. It never falls under
+ *    auto-approve, and a proposal that differs by one character is a new one.
+ * 2. *It is frozen once approved.* A model that may re-propose after a failed
+ *    transaction will weaken the check until one passes, which is an elaborate
+ *    way of producing `self-declared`. Changing it costs a user interaction.
+ */
+import type { Oracle, OracleVerdict } from "./oracle";
+/** What the model asks for, before anything has agreed to it. */
+export interface CheckProposal {
+    /**
+     * `page` is the harness's own check and needs nothing installed; `command`
+     * is a line for the shell, which may not exist on this machine and is why
+     * a proposal is validated before it is trusted.
+     */
+    kind: "page" | "command";
+    /** For `page`: the file to load, relative to the workspace root. */
+    path?: string;
+    /** For `command`: the line to run, exactly as the user would type it. */
+    command?: string;
+    /** For `command`: what the output must say, on top of exiting cleanly. */
+    expect?: string;
+    /** Why this check answers the task. Shown to the user, who decides. */
+    reason: string;
+}
+/** The tool the model names a check with. Here so the prompt can say it without importing the tool. */
+export declare const PROPOSE_CHECK_TOOL_NAME = "propose_check";
+/** How many rounds of proposing the model gets before the protocol moves on. */
+export declare const MAX_CHECK_PROPOSALS = 2;
+/**
+ * Discarded attempts before a check that has never passed may be replaced.
+ *
+ * The freeze is what stops a model weakening its check until one passes, so it
+ * is not lifted lightly — but a check that cannot pass at all freezes the run
+ * into failure, and measured over ten runs that cost two of them outright.
+ * Both spent every transaction they had. See `TransactionController`, which
+ * owns the condition; this is only the number of attempts of evidence needed
+ * before the check itself is allowed to be the suspect.
+ *
+ * Zero turns it off, which is the behaviour that preceded it.
+ */
+export declare const DEFAULT_CHECK_RECONSIDERED_AFTER = 2;
+export type CheckApproval = {
+    approved: true;
+}
+/** Declined, with what the user wants instead — the model's next round. */
+ | {
+    approved: false;
+    feedback?: string;
+};
+/** Asks the user. Absent on a host with nobody to ask, which is not a failure. */
+export type CheckApprover = (proposal: CheckProposal, described: string) => Promise<CheckApproval>;
+/** A proposal that cannot be used, and the sentence the model is told why. */
+export interface ProposalRejection {
+    problem: string;
+}
+/**
+ * Read a proposal off a tool call, or say what is wrong with it.
+ *
+ * Through a typed tool and validated here, never by reading the model's prose.
+ * `readSelfReport` is already a phrase-matching heuristic and it is the
+ * weakest thing in this protocol; a second one deciding what the check is
+ * would compound it.
+ */
+export declare function readCheckProposal(input: unknown, workspaceRoot: string): CheckProposal | ProposalRejection;
+/**
+ * The proposal as the user reads it before approving.
+ *
+ * Who runs it comes first, and this is not a style point. Measured on the
+ * first live use: the model proposed the page check — headless, in this
+ * process, no browser window and no human — and the dialog opened "Load and
+ * run `manic_miner.html`", which reads as an instruction to the person
+ * reading it. The model's own reason said "loading the page in a browser will
+ * confirm…", and the one line saying it runs inside Cline came last. The user
+ * declined it as manual work they would have to repeat every attempt. It was
+ * never manual, and this now says so before anything else.
+ *
+ * The exact text that will run still goes on its own line, because for a
+ * command that is the thing being approved.
+ */
+export declare function describeCheckProposal(proposal: CheckProposal): string;
+/** The approved proposal as the thing that judges transactions. */
+export declare function proposalToOracle(proposal: CheckProposal, workspaceRoot: string): Oracle;
+/** Whether two proposals are the same one, for "approved already" purposes. */
+export declare function sameProposal(a: CheckProposal, b: CheckProposal): boolean;
+/**
+ * Whether the output is an interpreter rejecting the check, not a verdict.
+ *
+ * Exported for the tests that pin each signature to the run that produced it.
+ */
+export declare function readBrokenCheck(verdict: OracleVerdict): {
+    what: string;
+} | undefined;
+export declare function judgeCandidateCheck(verdict: OracleVerdict, proposal?: CheckProposal): {
+    usable: true;
+} | {
+    usable: false;
+    problem: string;
+};

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

@@ -0,0 +1,76 @@
+/**
+ * The tool a model proposes its own check with.
+ *
+ * Offered only where there is nothing to run: `discoverOracle` found no test
+ * runner, no build and no compiler, so without this the transaction's verdict
+ * is the model's own account of its work. Measured, that account is wrong
+ * often enough to be the reason this protocol exists — and the model is
+ * nonetheless the only party that has read the code and knows what would
+ * demonstrate the fix. So it proposes, and the user decides.
+ *
+ * The check it adopts is reachable from `run_check` for the rest of the run.
+ * That is not decoration: this tool used to promise a feedback loop that did
+ * not exist -- the check ran once, at the completion attempt -- and a model
+ * that believes it is being checked stops checking itself.
+ *
+ * A tool rather than a sentence in the closing message. `readSelfReport` is
+ * already a phrase-matching heuristic and it is the weakest thing here; a
+ * second one deciding what the check *is* would compound it.
+ */
+import { type AgentTool } from "@cerebriline/shared";
+import type { Oracle, OracleVerdict } from "./oracle";
+import { type CheckApprover, type CheckProposal, PROPOSE_CHECK_TOOL_NAME } from "./proposal";
+export { PROPOSE_CHECK_TOOL_NAME };
+export declare const PROPOSE_CHECK_TOOL_DESCRIPTION = "Propose the check that will decide whether your change worked, and ask the user to approve it once.\n\nNothing in this workspace can be run to judge a change, so without a check your own account of the work is the verdict \u2014 and that is the weakest evidence there is. Propose one instead. You have read the code; name the thing that would show the fix.\n\n**It must run without a person.** Once it is approved you run it yourself with `run_check`, as often as you like, and it is also run once when you finish. Never propose something a human performs \u2014 \"open it in a browser and see\", \"confirm the layout looks right\", \"check that it feels responsive\". Propose the mechanical thing that would catch the bug: running the file, a parse, a test, a linter, a script that exits non-zero when it is still broken.\n\nTwo kinds:\n- `kind: \"page\"` \u2014 Cline loads `path` in this process, runs its scripts and pumps animation frames. No browser window opens and nobody looks at it. It fails if the file does not parse, throws while loading, throws in a frame, or never draws. Nothing has to be installed, so prefer this for a page, a game or a script.\n- `kind: \"command\"` \u2014 a line for the shell, run unattended, with the workspace root as its working directory: write paths relative to it and do not `cd` anywhere first. Only worth proposing when you know it exists on this machine; a check that cannot run judges nothing. Add `expect` when the command reports its verdict in its output and exits cleanly either way \u2014 without one its exit code is the whole verdict, and a command that exits zero on a broken tree would keep every change you make.\n\nGive a `reason` in one sentence: what passing this check proves about the task. Write it about the code, not about how a person would test it \u2014 \"the level data is built before the first frame draws\", not \"loading it in a browser will confirm it works\". The user reads that sentence to decide.\n\nPropose once, early \u2014 as soon as you know what you are fixing. What is approved judges every attempt for the rest of the run and cannot be changed, so do not propose something you can already make pass.\n\nThen use it. `run_check` runs it against the files as they stand, settles nothing and rolls nothing back. Run it before you edit, to see the failure in the check's own words, and after each change. A check you only meet when you finish is a check that can only ever throw the transaction away.\n\nOnce the user approves it, it is tried against the files as they were before your changes, and it has to FAIL there. A check that already passes on the unmodified files cannot tell a fix from no fix, and is refused.";
+export declare const PROPOSE_CHECK_TOOL_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly kind: {
+            readonly type: "string";
+            readonly enum: readonly ["page", "command"];
+            readonly description: "`page` for a file Cline loads and runs itself; `command` for a shell line.";
+        };
+        readonly path: {
+            readonly type: "string";
+            readonly description: "For `page`: the file to load, relative to the workspace root.";
+        };
+        readonly command: {
+            readonly type: "string";
+            readonly description: "For `command`: the exact line to run.";
+        };
+        readonly expect: {
+            readonly type: "string";
+            readonly description: "For `command`: a regular expression the output must match, on top of exiting cleanly. Matched inside Cline; never a command.";
+        };
+        readonly reason: {
+            readonly type: "string";
+            readonly description: "One sentence: what passing this check proves.";
+        };
+    };
+    readonly required: readonly ["kind", "reason"];
+};
+/** The part of the controller this tool drives. */
+export interface CheckAdopter {
+    readonly canAdoptOracle: boolean;
+    /**
+     * Whether the check in force is up for replacement, this transaction.
+     *
+     * Absent on a controller that does not offer it, which reads as never.
+     */
+    readonly checkIsUnderReconsideration?: boolean;
+    adoptOracle(oracle: Oracle): void;
+    /** Runs a candidate against the files this transaction opened on. */
+    judgeAgainstBase(oracle: Oracle): Promise<OracleVerdict>;
+}
+export interface ProposeCheckToolOptions {
+    workspaceRoot: string;
+    controller: CheckAdopter;
+    /** Rounds put to the user before the run gives up on having a check. */
+    maxProposals?: number;
+    /** Asks the user. The security boundary, and never auto-approved. */
+    approve: CheckApprover;
+    /** For the host to say, in its own voice, what now judges the run. */
+    onAdopted?: (oracle: Oracle, proposal: CheckProposal) => void;
+    onError?: (message: string, error: unknown) => void;
+}
+export declare function createProposeCheckTool(options: ProposeCheckToolOptions): AgentTool;