@cerebriline/core 4.100.240

package/dist/logging/early-logger.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Early SDK logger for components that operate before/outside of `ClineCore`
+ * sessions, plus a secret-hashing helper for credential diagnostics.
+ *
+ * `ClineCore.create({ logger })` receives a `BasicLogger` but it is only
+ * threaded to session-scoped components. `ProviderSettingsManager`,
+ * `RuntimeOAuthTokenManager`, and the Cline auth functions in `cline.ts` are
+ * constructed or called before `ClineCore` exists or outside a session.
+ * Hosts call `setSdkLogger()` once at startup and every early component picks
+ * it up without threading loggers through every constructor.
+ *
+ * When no logger is registered, every call is a no-op.
+ *
+ * Secrets are never logged in cleartext; {@link hashSecret} produces an
+ * 8-hex-digit fingerprint that is stable for the same value but irreversible.
+ */
+import type { BasicLogger } from "@cerebriline/shared";
+/**
+ * Register the logger used by {@link sdkDebug}. Pass `undefined` to disable.
+ */
+export declare function setSdkLogger(logger: BasicLogger | undefined): void;
+/** @internal Returns the currently registered early logger (for testing). */
+export declare function getSdkLogger(): BasicLogger | undefined;
+/**
+ * Short, stable fingerprint of a secret for debug logging (8 hex digits of a
+ * SHA-256 digest). The same input always yields the same hash, making it easy
+ * to eyeball whether a token changed across log entries without leaking it.
+ *
+ * Returns `"unset"` for undefined/null/empty so absence is still visible.
+ */
+export declare function hashSecret(value: unknown): string;
+/**
+ * Emit a debug-level SDK diagnostic message (already a formatted string).
+ * Best-effort: swallows errors from the underlying logger so logging never
+ * breaks auth/storage flows.
+ */
+export declare function sdkDebug(message: string): void;

package/dist/remote-config/integration.d.ts

@@ -0,0 +1,17 @@
+import { type AgentExtension, buildRemoteConfigSessionBlobUploadMetadata, type ITelemetryService, type OpenTelemetryClientConfig, type PreparedRemoteConfigRuntime, type PrepareRemoteConfigRuntimeOptions, REMOTE_CONFIG_SESSION_BLOB_UPLOAD_METADATA_KEY, readRemoteConfigSessionBlobUploadMetadata, registerRemoteConfigSessionBlobUpload } from "@cerebriline/shared";
+import type { ClineCoreStartInput } from "../cline-core/types";
+import type { CreateOpenTelemetryTelemetryServiceOptions } from "../services/telemetry/OpenTelemetryProvider";
+import type { SessionMessagesArtifactUploader } from "../types/session";
+export interface PrepareRemoteConfigCoreIntegrationOptions extends PrepareRemoteConfigRuntimeOptions {
+    telemetryService?: Omit<CreateOpenTelemetryTelemetryServiceOptions, keyof OpenTelemetryClientConfig>;
+}
+export interface PreparedRemoteConfigCoreIntegration {
+    prepared: PreparedRemoteConfigRuntime;
+    extensions: AgentExtension[];
+    telemetry?: ITelemetryService;
+    applyToStartSessionInput(input: ClineCoreStartInput): ClineCoreStartInput;
+    dispose(): Promise<void>;
+}
+export declare function createRemoteConfigSessionMessagesArtifactUploader(): SessionMessagesArtifactUploader;
+export declare function prepareRemoteConfigCoreIntegration(options: PrepareRemoteConfigCoreIntegrationOptions): Promise<PreparedRemoteConfigCoreIntegration>;
+export { buildRemoteConfigSessionBlobUploadMetadata, REMOTE_CONFIG_SESSION_BLOB_UPLOAD_METADATA_KEY, readRemoteConfigSessionBlobUploadMetadata, registerRemoteConfigSessionBlobUpload, };

package/dist/runtime/atomic/base-revision-reads.d.ts

@@ -0,0 +1,106 @@
+/**
+ * `read_files` with a `revision`, offered wherever a file history is being kept.
+ *
+ * Built for the change protocol and worded for it; the escalation keeps a
+ * history of its own -- the expert's writes, so the base model can check a note
+ * against the bytes it was about -- and needs the same reads under different
+ * words. `RevisionWording` below is that seam, and the change protocol's words
+ * remain the default, so nothing that called this before sees any change.
+ *
+ * A decoration rather than a parameter on the built-in tool, and deliberately:
+ * without an open transaction there is no base revision, and a schema that
+ * advertises one anyway teaches the model a call that can only ever be
+ * refused. Every host that runs without the protocol sees exactly the tool it
+ * saw before this existed — same description, same schema, same behaviour.
+ *
+ * The read is the safe half of this pair. `restore_file` next door hands the
+ * model a lever it can pull too often; this one only ever adds information, so
+ * a model that leans on it cannot thrash with it.
+ */
+import type { AgentToolDefinition } from "@cerebriline/shared";
+import { type RevisionLog } from "./file-revisions";
+import type { Snapshot } from "./snapshot";
+/** The value that asks for the transaction's copy instead of the file on disk. */
+export declare const BASE_REVISION = "base";
+/** What the decoration needs from the controller, and nothing more. */
+export interface BaseRevisionSource {
+    /** The open transaction's base, or nothing when none is open. */
+    readonly pending: Snapshot | undefined;
+    /** Which transaction is open, for messages that need to name it. */
+    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 lets a session read its own history with the change protocol
+     * off. There is no base snapshot then, so `#1` comes from the log, seeded
+     * from the file itself at first touch — which is what the compaction
+     * ledger's addresses point at either way.
+     */
+    readonly root?: string;
+}
+/**
+ * The words that differ between the two histories this decoration can serve.
+ *
+ * One machinery, two arrangements. The change protocol's log holds the base
+ * model's own edits inside its open transaction; the escalation's holds the
+ * expert's edits while the base model stands down and watches. The numbering,
+ * the de-duplication and the reads are identical. What is not identical is who
+ * wrote the versions and what the reader means to do with them -- and a reader
+ * told "your own edits are not in it" about somebody else's edits has been
+ * told something false.
+ */
+export interface RevisionWording {
+    /** Appended to `read_files`' description. */
+    readonly description: string;
+    /** The `revision` parameter's own description. */
+    readonly parameter: string;
+    /** What a refusal calls the span: "this transaction", "this escalation". */
+    readonly span: string;
+    /** What a served revision #1 is called. */
+    readonly baseLabel: string;
+    /** The refusal when nothing is open at all. */
+    readonly closed: string;
+}
+/** How the change protocol talks about its own revisions. The default. */
+export declare const TRANSACTION_REVISION_WORDING: RevisionWording;
+/** How the escalation talks about the expert's revisions. */
+/**
+ * The words for a session that has no transactions.
+ *
+ * Same machinery, third arrangement. `#1` here is the file as this session
+ * first found it rather than a base a rollback returns the tree to, and the
+ * "closed" line has to say something the model can act on: with the protocol
+ * off there is no transaction to open, so "no transaction is open" would be
+ * true forever and mean nothing.
+ */
+export declare const SESSION_REVISION_WORDING: RevisionWording;
+export declare const ESCALATION_REVISION_WORDING: RevisionWording;
+/**
+ * A second history that takes over while it is live.
+ *
+ * The escalation's, in practice. Two logs exist at once during a hand-over --
+ * the base model's open transaction and the expert's writes -- and they cannot
+ * both answer `revision: "#3"`. They do not have to: while the expert has the
+ * pen the base model is standing down and its own transaction is not moving,
+ * so the only numbers that mean anything are the expert's, and those are the
+ * ones the notes are quoting. When the escalation closes and the log is
+ * purged, this stops being live and the transaction answers again.
+ *
+ * Stacking two decorations instead would not work: the outer one would take
+ * `revision` off the input and the inner would never see it.
+ */
+export interface RevisionOverlay {
+    readonly source: BaseRevisionSource;
+    readonly wording: RevisionWording;
+    /** Whether this is the history a `revision` means right now. */
+    live(): boolean;
+}
+/**
+ * Return the tool list with `read_files` able to serve the transaction's base.
+ *
+ * Wraps rather than rebuilds, so every wrapper already applied to the tool —
+ * task-progress capture, edit verification — still sees an ordinary read.
+ */
+export declare function withBaseRevisionReads<T extends AgentToolDefinition>(tools: readonly T[], source: BaseRevisionSource, wording?: RevisionWording, overlay?: RevisionOverlay): T[];

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

@@ -0,0 +1,77 @@
+/**
+ * The transaction's base revision, addressed by path.
+ *
+ * A transaction already holds what every file said when it opened — that copy
+ * is the undo the whole protocol is built on. Until now only the rollback
+ * could read it, and the model, having mangled a file, had to reconstruct the
+ * original from memory.
+ *
+ * Measured on the run that prompted this (pandorum, 2026-09-05, 7328s, three
+ * discarded transactions): 22 of 43 edits re-edited a line the same
+ * transaction had already edited, and 91% of the run's wall clock fell after
+ * the model first wrote "I accidentally deleted the entire `dDec` method. Let
+ * me restore it correctly" — restoring, from memory, a 400-character minified
+ * line. The snapshot next door had it exactly.
+ *
+ * So: one resolver, shared by the read side and the restore side, and it
+ * distinguishes the cases rather than collapsing them into "not found". A file
+ * the transaction created and a file the snapshot could not hold both have no
+ * base revision, and they mean opposite things.
+ */
+import type { Snapshot } from "./snapshot";
+/** How a requested path relates to the transaction's base. */
+export type BaseFileLookup = 
+/** The snapshot holds it, with these bytes. */
+{
+    readonly kind: "held";
+    readonly absolutePath: string;
+    readonly body: Buffer;
+}
+/**
+ * Inside the snapshot's root, and the snapshot does not hold it — so this
+ * transaction created it. Its base revision is the file not existing, which
+ * is a real answer and not a failure.
+ */
+ | {
+    readonly kind: "created";
+    readonly absolutePath: string;
+}
+/** The snapshot skipped it: too large, a symlink, or past the limits. */
+ | {
+    readonly kind: "uncovered";
+    readonly absolutePath: string;
+}
+/** Outside the root the transaction covers, so nothing was ever held. */
+ | {
+    readonly kind: "outside";
+    readonly absolutePath: string;
+};
+/**
+ * Resolve a path the model gave against the transaction's base.
+ *
+ * Relative paths resolve against the snapshot's root rather than the process
+ * working directory: the root is what the transaction covers, and resolving
+ * elsewhere would report "outside the transaction" for a file sitting in it.
+ */
+export declare function resolveBaseFile(snapshot: Snapshot, requestedPath: string): BaseFileLookup;
+/**
+ * Why a path has no base text to show, in the words the model gets.
+ *
+ * Never "not found": each of these is a different fact about the transaction,
+ * and a model told the wrong one goes looking for the wrong thing.
+ */
+export declare function describeMissingBase(lookup: Exclude<BaseFileLookup, {
+    kind: "held";
+}>): string;
+/** Whether a snapshot's bytes can be shown as text at all. */
+export declare function isTextBody(body: Buffer): boolean;
+/**
+ * Resolve a path against the workspace, for a session with no transaction.
+ *
+ * The same answers `resolveBaseFile` gives, minus the one that needs a
+ * snapshot: there is no `uncovered`, because nothing was skipped by a snapshot
+ * that was never taken. A file inside the root reads as `created`, which here
+ * means "the log decides what it had" — and the log is seeded from the file
+ * itself at first touch, so that is exactly right.
+ */
+export declare function resolveSessionFile(root: string, requestedPath: string): BaseFileLookup;

package/dist/runtime/atomic/check-first-edits.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Hold the first edit of a transaction until the model has run the check.
+ *
+ * The protocol has said "before you edit anything, so you see the failure in
+ * its own words" since it was written, and it is the sentence models skip.
+ * Measured on a JackDelta 9B session, per transaction, counting from the first
+ * tool call:
+ *
+ *   TX-01  first `run_check` at tool call #25, after ten edits
+ *   TX-02  #3
+ *   TX-03  #0
+ *   TX-04  #7
+ *   TX-05  #0
+ *
+ * TX-01 is the expensive one and the pattern is the same every time it
+ * happens: the model reads the file, forms a theory from the source alone,
+ * edits against that theory, and only then asks the program what was actually
+ * wrong. In that run the first theory was a delimiter fault; the check, when
+ * it was finally run, reported `ReferenceError: collide is not defined`. Two
+ * dozen tool calls were spent before anything told it which of those it was
+ * looking at.
+ *
+ * So the sentence is turned into a gate. Not a permanent one: it refuses one
+ * edit, once per transaction. It is a nudge with a mechanism, not a new rule.
+ *
+ * It also asks for the plan, because that is the other thing the same run did
+ * not do: TX-01, TX-02 and TX-03 produced no plan text of any kind, the model
+ * going straight from reading to editing.
+ *
+ * Those two used to be one condition, and that was wrong. The gate fired only
+ * when the check had not been run, so a transaction that opened *with* the
+ * check bought an exemption from stating its plan. Measured on a later
+ * jackdelta-9b session that did exactly the right thing first: `run_check` was
+ * tool call #1 in TX-01, the gate therefore never fired, and no plan was
+ * stated -- 362 messages produced exactly one plan, in TX-02, and it appeared
+ * because the gate fired there. The model was rewarded for running the check
+ * by being asked for less.
+ *
+ * So the gate always fires once per transaction, and only the message changes:
+ * a model that has already run the check is asked for the plan alone, and is
+ * not told to re-run something it just ran.
+ *
+ * "Once" is once per turn, not once per call. A model that sends its edits as
+ * a parallel batch used to have exactly one of them refused while the rest
+ * applied, which is the worst of both: it was told its edit did not happen and
+ * asked for a plan, while two other edits it had not planned were already on
+ * disk. Measured on session 1789032320523_q29ta, assistant message 9: three
+ * `editor` calls in one message, the first held and the other two applied. So
+ * the hold covers every edit sharing the held call's iteration, and stands
+ * down from the next turn — which is the first moment the model could have
+ * read the refusal and answered it.
+ */
+import type { AgentToolDefinition } from "@cerebriline/shared";
+/** What the gate needs to know, and nothing more. */
+export interface CheckFirstSource {
+    /** Which transaction is open, so the gate can reset when it changes. */
+    readonly transaction: number;
+    /** How the check is named to the model, for a message it can act on. */
+    readonly checkLabel: string;
+}
+/**
+ * What the model is told instead of its first edit.
+ *
+ * Written as the two things to do next rather than as a rule it broke: a
+ * refusal that argues is one a model answers, and the turn is worth more spent
+ * on the check than on the disagreement. It says the edit did not happen, in
+ * as many words, because a model that thinks the change landed will build the
+ * next one on top of it.
+ */
+export declare function describeCheckFirst(checkLabel: string, checkAlreadyRun?: boolean): string;
+/**
+ * Wrap the editing tools so the first one waits for the check.
+ *
+ * Wrapping rather than asking the controller: whether the check has been run is
+ * a fact about this transaction's tool calls, and the tool list is where those
+ * are already passing. It also keeps the gate off entirely for a host with no
+ * check to run, which is the case it must not fire in.
+ */
+export declare function withCheckFirstEdits<T extends AgentToolDefinition>(tools: readonly T[], source: CheckFirstSource): T[];

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

@@ -0,0 +1,268 @@
+/**
+ * A per-file history inside the open transaction.
+ *
+ * The transaction's base snapshot is one point in time, and `restore_file`
+ * could only ever go back to it. That is the whole complaint: a model that
+ * has fixed three things and broken the fourth has to choose between keeping
+ * the break and throwing away the three (user, 2026-09-13: "restoring to
+ * original doesn't work, the model is loosing all the wins or half wins and
+ * starts from scratch"). Measured in the same shape on arm p01 -- three
+ * transactions, 8 discards, not one kept.
+ *
+ * So every write to a file appends a revision holding what the file said
+ * afterwards, and the model can go back to any of them by number. Revision 1
+ * is always the file as the transaction opened, which is what `restore_file`
+ * used to be able to do and nothing more.
+ *
+ * Why per-file and not a tree snapshot per change. `takeSnapshot` walks the
+ * whole workspace and reads every file; doing that after each edit would make
+ * a 5,000-file repository unusable. A revision is already addressed per file
+ * -- the model asks to put *one file* back -- so only the file a tool wrote is
+ * captured.
+ *
+ * Why numbers and not hashes. The audience is a 9B model reading its own
+ * conversation. `#4` is orderable, self-describing and cannot be confused with
+ * a path; `a3f9c21` is a token this model class invents when it half-remembers
+ * one, and a fabricated hash is indistinguishable from a real one until it is
+ * refused.
+ *
+ * Append-only. Restoring to #2 does not renumber anything -- it appends a new
+ * revision whose content equals #2. A model re-reads its own history
+ * constantly, and a #3 that silently stops meaning what it meant is worse than
+ * a larger number.
+ */
+/** What a file said at one point in the transaction. */
+export interface FileRevision {
+    /** One-based, in the order they were made. #1 is the transaction's base. */
+    readonly index: number;
+    /** The content, or nothing when the file did not exist at that point. */
+    readonly body: Buffer | undefined;
+    readonly hash: string;
+    /** What produced it: a tool name, or `transaction open` for #1. */
+    readonly by: string;
+    /**
+     * One line saying what this revision is, so the list can be chosen from.
+     *
+     * Without it every entry reads `editor — 136 lines` and the only one
+     * carrying meaning is `#1 original`, which is measurably the only one the
+     * model ever asked for: 132 restores across three runs, 132 to the
+     * original. A number is an address; this is the reason to go to it.
+     *
+     * `model` when the tool call said what it was for, `derived` when we had to
+     * work it out. Never absent — an unlabelled revision is one the model
+     * cannot choose, which is the whole defect.
+     */
+    readonly note: string;
+    readonly noteSource: "model" | "derived";
+    readonly lines: number;
+    readonly bytes: number;
+    /** Content released to stay under the memory cap; the entry remains. */
+    readonly dropped: boolean;
+    /** Kept for reading and restoring, never written to this workspace. */
+    readonly held?: boolean;
+    /**
+     * The earliest revision holding exactly these bytes, when it is not this
+     * one.
+     *
+     * Worth surfacing rather than just exploiting. A model that edits, undoes
+     * and edits back to the same text is in the loop this whole feature exists
+     * to break, and its own history is the one place that can show it the shape
+     * of what it has been doing.
+     */
+    readonly sameAs?: number;
+}
+export type RevisionLookup = {
+    kind: "found";
+    revision: FileRevision;
+} | {
+    kind: "untracked";
+} | {
+    kind: "dropped";
+    index: number;
+} | {
+    kind: "unknown";
+    requested: string;
+    available: readonly number[];
+};
+export interface RevisionLimits {
+    /** Content held for one file before the middle is released. */
+    maxBytesPerFile?: number;
+    /**
+     * Content held across every file before the middle is released.
+     *
+     * The per-file cap alone is only a bound when the log's lifetime is a
+     * transaction, which is short and touches a handful of files. A log that
+     * lives for the session touches as many files as the session does, and 32 MB
+     * each is not a limit — it is a limit per file, multiplied by a number
+     * nobody chose.
+     */
+    maxBytesTotal?: number;
+}
+/**
+ * Content held per file before revisions start being released.
+ *
+ * A 4 MB file -- the snapshot's own per-file ceiling -- edited fifty times is
+ * 200 MB for one transaction, and a transaction is not the only thing in the
+ * process. 32 MB covers the realistic case (a 15 KB source file has room for
+ * two thousand revisions) and bounds the pathological one.
+ */
+export declare const DEFAULT_MAX_REVISION_BYTES_PER_FILE: number;
+/**
+ * Content held across all files before the oldest is released.
+ *
+ * 128 MB: four times the per-file cap, so one pathological file cannot starve
+ * the rest, and small enough that a session holding the maximum is a number a
+ * person would recognise as deliberate rather than a leak. A session editing
+ * fifteen-kilobyte source files reaches it after roughly eight thousand
+ * revisions, which is not a session.
+ */
+export declare const DEFAULT_MAX_REVISION_BYTES_TOTAL: number;
+/** Revisions listed in a receipt before the middle is elided. */
+export declare const DEFAULT_REVISION_LIST_LIMIT = 10;
+/** The name for the transaction's own base revision. */
+export declare const ORIGINAL_REVISION = "original";
+/** The state before the most recent change. */
+export declare const LAST_REVISION = "last";
+/** What a caller can say about a revision it is recording. */
+export interface RevisionNote {
+    /** The model's own words, when the tool call carried them. */
+    readonly intent?: string;
+    /** What the writing tool reported doing, e.g. "Replaced line 90". */
+    readonly summary?: string;
+    /** What the checker said about this file afterwards, when it said anything. */
+    readonly check?: string;
+    /**
+     * The content was never written to this workspace: a delegated agent's
+     * version, kept so the lead can read or restore it. The file on disk is
+     * still the newest revision that is not held.
+     */
+    readonly held?: boolean;
+}
+/**
+ * The revisions a file has, as one short label like `#1–#7`.
+ *
+ * What the compaction ledger prints beside a file, so the model reading a
+ * summary knows the earlier content exists and what to ask for. A range rather
+ * than a count because the numbers are the addresses: `3 revisions` leaves the
+ * reader to guess whether they are numbered from zero.
+ *
+ * A single revision is `#1`, never `#1–#1` — a range with nothing in the
+ * middle reads as a mistake, and this audience is a small model that will
+ * repeat what it reads.
+ */
+export declare function revisionSpan(revisions: readonly FileRevision[]): string | undefined;
+/**
+ * What `#1` is, in the two worlds this log lives in.
+ *
+ * `transaction` is the base snapshot — a rollback can return the whole tree to
+ * it. `session` is the file's own content at first touch, which undoes this
+ * session's writes to that file and promises nothing about the tree.
+ */
+export type RevisionOrigin = "transaction" | "session";
+export interface RevisionLog {
+    /**
+     * Record the file as it was found. Ignored if already seeded.
+     *
+     * `origin` is what `#1` is said to be, and it is not cosmetic: inside a
+     * transaction `#1` is the base the rollback goes back to, and outside one it
+     * is merely what the file said the first time this session wrote to it. The
+     * second is a weaker promise, and a label claiming the first would teach the
+     * model to expect a rollback that cannot happen.
+     */
+    seed(absolutePath: string, body: Buffer | undefined, origin?: RevisionOrigin): void;
+    /**
+     * Record what a tool left behind. Returns the new revision, or nothing when
+     * the content is what it already was -- a tool that reported a refusal, or
+     * an edit that replaced text with itself, has not made a revision.
+     */
+    record(absolutePath: string, body: Buffer | undefined, by: string, note?: RevisionNote): FileRevision | undefined;
+    revisions(absolutePath: string): readonly FileRevision[];
+    resolve(absolutePath: string, requested: string): RevisionLookup;
+    tracked(): readonly string[];
+    /** Distinct bytes held for one file, after de-duplication. */
+    heldBytes(absolutePath: string): number;
+    /** Forget everything. A discard puts the tree back, so the history goes too. */
+    reset(): void;
+    /**
+     * Close the current compaction span and release what the next one cannot use.
+     *
+     * The retention policy, and it is semantic rather than a size. A revision
+     * exists so the ledger in a compaction summary can say "the content is not
+     * here, it is at `#4`", and so the model can go back to it. Both of those
+     * stop being possible two compactions later: the summary that named `#4`
+     * has itself been folded into a newer summary, and nothing the model can
+     * still read mentions it. Holding it after that is holding bytes no one can
+     * address.
+     *
+     * So a file's history survives while it was written inside the last two
+     * spans, and beyond that only while something the model can still see names
+     * it — the summary just written, and the retained tail when there is one.
+     * `keep` is that whitelist, and a file in it is never dropped however old.
+     *
+     * Whole files, not individual revisions. A file written inside the window is
+     * live and its whole history is worth having; one that has not been touched
+     * for two compactions and is named nowhere is not half-interesting. Dropping
+     * revisions out of the middle of a surviving file is what the byte cap does,
+     * for a different reason, and mixing the two would leave histories with
+     * holes that mean two different things.
+     *
+     * Returns how many files it released, for the log line.
+     */
+    noteCompaction(keep?: Iterable<string>): number;
+}
+/**
+ * Which version a `restore_file` call asked for, as something that can be said
+ * out loud.
+ *
+ * The chat row that reports a restore has to name its target, and it only has
+ * the call's arguments to name it from -- the row is built when the call
+ * starts. It used to name none of them: the header was the constant sentence
+ * "put this file back as the transaction found it", written when the base was
+ * the only place the tool could go. A restore to `#3` was reported as a
+ * restore to the base.
+ *
+ * This goes through `parseRevision`, the same reader the tool itself uses, so
+ * the aliases stay one set. Add an alias there and every caller says the right
+ * thing without being told.
+ */
+export type RestoreTarget = {
+    readonly kind: "original";
+} | {
+    readonly kind: "last";
+} | {
+    readonly kind: "numbered";
+    readonly index: number;
+} | {
+    readonly kind: "unreadable";
+    readonly requested: string;
+};
+export declare function describeRestoreTarget(requested: string | undefined | null): RestoreTarget;
+export declare function createRevisionLog(_unused?: unknown, limits?: RevisionLimits): RevisionLog;
+/**
+ * The history, written for the model rather than for a log file.
+ *
+ * Stated in full on every read of a covered file, and not only in the receipt
+ * for an edit. The ids are useless if they live only in scrollback: run 0295
+ * auto-compacted eight times, and a long thrashing run -- the exact run that
+ * needs to go back three revisions -- is the one whose early receipts are gone.
+ * Re-stating the list makes it recoverable from one call.
+ */
+export declare function describeRevisions(display: string, revisions: readonly FileRevision[], options?: {
+    limit?: number;
+    span?: string;
+}): string;
+/**
+ * Find the revisions that contain something, so a number can be looked up
+ * rather than remembered.
+ *
+ * The list answers "what are my options"; this answers "which one had the thing
+ * I want back". Those are different questions, and only the second one is
+ * asked by a model that has just deleted a method and knows exactly what it is
+ * looking for. Without it the model's only recourse is to restore candidates
+ * one at a time and read the file after each, which spends the restore budget
+ * on searching.
+ *
+ * Notes are searched as well as content: once a revision is labelled with the
+ * model's own sentence, "the dBoss brace" is a likelier query than the code.
+ */
+export declare function searchRevisions(display: string, revisions: readonly FileRevision[], query: string): string;