@orkestrel/agent 0.0.19 → 0.0.20

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

@@ -4,8 +4,9 @@ import { DriverInterface } from '@orkestrel/database';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
+import { FileInterface } from '@orkestrel/workspace';
 import { JSONValue } from '@orkestrel/contract';
-import { QueueExecution } from '@orkestrel/queue';
+import { QueueContext } from '@orkestrel/queue';
 import { QueueInterface } from '@orkestrel/queue';
 import { QueueStoreInterface } from '@orkestrel/queue';
 import { RunnerInterface } from '@orkestrel/workflow';
@@ -20,15 +21,15 @@ import { ToolResult } from '@orkestrel/tool';
 import { WorkspaceManagerInterface } from '@orkestrel/workspace';
 
 /**
- * The agent loop — composes a {@link ProviderInterface}, an {@link AgentContext}, and
- * a {@link ToolManagerInterface} into a bounded context → provider → tools → repeat
+ * Composes a {@link ProviderInterface}, an {@link AgentContext}, and a
+ * {@link ToolManagerInterface} into a bounded context → provider → tools → repeat
  * turn, exposed as both a one-shot `generate` and a live `stream`.
  *
  * @remarks
  * - **One loop, two faces.** A single private async generator (`#run`) drives the
  *   whole turn. `stream` kicks off an eager pump that iterates `#run` into a private
  *   {@link Channel}, settling `result` from the run's outcome — so `result` settles
- *   whether or not the live `events` are drained; `generate` simply awaits that same
+ *   whether or not the live `events` are drained; `generate` awaits that same
  *   settled `result` — so the two can never diverge.
  * - **The turn.** `#run` builds the provider input once (`context.build()` into a
  *   working array) then loops up to `limit`: drive `provider.stream(...)` accumulating
@@ -37,7 +38,7 @@ import { WorkspaceManagerInterface } from '@orkestrel/workspace';
  *   tools, append the assistant turn, `execute` them, yield a `tool` chunk per call,
  *   append each tool result message, and continue; otherwise append the final
  *   assistant message and stop.
- * - **Bounded.** Each run arms one cancel via `createAbort({ signal: AbortSignal.any([
+ * - **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
  *   (the `result` promise RESOLVES, never rejects, on a cancel) — only a genuine
@@ -61,8 +62,8 @@ import { WorkspaceManagerInterface } from '@orkestrel/workspace';
  */
 export declare class Agent implements AgentInterface {
     #private;
-    readonly id: string;
     constructor(provider: ProviderInterface, options?: AgentOptions);
+    get id(): string;
     get emitter(): EmitterInterface<AgentEventMap>;
     get status(): AgentStatus;
     get context(): AgentContextInterface;
@@ -72,8 +73,8 @@ export declare class Agent implements AgentInterface {
 }
 
 /**
- * A streamed step of an agent turn — the discriminated union the loop yields as it
- * runs.
+ * Represents a streamed step of an agent turn — the union the loop yields as it runs, discriminated
+ * by the `category` of step it carries.
  *
  * @remarks
  * - `token` — a content delta the provider streamed (the `'content'`
@@ -89,23 +90,23 @@ export declare class Agent implements AgentInterface {
  *   provider response that reported it (folded into the running total + any budget).
  */
 export declare type AgentChunk = {
-    readonly type: 'token';
+    readonly category: 'token';
     readonly content: string;
 } | {
-    readonly type: 'think';
+    readonly category: 'think';
     readonly content: string;
 } | {
-    readonly type: 'tool';
+    readonly category: 'tool';
     readonly call: ToolCall;
     readonly result: ToolResult;
 } | {
-    readonly type: 'usage';
+    readonly category: 'usage';
     readonly usage: TokenUsage;
 };
 
 /**
- * The richer turn context the agent loop assembles a provider request from — the optional
- * system prompt, the observable context managers (instructions / workspaces), the
+ * Assembles a provider request from the richer turn context — the optional system prompt, the
+ * observable context managers (instructions / workspaces), the
  * {@link ConversationManagerInterface} message source (whose active conversation IS `messages`),
  * the {@link ToolManagerInterface} registry, and an active {@link ScopeInterface} changed through
  * {@link AgentContextInterface.apply}.
@@ -126,7 +127,7 @@ export declare type AgentChunk = {
  *   {@link MessageManagerInterface} structurally — the same reference, no duplication), and
  *   `build()` folds that conversation's `view()` (its per-section summaries + live tail) as the
  *   AUTHORITATIVE message inclusion — the scope does NOT filter the conversation (it owns inclusion
- *   via compaction; scope filters only instructions / tools / workspace files). Because `messages`
+ *   through compaction; scope filters only instructions / tools / workspace files). Because `messages`
  *   is read dynamically, an agent SWITCHES the active
  *   conversation BETWEEN runs (`conversations.switch(id)`) to serve MANY threads (the real
  *   multi-conversation pattern); switch between runs, not during a run, and use separate agents
@@ -136,31 +137,31 @@ export declare type AgentChunk = {
  *   (each as a block: the section's resolved `open` text, each item's resolved rendering, then
  *   any resolved `close` text) into ONE leading `system` message (prepended only when at least
  *   one part exists), then appends the ACTIVE conversation's `view()` (the conversation owns
- *   message inclusion via compaction — the scope does NOT filter the conversation). Each
+ *   message inclusion through compaction — the scope does NOT filter the conversation). Each
  *   `open` / item / `close`
  *   resolves INDEPENDENTLY, MOST-SPECIFIC-FIRST — `build()`'s optional `format` (a provider's
  *   per-section default) is the PROVIDER level: `open` = manager-options-override > provider >
  *   built-in; per item = item-override > manager-options-override > provider > built-in; `close` =
  *   manager-options-override > provider (NO built-in ⇒ no closing line when unset) (see
  *   {@link AgentContextInterface.build}). Passing NO `format` (and with no overrides / no per-item
- *   format) reproduces the built-in framing byte-for-byte (each section is its built-in header +
- *   items, no closing line). The active workspace's scoped-in image files' `data` is attached to
+ *   override) reproduces the built-in framing byte-for-byte (each section is its built-in header +
+ *   items, no closing line). The active workspace's scoped-in image files' `base64` payload is attached to
  *   the LAST user message (a vision provider reads images off a user turn); when no user message
  *   exists the attachment is skipped. Built fresh each call (recomputed, never cached), so it
  *   always reflects the current managers / messages / scope / active workspace; it never mutates a
  *   manager or the stored messages.
  * - **The ACTIVE workspace, rendered BY CARRIER — the SOLE document/image context.**
- *   `workspaces.active` (when set) has its {@link FileInterface}s scope-filtered by `scope.files`,
+ *   `workspaces.active` (when set) has its {@link import('@orkestrel/workspace').FileInterface}s scope-filtered by `scope.files`,
  *   then split: TEXT files fold into a dedicated `## Workspace` system section (fenced reference
- *   blocks — placed right after the instructions section), and IMAGE files' base64 `data` attaches
+ *   blocks — placed right after the instructions section), and IMAGE files' `base64` payload attaches
  *   to the last user message. ACTIVE-ONLY — never the other registered workspaces; with no active
  *   workspace nothing renders for workspaces. `build()` OWNS this render (a `Workspace` /
  *   `WorkspaceManager` stays file-focused).
  * - **Tools are structural, not in the prompt.** The registry is advertised to the provider
- *   via `tools.definitions()` (scope-filtered by the loop), NEVER serialized into the
+ *   through `tools.definitions()` (scope-filtered by the loop), NEVER serialized into the
  *   message array — so `build()`'s output carries no tool content, scoped or not.
  * - **Event-free context; observable managers.** The context itself owns no Emitter; the
- *   context managers each carry their own (the §13 observation surface).
+ *   context managers each carry their own (the push observation surface).
  *
  * @example
  * ```ts
@@ -181,7 +182,7 @@ export declare class AgentContext implements AgentContextInterface {
     get tools(): ToolManagerInterface;
     get scope(): ScopeInterface | undefined;
     apply(scope: ScopeInterface | undefined): void;
-    build(format?: ContextFormatInterface): readonly MessageInterface[];
+    build(format?: ContextFormat): readonly Message[];
 }
 
 /**
@@ -193,12 +194,12 @@ export declare class AgentContext implements AgentContextInterface {
  * (`instructions` / `workspaces` / `conversations`), `messages` (the active
  * conversation's live tail, satisfying {@link MessageManagerInterface}), and the current `scope`
  * (the active {@link ScopeInterface} filter, or `undefined` for no filtering). `build()` folds the
- * scoped instructions into ONE leading `system` message (under the manager's `description`,
- * each item via its `format`) — PLUS the ACTIVE workspace's scope-filtered text files
+ * scoped instructions into ONE leading `system` message (under the manager's `open`,
+ * each item through its `render`) — PLUS the ACTIVE workspace's scope-filtered text files
  * (rendered as fenced reference blocks) — and appends the ACTIVE conversation's `view()`, attaching
- * the active workspace's scope-filtered image files' base64 `data` to the LAST user message. The
+ * the active workspace's scope-filtered image files' `base64` payload to the LAST user message. The
  * active workspace is the SOLE document/image context. Tools are advertised to the provider
- * STRUCTURALLY (via `tools.definitions()`, scope-filtered by the loop), NOT serialized into
+ * STRUCTURALLY (through `tools.definitions()`, scope-filtered by the loop), NOT serialized into
  * the prompt, so they never appear in `build()`'s output. The context managers are observable
  * (their own `emitter`s); the context itself is event-free.
  */
@@ -206,9 +207,9 @@ export declare interface AgentContextInterface {
     readonly system: string | undefined;
     readonly instructions: InstructionManagerInterface;
     /**
-     * The {@link WorkspaceManagerInterface} whose ACTIVE workspace `build()` renders by carrier —
+     * Holds the {@link WorkspaceManagerInterface} whose ACTIVE workspace `build()` renders by carrier —
      * its text files folded into the system block (fenced reference blocks) and its image files'
-     * base64 `data` attached to the LAST user message. The active workspace is the SOLE
+     * `base64` payload attached to the LAST user message. The active workspace is the SOLE
      * document/image context. ALWAYS present (a fresh empty manager when none was supplied).
      * `build()` reads its `active` (and the active workspace's `files()`) FRESH each call. With NO
      * active workspace, nothing is rendered for workspaces. Active-only — never the other registered
@@ -216,7 +217,7 @@ export declare interface AgentContextInterface {
      */
     readonly workspaces: WorkspaceManagerInterface;
     /**
-     * The active conversation's LIVE tail — the agent's message source, ALWAYS defined (the
+     * Holds the active conversation's LIVE tail — the agent's message source, ALWAYS defined (the
      * {@link conversations} registry always has an active conversation; a default is added at
      * construction). It IS the active {@link ConversationInterface} itself (which satisfies
      * {@link MessageManagerInterface} structurally), so appends through `messages` route to the
@@ -226,24 +227,23 @@ export declare interface AgentContextInterface {
      */
     readonly messages: MessageManagerInterface;
     /**
-     * The {@link ConversationManagerInterface} the message source flows from — `messages` IS its
+     * Holds the {@link ConversationManagerInterface} the message source flows from — `messages` IS its
      * ACTIVE conversation's live tail and `build()` folds that conversation's `view()`. ALWAYS holds
      * an active conversation (a default is added at construction when none was supplied), so
      * `messages` is always defined. Switch the active conversation through
      * `conversations.switch(id)` — so one agent can serve MANY conversations (set the active one per
-     * request). Switch BETWEEN runs, not during one; for CONCURRENT threads use separate agents (see
-     * clause 23).
+     * request). Switch BETWEEN runs, not during one; for CONCURRENT threads use separate agents.
      */
     readonly conversations: ConversationManagerInterface;
     /**
-     * The loop's tool registry for provider advertising and call dispatch. Tools are structural
+     * Holds the loop's tool registry for provider advertising and call dispatch. Tools are structural
      * loop machinery and never render into `build()`'s prompt.
      */
     readonly tools: ToolManagerInterface;
-    /** The active scope applied at `build()` time + the loop's tool-advertise step (`undefined` ⇒ no filtering). */
+    /** Holds the active scope applied at `build()` time + the loop's tool-advertise step (`undefined` ⇒ no filtering). */
     readonly scope: ScopeInterface | undefined;
     /**
-     * Apply the active per-turn scope filter. Passing `undefined` removes filtering.
+     * Applies the active per-turn scope filter. Passing `undefined` removes filtering.
      *
      * @param scope - The scope to apply, or `undefined` to remove the active filter
      *
@@ -255,10 +255,10 @@ export declare interface AgentContextInterface {
      */
     apply(scope: ScopeInterface | undefined): void;
     /**
-     * The provider input for the next turn: a leading `system` message folding the prompt
+     * Builds the provider input for the next turn: a leading `system` message folding the prompt
      * + the scoped instructions + the ACTIVE workspace's scoped-in TEXT files (rendered as
      * fenced reference blocks), then the ACTIVE conversation's `view()` (with the active workspace's
-     * scoped-in IMAGE files' `data` attached to the last user message). Tools are advertised
+     * scoped-in IMAGE files' `base64` payload attached to the last user message). Tools are advertised
      * structurally, not in the prompt. Built fresh on each call.
      *
      * @remarks
@@ -268,8 +268,8 @@ 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 just after the instructions
-     * section; binary files whose MIME starts with `image/` have their base64 `data`
+     * `` 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
      * 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.
@@ -279,40 +279,40 @@ export declare interface AgentContextInterface {
      * leading text), each item's `render`, and the `close` (the section's trailing text)
      * resolve INDEPENDENTLY, MOST-SPECIFIC-FIRST, from a {@link ContextSectionFormat} at each
      * level — an item override, a manager-options override, the provider `format` default,
-     * and the manager's built-in. For a section kind `K` (currently `instructions`), manager
+     * and the manager's built-in. For the `instructions` section kind `K`, manager
      * `M`, and the supplied `format` `F`:
-     * - **open** = `M.optionsFormat?.open ?? F?.[K]?.open ?? M.builtInOpen` — i.e.
+     * - **open** = `M.format?.open ?? F?.[K]?.open ?? M.open` — that is,
      *   **manager-options override > provider default > built-in** (the leading text has no
      *   per-item level). The manager ENCAPSULATES the `[options-override → built-in]` half:
-     *   `M.description` already returns the options override's `open` when one is set, else
+     *   `M.open` already returns the options override's `open` when one is set, else
      *   the built-in header — so `build()` only layers the provider default BETWEEN them.
-     * - **item** `I` = `I.format ?? M.optionsFormat?.render?.(I) ?? F?.[K]?.render?.(I) ?? M.builtInFormat(I)`
-     *   — i.e. **item override > manager-options override > provider default > built-in**.
-     *   Again `M.format(I)` already returns the options override when set, else the
-     *   built-in, so `build()` layers the per-item `I.format` ON TOP and the provider
+     * - **item** `I` = `I.override ?? M.format?.render?.(I) ?? F?.[K]?.render?.(I) ?? M.render(I)`
+     *   — that is, **item override > manager-options override > provider default > built-in**.
+     *   Again `M.render(I)` already returns the options override when set, else the
+     *   built-in, so `build()` layers the per-item `I.override` ON TOP and the provider
      *   default BETWEEN.
-     * - **close** = `M.optionsFormat?.close ?? F?.[K]?.close` — i.e. **manager-options
+     * - **close** = `M.format?.close ?? F?.[K]?.close` — that is, **manager-options
      *   override > provider default**, with NO built-in floor (the trailing text has no
      *   per-item level): unset at both levels ⇒ `undefined` ⇒ no closing line. Paired with
      *   `open`, it lets a level WRAP the group (`open: '<instructions>'` … `close: '</instructions>'`).
      *
      * Passing NO `format` (the default) leaves the provider-default level empty, so the
-     * output is BYTE-FOR-BYTE the managers' built-in framing — every section is just its
+     * output is BYTE-FOR-BYTE the managers' built-in framing — every section is its
      * built-in header + items, with no closing line (the regression contract). Scope
      * filtering runs BEFORE formatting (unchanged); the workspace image-data attachment to the
      * last user message is unchanged.
      *
-     * @param format - The provider's optional {@link ContextFormatInterface} default
+     * @param format - The provider's optional {@link ContextFormat} default
      *   (typically `provider.format`); omitted ⇒ only the manager-options / item / built-in
      *   levels apply, reproducing the prior built-in output exactly
      * @returns The scoped conversation, prefixed by the assembled `system` message when any
      *   of (the prompt, the scoped instructions, the active workspace's text files) is non-empty
      */
-    build(format?: ContextFormatInterface): readonly MessageInterface[];
+    build(format?: ContextFormat): readonly Message[];
 }
 
 /**
- * Options for `createAgentContext` — the richer context's configuration.
+ * Configures `createAgentContext` — the richer context's configuration.
  *
  * @remarks
  * `system` is the optional system prompt prepended to the turn's input. `instructions` /
@@ -331,29 +331,29 @@ export declare interface AgentContextInterface {
 export declare interface AgentContextOptions {
     readonly system?: string;
     /**
-     * The loop's pre-built tool registry for provider advertising and call dispatch; an empty one is
+     * Holds the loop's pre-built tool registry for provider advertising and call dispatch; an empty one is
      * created when omitted. Tools never render into `build()`'s prompt.
      */
     readonly tools?: ToolManagerInterface;
-    /** A pre-built instruction registry to reuse; an empty one is created when omitted. */
+    /** Reuses a pre-built instruction registry; an empty one is created when omitted. */
     readonly instructions?: InstructionManagerInterface;
     /**
-     * A pre-built {@link WorkspaceManagerInterface} to reuse; a fresh empty one is created when
+     * Reuses a pre-built {@link WorkspaceManagerInterface}; a fresh empty one is created when
      * omitted (so `context.workspaces` is ALWAYS present). `build()` renders the ACTIVE workspace's
      * files by carrier — text files into the system block (fenced), image files attached to the last
      * user message. The registry is structural; change its active workspace through
      * `workspaces.switch(id)`. The active workspace is the SOLE document/image context.
      */
     readonly workspaces?: WorkspaceManagerInterface;
-    /** The initial active scope (the build-time filter); `undefined` ⇒ no filtering. */
+    /** Sets the initial active scope (the build-time filter); `undefined` ⇒ no filtering. */
     readonly scope?: ScopeInterface;
     /**
-     * A pre-built {@link ConversationManagerInterface} to reuse as the message source; a fresh
+     * Reuses a pre-built {@link ConversationManagerInterface} as the message source; a fresh
      * empty one is created when omitted. The context ENSURES an active conversation at construction
      * (it `add`s a default when the manager has none), so `messages` — the manager's ACTIVE
      * conversation's LIVE tail — is ALWAYS defined. `build()` folds the active conversation's
      * `view()` (the per-section summaries + the live tail) as its AUTHORITATIVE message inclusion —
-     * the scope does NOT filter the conversation (it owns inclusion via compaction; scope filters
+     * the scope does NOT filter the conversation (it owns inclusion through compaction; scope filters
      * only instructions / tools / workspace files). The registry is structural; change its active
      * conversation through the manager's `switch(id)`.
      */
@@ -361,25 +361,28 @@ export declare interface AgentContextOptions {
 }
 
 /**
- * Thrown synchronously by an {@link AgentInterface}'s `stream()` when a concurrent run would
- * corrupt SHARED per-agent accounting — carries a machine-readable `code`.
+ * Reports a concurrent run that would corrupt SHARED per-agent accounting, or a rehydration
+ * name absent from its registry pool — thrown synchronously by an {@link AgentInterface}'s
+ * `stream()` and by an {@link AgentRegistryInterface}'s accessors, carrying a machine-readable
+ * `code`.
  *
  * @remarks
- * 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), means a second concurrent `stream()` would race its charges against the same
- * shared instance — corrupting the accounting. `code` is `'CONCURRENCY'` (the only condition
- * so far). Use separate agents, or per-run `budget` overrides with no `window`, for genuinely
- * concurrent runs. Narrow a caught value with {@link isAgentError} and branch on `error.code`.
+ * `'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`.
  */
 export declare class AgentError extends Error {
-    /** The machine-readable condition — `'CONCURRENCY'`: a concurrent run on a shared accounting agent. */
-    readonly code: 'CONCURRENCY';
-    constructor(code: 'CONCURRENCY', message: string);
+    /** Names the machine-readable condition — `'CONCURRENCY'`: a concurrent run on a shared accounting agent; `'REGISTRY'`: a rehydration name absent from its registry pool. */
+    readonly code: 'CONCURRENCY' | 'REGISTRY';
+    constructor(code: 'CONCURRENCY' | 'REGISTRY', message: string);
 }
 
 /**
- * The push observation surface of an {@link AgentInterface} (AGENTS §13) — the
+ * Maps the push observation surface of an {@link AgentInterface} — the
  * lifecycle + usage/tool moments a fire-and-forget observer (logging, metrics,
  * tracing) subscribes to, ALONGSIDE the pull {@link AgentChunk} stream.
  *
@@ -389,10 +392,10 @@ export declare class AgentError extends Error {
  * the chunk stream can't express (a `deny` never reaches the stream) or that a
  * fire-and-forget observer wants without draining the stream. PER-TOKEN deltas stay
  * EXCLUSIVELY the {@link AgentChunk} stream's job (the pull surface) — there is
- * deliberately NO `token` event here. Subscribe via `agent.emitter.on(...)`.
+ * deliberately NO `token` event here. Subscribe through `agent.emitter.on(...)`.
  *
- * Observation is provably side-effect-free on the loop: listener isolation is the emitter's
- * (§13) — every event is emitted directly and a listener throw is routed to the emitter's OWN
+ * Observation is side-effect-free on the loop: listener isolation is the emitter's
+ * — every event is emitted directly and a listener throw is routed to the emitter's OWN
  * `error` handler (the `error` option), never onto this domain map and never into the
  * settle-once / wake-park engine — so a buggy observer can never reorder, throw into, or
  * corrupt the run.
@@ -401,55 +404,80 @@ export declare class AgentError extends Error {
  * PARTIAL result) — so an observer sees both that the run was cancelled and the partial
  * outcome it committed; a genuine error emits `error` instead of `finish`.
  *
- * Declared as a `type` alias (not `interface extends EventMap`, §4.5 — `EventMap` is a
+ * Declared as a `type` alias (not `interface extends EventMap` — `EventMap` is a
  * `type` kind): a type-literal satisfies the `EventMap` constraint
  * (`Record<string, readonly unknown[]>`) structurally, whereas an interface lacks the
  * required index signature.
  */
 export declare type AgentEventMap = {
-    /** A run begins — emitted at the top of `stream()` once `status` is `running`. */
+    /** Reports a run beginning — emitted at the top of `stream()` once `status` is `running`. */
     readonly start: readonly [id: string];
-    /** Each `#run` loop iteration begins — the zero-based turn index. */
+    /** Reports each `#run` loop iteration beginning — the zero-based turn index. */
     readonly turn: readonly [index: number];
-    /** A dispatched {@link ToolCall} paired with its {@link ToolResult} (executed or a denial). */
+    /** Reports a dispatched {@link ToolCall} paired with its {@link ToolResult} (executed or a denial). */
     readonly tool: readonly [call: ToolCall, result: ToolResult];
-    /** A turn reported {@link TokenUsage} — emitted after a usage-bearing provider call. */
+    /** Reports a turn's {@link TokenUsage} — emitted after a usage-bearing provider call. */
     readonly usage: readonly [usage: TokenUsage];
-    /** The authority DENIED a call — the call + the optional reason (NOT in the chunk stream). */
+    /** Reports a call the authority DENIED — the call + the optional reason (NOT in the chunk stream). */
     readonly deny: readonly [call: ToolCall, reason: string | undefined];
-    /** The run settled successfully (a natural finish OR a cancel's partial) — the {@link AgentResult}. */
+    /** Reports the run settled successfully (a natural finish OR a cancel's partial) — the {@link AgentResult}. */
     readonly finish: readonly [result: AgentResult];
-    /** The run settled with a genuine (non-cancel) error — the thrown value (always `unknown`). */
+    /** Reports the run settled with a genuine (non-cancel) error — the thrown value (always `unknown`). */
     readonly error: readonly [error: unknown];
-    /** The run was cancelled (external signal / timeout / budget / `abort()`) — the cancel reason. */
+    /** Reports the run cancelled (external signal / timeout / budget / `abort()`) — the cancel reason. */
     readonly abort: readonly [reason: unknown];
     /**
-     * The loop exhausted its `limit` while still holding unresolved tool intent (the model
+     * Reports the loop exhausting its `limit` while still holding unresolved tool intent (the model
      * requested tools on the very last allowed turn) — the turn count reached. Distinct from
      * `abort`: exhaustion is NOT a cancel (no external signal / timeout / budget tripped), so
      * this fires INSTEAD of `abort`, still followed by `finish` carrying the partial result.
      */
     readonly exhaust: readonly [turns: number];
     /**
-     * AUTOMATIC compaction's summarizer THREW — a NON-FATAL warn channel (the run continues; see
+     * 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
      * (`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.
-     * Distinct from `error` (a GENUINE provider/tool failure that REJECTS the run) — this is a
-     * best-effort optimization that failed. A MANUAL `conversation.compact()` still propagates its
-     * own error; only the agent's AUTO path is resilient. A DOMAIN event (the emitter isolates a
-     * listener throw separately, routing it to its `error` handler).
+     * The run still SETTLES through the other events — `finish` for the lenient default, and
+     * `error` when {@link AgentOptions.strict} rethrows the same caught value — so `fault` reports
+     * the best-effort optimization that failed and never the run's own outcome. A MANUAL
+     * `conversation.compact()` still propagates its own error; only the agent's AUTO path is
+     * resilient. A DOMAIN event (the emitter isolates a listener throw separately, routing it to
+     * its `error` handler).
      */
-    readonly compactError: readonly [error: unknown];
+    readonly fault: readonly [error: unknown];
 };
 
+/**
+ * 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}.
+ * - **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`.
+ * - **Paced + capped.** The `scheduler` (when given) yields between turns; tool
+ *   iteration is capped at `limit` so the loop always terminates.
+ * - **Two observation surfaces.** PULL: the {@link AgentChunk} stream (`stream().events`)
+ *   carries per-token answer deltas, per-think reasoning deltas, and usage/tool chunks for a live consumer. PUSH: the
+ *   {@link emitter} ({@link AgentEventMap}) carries lifecycle + usage/tool/deny moments
+ *   for fire-and-forget observers — the emitter isolates a listener throw and routes it to
+ *   its `error` handler (the `error` option), so a buggy observer can NEVER corrupt the
+ *   loop. Per-token / per-thinking deltas are the stream's job exclusively; there is no
+ *   `token` or `think` event.
+ * - **Per-run overrides.** Both faces accept an optional {@link AgentRunOptions} bag whose
+ *   members override the construction {@link AgentOptions} for that one run.
+ */
 export declare interface AgentInterface {
     readonly emitter: EmitterInterface<AgentEventMap>;
     readonly id: string;
     readonly status: AgentStatus;
     readonly context: AgentContextInterface;
     /**
-     * Run the turn to completion, discarding the live chunks — drains the shared
+     * Runs the turn to completion, discarding the live chunks — drains the shared
      * stream and resolves the settled outcome.
      *
      * @remarks
@@ -460,13 +488,13 @@ export declare interface AgentInterface {
      * 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} (e.g. `think`); omitted ⇒ defaults
+     * @param options - Optional per-run {@link AgentRunOptions} (for example `think`); omitted ⇒ defaults
      * @returns The settled {@link AgentResult} (`partial: true` when cancelled)
      * @throws {AgentError} Synchronously, with `code: 'CONCURRENCY'`, for a concurrent run
      */
     generate(options?: AgentRunOptions): Promise<AgentResult>;
     /**
-     * Run the turn as a live stream — iterate `events` for {@link AgentChunk}s and
+     * Runs the turn as a live stream — iterate `events` for {@link AgentChunk}s and
      * `await result` for the settled outcome.
      *
      * @remarks
@@ -475,13 +503,13 @@ export declare interface AgentInterface {
      * {@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`.
      *
-     * @param options - Optional per-run {@link AgentRunOptions} (e.g. `think`); omitted ⇒ defaults
+     * @param options - Optional per-run {@link AgentRunOptions} (for example `think`); omitted ⇒ defaults
      * @returns A live {@link AgentStreamInterface} handle (events + result + abort)
      * @throws {AgentError} Synchronously, with `code: 'CONCURRENCY'`, for a concurrent run
      */
     stream(options?: AgentRunOptions): AgentStreamInterface;
     /**
-     * Cancel the in-flight turn — fires the turn's signal; the `result` settles
+     * Cancels the in-flight turn — fires the turn's signal; the `result` settles
      * `partial: true` with whatever content accumulated.
      *
      * @param reason - An optional cancellation reason propagated to the signal
@@ -490,9 +518,9 @@ export declare interface AgentInterface {
 }
 
 /**
- * Thrown by an agent-job handler (a `createAgentQueue` / `createAgentRunner` job) when
- * its {@link AgentInterface} run ended {@link AgentResult.partial} and the job's
- * `allowPartial` policy is `false` (the default) — carries the partial
+ * Reports an {@link AgentInterface} run that ended {@link AgentResult.partial} under a
+ * `partial` policy of `false` (the default) — thrown by an agent-job handler (a
+ * `createAgentQueue` / `createAgentRunner` job), carrying the partial
  * {@link AgentResult} so the failure stays inspectable.
  *
  * @remarks
@@ -500,18 +528,22 @@ export declare interface AgentInterface {
  * runner abort threaded in, a `timeout` deadline, or an exhausted token `budget`) rather
  * than finishing naturally. For a durable JOB that is a failure by default: throwing this
  * lets the Queue's retries re-run the job and a Runner's fail-fast abort its siblings.
- * Set `allowPartial: true` (see `AgentQueueOptions` / `AgentRunnerOptions`) to treat a
+ * Set `partial: true` (see `AgentQueueOptions` / `AgentRunnerOptions`) to treat a
  * partial as success instead, in which case this is never thrown. Narrow a caught value
- * with {@link isAgentJobError} to read `partial`.
+ * with {@link isAgentJobError} to read `partial`. `code` is the machine-readable condition
+ * (`'PARTIAL'` — the only one this error reports), so a `catch` branches on it rather than on
+ * the message string.
  */
 export declare class AgentJobError extends Error {
-    /** The partial {@link AgentResult} the cancelled job produced. */
+    /** Names the machine-readable condition — `'PARTIAL'`: a job that ended partial under a disallowing policy. */
+    readonly code: "PARTIAL";
+    /** Holds the partial {@link AgentResult} the cancelled job produced. */
     readonly partial: AgentResult;
     constructor(message: string, partial: AgentResult);
 }
 
 /**
- * A JSON-serializable agent job — the descriptor a durable queue / runner runs. Its
+ * Represents a JSON-serializable agent job — the descriptor a durable queue / runner runs. Its
  * non-serializable pieces (the provider, tools, authority, scheduler) are referenced by
  * NAME and resolved to live objects through an {@link AgentRegistryInterface} at handler
  * time; its data fields (the seed `messages`, `system`, `limit`, `timeout`, and a token
@@ -528,26 +560,26 @@ export declare class AgentJobError extends Error {
  * `budget` is a token ceiling rebuilt into a `createTokenBudget({ max })`.
  */
 export declare interface AgentJobInput {
-    /** The registry key of the {@link ProviderInterface} the job runs against. */
+    /** Names the registry key of the {@link ProviderInterface} the job runs against. */
     readonly provider: string;
-    /** The seed conversation added to the rehydrated agent's context (serializable). */
+    /** Holds the seed conversation added to the rehydrated agent's context (serializable). */
     readonly messages: readonly MessageInput[];
-    /** An optional system prompt seeding the agent's context. */
+    /** Holds an optional system prompt seeding the agent's context. */
     readonly system?: string;
-    /** Registry keys of the {@link ToolInterface}s loaded into the agent's tool manager. */
+    /** Names the registry keys of the {@link ToolInterface}s loaded into the agent's tool manager. */
     readonly tools?: readonly string[];
-    /** The registry key of an optional {@link AuthorityInterface} policy gate. */
+    /** Names the registry key of an optional {@link AuthorityInterface} policy gate. */
     readonly authority?: string;
-    /** The registry key of an optional {@link SchedulerInterface} pacing the loop. */
+    /** Names the registry key of an optional {@link SchedulerInterface} pacing the loop. */
     readonly scheduler?: string;
-    /** Max tool-iteration turns before the loop stops (see {@link AgentOptions.limit}). */
+    /** Caps the tool-iteration turns before the loop stops (see {@link AgentOptions.limit}). */
     readonly limit?: number;
-    /** A wall-clock deadline (ms) for the whole turn (see {@link AgentOptions.timeout}). */
+    /** Sets a wall-clock deadline (ms) for the whole turn (see {@link AgentOptions.timeout}). */
     readonly timeout?: number;
-    /** A token ceiling rebuilt into a `createTokenBudget({ max })` cost bound. */
+    /** Sets a token ceiling rebuilt into a `createTokenBudget({ max })` cost bound. */
     readonly budget?: number;
     /**
-     * Sub-agent jobs this job fans out — each a nested {@link AgentJobInput} (so the whole
+     * Lists the sub-agent jobs this job fans out — each a nested {@link AgentJobInput} (so the whole
      * tree stays serializable). On a `createAgentRunner`, the handler `controller.spawn`s
      * each child through the same bounded queue BEFORE running this (parent) job, so the
      * children run as sibling sub-agents and their results join the run after the declared
@@ -557,7 +589,7 @@ export declare interface AgentJobInput {
 }
 
 /**
- * Options for `createAgent` — bounds and pacing for the agent loop.
+ * Configures `createAgent` — bounds and pacing for the agent loop.
  *
  * @remarks
  * - `system` — an optional system prompt prepended to the turn (seeds the context).
@@ -582,12 +614,12 @@ export declare interface AgentJobInput {
  *   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 `consume` is a token estimator, its `max` the context window) and, when the prompt
+ *   (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
  *   `budget`'s hard abort. Omitted ⇒ no auto-compaction.
  * - `strict` — when `true`, a summarizer failure during AUTOMATIC compaction ABORTS the run
- *   (rethrown after the `compactError` event, propagating through `#run` to a genuine `error`
+ *   (rethrown after the `fault` event, propagating through `#run` to a genuine `error`
  *   settle) instead of skipping compaction and continuing over-window. Defaults to `false`
  *   (lenient — the prior, byte-for-byte behavior).
  * - `instructions` — an optional pre-built {@link InstructionManagerInterface} forwarded to the
@@ -596,34 +628,34 @@ export declare interface AgentJobInput {
  *   agent's context; a fresh empty one is created when omitted (mirrors {@link AgentContextOptions.workspaces}).
  * - `scope` — an optional initial active {@link ScopeInterface} forwarded to the agent's context
  *   (the build-time filter); `undefined` ⇒ no filtering (mirrors {@link AgentContextOptions.scope}).
- * - `on` — the reserved {@link EmitterHooks} key (§8): initial listeners for the agent's
- *   {@link AgentEventMap}, wired at construction (e.g. `{ finish: (r) => log(r) }`).
+ * - `on` — the reserved {@link EmitterHooks} key: initial listeners for the agent's
+ *   {@link AgentEventMap}, wired at construction (for example `{ finish: (r) => log(r) }`).
  */
 export declare interface AgentOptions {
     readonly on?: EmitterHooks<AgentEventMap>;
-    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    /** Holds the emitter's listener-error handler — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
     readonly system?: string;
-    /** A pre-built tool registry the loop dispatches calls through; an empty one is created when omitted. */
+    /** Reuses a pre-built tool registry the loop dispatches calls through; an empty one is created when omitted. */
     readonly tools?: ToolManagerInterface;
-    /** A pre-built instruction registry forwarded to the agent's context; an empty one is created when omitted. */
+    /** Reuses a pre-built instruction registry forwarded to the agent's context; an empty one is created when omitted. */
     readonly instructions?: InstructionManagerInterface;
-    /** A pre-built workspace registry forwarded to the agent's context; a fresh empty one is created when omitted. */
+    /** Reuses a pre-built workspace registry forwarded to the agent's context; a fresh empty one is created when omitted. */
     readonly workspaces?: WorkspaceManagerInterface;
-    /** The initial active scope forwarded to the agent's context (the build-time filter); `undefined` ⇒ no filtering. */
+    /** Sets the initial active scope forwarded to the agent's context (the build-time filter); `undefined` ⇒ no filtering. */
     readonly scope?: ScopeInterface;
-    /** Max tool-iteration turns before the loop stops; defaults to `DEFAULT_AGENT_LIMIT`. */
+    /** Caps the tool-iteration turns before the loop stops; defaults to `DEFAULT_AGENT_LIMIT`. */
     readonly limit?: number;
-    /** A wall-clock deadline (ms) for the whole turn; its abort commits a partial result. */
+    /** Sets a wall-clock deadline (ms) for the whole turn; its abort commits a partial result. */
     readonly timeout?: number;
-    /** A token cost bound; 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. */
     readonly budget?: BudgetInterface<TokenUsage>;
     /** Paces the loop — `yield`ed between turns so the host regains control. */
     readonly scheduler?: SchedulerInterface;
-    /** An external cancel; its abort commits a partial result. */
+    /** Carries an external cancel; its abort commits a partial result. */
     readonly signal?: AbortSignal;
     /**
-     * An optional policy gate consulted before each tool call runs — a denied call is
+     * Holds an optional policy gate consulted before each tool call runs — a denied call is
      * fed back to the model as a denial {@link ToolResult} (a `tool` chunk + a tool
      * message) rather than executed (no tool run, no budget cost), so the model sees the
      * denial and can react; an allowed call dispatches normally. Omitted ⇒ every call
@@ -631,7 +663,7 @@ export declare interface AgentOptions {
      */
     readonly authority?: AuthorityInterface;
     /**
-     * An optional {@link ConversationManagerInterface} that becomes the agent context's MESSAGE
+     * Holds an optional {@link ConversationManagerInterface} that becomes the agent context's MESSAGE
      * SOURCE — forwarded to the {@link AgentContextInterface} the agent builds, so
      * `agent.context.messages` IS its ACTIVE conversation's live tail and `build()` folds that
      * conversation's `view()` (the per-section summaries + the live tail). Omitted ⇒ a fresh
@@ -640,18 +672,18 @@ export declare interface AgentOptions {
      */
     readonly conversations?: ConversationManagerInterface;
     /**
-     * An optional CONTEXT {@link BudgetInterface} for AUTOMATIC compaction. Its `consume` is a
-     * token estimator (e.g. the exported {@link import('./helpers.js').estimateMessages}) and
+     * 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 MessageInterface[]>;
+    readonly window?: BudgetInterface<readonly Message[]>;
     /**
-     * When `true`, a summarizer failure during AUTOMATIC compaction ABORTS the run — the
-     * `compactError` event still fires, then the caught error is RETHROWN so the run settles
+     * If `true`, a summarizer failure during AUTOMATIC compaction ABORTS the run — the
+     * `fault` event still fires, then the caught error is RETHROWN so the run settles
      * `error` instead of continuing over-window. Defaults to `false` (lenient — the run
      * continues over-window, byte-for-byte the prior behavior).
      */
@@ -659,13 +691,13 @@ export declare interface AgentOptions {
 }
 
 /**
- * Options for `createAgentQueue` — the registry that rehydrates jobs, the partial-result
+ * Configures `createAgentQueue` — the registry that rehydrates jobs, the partial-result
  * policy, and the substrate knobs threaded into the backing `createQueue`.
  *
  * @remarks
  * - `registry` — the {@link AgentRegistryInterface} the handler rehydrates each job
  *   through (required).
- * - `allowPartial` — the partial policy. A partial {@link AgentResult} (a job committed
+ * - `partial` — the partial policy. A partial {@link AgentResult} (a job committed
  *   early from an abort / budget / timeout) is by DEFAULT a FAILURE: the handler THROWS
  *   an {@link import('./errors.js').AgentJobError}, so the Queue's retries (and a
  *   Runner's fail-fast) engage. Set `true` to treat a partial as SUCCESS instead — the
@@ -676,8 +708,8 @@ export declare interface AgentOptions {
  */
 export declare interface AgentQueueOptions {
     readonly registry: AgentRegistryInterface;
-    /** A partial `AgentResult` THROWS by default (retries engage); `true` resolves it as success. */
-    readonly allowPartial?: boolean;
+    /** If `true`, a partial `AgentResult` resolves as success; if `false` (the default), it THROWS and retries engage. */
+    readonly partial?: boolean;
     readonly concurrency?: number;
     readonly retries?: number;
     readonly timeout?: number;
@@ -685,10 +717,9 @@ export declare interface AgentQueueOptions {
 }
 
 /**
- * The bridge that makes a durable, JSON-serializable {@link AgentJobInput} runnable —
- * it holds the named pools of live, non-serializable pieces (providers, tools,
- * authorities, schedulers) and rehydrates a seeded, signal-wired {@link Agent} from a
- * job's names + data.
+ * Makes a durable, JSON-serializable {@link AgentJobInput} runnable — holds the named
+ * pools of live, non-serializable pieces (providers, tools, authorities, schedulers) and
+ * rehydrates a seeded, signal-wired {@link Agent} from a job's names + data.
  *
  * @remarks
  * - **Why it exists.** An `AgentJobInput` is serializable so it can survive a crash in a
@@ -696,18 +727,18 @@ export declare interface AgentQueueOptions {
  *   schedulers carrying functions) cannot serialize. The registry closes that gap:
  *   construct it once with the live pools, then a queue / runner handler calls `build`
  *   on each (possibly restored) job to get a ready agent.
- * - **Accessors throw on a miss (§9.1 + §12).** `provider` / `tool` / `authority` /
- *   `scheduler` resolve a name against their pool and THROW `unknown <category>: <name>`
- *   when it is absent — an unknown name in a rehydrated job is a programmer / config
- *   error that must fail LOUDLY at build time, never silently resolve to `undefined` and
- *   run an agent missing a dependency.
+ * - **Accessors throw on a miss.** `provider` / `tool` / `authority` / `scheduler` resolve a
+ *   name against their pool and THROW an {@link AgentError} carrying `code: 'REGISTRY'` and
+ *   the message `unknown <category>: <name>` when it is absent — an unknown name in a
+ *   rehydrated job is a programmer / config error that must fail LOUDLY at build time, never
+ *   silently resolve to `undefined` and run an agent missing a dependency.
  * - **`build` rehydrates.** Resolve the job's `provider`; assemble a fresh
  *   {@link ToolManager} from the `tools` names; rebuild the token `budget` from its
  *   ceiling (`createTokenBudget({ max })`); resolve the optional `authority` /
  *   `scheduler` names; construct the {@link Agent} with `system` / `limit` / `timeout` /
  *   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 `allowPartial` policy then
+ *   into the agent (which commits a partial — the job's `partial` policy then
  *   decides success vs. retry).
  * - **Event-free.** A pure resolver — no Emitter, no events.
  *
@@ -735,11 +766,11 @@ export declare class AgentRegistry implements AgentRegistryInterface {
  * durable, serializable job runnable.
  *
  * @remarks
- * - **Accessors throw on a miss (§9.1 + §12).** `provider` / `tool` / `authority` /
- *   `scheduler` look one up by name and THROW a clear `Error` (`unknown provider:
- *   <name>`, etc.) when the name is unregistered — an unknown name in a rehydrated job
- *   must fail loudly, never silently resolve to `undefined`, so a misconfigured job
- *   surfaces at once rather than running with a missing dependency.
+ * - **Accessors throw on a miss.** `provider` / `tool` / `authority` / `scheduler` look one
+ *   up by name and THROW an {@link AgentError} carrying `code: 'REGISTRY'` and the message
+ *   `unknown <category>: <name>` when the name is unregistered — an unknown name in a
+ *   rehydrated job must fail loudly, never silently resolve to `undefined`, so a
+ *   misconfigured job surfaces at once rather than running with a missing dependency.
  * - **`build` rehydrates.** It resolves the job's `provider`, assembles a
  *   {@link ToolManagerInterface} from the `tools` names, rebuilds the token `budget`
  *   from its ceiling, resolves the `authority` / `scheduler` names, seeds the agent's
@@ -749,7 +780,7 @@ export declare class AgentRegistry implements AgentRegistryInterface {
  */
 export declare interface AgentRegistryInterface {
     /**
-     * Resolve a registered {@link ProviderInterface} by name.
+     * Resolves a registered {@link ProviderInterface} by name.
      *
      * @param name - The provider's registry key
      * @returns The live provider
@@ -757,7 +788,7 @@ export declare interface AgentRegistryInterface {
      */
     provider(name: string): ProviderInterface;
     /**
-     * Resolve a registered {@link ToolInterface} by name.
+     * Resolves a registered {@link ToolInterface} by name.
      *
      * @param name - The tool's registry key
      * @returns The live tool
@@ -765,7 +796,7 @@ export declare interface AgentRegistryInterface {
      */
     tool(name: string): ToolInterface;
     /**
-     * Resolve a registered {@link AuthorityInterface} by name.
+     * Resolves a registered {@link AuthorityInterface} by name.
      *
      * @param name - The authority's registry key
      * @returns The live authority
@@ -773,7 +804,7 @@ export declare interface AgentRegistryInterface {
      */
     authority(name: string): AuthorityInterface;
     /**
-     * Resolve a registered {@link SchedulerInterface} by name.
+     * Resolves a registered {@link SchedulerInterface} by name.
      *
      * @param name - The scheduler's registry key
      * @returns The live scheduler
@@ -781,7 +812,7 @@ export declare interface AgentRegistryInterface {
      */
     scheduler(name: string): SchedulerInterface;
     /**
-     * Rehydrate a live, seeded {@link AgentInterface} from a serializable job — resolving
+     * Rehydrates a live, seeded {@link AgentInterface} from a serializable job — resolving
      * its names, rebuilding its budget, seeding its conversation, and wiring `signal`.
      *
      * @param input - The serializable {@link AgentJobInput} to rehydrate
@@ -793,18 +824,18 @@ export declare interface AgentRegistryInterface {
 }
 
 /**
- * Options for `createAgentRegistry` — the named pools of live, non-serializable pieces
+ * Configures `createAgentRegistry` — the named pools of live, non-serializable pieces
  * a {@link AgentJobInput}'s names resolve against.
  *
  * @remarks
  * `providers` is required (a job always names a provider); `tools` / `authorities` /
- * `schedulers` are optional pools, each an entity-keyed record (§8) mapping a registry
+ * `schedulers` are optional pools, each an entity-keyed record mapping a registry
  * name to its live object. A name absent from its pool throws when resolved (see
  * {@link AgentRegistryInterface}). `store` is the durable {@link ConversationStoreInterface}
  * every agent this registry builds carries: each built agent gets its OWN store-backed
  * {@link ConversationManagerInterface} over THIS shared store — a fresh conversation id per
  * build (minted by the seeded `add`), so concurrent builds never collide, and the store
- * simply accumulates one snapshot per built agent that later calls `save`. Persistence
+ * accumulates one snapshot per built agent that later calls `save`. Persistence
  * stays caller-triggered (`open` / `save`) — `build` never hydrates, so `build` stays
  * SYNCHRONOUS. Omitted ⇒ every built agent gets a registry-only manager, byte-identical
  * to today.
@@ -818,7 +849,7 @@ export declare interface AgentRegistryOptions {
 }
 
 /**
- * The settled outcome of an agent turn — the assembled assistant `content`, the
+ * Holds the settled outcome of an agent turn — the assembled assistant `content`, the
  * `usage` summed across the turn's provider calls, and whether it was committed
  * `partial`.
  *
@@ -834,7 +865,7 @@ export declare interface AgentRegistryOptions {
  * present only when at least one provider call reported usage — an aborted run's `usage`
  * INCLUDES the cancelled turn's tokens when the provider reports partial usage on the
  * abort (folded in exactly like a completed turn's); a provider that cannot observe
- * usage mid-stream (e.g. a daemon whose final counts never arrive before the cancel)
+ * usage mid-stream (for example a daemon whose final counts never arrive before the cancel)
  * reports none for that turn, and none is fabricated. `thinking` is present
  * only when a provider call surfaced reasoning it separated from the answer
  * ({@link ProviderResult.thinking}, joined across the run's calls) — display/audit
@@ -842,15 +873,15 @@ export declare interface AgentRegistryOptions {
  */
 export declare interface AgentResult {
     readonly content: string;
-    /** Reasoning the run's provider calls separated from the answer (present when any surfaced it). */
+    /** Carries reasoning the run's provider calls separated from the answer (present when any surfaced it). */
     readonly thinking?: string;
-    /** The summed {@link TokenUsage} across the turn's provider calls (present when any reported it). */
+    /** Holds the summed {@link TokenUsage} across the turn's provider calls (present when any reported it). */
     readonly usage?: TokenUsage;
     readonly partial: boolean;
 }
 
 /**
- * Project an unknown value onto the canonical JSON representation of an
+ * Projects an unknown value onto the canonical JSON representation of an
  * {@link AgentResult}.
  *
  * @remarks
@@ -876,11 +907,11 @@ export declare interface AgentResult {
 export declare function agentResultToJSON(value: unknown): JSONValue | undefined;
 
 /**
- * Options for `createAgentRunner` — the registry that rehydrates jobs, the partial-result
+ * Configures `createAgentRunner` — the registry that rehydrates jobs, the partial-result
  * policy, and the substrate knobs threaded into the backing `createRunner`.
  *
  * @remarks
- * Identical partial policy to {@link AgentQueueOptions} (`allowPartial` — a partial
+ * Identical partial policy to {@link AgentQueueOptions} (`partial` — a partial
  * `AgentResult` THROWS by default so the run's fail-fast engages, `true` resolves it as
  * success). `concurrency` / `retries` / `timeout` pass straight to the backing
  * `RunnerInterface` (see `RunnerOptions`). The runner enables sub-agent fan-out: a
@@ -889,38 +920,29 @@ export declare function agentResultToJSON(value: unknown): JSONValue | undefined
  */
 export declare interface AgentRunnerOptions {
     readonly registry: AgentRegistryInterface;
-    /** A partial `AgentResult` THROWS by default (fail-fast engages); `true` resolves it as success. */
-    readonly allowPartial?: boolean;
+    /** If `true`, a partial `AgentResult` resolves as success; if `false` (the default), it THROWS and fail-fast engages. */
+    readonly partial?: boolean;
     readonly concurrency?: number;
     readonly retries?: number;
     readonly timeout?: number;
 }
 
 /**
- * The agent loop — composes a {@link ProviderInterface}, an
- * {@link AgentContextInterface}, and a {@link ToolManagerInterface} into a bounded
- * context → provider → tools → repeat turn.
+ * Carries the per-run override bag an {@link AgentInterface}'s `generate` / `stream` accepts — each
+ * member overrides the matching {@link AgentOptions} value for ONE run.
  *
  * @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}.
- * - **Bounded.** Each turn arms a single cancel folded from the external `signal`, the
- *   `timeout` deadline, and the `budget` signal (via `AbortSignal.any`); any of them —
- *   or `abort()` — stops the loop and settles the result `partial: true`.
- * - **Paced + capped.** The `scheduler` (when given) yields between turns; tool
- *   iteration is capped at `limit` so the loop always terminates.
- * - **Two observation surfaces.** PULL: the {@link AgentChunk} stream (`stream().events`)
- *   carries per-token answer deltas, per-think reasoning deltas, and usage/tool chunks for a live consumer. PUSH: the
- *   {@link emitter} ({@link AgentEventMap}) carries lifecycle + usage/tool/deny moments
- *   for fire-and-forget observers — the emitter isolates a listener throw and routes it to
- *   its `error` handler (the `error` option, §13), so a buggy observer can NEVER corrupt the
- *   loop. Per-token / per-thinking deltas are the stream's job exclusively; there is no
- *   `token` or `think` event.
+ * 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
+ * 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.
  */
 export declare interface AgentRunOptions {
     /**
-     * The per-run reasoning preference forwarded to the provider's `stream` as
+     * Sets the per-run reasoning preference forwarded to the provider's `stream` as
      * {@link ProviderStreamOptions.think} — `true` asks the backend to separate reasoning
      * (surfaced as `think` {@link AgentChunk}s + the settled `thinking`), `false` suppresses
      * it. Omitted ⇒ the provider's own default applies (the loop is byte-for-byte the prior
@@ -928,7 +950,7 @@ export declare interface AgentRunOptions {
      */
     readonly think?: boolean;
     /**
-     * Constrain the response to this JSON-Schema shape, forwarded to the provider's `stream`
+     * Constrains the response to this JSON-Schema shape, forwarded to the provider's `stream`
      * as {@link ProviderStreamOptions.schema} — a per-run structured-output request. Omitted ⇒
      * no constraint (the loop is byte-for-byte the prior behaviour).
      */
@@ -950,29 +972,93 @@ export declare interface AgentRunOptions {
      */
     readonly budget?: BudgetInterface<TokenUsage>;
     /**
-     * An additional per-run external cancel, COMPOSED with {@link AgentOptions.signal} (both
-     * fold into the run's bound abort via `AbortSignal.any` — neither is dropped). Omitted ⇒
+     * 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 ⇒
      * only the agent's constructed `signal` (if any) applies.
      */
     readonly signal?: AbortSignal;
 }
 
 /**
- * The lifecycle state of an {@link AgentInterface} turn — `idle` before a run,
+ * Names the lifecycle state of an {@link AgentInterface} turn — `idle` before a run,
  * `running` while the loop is in flight, then the settled `done` (a normal finish or
  * a cancel) or `error` (a genuine provider / tool failure).
  */
 export declare type AgentStatus = 'idle' | 'running' | 'done' | 'error';
 
 /**
- * The agent turn's live handle — a {@link StreamInterface} of {@link AgentChunk}s
+ * Names the agent turn's live handle — a {@link StreamInterface} of {@link AgentChunk}s
  * resolving an {@link AgentResult}.
  */
 export declare type AgentStreamInterface = StreamInterface<AgentChunk, AgentResult>;
 
 /**
- * The synchronous policy gate the agent loop consults before each tool call runs —
- * it turns one {@link AuthorityContextInterface} into an {@link AuthorityDecision}.
+ * Assembles the settled {@link AgentResult} from a run's {@link RunOutcome} — `thinking` and
+ * `usage` are carried only when the run surfaced them.
+ *
+ * @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.
+ *
+ * @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 })
+ * // { content: 'hi', partial: false }
+ * ```
+ */
+export declare function assembleResult(outcome: RunOutcome): AgentResult;
+
+/**
+ * Copies a message with image data merged onto its `images` — the message's own images
+ * first, then the attached data.
+ *
+ * @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).
+ *
+ * @param message - The message to copy (left unchanged)
+ * @param data - The base64 image data to attach
+ * @returns A new message carrying the merged `images`
+ *
+ * @example
+ * ```ts
+ * attachImages({ id: '1', role: 'user', content: 'Describe' }, ['<payload>'])
+ * // { id: '1', role: 'user', content: 'Describe', images: ['<payload>'] }
+ * ```
+ */
+export declare function attachImages(message: Message, data: readonly string[]): Message;
+
+/**
+ * Attaches image data to a conversation's LAST user message — the turn a vision provider
+ * reads images off.
+ *
+ * @remarks
+ * 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).
+ *
+ * @param conversation - The messages to attach into (left unchanged)
+ * @param data - The base64 image data to attach
+ * @returns The conversation with its last user message replaced by the carrying copy
+ *
+ * @example
+ * ```ts
+ * attachUserImages([{ id: '1', role: 'user', content: 'Describe' }], ['<payload>'])
+ * // [{ id: '1', role: 'user', content: 'Describe', images: ['<payload>'] }]
+ * ```
+ */
+export declare function attachUserImages(conversation: readonly Message[], data: readonly string[]): readonly Message[];
+
+/**
+ * Gates the agent loop's tool calls — the synchronous policy consulted before each call
+ * runs, turning one {@link AuthorityContext} into an {@link AuthorityDecision}.
  *
  * @remarks
  * - **Ordered, first-match-wins.** `evaluate` walks the configured rules in order and
@@ -989,8 +1075,7 @@ export declare type AgentStreamInterface = StreamInterface<AgentChunk, AgentResu
  *   back to the model as a denial {@link import('@orkestrel/tool').ToolResult} (a `tool`
  *   chunk + a tool message) instead of being executed — no tool run, no budget cost —
  *   so the model sees the denial and can react.
- * - **Synchronous now.** The async human-approval handshake (request / grant / deny) is
- *   deferred to a later chunk; `evaluate` returns a verdict directly.
+ * - **Synchronous.** `evaluate` returns the verdict directly.
  * - **Event-free.** A purely functional gate — no Emitter, no events.
  *
  * @example
@@ -1006,28 +1091,27 @@ export declare type AgentStreamInterface = StreamInterface<AgentChunk, AgentResu
 export declare class Authority implements AuthorityInterface {
     #private;
     constructor(options?: AuthorityOptions);
-    evaluate(context: AuthorityContextInterface): AuthorityDecision;
+    evaluate(context: AuthorityContext): AuthorityDecision;
 }
 
 /**
- * What an {@link AuthorityInterface} evaluates for one tool call — the call under
+ * Carries what an {@link AuthorityInterface} evaluates for one tool call — the call under
  * consideration.
  *
  * @remarks
- * Lean by design: it carries only the {@link ToolCall} now (the tool `name` and its
+ * Lean by design: it carries the {@link ToolCall} (the tool `name` and its
  * parsed `arguments`), which is enough for a rule to branch on what is being called
- * and with what. It is a seam for richer policy inputs (call history, agent state)
- * later WITHOUT changing the `evaluate` signature — those would join as new fields.
+ * and with what.
  */
-export declare interface AuthorityContextInterface {
+export declare interface AuthorityContext {
     readonly call: ToolCall;
 }
 
 /**
- * An {@link AuthorityInterface}'s verdict on one tool call.
+ * Holds an {@link AuthorityInterface}'s verdict on one tool call.
  *
  * @remarks
- * `zone` is a project-defined classification (e.g. `'default'` / `'sensitive'` /
+ * `zone` is a project-defined classification (for example `'default'` / `'sensitive'` /
  * `'restricted'`) carried for routing + observability; `allowed` is the gate decision
  * (a denied call is fed back to the model, never executed); `reason` is an optional
  * human-readable explanation surfaced in the denial {@link ToolResult}.
@@ -1039,27 +1123,26 @@ export declare interface AuthorityDecision {
 }
 
 /**
- * A synchronous policy gate consulted before each tool call runs — it turns one
- * {@link AuthorityContextInterface} into an {@link AuthorityDecision}.
+ * Gates each tool call before it runs — the synchronous policy that turns one
+ * {@link AuthorityContext} into an {@link AuthorityDecision}.
  *
  * @remarks
  * Ordered first-match-wins over the configured rules, falling back to the configured
- * default when none match (see {@link AuthorityOptions}). Synchronous by design now;
- * the async human-approval handshake (request / grant / deny) is deferred to a later
- * chunk. Event-free — no Emitter, no events.
+ * default when none match (see {@link AuthorityOptions}). `evaluate` is synchronous and
+ * returns the verdict directly. Event-free — no Emitter, no events.
  */
 export declare interface AuthorityInterface {
     /**
-     * Evaluate one tool call against the ordered rules.
+     * Evaluates one tool call against the ordered rules.
      *
-     * @param context - The call under consideration (see {@link AuthorityContextInterface})
+     * @param context - The call under consideration (see {@link AuthorityContext})
      * @returns The first matching rule's verdict, or the fallback when none match
      */
-    evaluate(context: AuthorityContextInterface): AuthorityDecision;
+    evaluate(context: AuthorityContext): AuthorityDecision;
 }
 
 /**
- * Options for `createAuthority` — the ordered rules and the no-match fallback.
+ * Configures `createAuthority` — the ordered rules and the no-match fallback.
  *
  * @remarks
  * `rules` are evaluated in order, first match wins (see {@link AuthorityRule}).
@@ -1075,7 +1158,7 @@ export declare interface AuthorityOptions {
 }
 
 /**
- * One ordered policy rule an {@link AuthorityInterface} evaluates.
+ * Represents one ordered policy rule an {@link AuthorityInterface} evaluates.
  *
  * @remarks
  * The FIRST rule whose `match` returns true decides; if none match, the authority's
@@ -1085,16 +1168,59 @@ export declare interface AuthorityOptions {
  * into the denial {@link ToolResult}).
  */
 export declare interface AuthorityRule {
-    readonly match: (context: AuthorityContextInterface) => boolean;
+    readonly match: (context: AuthorityContext) => boolean;
     readonly zone: string;
     readonly allowed?: boolean;
     readonly reason?: string;
 }
 
 /**
- * A minimal unbounded async channel — the eager pump WRITES chunks into it (`push`)
- * and ends it (`close` / `fail`) regardless of consumption; a consumer READS them back
- * live via the `drain` async-iterator. Decoupling write from read is what lets a
+ * Builds the FRAMED recap message for one compacted section — the same role and stable `id`
+ * as {@link buildSummaryMessage}, with the content prefixed by
+ * {@link import('./constants.js').CONVERSATION_RECAP_PREFIX}.
+ *
+ * @remarks
+ * Pure and total. The prefix is what makes a small model read the message as a CONDENSED
+ * RECAP of earlier turns rather than a literal assistant turn to echo or answer from. It is a
+ * fixed handful of tokens, so a conversation's `view()` stays lean however many sections it
+ * carries.
+ *
+ * @param section - The compacted section to render
+ * @returns The framed recap message
+ *
+ * @example
+ * ```ts
+ * buildRecapMessage({ id: 's1', summary: 'recap', messages: [] })
+ * // { id: 's1', role: 'assistant', content: `${CONVERSATION_RECAP_PREFIX}recap` }
+ * ```
+ */
+export declare function buildRecapMessage(section: Section): Message;
+
+/**
+ * Builds the RAW synthetic summary message for one compacted section — role `'assistant'`,
+ * the section's stable `id`, its `summary` VERBATIM as content.
+ *
+ * @remarks
+ * Pure and total. This is the unframed form the rollup regeneration digests (a
+ * summary-of-summaries over the section summaries); the recap LABEL is a `view()`
+ * presentation concern kept out of what the summarizer re-reads — see
+ * {@link buildRecapMessage}.
+ *
+ * @param section - The compacted section to render
+ * @returns The synthetic summary message
+ *
+ * @example
+ * ```ts
+ * buildSummaryMessage({ id: 's1', summary: 'recap', messages: [] })
+ * // { id: 's1', role: 'assistant', content: 'recap' }
+ * ```
+ */
+export declare function buildSummaryMessage(section: Section): Message;
+
+/**
+ * Buffers chunks in a minimal unbounded async channel — the eager pump WRITES them in
+ * (`push`) and ends it (`close` / `fail`) regardless of consumption; a consumer READS them back
+ * live through the `drain` async-iterator. Decoupling write from read is what lets a
  * producer make progress without a consumer pulling.
  *
  * @remarks
@@ -1115,7 +1241,7 @@ export declare interface AuthorityRule {
  * }
  * ```
  */
-export declare class Channel<T> {
+export declare class Channel<T> implements ChannelInterface<T> {
     #private;
     push(value: T): void;
     close(): void;
@@ -1124,23 +1250,66 @@ export declare class Channel<T> {
 }
 
 /**
- * The PER-RUN auto-compaction state threaded through an {@link AgentInterface}'s loop —
- * a tiny immutable value replaced within a holder created fresh per run (so no state leaks across runs or a
- * conversation switch), mirroring how {@link RunOutcome} is the per-run sink.
+ * Buffers values in an unbounded async channel — a producer WRITES them in (`push`) and
+ * ends it (`close` / `fail`) regardless of consumption, while a consumer READS them back
+ * live through `drain`.
  *
  * @remarks
- * `futile` latches once the loop's between-turns `compact()` resolves `undefined` while
- * the prompt is still over the context window (the v1 single-level limit — the live tail
- * is at/below `keep` and the over-window is structural), so auto-compaction STOPS for the
- * rest of that run (no per-turn churn). Like {@link RunOutcome}, it is INTERNAL loop state
- * — the loop reads + replaces it as it runs, not a caller-facing shape.
+ * Decoupling the write from the read is what lets a producer make progress with nobody
+ * pulling: an agent's eager pump writes each {@link AgentChunk} into one, so the run's
+ * `result` settles whether or not `events` is ever drained. A waiting `drain` parks on a
+ * resolver the next `push` / `close` / `fail` fires, so a value pushed at a parked reader is
+ * delivered rather than dropped. Buffered values are always yielded BEFORE the end is
+ * reported, so a `close` arriving alongside the last values still delivers them. The FIRST
+ * failure wins — a later `close` / `fail` cannot override a recorded error. Event-free.
+ *
+ * @typeParam T - The value type the channel carries
  */
-export declare interface CompactionState {
-    readonly futile: boolean;
+export declare interface ChannelInterface<T> {
+    /**
+     * Writes one value — buffered, then handed to a parked consumer.
+     *
+     * @param value - The value to enqueue
+     */
+    push(value: T): void;
+    /** Ends the channel normally — a draining consumer returns once the buffer is empty. */
+    close(): void;
+    /**
+     * Ends the channel with a failure — a draining consumer throws it once the buffer is empty.
+     *
+     * @param error - The failure to surface (the first one recorded wins)
+     */
+    fail(error: unknown): void;
+    /**
+     * Reads the values back live, in write order.
+     *
+     * @returns A generator yielding each pushed value, returning on `close` and throwing on `fail`
+     */
+    drain(): AsyncGenerator<T, void>;
 }
 
 /**
- * Per-compaction options for {@link ConversationInterface.compact} — overrides for ONE fold.
+ * Collects the `base64` payload of the IMAGE files in a workspace file list — the data an
+ * agent context attaches to the last user message.
+ *
+ * @remarks
+ * Pure and total. `isBinary` NARROWS the tagless content to its binary arm (a total guard,
+ * never an assertion), then the MIME prefix gates it to an image, so a text file and a non-image
+ * binary (a PDF) are both skipped. Order follows the file list.
+ *
+ * @param files - The (already scope-filtered) workspace files
+ * @returns The `base64` payload of each image file, in file order
+ *
+ * @example
+ * ```ts
+ * collectImageData([createFile({ path: 'a.png', content: { base64: '<payload>', mime: 'image/png' } })])
+ * // ['<payload>']
+ * ```
+ */
+export declare function collectImageData(files: readonly FileInterface[]): readonly string[];
+
+/**
+ * Configures one {@link ConversationInterface.compact} call — overrides for ONE fold.
  *
  * @remarks
  * `keep` overrides the conversation's configured retained-tail size for THIS compaction only
@@ -1152,52 +1321,52 @@ export declare interface CompactionState {
  * conversation's own `sections` cap (or unlimited) applies.
  */
 export declare interface CompactOptions {
-    /** Override the retained-tail size for this compaction; omitted ⇒ the conversation's own `keep`. */
+    /** Overrides the retained-tail size for this compaction; omitted ⇒ the conversation's own `keep`. */
     readonly keep?: number;
-    /** Override the `sections` cap for this compaction; omitted ⇒ the conversation's own cap (or unlimited). */
+    /** Overrides the `sections` cap for this compaction; omitted ⇒ the conversation's own cap (or unlimited). */
     readonly sections?: number;
 }
 
 /**
- * A provider's OPTIONAL context-framing default, keyed by section kind — the framing a
- * model prefers (e.g. XML tags vs. Markdown headers), declared by a
+ * Holds a provider's OPTIONAL context-framing default, keyed by section kind — the framing a
+ * model prefers (for example XML tags against Markdown headers), declared by a
  * {@link ProviderInterface} that opts in.
  *
  * @remarks
  * Each key is a {@link ContextSectionFormat} for one of the observable context sections
- * (currently `instructions`), so a provider can frame each section independently — and any
+ * (the `instructions` section), so a provider can frame each section independently — and any
  * it omits falls through to that manager's built-in default. It is the PROVIDER-DEFAULT
  * level of the {@link import('./AgentContext.js').AgentContext} build cascade: it BEATS a
  * manager's built-in default but is BEATEN by a manager-options override and by a per-item
  * override (see {@link AgentContextInterface.build}). It references the ABSTRACT core
  * item interface ({@link InstructionInterface}), so a provider opting in imports it from
- * `@src/core` — the type is provider-agnostic, with no backend coupling. Omitting it
+ * `@orkestrel/agent` — the type is provider-agnostic, with no backend coupling. Omitting it
  * entirely (the default for an agnostic provider) leaves every section on its manager's
  * built-in framing.
  */
-export declare interface ContextFormatInterface {
-    /** The framing for the instructions section; omitted ⇒ that manager's built-in. */
+export declare interface ContextFormat {
+    /** Frames the instructions section; omitted ⇒ that manager's built-in. */
     readonly instructions?: ContextSectionFormat<InstructionInterface>;
 }
 
 /**
- * One context section's optional format override — an `open` / `render` / `close` trio
+ * Overrides one context section's format — an `open` / `render` / `close` trio
  * that frames a section in the {@link import('./AgentContext.js').AgentContext} build
  * cascade: a top line rendered once before the items, a per-item rendering, and a bottom
  * line rendered once after the items.
  *
  * @remarks
- * All three members are OPTIONAL and resolved INDEPENDENTLY (so an override may set only
+ * `open`, `render`, and `close` are OPTIONAL and resolved INDEPENDENTLY (so an override may set only
  * the top, only the per-item rendering, only the bottom, or any mix). A section assembles
  * as `[open, ...items.map(render), close]` with empty / absent slots dropped, the survivors
  * blank-line (`\n\n`) joined — so `open` + `close` together let a developer WRAP the whole
- * group (e.g. `open: '<instructions>'` … `close: '</instructions>'`). `open` is the section's
- * leading text (the header, or a group's opening tag); `render` turns one section item (an
- * {@link InstructionInterface}) into its prompt text; `close` is the trailing text. `open`
- * and `render` cascade through the
+ * group (for example `open: '<instructions>'` … `close: '</instructions>'`). `open` is the
+ * section's leading text (the header, or a group's opening tag); `render` turns one section
+ * item (an {@link InstructionInterface}) into its prompt text; `close` is the trailing text.
+ * `open` and `render` cascade through the
  * built-in floor (`open` ⇒ the manager's built-in header, `render` ⇒ the manager's built-in
- * rendering); `close` has NO built-in, so an unset `close` simply yields no closing line.
- * It is the unit BOTH a provider's {@link ContextFormatInterface} (a per-section-kind
+ * rendering); `close` has NO built-in, so an unset `close` yields no closing line.
+ * It is the unit BOTH a provider's {@link ContextFormat} (a per-section-kind
  * default) and a manager's `Options` carry — see {@link AgentContextInterface.build} for
  * the full precedence.
  *
@@ -1205,29 +1374,54 @@ export declare interface ContextFormatInterface {
  */
 export declare interface ContextSectionFormat<T> {
     /**
-     * Text rendered ONCE before the section's items — the section header or a group's
-     * opening wrapper, e.g. `'<instructions>'`; omitted ⇒ the next cascade level decides
+     * Holds text rendered ONCE before the section's items — the section header or a group's
+     * opening wrapper, for example `'<instructions>'`; omitted ⇒ the next cascade level decides
      * (defaulting to the built-in header).
      */
     readonly open?: string;
-    /** Override one item's rendering; omitted ⇒ the next cascade level decides. */
+    /** Overrides one item's rendering; omitted ⇒ the next cascade level decides. */
     readonly render?: (item: T) => string;
     /**
-     * Text rendered ONCE after the section's items — a group's closing wrapper, e.g.
-     * `'</instructions>'`; omitted ⇒ no closing line (there is no built-in close).
+     * Holds text rendered ONCE after the section's items — a group's closing wrapper, for
+     * example `'</instructions>'`; omitted ⇒ no closing line (there is no built-in close).
      */
     readonly close?: string;
 }
 
 /**
- * A conversation grouping messages ABOVE a flat message store — a live uncompacted tail it
- * OWNS DIRECTLY plus compacted, summarized {@link SectionInterface}s and a regenerated rollup
+ * Exposes the manager surface one context section's format cascade reads — its built-in
+ * `open` / `render`, plus the raw options override the cascade layers a provider
+ * default beneath.
+ *
+ * @remarks
+ * The narrow contract the cascade resolvers
+ * ({@link import('./helpers.js').resolveOpen} / {@link import('./helpers.js').resolveClose} /
+ * {@link import('./helpers.js').resolveItem}) take, so they stay independent of WHICH manager
+ * supplies the section: an {@link InstructionManagerInterface} satisfies it structurally.
+ * `open` and `render` already encapsulate `[options-override → built-in]` (so a manager
+ * used standalone renders correctly), and `format` exposes the raw override so `build()` can
+ * interleave the provider default BENEATH it.
+ *
+ * @typeParam T - The section item this source renders
+ */
+export declare interface ContextSectionSourceInterface<T> {
+    /** Names the built-in section header (already resolved against the manager-options override). */
+    readonly open: string;
+    /** Holds the raw manager-options override, or `undefined` when none was supplied. */
+    readonly format: ContextSectionFormat<T> | undefined;
+    /** Renders one item (already resolved against the manager-options override). */
+    render(item: T): string;
+}
+
+/**
+ * Represents a conversation — a live uncompacted tail of messages it OWNS DIRECTLY ABOVE a
+ * flat message store, plus compacted, summarized {@link Section}s and a regenerated rollup
  * `summary`, with on-demand `rehydrate` and substring `search`, driven by a provider-agnostic
- * {@link ConversationSummarizer} seam (so `core` never imports a provider).
+ * {@link ConversationSummaryHandler} seam (so `core` never imports a provider).
  *
  * @remarks
  * - **Live tail + sections.** The conversation OWNS its live tail DIRECTLY — `#messages` is an
- *   insertion-ordered `Map` of immutable {@link MessageInterface}s keyed by their minted id
+ *   insertion-ordered `Map` of immutable {@link Message}s keyed by their minted id
  *   (the SAME store mechanics a flat manager had, folded in: `add` / `message` / `messages` /
  *   `remove` / `clear` / `count`), exactly as a `Workspace` owns its files (no separate
  *   per-value manager). `#sections` are the compacted history (oldest → newest), each a
@@ -1245,10 +1439,10 @@ export declare interface ContextSectionFormat<T> {
  *   THROWS a {@link ConversationError} when no `#summarize` was supplied. Two summarizer calls
  *   per compaction.
  * - **`rehydrate(id)` / `search(query)`.** `rehydrate` returns a section's full original
- *   messages (`[]` for an unknown id) and emits `rehydrate` — a pure read (v1 never
- *   auto-reinserts). `search` is a case-insensitive substring scan of `content` across ALL
- *   messages (every section's originals + the live tail).
- * - **Observable (§13).** The owned {@link emitter} ({@link ConversationEventMap}) carries
+ *   messages (`[]` for an unknown id) and emits `rehydrate` — a pure read (the caller decides
+ *   whether to re-add them; `rehydrate` never reinserts). `search` is a case-insensitive
+ *   substring scan of `content` across ALL messages (every section's originals + the live tail).
+ * - **Observable.** The owned {@link emitter} ({@link ConversationEventMap}) carries
  *   `compact` / `summary` / `rehydrate`, emitted directly, strictly AFTER the state change;
  *   the emitter isolates a listener throw and routes it to its `error` handler (the `error`
  *   option), so a buggy observer can never corrupt a compaction.
@@ -1267,30 +1461,30 @@ export declare interface ContextSectionFormat<T> {
  */
 export declare class Conversation implements ConversationInterface {
     #private;
-    constructor(options?: ConversationOptions, seed?: ConversationSnapshot);
+    constructor(options?: ConversationOptions);
     get id(): string;
     get emitter(): EmitterInterface<ConversationEventMap>;
     get summary(): string | undefined;
-    get sections(): readonly SectionInterface[];
+    get sections(): readonly Section[];
     get summarizable(): boolean;
     get count(): number;
-    add(input: MessageInput): MessageInterface;
-    add(inputs: readonly MessageInput[]): readonly MessageInterface[];
-    message(id: string): MessageInterface | undefined;
-    messages(): readonly MessageInterface[];
+    add(input: MessageInput): Message;
+    add(inputs: readonly MessageInput[]): readonly Message[];
+    message(id: string): Message | undefined;
+    messages(): readonly Message[];
     remove(id: string): boolean;
     remove(ids: readonly string[]): boolean;
     clear(): void;
-    view(): readonly MessageInterface[];
-    compact(options?: CompactOptions): Promise<SectionInterface | undefined>;
-    rehydrate(id: string): readonly MessageInterface[];
-    search(query: string): readonly MessageInterface[];
+    view(): readonly Message[];
+    compact(options?: CompactOptions): Promise<Section | undefined>;
+    rehydrate(id: string): readonly Message[];
+    search(query: string): readonly Message[];
     reference(options?: ConversationReferenceOptions): string;
     snapshot(): ConversationSnapshot;
 }
 
 /**
- * The framing label a {@link ConversationInterface}'s `view()` prefixes onto each compacted
+ * Names the framing label a {@link ConversationInterface}'s `view()` prefixes onto each compacted
  * section's summary so a small model reads it as a CONDENSED RECAP of earlier turns — not a
  * literal assistant turn to echo or treat as the live answer.
  *
@@ -1306,70 +1500,71 @@ export declare class Conversation implements ConversationInterface {
 export declare const CONVERSATION_RECAP_PREFIX = "[Summary of earlier messages] ";
 
 /**
- * Thrown by a {@link ConversationInterface}'s `compact()` when the conversation has no
- * {@link ConversationSummarizer} to fold its messages with, or when its `sections` cap is
- * structurally invalid — carries a machine-readable `code`.
+ * Reports a conversation with no {@link ConversationSummaryHandler} to fold its messages
+ * with, or with a structurally invalid `sections` cap — thrown by a
+ * {@link ConversationInterface}'s `compact()`, carrying a machine-readable `code`.
  *
  * @remarks
  * Compaction REQUIRES a summarizer (it digests the folded slice into a section summary and
  * regenerates the rollup); a conversation created without one can still store + `view()` its
- * live tail, but a `compact()` is a programmer error (§12) and throws this with `'SUMMARIZER'`.
- * A `sections` cap (§F2, on {@link import('./types.js').ConversationOptions} /
+ * live tail, but a `compact()` 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'`. Narrow a caught value with
  * {@link isConversationError} and branch on `error.code`.
  */
 export declare class ConversationError extends Error {
-    /** The machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer; `'SECTIONS'`: a sub-1 `sections` cap. */
+    /** Names the machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer; `'SECTIONS'`: a sub-1 `sections` cap. */
     readonly code: 'SUMMARIZER' | 'SECTIONS';
     constructor(code: 'SUMMARIZER' | 'SECTIONS', message: string);
 }
 
 /**
- * The push observation surface (§13) of a {@link ConversationInterface} — the compaction
- * moments a fire-and-forget observer subscribes to via `conversation.emitter.on`.
+ * Maps the push observation surface of a {@link ConversationInterface} — the compaction
+ * moments a fire-and-forget observer subscribes to through `conversation.emitter.on`.
  *
  * @remarks
- * `compact` carries the newly-folded {@link SectionInterface}; `collapse` carries a section
+ * `compact` carries the newly-folded {@link Section}; `collapse` carries a section
  * created by folding multiple OLDER sections together (a bounded-`sections` cap enforcement,
  * distinct from `compact`'s fresh live-tail fold); `summary` carries the regenerated
  * conversation rollup (refreshed on each compaction); `rehydrate` carries the `id` of a
- * section whose originals were pulled back. Listener isolation is the emitter's
- * (§13): every event is emitted directly and a listener throw is routed to the emitter's
+ * section whose originals were pulled back. Listener isolation is the emitter's:
+ * every event is emitted directly and a listener throw is routed to the emitter's
  * `error` handler (the `error` option), never onto this map, so a buggy observer can never
- * corrupt a compaction. A `type` alias (not `interface extends EventMap`, §4.5) so the
+ * corrupt a compaction. A `type` alias (not `interface extends EventMap`) so the
  * type-literal satisfies `EventMap` structurally.
  */
 export declare type ConversationEventMap = {
-    /** A new section was folded from the live tail — the created section. */
-    readonly compact: readonly [section: SectionInterface];
-    /** The conversation rollup was regenerated — the new summary text. */
+    /** Reports a new section folded from the live tail — the created section. */
+    readonly compact: readonly [section: Section];
+    /** Reports the conversation rollup regenerated — the new summary text. */
     readonly summary: readonly [summary: string];
-    /** A section's original messages were pulled back — the section's `id`. */
+    /** Reports a section's original messages pulled back — the section's `id`. */
     readonly rehydrate: readonly [id: string];
     /**
-     * The bounded-`sections` cap folded the oldest sections into ONE merged section — the
-     * merged {@link SectionInterface} that replaced them.
+     * Reports the bounded-`sections` cap folding the oldest sections into ONE merged section — the
+     * merged {@link Section} that replaced them.
      */
-    readonly collapse: readonly [section: SectionInterface];
+    readonly collapse: readonly [section: Section];
 };
 
 /**
- * The data to author a {@link ConversationInterface} through a
+ * Carries the data to author a {@link ConversationInterface} through a
  * {@link ConversationManagerInterface} — the optional `id`, a `summarize` override, a `keep`
  * override, and the reserved `on` hooks.
  *
  * @remarks
  * `id` is the conversation's identity (minted when omitted). `summarize` OVERRIDES the
- * manager's default {@link ConversationSummarizer} for this conversation (omitted ⇒ the
+ * manager's default {@link ConversationSummaryHandler} for this conversation (omitted ⇒ the
  * manager's default flows in). `keep` overrides the manager's default retained-tail size.
- * `sections` overrides the manager's default `sections` cap. `on` is the §8 reserved key
+ * `sections` overrides the manager's default `sections` cap. `on` is the reserved listener key
  * (initial {@link ConversationEventMap} listeners). `snapshot` is
  * the construction-time hydration seam — a {@link ConversationSnapshot} whose `id` / `summary` /
  * `sections` / live tail are RESTORED into the new conversation (the live `summarize` / `keep` /
  * `on` re-supplied alongside it), the conversation analogue of
- * {@link import('@orkestrel/workspace').WorkspaceOptions}'s `seed` that a
+ * {@link import('@orkestrel/workspace').WorkspaceOptions}'s `seed`, carried onto
+ * {@link ConversationOptions.snapshot}, that a
  * {@link ConversationManagerInterface.open} reads a stored snapshot back through; hydration is
  * silent (no events). When both `snapshot.id` and `id` are given, `snapshot.id` wins (the snapshot
  * IS the conversation's identity).
@@ -1377,21 +1572,21 @@ export declare type ConversationEventMap = {
 export declare interface ConversationInput {
     readonly id?: string;
     /** Overrides the manager's default summarizer for this conversation. */
-    readonly summarize?: ConversationSummarizer;
+    readonly summarize?: ConversationSummaryHandler;
     /** Overrides the manager's default retained-tail size for this conversation. */
     readonly keep?: number;
     /** Overrides the manager's default `sections` cap for this conversation. */
     readonly sections?: number;
     readonly on?: EmitterHooks<ConversationEventMap>;
-    /** A {@link ConversationSnapshot} to hydrate from, analogous to the workspace package's seed input. */
+    /** Hydrates from a {@link ConversationSnapshot}, passed on as {@link ConversationOptions.snapshot}. */
     readonly snapshot?: ConversationSnapshot;
 }
 
 /**
- * A conversation grouping messages ABOVE the flat {@link MessageManagerInterface} — a live
- * uncompacted tail plus compacted, summarized {@link SectionInterface}s and a conversation
+ * Groups messages ABOVE the flat {@link MessageManagerInterface} — a live
+ * uncompacted tail plus compacted, summarized {@link Section}s and a conversation
  * rollup `summary`, with on-demand `rehydrate` and substring `search`, driven by a
- * provider-agnostic {@link ConversationSummarizer} seam.
+ * provider-agnostic {@link ConversationSummaryHandler} seam.
  *
  * @remarks
  * - **Live tail + sections.** The conversation OWNS its LIVE uncompacted tail DIRECTLY — a
@@ -1401,109 +1596,110 @@ export declare interface ConversationInput {
  *   (oldest → newest), each a summarized slice that RETAINS its originals. `summary` is the
  *   conversation rollup (a summary-of-summaries over all sections), regenerated on each
  *   compaction (`undefined` until the first compaction).
- * - **Message verbs (the inlined store).** `add` takes one {@link MessageInput} or a batch
- *   (§9.2), MINTS each message's `id` (a random UUID), stores it, and returns the created
+ * - **Message verbs (the inlined store).** `add` takes one {@link MessageInput} or a batch,
+ *   MINTS each message's `id` (a random UUID), stores it, and returns the created
  *   message(s); a stored message is immutable. `message(id)` resolves one (`undefined` when
  *   absent); `messages()` lists the live tail in insertion order; `remove` drops one by id or
- *   a batch (§9.2); `clear` empties the tail; `count` is how many live messages are stored.
+ *   a batch (`true` only when EVERY supplied id was removed); `clear` empties the tail;
+ *   `count` is how many live messages are stored.
  * - **`view()` — the model input.** Each section folds to ONE synthetic summary message,
  *   followed by the live messages verbatim: `[...sections-as-summary-messages, ...live]`. The
  *   rollup `summary` is NOT injected (it is a separately pull-able digest for a
  *   cross-conversation case); `view()` carries the per-section summaries, which ARE the
  *   compaction benefit.
  * - **`compact()` — fold older live → a section.** Folds the oldest `count - keep` live
- *   messages into a new {@link SectionInterface} (its `summary` from `summarize`), removes
+ *   messages into a new {@link Section} (its `summary` from `summarize`), removes
  *   them from the live tail, REGENERATES the rollup (a second `summarize` over all section
  *   summaries), and emits `summary` then `compact` — returning the new section (or
  *   `undefined` when nothing folds). TWO summarizer calls per compaction (the section digest
  *   + the rollup). Throws a {@link import('./errors.js').ConversationError} when no
  *   `summarize` was supplied.
  * - **`summarizable` — whether a `compact()` CAN fold.** `true` when a
- *   {@link ConversationSummarizer} was supplied, `false` otherwise. The agent loop's AUTOMATIC
+ *   {@link ConversationSummaryHandler} was supplied, `false` otherwise. The agent loop's AUTOMATIC
  *   compaction (`AgentOptions.window`) gates 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.
  * - **`rehydrate(id)` / `search(query)` — read the retained originals.** `rehydrate` returns
  *   a section's full original messages (`[]` for an unknown id) and emits `rehydrate` — a
- *   pure READ (the caller decides whether to re-add them; v1 never auto-reinserts).
+ *   pure READ (the caller decides whether to re-add them; `rehydrate` never reinserts).
  *   `search` is a case-insensitive substring scan of `content` across ALL messages (every
  *   section's originals + the live tail).
  * - **`reference(options?)` — pull THIS conversation into ANOTHER with provenance.** A PURE
  *   string render (no model call) of a self-labeled, fenced cross-conversation block — the
  *   rollup `summary` (when included + present) plus cherry-picked excerpts — framed so a small
- *   model reads it as FOREIGN material. Written into the ACTIVE conversation's context via the
- *   active workspace (`context.workspaces.active?.write(path, block)`); the cherry-pick comes
- *   from this conversation's own `search` / `rehydrate`, never its whole history.
- * - **Observable (§13).** The owned `emitter` ({@link ConversationEventMap}) carries
+ *   model reads it as FOREIGN material. Written into the ACTIVE conversation's context through
+ *   the active workspace (`context.workspaces.active?.write(path, block)`); the cherry-pick
+ *   comes from this conversation's own `search` / `rehydrate`, never its whole history.
+ * - **Observable.** The owned `emitter` ({@link ConversationEventMap}) carries
  *   `compact` / `summary` / `rehydrate`; the emitter isolates a listener throw and routes it
- *   to its `error` handler (the `error` option, §13).
+ *   to its `error` handler (the `error` option).
  */
 export declare interface ConversationInterface {
     readonly id: string;
     readonly emitter: EmitterInterface<ConversationEventMap>;
-    /** The conversation rollup (a summary-of-summaries), regenerated on each compaction; `undefined` until the first. */
+    /** Holds the conversation rollup (a summary-of-summaries), regenerated on each compaction; `undefined` until the first. */
     readonly summary: string | undefined;
-    /** The compacted history, oldest → newest. */
-    readonly sections: readonly SectionInterface[];
+    /** Lists the compacted history, oldest → newest. */
+    readonly sections: readonly Section[];
     /**
-     * Whether a `compact()` CAN fold — `true` when a {@link ConversationSummarizer} was supplied.
+     * Reports whether a `compact()` CAN fold — `true` when a {@link ConversationSummaryHandler} was supplied.
      * The agent loop's AUTOMATIC compaction (`AgentOptions.window`) gates 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.
      */
     readonly summarizable: boolean;
-    /** How many LIVE (uncompacted) messages are stored in the tail. */
+    /** Counts the LIVE (uncompacted) messages stored in the tail. */
     readonly count: number;
     /**
-     * Append one message to the live tail (or a batch, §9.2) — MINTS each message's `id`
+     * Appends one message to the live tail (or a batch) — MINTS each message's `id`
      * (a random UUID) and returns the created message(s); a stored message is immutable.
      *
      * @param input - One {@link MessageInput}, or a batch
-     * @returns The created {@link MessageInterface}(s), with their minted `id`s
+     * @returns The created {@link Message}(s), with their minted `id`s
      */
-    add(input: MessageInput): MessageInterface;
-    add(inputs: readonly MessageInput[]): readonly MessageInterface[];
+    add(input: MessageInput): Message;
+    add(inputs: readonly MessageInput[]): readonly Message[];
     /**
-     * Look up one LIVE message by id.
+     * Looks up one LIVE message by id.
      *
      * @param id - The message id to resolve
-     * @returns The {@link MessageInterface}, or `undefined` when absent
+     * @returns The {@link Message}, or `undefined` when absent
      */
-    message(id: string): MessageInterface | undefined;
+    message(id: string): Message | undefined;
     /**
-     * Every LIVE (uncompacted) message in the tail, in insertion order.
+     * Lists every LIVE (uncompacted) message in the tail, in insertion order.
      *
      * @returns The live tail, in insertion order
      */
-    messages(): readonly MessageInterface[];
+    messages(): readonly Message[];
     /**
-     * Remove one LIVE message by id (or a batch, §9.2) from the tail.
+     * Removes one LIVE message by id (or a batch) from the tail.
      *
      * @param id - One message id, or a batch
-     * @returns `true` when any was removed
+     * @returns True when every supplied id was present and removed; false otherwise
      */
     remove(id: string): boolean;
     remove(ids: readonly string[]): boolean;
-    /** Empty the live tail (the compacted `sections` are untouched). */
+    /** Empties the live tail (the compacted `sections` are untouched). */
     clear(): void;
     /**
-     * The model input for the next turn — each section as ONE synthetic summary message,
+     * Builds the model input for the next turn — each section as ONE synthetic summary message,
      * then the live messages verbatim (the rollup `summary` is NOT injected).
      *
      * @returns `[...sections-as-summary-messages, ...live messages]`
      */
-    view(): readonly MessageInterface[];
+    view(): readonly Message[];
     /**
-     * Fold the older live messages into a summarized {@link SectionInterface}, regenerate the
-     * rollup, and emit `summary` then `compact`.
+     * Folds the older live messages into a summarized {@link Section}, regenerates the
+     * rollup, and emits `summary` then `compact`.
      *
      * @remarks
      * Folds the oldest `count - keep` live messages (`keep` from `options`, else the
      * conversation's own); when `count <= keep` NOTHING folds and this is a no-op resolving
      * `undefined`. Otherwise it summarizes the slice into the section, removes those messages
      * from the live tail, regenerates the rollup (a second `summarize` over all sections), and
-     * resolves the new section. Requires a {@link ConversationSummarizer} — THROWS a
+     * resolves the new section. Requires a {@link ConversationSummaryHandler} — THROWS a
      * {@link import('./errors.js').ConversationError} when none was supplied.
      *
      * @remarks
@@ -1514,26 +1710,26 @@ export declare interface ConversationInterface {
      * propagates; the next successful `compact()` self-heals the section count back to `cap`.
      *
      * @param options - Optional {@link CompactOptions} (`keep` overrides the retained-tail size)
-     * @returns The new {@link SectionInterface}, or `undefined` when nothing folded
+     * @returns The new {@link Section}, or `undefined` when nothing folded
      */
-    compact(options?: CompactOptions): Promise<SectionInterface | undefined>;
+    compact(options?: CompactOptions): Promise<Section | undefined>;
     /**
-     * A section's full original messages — a pure READ that emits `rehydrate`.
+     * Returns a section's full original messages — a pure READ that emits `rehydrate`.
      *
-     * @param id - The {@link SectionInterface} `id` to pull back
+     * @param id - The {@link Section} `id` to pull back
      * @returns The section's retained original messages (empty when no such section)
      */
-    rehydrate(id: string): readonly MessageInterface[];
+    rehydrate(id: string): readonly Message[];
     /**
-     * Case-insensitive substring search over `content` across ALL messages — every section's
+     * Searches `content` for a case-insensitive substring across ALL messages — every section's
      * retained originals plus the live tail.
      *
      * @param query - The substring to match (case-insensitive)
      * @returns The matching messages, sections' originals first then the live tail
      */
-    search(query: string): readonly MessageInterface[];
+    search(query: string): readonly Message[];
     /**
-     * Render THIS conversation as a self-labeled, fenced PROVENANCE block to pull INTO another
+     * Renders THIS conversation as a self-labeled, fenced PROVENANCE block to pull INTO another
      * conversation — a pure string (NO model call), framed so a small model reads it as FOREIGN
      * material, not as part of the live thread.
      *
@@ -1554,7 +1750,7 @@ export declare interface ConversationInterface {
      */
     reference(options?: ConversationReferenceOptions): string;
     /**
-     * Serialize this conversation to a plain, JSON-serializable {@link ConversationSnapshot} — its
+     * Serializes this conversation to a plain, JSON-serializable {@link ConversationSnapshot} — its
      * `id`, the rollup `summary`, the compacted `sections`, and the live tail (its `messages()`).
      *
      * @remarks
@@ -1562,8 +1758,8 @@ export declare interface ConversationInterface {
      * {@link ConversationStoreInterface} persistence seam's payload, the exact analogue of
      * {@link import('@orkestrel/workspace').WorkspaceInterface}'s `snapshot`. The summarizer /
      * `keep` are NOT serialized — they are live
-     * CONFIG re-supplied on hydrate (a `ConversationSummarizer` is a function, not data). The snapshot
-     * is the durable analogue of the constructor `seed`: a {@link ConversationManagerInterface}
+     * CONFIG re-supplied on hydrate (a `ConversationSummaryHandler` is a function, not data). The snapshot
+     * is the durable analogue of the `snapshot` option: a {@link ConversationManagerInterface}
      * HYDRATES a conversation from it through that seam (see {@link ConversationManagerInterface.open}).
      * Pure — the sections + messages are already plain immutable records (so the snapshot
      * `structuredClone`s / JSON-round-trips losslessly), and snapshotting mutates nothing.
@@ -1574,8 +1770,8 @@ export declare interface ConversationInterface {
 }
 
 /**
- * The registry of {@link Conversation}s keyed by `id`, in insertion order, WITH an active pointer
- * — the §9 store over the conversation layer PLUS the `active` / `switch` seam the
+ * Registers {@link Conversation}s keyed by `id`, in insertion order, WITH an active pointer
+ * — the id-keyed store over the conversation layer PLUS the `active` / `switch` seam the
  * {@link import('../AgentContext.js').AgentContext} renders. Event-free (a registry, like
  * {@link import('@orkestrel/workspace').WorkspaceManager}); the observability lives
  * on each {@link Conversation}.
@@ -1592,8 +1788,8 @@ export declare interface ConversationInterface {
  *   `switch(id)` re-points `active` to the conversation with `id` and returns it; an unknown `id`
  *   returns `undefined` and leaves `active` unchanged (the lenient lookup style — never throws,
  *   no new error code).
- * - **Removal.** `remove` drops one by id, or a batch (§9.2) — `true` when any was removed;
- *   removing the ACTIVE conversation sets `active` to `undefined`. `clear` empties the registry
+ * - **Removal.** `remove` drops one by id, or a batch — `true` only when EVERY supplied id was
+ *   removed; removing the ACTIVE conversation sets `active` to `undefined`. `clear` empties the registry
  *   and sets `active` to `undefined`.
  * - **Event-free.** A purely registry store — no Emitter, no events (each conversation owns
  *   its own observable `emitter`).
@@ -1624,8 +1820,8 @@ export declare class ConversationManager implements ConversationManagerInterface
 }
 
 /**
- * A registry of {@link ConversationInterface}s keyed by their `id`, in insertion order, WITH an
- * active pointer — the §9 store over the conversation layer PLUS the `active` / `switch` seam the
+ * Registers {@link ConversationInterface}s keyed by their `id`, in insertion order, WITH an
+ * active pointer — the id-keyed store over the conversation layer PLUS the `active` / `switch` seam the
  * {@link AgentContextInterface} renders. Event-free (a registry, like
  * {@link import('@orkestrel/workspace').WorkspaceManagerInterface}); the observability lives on each
  * {@link ConversationInterface}.
@@ -1642,12 +1838,12 @@ export declare class ConversationManager implements ConversationManagerInterface
  *   `switch(id)` re-points `active` to the conversation with `id` and returns it; an unknown
  *   `id` returns `undefined` and leaves `active` unchanged (the lenient lookup style — never
  *   throws, no new error code).
- * - **Removal.** `remove` drops one by id, or a batch (§9.2, array overload FIRST) — `true`
- *   when any was removed; removing the ACTIVE conversation sets `active` to `undefined`. `clear`
+ * - **Removal.** `remove` drops one by id, or a batch (array overload FIRST) — `true`
+ *   only when EVERY supplied id was removed; removing the ACTIVE conversation sets `active` to `undefined`. `clear`
  *   empties the registry and sets `active` to `undefined`.
  * - **Durable open / save (the optional `store` seam).** When a {@link ConversationStoreInterface}
  *   is supplied (the `store` option), `open(id)` HYDRATES a conversation from the store on a registry
- *   miss (rebuilding it through the constructor `seed` from the snapshot, flowing the manager's
+ *   miss (rebuilding it through the `snapshot` option, flowing the manager's
  *   default `summarize` / `keep` in) and `save(id)` PERSISTS a registered conversation's
  *   {@link ConversationInterface.snapshot}. Both are LENIENT without a store — `open` resolves only
  *   registered ids, `save` is a no-op (`false`) — consistent with the lenient `switch`. It mirrors
@@ -1657,20 +1853,20 @@ export declare class ConversationManager implements ConversationManagerInterface
  */
 export declare interface ConversationManagerInterface {
     readonly count: number;
-    /** The active conversation — the agent's message source the context renders; `undefined` until the first `add`. */
+    /** Holds the active conversation — the agent's message source the context renders; `undefined` until the first `add`. */
     readonly active: ConversationInterface | undefined;
     conversation(id: string): ConversationInterface | undefined;
     conversations(): readonly ConversationInterface[];
     add(input?: ConversationInput): ConversationInterface;
     switch(id: string): ConversationInterface | undefined;
     /**
-     * Resolve a conversation by id, ACTIVATING it — from the registry if present, else HYDRATED from
+     * Resolves a conversation by id, ACTIVATING it — from the registry if present, else HYDRATED from
      * the optional {@link ConversationStoreInterface} (`store`).
      *
      * @remarks
      * - If `id` is ALREADY registered, it is ACTIVATED (`switch`ed to) and returned — no store hit.
      * - Else if a `store` is set, `store.get(id)` is awaited; on a HIT the snapshot is rehydrated
-     *   into a fresh {@link ConversationInterface} through the constructor `seed`
+     *   into a fresh {@link ConversationInterface} through the `snapshot` option
      *   (`add({ snapshot, ... })`, flowing the manager's default `summarize` / `keep` in), which
      *   registers AND activates it, and it is returned.
      * - Else (no store, or a store MISS) ⇒ `undefined` (lenient — no throw).
@@ -1680,7 +1876,7 @@ export declare interface ConversationManagerInterface {
      */
     open(id: string): Promise<ConversationInterface | undefined>;
     /**
-     * Persist a REGISTERED conversation's {@link ConversationInterface.snapshot} to the optional
+     * Persists a REGISTERED conversation's {@link ConversationInterface.snapshot} to the optional
      * {@link ConversationStoreInterface} (`store`).
      *
      * @remarks
@@ -1689,7 +1885,7 @@ export declare interface ConversationManagerInterface {
      * `false` — never a throw, consistent with the lenient `switch`.
      *
      * @param id - The id of the registered conversation to persist
-     * @returns `true` when the snapshot was persisted; `false` when no store / unknown id
+     * @returns True if the snapshot was persisted; false otherwise (no store, or an unknown id)
      */
     save(id: string): Promise<boolean>;
     remove(ids: readonly string[]): boolean;
@@ -1698,7 +1894,7 @@ export declare interface ConversationManagerInterface {
 }
 
 /**
- * Options for `createConversationManager` — the default {@link ConversationSummarizer} and
+ * Configures `createConversationManager` — the default {@link ConversationSummaryHandler} and
  * retained-tail size the conversations it creates inherit.
  *
  * @remarks
@@ -1711,14 +1907,14 @@ export declare interface ConversationManagerInterface {
  * overrides it); omitted ⇒ unlimited.
  */
 export declare interface ConversationManagerOptions {
-    /** The default summarizer for conversations this manager creates (a per-`add` override wins). */
-    readonly summarize?: ConversationSummarizer;
-    /** The default retained-tail size (a per-`add` override wins); defaults to `DEFAULT_CONVERSATION_KEEP`. */
+    /** Supplies the default summarizer for conversations this manager creates (a per-`add` override wins). */
+    readonly summarize?: ConversationSummaryHandler;
+    /** Sets the default retained-tail size (a per-`add` override wins); defaults to `DEFAULT_CONVERSATION_KEEP`. */
     readonly keep?: number;
-    /** The default `sections` cap for conversations this manager creates (a per-`add` override wins); omitted ⇒ unlimited. */
+    /** Sets the default `sections` cap for conversations this manager creates (a per-`add` override wins); omitted ⇒ unlimited. */
     readonly sections?: number;
     /**
-     * The optional durable {@link ConversationStoreInterface} backing
+     * Holds the optional durable {@link ConversationStoreInterface} backing
      * {@link ConversationManagerInterface.open} / {@link ConversationManagerInterface.save} — a memory
      * / JSON / SQLite / IndexedDB store a conversation is HYDRATED from (`open` a registry-miss) and
      * PERSISTED to (`save`). Omitted ⇒ the manager is registry-only: `open` resolves only what is
@@ -1729,37 +1925,46 @@ export declare interface ConversationManagerOptions {
 }
 
 /**
- * Options for `createConversation` — the optional `id`, the reserved `on` hooks (§8), the
+ * Configures `createConversation` — the optional `id`, the reserved `on` hooks, the
  * provider-agnostic `summarize` seam, and the retained-tail size.
  *
  * @remarks
- * `id` is the conversation's identity (a random UUID when omitted). `on` is the §8 reserved
- * key (initial {@link ConversationEventMap} listeners). `summarize` is the
- * {@link ConversationSummarizer} compaction needs — ABSENT ⇒ `compact()` throws a
+ * `id` is the conversation's identity (a random UUID when omitted). `on` is the reserved
+ * listener key (initial {@link ConversationEventMap} listeners). `summarize` is the
+ * {@link ConversationSummaryHandler} compaction needs — ABSENT ⇒ `compact()` throws a
  * {@link import('./errors.js').ConversationError} (a conversation can still store + view a
- * live tail, it just cannot fold). `keep` is how many recent live messages a `compact()`
+ * live tail; it cannot fold). `keep` is how many recent live messages a `compact()`
  * retains VERBATIM (folding only the older ones); it defaults to
  * {@link import('./constants.js').DEFAULT_CONVERSATION_KEEP} (`0` — a manual `compact()`
  * folds the WHOLE current live tail into one section). `sections` is an optional cap on the
  * compacted `sections` list — when set (`>= 1`), a `compact()` that would leave more than
  * `sections` sections FOLDS the oldest overflow into ONE merged section so the list never
  * exceeds `sections`, emitting `collapse`; omitted ⇒ unlimited (the prior behavior).
+ * `snapshot` is the HYDRATION seam — a {@link ConversationSnapshot} whose `id`, rollup
+ * `summary`, compacted `sections`, and live tail are RESTORED into the new conversation, with
+ * the live `summarize` / `keep` / `on` supplied alongside it (a summarizer is a function, not
+ * serialized data). Restoring is SILENT (no events — nothing was edited), and a `snapshot.id`
+ * WINS over `id` (the snapshot IS the conversation's identity). It is what lets
+ * `createConversation` hydrate, and what a {@link ConversationManagerInterface.open} reads a
+ * stored snapshot back through.
  */
 export declare interface ConversationOptions {
     readonly id?: string;
     readonly on?: EmitterHooks<ConversationEventMap>;
-    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    /** Holds the emitter's listener-error handler — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
-    /** The summarizer compaction needs; ABSENT ⇒ `compact()` throws a `ConversationError`. */
-    readonly summarize?: ConversationSummarizer;
-    /** Recent live messages kept verbatim on `compact`; defaults to `DEFAULT_CONVERSATION_KEEP` (`0`). */
+    /** Supplies the summarizer compaction needs; ABSENT ⇒ `compact()` throws a `ConversationError`. */
+    readonly summarize?: ConversationSummaryHandler;
+    /** Keeps this many recent live messages verbatim on `compact`; defaults to `DEFAULT_CONVERSATION_KEEP` (`0`). */
     readonly keep?: number;
-    /** A cap (`>= 1`) on the compacted `sections` list; overflow folds into one merged section. Omitted ⇒ unlimited. */
+    /** Caps the compacted `sections` list (`>= 1`); overflow folds into one merged section. Omitted ⇒ unlimited. */
     readonly sections?: number;
+    /** Hydrates from a {@link ConversationSnapshot} — its `id` wins over `id`; restoring is silent. */
+    readonly snapshot?: ConversationSnapshot;
 }
 
 /**
- * Options for {@link ConversationInterface.reference} — how to render ONE conversation as a
+ * Configures {@link ConversationInterface.reference} — how to render ONE conversation as a
  * self-labeled, fenced PROVENANCE block to pull INTO another conversation (by writing it to
  * the active context's active workspace).
  *
@@ -1767,56 +1972,56 @@ export declare interface ConversationOptions {
  * The rendered block is a cross-conversation reference a SMALL model must read as foreign
  * material, NOT as part of the live thread — so every member keeps it CONCISE and unmistakably
  * attributed:
- * - `label` — the human PROVENANCE name shown in the block's leading marker (e.g. `'planning'`);
+ * - `label` — the human PROVENANCE name shown in the block's leading marker (for example `'planning'`);
  *   defaults to the conversation's own `id`. It is what the model attributes the content to.
  * - `summary` — whether to include the conversation's rollup `summary` (its summary-of-summaries)
  *   in the block; defaults to `true` (the rollup is included WHEN one exists — `undefined` until
- *   the first compaction simply omits the `Summary:` line). Pass `false` to exclude it.
+ *   the first compaction omits the `Summary:` line). Pass `false` to exclude it.
  * - `messages` — the CHERRY-PICKED excerpts to include (each rendered `role: content`), default
  *   NONE. The intended source is the conversation's OWN `search(query)` / `rehydrate(id)` output
  *   (select the few relevant turns), NOT its whole history — dumping every message defeats the
  *   point (it re-bloats the destination context a small model then has to wade through).
  */
 export declare interface ConversationReferenceOptions {
-    /** The human provenance label in the block's marker; defaults to the conversation's `id`. */
+    /** Names the human provenance label in the block's marker; defaults to the conversation's `id`. */
     readonly label?: string;
-    /** Include the conversation's rollup `summary` (when one exists); defaults to `true`. */
+    /** Includes the conversation's rollup `summary` (when one exists); defaults to `true`. */
     readonly summary?: boolean;
-    /** The cherry-picked excerpts to include (`role: content`); defaults to none. */
-    readonly messages?: readonly MessageInterface[];
+    /** Lists the cherry-picked excerpts to include (`role: content`); defaults to none. */
+    readonly messages?: readonly Message[];
 }
 
 /**
- * A JSON-serializable snapshot of a conversation's state — its `id`, the rollup `summary`, the
+ * Holds a JSON-serializable snapshot of a conversation's state — its `id`, the rollup `summary`, the
  * compacted `sections`, and the live tail `messages` — the durable payload the
  * {@link ConversationStoreInterface} persists. The exact analogue of
  * {@link import('@orkestrel/workspace').WorkspaceSnapshot}.
  *
  * @remarks
- * Pure JSON DATA (no class instances, no functions): each {@link SectionInterface} and
- * {@link MessageInterface} is already a PLAIN record that `structuredClone`s / JSON-round-trips
+ * Pure JSON DATA (no class instances, no functions): each {@link Section} and
+ * {@link Message} is already a PLAIN record that `structuredClone`s / JSON-round-trips
  * losslessly. The snapshot carries the rollup `summary` (a summary-of-summaries; `undefined` until
  * the first compaction), the compacted `sections` (each RETAINING its folded originals), and the
  * live uncompacted tail `messages` — but NOT the `summarize` / `keep`, which are live CONFIG
  * re-supplied on hydrate (a summarizer is a function, not serializable data). The snapshot the
  * container produces from itself ({@link ConversationInterface.snapshot}); the durable analogue of
- * the constructor `seed`. A {@link ConversationManagerInterface} hydrates a conversation from it
- * through the seed seam (see {@link ConversationManagerInterface.open}). It is narrowed back from an
- * untrusted storage read by {@link import('./helpers.js').isConversationSnapshot} (the AGENTS §14
- * boundary narrow).
+ * the {@link ConversationOptions.snapshot} hydration seam. A {@link ConversationManagerInterface}
+ * hydrates a conversation from it through that seam (see {@link ConversationManagerInterface.open}). It is narrowed back from an
+ * untrusted storage read by {@link import('./validators.js').isConversationSnapshot} (the total
+ * boundary guard).
  */
 export declare interface ConversationSnapshot {
     readonly id: string;
-    /** The rollup (a summary-of-summaries); `undefined` until the first compaction. */
+    /** Holds the rollup (a summary-of-summaries); `undefined` until the first compaction. */
     readonly summary?: string;
-    /** The compacted history, oldest → newest (each section RETAINS its folded originals). */
-    readonly sections: readonly SectionInterface[];
-    /** The live uncompacted tail, in insertion order. */
-    readonly messages: readonly MessageInterface[];
+    /** Lists the compacted history, oldest → newest (each section RETAINS its folded originals). */
+    readonly sections: readonly Section[];
+    /** Lists the live uncompacted tail, in insertion order. */
+    readonly messages: readonly Message[];
 }
 
 /**
- * One row of the table a
+ * Represents one row of the table a
  * {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore}
  * persists — a conversation `id` plus its {@link ConversationSnapshot} held as ONE OPAQUE JSON
  * column. The exact analogue of {@link import('@orkestrel/workspace').WorkspaceSnapshotRow}.
@@ -1828,18 +2033,18 @@ export declare interface ConversationSnapshot {
  * row type stays FLAT and the sections/messages snapshot shape never
  * forces the contract to `Infer` it. The column therefore reads back as the broad `unknown`; the
  * store narrows it to a {@link ConversationSnapshot} on `get`
- * ({@link import('./helpers.js').isConversationSnapshot}, the AGENTS §14 boundary narrow). `id`
+ * ({@link import('./validators.js').isConversationSnapshot}, the total boundary guard). `id`
  * mirrors {@link ConversationSnapshot.id} (the primary key), so a `set` writes
  * `{ id: snapshot.id, snapshot }`.
  */
 export declare interface ConversationSnapshotRow {
     readonly id: string;
-    /** The whole {@link ConversationSnapshot} as one opaque JSON blob — read back as `unknown`, narrowed on `get`. */
+    /** Holds the whole {@link ConversationSnapshot} as one opaque JSON blob — read back as `unknown`, narrowed on `get`. */
     readonly snapshot: unknown;
 }
 
 /**
- * The durable persistence seam for a {@link ConversationSnapshot} — three async primitives
+ * Persists a {@link ConversationSnapshot} durably — three async primitives
  * (`get` / `set` / `delete`) keyed by a conversation id, the exact analogue of
  * {@link import('@orkestrel/workspace').WorkspaceStoreInterface}.
  *
@@ -1852,7 +2057,7 @@ export declare interface ConversationSnapshotRow {
  * {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore} (the
  * snapshot as one opaque JSON column) share THIS one interface. Hydration is NOT a store concern
  * — a {@link ConversationManagerInterface} reads a snapshot back and rebuilds the live conversation
- * through the constructor `seed` (re-supplying the live `summarize` / `keep`; see
+ * through the {@link ConversationOptions.snapshot} seam (re-supplying the live `summarize` / `keep`; see
  * {@link ConversationManagerInterface.open} / {@link ConversationManagerInterface.save}).
  *
  * Every primitive is async (a `Promise`), so a durable backend (a database round-trip) fits the
@@ -1861,26 +2066,26 @@ export declare interface ConversationSnapshotRow {
  * {@link import('@orkestrel/workspace').WorkspaceStoreInterface}'s `set`). UNLIKE a session store
  * there is NO idle-TTL
  * / eviction — a persisted conversation lives until an explicit `delete`. It is concrete over
- * {@link ConversationSnapshot} — no generic parameter (AGENTS §21 minimal-interface), since the
+ * {@link ConversationSnapshot} — no generic parameter, because the
  * snapshot is the ONE payload a conversation store persists.
  */
 export declare interface ConversationStoreInterface {
     /**
-     * Resolve the persisted snapshot for `id`, or `undefined` if none is stored.
+     * Resolves the persisted snapshot for `id`, or `undefined` if none is stored.
      *
      * @param id - The conversation id to resolve (a {@link ConversationSnapshot.id})
      * @returns The persisted snapshot, or `undefined` if absent
      */
     get(id: string): Promise<ConversationSnapshot | undefined>;
     /**
-     * Insert or replace a snapshot under its own `snapshot.id` (no separate id param —
+     * Inserts or replaces a snapshot under its own `snapshot.id` (no separate id param —
      * mirroring {@link import('@orkestrel/workspace').WorkspaceStoreInterface}'s `set`).
      *
      * @param snapshot - The snapshot to store (keyed by its `id`)
      */
     set(snapshot: ConversationSnapshot): Promise<void>;
     /**
-     * Drop 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
      */
@@ -1888,25 +2093,25 @@ export declare interface ConversationStoreInterface {
 }
 
 /**
- * A provider-agnostic conversation summarizer — the seam the agent RUNTIME supplies so
+ * Summarizes a conversation, provider-agnostically — the seam the agent RUNTIME supplies so
  * core never imports a provider. Given the folded messages, it resolves their digest (the
- * model-written summary), used both to summarize a compacted {@link SectionInterface} and
+ * model-written summary), used both to summarize a compacted {@link Section} and
  * to regenerate a {@link ConversationInterface}'s rollup `summary`.
  *
  * @remarks
- * The agent runtime builds one from its `ProviderInterface` (e.g.
+ * The agent runtime builds one from its `ProviderInterface` (for example
  * `async (messages) => (await provider.generate([systemPrompt, ...messages], signal)).content`)
  * and hands it to a {@link ConversationInterface} / {@link ConversationManagerInterface}.
- * The core conversation layer treats it as an opaque async function — it neither knows nor
- * cares which backend produced the digest, keeping `core` free of any provider coupling.
+ * 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.
  *
  * @param messages - The folded messages to digest into a summary
  * @returns The summary text (the model-written digest of those messages)
  */
-export declare type ConversationSummarizer = (messages: readonly MessageInterface[]) => Promise<string>;
+export declare type ConversationSummaryHandler = (messages: readonly Message[]) => Promise<string>;
 
 /**
- * Create an agent loop — an {@link AgentInterface} composing a
+ * Creates an agent loop — an {@link AgentInterface} composing a
  * {@link ProviderInterface}, its {@link AgentContextInterface}, and a tool registry
  * into a bounded context → provider → tools → repeat turn, exposed as a one-shot
  * `generate` and a live `stream`.
@@ -1914,11 +2119,11 @@ export declare type ConversationSummarizer = (messages: readonly MessageInterfac
  * @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` (via `AbortSignal.any`) — any trip (or `abort()`)
+ * `signal` + `timeout` + `budget` (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
- * structurally via `context.tools.definitions()`. Two observation surfaces: the
+ * structurally through `context.tools.definitions()`. Two observation surfaces: the
  * {@link AgentChunk} stream (pull — per-token content) and a typed `emitter` (push —
  * lifecycle + `usage` / `tool` / `deny` for fire-and-forget observers).
  *
@@ -1929,8 +2134,9 @@ export declare type ConversationSummarizer = (messages: readonly MessageInterfac
  *
  * @example
  * ```ts
- * import type { ProviderInterface } from '@src/core'
- * import { createAgent, createTokenBudget } from '@src/core'
+ * import type { ProviderInterface } from '@orkestrel/agent'
+ * import { createAgent } from '@orkestrel/agent'
+ * import { createTokenBudget } from '@orkestrel/budget'
  *
  * declare const provider: ProviderInterface // any concrete implementation supplied by the host app
  * const agent = createAgent(provider, {
@@ -1941,7 +2147,7 @@ export declare type ConversationSummarizer = (messages: readonly MessageInterfac
  *
  * const stream = agent.stream()
  * for await (const chunk of stream.events) {
- * 	if (chunk.type === 'token') process.stdout.write(chunk.content)
+ * 	if (chunk.category === 'token') process.stdout.write(chunk.content)
  * }
  * const result = await stream.result // { content, usage?, partial }
  * ```
@@ -1949,7 +2155,7 @@ export declare type ConversationSummarizer = (messages: readonly MessageInterfac
 export declare function createAgent(provider: ProviderInterface, options?: AgentOptions): AgentInterface;
 
 /**
- * Create a richer turn context — an {@link AgentContextInterface} assembling a provider
+ * Creates a richer turn context — an {@link AgentContextInterface} assembling a provider
  * request from the optional system prompt, the instruction registry, the workspace registry,
  * the conversation store, the tool registry, and the active scope.
  *
@@ -1957,11 +2163,11 @@ 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
- * via `context.apply(...)`). The `messages` store is always fresh. `build()` folds the scoped
+ * 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' `data` to the last user message), built fresh each call; the active
- * workspace is the SOLE document/image context. Tools are advertised STRUCTURALLY (via
+ * 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
  * `tools.definitions()`, scope-filtered by the loop), never serialized into the prompt.
  *
  * @param options - Optional `system` / `tools` / `instructions` / `workspaces` / `scope`
@@ -1970,7 +2176,7 @@ export declare function createAgent(provider: ProviderInterface, options?: Agent
  *
  * @example
  * ```ts
- * import { createAgentContext } from '@src/core'
+ * import { createAgentContext } from '@orkestrel/agent'
  *
  * const context = createAgentContext({ system: 'You are concise.' })
  * context.instructions.add({ name: 'tone', content: 'Be terse.' })
@@ -1981,7 +2187,7 @@ export declare function createAgent(provider: ProviderInterface, options?: Agent
 export declare function createAgentContext(options?: AgentContextOptions): AgentContextInterface;
 
 /**
- * Create a durable, bounded-concurrency agent-job queue — a {@link QueueInterface} over
+ * Creates a durable, bounded-concurrency agent-job queue — a {@link QueueInterface} over
  * serializable {@link AgentJobInput}s that COMPOSES `createQueue`: each job is rehydrated
  * through the `registry` into a live {@link AgentInterface}, run to its {@link AgentResult},
  * and subjected to the partial-as-configurable-failure policy.
@@ -1989,30 +2195,31 @@ export declare function createAgentContext(options?: AgentContextOptions): Agent
  * @remarks
  * - **Composes the substrate (no new engine).** The handler is the only new logic;
  *   bounded `concurrency`, `retries`, the per-attempt `timeout`, and durable persistence
- *   via `store` (+ `restore()` after a crash) are all the backing Queue's. `enqueue`
+ *   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`
- *   (e.g. `createMemoryQueueStore` / `createDatabaseQueueStore`) persists outstanding
+ *   (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.
  * - **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; `allowPartial: true`
+ *   attempt deadline / a queue abort RETRIES while attempts remain; `partial: true`
  *   resolves the partial as success instead.
- * - **Cancellation threads through.** The handler passes `execution.signal` into
+ * - **Cancellation threads through.** The handler passes `context.signal` into
  *   `registry.build`, so a queue `abort()` or a per-attempt timeout cancels the in-flight
  *   agent (which commits a partial → throws → retries / fails per policy).
  *
- * @param options - The `registry`, the `allowPartial` policy, and the substrate knobs
+ * @param options - The `registry`, the `partial` policy, and the substrate knobs
  *   (`concurrency` / `retries` / `timeout` / `store`) (see {@link AgentQueueOptions})
  * @returns A {@link QueueInterface} of {@link AgentJobInput} → {@link AgentResult}
  *
  * @example
  * ```ts
- * import { createAgentQueue, createAgentRegistry, createMemoryQueueStore } from '@src/core'
+ * import { createAgentQueue, createAgentRegistry } from '@orkestrel/agent'
+ * import { createMemoryQueueStore } from '@orkestrel/queue'
  *
  * const registry = createAgentRegistry({ providers: { main: provider } })
- * const store = createMemoryQueueStore(agentJobShape) // survives a restart via restore()
+ * 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?' }] })
  * ```
@@ -2020,16 +2227,17 @@ export declare function createAgentContext(options?: AgentContextOptions): Agent
 export declare function createAgentQueue(options: AgentQueueOptions): QueueInterface<AgentJobInput, AgentResult>;
 
 /**
- * Create an agent registry — an {@link AgentRegistryInterface} holding the named pools of
+ * Creates an agent registry — an {@link AgentRegistryInterface} holding the named pools of
  * live, non-serializable pieces (providers, tools, authorities, schedulers) that a
  * serializable {@link AgentJobInput}'s names resolve against, and `build`ing a seeded,
  * signal-wired {@link AgentInterface} from a job.
  *
  * @remarks
  * `providers` is required; `tools` / `authorities` / `schedulers` are optional pools.
- * The accessors (`provider` / `tool` / `authority` / `scheduler`) THROW `unknown <category>:
- * <name>` on an unregistered name (§9.1 + §12) — a misconfigured or crash-restored job
- * fails loudly rather than running with a missing dependency. `build(input, signal)`
+ * The accessors (`provider` / `tool` / `authority` / `scheduler`) THROW an
+ * {@link import('./errors.js').AgentError} carrying `code: 'REGISTRY'` and the message
+ * `unknown <category>: <name>` on an unregistered name — a misconfigured or crash-restored
+ * job fails loudly rather than running with a missing dependency. `build(input, signal)`
  * resolves the names, rebuilds the token budget from its ceiling, seeds the agent's
  * context with the job's messages, and threads `signal` so a queue / runner abort
  * propagates. This is the bridge that makes durable, serializable agent jobs runnable.
@@ -2039,8 +2247,8 @@ export declare function createAgentQueue(options: AgentQueueOptions): QueueInter
  *
  * @example
  * ```ts
- * import { createAgentRegistry } from '@src/core'
- * import type { ProviderInterface } from '@src/core'
+ * import { createAgentRegistry } from '@orkestrel/agent'
+ * import type { ProviderInterface } from '@orkestrel/agent'
  * import { createTool } from '@orkestrel/tool'
  *
  * declare const provider: ProviderInterface // any concrete implementation supplied by the host app
@@ -2054,7 +2262,7 @@ export declare function createAgentQueue(options: AgentQueueOptions): QueueInter
 export declare function createAgentRegistry(options: AgentRegistryOptions): AgentRegistryInterface;
 
 /**
- * Create an agent-job runner — a {@link RunnerInterface} over serializable
+ * Creates an agent-job runner — a {@link RunnerInterface} over serializable
  * {@link AgentJobInput}s that COMPOSES `createRunner` (one-shot, ordered, fail-fast), each
  * unit rehydrated through the `registry` and subjected to the partial policy. The runner
  * enables **sub-agent fan-out**: a parent job's handler can `controller.spawn(childJob)`.
@@ -2069,17 +2277,17 @@ export declare function createAgentRegistry(options: AgentRegistryOptions): Agen
  *   runner, FAN OUT and return — do NOT inline-`await` a spawn 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
- *   THROWS by default (the run's fail-fast engages), `allowPartial: true` resolves it; the
+ *   THROWS by default (the run's fail-fast engages), `partial: true` resolves it; the
  *   handler threads `controller.signal` into `registry.build`, so a runner abort / a
  *   per-attempt timeout cancels the agent.
  *
- * @param options - The `registry`, the `allowPartial` policy, and the substrate knobs
+ * @param options - The `registry`, the `partial` policy, and the substrate knobs
  *   (`concurrency` / `retries` / `timeout`) (see {@link AgentRunnerOptions})
  * @returns A {@link RunnerInterface} of {@link AgentJobInput} → {@link AgentResult}
  *
  * @example
  * ```ts
- * import { createAgentRunner, createAgentRegistry } from '@src/core'
+ * import { createAgentRunner, createAgentRegistry } from '@orkestrel/agent'
  *
  * const registry = createAgentRegistry({ providers: { main: provider } })
  * const runner = createAgentRunner({ registry, concurrency: 2 })
@@ -2092,7 +2300,7 @@ export declare function createAgentRegistry(options: AgentRegistryOptions): Agen
 export declare function createAgentRunner(options: AgentRunnerOptions): RunnerInterface<AgentJobInput, AgentResult>;
 
 /**
- * Create a policy gate — an {@link AuthorityInterface} the agent loop consults before
+ * Creates a policy gate — an {@link AuthorityInterface} the agent loop consults before
  * each tool call runs, evaluating the ordered rules first-match-wins and falling back
  * to the configured default when none match.
  *
@@ -2102,16 +2310,16 @@ export declare function createAgentRunner(options: AgentRunnerOptions): RunnerIn
  * `fallback` decides; it defaults to `{ zone: DEFAULT_AUTHORITY_ZONE, allowed: true }`
  * (allow-unmatched — a rules list of denials acts as a DENYLIST). Pass an
  * `allowed: false` `fallback` to flip the gate to deny-by-default (an ALLOWLIST). Wire
- * the result into `createAgent` via `AgentOptions.authority`: a denied call is fed back
+ * the result into `createAgent` through `AgentOptions.authority`: a denied call is fed back
  * to the model as a denial `ToolResult` (not executed, no budget cost), so the model
- * can react. Synchronous now — the async human-approval handshake is deferred.
+ * can react. Synchronous — `evaluate` returns the verdict directly.
  *
  * @param options - Optional `rules` (ordered) and `fallback` (see {@link AuthorityOptions})
  * @returns A working {@link AuthorityInterface}
  *
  * @example
  * ```ts
- * import { createAgent, createAuthority } from '@src/core'
+ * import { createAgent, createAuthority } from '@orkestrel/agent'
  *
  * // Deny the `delete` tool, allow everything else.
  * const authority = createAuthority({
@@ -2123,28 +2331,56 @@ export declare function createAgentRunner(options: AgentRunnerOptions): RunnerIn
 export declare function createAuthority(options?: AuthorityOptions): AuthorityInterface;
 
 /**
- * Create a conversation — a {@link ConversationInterface} grouping messages above a flat
+ * Creates an empty unbounded async channel — a {@link ChannelInterface} a producer writes
+ * values into (`push`) and ends (`close` / `fail`) regardless of consumption, while a
+ * consumer reads them back live through `drain`.
+ *
+ * @remarks
+ * Write and read are decoupled, so the producer never waits for a consumer: an agent's eager
+ * pump writes each chunk into one, which is why a run's `result` settles whether or not the
+ * live events are drained. A value pushed at an already-parked consumer is delivered, buffered
+ * values are yielded before the end is reported, and the FIRST failure wins.
+ *
+ * @typeParam T - The value type the channel carries
+ * @returns A fresh, empty {@link ChannelInterface}
+ *
+ * @example
+ * ```ts
+ * import { createChannel } from '@orkestrel/agent'
+ *
+ * const channel = createChannel<number>()
+ * channel.push(1)
+ * channel.close()
+ * for await (const value of channel.drain()) {
+ * 	value // 1
+ * }
+ * ```
+ */
+export declare function createChannel<T>(): ChannelInterface<T>;
+
+/**
+ * Creates a conversation — a {@link ConversationInterface} grouping messages above a flat
  * message store it OWNS DIRECTLY, with compaction into summarized sections, a regenerated
  * rollup `summary`, on-demand `rehydrate`, and substring `search`, driven by a
- * provider-agnostic {@link ConversationSummarizer} seam.
+ * provider-agnostic {@link ConversationSummaryHandler} seam.
  *
  * @remarks
  * Append turns through the conversation's own `add` (the live tail it owns); `view()` is the model input
  * (each section as a summary message, then the live tail). `compact()` folds the older live
- * messages into a summarized {@link SectionInterface} and regenerates the rollup — it REQUIRES
+ * messages into a summarized {@link Section} and regenerates the rollup — it REQUIRES
  * a `summarize` (omitted ⇒ `compact()` throws a `ConversationError`); `keep` retains a recent
  * tail (default `DEFAULT_CONVERSATION_KEEP` — fold ALL). `rehydrate(id)` / `search(query)` read
  * the retained originals. Observable (`emitter` — `compact` / `summary` / `rehydrate`), wired
- * via the reserved `on` option (§8); the emitter isolates a listener throw and routes it to
- * its `error` handler (the `error` option, §13), so it can never corrupt a compaction.
+ * through the reserved `on` option; the emitter isolates a listener throw and routes it to
+ * its `error` handler (the `error` option), so it can never corrupt a compaction.
  *
  * @param options - Optional `id` / `on` hooks + the `summarize` seam + `keep` (see {@link ConversationOptions})
  * @returns A working {@link ConversationInterface}
  *
  * @example
  * ```ts
- * import type { ProviderInterface } from '@src/core'
- * import { createConversation } from '@src/core'
+ * import type { ProviderInterface } from '@orkestrel/agent'
+ * import { createConversation } from '@orkestrel/agent'
  *
  * declare const provider: ProviderInterface // any concrete implementation supplied by the host app
  * const conversation = createConversation({
@@ -2160,9 +2396,10 @@ export declare function createAuthority(options?: AuthorityOptions): AuthorityIn
 export declare function createConversation(options?: ConversationOptions): ConversationInterface;
 
 /**
- * Create a conversation registry — a {@link ConversationManagerInterface} holding
+ * Creates a conversation registry — a {@link ConversationManagerInterface} holding
  * {@link ConversationInterface}s keyed by their `id` (in insertion order) WITH an active pointer:
- * the §9 store over the conversation layer plus the `active` / `switch` seam the context renders.
+ * the id-keyed store over the conversation layer plus the `active` / `switch` seam the context
+ * renders.
  *
  * @remarks
  * Starts empty; `add(input?)` mints a {@link ConversationInterface} (its `id` from the input
@@ -2171,8 +2408,9 @@ export declare function createConversation(options?: ConversationOptions): Conve
  * AUTO-ACTIVATES the FIRST one (a registry with conversations always has one `active`); a later
  * `add` leaves `active` unchanged. `switch(id)` re-points `active` (an unknown `id` returns
  * `undefined`, leaving `active` unchanged — lenient, never throws); `conversation(id)` /
- * `conversations()` look up; `remove` (one or a batch, §9.2) reports whether any was removed AND
- * clears `active` if it was the removed one; `clear` empties it and clears `active`. Event-free
+ * `conversations()` look up; `remove` (one or a batch) reports `true` only when every supplied id
+ * was removed AND clears `active` if it was a removed one; `clear` empties it and clears `active`.
+ * Event-free
  * (each conversation owns its own observable `emitter`). A conversation created with NEITHER a
  * manager default nor a per-`add` `summarize` cannot `compact` (it throws a `ConversationError`).
  *
@@ -2181,7 +2419,7 @@ export declare function createConversation(options?: ConversationOptions): Conve
  *
  * @example
  * ```ts
- * import { createConversationManager } from '@src/core'
+ * import { createConversationManager } from '@orkestrel/agent'
  *
  * const conversations = createConversationManager({ summarize: async (m) => `recap of ${m.length}` })
  * const chat = conversations.add() // auto-activates — conversations.active === chat
@@ -2191,7 +2429,7 @@ export declare function createConversation(options?: ConversationOptions): Conve
 export declare function createConversationManager(options?: ConversationManagerOptions): ConversationManagerInterface;
 
 /**
- * Create a {@link DatabaseConversationStore} over any {@link DriverInterface} — the durable,
+ * Creates a {@link DatabaseConversationStore} over any {@link DriverInterface} — the durable,
  * driver-pluggable backing for the conversation persistence seam, the opt-in twin of
  * {@link createMemoryConversationStore}. The exact twin of
  * {@link import('@orkestrel/workspace').createDatabaseWorkspaceStore}.
@@ -2203,7 +2441,7 @@ export declare function createConversationManager(options?: ConversationManagerO
  * {@link import('@orkestrel/workspace').createDatabaseWorkspaceStore} stores its snapshot. The
  * snapshot is already a COMPLETE, self-contained, pure-JSON payload, so storing it whole is lossless
  * AND keeps the row type FLAT (the column reads back as `unknown`, narrowed on `get` by
- * {@link import('./helpers.js').isConversationSnapshot}). The `driver` DEFAULTS to
+ * {@link import('./validators.js').isConversationSnapshot}). The `driver` DEFAULTS to
  * {@link createMemoryDriver}, so the store ALSO works in memory out of the box; pass a server
  * `createJSONDriver` / `createSQLiteDriver` (or a browser IndexedDB driver) for a persistent one —
  * the durability is the driver's job, the store engine is shared. It swaps in behind
@@ -2214,7 +2452,8 @@ export declare function createConversationManager(options?: ConversationManagerO
  *
  * @example
  * ```ts
- * import { createConversationManager, createDatabaseConversationStore, createMemoryDriver } from '@src/core'
+ * import { createConversationManager, createDatabaseConversationStore } from '@orkestrel/agent'
+ * import { createMemoryDriver } from '@orkestrel/database'
  *
  * const store = createDatabaseConversationStore(createMemoryDriver()) // a durable driver swaps in here
  * const manager = createConversationManager({ store })
@@ -2226,7 +2465,7 @@ export declare function createConversationManager(options?: ConversationManagerO
 export declare function createDatabaseConversationStore(driver?: DriverInterface): ConversationStoreInterface;
 
 /**
- * Create an instruction — an immutable {@link InstructionInterface} (a named directive)
+ * Creates an instruction — an immutable {@link InstructionInterface} (a named directive)
  * from its `name` / `content` and optional `priority`, the `id` minted at construction.
  *
  * @remarks
@@ -2240,7 +2479,7 @@ export declare function createDatabaseConversationStore(driver?: DriverInterface
  *
  * @example
  * ```ts
- * import { createInstruction } from '@src/core'
+ * import { createInstruction } from '@orkestrel/agent'
  *
  * const instruction = createInstruction({ name: 'tone', content: 'Be concise.', priority: 5 })
  * ```
@@ -2248,28 +2487,28 @@ export declare function createDatabaseConversationStore(driver?: DriverInterface
 export declare function createInstruction(input: InstructionInput): InstructionInterface;
 
 /**
- * Create an instruction registry — an {@link InstructionManagerInterface} holding
+ * Creates an instruction registry — an {@link InstructionManagerInterface} holding
  * immutable instructions keyed by `name`, listed by descending `priority`.
  *
  * @remarks
- * Starts empty; `add` (one or a batch, §9.2) MINTS each `id` and OVERWRITES a same-name
+ * Starts empty; `add` (one or a batch) MINTS each `id` and OVERWRITES a same-name
  * instruction (last write wins); `instructions()` lists them sorted by descending
- * `priority` (stable for ties); `format` / `description` are the build contract a richer
- * context renders an instructions block with; `remove` (one or a batch) reports whether
- * any was removed; `clear` empties it. Carries an observable `emitter`
- * ({@link import('./types.js').InstructionManagerEventMap}) wired via the reserved `on`
- * option (§8); the emitter isolates a listener throw and routes it to its `error` handler
- * (the `error` option, §13), so it can never corrupt a mutation. An optional `format`
+ * `priority` (stable for ties); `open` / `render` are the build contract a richer
+ * context renders an instructions block with; `remove` (one or a batch) reports `true` only
+ * when every supplied name was removed; `clear` empties it. Carries an observable `emitter`
+ * ({@link import('./types.js').InstructionManagerEventMap}) wired through the reserved `on`
+ * option; the emitter isolates a listener throw and routes it to its `error` handler
+ * (the `error` option), so it can never corrupt a mutation. An optional `format`
  * override is the manager-options level of the `AgentContext` build cascade (consulted by
- * `description` / `format`, beating the provider default + built-in; a per-item
- * `InstructionInput.format` still beats it).
+ * `open` / `render`, beating the provider default + built-in; a per-item
+ * `InstructionInput.override` still beats it).
  *
  * @param options - Optional `on` hooks + a `format` override (see {@link InstructionManagerOptions})
  * @returns An empty {@link InstructionManagerInterface}
  *
  * @example
  * ```ts
- * import { createInstructionManager } from '@src/core'
+ * import { createInstructionManager } from '@orkestrel/agent'
  *
  * const instructions = createInstructionManager()
  * instructions.add({ name: 'tone', content: 'Be concise.', priority: 5 })
@@ -2278,7 +2517,7 @@ export declare function createInstruction(input: InstructionInput): InstructionI
 export declare function createInstructionManager(options?: InstructionManagerOptions): InstructionManagerInterface;
 
 /**
- * Create the in-memory conversation store — a {@link ConversationStoreInterface} backed by a
+ * Creates the in-memory conversation store — a {@link ConversationStoreInterface} backed by a
  * process-lifetime `Map` of {@link import('./types.js').ConversationSnapshot}s keyed by conversation
  * id, the DEFAULT backing for the durable {@link ConversationManagerInterface.open} /
  * {@link ConversationManagerInterface.save} seam. The exact twin of
@@ -2293,14 +2532,14 @@ export declare function createInstructionManager(options?: InstructionManagerOpt
  * {@link createDatabaseConversationStore} (the snapshot as one opaque JSON column over a `databases`
  * table) — for a DURABLE store pass it a JSON / SQLite / IndexedDB driver, and it swaps in WITHOUT
  * touching the manager or the conversation. Hydration stays a manager concern: read a snapshot back
- * and rebuild the live conversation through the constructor `seed` (re-supplying the live
+ * and rebuild the live conversation through the `snapshot` option (re-supplying the live
  * `summarize` / `keep`).
  *
  * @returns A memory-backed {@link ConversationStoreInterface}
  *
  * @example
  * ```ts
- * import { createConversationManager, createMemoryConversationStore } from '@src/core'
+ * import { createConversationManager, createMemoryConversationStore } from '@orkestrel/agent'
  *
  * const store = createMemoryConversationStore()
  * const manager = createConversationManager({ store })
@@ -2312,8 +2551,8 @@ export declare function createInstructionManager(options?: InstructionManagerOpt
 export declare function createMemoryConversationStore(): ConversationStoreInterface;
 
 /**
- * Create a named scope — an immutable {@link ScopeInterface} from its `name` and the four
- * optional per-category allow-lists, the `id` minted at construction.
+ * Creates a named scope — an immutable {@link ScopeInterface} from its `name` and its
+ * per-category allow-lists, the `id` minted at construction.
  *
  * @remarks
  * Each list is THREE-WAY: `undefined` ⇒ NO constraint on that category (all pass), `[]` ⇒
@@ -2321,13 +2560,13 @@ export declare function createMemoryConversationStore(): ConversationStoreInterf
  * tighter child by set-INTERSECTION (an `undefined` side imposing no constraint). Stored
  * immutable — never mutated after creation (`narrow` returns a new scope).
  *
- * @param input - `name` (required) and the optional `instructions` / `tools` / `messages` /
- *   `files` allow-lists (see {@link ScopeInput})
+ * @param input - `name` (required) and the optional `instructions` / `tools` / `files`
+ *   allow-lists (see {@link ScopeInput})
  * @returns A working {@link ScopeInterface}
  *
  * @example
  * ```ts
- * import { createScope } from '@src/core'
+ * import { createScope } from '@orkestrel/agent'
  *
  * const reader = createScope({ name: 'reader', tools: ['search', 'read'] })
  * reader.narrow({ tools: ['read', 'write'] }).tools // ['read'] — intersection tightens
@@ -2336,23 +2575,24 @@ export declare function createMemoryConversationStore(): ConversationStoreInterf
 export declare function createScope(input: ScopeInput): ScopeInterface;
 
 /**
- * Create a scope registry — a {@link ScopeManagerInterface} holding immutable scopes keyed
+ * Creates a scope registry — a {@link ScopeManagerInterface} holding immutable scopes keyed
  * 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;
- * `remove` (one or a batch, §9.2) reports whether any was removed; `clear` empties it.
- * Carries an observable `emitter` ({@link import('./types.js').ScopeManagerEventMap}) wired
- * via the reserved `on` option (§8); the emitter isolates a listener throw and routes it to
- * its `error` handler (the `error` option, §13), so it can never corrupt a mutation.
+ * `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`
+ * option; the emitter isolates a listener throw and routes it to its `error` handler
+ * (the `error` option), so it can never corrupt a mutation.
  *
  * @param options - Optional `on` hooks (see {@link ScopeManagerOptions})
  * @returns An empty {@link ScopeManagerInterface}
  *
  * @example
  * ```ts
- * import { createScopeManager } from '@src/core'
+ * import { createScopeManager } from '@orkestrel/agent'
  *
  * const scopes = createScopeManager()
  * const reader = scopes.create({ name: 'reader', tools: ['search'] })
@@ -2361,7 +2601,7 @@ export declare function createScope(input: ScopeInput): ScopeInterface;
 export declare function createScopeManager(options?: ScopeManagerOptions): ScopeManagerInterface;
 
 /**
- * Create a stream-stateful `<think>` separator — a {@link ThinkSplitterInterface} that
+ * Creates a stream-stateful `<think>` separator — a {@link ThinkSplitterInterface} that
  * splits a thinking model's in-content `<think>…</think>` reasoning spans away from
  * the answer, delta by delta, so a provider yields ONLY clean content and surfaces the
  * accumulated reasoning as {@link import('./types.js').ProviderResult.thinking}.
@@ -2372,14 +2612,14 @@ export declare function createScopeManager(options?: ScopeManagerOptions): Scope
  * partial open tag that never completed returns as final content; an UNCLOSED think
  * span lands on `thinking`). Tags split ACROSS deltas are held back until
  * disambiguated, multiple spans accumulate in order, and a nested-looking `<think>`
- * inside an open span is just thinking text. One splitter serves ONE stream — create
+ * inside an open span is thinking text. One splitter serves ONE stream — create
  * a fresh one per provider call.
  *
  * @returns A fresh {@link ThinkSplitterInterface} (state empty, outside any span)
  *
  * @example
  * ```ts
- * import { createThinkSplitter } from '@src/core'
+ * import { createThinkSplitter } from '@orkestrel/agent'
  *
  * const splitter = createThinkSplitter()
  * const clean = splitter.split('<think>plan the answer</think>Here it is.')
@@ -2390,7 +2630,7 @@ export declare function createScopeManager(options?: ScopeManagerOptions): Scope
 export declare function createThinkSplitter(): ThinkSplitterInterface;
 
 /**
- * A {@link ConversationStoreInterface} backed by one table of the `databases` layer — a
+ * Backs a {@link ConversationStoreInterface} with one table of the `databases` layer — a
  * conversation's durable state IS a row, so persistence reduces to keyed point-access (`get` / `set`
  * / `delete`) over a {@link TableInterface}, the driver-pluggable twin of the plain-`Map`
  * {@link import('./MemoryConversationStore.js').MemoryConversationStore}. The EXACT twin of
@@ -2416,19 +2656,20 @@ export declare function createThinkSplitter(): ThinkSplitterInterface;
  * - **`set(snapshot)` upserts under the snapshot's OWN `id`** (no separate id param) — it writes
  *   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('../../helpers.js').isConversationSnapshot} — the
- *   AGENTS §14 boundary narrow for an untrusted storage read), or `undefined` if none is stored.
+ *   a {@link ConversationSnapshot} ({@link import('../../validators.js').isConversationSnapshot} — the
+ *   total guard for an untrusted storage read), or `undefined` if none is stored.
  * - **`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
  * explicit `delete`. The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the
- * §22 method bijection with {@link ConversationStoreInterface}). Hydration stays a caller concern: a
+ * method bijection with {@link ConversationStoreInterface}). Hydration stays a caller concern: a
  * {@link import('../ConversationManager.js').ConversationManager} reads a snapshot back and rebuilds
- * the live conversation through the constructor `seed` (its `open` / `save`).
+ * the live conversation through the `snapshot` option (its `open` / `save`).
  *
  * @example
  * ```ts
- * import { createConversation, createDatabaseConversationStore, createMemoryDriver } from '@src/core'
+ * import { createConversation, createDatabaseConversationStore } from '@orkestrel/agent'
+ * import { createMemoryDriver } from '@orkestrel/database'
  *
  * const store = createDatabaseConversationStore(createMemoryDriver()) // a durable driver swaps in here
  * const conversation = createConversation()
@@ -2441,30 +2682,30 @@ export declare function createThinkSplitter(): ThinkSplitterInterface;
 export declare class DatabaseConversationStore implements ConversationStoreInterface {
     #private;
     /**
-     * Wrap a table as a conversation store.
+     * Wraps a table as a conversation store.
      *
      * @param table - The {@link TableInterface} holding the snapshots — its row is the
      *   {@link ConversationSnapshotRow} `{ id; snapshot }` shape (the snapshot one opaque JSON column)
      */
     constructor(table: TableInterface<ConversationSnapshotRow>);
-    /** Resolve 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`. */
     get(id: string): Promise<ConversationSnapshot | undefined>;
-    /** Insert or replace 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 }`. */
     set(snapshot: ConversationSnapshot): Promise<void>;
-    /** Drop 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). */
     delete(id: string): Promise<void>;
 }
 
 /**
- * The default cap on an {@link AgentInterface} turn's tool iterations — the maximum
+ * Caps an {@link AgentInterface} turn's tool iterations by default — the maximum
  * number of context → provider → tools cycles before the loop stops, so a model that
- * keeps requesting tools can never loop forever. Overridable per agent via
+ * keeps requesting tools can never loop forever. Overridable per agent through
  * `AgentOptions.limit`.
  */
 export declare const DEFAULT_AGENT_LIMIT = 10;
 
 /**
- * The zone an {@link AuthorityInterface}'s default fallback {@link AuthorityDecision}
+ * Names the zone an {@link AuthorityInterface}'s default fallback {@link AuthorityDecision}
  * carries — the classification for a tool call that matched no rule. Paired with the
  * default `allowed: true` fallback, an unmatched call is allowed under this zone, so a
  * rules list of denials acts as a denylist; a caller wanting deny-by-default supplies
@@ -2473,17 +2714,38 @@ export declare const DEFAULT_AGENT_LIMIT = 10;
 export declare const DEFAULT_AUTHORITY_ZONE = "default";
 
 /**
- * The default number of recent live messages a {@link ConversationInterface}'s `compact()`
+ * Sets the default number of recent live messages a {@link ConversationInterface}'s `compact()`
  * RETAINS verbatim — `0`, so a manual `compact()` folds ALL of the current live messages
  * into one summarized section (no tail kept). A caller retains a recent tail by passing
  * `keep` (on {@link ConversationOptions}, {@link ConversationManagerOptions}, or per-fold
- * via {@link CompactOptions}), folding only the older `count - keep` messages and leaving
+ * through {@link CompactOptions}), folding only the older `count - keep` messages and leaving
  * the most recent `keep` live for the next turn. Overridable everywhere `keep` is accepted.
  */
 export declare const DEFAULT_CONVERSATION_KEEP = 0;
 
 /**
- * Estimate the context-token footprint of a batch of messages — the default `consume`
+ * Synthesizes the denial {@link ToolResult} an authority-blocked call is fed back with — the
+ * call's `id` / `name` keyed back, carrying a denial `error` instead of a value.
+ *
+ * @remarks
+ * Pure and total. The rule's `reason` is rendered as `denied: <reason>` when one was given,
+ * else the generic `denied by authority`. There is no `value`, so the agent loop feeds it back
+ * exactly like a tool error and the model can react to it.
+ *
+ * @param call - The denied {@link ToolCall}
+ * @param reason - The rule's explanation, or `undefined` for the generic denial
+ * @returns The failure-arm {@link ToolResult}
+ *
+ * @example
+ * ```ts
+ * denyCall({ id: '1', name: 'drop', arguments: {} }, 'read-only mode')
+ * // { success: false, id: '1', name: 'drop', error: 'denied: read-only mode' }
+ * ```
+ */
+export declare function denyCall(call: ToolCall, reason: string | undefined): ToolResult;
+
+/**
+ * Estimates the context-token footprint of a batch of messages — the default `consumer`
  * estimator for an agent's context `BudgetInterface` (a budgets surface's tracking contract)
  * (the {@link import('./types.js').AgentOptions} `window`).
  *
@@ -2495,7 +2757,7 @@ export declare const DEFAULT_CONVERSATION_KEEP = 0;
  * 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 `consume` to
+ * turn's new messages through; a caller wanting a sharper count supplies its own `consumer` to
  * `createBudget` instead. Total — never throws: a `calls` `JSON.stringify` that throws (a
  * circular `ToolCall.arguments`) is caught and replaced with a conservative fixed contribution of
  * {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} (the same per-message overhead scale)
@@ -2510,10 +2772,10 @@ export declare const DEFAULT_CONVERSATION_KEEP = 0;
  * estimateMessages([{ id: '1', role: 'user', content: 'hello' }]) // 6  (2 content + 4 overhead)
  * ```
  */
-export declare function estimateMessages(messages: readonly MessageInterface[]): number;
+export declare function estimateMessages(messages: readonly Message[]): number;
 
 /**
- * Estimate the context-token footprint of a string — the deterministic char-based heuristic
+ * Estimates the context-token footprint of a string — the deterministic char-based heuristic
  * {@link estimateMessages} sums over a conversation's messages (the default context-budget
  * estimator).
  *
@@ -2537,34 +2799,7 @@ export declare function estimateMessages(messages: readonly MessageInterface[]):
 export declare function estimateTokens(text: string): number;
 
 /**
- * Render a path-addressed text body as a fenced reference block — the framing an
- * {@link import('./AgentContext.js').AgentContext}'s ACTIVE-workspace text-file render emits (the
- * active workspace is the SOLE document/image context).
- *
- * @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).
- *
- * @param path - The file path shown on the `File:` label line
- * @param language - The fenced-code language tag (e.g. `'typescript'`)
- * @param content - The file body rendered verbatim inside the fence
- * @returns The fenced reference block
- *
- * @example
- * ```ts
- * import { fencedFile } from '@src/core'
- *
- * fencedFile('src/main.ts', 'typescript', 'const x = 1')
- * // 'File: src/main.ts\n```typescript\nconst x = 1\n```'
- * ```
- */
-export declare function fencedFile(path: string, language: string, content: string): string;
-
-/**
- * Filter a list of items by a {@link import('./types.js').ScopeInterface} allow-list of
+ * Filters a list of items by a {@link import('./types.js').ScopeInterface} allow-list of
  * keys — the pure, total set-membership primitive the context's build step and the agent
  * loop's tool-advertise step apply a scope through.
  *
@@ -2581,7 +2816,7 @@ export declare function fencedFile(path: string, language: string, content: stri
  * @typeParam T - The item type being filtered
  * @param allow - The allow-list of keys (`undefined` ⇒ all, `[]` ⇒ none, else only-listed)
  * @param items - The items to filter (returned unchanged when `allow` is `undefined`)
- * @param key - Extracts the key an item is matched on (e.g. an instruction's `name`)
+ * @param key - Extracts the key an item is matched on (for example an instruction's `name`)
  * @returns The items that pass the allow-list, in their original order
  *
  * @example
@@ -2595,19 +2830,19 @@ export declare function fencedFile(path: string, language: string, content: stri
 export declare function filterAllowList<T>(allow: readonly string[] | undefined, items: readonly T[], key: (item: T) => string): readonly T[];
 
 /**
- * Handle one queued agent job by rehydrating it through a registry with the queue
+ * Handles one queued agent job by rehydrating it through a registry with the queue
  * attempt's signal, then applying the shared partial-result policy.
  *
  * @param registry - The registry that rehydrates the serializable job
- * @param allowPartial - Whether a partial result resolves instead of throwing
+ * @param partial - The partial policy. If `true`, a partial result resolves; if `false`, it throws
  * @param input - The serializable agent job
- * @param execution - The queue attempt whose signal bounds the agent
+ * @param context - The queue attempt whose signal bounds the agent
  * @returns The settled agent result
  */
-export declare function handleAgentQueueJob(registry: AgentRegistryInterface, allowPartial: boolean, input: AgentJobInput, execution: QueueExecution): Promise<AgentResult>;
+export declare function handleAgentQueueJob(registry: AgentRegistryInterface, partial: boolean, input: AgentJobInput, context: QueueContext): Promise<AgentResult>;
 
 /**
- * Handle one runner agent job by fanning out its declared children, rehydrating the
+ * 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.
  *
@@ -2616,14 +2851,14 @@ export declare function handleAgentQueueJob(registry: AgentRegistryInterface, al
  * inline, preserving bounded-runner progress.
  *
  * @param registry - The registry that rehydrates serializable jobs
- * @param allowPartial - Whether a partial result resolves instead of throwing
+ * @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
  */
-export declare function handleAgentRunnerJob(registry: AgentRegistryInterface, allowPartial: boolean, controller: ControllerInterface<AgentJobInput, AgentResult>): Promise<AgentResult>;
+export declare function handleAgentRunnerJob(registry: AgentRegistryInterface, partial: boolean, controller: ControllerInterface<AgentJobInput, AgentResult>): Promise<AgentResult>;
 
 /**
- * The coarse, deliberately-approximate per-image token cost {@link import('./helpers.js').estimateMessages}
+ * Names the coarse, deliberately-approximate per-image token cost {@link import('./helpers.js').estimateMessages}
  * charges for each attached image.
  *
  * @remarks
@@ -2635,15 +2870,15 @@ export declare function handleAgentRunnerJob(registry: AgentRegistryInterface, a
 export declare const IMAGE_TOKEN_ESTIMATE = 512;
 
 /**
- * An immutable named directive — a {@link InstructionInterface} assembled once from its
- * input (`name` / `content`, an optional `priority` defaulting to `0`), the `id` minted
- * at construction.
+ * Represents an immutable named directive — a {@link InstructionInterface} assembled once
+ * from its input (`name` / `content`, an optional `priority` defaulting to `0`), the `id`
+ * minted at construction.
  *
  * @remarks
  * A thin immutable value object (mirroring {@link import('@orkestrel/tool').Tool}): the
  * constructor mints a fresh `id` (`crypto.randomUUID()`), copies the input's `name` /
  * `content`, resolves `priority` to the input's value or `0`, and carries the input's
- * per-item `format` override ONLY when supplied (assigned just when present, mirroring a
+ * per-item `override` ONLY when supplied (assigned when present, mirroring a
  * message's `images` / `calls` present-when-given convention — kept absent otherwise).
  * Never mutated after construction. An
  * {@link import('./InstructionManager.js').InstructionManager} keys it by `name` and
@@ -2660,77 +2895,77 @@ export declare class Instruction implements InstructionInterface {
     readonly name: string;
     readonly content: string;
     readonly priority: number;
-    readonly format?: string;
+    readonly override?: string;
     constructor(input: InstructionInput);
 }
 
 /**
- * The minimal data to author an {@link InstructionInterface} — the `id` is minted by
+ * Carries the minimal data to author an {@link InstructionInterface} — the `id` is minted by
  * the {@link InstructionManagerInterface} that stores it, so a caller supplies only
  * `name` / `content` (and an optional `priority`, defaulting to `0`).
  */
 export declare interface InstructionInput {
     readonly name: string;
     readonly content: string;
-    /** Ordering weight (higher renders first); defaults to `0` when omitted. */
+    /** Weights the ordering (higher renders first); defaults to `0` when omitted. */
     readonly priority?: number;
     /**
-     * A fully-rendered override of THIS instruction's prompt text — the most-specific
+     * Holds a fully-rendered override of THIS instruction's prompt text — the most-specific
      * level of the {@link import('./AgentContext.js').AgentContext} build cascade (beats a
      * manager-options / provider / built-in format for this item). Round-tripped onto the
      * stored {@link InstructionInterface} when given (present-when-supplied, like `images`).
      */
-    readonly format?: string;
+    readonly override?: string;
 }
 
 /**
- * An immutable instruction — a named directive a richer context places between the
+ * Represents an immutable instruction — a named directive a richer context places between the
  * system prompt and the conversation, ordered by descending {@link priority}.
  *
  * @remarks
  * Assembled once from its {@link InstructionInput} (the `id` minted by the storing
  * layer) and never mutated. `name` keys it in an {@link InstructionManagerInterface}
  * (last write wins); `priority` orders the rendered list (higher first), defaulting to
- * `0`. The {@link import('./AgentContext.js').AgentContext} build step renders it via
- * its manager's `format` (`content`) under the manager's `description` header.
+ * `0`. The {@link import('./AgentContext.js').AgentContext} build step renders it through
+ * its manager's `render` (`content`) under the manager's `open` header.
  */
 export declare interface InstructionInterface {
     readonly id: string;
     readonly name: string;
     readonly content: string;
-    /** Higher renders first; defaults to `0`. */
+    /** Ranks the instruction — higher renders first; defaults to `0`. */
     readonly priority: number;
     /**
-     * A fully-rendered per-item override of this instruction's prompt text — the
+     * Holds a fully-rendered per-item override of this instruction's prompt text — the
      * MOST-SPECIFIC level of the {@link import('./AgentContext.js').AgentContext} build
      * cascade, beating every format level for THIS item. Present only when supplied on the
      * {@link InstructionInput} (round-tripped through the manager, like a message's
      * `images`); absent ⇒ the cascade decides.
      */
-    readonly format?: string;
+    readonly override?: string;
 }
 
 /**
- * The instruction registry a richer context assembles a directives block from —
- * immutable {@link Instruction}s keyed by `name`, listed by descending `priority`.
+ * Registers the immutable {@link Instruction}s a richer context assembles a directives
+ * block from — keyed by `name`, listed by descending `priority`.
  *
  * @remarks
  * - **Registry.** Instructions live in an insertion-ordered `Map` keyed by `name`;
- *   `add` takes one {@link InstructionInput} or a batch (§9.2), MINTS each instruction's
+ *   `add` takes one {@link InstructionInput} or a batch, MINTS each instruction's
  *   `id`, and a re-`add` of the same name OVERWRITES it (last write wins). `count` is the
  *   map size, `instruction(name)` looks one up, and `instructions()` lists them SORTED by
  *   descending `priority` (a stable sort, so equal priorities keep insertion order).
- * - **Build contract (with the manager-options override).** `description` is the section
- *   header a context renders the instructions under; `format(instruction)` renders one
+ * - **Build contract (with the manager-options override).** `open` is the section
+ *   header a context renders the instructions under; `render(instruction)` renders one
  *   instruction (its `content`). Each ENCAPSULATES the cascade's `[options-override →
  *   built-in]` half: when `InstructionManagerOptions.format` supplies an `open` /
- *   `render`, `description` / `format` return IT, else the built-in — so a richer context
+ *   `render`, `open` / `render` return IT, else the built-in — so a richer context
  *   reads one consistent pair and layers the provider default + per-item override on top
  *   (see {@link import('../AgentContext.js').AgentContext}). The per-item
- *   {@link InstructionInput.format} is round-tripped onto the stored instruction.
- * - **Removal.** `remove` drops one by name, or a batch (§9.2) — `true` when any was
- *   removed; `clear` empties the registry.
- * - **Observable (§13).** The owned {@link emitter} ({@link InstructionManagerEventMap})
+ *   {@link InstructionInput.override} is round-tripped onto the stored instruction.
+ * - **Removal.** `remove` drops one by name, or a batch — `true` only when EVERY supplied
+ *   name was removed; `clear` empties the registry.
+ * - **Observable.** The owned {@link emitter} ({@link InstructionManagerEventMap})
  *   carries `add` (the created instruction) / `remove` (the name) / `clear` for
  *   fire-and-forget observers. Every event is emitted directly, strictly AFTER the map
  *   mutation completes; the emitter isolates a listener throw and routes it to its `error`
@@ -2751,105 +2986,129 @@ export declare class InstructionManager implements InstructionManagerInterface {
     constructor(options?: InstructionManagerOptions);
     get emitter(): EmitterInterface<InstructionManagerEventMap>;
     get count(): number;
-    get description(): string;
-    get framing(): ContextSectionFormat<InstructionInterface> | undefined;
+    get open(): string;
+    get format(): ContextSectionFormat<InstructionInterface> | undefined;
     add(input: InstructionInput): InstructionInterface;
     add(inputs: readonly InstructionInput[]): readonly InstructionInterface[];
     instruction(name: string): InstructionInterface | undefined;
     instructions(): readonly InstructionInterface[];
-    format(instruction: InstructionInterface): string;
+    render(instruction: InstructionInterface): string;
     remove(name: string): boolean;
     remove(names: readonly string[]): boolean;
     clear(): void;
 }
 
 /**
- * The push observation surface (§13) of an {@link InstructionManagerInterface} — the
- * mutation moments a fire-and-forget observer subscribes to via `manager.emitter.on`.
+ * Maps the push observation surface of an {@link InstructionManagerInterface} — the
+ * mutation moments a fire-and-forget observer subscribes to through `manager.emitter.on`.
  *
  * @remarks
  * `add` carries the created (or replaced) {@link InstructionInterface}; `remove`
  * carries the removed instruction's `name`; `clear` is a pure signal (no payload).
- * Listener isolation is the emitter's (AGENTS §13): a listener throw is routed to the
+ * Listener isolation is the emitter's: a listener throw is routed to the
  * emitter's `error` handler (the `error` option), never onto this map, so a buggy
  * observer can never corrupt a mutation. Declared as a `type` alias (not `interface
- * extends EventMap`, §4.5) so the type-literal satisfies `EventMap` structurally.
+ * extends EventMap`) so the type-literal satisfies `EventMap` structurally.
  */
 export declare type InstructionManagerEventMap = {
-    /** An instruction was added (or a same-name one replaced) — the created instruction. */
+    /** Reports an instruction added (or a same-name one replaced) — the created instruction. */
     readonly add: readonly [instruction: InstructionInterface];
-    /** An instruction was removed — its `name`. */
+    /** Reports an instruction removed — its `name`. */
     readonly remove: readonly [name: string];
-    /** Every instruction was removed. */
+    /** Reports every instruction removed. */
     readonly clear: readonly [];
 };
 
 /**
- * A registry of {@link InstructionInterface}s keyed by `name` — `add` (one or a batch,
- * §9.2) mints each `id` and OVERWRITES a same-name instruction (last write wins);
+ * Registers {@link InstructionInterface}s keyed by `name` — `add` (one or a batch)
+ * mints each `id` and OVERWRITES a same-name instruction (last write wins);
  * `instructions()` lists them SORTED by descending `priority` (stable for ties).
  *
  * @remarks
- * - **Build contract.** `description` is the section header a richer context renders
- *   the instructions under; `format(instruction)` renders one instruction (its
+ * - **Build contract.** `open` is the section header a richer context renders
+ *   the instructions under; `render(instruction)` renders one instruction (its
  *   `content`). Together they let an {@link import('./AgentContext.js').AgentContext}
  *   assemble an instructions block.
- * - **Observable (§13).** The owned `emitter` ({@link InstructionManagerEventMap})
+ * - **Observable.** The owned `emitter` ({@link InstructionManagerEventMap})
  *   carries `add` / `remove` / `clear` for fire-and-forget observers; the emitter
- *   isolates a listener throw and routes it to its `error` handler (the `error` option, §13).
+ *   isolates a listener throw and routes it to its `error` handler (the `error` option).
  */
 export declare interface InstructionManagerInterface {
     readonly emitter: EmitterInterface<InstructionManagerEventMap>;
     readonly count: number;
-    /** The section header a context renders the instructions under. */
-    readonly description: string;
+    /** Names the section header a context renders the instructions under. */
+    readonly open: string;
     /**
-     * The manager-options format override (the {@link InstructionManagerOptions.format}
+     * Holds the manager-options format override (the {@link InstructionManagerOptions.format}
      * supplied at construction), or `undefined` when none — the MANAGER-OPTIONS level of the
      * {@link import('./AgentContext.js').AgentContext} build cascade, exposed so `build()`
-     * can interleave the provider default BENEATH it (`description` / `format` already
+     * can interleave the provider default BENEATH it (`open` / `render` already
      * encapsulate the `[override → built-in]` half for standalone use). A `readonly` data
      * member, not a method.
      */
-    readonly framing: ContextSectionFormat<InstructionInterface> | undefined;
+    readonly format: ContextSectionFormat<InstructionInterface> | undefined;
     add(input: InstructionInput): InstructionInterface;
     add(inputs: readonly InstructionInput[]): readonly InstructionInterface[];
     instruction(name: string): InstructionInterface | undefined;
-    /** Every instruction, sorted by descending `priority` (stable for equal priorities). */
+    /** Lists every instruction, sorted by descending `priority` (stable for equal priorities). */
     instructions(): readonly InstructionInterface[];
-    /** Render one instruction for the prompt — its `content`. */
-    format(instruction: InstructionInterface): string;
+    /** Renders one instruction for the prompt — its `content`. */
+    render(instruction: InstructionInterface): string;
     remove(name: string): boolean;
     remove(names: readonly string[]): boolean;
     clear(): void;
 }
 
 /**
- * Options for `createInstructionManager` — the reserved `on` hooks (§8) plus an optional
+ * Configures `createInstructionManager` — the reserved `on` hooks plus an optional
  * per-section format override.
  *
  * @remarks
- * `on` is the §8 reserved key: initial listeners for the manager's
+ * `on` is the reserved listener key: initial listeners for the manager's
  * {@link InstructionManagerEventMap}, wired at construction. `format` is the
  * MANAGER-OPTIONS level of the {@link import('./AgentContext.js').AgentContext} build
  * cascade — a {@link ContextSectionFormat} the manager consults FIRST in its own
- * `description` / `format` (falling back to the built-in when a member is omitted), so it
+ * `open` / `render` (falling back to the built-in when a member is omitted), so it
  * BEATS the provider default and the built-in, while a per-item
- * {@link InstructionInput.format} still beats it. Omitted ⇒ the built-in framing applies.
+ * {@link InstructionInput.override} still beats it. Omitted ⇒ the built-in framing applies.
  */
 export declare interface InstructionManagerOptions {
     readonly on?: EmitterHooks<InstructionManagerEventMap>;
-    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    /** Holds the emitter's listener-error handler — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
-    /** A manager-level format override (beats the provider default + built-in); see {@link AgentContextInterface.build}. */
+    /** Holds a manager-level format override (beats the provider default + built-in); see {@link AgentContextInterface.build}. */
     readonly format?: ContextSectionFormat<InstructionInterface>;
 }
 
 /**
- * Narrow an unknown caught value to an {@link AgentError}.
+ * Intersects two scope category lists under the "`undefined` is the universal set" rule — the
+ * primitive a scope narrows through.
+ *
+ * @remarks
+ * Pure and total, and it can only TIGHTEN: `undefined` ∩ `undefined` is `undefined` (still no
+ * constraint); `undefined` ∩ a list is a COPY of that list (the `undefined` side imposes
+ * nothing); a list ∩ a list keeps the child keys the parent also allows, so a parent-excluded
+ * key can never be re-admitted. Every returned list is a fresh copy, so a later mutation of
+ * either input cannot leak into the result.
+ *
+ * @param parent - The parent's allow-list (`undefined` ⇒ no constraint)
+ * @param child - The narrowing allow-list (`undefined` ⇒ no constraint)
+ * @returns The intersected allow-list, or `undefined` when neither side constrains
+ *
+ * @example
+ * ```ts
+ * intersectKeys(['read', 'write'], ['write', 'admin']) // ['write']
+ * intersectKeys(undefined, ['read']) // ['read']
+ * intersectKeys(undefined, undefined) // undefined
+ * ```
+ */
+export declare function intersectKeys(parent: readonly string[] | undefined, child: readonly string[] | undefined): readonly string[] | undefined;
+
+/**
+ * Narrows an unknown caught value to an {@link AgentError}.
  *
  * @param value - The value to test (typically a `catch` binding)
- * @returns `true` when `value` is an {@link AgentError}
+ * @returns True if `value` is an {@link AgentError}; false otherwise
  *
  * @example
  * ```ts
@@ -2863,10 +3122,10 @@ export declare interface InstructionManagerOptions {
 export declare function isAgentError(value: unknown): value is AgentError;
 
 /**
- * Narrow an unknown caught value to an {@link AgentJobError}.
+ * Narrows an unknown caught value to an {@link AgentJobError}.
  *
  * @param value - The value to test (typically a `catch` binding or a rejected enqueue)
- * @returns `true` when `value` is an {@link AgentJobError}
+ * @returns True if `value` is an {@link AgentJobError}; false otherwise
  *
  * @example
  * ```ts
@@ -2880,10 +3139,10 @@ export declare function isAgentError(value: unknown): value is AgentError;
 export declare function isAgentJobError(value: unknown): value is AgentJobError;
 
 /**
- * Narrow an unknown caught value to a {@link ConversationError}.
+ * Narrows an unknown caught value to a {@link ConversationError}.
  *
  * @param value - The value to test (typically a `catch` binding)
- * @returns `true` when `value` is a {@link ConversationError}
+ * @returns True if `value` is a {@link ConversationError}; false otherwise
  *
  * @example
  * ```ts
@@ -2897,7 +3156,7 @@ export declare function isAgentJobError(value: unknown): value is AgentJobError;
 export declare function isConversationError(value: unknown): value is ConversationError;
 
 /**
- * Narrow an `unknown` to a {@link ConversationSnapshot} — the AGENTS §14 boundary guard for an
+ * Narrows an `unknown` to a {@link ConversationSnapshot} — the total boundary guard for an
  * UNTRUSTED snapshot read (a storage row a
  * {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore}
  * reads back from its opaque JSON column, a snapshot loaded from disk). The EXACT analogue of
@@ -2907,8 +3166,8 @@ export declare function isConversationError(value: unknown): value is Conversati
  * A total guard (it NEVER throws — adversarial input returns `false`). It checks the snapshot's
  * SHAPE: a `string` `id`, an OPTIONAL `string` `summary` (present-or-absent — the rollup is
  * `undefined` until the first compaction), a `sections` array EVERY element of which is a valid
- * {@link SectionInterface} ({@link isSection}), and a `messages` array EVERY element of which is a
- * valid {@link MessageInterface} ({@link isMessage}) — enough to safely impose the
+ * {@link Section} ({@link isSection}), and a `messages` array EVERY element of which is a
+ * valid {@link Message} ({@link isMessage}) — enough to safely impose the
  * {@link ConversationSnapshot} type at a storage boundary WITHOUT a cast. The structural twin of
  * {@link import('@orkestrel/workspace').isWorkspaceSnapshot}. A malformed blob (a non-record, a missing / non-string `id`, a
  * non-string `summary` when present, a non-array `sections` / `messages`, or any malformed
@@ -2917,7 +3176,7 @@ export declare function isConversationError(value: unknown): value is Conversati
  * read yields `undefined` rather than a broken conversation.
  *
  * @param value - The value to test (an opaque storage read)
- * @returns `true` when `value` has the structural shape of a {@link ConversationSnapshot}
+ * @returns True if `value` has the structural shape of a {@link ConversationSnapshot}; false otherwise
  *
  * @example
  * ```ts
@@ -2930,9 +3189,9 @@ export declare function isConversationError(value: unknown): value is Conversati
 export declare function isConversationSnapshot(value: unknown): value is ConversationSnapshot;
 
 /**
- * Whether an `unknown` is structurally a {@link MessageInterface} record — the per-message step of
- * the {@link isConversationSnapshot} read-boundary narrow (AGENTS §14: narrow an untrusted storage
- * read via a guard, never an `as`). The conversation analogue of
+ * Checks whether an `unknown` is structurally a {@link Message} record — the per-message step of
+ * the {@link isConversationSnapshot} read-boundary narrow (a total guard over an untrusted storage
+ * read, never an assertion). The conversation analogue of
  * {@link import('@orkestrel/workspace').isFile}.
  *
  * @remarks
@@ -2940,16 +3199,16 @@ export declare function isConversationSnapshot(value: unknown): value is Convers
  * SHAPE: a record with a `string` `id`, a `string` `role`, a `string` `content`, and — WHEN present
  * — a `calls` array EVERY element of which is a valid
  * {@link import('@orkestrel/tool').ToolCall} ({@link isToolCall} — the
- * ASI06 fail-closed deepening: a tampered `calls` element rejects the message, so the snapshot
+ * fail-closed deepening: a tampered `calls` element rejects the message, so the snapshot
  * reads back as absent rather than replaying a malformed call) and an `images` that is an array
  * (an absent optional passes). The `role` is left as a broad `string` here (an open
  * {@link import('./types.js').MessageRole}, so any storage-read role string is accepted
  * defensively rather than rejected against the current literal set). Enough to safely impose the
- * {@link MessageInterface} type at
+ * {@link Message} type at
  * a storage boundary WITHOUT a cast.
  *
  * @param value - The value to test (one element of a snapshot's `messages` / a section's `messages`)
- * @returns `true` when `value` has the structural shape of a {@link MessageInterface}
+ * @returns True if `value` has the structural shape of a {@link Message}; false otherwise
  *
  * @example
  * ```ts
@@ -2959,13 +3218,13 @@ export declare function isConversationSnapshot(value: unknown): value is Convers
  * isMessage({ id: '1', role: 'assistant', content: '', calls: [null] }) // false (malformed call)
  * ```
  */
-export declare function isMessage(value: unknown): value is MessageInterface;
+export declare function isMessage(value: unknown): value is Message;
 
 /**
- * Narrow an unknown caught value to a {@link ProviderAbortError}.
+ * Narrows an unknown caught value to a {@link ProviderAbortError}.
  *
  * @param value - The value to test (typically a `catch` binding)
- * @returns `true` when `value` is a {@link ProviderAbortError}
+ * @returns True if `value` is a {@link ProviderAbortError}; false otherwise
  *
  * @example
  * ```ts
@@ -2979,18 +3238,18 @@ export declare function isMessage(value: unknown): value is MessageInterface;
 export declare function isProviderAbortError(value: unknown): value is ProviderAbortError;
 
 /**
- * Whether an `unknown` is structurally a {@link SectionInterface} record — the per-section step of
- * the {@link isConversationSnapshot} read-boundary narrow (AGENTS §14: narrow an untrusted storage
- * read via a guard, never an `as`).
+ * Checks whether an `unknown` is structurally a {@link Section} record — the per-section step of
+ * the {@link isConversationSnapshot} read-boundary narrow (a total guard over an untrusted storage
+ * read, never an assertion).
  *
  * @remarks
  * A total guard (it NEVER throws — adversarial input returns `false`). It checks the section's
  * SHAPE: a record with a `string` `id`, a `string` `summary`, and a `messages` array EVERY element
- * of which is a valid {@link MessageInterface} record ({@link isMessage}). Enough to safely impose
- * the {@link SectionInterface} type at a storage boundary WITHOUT a cast.
+ * of which is a valid {@link Message} record ({@link isMessage}). Enough to safely impose
+ * the {@link Section} type at a storage boundary WITHOUT a cast.
  *
  * @param value - The value to test (one element of a snapshot's `sections` array)
- * @returns `true` when `value` has the structural shape of a {@link SectionInterface}
+ * @returns True if `value` has the structural shape of a {@link Section}; false otherwise
  *
  * @example
  * ```ts
@@ -2999,17 +3258,39 @@ export declare function isProviderAbortError(value: unknown): value is ProviderA
  * isSection({ id: 's', messages: [] }) // false (missing summary)
  * ```
  */
-export declare function isSection(value: unknown): value is SectionInterface;
+export declare function isSection(value: unknown): value is Section;
+
+/**
+ * Joins the reasoning a run's provider calls separated from the answer — the first call
+ * seeds the accumulation, a later call appends blank-line separated so each turn's reasoning
+ * stays readable.
+ *
+ * @remarks
+ * Pure and total. `running` is `undefined` until a call surfaces reasoning, so the first join
+ * returns `next` verbatim (no leading separator). The result is display/audit metadata that
+ * never re-enters the conversation.
+ *
+ * @param running - The reasoning accumulated so far (`undefined` before the first)
+ * @param next - This call's separated reasoning
+ * @returns The joined reasoning
+ *
+ * @example
+ * ```ts
+ * joinThinking(undefined, 'first') // 'first'
+ * joinThinking('first', 'second') // 'first\n\nsecond'
+ * ```
+ */
+export declare function joinThinking(running: string | undefined, next: string): string;
 
 /**
- * The in-memory {@link ConversationStoreInterface} — a process-lifetime `Map` of
+ * Implements the {@link ConversationStoreInterface} in memory — a process-lifetime `Map` of
  * {@link ConversationSnapshot}s keyed by conversation id, the DEFAULT store
  * {@link import('../../factories.js').createMemoryConversationStore} builds. The EXACT twin of
  * {@link import('@orkestrel/workspace').MemoryWorkspaceStore}.
  *
  * @remarks
- * A plain `Map<string, ConversationSnapshot>` (AGENTS §21 — the snapshot is already pure,
- * self-contained JSON, so no encoding is needed for the memory tier). Like the
+ * A plain `Map<string, ConversationSnapshot>` — the snapshot is already pure,
+ * self-contained JSON, so no encoding is needed for the memory tier. Like the
  * {@link import('@orkestrel/workspace').MemoryWorkspaceStore} it twins,
  * there is NO idle-TTL and NO eviction: a persisted conversation lives until an explicit `delete`. A
  * durable backend (JSON / SQLite / IndexedDB) swaps in through the SAME interface without touching
@@ -3022,14 +3303,14 @@ export declare function isSection(value: unknown): value is SectionInterface;
  * - **`set` inserts / replaces under the snapshot's OWN `id`** (no separate id param).
  * - **`delete` drops a snapshot by id**; an absent id is a no-op (no throw).
  *
- * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the §22 method
+ * The public surface is EXACTLY `get` / `set` / `delete` — no extra members (the method
  * bijection with {@link ConversationStoreInterface}). Hydration is a caller concern: a
  * {@link import('../ConversationManager.js').ConversationManager} reads a snapshot back and rebuilds
- * the live conversation through the constructor `seed` (its `open` / `save`).
+ * the live conversation through the `snapshot` option (its `open` / `save`).
  *
  * @example
  * ```ts
- * import { createConversation, createMemoryConversationStore } from '@src/core'
+ * import { createConversation, createMemoryConversationStore } from '@orkestrel/agent'
  *
  * const store = createMemoryConversationStore()
  * const conversation = createConversation()
@@ -3047,31 +3328,7 @@ export declare class MemoryConversationStore implements ConversationStoreInterfa
 }
 
 /**
- * The estimated per-message role/framing overhead {@link import('./helpers.js').estimateMessages}
- * adds on top of a message's content estimate — accounts for the fixed wire framing every
- * conversation turn carries (its role tag, delimiters) that {@link import('./helpers.js').estimateTokens}'s
- * content-only heuristic does not otherwise capture.
- */
-export declare const MESSAGE_TOKEN_OVERHEAD = 4;
-
-/**
- * The minimal data needed to author a {@link MessageInterface} — the `id` is
- * assigned by the layer that stores it, so a caller supplies only role / content
- * (and, for a replayed assistant turn, its `calls`).
- */
-export declare interface MessageInput {
-    readonly role: MessageRole;
-    readonly content: string;
-    readonly calls?: readonly ToolCall[];
-    /**
-     * Multimodal image data for this turn — base64-encoded image strings forwarded to a
-     * vision-capable provider (carried verbatim onto the stored {@link MessageInterface}).
-     */
-    readonly images?: readonly string[];
-}
-
-/**
- * One conversation turn fed to a {@link ProviderInterface} — a stored, identified
+ * Represents one conversation turn fed to a {@link ProviderInterface} — a stored, identified
  * message.
  *
  * @remarks
@@ -3080,14 +3337,14 @@ export declare interface MessageInput {
  * the model sees its own decision. A `tool` turn carries the tool's result in
  * `content` (the textual outcome), keyed back to the call by the conversation order.
  */
-export declare interface MessageInterface {
+export declare interface Message {
     readonly id: string;
     readonly role: MessageRole;
     readonly content: string;
-    /** An assistant turn that requested tools — its `tool_calls`, replayed. */
+    /** Holds an assistant turn's requested tools — its `tool_calls`, replayed. */
     readonly calls?: readonly ToolCall[];
     /**
-     * Multimodal image data attached to this turn — base64-encoded image strings,
+     * Holds multimodal image data attached to this turn — base64-encoded image strings,
      * forwarded to a vision-capable provider (the provider maps them onto the wire's
      * per-message `images` array). Present only on a multimodal turn; absent otherwise.
      */
@@ -3095,56 +3352,82 @@ export declare interface MessageInterface {
 }
 
 /**
- * The conversation store — immutable {@link MessageInterface}s in insertion order;
- * `add` mints the `id`.
+ * Estimates the per-message role/framing overhead {@link import('./helpers.js').estimateMessages}
+ * adds on top of a message's content estimate — accounts for the fixed wire framing every
+ * conversation turn carries (its role tag, delimiters) that {@link import('./helpers.js').estimateTokens}'s
+ * content-only heuristic does not otherwise capture.
+ */
+export declare const MESSAGE_TOKEN_OVERHEAD = 4;
+
+/**
+ * Carries the minimal data needed to author a {@link Message} — the `id` is
+ * assigned by the layer that stores it, so a caller supplies only role / content
+ * (and, for a replayed assistant turn, its `calls`).
+ */
+export declare interface MessageInput {
+    readonly role: MessageRole;
+    readonly content: string;
+    readonly calls?: readonly ToolCall[];
+    /**
+     * Holds multimodal image data for this turn — base64-encoded image strings forwarded to a
+     * vision-capable provider (carried verbatim onto the stored {@link Message}).
+     */
+    readonly images?: readonly string[];
+}
+
+/**
+ * Stores immutable {@link Message}s in insertion order; `add` mints the `id`.
  *
  * @remarks
  * - **Store.** Messages live in insertion order; `count` is how many are stored.
- *   `add` takes one {@link MessageInput} or a batch (§9.2) and MINTS each message's
+ *   `add` takes one {@link MessageInput} or a batch and MINTS each message's
  *   `id` (a random UUID), returning the created message(s). A stored message is
  *   immutable — created once from its input, never mutated.
  * - **Lookup.** `message(id)` resolves one by id (`undefined` when absent);
  *   `messages()` lists every message in insertion order.
- * - **Removal.** `remove` drops one by id, or a batch (§9.2) — `true` when any was
- *   removed; `clear` empties the store.
+ * - **Removal.** `remove` drops one by id, or a batch — `true` only when EVERY supplied id
+ *   was removed; `clear` empties the store.
  * - **Event-free.** A purely data store — no Emitter, no events.
  */
 export declare interface MessageManagerInterface {
     readonly count: number;
-    add(input: MessageInput): MessageInterface;
-    add(inputs: readonly MessageInput[]): readonly MessageInterface[];
-    message(id: string): MessageInterface | undefined;
-    messages(): readonly MessageInterface[];
+    add(input: MessageInput): Message;
+    add(inputs: readonly MessageInput[]): readonly Message[];
+    message(id: string): Message | undefined;
+    messages(): readonly Message[];
     remove(id: string): boolean;
     remove(ids: readonly string[]): boolean;
     clear(): void;
 }
 
-/** The role a {@link MessageInterface} plays in a conversation turn. */
+/** Names the role a {@link Message} plays in a conversation turn. */
 export declare type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
 
 /**
- * Thrown by a {@link ProviderInterface}'s `stream` when its bound signal aborts
- * mid-flight — carries the {@link ProviderResult} assembled from whatever streamed
- * before the cancel.
+ * Reports a provider stream cancelled mid-flight by its bound signal — thrown by a
+ * {@link ProviderInterface}'s `stream`, carrying the {@link ProviderResult} assembled
+ * from whatever streamed before the cancel.
  *
  * @remarks
  * Lets a caller recover the partial content (and any tool calls / usage seen so far)
  * on cancellation: `catch` the throw, narrow with {@link isProviderAbortError}, and
- * read `partial`.
+ * read `partial`. `code` is the machine-readable condition (`'ABORT'` — the only one this
+ * error reports), so a `catch` branches on it rather than on the message string.
  */
 export declare class ProviderAbortError extends Error {
+    /** Names the machine-readable condition — `'ABORT'`: a stream cancelled mid-flight. */
+    readonly code: "ABORT";
     readonly partial: ProviderResult;
     constructor(partial: ProviderResult);
 }
 
 /**
- * One streamed delta a {@link ProviderInterface}'s `stream` yields — a TAGGED unit
+ * Represents one streamed delta a {@link ProviderInterface}'s `stream` yields — a TAGGED unit
  * discriminated by the channel it belongs to, so the agent loop can re-surface the two
  * channels separately (answer content vs. live reasoning) as it pumps.
  *
  * @remarks
- * The discriminant `type` names the CHANNEL axis (AGENTS §4.4 — never `kind`): a
+ * The discriminant `channel` names the axis that varies: a
  * `'content'` delta is a chunk of the assistant ANSWER (the deltas that accumulate into
  * {@link ProviderResult.content}); a `'thinking'` delta is a chunk of the model's
  * REASONING the provider separated from the answer (the daemon's native
@@ -3154,15 +3437,15 @@ export declare class ProviderAbortError extends Error {
  * as {@link ProviderResult.thinking} (the authoritative final accumulation) is.
  */
 export declare type ProviderDelta = {
-    readonly type: 'content';
+    readonly channel: 'content';
     readonly text: string;
 } | {
-    readonly type: 'thinking';
+    readonly channel: 'thinking';
     readonly text: string;
 };
 
 /**
- * The pluggable LLM inference boundary — the one contract every agent chunk depends
+ * Defines the pluggable LLM inference boundary — the one contract every agent chunk depends
  * on. A provider turns a conversation (plus optional tools) into either a single
  * assembled {@link ProviderResult} (`generate`) or a stream of {@link ProviderDelta}s that
  * RETURNS the assembled result (`stream`).
@@ -3171,35 +3454,35 @@ export declare type ProviderDelta = {
  * - `id` is a stable per-instance trace label; `name` identifies the backend
  *   (`'ollama'`).
  * - Both calls take an `AbortSignal` so a caller bounds the request (cancel,
- *   deadline, or budget folded via `AbortSignal.any`); aborting a `stream` mid-flight
+ *   deadline, or budget folded through `AbortSignal.any`); aborting a `stream` mid-flight
  *   surfaces a `ProviderAbortError` carrying the partial result.
  * - `tools`, when given non-empty, advertises the callable tools for this turn.
- * - `options` carries the optional per-call {@link ProviderStreamOptions} (e.g. `think`),
+ * - `options` carries the optional per-call {@link ProviderStreamOptions} (for example `think`),
  *   overriding the provider's constructed defaults for that one call; omitted ⇒ defaults.
  */
 export declare interface ProviderInterface {
     readonly id: string;
     readonly name: string;
     /**
-     * The model's preferred context framing, by section kind — an OPTIONAL
-     * {@link ContextFormatInterface} an {@link import('./AgentContext.js').AgentContext}
+     * Holds the model's preferred context framing, by section kind — an OPTIONAL
+     * {@link ContextFormat} an {@link import('./AgentContext.js').AgentContext}
      * applies as the PROVIDER-DEFAULT level of its build cascade (beating the managers'
      * built-in framing, beaten by a manager-options or per-item override). Omitted ⇒ the
      * provider is framing-agnostic and the managers' built-in defaults apply unchanged.
      */
-    readonly format?: ContextFormatInterface | undefined;
+    readonly format?: ContextFormat | undefined;
     /**
-     * Generate one complete turn — resolves the assembled {@link ProviderResult}.
+     * Generates one complete turn — resolves the assembled {@link ProviderResult}.
      *
      * @param messages - The conversation so far
      * @param signal - Bounds the request; an abort rejects the call
      * @param tools - Optional tools the model may call this turn
-     * @param options - Optional per-call {@link ProviderStreamOptions} (e.g. `think`); omitted ⇒ defaults
+     * @param options - Optional per-call {@link ProviderStreamOptions} (for example `think`); omitted ⇒ defaults
      * @returns The assembled result (content + any tool calls + any usage)
      */
-    generate(messages: readonly MessageInterface[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): Promise<ProviderResult>;
+    generate(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): Promise<ProviderResult>;
     /**
-     * Stream one turn — yields {@link ProviderDelta}s (channel-tagged `content` / `thinking`
+     * Streams one turn — yields {@link ProviderDelta}s (channel-tagged `content` / `thinking`
      * chunks) as they arrive and RETURNS the assembled {@link ProviderResult} (the
      * concatenated content + any separated reasoning + any tool calls + any usage) when the
      * stream completes.
@@ -3211,14 +3494,14 @@ export declare interface ProviderInterface {
      * @param messages - The conversation so far
      * @param signal - Bounds the request; an abort throws `ProviderAbortError`
      * @param tools - Optional tools the model may call this turn
-     * @param options - Optional per-call {@link ProviderStreamOptions} (e.g. `think`); omitted ⇒ defaults
+     * @param options - Optional per-call {@link ProviderStreamOptions} (for example `think`); omitted ⇒ defaults
      * @returns A generator of {@link ProviderDelta}s, returning the assembled result
      */
-    stream(messages: readonly MessageInterface[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
+    stream(messages: readonly Message[], signal: AbortSignal, tools?: readonly ToolDefinition[], options?: ProviderStreamOptions): AsyncGenerator<ProviderDelta, ProviderResult>;
 }
 
 /**
- * A single inference turn's structured outcome — the assembled assistant content,
+ * Holds a single inference turn's structured outcome — the assembled assistant content,
  * any reasoning the provider separated from it, any tool calls the model requested,
  * and the token usage it reported.
  *
@@ -3234,16 +3517,16 @@ export declare interface ProviderInterface {
  */
 export declare interface ProviderResult {
     readonly content: string;
-    /** Present ⇒ reasoning the provider separated from the answer — never re-enters the conversation. */
+    /** Carries reasoning the provider separated from the answer when present — never re-enters the conversation. */
     readonly thinking?: string;
-    /** Present ⇒ the model wants these tool calls. */
+    /** Carries the tool calls the model wants when present. */
     readonly tools?: readonly ToolCall[];
-    /** Present ⇒ token consumption for this turn (from the wire's `done` line / body). */
+    /** Carries token consumption for this turn when present (from the wire's `done` line / body). */
     readonly usage?: TokenUsage;
 }
 
 /**
- * Per-call options threaded into a {@link ProviderInterface}'s `generate` / `stream` —
+ * Carries the per-call options threaded into a {@link ProviderInterface}'s `generate` / `stream` —
  * the bag a caller passes to influence ONE inference call without reconfiguring the
  * provider instance.
  *
@@ -3259,28 +3542,151 @@ export declare interface ProviderResult {
  * that passes no options behaves exactly as before.
  */
 export declare interface ProviderStreamOptions {
-    /** Override the provider's reasoning preference for this call; omitted ⇒ the provider default. */
+    /** Overrides the provider's reasoning preference for this call; omitted ⇒ the provider default. */
     readonly think?: boolean;
-    /** Constrain the response to this JSON-Schema shape (the same open record {@link ToolDefinition.parameters} uses); omitted ⇒ no constraint. */
+    /** Constrains the response to this JSON-Schema shape (the same open record {@link ToolDefinition.parameters} uses); omitted ⇒ no constraint. */
     readonly schema?: Readonly<Record<string, unknown>>;
 }
 
 /**
- * The immutable per-run outcome value an {@link AgentInterface}'s loop replaces as it runs — the
- * assembled value its `stream`'s `result` promise resolves into a settled
- * {@link AgentResult} once the run completes.
+ * Renders a path-addressed text body as a fenced reference block — the framing an
+ * {@link import('./AgentContext.js').AgentContext}'s ACTIVE-workspace text-file render emits (the
+ * active workspace is the SOLE document/image context).
  *
  * @remarks
- * Created fresh per run (so concurrent runs never share state) and replaced through
- * the loop: `content` accumulates the streamed assistant text, `thinking` the
- * reasoning the provider calls separated from it ({@link ProviderResult.thinking},
- * joined across calls — `undefined` until one surfaces it), `usage` the summed
- * {@link TokenUsage} (present only when a provider call reported it), `partial`
- * flips `true` when a cancel commits the run early OR when the loop exhausts its
- * `limit` with unresolved tool intent, and `exhausted` flips `true` in that second
- * case specifically (a distinct, non-cancel cause the {@link AgentEventMap} `exhaust`
- * event observes). It is the INTERNAL precursor to the settled `AgentResult` — the
- * loop reads it back to assemble the public result — not a caller-facing shape.
+ * 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).
+ *
+ * @param path - The file path shown on the `File:` label line
+ * @param language - The fenced-code language tag (for example `'typescript'`)
+ * @param content - The file body rendered verbatim inside the fence
+ * @returns The fenced reference block
+ *
+ * @example
+ * ```ts
+ * import { renderFencedFile } from '@orkestrel/agent'
+ *
+ * renderFencedFile('src/main.ts', 'typescript', 'const x = 1')
+ * // 'File: src/main.ts\n```typescript\nconst x = 1\n```'
+ * ```
+ */
+export declare function renderFencedFile(path: string, language: string, content: string): string;
+
+/**
+ * Renders one context section — the resolved `open`, each item's rendering, and the resolved
+ * `close` when one exists, blank-line joined.
+ *
+ * @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` never appear without items. `close`
+ * is the only optional slot: an unset one (there is no built-in close) drops the
+ * trailing line.
+ *
+ * @typeParam T - The section item being rendered
+ * @param open - The section's resolved leading text
+ * @param items - 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
+ *
+ * @example
+ * ```ts
+ * renderSection('## Instructions', [{ content: 'Be terse.' }], (one) => one.content, undefined)
+ * // '## Instructions\n\nBe terse.'
+ * renderSection('<rules>', [], (one) => one.content, '</rules>') // undefined (no items)
+ * ```
+ */
+export declare function renderSection<T>(open: string, items: readonly T[], render: (item: T) => string, close: string | undefined): string | undefined;
+
+/**
+ * Resolves one section's CLOSE text through the format cascade — manager-options override >
+ * provider default.
+ *
+ * @remarks
+ * Pure and total. There is NO built-in close, so a section with neither level set returns
+ * `undefined` and {@link renderSection} appends no closing line. Paired with
+ * {@link resolveOpen}, one level can WRAP the whole group.
+ *
+ * @typeParam T - The section item the manager renders
+ * @param manager - The section source (its `format` override)
+ * @param provider - The provider-default framing for this section, or `undefined`
+ * @returns The section's trailing text, or `undefined` when no level sets one
+ *
+ * @example
+ * ```ts
+ * resolveClose(instructions, undefined) // undefined (no built-in close)
+ * resolveClose(instructions, { close: '</rules>' }) // '</rules>'
+ * ```
+ */
+export declare function resolveClose<T>(manager: ContextSectionSourceInterface<T>, provider: ContextSectionFormat<T> | undefined): string | undefined;
+
+/**
+ * Resolves ONE item's rendering through the format cascade — item override >
+ * manager-options override > provider default > built-in rendering.
+ *
+ * @remarks
+ * Pure and total. The item's own `override` is the most-specific level (a fully-rendered
+ * string for that item alone). A manager's `render(item)` already encapsulates
+ * `[options-override → built-in]`, so it is reached only when no higher level applies — and
+ * there it IS the built-in rendering.
+ *
+ * @typeParam T - The section item being rendered (it may carry its own `override`)
+ * @param manager - The section source (its `format` override + its built-in `render`)
+ * @param provider - The provider-default framing for this section, or `undefined`
+ * @param item - The item to render
+ * @returns The item's prompt text
+ *
+ * @example
+ * ```ts
+ * resolveItem(instructions, undefined, terse) // 'Be terse.' (the built-in rendering)
+ * resolveItem(instructions, { render: (one) => `<rule>${one.content}</rule>` }, terse)
+ * // '<rule>Be terse.</rule>'
+ * ```
+ */
+export declare function resolveItem<T extends {
+    readonly override?: string;
+}>(manager: ContextSectionSourceInterface<T>, provider: ContextSectionFormat<T> | undefined, item: T): string;
+
+/**
+ * Resolves one section's OPEN text through the format cascade — manager-options override >
+ * provider default > built-in header.
+ *
+ * @remarks
+ * Pure and total. The leading text has NO per-item level. A manager's `open` already
+ * encapsulates `[options-override → built-in]`, so it is reached only when neither the
+ * override's `open` nor the provider's `open` applies — and there it IS the built-in header.
+ *
+ * @typeParam T - The section item the manager renders
+ * @param manager - The section source (its `format` override + its built-in `open`)
+ * @param provider - The provider-default framing for this section, or `undefined`
+ * @returns The section's leading text
+ *
+ * @example
+ * ```ts
+ * resolveOpen(instructions, undefined) // '## Instructions' (the built-in header)
+ * resolveOpen(instructions, { open: '<rules>' }) // '<rules>' (the provider default)
+ * ```
+ */
+export declare function resolveOpen<T>(manager: ContextSectionSourceInterface<T>, provider: ContextSectionFormat<T> | undefined): string;
+
+/**
+ * Holds the immutable per-run outcome an {@link AgentInterface}'s loop settles on — the value its
+ * run RETURNS, assembled from there into the {@link AgentResult} its `stream`'s `result`
+ * promise resolves.
+ *
+ * @remarks
+ * Computed inside one run (so concurrent runs never share state) and returned once, when the
+ * loop settles: `content` is the streamed assistant text, `thinking` the reasoning the
+ * provider calls separated from it ({@link ProviderResult.thinking}, joined across calls —
+ * `undefined` when none surfaced), `usage` the summed {@link TokenUsage} (present only when
+ * a provider call 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
+ * it into the {@link AgentResult} its `stream`'s `result` promise resolves.
  */
 export declare interface RunOutcome {
     readonly content: string;
@@ -3291,7 +3697,7 @@ export declare interface RunOutcome {
 }
 
 /**
- * Sanitize one reported token count into a safe non-negative integer.
+ * Sanitizes one reported token count into a safe non-negative integer.
  *
  * @param value - The token count to sanitize
  * @returns The floored count, or `0` when the value is non-finite or non-positive
@@ -3299,7 +3705,7 @@ export declare interface RunOutcome {
 export declare function sanitizeToken(value: number): number;
 
 /**
- * Sanitize a {@link TokenUsage} into safe, non-negative integers — the guard an agent's
+ * Sanitizes a {@link TokenUsage} into safe, 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.
  *
@@ -3308,7 +3714,7 @@ export declare function sanitizeToken(value: number): number;
  * `-Infinity`) or a negative value floors to `0`; a fractional value floors to its
  * non-negative integer part. No upper cap is applied. Total — never throws.
  *
- * @param usage - The token usage to sanitize (e.g. a provider's abort-partial usage)
+ * @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
  *
  * @example
@@ -3319,14 +3725,14 @@ export declare function sanitizeToken(value: number): number;
 export declare function sanitizeUsage(usage: TokenUsage): TokenUsage;
 
 /**
- * A named, immutable filter over a richer context's items — three optional allow-lists,
- * one per category (`instructions` / `tools` / `files`), each keyed by that category's
- * identity (an instruction's `name`, a tool's `name`, a workspace file's `path`).
+ * Represents a named, immutable filter over a richer context's items — an optional
+ * allow-list per category (`instructions` / `tools` / `files`), each keyed by that
+ * category's identity (an instruction's `name`, a tool's `name`, a workspace file's `path`).
  *
  * @remarks
  * - **A category list is three-way.** `undefined` ⇒ NO constraint on that category (all
  *   pass); `[]` ⇒ NONE pass; a non-empty list ⇒ only the listed keys pass. The build
- *   step / loop apply this via `filterAllowList`.
+ *   step / loop apply this through `filterAllowList`.
  * - **Immutable.** The `id` is minted at construction; every supplied list is COPIED in
  *   (so a later mutation of the caller's array can't leak in), and the lists are
  *   `readonly`. A `Scope` is never mutated after construction — `narrow` returns a NEW
@@ -3349,19 +3755,18 @@ export declare function sanitizeUsage(usage: TokenUsage): TokenUsage;
  * ```
  */
 export declare class Scope implements ScopeInterface {
-    #private;
     readonly id: string;
     readonly name: string;
     readonly instructions?: readonly string[];
     readonly tools?: readonly string[];
     readonly files?: readonly string[];
     constructor(input: ScopeInput);
-    narrow(config: ScopeConfiguration): ScopeInterface;
+    narrow(config: ScopeFilter): ScopeInterface;
 }
 
 /**
- * The per-category allow-lists a {@link ScopeInterface} carries — three optional
- * `readonly string[]`s, one per filterable context category, each keyed by that
+ * Lists the per-category allow-lists a {@link ScopeInterface} carries — an optional
+ * `readonly string[]` for `instructions`, for `tools`, and for `files`, each keyed by that
  * category's identity (an instruction's `name`, a tool's `name`, a workspace file's
  * `path`).
  *
@@ -3373,13 +3778,13 @@ export declare class Scope implements ScopeInterface {
  * files (by `path`) in {@link AgentContextInterface.build} — both the text files folded into
  * the system block and the image files attached to the last user message.
  */
-export declare interface ScopeConfiguration {
-    /** Allowed instruction `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
+export declare interface ScopeFilter {
+    /** Lists the allowed instruction `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
     readonly instructions?: readonly string[];
-    /** Allowed tool `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
+    /** Lists the allowed tool `name`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed). */
     readonly tools?: readonly string[];
     /**
-     * Allowed ACTIVE-workspace file `path`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed) —
+     * Lists the allowed ACTIVE-workspace file `path`s (`undefined` ⇒ all, `[]` ⇒ none, else only-listed) —
      * the filter {@link AgentContextInterface.build} applies to the active workspace's
      * {@link import('@orkestrel/workspace').WorkspaceInterface.files} before rendering them (text → the system block, image →
      * the last user message).
@@ -3388,16 +3793,16 @@ export declare interface ScopeConfiguration {
 }
 
 /**
- * The data to author a {@link ScopeInterface} — a {@link ScopeConfiguration} plus the
+ * Carries the data to author a {@link ScopeInterface} — a {@link ScopeFilter} plus the
  * required `name` (a human label; the `id` is minted by the layer that stores it).
  */
-export declare interface ScopeInput extends ScopeConfiguration {
+export declare interface ScopeInput extends ScopeFilter {
     readonly name: string;
 }
 
 /**
- * A named, immutable filter over a richer context's items — the three per-category
- * allow-lists ({@link ScopeConfiguration}) plus an `id` / `name`, and a `narrow` that
+ * Represents a named, immutable filter over a richer context's items — the per-category
+ * allow-lists ({@link ScopeFilter}) plus an `id` / `name`, and a `narrow` that
  * composes a tighter child by set-INTERSECTION.
  *
  * @remarks
@@ -3407,22 +3812,22 @@ export declare interface ScopeInput extends ScopeConfiguration {
  * so `undefined ∩ list = list` and `undefined ∩ undefined = undefined`. Narrowing can
  * only TIGHTEN (a parent-excluded key never returns); the scope itself is never mutated.
  */
-export declare interface ScopeInterface extends ScopeConfiguration {
+export declare interface ScopeInterface extends ScopeFilter {
     readonly id: string;
     readonly name: string;
     /**
-     * Compose a tighter child scope — its per-category set is the intersection of this
+     * Composes a tighter child scope — its per-category set is the intersection of this
      * scope's list and `config`'s (an `undefined` side imposing no constraint).
      *
-     * @param config - The narrowing allow-lists (a `name`-less {@link ScopeConfiguration})
+     * @param config - The narrowing allow-lists (a `name`-less {@link ScopeFilter})
      * @returns A NEW, tighter {@link ScopeInterface} (this one is left unchanged)
      */
-    narrow(config: ScopeConfiguration): ScopeInterface;
+    narrow(config: ScopeFilter): ScopeInterface;
 }
 
 /**
- * The scope registry a richer context reuses named filters from — immutable {@link Scope}s
- * keyed by their minted `id`, in insertion order.
+ * Registers the named filters a richer context reuses — immutable {@link Scope}s keyed by
+ * their minted `id`, in insertion order.
  *
  * @remarks
  * - **Registry.** Scopes live in an insertion-ordered `Map` keyed by their minted `id`;
@@ -3431,9 +3836,9 @@ export declare interface ScopeInterface extends ScopeConfiguration {
  *   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.)
- * - **Removal.** `remove` drops one by id, or a batch (§9.2) — `true` when any was
- *   removed; `clear` empties the registry.
- * - **Observable (§13).** The owned {@link emitter} ({@link ScopeManagerEventMap}) carries
+ * - **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
  *   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
@@ -3449,7 +3854,7 @@ export declare interface ScopeInterface extends ScopeConfiguration {
  */
 export declare class ScopeManager implements ScopeManagerInterface {
     #private;
-    constructor(on?: EmitterHooks<ScopeManagerEventMap>, error?: EmitterErrorHandler);
+    constructor(options?: ScopeManagerOptions);
     get emitter(): EmitterInterface<ScopeManagerEventMap>;
     get count(): number;
     create(input: ScopeInput): ScopeInterface;
@@ -3461,43 +3866,43 @@ export declare class ScopeManager implements ScopeManagerInterface {
 }
 
 /**
- * The push observation surface (§13) of a {@link ScopeManagerInterface} — analogous to
+ * 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`.
  *
  * @remarks
  * `create` carries the created {@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 (§13). A `type` alias (§4.5) so it satisfies `EventMap` structurally.
+ * it to its `error` handler. A `type` alias so it satisfies `EventMap` structurally.
  */
 export declare type ScopeManagerEventMap = {
-    /** A scope was created — the created scope. */
+    /** Reports a scope created — the created scope. */
     readonly create: readonly [scope: ScopeInterface];
-    /** A scope was removed — its `id`. */
+    /** Reports a scope removed — its `id`. */
     readonly remove: readonly [id: string];
-    /** Every scope was removed. */
+    /** Reports every scope removed. */
     readonly clear: readonly [];
 };
 
 /**
- * A registry of reusable {@link ScopeInterface}s keyed by their minted `id` — `create`
+ * Registers reusable {@link ScopeInterface}s keyed by their minted `id` — `create`
  * mints + stores one (never overwrites), `scopes()` lists them in insertion order.
  *
  * @remarks
- * - **Registry.** `create(input)` mints a scope (an `id` + the three allow-lists) and
+ * - **Registry.** `create(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.)
- * - **Observable (§13).** The owned `emitter` ({@link ScopeManagerEventMap}) carries
+ * - **Observable.** The owned `emitter` ({@link ScopeManagerEventMap}) carries
  *   `create` / `remove` / `clear` for fire-and-forget observers; the emitter isolates a
- *   listener throw and routes it to its `error` handler (the `error` option, §13).
+ *   listener throw and routes it to its `error` handler (the `error` option).
  */
 export declare interface ScopeManagerInterface {
     readonly emitter: EmitterInterface<ScopeManagerEventMap>;
     readonly count: number;
     create(input: ScopeInput): ScopeInterface;
     scope(id: string): ScopeInterface | undefined;
-    /** Every scope, in insertion order. */
+    /** Lists every scope, in insertion order. */
     scopes(): readonly ScopeInterface[];
     remove(id: string): boolean;
     remove(ids: readonly string[]): boolean;
@@ -3505,59 +3910,60 @@ export declare interface ScopeManagerInterface {
 }
 
 /**
- * Options for `createScopeManager` — the reserved `on` hooks (§8): initial listeners for
+ * Configures `createScopeManager` — the reserved `on` hooks: initial listeners for
  * the manager's {@link ScopeManagerEventMap}, wired at construction.
  */
 export declare interface ScopeManagerOptions {
     readonly on?: EmitterHooks<ScopeManagerEventMap>;
-    /** The emitter's listener-error handler (AGENTS §13) — a listener throw routes here, not to a domain event. */
+    /** Holds the emitter's listener-error handler — a listener throw routes here, not to a domain event. */
     readonly error?: EmitterErrorHandler;
 }
 
 /**
- * A slice of folded messages digested into a summary — the unit of compaction a
+ * Holds a slice of folded messages digested into a summary — the unit of compaction a
  * {@link ConversationInterface} produces when it `compact`s its live tail.
  *
  * @remarks
- * `summary` is the model-written digest of this slice (via the
- * {@link ConversationSummarizer}); `messages` are the folded ORIGINALS, RETAINED in full so
+ * `summary` is the model-written digest of this slice (through the
+ * {@link ConversationSummaryHandler}); `messages` are the folded ORIGINALS, RETAINED in full so
  * `rehydrate` can pull them back and `search` can scan them (compaction shrinks the model
  * INPUT, never discards history).
  */
-export declare interface SectionInterface {
+export declare interface Section {
     readonly id: string;
-    /** The model-written digest of this slice (its {@link ConversationSummarizer} output). */
+    /** Holds the model-written digest of this slice (its {@link ConversationSummaryHandler} output). */
     readonly summary: string;
-    /** The folded original messages, RETAINED in full for `rehydrate` / `search`. */
-    readonly messages: readonly MessageInterface[];
+    /** Retains the folded original messages in full for `rehydrate` / `search`. */
+    readonly messages: readonly Message[];
 }
 
 /**
- * Run one rehydrated agent and apply the partial-as-configurable-failure policy — the
+ * Runs one rehydrated agent and applies the partial-as-configurable-failure policy — the
  * shared job-handler step BOTH `createAgentQueue` and `createAgentRunner` settle each job
  * through, so the policy can never diverge between them.
  *
  * @remarks
  * A turn that committed PARTIAL (a cancel — abort / budget / timeout) is by default a
  * FAILURE, so it THROWS an {@link import('./errors.js').AgentJobError} carrying the partial
- * (the Queue's retries + a Runner's fail-fast then engage); with `allowPartial` it RESOLVES
- * the partial as success instead. A natural finish ALWAYS resolves with its result.
+ * (the Queue's retries + a Runner's fail-fast then engage); the `partial` policy RESOLVES
+ * it as success instead. A natural finish ALWAYS resolves with its result.
  *
  * @param agent - The rehydrated {@link AgentInterface} to run to its {@link AgentResult}
- * @param allowPartial - When `true`, a partial result resolves as success; when `false`
- *   (the default policy), a partial result throws an {@link AgentJobError}
- * @returns The agent's {@link AgentResult} (a natural finish, or a partial when `allowPartial`)
- * @throws {AgentJobError} When the run ended `partial` and `allowPartial` is `false`
+ * @param partial - The partial policy. If `true`, a partial result resolves as success; if
+ *   `false` (the default policy), a partial result throws an {@link AgentJobError}
+ * @returns The agent's {@link AgentResult} (a natural finish, or a partial one under the
+ *   `partial` policy)
+ * @throws {AgentJobError} Thrown when the run ended partial and the `partial` policy is `false`
  *
  * @example
  * ```ts
  * const result = await settleAgentJob(registry.build(input, signal), false)
  * ```
  */
-export declare function settleAgentJob(agent: AgentInterface, allowPartial: boolean): Promise<AgentResult>;
+export declare function settleAgentJob(agent: AgentInterface, partial: boolean): Promise<AgentResult>;
 
 /**
- * A live event stream paired with the eventual settled result and a cancel — the
+ * Pairs a live event stream with the eventual settled result and a cancel — the
  * generic pull/streaming handle a long-running operation hands back.
  *
  * @remarks
@@ -3573,7 +3979,7 @@ export declare interface StreamInterface<T, R> {
     readonly events: AsyncIterable<T>;
     readonly result: Promise<R>;
     /**
-     * Cancel the in-flight operation — fires its bound signal.
+     * Cancels the in-flight operation — fires its bound signal.
      *
      * @param reason - An optional cancellation reason propagated to the signal
      */
@@ -3581,14 +3987,36 @@ export declare interface StreamInterface<T, R> {
 }
 
 /**
- * The closing tag that ends a {@link THINK_OPEN} reasoning span. A span the stream never closes
+ * Adds two {@link TokenUsage} values field by field — the running total an agent run keeps
+ * across its provider calls.
+ *
+ * @remarks
+ * Pure and total: the first call seeds the total (`running` `undefined` returns `next`
+ * unchanged), later calls accumulate. No sanitization happens here — charge a provider's
+ * reported usage through {@link sanitizeUsage} first.
+ *
+ * @param running - The total so far (`undefined` before the first usage-bearing call)
+ * @param next - This call's reported usage
+ * @returns The summed usage
+ *
+ * @example
+ * ```ts
+ * sumUsage(undefined, { prompt: 2, completion: 1, total: 3 }) // { prompt: 2, completion: 1, total: 3 }
+ * sumUsage({ prompt: 2, completion: 1, total: 3 }, { prompt: 1, completion: 1, total: 2 })
+ * // { prompt: 3, completion: 2, total: 5 }
+ * ```
+ */
+export declare function sumUsage(running: TokenUsage | undefined, next: TokenUsage): TokenUsage;
+
+/**
+ * Names the closing tag that ends a {@link THINK_OPEN} reasoning span. A span the stream never closes
  * (the model was cut off mid-reasoning) is treated as thinking to its end —
  * {@link import('./types.js').ThinkSplitterInterface.flush} settles it.
  */
 export declare const THINK_CLOSE = "</think>";
 
 /**
- * The opening tag a {@link import('./ThinkSplitter.js').ThinkSplitter} recognizes as the start of
+ * Names the opening tag a {@link import('./ThinkSplitter.js').ThinkSplitter} recognizes as the start of
  * an in-content reasoning span — the de-facto wire convention thinking models (qwen3, DeepSeek-R1
  * family) emit their chain-of-thought under when a daemon renders it inline instead of on a
  * separate wire field. Paired with {@link THINK_CLOSE}.
@@ -3596,10 +4024,10 @@ export declare const THINK_CLOSE = "</think>";
 export declare const THINK_OPEN = "<think>";
 
 /**
- * The stream-stateful `<think>` separator — feeds raw content deltas through a tiny
- * state machine that routes everything inside a `<think>…</think>` span to `thinking`
- * and returns everything outside it as clean content, so a provider yields ONLY the
- * answer and surfaces the reasoning as {@link import('./types.js').ProviderResult.thinking}.
+ * 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 ONLY the answer and surfaces the reasoning as
+ * {@link import('./types.js').ProviderResult.thinking}.
  *
  * @remarks
  * - **Cross-chunk tags.** A tag may arrive split across wire deltas (`'<thi'` then
@@ -3615,7 +4043,7 @@ export declare const THINK_OPEN = "<think>";
  *   prefix cannot be recalled, so `content` is the authoritative accumulation). The
  *   rule is ONE-SHOT: after any tag event a bare `</think>` is plain text.
  * - **Multiple spans** accumulate onto `thinking` in stream order. A nested-looking
- *   `<think>` inside an open span is just thinking text (no nesting is tracked — the
+ *   `<think>` inside an open span is thinking text (no nesting is tracked — the
  *   first `</think>` closes the span), matching how the models emit it.
  * - **Unclosed span at stream end.** `flush()` routes the open span's tail (including
  *   any held partial close tag) to `thinking` — a cut-off model was still reasoning.
@@ -3641,10 +4069,9 @@ export declare class ThinkSplitter implements ThinkSplitterInterface {
 }
 
 /**
- * The stream-stateful `<think>` separator — splits a thinking model's in-content
- * `<think>…</think>` reasoning spans away from the answer, delta by delta, so a
- * provider yields ONLY clean content and surfaces the reasoning as
- * {@link ProviderResult.thinking}.
+ * Splits a thinking model's in-content `<think>…</think>` reasoning spans away from the
+ * answer, delta by delta with per-stream state, so a provider yields ONLY clean content
+ * and surfaces the reasoning as {@link ProviderResult.thinking}.
  *
  * @remarks
  * - **Stateful across deltas.** A tag may arrive SPLIT across wire chunks (`'<thi'`
@@ -3652,9 +4079,9 @@ export declare class ThinkSplitter implements ThinkSplitterInterface {
  *   back until the next delta (or `flush`) disambiguates it, so a partial tag is
  *   never leaked as content and never mis-eaten as thinking.
  * - **`split(delta)`** feeds one raw content delta and returns the CLEAN content to
- *   surface for it (possibly `''` — e.g. mid-think). Text inside a
+ *   surface for it (possibly `''` — for example mid-think). Text inside a
  *   `<think>…</think>` span accumulates on `thinking`; multiple spans accumulate in
- *   order; a nested-looking `<think>` inside an open span is just thinking text (no
+ *   order; a nested-looking `<think>` inside an open span is thinking text (no
  *   nesting — the first `</think>` closes).
  * - **The IMPLICIT leading open (the qwen3-template shape).** Some chat templates
  *   PRE-SEED `<think>` into the prompt scaffold, so the wire stream begins
@@ -3675,27 +4102,27 @@ export declare class ThinkSplitter implements ThinkSplitterInterface {
  *   one per call ({@link import('./factories.js').createThinkSplitter}).
  */
 export declare interface ThinkSplitterInterface {
-    /** The AUTHORITATIVE clean content accumulated so far (corrected across an implicit-open reclassification). */
+    /** Holds the AUTHORITATIVE clean content accumulated so far (corrected across an implicit-open reclassification). */
     readonly content: string;
-    /** The reasoning text accumulated from every `<think>…</think>` span so far. */
+    /** Holds the reasoning text accumulated from every `<think>…</think>` span so far. */
     readonly thinking: string;
-    /** Feed one raw delta; returns the clean (non-think) content to surface for it. */
+    /** Feeds one raw delta; returns the clean (non-think) content to surface for it. */
     split(delta: string): string;
-    /** Settle the stream end — returns any held clean tail; an unclosed think span lands on `thinking`. */
+    /** Settles the stream end — returns any held clean tail; an unclosed think span lands on `thinking`. */
     flush(): string;
 }
 
 /**
- * The section header {@link import('./AgentContext.js').AgentContext}'s `build()` renders the
+ * Names the section header {@link import('./AgentContext.js').AgentContext}'s `build()` renders the
  * ACTIVE workspace's TEXT files under — the leading line of the dedicated workspace block in the
  * system message, the carrier-split counterpart to the documents / images section headers.
  *
  * @remarks
  * `build()` OWNS the workspace render (a `Workspace` / `WorkspaceManager` stays file-focused — no
- * `description` / `framing` getters), so this header lives here as the agents module's one
+ * `open` / `format` getters), so this header lives here as the agents 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 just after the documents section in the system block.
+ * the documents section uses — placed immediately after the documents section in the system block.
  */
 export declare const WORKSPACE_SECTION_HEADER = "## Workspace";