@orkestrel/agent 0.0.30 → 0.0.31

package/dist/src/core/index.d.cts

@@ -42,22 +42,25 @@ import type { WorkspaceManagerInterface } from '@orkestrel/workspace';
  *
  * @remarks
  * - **One loop, two faces.** A single private async generator (`#execute`) drives the
- *   whole turn. `stream` kicks off an eager pump that iterates `#execute` into a private
- *   {@link Channel}, settling `result` from the run's outcome — so `result` settles
+ *   whole run. `stream` drives it eagerly into a private {@link Channel} and settles `result`
+ *   from the outcome the generator returns, through one `.then` — so `result` settles
  *   whether or not the live `events` are drained; `generate` awaits that same
  *   settled `result` — so the two can never diverge.
- * - **The turn.** `#execute` builds the provider input once (`context.build()` into a
- *   working array) then loops up to `limit`: drive `provider.stream(...)` accumulating
- *   + yielding each content delta as a `token` chunk; fold the turn's usage into the
- *   running total + the `budget` and yield a `usage` chunk; if the model requested
- *   tools, append the assistant turn, pass them to the tool manager's `execute` method, yield a `tool` chunk per call,
- *   append each tool result message, and continue; otherwise append the final
- *   assistant message and stop. Each assistant message stores its call's non-empty thinking.
+ * - **The turn.** `#execute` builds the provider input once, then runs up to `limit` turns,
+ *   each appending one readonly {@link AgentTurn} record: drive `provider.stream(...)`,
+ *   yielding each content delta as a `token` chunk and charging its estimate to the
+ *   `allowance` when one is set; reconcile the turn's usage against the `budget`, before a
+ *   genuine provider error rejects the run too, and yield a `usage` chunk; if the model
+ *   requested tools, append the assistant turn, pass them to the tool manager's `execute`
+ *   method, yield a `tool` chunk per call, append each tool result message, and continue;
+ *   otherwise append the final assistant message and stop. The run's content,
+ *   thinking, usage, and stop derive from the turn records. Each assistant message stores its
+ *   call's non-empty thinking.
  *   Provider calls and prompt estimates apply the provider's `replay` policy to the working
  *   array; an absent policy means `'none'`.
  * - **Bounded.** Each run arms one cancel through `createAbort({ signal: AbortSignal.any([
- *   …]) })` folding the external `signal`, the `timeout` deadline, and the `budget`
- *   signal; `abort()` fires it. Any trip stops the loop and commits a partial result
+ *   …]) })` folding the external `signal`, the `timeout` deadline, and the `budget` and
+ *   `allowance` signals; `abort()` fires it. Any trip stops the loop and commits a partial result
  *   (the `result` promise resolves, never rejects, on a cancel) — only a genuine
  *   provider / tool error rejects.
  * - **Paced + capped.** The loop calls the `scheduler` object's `yield` method between turns when given; tool
@@ -105,6 +108,8 @@ export declare class Agent implements AgentInterface {
  *   emitted after the tool runs (so a consumer sees what was called and what came back).
  * - `usage` — one provider call's {@link TokenUsage}, emitted after each turn's
  *   provider response that reported it (folded into the running total + any budget).
+ *   `estimate` is the token estimate of the answer the call streamed, the meter layer's reading
+ *   beside the reported usage.
  */
 export declare type AgentChunk = {
     readonly category: 'token';
@@ -119,6 +124,7 @@ export declare type AgentChunk = {
 } | {
     readonly category: 'usage';
     readonly usage: TokenUsage;
+    readonly estimate: number;
 };
 
 /**
@@ -314,8 +320,9 @@ export declare interface AgentContextInterface {
      * `scope.files` (a three-way allow-list; `undefined` ⇒ all active files), then split by
      * carrier: text files ({@link import('@orkestrel/workspace').isText}) render into a dedicated
      * `## Workspace` section in the system block — each a fenced
-     * `` File: <path>\n```<language>\n<text>\n``` `` block — placed immediately after the instructions
-     * section; binary files whose MIME starts with `image/` have their `base64` payload
+     * `` File: <path>\n```<language>\n<text>\n``` `` block whose fence is one backtick longer than
+     * the longest backtick run in the text, and never shorter than three — placed immediately after
+     * the instructions section; binary files whose MIME starts with `image/` have their `base64` payload
      * attached to the last user message (a vision provider reads images off a user turn).
      * Active-only — never the other registered workspaces; with no active workspace nothing is
      * rendered for workspaces.
@@ -411,25 +418,41 @@ export declare interface AgentContextOptions {
 }
 
 /**
- * Reports a concurrent run sharing construction accounting or a name absent from a registry pool. The `stream` and `generate` methods and registry accessors throw synchronously, before returning a handle or promise. Await the call inside `try`/`catch` to catch it.
+ * Reports a run sharing accounting with a live run, a `limit` that is not a nonnegative safe integer, a name absent from a registry pool, or a strict run whose request exceeds its window. Agent construction, the `stream` and `generate` methods, and registry accessors throw synchronously, before returning a handle or promise; a `'WINDOW'` refusal rejects the run's `result` instead. Await the call inside `try`/`catch` to catch it.
  *
  * @remarks
- * `'CONCURRENCY'` reports a run already in flight on the same agent, plus a construction-level
- * `window` (a shared context budget) or a construction-level `budget` with no per-run override
- * (a shared cost budget) — a second concurrent `stream()` would race its charges against the
- * same shared instance, corrupting the accounting. Use separate agents, or per-run `budget`
- * overrides with no `window`, for genuinely concurrent runs. `'REGISTRY'` reports a rehydration
- * name absent from its registry pool, on `provider` / `tool` / `authority` / `scheduler` /
- * `build`. Narrow a caught value with {@link isAgentError} and branch on `error.code`.
+ * `'CONCURRENCY'` reports a run started while another run on the same agent is live, when the
+ * agent carries a `window` (a shared context budget) or when the run's effective `budget` or
+ * `allowance` is an instance a live run holds — the second run's `start()` would replace that
+ * instance's signal and race its charges against the first run's. Use separate agents, or
+ * distinct budget and allowance instances per run with no `window`, for concurrent runs. Its
+ * `context` names the `agent` id.
+ * `'LIMIT'` reports a construction or per-run `limit` that is not a nonnegative safe integer,
+ * including one a rehydrated job carries into `build`. `'REGISTRY'` reports a rehydration name
+ * absent from its registry pool, on `provider` / `tool` / `authority` / `scheduler` / `build`;
+ * its `context` names the `category` and the `name`. `'WINDOW'` reports a `strict` run whose
+ * complete provider request is still over the `window` budget, equal to its `max` included, after
+ * the one permitted fold or with no fold possible; it settles the run `error` before the provider
+ * is called, and its `context` holds the `agent` id, the measured `consumed`, and the window `max`.
+ * Narrow a caught value with {@link isAgentError} and branch on `error.code`.
  */
 export declare class AgentError extends Error {
-    /** Names the machine-readable condition — `'CONCURRENCY'`: a concurrent run on a shared accounting agent; `'REGISTRY'`: a rehydration name absent from its registry pool. */
+    /** Names the machine-readable condition — `'CONCURRENCY'`: a run sharing accounting with a live run; `'LIMIT'`: a `limit` that is not a nonnegative safe integer; `'REGISTRY'`: a rehydration name absent from its registry pool; `'WINDOW'`: a strict run whose complete request is still over its window budget. */
     readonly code: AgentErrorCode;
-    constructor(code: AgentErrorCode, message: string);
+    /** Holds the values that locate the failure, such as the `agent` id of a refused run, or `undefined` when none were supplied. */
+    readonly context: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * Creates the error with its code, message, and optional cause and context.
+     *
+     * @param code - The machine-readable {@link AgentErrorCode}
+     * @param message - The human-readable description
+     * @param options - The optional {@link CodedErrorOptions}; `cause` reaches `Error.cause` only when present
+     */
+    constructor(code: AgentErrorCode, message: string, options?: CodedErrorOptions);
 }
 
-/** Names the machine-readable agent concurrency and registry failures. */
-export declare type AgentErrorCode = 'CONCURRENCY' | 'REGISTRY';
+/** Names the machine-readable agent concurrency, limit, registry, and window failures. */
+export declare type AgentErrorCode = 'CONCURRENCY' | 'LIMIT' | 'REGISTRY' | 'WINDOW';
 
 /**
  * Maps the push observation surface of an {@link AgentInterface} — the lifecycle, usage, and tool
@@ -466,8 +489,12 @@ export declare type AgentEventMap = {
     readonly turn: readonly [index: number];
     /** Reports a dispatched {@link ToolCall} paired with its {@link ToolResult} (executed or a denial). */
     readonly tool: readonly [call: ToolCall, result: ToolResult];
-    /** Reports a turn's {@link TokenUsage} — emitted after a usage-bearing provider call. */
-    readonly usage: readonly [usage: TokenUsage];
+    /**
+     * Reports a turn's {@link TokenUsage} — emitted after a usage-bearing provider call. Carries the
+     * call's streamed-answer `estimate` beside its reported usage, so the meter's allowance can be
+     * calibrated without a failure.
+     */
+    readonly usage: readonly [usage: TokenUsage, estimate: number];
     /**
      * Reports a call denied by scope or authority, before dispatch.
      * A turn advertising no tools drops each call with `no tool is advertised in the active scope`.
@@ -490,7 +517,7 @@ export declare type AgentEventMap = {
     readonly exhaust: readonly [turns: number];
     /**
      * Reports automatic compaction's summarizer throwing — a non-fatal warn channel (the run continues; see
-     * {@link AgentOptions.window}). When the loop's between-turns / pre-first-turn auto-compaction
+     * {@link AgentOptions.window}). When the loop's pre-dispatch auto-compaction
      * (`conversation.compact()`) rejects, the run does not crash: the loop skips compaction that
      * turn and surfaces the caught error here so the failure is observable, never silently lost.
      * The run still settles through the other events — `finish` for the lenient default, and
@@ -511,21 +538,67 @@ export declare type AgentEventMap = {
     readonly select: readonly [selection: Selection];
 };
 
+/**
+ * Executes one runner's agent jobs — spawning each unit's declared children on its first attempt
+ * only, then rehydrating the unit through a registry with the controller signal and settling it
+ * under the shared partial-result policy.
+ *
+ * @remarks
+ * One instance serves one runner, because it records every unit it has fanned out. The runner
+ * calls its handler once per attempt with the same unit id, so a retried attempt finds its unit
+ * recorded and spawns no child again. Children are fired through the controller without being
+ * awaited inline, so a bounded runner frees the parent's slot for them. `createAgentRunner`
+ * creates one instance per runner and binds its `execute` method as the runner's handler.
+ *
+ * @example
+ * ```ts
+ * import type { AgentJobInput, ProviderInterface } from '@orkestrel/agent'
+ * import { AgentFanout, createAgentRegistry } from '@orkestrel/agent'
+ * import { createRunner } from '@orkestrel/workflow'
+ *
+ * declare const provider: ProviderInterface // any concrete implementation supplied by the host app
+ * const fanout = new AgentFanout(createAgentRegistry({ providers: { main: provider } }), false)
+ * const runner = createRunner({ handler: fanout.execute.bind(fanout), retries: 1 })
+ * const child: AgentJobInput = { provider: 'main', messages: [{ role: 'user', content: 'child' }] }
+ * const parent: AgentJobInput = { ...child, messages: [{ role: 'user', content: 'parent' }], children: [child] }
+ * const results = await runner.execute([parent]) // the parent's result, then the child's
+ * ```
+ */
+export declare class AgentFanout {
+    #private;
+    /**
+     * Creates the fan-out for one runner over a registry and a partial policy.
+     *
+     * @param registry - The registry that rehydrates each serializable job
+     * @param partial - The partial policy. If `true`, a partial result resolves; if `false`, it throws an `AgentJobError`
+     */
+    constructor(registry: AgentRegistryInterface, partial: boolean);
+    /**
+     * Executes one unit: spawns its declared children unless an earlier attempt of the unit already
+     * did, then runs the rehydrated agent and settles it under the partial policy.
+     *
+     * @param controller - The runner controller for this unit's attempt
+     * @returns The settled agent result of the unit
+     * @throws {AgentJobError} Thrown when the run ended partial and the partial policy is `false`
+     */
+    execute(controller: ControllerInterface<AgentJobInput, AgentResult>): Promise<AgentResult>;
+}
+
 /**
  * Composes a {@link ProviderInterface}, an {@link AgentContextInterface}, and a
  * {@link ToolManagerInterface} into a bounded context → provider → tools → repeat turn.
  *
  * @remarks
  * - **One loop, two faces.** `generate` and `stream` share one private run, so they
- *   can never diverge: `generate` drains the same stream `stream` exposes, then
- *   resolves its settled {@link AgentResult}.
+ *   can never diverge: `generate` awaits the settled {@link AgentResult} of the run `stream`
+ *   exposes and leaves its live chunks undrained.
  * - **Bounded.** Each turn arms a single cancel folded from the external `signal`, the
- *   `timeout` deadline, and the `budget` signal (through `AbortSignal.any`); any of them —
- *   or `abort()` — stops the loop and settles the result `partial: true`.
+ *   `timeout` deadline, and the `budget` and `allowance` signals (through `AbortSignal.any`); any
+ *   of them — or `abort()` — stops the loop and settles the result `partial: true`.
  *   Tool handlers receive that run's signal through their `ToolContext`. An agent abort,
- *   stream abort, external signal, or deadline can reach a running handler. The budget is
- *   charged during provider streaming and between turns, before tool dispatch; exhaustion
- *   ends the run without dispatching, never inside a handler. An abort before dispatch
+ *   stream abort, external signal, or deadline can reach a running handler. The allowance is
+ *   charged during provider streaming and the budget after each provider call and between turns,
+ *   before tool dispatch; exhaustion ends the run without dispatching, never inside a handler. An abort before dispatch
  *   appends neither the assistant call turn nor tool messages and emits no tool chunk;
  *   streamed content remains in the partial result. Cancellation after entry is cooperative:
  *   the loop awaits a running handler even when it ignores the signal, records its tool message,
@@ -550,20 +623,24 @@ export declare interface AgentInterface {
     readonly status: AgentStatus;
     readonly context: AgentContextInterface;
     /**
-     * Runs the turn to completion, discarding the live chunks — drains the shared stream and
-     * resolves the settled {@link AgentResult} (`partial: true` when cancelled).
+     * Runs the turn to completion — awaits the settled {@link AgentResult} (`partial: true` when
+     * cancelled) and leaves the live chunks undrained.
      *
      * @remarks
-     * A concurrent run on a shared accounting agent throws an
-     * {@link import('./errors.js').AgentError} (`code: 'CONCURRENCY'`) — and it throws
-     * synchronously, before any `Promise` is returned. A fire-and-forget
-     * `agent.generate().catch(...)` therefore will not catch it (the throw happens on the call
-     * itself, ahead of the `.catch` ever attaching) — await the call (inside a `try`/`catch`)
-     * or wrap the call expression itself in `try`/`catch`.
+     * A run started while another is live throws an {@link import('./errors.js').AgentError} with
+     * `code: 'CONCURRENCY'` when the agent carries a `window`, or when the run's effective
+     * `budget` or `allowance` is an instance a live run holds; a run whose `limit` is not a nonnegative safe
+     * integer throws one with `code: 'LIMIT'`. A `budget` or `allowance` that does not implement
+     * `BudgetInterface` throws a `ContractError` with code `'placement'` before either bound starts.
+     * Each throws synchronously, before any `Promise` is
+     * returned. A fire-and-forget `agent.generate().catch(...)` therefore will not catch them (the
+     * throw happens on the call itself, ahead of the `.catch` ever attaching) — await the call
+     * (inside a `try`/`catch`) or wrap the call expression itself in `try`/`catch`.
      *
      * @param options - Optional per-run {@link AgentRunOptions} (for example `think`); omitted ⇒ defaults
      * @returns The settled {@link AgentResult} (`partial: true` when cancelled)
-     * @throws {AgentError} Thrown when a concurrent run shares construction accounting (`code: 'CONCURRENCY'`), synchronously before a handle returns.
+     * @throws {AgentError} Thrown when a live run shares the `window` or a budget or allowance instance (`code: 'CONCURRENCY'`) or the `limit` is not a nonnegative safe integer (`code: 'LIMIT'`), synchronously before a handle returns.
+     * @throws {ContractError} Thrown when the `budget` or `allowance` does not implement `BudgetInterface` (`code: 'placement'`), synchronously before a handle returns.
      */
     generate(options?: AgentRunOptions): Promise<AgentResult>;
     /**
@@ -572,14 +649,18 @@ export declare interface AgentInterface {
      * on a genuine error.
      *
      * @remarks
-     * Like `generate()`, a concurrent run on a shared accounting agent throws an
-     * {@link import('./errors.js').AgentError} (`code: 'CONCURRENCY'`) synchronously — before the
+     * Like `generate()`, a run that would share the `window` or a live run's budget or allowance
+     * instance throws an {@link import('./errors.js').AgentError} with `code: 'CONCURRENCY'`, an
+     * invalid `limit` throws one with `code: 'LIMIT'`, and a `budget` or `allowance` that does not
+     * implement `BudgetInterface` throws a `ContractError` with code `'placement'`, synchronously — before the
      * {@link AgentStreamInterface} handle is even returned, so it cannot be caught by chaining
-     * off the (never-produced) handle; wrap the call itself in `try`/`catch`.
+     * off the (never-produced) handle; wrap the call itself in `try`/`catch`. A `signal` that
+     * `AbortSignal.any` refuses throws its `TypeError` the same way, before any deadline is armed.
      *
      * @param options - Optional per-run {@link AgentRunOptions} (for example `think`); omitted ⇒ defaults
      * @returns A live {@link AgentStreamInterface} handle (events + result + abort)
-     * @throws {AgentError} Thrown when a concurrent run shares construction accounting (`code: 'CONCURRENCY'`), synchronously before a handle returns.
+     * @throws {AgentError} Thrown when a live run shares the `window` or a budget or allowance instance (`code: 'CONCURRENCY'`) or the `limit` is not a nonnegative safe integer (`code: 'LIMIT'`), synchronously before a handle returns.
+     * @throws {ContractError} Thrown when the `budget` or `allowance` does not implement `BudgetInterface` (`code: 'placement'`), synchronously before a handle returns.
      */
     stream(options?: AgentRunOptions): AgentStreamInterface;
     /**
@@ -766,13 +847,17 @@ export declare interface AgentJudgeInterface extends JudgeInterface {
  * - `system` — an optional system prompt prepended to the turn (seeds the context).
  * - `tools` — an optional pre-built {@link ToolManagerInterface} the loop dispatches
  *   the model's calls through; an empty one is created when omitted.
- * - `limit` — the maximum number of tool-iteration turns before the loop stops.
+ * - `limit` — the maximum number of tool-iteration turns before the loop stops, a nonnegative
+ *   safe integer; construction throws an `AgentError` with code `'LIMIT'` when it is not.
  *   Default: `DEFAULT_AGENT_LIMIT`.
  * - `timeout` — an optional wall-clock deadline (ms) for the whole turn; its signal
  *   folds into the turn's bound, committing a partial result on expiry.
  * - `budget` — an optional token {@link BudgetInterface} cost bound; the loop charges
  *   each provider call's usage and its signal folds into the turn's bound, committing
  *   a partial result after the budget is exhausted.
+ * - `allowance` — an optional token {@link BudgetInterface} the meter layer charges each content
+ *   delta's mid-stream estimate against; its signal folds into the turn's bound beside the
+ *   `budget`'s. Pass the `budget` itself to share one ceiling. Omitted ⇒ no meter layer.
  * - `scheduler` — an optional {@link SchedulerInterface} that paces the loop —
  *   the loop calls its `yield` method between turns, so the host regains control between expensive provider calls.
  * - `signal` — an optional external `AbortSignal` whose abort cancels the turn (a
@@ -781,17 +866,20 @@ export declare interface AgentJudgeInterface extends JudgeInterface {
  *   context as the message source (so `context.messages` is its active conversation's live tail);
  *   omitted ⇒ a fresh registry holding one default conversation. Auto-compaction (`window`) folds
  *   the active conversation when it is summarizable.
- * - `window` — an optional context {@link BudgetInterface} for automatic conversation
- *   compaction: when set, the loop measures the current full prompt against this budget each turn
- *   (its `consumer` is a token estimator, its `max` the context window) and, when the prompt
- *   reaches the window and the active conversation is summarizable, compacts the active
- *   conversation + continues on the rebuilt smaller view — compact-and-continue, distinct from
+ * - `window` — an optional context {@link BudgetInterface} over the complete
+ *   {@link ProviderRequest} for automatic conversation compaction: when set, the loop measures the
+ *   exact request, messages after replay, advertised tools, and per-call options, before every
+ *   provider dispatch (its `consumer` is a token estimator, its `max` the context window) and, when
+ *   the request reaches the window and the active conversation is summarizable, compacts the active
+ *   conversation once + dispatches the rebuilt smaller request — compact-and-continue, distinct from
  *   hard abort of the `budget` object. Omitted ⇒ no auto-compaction.
  * - `strict` — when `true`, a summarizer failure during automatic compaction aborts the run
  *   (rethrown after the `fault` event, propagating through `#execute` to a genuine `error`
  *   settle) instead of skipping compaction and continuing over-window. The selection faults (a
  *   thrown handler, a returned `fault`, a conversation changed under the handler) settle the same
- *   way. Default: `false`. The run continues over-window, or on `view()` after a selection fault.
+ *   way, and a request still over the `window` after the permitted fold, or one that cannot fold,
+ *   settles `error` with an `AgentError` coded `'WINDOW'` before the provider is called.
+ *   Default: `false`. The run continues over-window, or on `view()` after a selection fault.
  * - `select` — an optional default {@link SelectionHandler} forwarded to the agent's context; the
  *   active scope's `select` overrides it. The loop runs it at run entry and after each automatic
  *   compaction rebuild, emits each {@link Selection} it builds from on `select`, and charges the
@@ -830,12 +918,33 @@ export declare interface AgentOptions {
      * compaction fold, or a compaction rebuild.
      */
     readonly scope?: ScopeInterface;
-    /** Caps the tool-iteration turns before the loop stops. Default: `DEFAULT_AGENT_LIMIT`. */
+    /**
+     * Caps the tool-iteration turns before the loop stops, as a nonnegative safe integer.
+     * Thrown as an `AgentError` with code `'LIMIT'` when it is not. Default: `DEFAULT_AGENT_LIMIT`.
+     */
     readonly limit?: number;
     /** Sets a wall-clock deadline (ms) for the whole turn; its abort commits a partial result. */
     readonly timeout?: number;
-    /** Bounds the token cost; each provider call's usage is charged and its abort commits a partial. */
+    /**
+     * Bounds the token cost; each provider call's usage is charged and its abort commits a partial.
+     * A call that reports no usage charges the `budget` its streamed-answer estimate, unless the
+     * `allowance` is the `budget` and already charged it.
+     */
     readonly budget?: BudgetInterface<TokenUsage>;
+    /**
+     * Holds the meter layer's allowance: the token budget each content delta's mid-stream estimate is
+     * charged against, beside the reported usage the cost `budget` is reconciled to.
+     * The meter charges completion growth as `{ prompt: 0, completion: n, total: n }`, so a
+     * `completion`- or `total`-scoped allowance tracks the answer, while a `prompt`-scoped allowance
+     * is charged `0` and never trips through the meter. Its signal folds into the run's bound with
+     * the `budget`'s, so the estimate can stop a stream before the provider
+     * reports usage. Pass the `budget` itself to make the estimate and the reported usage share one
+     * ceiling; pass a separate budget with a smaller `max` to let the estimate stop the run first, or
+     * a larger one to let the reported usage or the model's own limit stop it instead. Cumulative
+     * across turns and runs, like the `budget`. Default: no meter layer; the estimate is still
+     * measured for the `usage` event and charges nothing mid-stream.
+     */
+    readonly allowance?: BudgetInterface<TokenUsage>;
     /** Paces the loop — the loop yields to it between turns so the host regains control. */
     readonly scheduler?: SchedulerInterface;
     /** Carries an external cancel; its abort commits a partial result. */
@@ -858,22 +967,34 @@ export declare interface AgentOptions {
      */
     readonly conversations?: ConversationManagerInterface;
     /**
-     * Holds an optional context {@link BudgetInterface} for automatic compaction. Its `consumer` is a
-     * token estimator (for example the exported {@link import('./helpers.js').estimateMessages}) and
-     * its `max` is the context window. When set, the loop measures the current full prompt (the
-     * next provider request) against this budget each turn; when that prompt reaches the window and
-     * the active conversation is summarizable, it **compacts the active conversation + continues on
-     * the rebuilt smaller view** (compact-and-continue) — the same consume-to-a-ceiling primitive
-     * as the cost `budget`, but compaction is the ceiling action instead of abort. Omit to disable.
-     */
-    readonly window?: BudgetInterface<readonly Message[]>;
+     * Holds an optional context {@link BudgetInterface} that admits each provider request. Its
+     * `consumer` is a token estimator over the complete {@link ProviderRequest} (for example the
+     * exported {@link import('./helpers.js').estimateRequest}) and its `max` is the context window.
+     * Before every provider dispatch the loop measures the exact request it will send: the messages
+     * after the provider's `replay` policy, the tools the turn advertises after the scope's
+     * allow-list, and the per-call `options` (`think`, `schema`). The budget is cleared, consumes that
+     * request, and the request is over the window when the budget is `exhausted`, which includes a
+     * request equal to `max`. When it is over and the active conversation is summarizable, the loop
+     * **compacts the active conversation once, rebuilds with the same tools and options, measures the
+     * rebuilt request, and dispatches it** (compact-and-continue) — the same consume-to-a-ceiling
+     * primitive as the cost `budget`, but compaction is the ceiling action instead of abort. A
+     * non-summarizable conversation is still measured, but cannot fold. After a run `consumed` holds
+     * the last measured request. With {@link AgentOptions.strict}, a request still over the window
+     * after the one permitted fold, or one that cannot fold, is refused before dispatch with an
+     * `AgentError` coded `'WINDOW'`. Omit to disable.
+     */
+    readonly window?: BudgetInterface<ProviderRequest>;
     /**
      * If `true`, a summarizer failure during automatic compaction emits `fault` and settles the
      * run `error`; a thrown selection handler, a returned selection `fault`, and a conversation
-     * changed during selection follow the same rule. If `false`, the run continues — over-window
-     * after a summarizer failure, and on the active conversation's `view()` after a selection
-     * fault. A cancel at a selection site, a `fault` listener's included, settles partial instead
-     * of `error`. Default: `false`.
+     * changed during selection follow the same rule. A request that the {@link AgentOptions.window}
+     * still finds over the window, equal to `max` included, after the one permitted fold, or that
+     * cannot fold, is refused before the provider is called: the run settles `error` with an
+     * `AgentError` coded `'WINDOW'` whose `context` holds the `agent`, the measured `consumed`, and
+     * the window `max`, and no `fault` fires for it. If `false`, the run continues — over-window
+     * after a summarizer failure or a futile fold, and on the active conversation's `view()` after a
+     * selection fault. A cancel at a selection site or a fold, a `fault` listener's included, settles
+     * partial instead of `error`. Default: `false`.
      */
     readonly strict?: boolean;
     /**
@@ -1058,7 +1179,8 @@ export declare interface AgentQueueOptions {
  *   the threaded `signal`; seed its context with the job's `messages`; return it. The
  *   `signal` is the queue attempt's / runner unit's cancel, so a bounded abort propagates
  *   into the agent (which commits a partial — the job's `partial` policy then
- *   decides success vs. retry).
+ *   decides success vs. retry). A job `limit` that is not a nonnegative safe integer throws an
+ *   {@link AgentError} carrying `code: 'LIMIT'` from the agent's construction.
  * - **Event-free.** A pure resolver — no Emitter, no events.
  *
  * @example
@@ -1140,7 +1262,7 @@ export declare interface AgentRegistryInterface {
      * @param input - The serializable {@link AgentJobInput} to rehydrate
      * @param signal - An optional cancel threaded into the agent (a queue / runner abort)
      * @returns The ready agent, its context seeded with the job's messages
-     * @throws {AgentError} Thrown when a referenced provider, tool, authority, or scheduler name is unregistered (`code: 'REGISTRY'`)
+     * @throws {AgentError} Thrown when a referenced provider, tool, authority, or scheduler name is unregistered (`code: 'REGISTRY'`), or when the job's `limit` is not a nonnegative safe integer (`code: 'LIMIT'`)
      */
     build(input: AgentJobInput, signal?: AbortSignal): AgentInterface;
 }
@@ -1191,7 +1313,10 @@ export declare interface AgentRegistryOptions {
  * it stays out of `content`. Each call's non-empty thinking is recorded on the assistant
  * message that call appends. The joined result also includes thinking from calls that appended
  * no message, such as an aborted call. Only recorded thinking can return to a provider,
- * as its `replay` policy allows.
+ * as its `replay` policy allows. A run stopped by the `meter` or `budget` layer settles
+ * `partial: true`. A `model` stop settles `partial: false`, because its answer is complete as the
+ * model ended it, unless that call's reconciled usage then exhausted a budget or a cancel landed
+ * before the run settled, which settles `partial: true` with that reason on the `abort` event.
  */
 export declare interface AgentResult {
     readonly content: string;
@@ -1209,6 +1334,13 @@ export declare interface AgentResult {
      * contains calls: those calls are dropped and observed through the `deny` event.
      */
     readonly partial: boolean;
+    /**
+     * Names the layer that stopped the run — the meter's estimate allowance, the cost budget, or the
+     * model's own token limit — with the readings it crossed. Absent when the run finished by
+     * itself, reached its `limit`, or was cancelled by a signal, a deadline, or `abort()` before the
+     * model ended its final answer.
+     */
+    readonly stop?: AgentStop;
 }
 
 /**
@@ -1223,8 +1355,11 @@ export declare interface AgentResult {
  * through Contract's sanctioned exception boundary, so conforming accessors and inherited
  * properties are supported while a throwing getter or revoked proxy returns `undefined`.
  * Present usage counts must be finite numbers; negative and fractional values are preserved,
- * not normalized. Extra input properties are dropped while a fresh exact plain object is rebuilt
- * and deep-gated through
+ * not normalized. The result is exact `{ content, thinking?, usage?, partial, stop? }`. A present
+ * `stop` is read once, then its `layer`, `id`, `max`, `consumed`, `estimate`, and `usage` once each
+ * in that order, `max` and `consumed` only on a `meter` or `budget` arm; the arm is rebuilt
+ * exactly, omitting absent readings, and a malformed `stop` refuses the whole value. Extra input
+ * properties are dropped while a fresh exact plain object is rebuilt and deep-gated through
  * {@link import('@orkestrel/contract').parseJSONValue}.
  *
  * @param value - The unknown value to project
@@ -1268,7 +1403,7 @@ export declare interface AgentRunnerOptions {
  * Every member is optional and resolved independently, so an omitted member leaves the
  * agent's constructed value in force and a caller that passes no options runs exactly the
  * agent it configured. `think` / `schema` ride through to the provider as
- * {@link ProviderStreamOptions}; `limit` / `timeout` / `budget` replace their construction
+ * {@link ProviderStreamOptions}; `limit` / `timeout` / `budget` / `allowance` replace their construction
  * defaults for this run only; `signal` composes with the constructed `signal` (both fold into
  * the run's bound abort) rather than replacing it. Nothing here mutates the agent — the next
  * run reads the construction defaults again.
@@ -1289,7 +1424,8 @@ export declare interface AgentRunOptions {
     readonly schema?: Readonly<Record<string, unknown>>;
     /**
      * Overrides {@link AgentOptions.limit} for this run only — the max tool-iteration turns
-     * before the loop stops. Omitted ⇒ the agent's constructed `limit` applies.
+     * before the loop stops, as a nonnegative safe integer; the call throws an `AgentError` with
+     * code `'LIMIT'` when it is not. Omitted ⇒ the agent's constructed `limit` applies.
      */
     readonly limit?: number;
     /**
@@ -1303,6 +1439,11 @@ export declare interface AgentRunOptions {
      * Omitted ⇒ the agent's constructed `budget` applies.
      */
     readonly budget?: BudgetInterface<TokenUsage>;
+    /**
+     * Overrides {@link AgentOptions.allowance} for this run only; started for this run with
+     * `start()`, as the constructed allowance is. Default: the agent's constructed `allowance`.
+     */
+    readonly allowance?: BudgetInterface<TokenUsage>;
     /**
      * Carries an additional per-run external cancel, composed with {@link AgentOptions.signal} (both
      * fold into the run's bound abort through `AbortSignal.any` — neither is dropped). Omitted ⇒
@@ -1322,7 +1463,8 @@ export declare interface AgentRunOptions {
  * a provider call or a selection reported it), `partial` is `true` when a cancel committed the run early or
  * when the loop exhausted its `limit` with unresolved tool intent, and `exhausted` is `true`
  * in that second case specifically (a distinct, non-cancel cause the {@link AgentEventMap}
- * `exhaust` event observes). It is the settled outcome one run returns, before the agent folds
+ * `exhaust` event observes), and `stop` the {@link AgentStop} of the layer that stopped the run
+ * (`undefined` when none did). It is the settled outcome one run returns, before the agent folds
  * it into the {@link AgentResult} resolved by the stream handle's `result` promise.
  */
 export declare interface AgentRunResult {
@@ -1331,6 +1473,7 @@ export declare interface AgentRunResult {
     readonly usage: TokenUsage | undefined;
     readonly partial: boolean;
     readonly exhausted: boolean;
+    readonly stop: AgentStop | undefined;
 }
 
 /**
@@ -1340,11 +1483,74 @@ export declare interface AgentRunResult {
  */
 export declare type AgentStatus = 'idle' | 'running' | 'done' | 'error';
 
+/**
+ * Represents why one of a run's three allowed failure layers stopped it — the meter's estimate
+ * allowance, the cost budget, or the model's own token limit — with the readings that layer crossed.
+ *
+ * @remarks
+ * `layer` names the failure point. A `meter` or `budget` stop copies the tripped budget's `id`, its
+ * `max`, and its `consumed` tally at the crossing from the `BudgetError` that aborted the run; a
+ * `meter` stop is a crossing of the run's `allowance`, a `budget` stop any other budget's, including
+ * a budget folded into an external signal or linked as the allowance's own parent signal. A `model`
+ * stop carries the provider instance's trace `id`, not the model's name: the provider reported that
+ * the model ended its answer at its own token limit, and the reason the wire gave is not carried
+ * beyond that. `estimate` is the token estimate of the answer the stopped provider call streamed,
+ * and `usage` the sanitized usage that call reported; each is present only when the stop landed on
+ * a provider call that produced it.
+ *
+ * @example
+ * ```ts
+ * const stop: AgentStop = { layer: 'meter', id: 'meter', max: 2_000, consumed: 2_001, estimate: 2_001 }
+ * ```
+ */
+export declare type AgentStop = {
+    readonly layer: 'meter' | 'budget';
+    readonly id: string;
+    readonly max: number;
+    readonly consumed: number;
+    readonly estimate?: number;
+    readonly usage?: TokenUsage;
+} | {
+    readonly layer: 'model';
+    readonly id: string;
+    readonly estimate?: number;
+    readonly usage?: TokenUsage;
+};
+
 /**
  * Names the agent turn's live handle carrying {@link AgentChunk} values and resolving an {@link AgentResult}.
  */
 export declare type AgentStreamInterface = StreamInterface<AgentChunk, AgentResult>;
 
+/**
+ * Holds what one agent loop turn contributed to its run and how the turn ended — the readonly
+ * record the loop appends for each turn, from which the run derives its {@link AgentRunResult}.
+ *
+ * @remarks
+ * `content` is the final answer on an `answer` turn and the content the provider streamed on any
+ * other turn. `thinking` and `usage` are this turn's own non-empty reasoning and sanitized usage;
+ * `spent` is the sanitized usage of a selection this turn's admission rebuilt through. `messages`
+ * is the working conversation the next turn starts from. `partial` is the run's partial flag if the
+ * run ends after this turn, and `futile` is the compaction latch after this turn's admission.
+ * `estimate` is the token estimate of the content this turn's call streamed, `undefined` on a turn
+ * a cancel stopped before its call. `interrupted` reports that the run's signal had aborted when
+ * this turn's call returned, before its usage was reconciled. `truncated` reports that the model
+ * ended this turn's final answer at its own token limit.
+ */
+export declare interface AgentTurn {
+    readonly content: string;
+    readonly thinking: string | undefined;
+    readonly usage: TokenUsage | undefined;
+    readonly spent: TokenUsage | undefined;
+    readonly messages: readonly Message[];
+    readonly ending: 'answer' | 'tools' | 'cancel';
+    readonly partial: boolean;
+    readonly futile: boolean;
+    readonly estimate: number | undefined;
+    readonly interrupted: boolean;
+    readonly truncated: boolean;
+}
+
 /**
  * Arms signal propagation to a byte reader and returns the controller that removes the listener.
  *
@@ -1362,22 +1568,23 @@ export declare type AgentStreamInterface = StreamInterface<AgentChunk, AgentResu
 export declare function armReaderAbort(reader: ReadableStreamDefaultReader<Uint8Array>, signal: AbortSignal | undefined): Promise<AbortController>;
 
 /**
- * Assembles the settled {@link AgentResult} from a run's {@link AgentRunResult} — `thinking` and
- * `usage` are carried only when the run surfaced them, and the loop-internal `exhausted` flag is
- * left out.
+ * Assembles the settled {@link AgentResult} from a run's {@link AgentRunResult} — `thinking`,
+ * `usage`, and `stop` are carried only when the run surfaced them, and the loop-internal
+ * `exhausted` flag is left out.
  *
  * @remarks
  * Pure and total. An absent optional is omitted rather than stored as `undefined` (the
  * present-when-given convention the message store follows), so a settled result JSON
- * round-trips without an explicit `undefined` field. `exhausted` is loop bookkeeping and does
- * not reach the public result — the `exhaust` event carries it instead.
+ * round-trips without an explicit `undefined` field. The keys follow `content`, `partial`,
+ * `thinking`, `usage`, then `stop`. `exhausted` is loop bookkeeping and does not reach the public
+ * result — the `exhaust` event carries it instead.
  *
  * @param outcome - The run's settled outcome
  * @returns The public {@link AgentResult}
  *
  * @example
  * ```ts
- * assembleResult({ content: 'hi', thinking: undefined, usage: undefined, partial: false, exhausted: false })
+ * assembleResult({ content: 'hi', thinking: undefined, usage: undefined, partial: false, exhausted: false, stop: undefined })
  * // { content: 'hi', partial: false }
  * ```
  */
@@ -1385,12 +1592,12 @@ export declare function assembleResult(outcome: AgentRunResult): AgentResult;
 
 /**
  * Copies a message with image data merged onto its `images` — the message's own images first,
- * then the attached data, carrying `calls` only when present and never mutating the original.
+ * then the attached data, keeping every other field and never mutating the original.
  *
  * @remarks
- * Pure and total: the original message is never mutated. `calls` is carried only when the
- * source message has one (kept omitted otherwise, mirroring the store's present-when-given
- * convention).
+ * Pure and total: the original message is never mutated. Every other field the source message
+ * carries (`calls`, `call`, `thinking`) is kept as given, and an absent one stays absent,
+ * mirroring the store's present-when-given convention.
  *
  * @param message - The message to copy (left unchanged)
  * @param payloads - The base64 image data to attach
@@ -1414,7 +1621,8 @@ export declare function attachImages(message: Message, payloads: readonly string
  * Pure and total: the conversation and its messages are never mutated, and the returned array
  * replaces exactly the one target message with the copy {@link attachImages} builds. Empty
  * data returns the conversation unchanged; a conversation with no user message returns it
- * unchanged too (there is nowhere to attach, and the images already rode the system block).
+ * unchanged too (there is nowhere to attach, and the images already rode the system block). A hole
+ * in a sparse conversation is not a user message.
  *
  * @param conversation - The messages to attach into (left unchanged)
  * @param payloads - The base64 image data to attach
@@ -1647,13 +1855,14 @@ export declare function buildProviderHeaders(hook: ProviderOptions['headers'], s
  * @param thinking - The joined reasoning
  * @param tools - The accumulated calls
  * @param usage - The reported token usage
+ * @param truncated - Whether the model stopped at its own limit, or undefined when the wire did not report it
  * @returns The assembled result
  * @example
  * ```ts
- * buildProviderResult('ok', '', [], undefined) // { content: 'ok' }
+ * buildProviderResult('ok', '', [], undefined, undefined) // { content: 'ok' }
  * ```
  */
-export declare function buildProviderResult(content: string, thinking: string, tools: readonly ToolCall[], usage: TokenUsage | undefined): ProviderResult;
+export declare function buildProviderResult(content: string, thinking: string, tools: readonly ToolCall[], usage: TokenUsage | undefined, truncated: boolean | undefined): ProviderResult;
 
 /**
  * Builds the placeholder assistant recall call used to price recall framing.
@@ -1734,8 +1943,8 @@ export declare function buildRecords(input: LedgerProjectionInput): LedgerProjec
  *
  * @remarks
  * Pure and total. This is the unframed form a `sections` cap merge digests when it folds the
- * oldest sections into one (a summary over their section summaries); the recap label is a
- * `view()` presentation concern kept out of what the summarizer re-reads — see
+ * oldest sections into one (a summary over their section summaries); the recap label is absent
+ * from that merge input. A rolling fold instead re-reads the framed recap — see
  * {@link buildRecapMessage}.
  *
  * @param section - The compacted section to render
@@ -1757,10 +1966,13 @@ export declare function buildSummaryMessage(section: Section): Message;
  * its `events` are drained.
  *
  * @remarks
- * The standard resolver-swap: a waiting `drain` parks on `#wake` (a void resolver);
- * `push` / `close` / `fail` enqueue/flag, then fire `#wake` so the parked reader wakes,
- * re-reads the buffer, and either yields the next chunk, returns (on `close`), or throws
- * (on `fail`). Event-free, no `!` / `as` / `any`.
+ * A waiting `drain` parks its void resolver in `#waiting`; `push` / `close` / `fail`
+ * enqueue/flag, then fire and clear every parked resolver, so each parked reader wakes,
+ * re-reads the shared buffer, and either takes the next chunk, returns (on `close`), throws
+ * (on `fail`), or parks again when another reader took the chunk first. Taking a chunk is
+ * synchronous, so each value reaches exactly one reader.
+ * A `return()` issued while a read is parked waits for the next `push`, `close`, or `fail`.
+ * The parked read takes a pushed value before that `return()` settles.
  *
  * @example
  * ```ts
@@ -1818,6 +2030,14 @@ export declare interface ChannelInterface<T> {
     /**
      * Reads the values back live, in write order — returning on `close` and throwing on `fail`.
      *
+     * @remarks
+     * Concurrent readers share one buffer: each value goes to exactly one reader, and `close` or
+     * `fail` ends every reader, parked or not, after the buffer empties. A `push` after `close` or
+     * `fail` is buffered rather than refused, so a reader still draining or a later `drain` yields
+     * it before reporting the end.
+     * A `return()` issued while a read is parked waits for the next `push`, `close`, or `fail`.
+     * The parked read takes a pushed value before that `return()` settles.
+     *
      * @returns A generator yielding each pushed value, returning on `close` and throwing on `fail`
      */
     drain(): AsyncGenerator<T, void>;
@@ -1825,11 +2045,12 @@ export declare interface ChannelInterface<T> {
 
 /**
  * Consumes a reported usage against a budget over what was already charged, so a turn's total
- * draw matches the report and nothing is charged twice.
+ * draw is never less than the report and nothing is charged twice.
  *
  * @remarks
  * The full `prompt` count is consumed because no earlier charge covers it. Each of `completion`
- * and `total` is consumed less `charged`, floored at 0. The usage must already be sanitized: a
+ * and `total` is consumed less `charged`, floored at 0. An estimate above the report is not
+ * refunded. The usage must already be sanitized: a
  * non-finite field yields a non-finite charge, which the installed `Budget` refuses by throwing
  * a `range` `ContractError`. Without a budget the call consumes nothing.
  *
@@ -1883,7 +2104,7 @@ export declare class Classifier implements ClassifierInterface {
      * Asks the judge every question the filing still lacks, in the measured order.
      * @param requests - The request ids, which skip category questions and receive only enabled request-topic questions
      * @param signal - The caller's signal; an abort returns a fault with completed judgments and usage
-     * @returns The judgment keys and summed usage; a throw from the assign or entities handler, or a caller abort, returns the partial result with `fault`; a judge rejection under a live signal leaves that question undecided and sets no `fault`
+     * @returns The judgment keys, summed usage, and one reading per logical question attempt, in asking order; a throw from the assign or entities handler, or a caller abort, returns the partial result with `fault`; a judge rejection under a live signal leaves that question undecided and sets no `fault`
      */
     classify(requests: ReadonlySet<string>, signal: AbortSignal): Promise<ClassifierResult>;
     /**
@@ -1930,7 +2151,7 @@ export declare interface ClassifierInterface {
      *
      * @param requests - The request ids, which skip category questions and receive only enabled request-topic questions
      * @param signal - The signal that aborts the questions; completed judgments stay recorded
-     * @returns The judgment keys and usage spent; a throw from the assign or entities handler, or a caller abort, returns the partial result with `fault`; a judge rejection under a live signal leaves that question undecided and sets no `fault`
+     * @returns The judgment keys, usage spent, and one reading per logical question attempt; a throw from the assign or entities handler, or a caller abort, returns the partial result with `fault`; a judge rejection under a live signal leaves that question undecided and sets no `fault`
      */
     classify(requests: ReadonlySet<string>, signal: AbortSignal): Promise<ClassifierResult>;
     /**
@@ -1987,14 +2208,66 @@ export declare interface ClassifierOptions {
     readonly entities: LedgerEntityHandler;
 }
 
-/** Carries the judgment keys one classification rests on and the judge usage it spent. */
+/**
+ * Names what became of one filing question.
+ *
+ * @remarks
+ * `cached` means the conversation already held a matching judgment, so the classifier did not call the judgment manager.
+ * `skipped` means the classifier held the question after a deterministic failure and did not call the judgment manager.
+ * `resolved` means the judgment manager's resolve call fulfilled. `failed` means it rejected while the caller's signal was live.
+ * `aborted` means it rejected with a `JudgeAbortError` or after the caller's signal aborted.
+ */
+export declare type ClassifierOutcome = 'cached' | 'skipped' | 'resolved' | 'failed' | 'aborted';
+
+/** Names the filing question a classifier asked: a message's category, a message's topic, or an earlier and later message's amendment or supersession. */
+export declare type ClassifierPhase = 'category' | 'topic' | 'amends' | 'supersedes';
+
+/**
+ * Carries what became of one filing question: its judgment key, its phase, its outcome, and the time spent resolving it.
+ *
+ * @remarks
+ * `key` is the judgment key the classifier asked or reused. `duration` is the monotonic milliseconds
+ * the classifier waited on the judgment manager's resolve call, present for `resolved`, `failed`, and `aborted`
+ * and absent for `cached` and `skipped`, which make no resolve call. A reading counts one logical
+ * question attempt. It counts neither the physical wire calls a judge made nor a request that joined
+ * another pending request, and a question the caller's signal aborted before its resolve call began
+ * has no reading.
+ */
+export declare interface ClassifierReading {
+    readonly key: string;
+    readonly phase: ClassifierPhase;
+    readonly outcome: ClassifierOutcome;
+    readonly duration?: number;
+}
+
+/**
+ * Carries the judgment keys one classification rests on and the judge usage it spent.
+ *
+ * @remarks
+ * `readings` lists one {@link ClassifierReading} per logical question attempt, in asking order, including
+ * the attempt a caller abort interrupted. Each result owns its array.
+ */
 export declare interface ClassifierResult {
     readonly judgments: readonly string[];
     readonly usage?: TokenUsage;
+    readonly readings: readonly ClassifierReading[];
     /** Holds the error when an assign or entities handler throw, or a caller abort, interrupts classification; judgments and usage retain the partial result. A judge rejection under a live signal sets no fault. */
     readonly fault?: Error;
 }
 
+/**
+ * Carries the optional cause and context an error class with a machine-readable `code` takes at
+ * construction.
+ *
+ * @remarks
+ * `cause` holds the underlying failure. `context` holds the values that locate the failure, such
+ * as the category and name of a missing entry.
+ */
+export declare interface CodedErrorOptions {
+    readonly cause?: unknown;
+    readonly context?: Readonly<Record<string, unknown>>;
+}
+
 /**
  * Collects whole exchanges, joining every exchange spanned by a tool group.
  *
@@ -2041,7 +2314,8 @@ export declare function collectImageData(files: readonly FileInterface[]): reado
  * A message is live when it is a user message, or a tool message whose reading is the last reading of its
  * call, and the input neither excludes it nor files it quiet or replaced. A reading replaces any
  * earlier reading of the same call, an empty one included, so an empty lookup leaves the earlier
- * result out of every record.
+ * result out of every record. A reading with no canonical identity stays live as its own source
+ * and participates in no replacement.
  *
  * @param input - The messages, readings, and classification to read
  * @returns The live message ids
@@ -2157,13 +2431,21 @@ export declare function collectToolGroups(messages: readonly Message[]): Readonl
  * `DEFAULT_CONVERSATION_KEEP`). `sections` overrides the configured `sections` cap of the
  * conversation for this compaction only — after the folded section is appended, an overflow past
  * `sections` folds the oldest sections into one merged section. Default: the cap of the
- * conversation (or no cap).
+ * conversation (or no cap). `keep` must be a nonnegative safe integer; any other value throws a
+ * {@link import('./errors.js').ConversationError} with code `'KEEP'`. A `sections` cap on a
+ * rolling conversation throws code `'SECTIONS'`. `signal` cancels this
+ * compaction: an already-aborted signal rejects with its reason before the summarizer is called,
+ * the signal is passed to the {@link ConversationSummaryHandler}, and an abort while the
+ * summarizer runs rejects with the reason at once and commits nothing after the abort. A fold
+ * committed before an aborted overflow merge stays. Default: no signal.
  */
 export declare interface CompactOptions {
     /** Overrides the retained-tail size for this compaction. Default: the `keep` of the conversation. */
     readonly keep?: number;
     /** Overrides the `sections` cap for this compaction. Default: the cap of the conversation (or no cap). */
     readonly sections?: number;
+    /** Cancels this compaction and is passed to the summarizer. Default: no signal. */
+    readonly signal?: AbortSignal;
 }
 
 /**
@@ -2278,7 +2560,14 @@ export declare interface ContextSectionFormat<T> {
  *   exchanges. A cut inside an assistant call group, which only a group spanning two exchanges
  *   allows, moves before the group, so a tool result never stays live without its call. Returns
  *   the section, or `undefined` when nothing folds. A {@link ConversationError} is thrown when no
- *   `#summarize` was supplied.
+ *   `#summarize` was supplied. Calls run one at a time, a fold commits only when its messages are
+ *   still the live entries after the summarizer settles, and `options.signal` rejects the call
+ *   with its reason at once and commits nothing after the abort.
+ * - **Rolling.** With `rolling`, a fold makes one summarizer call over the framed recaps of all
+ *   prior sections then the slice, and replaces those sections with one that retains their
+ *   originals then the slice. It emits `compact` once and never `collapse`, commits nothing when
+ *   the call throws, aborts, or the slice or prior sections changed, and cannot combine with a
+ *   `sections` cap (`'SECTIONS'`).
  * - **`rehydrate(id)` / `search(query)`.** `rehydrate` returns the full original messages of a
  *   known section and emits its `id` through `rehydrate`, even when the list is empty. An unknown
  *   id returns `undefined` without an event. The read never reinserts messages. `search` is a case-insensitive
@@ -2344,9 +2633,10 @@ export declare const CONVERSATION_RECAP_PREFIX = "[Summary of earlier messages]
 
 /**
  * Reports a conversation with no {@link ConversationSummaryHandler} to fold its messages with, a
- * `sections` cap below `1`, or a judgment or judge request that JSON cannot carry — thrown by the
- * `compact()` method of a {@link ConversationInterface}, its construction, or its judgment store,
- * carrying the machine-readable `code` `'SUMMARIZER' | 'SECTIONS' | 'JUDGMENT'`.
+ * `sections` cap below `1`, a `keep` that is not a nonnegative safe integer, or a judgment or
+ * judge request that JSON cannot carry — thrown by the `compact()` method of a
+ * {@link ConversationInterface}, its construction, or its judgment store, carrying the
+ * machine-readable `code` `'SUMMARIZER' | 'SECTIONS' | 'JUDGMENT' | 'KEEP'`.
  *
  * @remarks
  * Compaction requires a summarizer (it digests the folded slice into a section summary); a
@@ -2354,18 +2644,40 @@ export declare const CONVERSATION_RECAP_PREFIX = "[Summary of earlier messages]
  * is a programmer error and throws this with `'SUMMARIZER'`.
  * A `sections` cap (on {@link import('./types.js').ConversationOptions} /
  * {@link import('./types.js').ConversationManagerOptions} /
- * {@link import('./types.js').CompactOptions}) must be `>= 1` — a sub-1 cap is a programmer
- * error and throws this with `'SECTIONS'`. A judgment record or a judge request that JSON cannot
- * carry, or whose copy fails its guard, is a programmer error and throws this with `'JUDGMENT'`.
- * Narrow a caught value with
- * {@link isConversationError} and branch on `error.code`.
+ * {@link import('./types.js').CompactOptions}) must be `>= 1`, and cannot combine with
+ * `rolling` — either is a programmer error and throws this with `'SECTIONS'`. A `keep` on the same options must be a nonnegative
+ * safe integer — any other value is a programmer error and throws this with `'KEEP'`. A judgment
+ * record or a judge request that JSON cannot carry, or whose copy fails its guard, is a
+ * programmer error and throws this with `'JUDGMENT'`, its `context` naming the `question` id
+ * where one exists. Narrow a caught value with {@link isConversationError} and branch on
+ * `error.code`.
  */
 export declare class ConversationError extends Error {
-    /** Names the machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer; `'SECTIONS'`: a sub-1 `sections` cap; `'JUDGMENT'`: a judgment or judge request that is not JSON. */
-    readonly code: 'SUMMARIZER' | 'SECTIONS' | 'JUDGMENT';
-    constructor(code: 'SUMMARIZER' | 'SECTIONS' | 'JUDGMENT', message: string);
+    /** Names the machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer; `'SECTIONS'`: a sub-1 `sections` cap, or a cap combined with `rolling`; `'JUDGMENT'`: a judgment or judge request that is not JSON; `'KEEP'`: a `keep` that is not a nonnegative safe integer. */
+    readonly code: ConversationErrorCode;
+    /** Holds the values that locate the failure, such as the `question` id of a malformed question, or `undefined` when none were supplied. */
+    readonly context: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * Creates the error with its code, message, and optional cause and context.
+     *
+     * @param code - The machine-readable {@link ConversationErrorCode}
+     * @param message - The human-readable description
+     * @param options - The optional {@link CodedErrorOptions}; `cause` reaches `Error.cause` only when present
+     */
+    constructor(code: ConversationErrorCode, message: string, options?: CodedErrorOptions);
 }
 
+/**
+ * Names the machine-readable condition a {@link import('./errors.js').ConversationError} reports.
+ *
+ * @remarks
+ * `'SUMMARIZER'`: a `compact()` with no summarizer. `'SECTIONS'`: a `sections` cap below `1`, or
+ * any `sections` cap combined with `rolling`.
+ * `'JUDGMENT'`: a judgment or judge request that JSON cannot carry, or whose copy fails its guard.
+ * `'KEEP'`: a `keep` that is not a nonnegative safe integer.
+ */
+export declare type ConversationErrorCode = 'SUMMARIZER' | 'SECTIONS' | 'JUDGMENT' | 'KEEP';
+
 /**
  * Maps the push observation surface of a {@link ConversationInterface} — the compaction
  * moments a fire-and-forget observer subscribes to through `conversation.emitter.on`.
@@ -2395,15 +2707,18 @@ export declare type ConversationEventMap = {
 /**
  * Carries the data to author a {@link ConversationInterface} through a {@link
  * ConversationManagerInterface} — the optional `id`, a `summarize` override, a `keep` override, a
- * `sections` cap override, the reserved `on` hooks, and a {@link ConversationSnapshot} to hydrate
- * from.
+ * `sections` cap override, the `rolling` switch, the reserved `on` hooks, and a
+ * {@link ConversationSnapshot} to hydrate from.
  *
  * @remarks
  * `id` is the identity of the conversation. Default: a minted id. `summarize` overrides the
  * default {@link ConversationSummaryHandler} of the manager for this conversation. Default: the
  * manager default. `keep` overrides the default retained-tail size of the manager. `sections`
- * overrides the default `sections` cap of the manager. `on` is the reserved listener key
- * (initial {@link ConversationEventMap} listeners). `snapshot` is the construction-time hydration
+ * overrides the default `sections` cap of the manager. `rolling` switches on rolling folds; a
+ * manager `sections` default it would inherit throws `'SECTIONS'`. `on` is the reserved listener key
+ * (initial {@link ConversationEventMap} listeners). `error` is the listener-error handler of the
+ * conversation's emitter, so a throwing `on` listener reports there. Default: the emitter's own
+ * handler. `snapshot` is the construction-time hydration
  * seam — a {@link ConversationSnapshot} whose `id` / `sections` / live tail are restored into the
  * conversation (the live `summarize` / `keep` / `on` re-supplied alongside it), the conversation
  * analogue of the `seed` option of {@link import('@orkestrel/workspace').WorkspaceOptions},
@@ -2420,7 +2735,11 @@ export declare interface ConversationInput {
     readonly keep?: number;
     /** Overrides the default `sections` cap of the manager for this conversation. */
     readonly sections?: number;
+    /** Rolls every fold of this conversation into one section, passed on as {@link ConversationOptions.rolling}. Default: `false`; the manager holds no default. */
+    readonly rolling?: boolean;
     readonly on?: EmitterHooks<ConversationEventMap>;
+    /** Holds the listener-error handler of the conversation's emitter — a listener throw routes here, not to a domain event. */
+    readonly error?: EmitterErrorHandler;
     /** Hydrates from a {@link ConversationSnapshot}, passed on as {@link ConversationOptions.snapshot}. */
     readonly snapshot?: ConversationSnapshot;
 }
@@ -2455,10 +2774,11 @@ export declare interface ConversationInput {
  *   thrown when no `summarize` was supplied.
  * - **`summarizable` — whether a `compact()` can fold.** `true` when a
  *   {@link ConversationSummaryHandler} was supplied, `false` otherwise. The automatic compaction
- *   of the agent loop (`AgentOptions.window`) gates on it so a conversation that has no
+ *   of the agent loop (`AgentOptions.window`) gates its fold on it so a conversation that has no
  *   summarizer is never auto-compacted (and the loop never throws the `compact()` `SUMMARIZER`
- *   error from the auto path). A manual `compact()` still throws without a summarizer — only the
- *   auto path is guarded.
+ *   error from the auto path); the loop still measures its requests against the window, and a
+ *   strict agent refuses one that is over. A manual `compact()` still throws without a summarizer
+ *   — only the auto path is guarded.
  * - **`rehydrate(id)` / `search(query)` — read the retained originals.** `rehydrate` returns
  *   the full original messages of a known section and emits its `id` through `rehydrate`, even
  *   when the list is empty. An unknown id returns `undefined` without an event. The read never
@@ -2483,9 +2803,10 @@ export declare interface ConversationInterface {
     readonly sections: readonly Section[];
     /**
      * Reports whether a `compact()` can fold — `true` when a {@link ConversationSummaryHandler} was supplied.
-     * The automatic compaction of the agent loop (`AgentOptions.window`) gates on it (a
+     * The automatic compaction of the agent loop (`AgentOptions.window`) gates its fold on it (a
      * non-summarizable conversation is never auto-compacted, so the auto path never throws the
-     * `SUMMARIZER` error); a manual `compact()` still throws without a summarizer.
+     * `SUMMARIZER` error, though its requests are still measured); a manual `compact()` still throws
+     * without a summarizer.
      */
     readonly summarizable: boolean;
     /** Counts the live (uncompacted) messages stored in the tail. */
@@ -2549,16 +2870,46 @@ export declare interface ConversationInterface {
      * a group moves before its assistant message, then back to whole exchanges again. Only a group
      * that spans two exchanges reaches that rule.
      *
+     * A rolling conversation makes one summarizer call per fold, over the framed recaps of every
+     * prior section followed by the slice with thinking stripped; the originals behind the recaps
+     * are not sent. After the call settles, the slice and the prior sections must be unchanged; the
+     * prior sections are then replaced atomically by one section retaining their originals in order
+     * and then the slice, and the slice leaves the live tail. It emits `compact` once and never
+     * `collapse`. A throw, an abort, or a changed input commits nothing. A fold with no eligible
+     * slice makes no call. A `sections` cap, configured or supplied here, throws `'SECTIONS'`.
+     *
      * When a `sections` cap is set and the fold pushes the section count over it, an overflow
      * merge step folds the oldest sections into one. If the `summarize` call of that merge throws,
      * the merge is skipped (sections transiently sit at `cap + 1`, no loss), no `compact` is
      * emitted, and the error propagates; the next successful `compact()` merges the section count
      * back to `cap`.
      *
-     * @param options - Optional {@link CompactOptions} (`keep` overrides the retained-tail size)
-     * @returns The folded {@link Section}, or `undefined` when nothing folded
-     * @throws ConversationError Thrown when no summarizer was supplied, or when the effective
-     * sections cap does not satisfy `>= 1` (code `'SECTIONS'`, including `NaN`)
+     * Calls run one at a time: a call made while another is in flight waits for it, then computes
+     * its own fold from the live tail it finds. A fold commits only when every folded message is
+     * still the same live entry after the summarizer settles, and a merge commits only when the
+     * folded sections are still the oldest; otherwise the call resolves `undefined` and emits
+     * nothing, so a `remove` or `clear` during the summarizer leaves no section.
+     *
+     * A summarizer must not call `compact` on the conversation it serves. A call that finds no fold in
+     * flight calls its summarizer before its own fold counts as in flight, so that summarizer's own
+     * `compact` finds nothing to wait for and summarizes the same slice again; the commit check above
+     * keeps one section, because the later fold finds its slice already folded and resolves
+     * `undefined`. A call queued behind an earlier fold counts as in flight before its summarizer
+     * runs, so its summarizer's own `compact` waits for the fold that called it.
+     *
+     * `options.signal` cancels the call. An already-aborted signal rejects with its reason before
+     * the summarizer is called. An abort while waiting for an earlier call or while the summarizer
+     * runs rejects with the reason at once, even when the summarizer ignores the signal, and the
+     * call commits nothing afterwards; a fold committed before an aborted merge stays, as when the
+     * merge throws.
+     *
+     * @param options - Optional {@link CompactOptions} (`keep`, `sections`, `signal`)
+     * @returns The folded {@link Section}, or `undefined` when nothing folded or the folded
+     * messages or sections changed while the summarizer ran
+     * @throws ConversationError Thrown when no summarizer was supplied (code `'SUMMARIZER'`), when the
+     * effective sections cap does not satisfy `>= 1` or combines with `rolling` (code `'SECTIONS'`,
+     * including `NaN`), or when
+     * the effective `keep` is not a nonnegative safe integer (code `'KEEP'`)
      */
     compact(options?: CompactOptions): Promise<Section | undefined>;
     /**
@@ -2750,7 +3101,11 @@ export declare interface ConversationManagerInterface {
      *   into a fresh {@link ConversationInterface} through the `snapshot` option
      *   (`add({ snapshot, ... })`, flowing the default `summarize` / `keep` of the manager in),
      *   which registers and activates it, and it is returned.
-     * - Else (no store, or a store miss) ⇒ `undefined` (lenient — no throw).
+     * - A conversation registered under `id` while the store read was pending wins: it is
+     *   activated and returned, and the stored snapshot is discarded. So a concurrent `add({ id })`
+     *   keeps its turns, and concurrent `open(id)` calls return the one registered instance.
+     * - Else (no store, a store miss, or a stored snapshot whose `id` is not `id`) ⇒ `undefined`
+     *   (lenient — no throw).
      *
      * @param id - The conversation id to open
      * @returns The activated {@link ConversationInterface}, or `undefined` when neither registered nor stored
@@ -2759,12 +3114,12 @@ export declare interface ConversationManagerInterface {
     /**
      * Persists a registered conversation's {@link ConversationInterface.snapshot} to the optional
      * {@link ConversationStoreInterface} (`store`) — `true` when persisted, `false` when there is
-     * no store or the id is unknown, and never throwing.
+     * no store or the id is unknown; a store failure propagates.
      *
      * @remarks
      * Lenient: when a `store` is set and `id` is registered, `store.set(conversation.snapshot())` is
      * awaited and `true` is returned; otherwise (no store, or an unknown id) it is a no-op returning
-     * `false` — never a throw, consistent with the lenient `switch`.
+     * `false`. A failure from `store.set` propagates.
      *
      * @param id - The id of the registered conversation to persist
      * @returns True if the snapshot was persisted; false otherwise (no store, or an unknown id)
@@ -2792,7 +3147,8 @@ export declare interface ConversationManagerInterface {
  * `summarize` is the default summarizer flowed into every conversation the manager creates
  * (a per-`add` {@link ConversationInput.summarize} overrides it); a conversation created
  * with neither cannot `compact` (it throws a `ConversationError`). `keep` is the default
- * retained-tail size (a per-`add` {@link ConversationInput.keep} overrides it). Default:
+ * retained-tail size (a per-`add` {@link ConversationInput.keep} overrides it); it must be a
+ * nonnegative safe integer, else construction throws a `ConversationError` with code `'KEEP'`. Default:
  * {@link import('./constants.js').DEFAULT_CONVERSATION_KEEP}. `sections` is the default cap
  * on the compacted `sections` list of a created conversation (a per-`add`
  * {@link ConversationInput.sections} overrides it). Default: no cap.
@@ -2826,13 +3182,18 @@ export declare interface ConversationManagerOptions {
  * {@link ConversationSummaryHandler} compaction needs — without it `compact()` throws a
  * {@link import('./errors.js').ConversationError} (a conversation can still store + view a
  * live tail; it cannot fold). `keep` is how many recent live messages a `compact()`
- * retains verbatim (folding only the older ones). Default:
- * {@link import('./constants.js').DEFAULT_CONVERSATION_KEEP} (`0` — a manual `compact()`
+ * retains verbatim (folding only the older ones); it must be a nonnegative safe integer, else
+ * construction throws a {@link import('./errors.js').ConversationError} with code `'KEEP'`.
+ * Default: {@link import('./constants.js').DEFAULT_CONVERSATION_KEEP} (`0` — a manual `compact()`
  * folds every exchange before the newest user message into one section). `sections` is an
  * optional cap on the compacted `sections` list — when set (`>= 1`), a `compact()` that would
  * leave more than `sections` entries folds the oldest overflow into one merged section,
  * emitting `collapse`. A successful capped merge retains at most `Math.ceil(sections)` entries;
- * fractions and positive infinity are accepted. Default: no cap.
+ * fractions and positive infinity are accepted. Default: no cap. `rolling` makes each `compact()`
+ * one summarizer call over the framed recaps of every prior section then the slice, replacing all
+ * prior sections with one that retains their originals then the slice, with one `compact` event
+ * and no `collapse`; it cannot combine with `sections`, which throws a `ConversationError` with
+ * code `'SECTIONS'`. Default: `false`.
  * `snapshot` is the hydration seam — a {@link ConversationSnapshot} whose `id`, compacted
  * `sections`, and live tail are restored into the conversation, with the live `summarize` /
  * `keep` / `on` supplied alongside it (a summarizer is a function, not serialized data).
@@ -2851,6 +3212,13 @@ export declare interface ConversationOptions {
     readonly keep?: number;
     /** Caps the compacted `sections` list (`>= 1`); overflow folds into one merged section. Default: no cap. */
     readonly sections?: number;
+    /**
+     * Rolls every fold into one section: the summarizer digests the framed recaps of all prior
+     * sections followed by the slice, and one section retaining their originals then the slice
+     * replaces them. Combining it with a `sections` cap throws a `ConversationError` (`'SECTIONS'`).
+     * Default: `false`.
+     */
+    readonly rolling?: boolean;
     /** Hydrates from a {@link ConversationSnapshot} — its `id` wins over `id`; restoring is silent. */
     readonly snapshot?: ConversationSnapshot;
 }
@@ -2995,10 +3363,16 @@ export declare interface ConversationStoreInterface {
  * The core conversation layer treats it as an opaque async function — it never reads which
  * backend produced the digest, keeping `core` free of any provider coupling.
  *
+ * `signal` is the {@link CompactOptions.signal} of the `compact()` call the fold serves, or
+ * `undefined` when that call supplied none. A summarizer must stop its work when it aborts. One
+ * that ignores it still cannot hold the caller: `compact()` races the summarizer against the
+ * signal, rejects with the abort reason, and discards a digest that arrives later.
+ *
  * @param messages - The folded messages to digest into a summary
+ * @param signal - The cancellation signal of the `compact()` call, or `undefined` when it supplied none
  * @returns The summary text (the model-written digest of those messages)
  */
-export declare type ConversationSummaryHandler = (messages: readonly Message[]) => Promise<string>;
+export declare type ConversationSummaryHandler = (messages: readonly Message[], signal?: AbortSignal) => Promise<string>;
 
 /**
  * Owns a value by serializing it to JSON and parsing the text, so the copy shares nothing with its source.
@@ -3025,9 +3399,9 @@ export declare function copyJSON(value: unknown): unknown;
  * `generate` and a live `stream`.
  *
  * @remarks
- * One private loop drives the turn; `generate` drains the same stream `stream`
- * exposes, so they can never diverge. Each turn is bounded by one cancel folded from
- * `signal` + `timeout` + `budget` (through `AbortSignal.any`) — any trip (or `abort()`)
+ * One private loop drives the turn; `generate` awaits the settled result of the same run
+ * `stream` exposes and leaves its live chunks undrained, so they can never diverge. Each turn is bounded by one cancel folded from
+ * `signal` + `timeout` + `budget` + `allowance` (through `AbortSignal.any`) — any trip (or `abort()`)
  * commits a partial result (the stream's `result` resolves on a cancel, rejects only
  * on a genuine provider / tool error). The `scheduler` paces between turns; tool
  * iteration is capped at `limit`. Default: `DEFAULT_AGENT_LIMIT`. Tools are advertised
@@ -3072,15 +3446,18 @@ export declare function createAgent(provider: ProviderInterface, options?: Agent
  * `system` is the optional system prompt; `tools` / `instructions` / `workspaces` are pre-built
  * managers to reuse (empty ones are created when omitted, so `context.workspaces` is always
  * present); `scope` is the initial active filter (`undefined` ⇒ no filtering, changeable afterwards
- * through `context.apply(...)`). The `messages` store is always fresh. `build()` folds the scoped
- * instructions — plus the active workspace's scope-filtered text files (fenced) — into one leading
- * `system` message and appends the scoped conversation (attaching the active workspace's
- * scope-filtered image files' `base64` payload to the last user message), built fresh each call; the active
- * workspace is the sole document/image context. Tools are advertised structurally (through
+ * through `context.apply(...)`). `conversations` is the message source: a supplied manager's
+ * active conversation is reused as `messages`, and a default conversation is added only when it
+ * has none (a fresh registry with one default conversation is created when omitted). `build()`
+ * folds the scoped instructions — plus the active workspace's scope-filtered text files (fenced) —
+ * into one leading `system` message and appends the active conversation's `view()` (attaching the
+ * active workspace's scope-filtered image files' `base64` payload to the last user message), built
+ * fresh each call; the scope never filters the conversation. The active workspace is the sole
+ * document/image context. Tools are advertised structurally (through
  * `tools.definitions()`, scope-filtered by the loop), never serialized into the prompt.
  *
- * @param options - Optional `system` / `tools` / `instructions` / `workspaces` / `scope`
- *   (see {@link AgentContextOptions})
+ * @param options - Optional `system` / `tools` / `instructions` / `workspaces` /
+ *   `conversations` / `scope` / `select` (see {@link AgentContextOptions})
  * @returns A working {@link AgentContextInterface}
  *
  * @example
@@ -3107,9 +3484,10 @@ export declare function createAgentContext(options?: AgentContextOptions): Agent
  *   through `store` (+ `restore()` after a crash) are all the backing Queue's. `enqueue`
  *   returns a per-job promise.
  * - **Durable + serializable.** Because `AgentJobInput` is JSON-serializable, a `store`
- *   (for example `createMemoryQueueStore` / `createDatabaseQueueStore`) persists outstanding
- *   jobs; `restore()` re-enqueues them after a restart and the `registry` rehydrates the
- *   live pieces from the names — so a job survives a crash.
+ *   persists outstanding jobs; `restore()` re-enqueues them and the `registry` rehydrates the
+ *   live pieces from the names. A job survives a crash only through a store whose rows outlive
+ *   the process (for example `createDatabaseQueueStore`); a `createMemoryQueueStore` row is
+ *   gone when the process exits.
  * - **Partial policy.** A partial result throws an
  *   {@link import('./errors.js').AgentJobError} by default, so a job cancelled by its
  *   attempt deadline / a queue abort retries while attempts remain; `partial: true`
@@ -3124,11 +3502,13 @@ export declare function createAgentContext(options?: AgentContextOptions): Agent
  *
  * @example
  * ```ts
+ * import type { AgentJobInput, ProviderInterface } from '@orkestrel/agent'
+ * import type { QueueStoreInterface } from '@orkestrel/queue'
  * import { createAgentQueue, createAgentRegistry } from '@orkestrel/agent'
- * import { createMemoryQueueStore } from '@orkestrel/queue'
  *
+ * declare const provider: ProviderInterface // any concrete implementation supplied by the host app
+ * declare const store: QueueStoreInterface<AgentJobInput> // a durable store the host supplies
  * const registry = createAgentRegistry({ providers: { main: provider } })
- * const store = createMemoryQueueStore(agentJobShape) // survives a restart through restore()
  * const queue = createAgentQueue({ registry, concurrency: 2, retries: 1, store })
  * const result = await queue.enqueue({ provider: 'main', messages: [{ role: 'user', content: 'ok?' }] })
  * ```
@@ -3179,7 +3559,9 @@ export declare function createAgentRegistry(options: AgentRegistryOptions): Agen
  *   the handler adds only rehydration + the partial policy.
  * - **Sub-agent fan-out.** Each unit's handler receives a `ControllerInterface` whose
  *   `spawn(childJob)` launches a child agent job through the same bounded queue (the
- *   child's result joins the run after the declared units, in spawn order). On a bounded
+ *   child's result joins the run after the declared units, in spawn order). A unit spawns its
+ *   declared `children` on its first attempt only, so a retried parent never runs a child
+ *   twice. On a bounded
  *   runner, fan out and return — do not await a spawn inline from within the handler (a
  *   slot-holding handler awaiting its own spawn can deadlock; see `ControllerInterface`).
  * - **Partial policy + cancellation.** Same as `createAgentQueue`: a partial result
@@ -3294,14 +3676,14 @@ export declare function createChannel<T>(): ChannelInterface<T>;
  * // Append the instruction as the FINAL user turn: a chat model emits nothing when the prompt
  * // ends on an assistant turn, so a leading-system instruction is unreliable.
  * const conversation = createConversation({
- * 	summarize: async (messages) =>
+ * 	summarize: async (messages, signal) =>
  * 		(
  * 			await provider.generate(
  * 				[
  * 					...messages,
  * 					{ id: 's', role: 'user', content: 'Summarize the conversation so far concisely.' },
  * 				],
- * 				AbortSignal.timeout(30_000),
+ * 				signal ?? AbortSignal.timeout(30_000), // the compact() call's signal, when it passed one
  * 			)
  * 		).content,
  * 	keep: 2, // retain at least the 2 most recent messages verbatim on each compaction
@@ -3541,7 +3923,8 @@ export declare function createRelay(options: RelayOptions): RelayHandler;
  * is the server half this one pairs with.
  *
  * @param options - The endpoint, parser factory, and HTTP call configuration
- * @returns The concrete relay provider
+ * @returns The relay provider behind the shared provider interface; construct
+ * {@link RelayProvider} directly to reach its wire seams
  * @example Reaching the relay from the browser
  * ```ts
  * import type { ProviderInterface, ProviderParserInterface } from '@orkestrel/agent'
@@ -3555,14 +3938,13 @@ export declare function createRelay(options: RelayOptions): RelayHandler;
  * 		this.#pending += chunk
  * 		const lines = this.#pending.split(/\r\n|\n/)
  * 		this.#pending = lines.pop() ?? ''
- * 		const records: Array<Readonly<Record<string, unknown>>> = []
- * 		for (const line of lines) {
- * 			if (line.trim().length === 0) continue
- * 			const record = parseJSONAs(line, isRecord)
- * 			if (record === undefined) throw new ProviderError('PROTOCOL', 'invalid JSON record')
- * 			records.push(record)
- * 		}
- * 		return records
+ * 		return lines
+ * 			.filter((line) => line.trim().length > 0)
+ * 			.map((line) => {
+ * 				const record = parseJSONAs(line, isRecord)
+ * 				if (record === undefined) throw new ProviderError('PROTOCOL', 'invalid JSON record')
+ * 				return record
+ * 			})
  * 	}
  * 	clear(): void {
  * 		this.#pending = ''
@@ -3581,7 +3963,7 @@ export declare function createRelay(options: RelayOptions): RelayHandler;
  * const result = await browser.generate(messages, abort.signal) // a ProviderResult like a local provider's
  * ```
  */
-export declare function createRelayProvider(options: RelayProviderOptions): RelayProvider;
+export declare function createRelayProvider(options: RelayProviderOptions): ProviderInterface;
 
 /**
  * Creates a named scope — an immutable {@link ScopeInterface} from its `name` and its
@@ -3612,8 +3994,8 @@ export declare function createScope(input: ScopeInput): ScopeInterface;
  * by their minted `id`, in insertion order.
  *
  * @remarks
- * Starts empty; `create` mints each scope's `id` and stores it (keyed by `id`, so it
- * always adds — two scopes may share a `name`); `scopes()` lists them in insertion order;
+ * Starts empty; `add` mints each scope's `id` and stores it (keyed by `id`, so it
+ * never overwrites — two scopes may share a `name`); `scopes()` lists them in insertion order;
  * `remove` (one or a batch) reports `true` only when every supplied id was removed; `clear`
  * empties it. Carries an observable `emitter`
  * ({@link import('./types.js').ScopeManagerEventMap}) wired through the reserved `on`
@@ -3628,7 +4010,7 @@ export declare function createScope(input: ScopeInput): ScopeInterface;
  * import { createScopeManager } from '@orkestrel/agent'
  *
  * const scopes = createScopeManager()
- * const reader = scopes.create({ name: 'reader', tools: ['search'] })
+ * const reader = scopes.add({ name: 'reader', tools: ['search'] })
  * ```
  */
 export declare function createScopeManager(options?: ScopeManagerOptions): ScopeManagerInterface;
@@ -3724,7 +4106,8 @@ export declare function cutListing(entries: readonly string[], room: number): st
  *   the row `{ id: snapshot.id, snapshot }`.
  * - **`get(id)` resolves the stored snapshot for an id**, narrowing the opaque JSON column back to
  *   a {@link ConversationSnapshot} ({@link import('../validators.js').isConversationSnapshot} — the
- *   total guard for an untrusted storage read), or `undefined` if none is stored.
+ *   total guard for an untrusted storage read), or `undefined` if none is stored, the blob is
+ *   malformed, or the blob's own `id` is not the requested one.
  * - **`delete(id)` drops a snapshot by id**; an absent id is a no-op (no throw).
  *
  * Unlike a session store there is no idle-TTL / eviction — a persisted conversation lives until an
@@ -3755,11 +4138,34 @@ export declare class DatabaseConversationStore implements ConversationStoreInter
      *   {@link ConversationSnapshotRow} `{ id; snapshot }` shape (the snapshot one opaque JSON column)
      */
     constructor(table: TableInterface<ConversationSnapshotRow>);
-    /** Resolves the persisted snapshot for `id`, narrowing the opaque JSON column back to a `ConversationSnapshot`. */
+    /**
+     * Resolves the persisted snapshot for `id`, narrowing the opaque JSON column back to a
+     * `ConversationSnapshot`.
+     *
+     * @remarks
+     * The column is an untrusted storage read, so a blob that fails
+     * {@link import('../validators.js').isConversationSnapshot}, or whose own `id` is not `id`,
+     * resolves `undefined` rather than a conversation under the wrong key.
+     *
+     * @param id - The conversation id to resolve (the row key)
+     * @returns The persisted snapshot, or `undefined` when no row is stored, the blob is malformed,
+     * or the blob names another id
+     */
     get(id: string): Promise<ConversationSnapshot | undefined>;
-    /** Inserts or replaces under the snapshot's own `id` (no separate id param) — the row is `{ id, snapshot }`. */
+    /**
+     * Inserts or replaces under the snapshot's own `id` (no separate id param) — the row is
+     * `{ id, snapshot }`.
+     *
+     * @param snapshot - The snapshot to store, keyed by its `id`
+     * @returns A promise that resolves once the row is written
+     */
     set(snapshot: ConversationSnapshot): Promise<void>;
-    /** Drops a snapshot by id; an absent id is a no-op (no throw). */
+    /**
+     * Drops a snapshot by id; an absent id is a no-op (no throw).
+     *
+     * @param id - The conversation id to drop
+     * @returns A promise that resolves once the row is gone
+     */
     delete(id: string): Promise<void>;
 }
 
@@ -3844,8 +4250,8 @@ export declare const DETERMINISTIC_JUDGE_ERROR: RegExp;
 /**
  * Estimates the context-token footprint of a batch of messages — each message's content plus
  * {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD}, a tool-call JSON estimate, a thinking estimate, and
- * {@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} for each attached image. The default
- * `consumer` estimator for an agent's context budget (the
+ * {@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} for each attached image. The {@link estimateRequest} message term
+ * for an agent's context budget (the
  * {@link import('./types.js').AgentOptions} `window`), a provider-independent approximation for conforming messages rather than an exact tokenizer count.
  *
  * @remarks
@@ -3855,12 +4261,12 @@ export declare const DETERMINISTIC_JUDGE_ERROR: RegExp;
  * `calls` plus, when present, {@link estimateTokens} over its `thinking` plus `images.length * `{@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} (a coarse,
  * deliberately-approximate per-image cost — a base64 length is not a token proxy). Deterministic
  * and provider-free — the same messages always yield the same estimate, with an empty batch `0`.
- * It is the fully-swappable default an agent's auto-compaction context budget charges each
- * turn's new messages through; a caller wanting a sharper count supplies its own `consumer` to
- * `createBudget` instead. A `calls` `JSON.stringify` that throws (a
- * circular `ToolCall.arguments`) is caught and replaced with a fixed contribution of
+ * It is the message term of the request estimate an agent's auto-compaction context budget
+ * measures; a caller wanting a sharper count supplies its own `consumer` to `createBudget`
+ * instead. A `calls` list JSON cannot carry (a circular or `BigInt`
+ * `ToolCall.arguments`) contributes a fixed
  * {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} (the same per-message overhead scale)
- * instead of estimating the (unreachable) serialized length.
+ * instead of an estimate of the (unreachable) serialized length.
  *
  * @param messages - The messages to estimate (a turn's appended assistant + tool messages)
  * @returns The summed estimated token count (`0` when empty)
@@ -3873,6 +4279,32 @@ export declare const DETERMINISTIC_JUDGE_ERROR: RegExp;
  */
 export declare function estimateMessages(messages: readonly Message[]): number;
 
+/**
+ * Estimates the context-token footprint of a complete provider request — its messages through
+ * {@link estimateMessages}, plus the rendered advertised `tools`, plus the rendered
+ * `options.schema`. The `consumer` estimator an agent's `window` budget measures every request
+ * through, a provider-independent heuristic rather than an exact tokenizer count.
+ *
+ * @remarks
+ * Adds {@link estimateTokens} over the JSON rendering of `tools` and of `options.schema` to the
+ * message estimate. An absent or empty `tools` list and an absent or empty `schema` add `0`, so a
+ * request that advertises neither equals {@link estimateMessages} of its messages. A value JSON
+ * cannot carry contributes a fixed {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD}. The
+ * estimate counts JSON characters, not a provider's template: the chat template's own tokens, how
+ * a provider encodes tool definitions, and the `think` flag are not counted, and no tokenizer
+ * runs. A model's real prompt count can exceed it, so choose the window `max` with headroom
+ * measured against the provider.
+ *
+ * @param request - The {@link ProviderRequest} to estimate: messages, advertised tools, call options
+ * @returns The estimated token count (`0` for an empty request)
+ *
+ * @example
+ * ```ts
+ * estimateRequest({ messages: [{ id: '1', role: 'user', content: 'hello' }] }) // 6, equal to estimateMessages
+ * ```
+ */
+export declare function estimateRequest(request: ProviderRequest): number;
+
 /**
  * Estimates the context-token footprint of a string — the deterministic `ceil(length / 4)`
  * character heuristic {@link estimateMessages} sums over a conversation's messages (the default
@@ -3966,9 +4398,17 @@ export declare function extractTokens(text: string): LedgerTokenSet;
  */
 export declare function extractWords(message: Message): LedgerWordSet;
 
-/** Carries an HTTP failure message and the underlying body-read cause when available. */
+/**
+ * Carries an HTTP failure message, the response status, and the underlying body-read cause when
+ * available.
+ *
+ * @remarks
+ * The members spread past `message` form the options of a coded HTTP error: `status` is the
+ * response status, and `cause` is present only when the error body could not be read.
+ */
 export declare interface FailureRead {
     readonly message: string;
+    readonly status: number;
     readonly cause?: unknown;
 }
 
@@ -4103,7 +4543,7 @@ export declare interface GaugeCall {
  * Prices prompts in tokens and measures the room a request has left.
  *
  * @remarks
- * `scale` and `overhead` hold the price the gauge read from its last observation.
+ * `scale` holds the price from the last observation; `overhead` holds the construction price.
  */
 export declare interface GaugeInterface extends LedgerGauge {
     /**
@@ -4193,38 +4633,36 @@ export declare interface GaugeOptions extends LedgerGauge {
 export declare function handleAgentQueueJob(registry: AgentRegistryInterface, partial: boolean, input: AgentJobInput, context: QueueContext): Promise<AgentResult>;
 
 /**
- * Handles one runner agent job by fanning out its declared children, rehydrating the
- * parent through a registry with the controller signal, and applying the shared
- * partial-result policy.
+ * Checks whether a message carries at least one tool call.
  *
  * @remarks
- * Children are fired and tracked through the runner controller without awaiting them
- * inline, preserving bounded-runner progress.
- *
- * @param registry - The registry that rehydrates serializable jobs
- * @param partial - The partial policy. If `true`, a partial result resolves; if `false`, it throws
- * @param controller - The runner controller for this parent job
- * @returns The settled parent agent result
+ * Pure and total. An absent `calls` member and an empty list both return false, so a tool-free
+ * assistant turn and a turn whose provider reported an empty call list read alike.
  *
+ * @param message - The message to inspect; only its `calls` member is read
+ * @returns True if `calls` holds at least one call; false otherwise
  * @example
  * ```ts
- * const result = await handleAgentRunnerJob(registry, false, controller)
+ * hasCalls({ calls: [{ id: 'order', name: 'lookup', arguments: {} }] }) // true
+ * hasCalls({ calls: [] }) // false
+ * hasCalls({}) // false
  * ```
  */
-export declare function handleAgentRunnerJob(registry: AgentRegistryInterface, partial: boolean, controller: ControllerInterface<AgentJobInput, AgentResult>): Promise<AgentResult>;
+export declare function hasCalls(message: Pick<Message, 'calls'>): boolean;
 
 /**
  * Identifies a lookup reading for projection by its tool name and normalized arguments.
  *
  * @remarks
  * Two calls share an identity whatever the key order of their arguments at any depth. A top-level
- * string argument is trimmed and uppercased first, so `"lh-1 "` and `"LH-1"` name one call.
+ * string argument passes through {@link normalizeArgument} first, so `"lh-1 "` and `"LH-1"` name one call.
  * The ledger's repeat stop instead compares the tool name and canonical arguments without this
  * string normalization, so those argument spellings remain distinct within a request.
+ * An uncanonicalizable call has no identity and neither replaces nor is replaced by another reading.
  *
  * @param name - The tool name
  * @param args - The arguments the call carried
- * @returns The identity: the name, a space, and the canonical arguments
+ * @returns The name, a space, and the canonical arguments, or `undefined` when uncanonicalizable
  *
  * @example
  * ```ts
@@ -4232,7 +4670,7 @@ export declare function handleAgentRunnerJob(registry: AgentRegistryInterface, p
  * 	identifyLookup('lookup_order', { opts: { region: 'north', tier: 2 }, id: ' BW-5512' }) // true
  * ```
  */
-export declare function identifyLookup(name: string, args: Readonly<Record<string, unknown>>): string;
+export declare function identifyLookup(name: string, args: Readonly<Record<string, unknown>>): string | undefined;
 
 /**
  * Names the coarse, deliberately approximate per-image token cost
@@ -4247,6 +4685,43 @@ export declare function identifyLookup(name: string, args: Readonly<Record<strin
  */
 export declare const IMAGE_TOKEN_ESTIMATE = 512;
 
+/**
+ * Infers which of a run's three failure layers stopped it — the meter allowance, a cost budget, or
+ * the model's own token limit — and returns the stop record with the final call's readings, or
+ * `undefined` when no layer stopped the run.
+ *
+ * @remarks
+ * The layer that stopped the final provider call first wins. A model-truncated final answer whose
+ * call returned unaborted is a `model` stop, even when that call's reconciled usage then exhausted a
+ * budget or a cancel then landed before the run settled. Otherwise a `BudgetError` reason is a
+ * `meter` stop when the allowance is exhausted, the reason is the allowance signal's own reason, its
+ * context carries the allowance's `id` and `max`, and either the allowance is a separate instance or
+ * the run had aborted when the call returned; any other `BudgetError` is a `budget` stop. The
+ * identity test tells an allowance and a budget that share an `id` apart, and the readings test
+ * tells a parent budget linked through the allowance's `signal` option apart from the allowance. An
+ * external cancel, a deadline, or an `abort()` reason yields `undefined`. Two inputs still read as
+ * the meter's: a charge a caller makes to the run's shared allowance from its own code while a call
+ * streams, and a parent with the allowance's own `id` and `max` that aborted before `start()` when
+ * the allowance then exhausts.
+ *
+ * @param reason - The run signal's abort reason (`undefined` while it is unaborted)
+ * @param allowance - The run's meter allowance, or `undefined` for a run with no meter layer
+ * @param budget - The run's cost budget, or `undefined` for an unbudgeted run
+ * @param provider - The provider's trace `id`, named by a `model` stop
+ * @param turn - The run's final turn record, or `undefined` when the run took no turn
+ * @returns The stop record, or `undefined` when no layer stopped the run
+ *
+ * @example
+ * ```ts
+ * const allowance = createTokenBudget({ id: 'meter', max: 2 })
+ * allowance.start()
+ * allowance.consume({ prompt: 0, completion: 3, total: 3 })
+ * inferStop(allowance.signal.reason, allowance, undefined, 'ollama', undefined)
+ * // { layer: 'meter', id: 'meter', max: 2, consumed: 3 }
+ * ```
+ */
+export declare function inferStop(reason: unknown, allowance: BudgetInterface<TokenUsage> | undefined, budget: BudgetInterface<TokenUsage> | undefined, provider: string, turn: AgentTurn | undefined): AgentStop | undefined;
+
 /**
  * Represents an immutable named directive — an {@link InstructionInterface} assembled once from
  * its input (`name` / `content` and an optional `priority`), the `id` minted at
@@ -4428,21 +4903,39 @@ export declare interface InstructionManagerInterface {
     /**
      * Adds one {@link InstructionInput}, or a batch — mints each `id`; adding an instruction whose
      * name is already stored overwrites it, last write wins.
+     *
+     * @param input - One {@link InstructionInput}, or a batch
+     * @returns The stored instruction, or the stored batch in input order
      */
     add(input: InstructionInput): InstructionInterface;
     add(inputs: readonly InstructionInput[]): readonly InstructionInterface[];
-    /** Looks up one instruction by name (`undefined` when absent). */
+    /**
+     * Looks up one instruction by name (`undefined` when absent).
+     *
+     * @param name - The instruction name to look up
+     * @returns The stored instruction, or `undefined` when absent
+     */
     instruction(name: string): InstructionInterface | undefined;
-    /** Lists every instruction, sorted by descending `priority` (stable for equal priorities). */
+    /**
+     * Lists every instruction, sorted by descending `priority` (stable for equal priorities).
+     *
+     * @returns Every stored instruction, highest `priority` first
+     */
     instructions(): readonly InstructionInterface[];
     /**
      * Renders one instruction for the prompt — its `override`, else the manager-options
      * `render`, else its `content`.
+     *
+     * @param instruction - The instruction to render
+     * @returns The instruction's prompt text, `''` when its `override` is `''`
      */
     render(instruction: InstructionInterface): string;
     /**
      * Removes one instruction by name, or a batch. True if every supplied name was removed; false
      * otherwise.
+     *
+     * @param name - One instruction name, or a batch
+     * @returns True if every supplied name was present and removed; false otherwise
      */
     remove(name: string): boolean;
     remove(names: readonly string[]): boolean;
@@ -4669,8 +5162,11 @@ export declare function isJudgeQuestion(value: unknown): value is JudgeQuestion;
  * Checks whether a stored judgment carries a valid question and exactly one answer or refusal.
  *
  * @remarks
- * Malformed members and unreadable inputs return false. Answer fields follow the root judge
- * value types; this storage guard does not impose a wire's probability or candidate limits.
+ * Unknown members, malformed members, and unreadable inputs return false. Answer fields follow
+ * the root judge value types; this storage guard does not impose a wire's probability or
+ * candidate limits. The `time`, `noul`, and probability numbers must be finite, because a stored
+ * record is owned through JSON, which turns `NaN` and the infinities into `null`; so every record
+ * this guard accepts hydrates through a `JudgmentManager`.
  *
  * @param value - The unknown stored record
  * @returns True if the record satisfies the judgment contract; false otherwise
@@ -4717,6 +5213,27 @@ export declare function isLedgerError(value: unknown): value is LedgerError;
  */
 export declare function isMessage(value: unknown): value is Message;
 
+/**
+ * Checks whether a value is a non-negative safe integer, `-0` included.
+ *
+ * @remarks
+ * Total: a non-number, `NaN`, an infinity, a fraction, a negative number, and an integer past
+ * `Number.MAX_SAFE_INTEGER` return false. It differs from `isNonNegativeInteger` in
+ * `@orkestrel/contract` at two values: that guard rejects `-0` and admits an unsafe integer such
+ * as `2 ** 53`, while this guard admits `-0` and rejects `2 ** 53`.
+ *
+ * @param value - The unknown count or limit candidate
+ * @returns True if the value is a safe integer at or above zero; false otherwise
+ * @example
+ * ```ts
+ * isNonNegativeSafeInteger(0) // true
+ * isNonNegativeSafeInteger(-0) // true
+ * isNonNegativeSafeInteger(2 ** 53) // false
+ * isNonNegativeSafeInteger(1.5) // false
+ * ```
+ */
+export declare function isNonNegativeSafeInteger(value: unknown): value is number;
+
 /**
  * Checks whether a value is a positive safe integer.
  * @param value - The value to inspect
@@ -5076,13 +5593,15 @@ export declare class Ledger implements LedgerInterface {
      */
     calibrate(signal: AbortSignal): Promise<LedgerGauge>;
     /**
-     * Appends a request and serves it, recovering an unfinished first pass with one answer pass.
+     * Appends a request and serves it, recovering an unfinished or rejected first pass with one answer pass.
      * A calibration call that reports no prompt usage, or a prompt usage of 0 or less, rejects with `LedgerError` code `'GAUGE'`; a provider error during calibration rejects with that error.
+     * When the answer pass rejects, `respond` rejects with that error. Every rejection leaves the ledger free for a later call.
      * @param content - The request text
      * @param signal - The caller's cancellation signal; an abort during calibration rejects with its reason
-     * @returns The final pass and the usage of every pass
+     * @returns The final pass, the usage of every pass, and the filing readings of this request alone
      * @throws {AgentError} Thrown when a request or calibration is active (code `'CONCURRENCY'`)
      * @throws {LedgerError} Thrown when a calibration call reports no prompt usage, or a prompt usage of 0 or less (code `'GAUGE'`)
+     * @throws {ContractError} Thrown when `signal` is defined and is not a native `AbortSignal`
      */
     respond(content: string, signal?: AbortSignal): Promise<LedgerResult>;
 }
@@ -5184,6 +5703,12 @@ export declare type LedgerEntityHandler = (text: string, partial: boolean) => Re
 export declare class LedgerError extends Error {
     /** Names the machine-readable condition; the {@link LedgerErrorCode} union describes each code. */
     readonly code: LedgerErrorCode;
+    /**
+     * Records the failure condition and its description.
+     *
+     * @param code - The machine-readable condition, exposed as `error.code`
+     * @param message - The human-readable description of the failure
+     */
     constructor(code: LedgerErrorCode, message: string);
 }
 
@@ -5242,17 +5767,22 @@ export declare interface LedgerInterface {
      * @remarks
      * The ledger calibrates first while `gauge` is undefined. When the first pass ends without final
      * text and the caller did not abort, the ledger adds the results and cue notes and makes one
-     * answer pass that advertises no tools. A `respond` or `calibrate` call while either is in flight
+     * answer pass that advertises no tools. A rejected first pass counts as unfinished; when the
+     * answer pass rejects as well, `respond` rejects with that pass's error. A `respond` or `calibrate` call while either is in flight
      * rejects with an `AgentError` whose `code` is `'CONCURRENCY'`. A calibration call that reports no prompt usage, or a prompt usage of 0 or less, rejects with
      * `LedgerError` code `'GAUGE'`; a provider error during calibration rejects with that error.
      * Direct agent runs share an active request's gauge readings and repeat stop, even when their
      * selections fault. Only `respond` and `calibrate` calls are refused by the concurrency guard.
+     * A run no `respond` call owns, including a run during calibration, reads no request's state:
+     * its lookup and `recall` calls run with no repeat stop, recall limit, or close rule.
+     * Every rejection leaves the ledger free for a later call.
      *
      * @param content - The request text
      * @param signal - An optional caller signal; an abort during calibration rejects with its reason; afterward it ends the request partial and skips the answer pass
-     * @returns The reply and the passes the request took
+     * @returns The reply, the passes the request took, and the filing readings of this request alone
      * @throws {LedgerError} Thrown when a calibration call reports no prompt usage, or a prompt usage of 0 or less (code `'GAUGE'`)
      * @throws {AgentError} Thrown when a request or calibration is active (code `'CONCURRENCY'`)
+     * @throws {ContractError} Thrown when `signal` is defined and is not a native `AbortSignal`
      */
     respond(content: string, signal?: AbortSignal): Promise<LedgerResult>;
     /**
@@ -5519,6 +6049,202 @@ export declare interface LedgerRegistry {
     readonly owners: ReadonlyMap<string, readonly string[]>;
 }
 
+/**
+ * Holds what one ledger request keeps while it is served: its message, its filing readings and
+ * plan, the gauge calls of its passes, and its repeat and recall stops.
+ *
+ * @remarks
+ * A ledger creates one request per `respond` call and drops it when the call settles. Each pass the
+ * request opens holds its own selection, boundary, usage, and calls; the request reads the current
+ * pass, the last one opened. {@link LedgerRequestInterface} describes each member.
+ *
+ * @example
+ * ```ts
+ * const request = new LedgerRequest('What approval is needed?', 1)
+ * request.enter(conversation) // the appended user message
+ * request.admit('lookup', { id: 'BW-20931' })
+ * request.admit('lookup', { id: 'BW-20931' }) // throws Error(LEDGER_NOTES.repeat)
+ * request.recall()
+ * request.recall() // throws Error(LEDGER_NOTES.closure): the limit of 1 is spent
+ * ```
+ */
+export declare class LedgerRequest implements LedgerRequestInterface {
+    #private;
+    /**
+     * Holds the request's content and its recall limit.
+     *
+     * @param content - The request text `enter` appends
+     * @param limit - The `recall` calls the request can make. Default: the `DEFAULT_RECALL_LIMIT` constant
+     * @throws {LedgerError} Thrown when `limit` is not a nonnegative safe integer (code `'LIMIT'`)
+     */
+    constructor(content: string, limit?: number);
+    /**
+     * Returns the request message.
+     *
+     * @returns The message `enter` appended, or undefined before it
+     */
+    get message(): Message | undefined;
+    /**
+     * Returns the selection the request's last successful plan produced.
+     *
+     * @returns The planned selection, or undefined before one
+     */
+    get plan(): Selection | undefined;
+    /**
+     * Returns the selection the current pass's run adopted last.
+     *
+     * @returns The selection, or undefined before one
+     */
+    get selection(): Selection | undefined;
+    /**
+     * Returns the conversation length the current pass's calls count additions from.
+     *
+     * @returns The length, or undefined before a pass
+     */
+    get boundary(): number | undefined;
+    /**
+     * Returns the summed usage of the current pass.
+     *
+     * @returns The summed usage, or undefined while none reported usage
+     */
+    get usage(): TokenUsage | undefined;
+    /**
+     * Returns the gauge calls of every pass.
+     *
+     * @returns The calls in order, the call in flight last
+     */
+    get calls(): readonly GaugeCall[];
+    /**
+     * Returns the filing readings of the request's planning selections.
+     *
+     * @returns The readings in asking order
+     */
+    get readings(): readonly ClassifierReading[];
+    enter(conversation: ConversationInterface): Message;
+    open(boundary: number): void;
+    adopt(selection: Selection, boundary: number): void;
+    observe(call: GaugeCall, position: number): void;
+    spend(usage: TokenUsage): void;
+    think(messages: readonly Message[]): void;
+    file(readings: readonly ClassifierReading[], plan?: Selection): void;
+    admit(name: string, args: Readonly<Record<string, unknown>>): void;
+    recall(): void;
+    close(): void;
+    list(result: string, lines: ReadonlyMap<string, string>): void;
+    listing(result: string): ReadonlyMap<string, string> | undefined;
+}
+
+/**
+ * Holds what one `respond` call of a ledger keeps while it serves its request: the request message,
+ * the filing readings and the plan its selections produced, the gauge calls of its passes, and its
+ * repeat and recall stops.
+ *
+ * @remarks
+ * A ledger creates one request per `respond` call and drops it when the call settles, so no request
+ * state reaches a later call or a run no call owns. Each agent run the call makes is a pass: `open`
+ * starts one, and `selection`, `boundary`, and `usage` read the current pass, the last one opened.
+ * `calls` lists the gauge calls of every pass in order. A call stays in flight, taking its usage and
+ * thinking, until its pass observes the next call, and is final from then on.
+ */
+export declare interface LedgerRequestInterface {
+    /** Holds the request message, or undefined until `enter` appends it. */
+    readonly message: Message | undefined;
+    /** Holds the selection the request's last successful plan produced, or undefined before one. */
+    readonly plan: Selection | undefined;
+    /** Holds the selection the current pass's run adopted last, or undefined before one. */
+    readonly selection: Selection | undefined;
+    /** Holds the conversation length at the current pass's start or at its last adopted selection, or undefined before a pass. */
+    readonly boundary: number | undefined;
+    /** Holds the summed usage of the current pass's selections and calls, or undefined while none reported usage. */
+    readonly usage: TokenUsage | undefined;
+    /** Holds the gauge calls of every pass in order, the call in flight last. */
+    readonly calls: readonly GaugeCall[];
+    /** Holds the filing readings of every planning selection the request made, in asking order. */
+    readonly readings: readonly ClassifierReading[];
+    /**
+     * Appends the request's content to a conversation as a user message, once, and holds it as `message`.
+     *
+     * @param conversation - The conversation the request is served from
+     * @returns The request message; a later call returns it without appending again
+     */
+    enter(conversation: ConversationInterface): Message;
+    /**
+     * Opens a pass, which becomes the current pass.
+     *
+     * @param boundary - The conversation length when the pass's run starts
+     */
+    open(boundary: number): void;
+    /**
+     * Records the selection the current pass's run adopted and adds the usage it spent.
+     *
+     * @param selection - The selection the run built its prompt from
+     * @param boundary - The conversation length when the run adopted it
+     */
+    adopt(selection: Selection, boundary: number): void;
+    /**
+     * Starts a gauge call in the current pass, making that pass's call in flight final.
+     *
+     * @param call - The call's estimate and advertised tool count
+     * @param position - The conversation length when the call starts
+     */
+    observe(call: GaugeCall, position: number): void;
+    /**
+     * Adds one call's reported usage to the current pass and records it on the call in flight.
+     *
+     * @param usage - The usage the provider reported for the call
+     */
+    spend(usage: TokenUsage): void;
+    /**
+     * Records the thinking share of the call in flight, read from the first assistant message after
+     * the call's position.
+     *
+     * @remarks
+     * Records nothing while the call in flight has no reported completion or no such message carries
+     * thinking.
+     *
+     * @param messages - The conversation's messages
+     */
+    think(messages: readonly Message[]): void;
+    /**
+     * Appends the readings of one planning selection and holds its plan when planning succeeded.
+     *
+     * @param readings - The selection's filing readings, in asking order
+     * @param plan - The planned selection, or undefined when planning failed
+     */
+    file(readings: readonly ClassifierReading[], plan?: Selection): void;
+    /**
+     * Admits one tool call of the request, compared by tool name and canonical arguments.
+     *
+     * @param name - The tool name
+     * @param args - The call's arguments
+     * @throws {Error} Thrown with the {@link LedgerNote} `repeat` text when the request already admitted the same call
+     * @throws {Error} Thrown when the arguments have no canonical identity
+     */
+    admit(name: string, args: Readonly<Record<string, unknown>>): void;
+    /**
+     * Counts one `recall` call, closing the request's recall tool when its recalls reach the limit.
+     *
+     * @throws {Error} Thrown with the {@link LedgerNote} `closure` text when the recall tool is closed
+     */
+    recall(): void;
+    /** Closes the request's recall tool, so every later `recall` call throws the closure note. */
+    close(): void;
+    /**
+     * Holds the stored first line of each lookup a recall result listed, keyed by its listed line.
+     *
+     * @param result - The recall result text
+     * @param lines - Each listed lookup line mapped to the first line of its stored content
+     */
+    list(result: string, lines: ReadonlyMap<string, string>): void;
+    /**
+     * Returns the stored first lines a recall result listed.
+     *
+     * @param result - The recall result text
+     * @returns Each listed lookup line mapped to its stored first line, or undefined when no recall returned `result`
+     */
+    listing(result: string): ReadonlyMap<string, string> | undefined;
+}
+
 /**
  * Carries the outcome of one request a ledger served: the agent result of its reply and every pass
  * it took.
@@ -5526,10 +6252,14 @@ export declare interface LedgerRegistry {
  * @remarks
  * `passes` holds the first pass and, when the ledger ran one, the answer pass. `content` and
  * `partial` are the last pass's, `usage` sums the passes' usage, and `thinking` joins the passes'
- * reasoning; each optional member is present when any pass reported it.
+ * reasoning; each optional member is present when any pass reported it. `stop` is the last pass's
+ * stop, when one stopped it. `readings` lists every {@link ClassifierReading} the request's
+ * selections recorded, in asking order. A request's reading count is its logical questions, never
+ * its physical wire calls.
  */
 export declare interface LedgerResult extends AgentResult {
     readonly passes: readonly AgentResult[];
+    readonly readings: readonly ClassifierReading[];
 }
 
 /**
@@ -5695,6 +6425,54 @@ export declare function matchesJudgment(judgment: Judgment, question: JudgeQuest
  */
 export declare const MAX_ERROR_BODY_LENGTH = 2048;
 
+/**
+ * Measures the disjoint estimate components of one message — its content, framing, rendered calls,
+ * thinking, and attached images — as the same heuristic units {@link estimateMessages} sums.
+ *
+ * @remarks
+ * The result is a structural estimate, not a tokenizer allocation. `id` and `role` are joins back to
+ * the message, not token components, and a provider's template effects and the estimation error are
+ * not individually attributed. `content` is `ceil(length / 4)`, `framing` is
+ * {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD}, `calls` is the estimate of the JSON-rendered
+ * calls (`0` when the message carries none, the framing overhead when they cannot be rendered),
+ * `thinking` is the estimate of the thinking (`0` when absent), and `images` is the attached image
+ * count times {@link import('./constants.js').IMAGE_TOKEN_ESTIMATE}. The message is not mutated.
+ *
+ * @param message - The message to measure
+ * @returns The message's identity and its estimate components
+ *
+ * @example
+ * ```ts
+ * measureMessage({ id: '1', role: 'user', content: 'hello' })
+ * // { id: '1', role: 'user', content: 2, framing: 4, calls: 0, thinking: 0, images: 0 }
+ * ```
+ */
+export declare function measureMessage(message: Message): MessageMeasure;
+
+/**
+ * Measures the disjoint estimate components of a complete provider request — each message through
+ * {@link measureMessage}, plus the rendered advertised `tools` and `options.schema` — as the same
+ * heuristic units {@link estimateRequest} sums.
+ *
+ * @remarks
+ * The result is a structural estimate, not a tokenizer allocation; a provider's template effects, how
+ * it encodes tool definitions, the `think` flag, and the estimation error are not individually
+ * attributed. `messages` keeps the request's message order, duplicate ids included. `tools` and
+ * `schema` are each `0` when absent or empty and the estimate of their JSON rendering otherwise, or
+ * the {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} when JSON cannot carry them. The request
+ * is not mutated.
+ *
+ * @param request - The {@link ProviderRequest} to measure: messages, advertised tools, call options
+ * @returns The per-message components and the tools and schema estimates
+ *
+ * @example
+ * ```ts
+ * measureRequest({ messages: [{ id: '1', role: 'user', content: 'hello' }] })
+ * // { messages: [{ id: '1', role: 'user', content: 2, framing: 4, calls: 0, thinking: 0, images: 0 }], tools: 0, schema: 0 }
+ * ```
+ */
+export declare function measureRequest(request: ProviderRequest): RequestMeasure;
+
 /**
  * Implements the {@link ConversationStoreInterface} in memory — a process-lifetime `Map` of
  * {@link ConversationSnapshot} records keyed by conversation id, the default store
@@ -5910,6 +6688,30 @@ export declare interface MessageManagerInterface {
     clear(): void;
 }
 
+/**
+ * Holds the disjoint estimate components of one message, in heuristic estimate units.
+ *
+ * @remarks
+ * The structural estimate is not a tokenizer allocation. `id` and `role` are joins back to the
+ * message, not token components. A message's estimate is the sum of `content`, `framing`, `calls`,
+ * `thinking`, and `images`; no total is stored. A provider's template effects and the estimation
+ * error are not individually attributed.
+ */
+export declare interface MessageMeasure {
+    readonly id: string;
+    readonly role: MessageRole;
+    /** Holds the `ceil(length / 4)` estimate of the message `content`. */
+    readonly content: number;
+    /** Holds the fixed per-message framing overhead. */
+    readonly framing: number;
+    /** Holds the estimate of the JSON-rendered `calls`, or the framing overhead when they cannot be rendered; `0` when the message carries none. */
+    readonly calls: number;
+    /** Holds the estimate of the message `thinking`; `0` when absent. */
+    readonly thinking: number;
+    /** Holds the per-image estimate times the attached image count; `0` when none. */
+    readonly images: number;
+}
+
 /** Names the role a {@link Message} plays in a conversation turn. */
 export declare type MessageRole = (typeof MESSAGE_ROLES)[number];
 
@@ -5934,6 +6736,23 @@ images: OptionalShape<ArrayShape<StringShape>>;
 thinking: OptionalShape<StringShape>;
 }, boolean | ContractShape>;
 
+/**
+ * Normalizes a lookup argument string to the spelling that lookup identity and owner linking compare.
+ *
+ * @remarks
+ * {@link identifyLookup} and {@link linkOwners} read an argument through this one form, so a reading
+ * a later lookup replaces and the owner link of its argument agree on the spelling.
+ *
+ * @param value - The string argument a lookup call carried
+ * @returns The argument trimmed and uppercased
+ *
+ * @example
+ * ```ts
+ * normalizeArgument(' bw-5512 ') // 'BW-5512'
+ * ```
+ */
+export declare function normalizeArgument(value: string): string;
+
 /** Carries the probability that the answer is yes; the protocol's noul field. */
 export declare interface NoulAnswer {
     readonly form: 'noul';
@@ -5972,11 +6791,20 @@ export declare const PLACED_CATEGORIES: readonly LedgerCategory[];
  * A message that is not live still places, because a correction joins where its earlier side would
  * join.
  *
+ * With `settled`, the walk returns a placement the map holds without walking again, and records each
+ * placement whose walk, its nested walks included, excluded no earlier side through `seen`. Such a
+ * walk reaches no cycle. While every `seen` holds only the path that reached the message, as
+ * {@link buildRecords} passes it, that path never holds a message the recorded walk reached, so a
+ * fresh walk returns the same keys in the same order. A placement a cycle cut stays unrecorded,
+ * because its keys depend on the path that reached it. Sharing one map across the members of one
+ * input bounds a dense amendment graph to one walk per message.
+ *
  * @param input - The owners, entities, and classification to read
  * @param links - The owner of each linked lookup argument, from {@link linkOwners}
  * @param amending - The earlier sides of each message's amendment pairs
  * @param id - The message id
  * @param seen - The ids already visited, which stops a cycle of amendment pairs
+ * @param settled - The placements already walked for the same `input`, `links`, and `amending`; the walk adds to it. Default: no map, so every call walks
  * @returns The record keys, empty when the message is an orphan
  *
  * @example
@@ -5984,7 +6812,7 @@ export declare const PLACED_CATEGORIES: readonly LedgerCategory[];
  * placeMember(input, new Map(), new Map(), 'user-1', new Set()) // Set { 'owner:BW-20931' }
  * ```
  */
-export declare function placeMember(input: LedgerProjectionInput, links: ReadonlyMap<string, string>, amending: ReadonlyMap<string, readonly string[]>, id: string, seen: ReadonlySet<string>): ReadonlySet<string>;
+export declare function placeMember(input: LedgerProjectionInput, links: ReadonlyMap<string, string>, amending: ReadonlyMap<string, readonly string[]>, id: string, seen: ReadonlySet<string>, settled?: Map<string, ReadonlySet<string>>): ReadonlySet<string>;
 
 /**
  * Reports a provider stream cancelled mid-flight by its bound signal — thrown by the
@@ -6008,8 +6836,8 @@ export declare class ProviderAbortError extends Error {
 
 /**
  * Represents one streamed delta the `stream` method of a {@link ProviderInterface} yields — a unit tagged by
- * the channel it belongs to, so the agent loop can re-surface answer content and live reasoning
- * separately as it pumps.
+ * the channel it belongs to, so the agent loop can forward answer content and live reasoning
+ * separately as each delta arrives.
  *
  * @remarks
  * The discriminant `channel` names the axis that varies: a
@@ -6067,6 +6895,7 @@ export declare interface ProviderIncrement {
     readonly thinking: string;
     readonly tools: readonly ToolCall[];
     readonly usage?: TokenUsage;
+    readonly truncated?: boolean;
     readonly result?: ProviderResult;
 }
 
@@ -6238,7 +7067,9 @@ schema: OptionalShape<ObjectShape<Record<never, never>, JSONShape>>;
  * allows. `tools` is present only when the model requests tool calls (an
  * empty array is never surfaced — its absence means "no calls"). `usage` is present
  * only when the wire reported it (on the stream's `done` line, or the non-stream
- * body), so a caller folds it into a token budget exactly when it exists.
+ * body), so a caller folds it into a token budget exactly when it exists. `truncated` is present
+ * only when the provider's wire reports that the model stopped at its limit; the agent attributes a
+ * truncated final answer to the model layer.
  */
 export declare interface ProviderResult {
     readonly content: string;
@@ -6248,6 +7079,12 @@ export declare interface ProviderResult {
     readonly tools?: readonly ToolCall[];
     /** Carries token consumption for this turn when present (from the wire's `done` line / body). */
     readonly usage?: TokenUsage;
+    /**
+     * Reports that the model ended its answer at its own token limit (an output cap or a full context
+     * window) rather than by finishing; present only when the provider's wire reports that stop. It
+     * is not the request's prompt `truncate` setting.
+     */
+    readonly truncated?: boolean;
 }
 
 /** Validates and projects provider results at a JSON wire boundary. */
@@ -6267,6 +7104,7 @@ prompt: number;
 completion: number;
 total: number;
 } & {}>;
+truncated?: boolean;
 }>>;
 
 /**
@@ -6289,6 +7127,7 @@ prompt: NumberShape;
 completion: NumberShape;
 total: NumberShape;
 }, boolean | ContractShape>>;
+truncated: OptionalShape<BooleanShape>;
 }, boolean | ContractShape>;
 
 /**
@@ -6328,6 +7167,29 @@ export declare function questionToSystemOne(question: JudgeQuestion): SystemOneQ
 /** Lists the categories whose messages the projection leaves out as quiet. */
 export declare const QUIET_CATEGORIES: readonly LedgerCategory[];
 
+/**
+ * Settles with a promise, or rejects with the reason of a signal that aborts first, so a caller
+ * is released at once even when the work behind the promise ignores the signal.
+ *
+ * @remarks
+ * An absent signal returns `promise` itself. An already-aborted signal rejects with its reason
+ * without waiting. The abort listener is removed as soon as `promise` settles. A rejection of
+ * `promise` after the abort is handled here and never surfaces as unhandled.
+ *
+ * @param promise - The work to wait for
+ * @param signal - The cancellation signal, or `undefined` for none
+ * @returns A promise that settles as `promise` does, or rejects with `signal.reason` on abort
+ *
+ * @example
+ * ```ts
+ * const controller = new AbortController()
+ * const raced = raceSignal(new Promise<string>(() => {}), controller.signal)
+ * controller.abort(new Error('stop'))
+ * await raced // rejects with the Error 'stop'
+ * ```
+ */
+export declare function raceSignal<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
+
 /**
  * Ranks a briefing source for removal before the next prompt.
  *
@@ -6362,14 +7224,22 @@ export declare function readChunks(body: ReadableStream<Uint8Array>, signal?: Ab
 /**
  * Reads a bounded HTTP failure excerpt and preserves an unreadable body's cause.
  *
+ * @remarks
+ * Both HTTP engines, the provider and the judge, translate a non-OK response here and throw
+ * their own coded error from the result. When the excerpt is read and `signal` has aborted, the
+ * abort is the call's outcome, so the signal's reason is thrown. When the body read fails, the
+ * failure is returned as `cause` whether or not `signal` has aborted, so a read that raced the
+ * abort stays recorded on the error the caller throws.
+ *
  * @param response - The failed HTTP response
  * @param prefix - The error taxonomy prefix, including its trailing colon
  * @param signal - The call's combined caller and deadline signal
- * @returns The status message with any excerpt or body-read failure
+ * @returns The status message with any excerpt, the response status, and any body-read failure
+ * @throws Thrown when the excerpt is read after `signal` aborts, with the signal's reason
  * @example
  * ```ts
  * await readFailure(new Response('unavailable', { status: 503 }), 'provider error:', new AbortController().signal)
- * // { message: 'provider error: 503 - unavailable' }
+ * // { message: 'provider error: 503 - unavailable', status: 503 }
  * ```
  */
 export declare function readFailure(response: Response, prefix: string, signal: AbortSignal): Promise<FailureRead>;
@@ -6459,6 +7329,7 @@ prompt: number;
 completion: number;
 total: number;
 } & {}>;
+truncated?: boolean;
 }>;
 } & {}> | Readonly<{
 channel: "abort";
@@ -6478,6 +7349,7 @@ prompt: number;
 completion: number;
 total: number;
 } & {}>;
+truncated?: boolean;
 }>;
 } & {}> | Readonly<{
 channel: "error";
@@ -6510,6 +7382,7 @@ prompt: NumberShape;
 completion: NumberShape;
 total: NumberShape;
 }, boolean | ContractShape>>;
+truncated: OptionalShape<BooleanShape>;
 }, boolean | ContractShape>;
 }, boolean | ContractShape>, ObjectShape<    {
 channel: LiteralShape<readonly ["abort"]>;
@@ -6526,6 +7399,7 @@ prompt: NumberShape;
 completion: NumberShape;
 total: NumberShape;
 }, boolean | ContractShape>>;
+truncated: OptionalShape<BooleanShape>;
 }, boolean | ContractShape>;
 }, boolean | ContractShape>, ObjectShape<    {
 channel: LiteralShape<readonly ["error"]>;
@@ -6725,10 +7599,13 @@ export declare function renderCauseChain(error: unknown): string;
  *
  * @remarks
  * Produces `` File: <path>\n```<language>\n<content>\n``` `` — the `File:` label line, then a
- * fenced code block tagged with `language`, the `content` verbatim inside. Pure string assembly,
- * total — never throws. The one fenced-file format string for the whole module — `AgentContext.build()`
- * frames an active workspace's text files with it (each carries its own `language` on its
- * {@link import('@orkestrel/workspace').FileContent} text arm).
+ * fenced code block tagged with `language`, the `content` verbatim inside. The fence is one
+ * backtick longer than the longest backtick run in `content`, and never shorter than three (the
+ * CommonMark rule), so file text holding a triple backtick cannot close the block early and
+ * land outside it; content with no run of three or more keeps the three-backtick fence. Pure
+ * string assembly, total — never throws. The one fenced-file format string for the whole
+ * module — `AgentContext.build()` frames an active workspace's text files with it (each carries
+ * its own `language` on its {@link import('@orkestrel/workspace').FileContent} text arm).
  *
  * @param path - The file path shown on the `File:` label line
  * @param language - The fenced-code language tag (for example `'typescript'`)
@@ -6745,6 +7622,27 @@ export declare function renderCauseChain(error: unknown): string;
  */
 export declare function renderFencedFile(path: string, language: string, content: string): string;
 
+/**
+ * Renders a value as the JSON text `JSON.stringify` produces, or `undefined` when JSON cannot
+ * carry the value.
+ *
+ * @remarks
+ * Pure and total. Where `JSON.stringify` returns text, the result is the same text, property order
+ * included; `canonicalStringify` from `@orkestrel/contract` sorts keys instead. A value
+ * `JSON.stringify` throws on, such as a `BigInt` or a cycle, and a value it renders as nothing,
+ * such as `undefined`, a function, or a symbol, return `undefined`.
+ *
+ * @param value - The value to render
+ * @returns The JSON text, or `undefined` when the value has no JSON text
+ * @example
+ * ```ts
+ * renderJSON({ order: 'LH-81660', late: true }) // '{"order":"LH-81660","late":true}'
+ * renderJSON(10n) // undefined
+ * renderJSON(undefined) // undefined
+ * ```
+ */
+export declare function renderJSON(value: unknown): string | undefined;
+
 /**
  * Renders one owner record under a `###` heading, which the briefing nests under its one `## Pinned` heading.
  *
@@ -6775,22 +7673,42 @@ export declare function renderLedgerPinned(record: Pick<LedgerRecord, 'title' |
  */
 export declare function renderLedgerRecord(record: Pick<LedgerRecord, 'title' | 'lines'>): string;
 
+/**
+ * Renders a lookup call as its tool name and its JSON arguments.
+ *
+ * @remarks
+ * The arguments keep the text `JSON.stringify` writes, key order included. Arguments JSON cannot
+ * carry, such as a `BigInt` or a cycle, render the bare tool name instead of throwing.
+ *
+ * @param name - The lookup tool name
+ * @param args - The arguments the call carried
+ * @returns The tool name, a space, and the JSON arguments; the bare tool name when JSON cannot carry them
+ *
+ * @example
+ * ```ts
+ * renderLookupCall('lookup_order', { id: 'BW-5512' }) // 'lookup_order {"id":"BW-5512"}'
+ * renderLookupCall('lookup_order', { count: 1n }) // 'lookup_order'
+ * ```
+ */
+export declare function renderLookupCall(name: string, args: Readonly<Record<string, unknown>>): string;
+
 /**
  * Renders one context section — the resolved `open`, each item's rendering, and the resolved
  * `close` when one exists, blank-line joined; `undefined` when the section has no items.
  *
  * @remarks
  * Pure and total. A section with no items renders nothing (`undefined`), so an empty or fully
- * scoped-out manager stays silent — its `open` / `close` appear only when the section has items. `close`
- * is the only optional slot: an unset one (there is no built-in close) drops the
- * trailing line.
+ * scoped-out manager stays silent — its `open` / `close` appear only when the section has items.
+ * An empty or absent slot is dropped before the join, so an `open: ''`, a `close: ''`, an unset
+ * `close` (there is no built-in close), and an item rendered to `''` each add no blank line; a
+ * section whose every slot is empty renders nothing (`undefined`).
  *
  * @typeParam T - The section item being rendered
  * @param open - The section's resolved leading text
  * @param members - The already scope-filtered items
  * @param render - Renders one item to its prompt text
  * @param close - The section's resolved trailing text, or `undefined` for none
- * @returns The rendered section, or `undefined` when there are no items
+ * @returns The rendered section, or `undefined` when there are no items or every slot is empty
  *
  * @example
  * ```ts
@@ -6805,7 +7723,7 @@ export declare function renderSection<T>(open: string, members: readonly T[], re
  * Renders the tail stub of a lookup result from an earlier request.
  *
  * @param name - The lookup tool name
- * @param args - The arguments the call carried
+ * @param args - The arguments the call carried; arguments JSON cannot carry leave the call as its bare tool name, per {@link renderLookupCall}
  * @param state - What became of the result: `failed`, `empty`, `shown` in the briefing, or `hidden` from it
  * @returns The stub text, which carries the call and its state
  *
@@ -6817,6 +7735,28 @@ export declare function renderSection<T>(open: string, members: readonly T[], re
  */
 export declare function renderStub(name: string, args: Readonly<Record<string, unknown>>, state: LedgerLookupState): string;
 
+/**
+ * Renders a tool's output as the string content of its tool message.
+ *
+ * @remarks
+ * A string passes through unchanged and `undefined` renders as `''`. Any other value renders as
+ * its `JSON.stringify` text, byte for byte, when JSON can carry it. A value JSON cannot carry (a
+ * `BigInt`, a cycle, a symbol, a throwing `toJSON`) renders as `String(value)`, and as `''` when
+ * that conversion throws too, so a tool's output never rejects the run that dispatched it.
+ *
+ * @param value - The tool's output (`ToolSuccess.value`, which may be `undefined`)
+ * @returns The message content
+ *
+ * @example
+ * ```ts
+ * renderToolValue('sunny') // 'sunny'
+ * renderToolValue({ count: 2 }) // '{"count":2}'
+ * renderToolValue(undefined) // ''
+ * renderToolValue(10n) // '10'
+ * ```
+ */
+export declare function renderToolValue(value: unknown): string;
+
 /**
  * Renders topic names as a comma-separated list in their supplied order.
  * @param topics - The configured desk topics
@@ -6828,13 +7768,74 @@ export declare function renderStub(name: string, args: Readonly<Record<string, u
  */
 export declare function renderTopicNames(topics: readonly LedgerTopic[]): string;
 
+/**
+ * Holds the disjoint estimate components of one provider request, in heuristic estimate units.
+ *
+ * @remarks
+ * `messages` keeps the request's message order, duplicate ids included. `tools` and `schema` are the
+ * estimates of the rendered advertised tools and `options.schema`, each `0` when absent or empty and
+ * the framing overhead when unrenderable. A request's estimate is the sum of every message component
+ * plus `tools` and `schema`; no total is stored.
+ */
+export declare interface RequestMeasure {
+    readonly messages: readonly MessageMeasure[];
+    readonly tools: number;
+    readonly schema: number;
+}
+
+/**
+ * Projects a provider request onto the declared members the relay wire carries.
+ *
+ * @remarks
+ * Each message keeps `id`, `role`, `content`, and any `calls`, `call`, `images`, and `thinking`;
+ * each call keeps only `id`, `name`, and `arguments`, so a local execution context never reaches
+ * the wire. Each tool keeps `name` and any `description` and `parameters`, and the options keep
+ * any `think` and `schema`. An absent member stays absent. The projection shares every nested
+ * value with the input rather than copying it, so the caller snapshots and validates the result;
+ * a throwing getter propagates its failure.
+ *
+ * @param request - The domain conversation and call configuration
+ * @returns The request with only the members the relay wire declares
+ * @example
+ * ```ts
+ * requestToRelay({
+ * 	messages: [{ id: 'turn-1', role: 'user', content: 'Track BW-5512' }],
+ * 	options: { think: false },
+ * })
+ * // { messages: [{ id: 'turn-1', role: 'user', content: 'Track BW-5512' }], options: { think: false } }
+ * ```
+ */
+export declare function requestToRelay(request: ProviderRequest): ProviderRequest;
+
+/**
+ * Returns a run's budget or allowance after checking it implements `BudgetInterface`, or throws a
+ * coded error before the run starts it.
+ *
+ * @remarks
+ * The check is `isBudget` from `@orkestrel/budget`, a total guard. `undefined` passes, because an
+ * absent bound is no bound. The error's `context` carries the option path, the limit
+ * `'BudgetInterface'`, and a preview of the refused value.
+ *
+ * @param value - The effective `budget` or `allowance`, or `undefined`
+ * @param key - The option the value came from, named in the error's path
+ * @returns The value unchanged
+ * @throws {ContractError} Thrown when `value` is defined and does not implement `BudgetInterface` (code `'placement'`)
+ *
+ * @example
+ * ```ts
+ * requireBudget(createTokenBudget({ max: 10 }), 'budget') // the budget
+ * requireBudget({ consume() {} }, 'allowance') // throws ContractError ('placement')
+ * ```
+ */
+export declare function requireBudget(value: BudgetInterface<TokenUsage> | undefined, key: 'budget' | 'allowance'): BudgetInterface<TokenUsage> | undefined;
+
 /**
  * Returns a registered value or throws when its name is absent.
  * @param pool - The named values
  * @param category - The registry category named in an error
  * @param name - The requested key
  * @returns The registered value
- * @throws {AgentError} Thrown when the name is absent, with code REGISTRY.
+ * @throws {AgentError} Thrown when the name is absent, with code REGISTRY and a `context` naming the `category` and the `name`.
  * @example
  * ```ts
  * requireEntry(new Map([['main', provider]]), 'provider', 'main') // provider
@@ -6861,6 +7862,71 @@ export declare function requireEntry<T>(pool: ReadonlyMap<string, T>, category:
  */
 export declare function requireJudgment(value: unknown): Judgment;
 
+/**
+ * Returns a retained-tail size after checking it is a nonnegative safe integer, or throws a coded
+ * error.
+ *
+ * @remarks
+ * The check is {@link import('../validators.js').isNonNegativeSafeInteger}, so `0` and `-0`
+ * pass while `NaN`, a fraction, a negative, and either infinity are refused. The error's `context`
+ * carries the refused value as `keep`.
+ *
+ * @param keep - The retained-tail size to check
+ * @returns The size unchanged
+ * @throws ConversationError Thrown when `keep` is not a nonnegative safe integer (code `'KEEP'`)
+ *
+ * @example
+ * ```ts
+ * requireKeep(2) // 2
+ * requireKeep(1.5) // throws ConversationError ('KEEP')
+ * ```
+ */
+export declare function requireKeep(keep: number): number;
+
+/**
+ * Returns a tool-iteration cap after checking it is a nonnegative safe integer, or throws a coded
+ * error.
+ *
+ * @remarks
+ * The check is {@link import('../validators.js').isNonNegativeSafeInteger}, so `0` and `-0`
+ * pass while `NaN`, a fraction, a negative, and either infinity are refused. The error's `context`
+ * carries the refused value as `limit`.
+ *
+ * @param limit - The tool-iteration cap to check
+ * @returns The cap unchanged
+ * @throws {AgentError} Thrown when `limit` is not a nonnegative safe integer (code `'LIMIT'`)
+ *
+ * @example
+ * ```ts
+ * requireLimit(3) // 3
+ * requireLimit(1.5) // throws AgentError ('LIMIT')
+ * ```
+ */
+export declare function requireLimit(limit: number): number;
+
+/**
+ * Returns the rolling switch after checking it does not combine with a `sections` cap, or throws a
+ * coded error.
+ *
+ * @remarks
+ * A rolling conversation keeps one section, so a cap has nothing to bound. The cap checked is the
+ * effective one: inherited from a manager, configured on the conversation, or supplied to one
+ * `compact()` call.
+ *
+ * @param rolling - Whether folds roll every prior section into one
+ * @param cap - The effective `sections` cap, or `undefined` for none
+ * @returns The rolling switch unchanged
+ * @throws ConversationError Thrown when `rolling` is true and a cap is present (code `'SECTIONS'`)
+ *
+ * @example
+ * ```ts
+ * requireRolling(true, undefined) // true
+ * requireRolling(false, 2) // false
+ * requireRolling(true, 2) // throws ConversationError ('SECTIONS')
+ * ```
+ */
+export declare function requireRolling(rolling: boolean, cap: number | undefined): boolean;
+
 /**
  * Returns a `sections` cap after checking its lower bound, or throws a coded error.
  *
@@ -6896,7 +7962,7 @@ export declare function requireSectionsCap(cap: number | undefined): number | un
 export declare function resolvePredict(predict: number | undefined, capacity: number): number;
 
 /**
- * Sanitizes one reported token count into a safe non-negative integer — a non-finite or
+ * Sanitizes one reported token count into a non-negative integer — a non-finite or
  * non-positive value becomes `0`, and a positive fractional value floors down.
  *
  * @param value - The token count to sanitize
@@ -6911,7 +7977,7 @@ export declare function resolvePredict(predict: number | undefined, capacity: nu
 export declare function sanitizeToken(value: number): number;
 
 /**
- * Sanitizes a {@link TokenUsage} into safe, non-negative integers — the guard an agent's
+ * Sanitizes a {@link TokenUsage} into non-negative integers — the guard an agent's
  * abort-usage path applies to a provider's partial usage before it is charged against a
  * budget or folded into the run total.
  *
@@ -6921,7 +7987,7 @@ export declare function sanitizeToken(value: number): number;
  * non-negative integer part. No upper cap is applied. Total — never throws.
  *
  * @param usage - The token usage to sanitize (for example a provider's abort-partial usage)
- * @returns A new {@link TokenUsage} with every field a safe non-negative integer
+ * @returns A new {@link TokenUsage} with every field a non-negative integer
  *
  * @example
  * ```ts
@@ -7062,20 +8128,20 @@ export declare interface ScopeInterface extends ScopeFilter {
 
 /**
  * Registers the named filters a richer context reuses — immutable {@link Scope} instances keyed by their
- * minted `id`, in insertion order, where `create` always mints and stores rather than overwriting,
+ * minted `id`, in insertion order, where `add` always mints and stores rather than overwriting,
  * and an observable `emitter` reports each change.
  *
  * @remarks
  * - **Registry.** Scopes live in an insertion-ordered `Map` keyed by their minted `id`;
- *   `create` mints a {@link Scope} from a {@link ScopeInput} (an `id` plus the three
+ *   `add` mints a {@link Scope} from a {@link ScopeInput} (an `id` plus the three
  *   allow-lists), stores it, and returns it. `count` is the map size, `scope(id)` looks
  *   one up, and `scopes()` lists them in insertion order. (Unlike the name-keyed
  *   instruction registry, a scope's key is its minted `id`, so two scopes may share a
- *   `name`; `create` therefore always adds — it never overwrites.)
+ *   `name`; `add` therefore never overwrites.)
  * - **Removal.** `remove` drops one by id, or a batch — `true` only when every supplied id
  *   was removed; `clear` empties the registry.
  * - **Observable.** The owned {@link emitter} ({@link ScopeManagerEventMap}) carries
- *   `create` (the created scope) / `remove` (the id) / `clear`. Every event is emitted
+ *   `add` (the added scope) / `remove` (the id) / `clear`. Every event is emitted
  *   directly, strictly after the map mutation completes; the emitter isolates a listener
  *   throw and routes it to its `error` handler (the `error` option), so a buggy observer can
  *   never corrupt a mutation.
@@ -7083,7 +8149,7 @@ export declare interface ScopeInterface extends ScopeFilter {
  * @example
  * ```ts
  * const manager = new ScopeManager()
- * const reader = manager.create({ name: 'reader', tools: ['search', 'read'] })
+ * const reader = manager.add({ name: 'reader', tools: ['search', 'read'] })
  * manager.scope(reader.id) // the same scope
  * manager.count // 1
  * ```
@@ -7093,7 +8159,7 @@ export declare class ScopeManager implements ScopeManagerInterface {
     constructor(options?: ScopeManagerOptions);
     get emitter(): EmitterInterface<ScopeManagerEventMap>;
     get count(): number;
-    create(input: ScopeInput): ScopeInterface;
+    add(input: ScopeInput): ScopeInterface;
     scope(id: string): ScopeInterface | undefined;
     scopes(): readonly ScopeInterface[];
     remove(id: string): boolean;
@@ -7103,17 +8169,17 @@ export declare class ScopeManager implements ScopeManagerInterface {
 
 /**
  * Maps the push observation surface of a {@link ScopeManagerInterface} — analogous to
- * {@link InstructionManagerEventMap}, but keyed by the minted `id` and carrying `create`
- * (a scope always mints, never overwrites) rather than `add`.
+ * {@link InstructionManagerEventMap}, but keyed by the minted `id`, so `add` never reports a
+ * replaced scope.
  *
  * @remarks
- * `create` carries the created {@link ScopeInterface}; `remove` carries the removed
+ * `add` carries the added {@link ScopeInterface}; `remove` carries the removed
  * scope's `id`; `clear` is a pure signal. The emitter isolates a listener throw and routes
  * it to its `error` handler. A `type` alias so it satisfies `EventMap` structurally.
  */
 export declare type ScopeManagerEventMap = {
-    /** Reports a scope created — the created scope. */
-    readonly create: readonly [scope: ScopeInterface];
+    /** Reports a scope added — the added scope. */
+    readonly add: readonly [scope: ScopeInterface];
     /** Reports a scope removed — its `id`. */
     readonly remove: readonly [id: string];
     /** Reports every scope removed. */
@@ -7121,16 +8187,16 @@ export declare type ScopeManagerEventMap = {
 };
 
 /**
- * Registers reusable {@link ScopeInterface} instances keyed by their minted `id` — `create`
+ * Registers reusable {@link ScopeInterface} instances keyed by their minted `id` — `add`
  * mints + stores one (never overwrites), `scopes()` lists them in insertion order.
  *
  * @remarks
- * - **Registry.** `create(input)` mints a scope (an `id` + the per-category allow-lists) and
+ * - **Registry.** `add(input)` mints a scope (an `id` + the per-category allow-lists) and
  *   stores it; `count` is how many are stored. `scope(id)` looks one up; `scopes()` lists
  *   them in insertion order. (Keyed by minted `id`, not `name`, so two scopes may share a
- *   `name` and `create` always adds.)
+ *   `name` and `add` never overwrites.)
  * - **Observable.** The owned `emitter` ({@link ScopeManagerEventMap}) carries
- *   `create` / `remove` / `clear` for fire-and-forget observers; the emitter isolates a
+ *   `add` / `remove` / `clear` for fire-and-forget observers; the emitter isolates a
  *   listener throw and routes it to its `error` handler (the `error` option).
  */
 export declare interface ScopeManagerInterface {
@@ -7139,13 +8205,30 @@ export declare interface ScopeManagerInterface {
     /**
      * Mints a scope from a {@link ScopeInput} (a `name` plus the per-category allow-lists) and
      * stores it — always adds, never overwrites.
+     *
+     * @param input - The scope's `name`, allow-lists, and optional `select` handler
+     * @returns The stored scope, carrying its minted `id`
+     */
+    add(input: ScopeInput): ScopeInterface;
+    /**
+     * Looks up one scope by id (`undefined` when absent).
+     *
+     * @param id - The minted scope id to look up
+     * @returns The stored scope, or `undefined` when absent
      */
-    create(input: ScopeInput): ScopeInterface;
-    /** Looks up one scope by id (`undefined` when absent). */
     scope(id: string): ScopeInterface | undefined;
-    /** Lists every scope, in insertion order. */
+    /**
+     * Lists every scope, in insertion order.
+     *
+     * @returns Every stored scope, in insertion order
+     */
     scopes(): readonly ScopeInterface[];
-    /** Removes one scope by id, or a batch. True if every supplied id was removed; false otherwise. */
+    /**
+     * Removes one scope by id, or a batch. True if every supplied id was removed; false otherwise.
+     *
+     * @param id - One scope id, or a batch
+     * @returns True if every supplied id was present and removed; false otherwise
+     */
     remove(id: string): boolean;
     remove(ids: readonly string[]): boolean;
     /** Removes every scope. */
@@ -7299,6 +8382,23 @@ export declare function selectRecords(projection: LedgerProjection, request: Led
  */
 export declare function settleAgentJob(agent: AgentInterface, partial: boolean): Promise<AgentResult>;
 
+/**
+ * Splits a tool result into its lines at each line feed, with or without a carriage return before it.
+ *
+ * @remarks
+ * The recall listing keys each recalled line by its first line, and the answer note reads a result
+ * line by line, so both read lines through this one split.
+ *
+ * @param text - The tool result text
+ * @returns The lines in order, an empty line included; one empty line for an empty text
+ *
+ * @example
+ * ```ts
+ * splitResultLines('Account BW-20931.\r\nRefund is $148.50.') // ['Account BW-20931.', 'Refund is $148.50.']
+ * ```
+ */
+export declare function splitResultLines(text: string): readonly string[];
+
 /**
  * Splits a message into its sentences.
  *
@@ -7591,9 +8691,9 @@ export declare const THINK_OPEN = "<think>";
 export declare type ThinkingReplay = 'none' | 'turn' | 'all';
 
 /**
- * Feeds raw content deltas through a tiny stream-stateful state machine that routes everything
- * inside a `<think>…</think>` span to `thinking` and returns everything outside it as clean
- * content, so a provider yields the answer alone and surfaces the reasoning as
+ * Separates `<think>…</think>` spans from raw content deltas with per-stream state: text inside a
+ * span accumulates on `thinking`, and text outside it returns as clean content, so a provider
+ * yields the answer alone and surfaces the reasoning as
  * {@link import('./types.js').ProviderResult.thinking}. A tag split across deltas is held until
  * disambiguated, `flush()` settles the stream end, and one splitter serves one stream.
  *
@@ -7645,7 +8745,7 @@ export declare class ThinkSplitter implements ThinkSplitterInterface {
  * - **Stateful across deltas.** A tag may arrive split across wire chunks (`'<thi'`
  *   ending one delta, `'nk>'` opening the next) — `split` holds any ambiguous tail
  *   back until the next delta (or `flush`) disambiguates it, so a partial tag is
- *   never leaked as content and never mis-eaten as thinking.
+ *   neither returned as content nor routed to thinking.
  * - **`split(delta)`** feeds one raw content delta and returns the clean content to
  *   surface for it (possibly `''` — for example mid-think). Text inside a
  *   `<think>…</think>` span accumulates on `thinking`; multiple spans accumulate in
@@ -7676,8 +8776,8 @@ export declare interface ThinkSplitterInterface {
     readonly thinking: string;
     /**
      * Feeds one raw delta and returns the clean, non-think content to surface for it (possibly
-     * `''`) — a tag split across deltas is held until disambiguated, never leaked as content
-     * and never mis-eaten as thinking.
+     * `''`) — a tag split across deltas is held until disambiguated, so it is neither returned
+     * as content nor routed to thinking.
      */
     split(delta: string): string;
     /**
@@ -7687,6 +8787,31 @@ export declare interface ThinkSplitterInterface {
     flush(): string;
 }
 
+/**
+ * Projects an unknown value onto a fresh, exact `TokenUsage` — capturing `prompt`, `completion`, and
+ * `total` once each through a total boundary, preserving finite negative and fractional counts,
+ * dropping extras, and resolving `undefined` for a non-object, a missing or non-finite count, a
+ * throwing getter, or a hostile or revoked proxy.
+ *
+ * @remarks
+ * The capture runs inside Contract's sanctioned exception boundary, so conforming accessors and
+ * inherited properties are read while a throwing getter or a revoked proxy returns `undefined`.
+ * Counts are not normalized. A caller that treats an absent usage as valid checks for `undefined`
+ * before it projects, because this function refuses `undefined` like any other non-object.
+ *
+ * @param value - The unknown value to project
+ * @returns A fresh `{ prompt, completion, total }`, or `undefined` when the value is not a finite usage triple
+ *
+ * @example
+ * ```ts
+ * import { tokenUsageToJSON } from '@orkestrel/agent'
+ *
+ * tokenUsageToJSON({ prompt: 2, completion: -1, total: 1.5, cached: 4 }) // { prompt: 2, completion: -1, total: 1.5 }
+ * tokenUsageToJSON({ prompt: 2, completion: Infinity, total: 3 }) // undefined
+ * ```
+ */
+export declare function tokenUsageToJSON(value: unknown): TokenUsage | undefined;
+
 /**
  * Describes a tool call's JSON wire projection.
  *
@@ -7717,15 +8842,16 @@ export declare const UPSTREAM_RELAY_STATUS = 502;
 /**
  * Names the section header the `build()` method of {@link import('./AgentContext.js').AgentContext}
  * renders the active workspace's text files under — `'## Workspace'`, the leading line of the dedicated
- * workspace block in the system message and the carrier-split counterpart to the documents and
- * images section headers.
+ * workspace block in the system message.
  *
  * @remarks
  * `build()` owns the workspace render (a `Workspace` / `WorkspaceManager` stays file-focused — no
  * `open` / `format` getters), so this header lives here as the contexts module's one
  * workspace-section framing constant rather than on a manager. Each workspace text file renders
- * beneath it as a fenced `` File: <path>\n```<language>\n<text>\n``` `` block — the same framing
- * the documents section uses — placed immediately after the documents section in the system block.
+ * beneath it as a fenced `` File: <path>\n```<language>\n<text>\n``` `` block through
+ * {@link import('./helpers.js').renderFencedFile}, and the block is placed immediately after the
+ * instructions section in the system block. The workspace's image files render no section: their
+ * `base64` payload attaches to the last user message.
  */
 export declare const WORKSPACE_SECTION_HEADER = "## Workspace";