@orkestrel/agent 0.0.19 → 0.0.21

package/dist/src/core/index.js

@@ -1,7 +1,7 @@
 import { attempt, isArray, isBoolean, isFiniteNumber, isObject, isRecord, isString, parseJSONValue, rawShape, stringShape } from "@orkestrel/contract";
 import { createDatabase, createMemoryDriver } from "@orkestrel/database";
 import { createQueue } from "@orkestrel/queue";
-import { createDeferred, createRunner } from "@orkestrel/workflow";
+import { createRunner, errorToMessage } from "@orkestrel/workflow";
 import { createAbort } from "@orkestrel/abort";
 import { createTimeout } from "@orkestrel/timeout";
 import { Emitter } from "@orkestrel/emitter";
@@ -10,37 +10,37 @@ import { WorkspaceManager, isBinary, isText } from "@orkestrel/workspace";
 import { createTokenBudget } from "@orkestrel/budget";
 //#region src/core/constants.ts
 /**
-* The default cap on an {@link AgentInterface} turn's tool iterations — 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
-* `AgentOptions.limit`.
+* Caps an {@link AgentInterface} turn's tool iterations by default — `10` context → provider →
+* tools cycles before the loop stops, so a model that keeps requesting tools can never loop
+* forever. Overridable per agent through `AgentOptions.limit`.
 */
 var DEFAULT_AGENT_LIMIT = 10;
 /**
-* 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
-* an `allowed: false` `fallback` of their own (see `AuthorityOptions`).
+* Names the zone an {@link AuthorityInterface}'s default fallback {@link AuthorityDecision}
+* carries — `'default'`, 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 an
+* `allowed: false` `fallback` of their own (see `AuthorityOptions`).
 */
 var DEFAULT_AUTHORITY_ZONE = "default";
 /**
-* 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
-* the most recent `keep` live for the next turn. Overridable everywhere `keep` is accepted.
+* Sets the default number of recent live messages a {@link ConversationInterface}'s `compact()`
+* retains verbatim — `0`, so a manual `compact()` folds every current live message into one
+* summarized section and keeps no tail. A caller retains a recent tail by passing `keep` (on
+* {@link ConversationOptions}, {@link ConversationManagerOptions}, or per-fold 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.
 */
 var DEFAULT_CONVERSATION_KEEP = 0;
 /**
-* 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.
+* 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 — the lean
+* `'[Summary of earlier messages] '` marker, never a literal assistant turn to echo or treat as
+* the live answer.
 *
 * @remarks
-* Deliberately a FIXED, lean handful of tokens (a short bracketed marker) so the framing adds a
-* bounded `prefix × sections` overhead and NEVER an open-ended blow-up — the
+* Deliberately a fixed, lean handful of tokens (a short bracketed marker) so the framing adds a
+* bounded `prefix × sections` overhead and never an open-ended blow-up — the
 * {@link ConversationInterface} no-bloat test guard pins exactly that. Kept here (beside
 * {@link DEFAULT_CONVERSATION_KEEP}) as the conversation layer's one tunable framing constant, so
 * the wording has a single source of truth as it is optimized against real small-model behavior
@@ -49,44 +49,47 @@ var DEFAULT_CONVERSATION_KEEP = 0;
 */
 var CONVERSATION_RECAP_PREFIX = "[Summary of earlier messages] ";
 /**
-* 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}.
+* Names the opening tag a {@link import('./ThinkSplitter.js').ThinkSplitter} recognizes as the start of
+* an in-content reasoning span — `'<think>'`, 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}.
 */
 var THINK_OPEN = "<think>";
 /**
-* 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.
+* Names the closing tag that ends a {@link THINK_OPEN} reasoning span — `'</think>'`. A span the
+* stream never closes (the model was cut off mid-reasoning) is treated as thinking to its end,
+* and {@link import('./types.js').ThinkSplitterInterface.flush} settles it.
 */
 var THINK_CLOSE = "</think>";
 /**
-* 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.
+* Names the section header {@link import('./AgentContext.js').AgentContext}'s `build()` renders the
+* active workspace's text files under — `'## Workspace'`, the leading line of the dedicated
+* workspace block in the system message and the carrier-split counterpart to the documents and
+* images section headers.
 *
 * @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
+* `build()` owns the workspace render (a `Workspace` / `WorkspaceManager` stays file-focused — no
+* `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.
+* beneath it as a fenced `` File: <path>\n```<language>\n<text>\n``` `` block — the same framing
+* the documents section uses — placed immediately after the documents section in the system block.
 */
 var WORKSPACE_SECTION_HEADER = "## Workspace";
 /**
-* 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.
+* Estimates the per-message role and framing overhead {@link import('./helpers.js').estimateMessages}
+* adds on top of a message's content estimate — `4` tokens for the fixed wire framing every
+* conversation turn carries (its role tag, its delimiters) that
+* {@link import('./helpers.js').estimateTokens}'s content-only heuristic does not otherwise
+* capture.
 */
 var MESSAGE_TOKEN_OVERHEAD = 4;
 /**
-* The coarse, deliberately-approximate per-image token cost {@link import('./helpers.js').estimateMessages}
-* charges for each attached image.
+* Names the coarse, deliberately approximate per-image token cost
+* {@link import('./helpers.js').estimateMessages} charges for each attached image — `512`, because
+* a base64 payload's length is no reliable token proxy.
 *
 * @remarks
-* A base64 image payload's LENGTH is NOT a reliable token proxy (a vision model's actual image
+* A base64 image payload's length is not a reliable token proxy (a vision model's actual image
 * token cost depends on resolution / tiling, not byte size), so this is a fixed, coarse
 * per-image estimate rather than a derivation from `image.length` — a planning heuristic, not an
 * exact count.
@@ -95,16 +98,19 @@ var IMAGE_TOKEN_ESTIMATE = 512;
 //#endregion
 //#region src/core/errors.ts
 /**
-* 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 and the machine-readable `code` `'ABORT'`.
 *
 * @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.
 */
 var ProviderAbortError = class extends Error {
+	/** Names the machine-readable condition — `'ABORT'`: a stream cancelled mid-flight. */
+	code = "ABORT";
 	partial;
 	constructor(partial) {
 		super("provider stream aborted");
@@ -113,10 +119,11 @@ var ProviderAbortError = class extends Error {
 	}
 };
 /**
-* Narrow an unknown caught value to a {@link ProviderAbortError}.
+* Narrows an unknown caught value to a {@link ProviderAbortError} through `instanceof`, so a
+* `catch` can recover its `partial` result.
 *
 * @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
@@ -131,22 +138,26 @@ function isProviderAbortError(value) {
 	return value instanceof ProviderAbortError;
 }
 /**
-* 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
-* {@link AgentResult} so the failure stays inspectable.
+* 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, and the machine-readable `code` `'PARTIAL'`.
 *
 * @remarks
 * A partial result means the agent was cancelled (an external `signal` abort, a queue /
 * 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
+* 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.
 */
 var AgentJobError = class 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. */
+	code = "PARTIAL";
+	/** Holds the partial {@link AgentResult} the cancelled job produced. */
 	partial;
 	constructor(message, partial) {
 		super(message);
@@ -155,10 +166,11 @@ var AgentJobError = class extends Error {
 	}
 };
 /**
-* Narrow an unknown caught value to an {@link AgentJobError}.
+* Narrows an unknown caught value to an {@link AgentJobError} through `instanceof`, so a
+* `catch` can recover its `partial` result.
 *
 * @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
@@ -173,22 +185,23 @@ function isAgentJobError(value) {
 	return value instanceof AgentJobError;
 }
 /**
-* 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 `sections` cap below `1` — thrown by a {@link ConversationInterface}'s `compact()`
+* or its construction, carrying the machine-readable `code`
+* `'SUMMARIZER' | 'SECTIONS'`.
 *
 * @remarks
-* Compaction REQUIRES a summarizer (it digests the folded slice into a section summary and
+* 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`.
 */
 var ConversationError = class 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. */
 	code;
 	constructor(code, message) {
 		super(message);
@@ -197,10 +210,11 @@ var ConversationError = class extends Error {
 	}
 };
 /**
-* Narrow an unknown caught value to a {@link ConversationError}.
+* Narrows an unknown caught value to a {@link ConversationError} through `instanceof`, so a
+* `catch` can branch on its `code`.
 *
 * @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
@@ -215,19 +229,25 @@ function isConversationError(value) {
 	return value instanceof ConversationError;
 }
 /**
-* 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 so by `generate()`, which calls it) and by an
+* {@link AgentRegistryInterface}'s accessors, carrying the machine-readable `code`
+* `'CONCURRENCY' | 'REGISTRY'`. Synchronous means a fire-and-forget
+* `agent.generate().catch(…)` never catches it: `await` the call inside `try`/`catch`, or wrap
+* the call expression itself.
 *
 * @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`.
 */
 var AgentError = class extends Error {
-	/** The machine-readable condition — `'CONCURRENCY'`: a concurrent run on a shared accounting agent. */
+	/** Names the machine-readable condition — `'CONCURRENCY'`: a concurrent run on a shared accounting agent; `'REGISTRY'`: a rehydration name absent from its registry pool. */
 	code;
 	constructor(code, message) {
 		super(message);
@@ -236,10 +256,11 @@ var AgentError = class extends Error {
 	}
 };
 /**
-* Narrow an unknown caught value to an {@link AgentError}.
+* Narrows an unknown caught value to an {@link AgentError} through `instanceof`, so a `catch`
+* can branch on its `code`.
 *
 * @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
@@ -254,336 +275,13 @@ function isAgentError(value) {
 	return value instanceof AgentError;
 }
 //#endregion
-//#region src/core/conversations/Conversation.ts
-/**
-* 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
-* `summary`, with on-demand `rehydrate` and substring `search`, driven by a provider-agnostic
-* {@link ConversationSummarizer} 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
-*   (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
-*   summarized slice that RETAINS its originals. `#summary` is the rollup (a
-*   summary-of-summaries over all sections), regenerated on each compaction (`undefined`
-*   until the first).
-* - **`view()`.** Each section folds to ONE synthetic summary message (role `'assistant'` — a
-*   prior-context recap — keyed by the section's stable `id`), then the live messages
-*   verbatim. The rollup `summary` is NOT injected (it is separately pull-able); `view()`
-*   carries the per-section summaries, which ARE the compaction benefit.
-* - **`compact()`.** Folds the oldest `count - keep` live messages into a new section
-*   (its `summary` from `#summarize`), removes them from the live tail by id, regenerates the
-*   rollup (a SECOND `#summarize` over all section summaries), and emits `summary` then
-*   `compact`. Returns the section, or `undefined` when nothing folds (`count <= keep`).
-*   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
-*   `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.
-*
-* @example
-* ```ts
-* const conversation = new Conversation({ summarize: async (m) => `recap of ${m.length}` })
-* conversation.add([
-* 	{ role: 'user', content: 'Hello' },
-* 	{ role: 'assistant', content: 'Hi there' },
-* ])
-* const section = await conversation.compact() // folds both into one summarized section
-* conversation.view() // [{ role: 'assistant', content: 'recap of 2' }] — the live tail is empty
-* conversation.summary // 'recap of 1' — the rollup over the one section
-* ```
-*/
-var Conversation = class {
-	#id;
-	#emitter;
-	#summarize;
-	#keep;
-	#cap;
-	#sections = [];
-	#summary;
-	#messages = /* @__PURE__ */ new Map();
-	constructor(options, seed) {
-		this.#id = seed?.id ?? options?.id ?? crypto.randomUUID();
-		this.#emitter = new Emitter({
-			...options?.on === void 0 ? {} : { on: options.on },
-			...options?.error === void 0 ? {} : { error: options.error }
-		});
-		this.#summarize = options?.summarize;
-		this.#keep = options?.keep ?? 0;
-		if (options?.sections !== void 0 && options.sections < 1) throw new ConversationError("SECTIONS", "a sections cap must be >= 1");
-		this.#cap = options?.sections;
-		if (seed) {
-			this.#summary = seed.summary;
-			for (const section of seed.sections) this.#sections.push(section);
-			for (const message of seed.messages) this.#messages.set(message.id, message);
-		}
-	}
-	get id() {
-		return this.#id;
-	}
-	get emitter() {
-		return this.#emitter;
-	}
-	get summary() {
-		return this.#summary;
-	}
-	get sections() {
-		return [...this.#sections];
-	}
-	get summarizable() {
-		return this.#summarize !== void 0;
-	}
-	get count() {
-		return this.#messages.size;
-	}
-	add(input) {
-		if (isArray(input)) return input.map((one) => this.#create(one));
-		return this.#create(input);
-	}
-	message(id) {
-		return this.#messages.get(id);
-	}
-	messages() {
-		return [...this.#messages.values()];
-	}
-	remove(ids) {
-		if (isArray(ids)) {
-			let removed = false;
-			for (const id of ids) if (this.#messages.delete(id)) removed = true;
-			return removed;
-		}
-		return this.#messages.delete(ids);
-	}
-	clear() {
-		this.#messages.clear();
-	}
-	view() {
-		return [...this.#sections.map((section) => this.#recapMessage(section)), ...this.#messages.values()];
-	}
-	async compact(options) {
-		const summarize = this.#summarize;
-		if (summarize === void 0) throw new ConversationError("SUMMARIZER", "cannot compact a conversation without a summarizer");
-		const cap = options?.sections ?? this.#cap;
-		if (cap !== void 0 && cap < 1) throw new ConversationError("SECTIONS", "a sections cap must be >= 1");
-		const keep = options?.keep ?? this.#keep;
-		const live = [...this.#messages.values()];
-		const fold = keep <= 0 ? live.length : live.length - keep;
-		if (fold <= 0) return void 0;
-		const slice = live.slice(0, fold);
-		const summary = await summarize(slice);
-		const section = {
-			id: crypto.randomUUID(),
-			summary,
-			messages: slice
-		};
-		for (const message of slice) this.#messages.delete(message.id);
-		this.#sections.push(section);
-		if (cap !== void 0 && this.#sections.length > cap) {
-			const overflow = this.#sections.length - cap + 1;
-			const folded = this.#sections.slice(0, overflow);
-			try {
-				const merged = {
-					id: crypto.randomUUID(),
-					summary: await summarize(folded.map((one) => this.#summaryMessage(one))),
-					messages: folded.flatMap((one) => one.messages)
-				};
-				this.#sections.splice(0, overflow, merged);
-				this.#emitter.emit("collapse", merged);
-			} catch (error) {
-				this.#summary = await summarize(this.#sections.map((one) => this.#summaryMessage(one)));
-				this.#emitter.emit("summary", this.#summary);
-				throw error;
-			}
-		}
-		this.#summary = await summarize(this.#sections.map((one) => this.#summaryMessage(one)));
-		this.#emitter.emit("summary", this.#summary);
-		this.#emitter.emit("compact", section);
-		return section;
-	}
-	rehydrate(id) {
-		const section = this.#sections.find((one) => one.id === id);
-		this.#emitter.emit("rehydrate", id);
-		return section === void 0 ? [] : section.messages;
-	}
-	search(query) {
-		const needle = query.toLowerCase();
-		return [...this.#sections.flatMap((section) => section.messages), ...this.#messages.values()].filter((message) => message.content.toLowerCase().includes(needle));
-	}
-	reference(options) {
-		const lines = [`[Reference — conversation "${options?.label ?? this.#id}" — NOT part of this conversation]`];
-		if (options?.summary !== false && this.#summary !== void 0) lines.push(`Summary: ${this.#summary}`);
-		const messages = options?.messages ?? [];
-		if (messages.length > 0) {
-			lines.push("Relevant messages:");
-			for (const message of messages) lines.push(`- ${message.role}: ${message.content}`);
-		}
-		return lines.join("\n");
-	}
-	snapshot() {
-		return {
-			id: this.#id,
-			...this.#summary === void 0 ? {} : { summary: this.#summary },
-			sections: this.sections,
-			messages: this.messages()
-		};
-	}
-	#summaryMessage(section) {
-		return {
-			id: section.id,
-			role: "assistant",
-			content: section.summary
-		};
-	}
-	#recapMessage(section) {
-		return {
-			id: section.id,
-			role: "assistant",
-			content: `${CONVERSATION_RECAP_PREFIX}${section.summary}`
-		};
-	}
-	#create(input) {
-		const message = {
-			id: crypto.randomUUID(),
-			role: input.role,
-			content: input.content,
-			...input.calls === void 0 ? {} : { calls: input.calls },
-			...input.images === void 0 ? {} : { images: input.images }
-		};
-		this.#messages.set(message.id, message);
-		return message;
-	}
-};
-//#endregion
-//#region src/core/conversations/ConversationManager.ts
-/**
-* 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
-* {@link import('../AgentContext.js').AgentContext} renders. Event-free (a registry, like
-* {@link import('@orkestrel/workspace').WorkspaceManager}); the observability lives
-* on each {@link Conversation}.
-*
-* @remarks
-* - **Registry.** Conversations live in an insertion-ordered `Map` keyed by `id`. `add(input?)`
-*   mints a {@link Conversation} (its `id` from `input` or `crypto.randomUUID()`), flowing the
-*   manager's default `#summarize` / `#keep` in unless the `input` OVERRIDES them, and stores
-*   it (an already-present `id` OVERWRITES — last write wins). `count` is the map size,
-*   `conversation(id)` looks one up, `conversations()` lists them in insertion order.
-* - **Active pointer.** `active` is the active conversation (the agent's message source the
-*   context renders), `undefined` until the FIRST `add` (which auto-activates it — a registry
-*   with conversations always has one active). A subsequent `add` leaves `active` unchanged.
-*   `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
-*   and sets `active` to `undefined`.
-* - **Event-free.** A purely registry store — no Emitter, no events (each conversation owns
-*   its own observable `emitter`).
-*
-* @example
-* ```ts
-* const manager = new ConversationManager({ summarize: async (m) => `recap of ${m.length}` })
-* const conversation = manager.add() // auto-activates — active === conversation
-* manager.add({ id: 'scratch' }) // leaves active unchanged
-* manager.switch('scratch') // re-points active to the 'scratch' conversation
-* manager.count // 2
-* ```
-*/
-var ConversationManager = class {
-	#conversations = /* @__PURE__ */ new Map();
-	#active;
-	#summarize;
-	#keep;
-	#sections;
-	#store;
-	constructor(options) {
-		this.#summarize = options?.summarize;
-		this.#keep = options?.keep ?? 0;
-		this.#sections = options?.sections;
-		this.#store = options?.store;
-	}
-	get count() {
-		return this.#conversations.size;
-	}
-	get active() {
-		return this.#active === void 0 ? void 0 : this.#conversations.get(this.#active);
-	}
-	conversation(id) {
-		return this.#conversations.get(id);
-	}
-	conversations() {
-		return [...this.#conversations.values()];
-	}
-	add(input) {
-		const sections = input?.sections ?? this.#sections;
-		const summarize = input?.summarize ?? this.#summarize;
-		const conversation = new Conversation({
-			...input?.id === void 0 ? {} : { id: input.id },
-			...input?.on === void 0 ? {} : { on: input.on },
-			...summarize === void 0 ? {} : { summarize },
-			keep: input?.keep ?? this.#keep,
-			...sections === void 0 ? {} : { sections }
-		}, input?.snapshot);
-		this.#conversations.set(conversation.id, conversation);
-		if (this.#active === void 0) this.#active = conversation.id;
-		return conversation;
-	}
-	switch(id) {
-		const conversation = this.#conversations.get(id);
-		if (conversation === void 0) return void 0;
-		this.#active = id;
-		return conversation;
-	}
-	async open(id) {
-		const existing = this.#conversations.get(id);
-		if (existing !== void 0) {
-			this.#active = id;
-			return existing;
-		}
-		if (this.#store === void 0) return void 0;
-		const snapshot = await this.#store.get(id);
-		if (snapshot === void 0) return void 0;
-		const conversation = this.add({ snapshot });
-		this.#active = conversation.id;
-		return conversation;
-	}
-	async save(id) {
-		const conversation = this.#conversations.get(id);
-		if (this.#store === void 0 || conversation === void 0) return false;
-		await this.#store.set(conversation.snapshot());
-		return true;
-	}
-	remove(ids) {
-		if (isArray(ids)) {
-			let removed = false;
-			for (const id of ids) if (this.#drop(id)) removed = true;
-			return removed;
-		}
-		return this.#drop(ids);
-	}
-	clear() {
-		this.#conversations.clear();
-		this.#active = void 0;
-	}
-	#drop(id) {
-		const removed = this.#conversations.delete(id);
-		if (removed && this.#active === id) this.#active = void 0;
-		return removed;
-	}
-};
-//#endregion
 //#region src/core/helpers.ts
 /**
-* Project an unknown value onto the canonical JSON representation of an
-* {@link AgentResult}.
+* Projects an unknown value onto a fresh, exact `JSONValue` representation of an
+* {@link AgentResult} — capturing each structural field once through a total boundary,
+* accepting conforming accessors and inherited properties, preserving finite negative and
+* fractional usage counts, dropping extras, and resolving `undefined` for a malformed field, a
+* non-finite usage number, a throwing getter, or a hostile or revoked proxy.
 *
 * @remarks
 * This is a total hostile-boundary projection. Each structural field is captured once
@@ -637,15 +335,16 @@ function agentResultToJSON(value) {
 	return captured.success ? parseJSONValue(captured.value) : void 0;
 }
 /**
-* Filter 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.
+* Filters a list of items by a {@link import('./types.js').ScopeInterface} allow-list of keys —
+* `undefined` passes everything, `[]` passes nothing, and a non-empty list passes the listed keys
+* alone, order preserved. The pure, total set-membership primitive the context's build step and
+* the agent loop's tool-advertise step apply a scope through.
 *
 * @remarks
 * Three-way by the allow-list's shape, so a `Scope` category cleanly expresses "all /
 * none / only these":
-* - `undefined` ⇒ NO constraint — every item passes (returned unchanged).
-* - `[]` (empty) ⇒ NONE pass (no key is in an empty set).
+* - `undefined` ⇒ no constraint — every item passes (returned unchanged).
+* - `[]` (empty) ⇒ none pass (no key is in an empty set).
 * - a non-empty list ⇒ only items whose `key(item)` is in the list pass.
 *
 * Order-preserving (it filters `items` in place order, never reorders) and total — never
@@ -654,7 +353,7 @@ function agentResultToJSON(value) {
 * @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
@@ -672,15 +371,15 @@ function filterAllowList(allow, items, key) {
 	return items.filter((item) => set.has(key(item)));
 }
 /**
-* Estimate 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).
+* Estimates the context-token footprint of a string — the deterministic `ceil(length / 4)`
+* character heuristic {@link estimateMessages} sums over a conversation's messages (the default
+* context-budget estimator).
 *
 * @remarks
 * Approximates `ceil(length / 4)` (≈ four characters per token — the rough average for
 * English text), so the same input always yields the same estimate (no model round-trip).
 * Empty text is `0`. This is a planning heuristic for reasoning about how much a turn's
-* messages cost the next request, NOT an exact tokenizer count — it never calls a provider,
+* messages cost the next request, not an exact tokenizer count — it never calls a provider,
 * so the agent layer stays provider-agnostic and synchronous where it can be.
 *
 * @param text - The text to estimate (a section summary, a message's content)
@@ -697,19 +396,22 @@ function estimateTokens(text) {
 	return Math.ceil(text.length / 4);
 }
 /**
-* Estimate the context-token footprint of a batch of messages — the default `consume`
-* estimator for an agent's context `BudgetInterface` (a budgets surface's tracking contract)
-* (the {@link import('./types.js').AgentOptions} `window`).
+* Estimates the context-token footprint of a batch of messages — each message's content plus
+* {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD}, a tool-call JSON estimate, and
+* {@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} for each attached image. The default
+* `consumer` estimator for an agent's context budget (the
+* {@link import('./types.js').AgentOptions} `window`), total and never throwing, and a
+* deliberate provider-agnostic approximation rather than an exact tokenizer count.
 *
 * @remarks
 * Sums, per message, {@link estimateTokens} over its `content` (the `ceil(length / 4)` char
-* heuristic) PLUS {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} (a fixed per-message
-* role/framing overhead) PLUS, when present, {@link estimateTokens} over its JSON-stringified
-* `calls` PLUS `images.length * `{@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} (a coarse,
-* deliberately-approximate per-image cost — a base64 length is NOT a token proxy). Deterministic
+* heuristic) plus {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} (a fixed per-message
+* role/framing overhead) plus, when present, {@link estimateTokens} over its JSON-stringified
+* `calls` plus `images.length * `{@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} (a coarse,
+* deliberately-approximate per-image cost — a base64 length is not a token proxy). Deterministic
 * and provider-free — the same messages always yield the same estimate, with an empty batch `0`.
 * It is the fully-swappable default an agent's auto-compaction context budget charges each
-* turn's new messages through; a caller wanting a sharper count supplies its own `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)
@@ -738,238 +440,836 @@ function estimateMessages(messages) {
 	}, 0);
 }
 /**
-* Run one rehydrated agent and apply 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.
+* Runs one rehydrated agent and applies the partial-as-configurable-failure policy — a partial
+* run throws an {@link import('./errors.js').AgentJobError} unless the `partial` policy allows
+* it, and a natural finish resolves. The shared job-handler step `createAgentQueue` and
+* `createAgentRunner` both 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.
+* 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); 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)
 * ```
 */
-async function settleAgentJob(agent, allowPartial) {
+async function settleAgentJob(agent, partial) {
 	const result = await agent.generate();
-	if (result.partial && !allowPartial) throw new AgentJobError("agent job ended partial", result);
+	if (result.partial && !partial) throw new AgentJobError("agent job ended partial", result);
 	return result;
 }
 /**
-* 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
 */
-function handleAgentQueueJob(registry, allowPartial, input, execution) {
-	return settleAgentJob(registry.build(input, execution.signal), allowPartial);
+function handleAgentQueueJob(registry, partial, input, context) {
+	return settleAgentJob(registry.build(input, context.signal), partial);
+}
+/**
+* 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.
+*
+* @remarks
+* Children are fired and tracked through the runner controller without awaiting them
+* inline, preserving bounded-runner progress.
+*
+* @param registry - The registry that rehydrates serializable jobs
+* @param partial - The partial policy. If `true`, a partial result resolves; if `false`, it throws
+* @param controller - The runner controller for this parent job
+* @returns The settled parent agent result
+*/
+function handleAgentRunnerJob(registry, partial, controller) {
+	const children = controller.input.children;
+	if (children !== void 0) for (const child of children) controller.spawn(child);
+	return settleAgentJob(registry.build(controller.input, controller.signal), partial);
+}
+/**
+* Renders a path-addressed text body as a fenced reference block — a `File: <path>` label line
+* over a language-tagged fence, the framing an
+* {@link import('./AgentContext.js').AgentContext}'s active-workspace text-file render emits.
+*
+* @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 (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```'
+* ```
+*/
+function renderFencedFile(path, language, content) {
+	return `File: ${path}\n\`\`\`${language}\n${content}\n\`\`\``;
+}
+/**
+* Sanitizes one reported token count into a safe non-negative integer — a non-finite or
+* non-positive value becomes `0`, and a positive fractional value floors down.
+*
+* @param value - The token count to sanitize
+* @returns The floored count, or `0` when the value is non-finite or non-positive
+*/
+function sanitizeToken(value) {
+	return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+/**
+* 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.
+*
+* @remarks
+* Per field (`prompt` / `completion` / `total`): a non-finite value (`NaN`, `+Infinity`,
+* `-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 (for example a provider's abort-partial usage)
+* @returns A new {@link TokenUsage} with every field a safe non-negative integer
+*
+* @example
+* ```ts
+* sanitizeUsage({ prompt: -5, completion: NaN, total: 12.7 }) // { prompt: 0, completion: 0, total: 12 }
+* ```
+*/
+function sanitizeUsage(usage) {
+	return {
+		prompt: sanitizeToken(usage.prompt),
+		completion: sanitizeToken(usage.completion),
+		total: sanitizeToken(usage.total)
+	};
+}
+/**
+* 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'
+* ```
+*/
+function joinThinking(running, next) {
+	return running === void 0 ? next : `${running}\n\n${next}`;
+}
+/**
+* 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 }
+* ```
+*/
+function sumUsage(running, next) {
+	if (running === void 0) return next;
+	return {
+		prompt: running.prompt + next.prompt,
+		completion: running.completion + next.completion,
+		total: running.total + next.total
+	};
+}
+/**
+* Assembles the settled {@link AgentResult} from a run's {@link RunOutcome} — `thinking` and
+* `usage` are carried only when the run surfaced them, and the loop-internal `exhausted` flag is
+* left out.
+*
+* @remarks
+* Pure and total. An absent optional is omitted rather than stored as `undefined` (the
+* present-when-given convention the message store follows), so a settled result JSON
+* round-trips without an explicit `undefined` field. `exhausted` is loop bookkeeping and does
+* not reach the public result — the `exhaust` event carries it instead.
+*
+* @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 }
+* ```
+*/
+function assembleResult(outcome) {
+	const result = {
+		content: outcome.content,
+		partial: outcome.partial
+	};
+	if (outcome.thinking !== void 0) result.thinking = outcome.thinking;
+	if (outcome.usage !== void 0) result.usage = outcome.usage;
+	return result;
+}
+/**
+* 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' }
+* ```
+*/
+function denyCall(call, reason) {
+	return {
+		success: false,
+		id: call.id,
+		name: call.name,
+		error: reason !== void 0 ? `denied: ${reason}` : "denied by authority"
+	};
+}
+/**
+* Renders one context section — the resolved `open`, each item's rendering, and the resolved
+* `close` when one exists, blank-line joined; `undefined` when the section has no items.
+*
+* @remarks
+* Pure and total. A section with no items renders nothing (`undefined`), so an empty or fully
+* scoped-out manager stays silent — its `open` / `close` 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)
+* ```
+*/
+function renderSection(open, items, render, close) {
+	if (items.length === 0) return void 0;
+	const lines = [open, ...items.map(render)];
+	if (close !== void 0) lines.push(close);
+	return lines.join("\n\n");
+}
+/**
+* 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)
+* ```
+*/
+function resolveOpen(manager, provider) {
+	return manager.format?.open ?? provider?.open ?? manager.open;
+}
+/**
+* Resolves one section's close text through the format cascade — manager-options override >
+* provider default; `undefined` when neither sets one, because there is no built-in close.
+*
+* @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>'
+* ```
+*/
+function resolveClose(manager, provider) {
+	return manager.format?.close ?? provider?.close;
 }
 /**
-* Handle 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.
+* Resolves one item's rendering through the format cascade — item override > manager-options
+* override > provider default > built-in rendering.
 *
 * @remarks
-* Children are fired and tracked through the runner controller without awaiting them
-* inline, preserving bounded-runner progress.
+* 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.
 *
-* @param registry - The registry that rehydrates serializable jobs
-* @param allowPartial - Whether a partial result resolves instead of throwing
-* @param controller - The runner controller for this parent job
-* @returns The settled parent agent result
+* @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>'
+* ```
 */
-function handleAgentRunnerJob(registry, allowPartial, controller) {
-	const children = controller.input.children;
-	if (children !== void 0) for (const child of children) controller.spawn(child);
-	return settleAgentJob(registry.build(controller.input, controller.signal), allowPartial);
+function resolveItem(manager, provider, item) {
+	return item.override ?? manager.format?.render?.(item) ?? provider?.render?.(item) ?? manager.render(item);
 }
 /**
-* 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
-* {@link import('@orkestrel/workspace').isFile}.
+* Copies a message with image data merged onto its `images` — the message's own images first,
+* then the attached data, carrying `calls` only when present and never mutating the original.
 *
 * @remarks
-* A total guard (it NEVER throws — adversarial input returns `false`). It checks the message's
-* 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
-* 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
-* a storage boundary WITHOUT a cast.
+* 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 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}
+* @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
-* isMessage({ id: '1', role: 'user', content: 'hi' }) // true
-* isMessage({ id: '1', role: 'assistant', content: '', calls: [] }) // true
-* isMessage({ id: '1', role: 'user' }) // false (missing content)
-* isMessage({ id: '1', role: 'assistant', content: '', calls: [null] }) // false (malformed call)
+* attachImages({ id: '1', role: 'user', content: 'Describe' }, ['<payload>'])
+* // { id: '1', role: 'user', content: 'Describe', images: ['<payload>'] }
 * ```
 */
-function isMessage(value) {
-	if (!isRecord(value)) return false;
-	if (!isString(value.id) || !isString(value.role) || !isString(value.content)) return false;
-	if (value.calls !== void 0 && !(isArray(value.calls) && value.calls.every(isToolCall))) return false;
-	return value.images === void 0 || isArray(value.images);
+function attachImages(message, data) {
+	const images = [...message.images ?? [], ...data];
+	return message.calls === void 0 ? {
+		id: message.id,
+		role: message.role,
+		content: message.content,
+		images
+	} : {
+		id: message.id,
+		role: message.role,
+		content: message.content,
+		calls: message.calls,
+		images
+	};
 }
 /**
-* 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`).
+* Attaches image data to a conversation's last user message — the turn a vision provider reads
+* images off — as a new array with that one message replaced by its carrying copy, and unchanged
+* when there is no data or no user turn.
 *
 * @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.
+* 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 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}
+* @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
-* isSection({ id: 's', summary: 'recap', messages: [{ id: '1', role: 'user', content: 'hi' }] }) // true
-* isSection({ id: 's', summary: 'recap', messages: 'nope' }) // false
-* isSection({ id: 's', messages: [] }) // false (missing summary)
+* attachUserImages([{ id: '1', role: 'user', content: 'Describe' }], ['<payload>'])
+* // [{ id: '1', role: 'user', content: 'Describe', images: ['<payload>'] }]
 * ```
 */
-function isSection(value) {
-	if (!isRecord(value)) return false;
-	if (!isString(value.id) || !isString(value.summary)) return false;
-	return isArray(value.messages) && value.messages.every(isMessage);
+function attachUserImages(conversation, data) {
+	if (data.length === 0) return conversation;
+	let target = -1;
+	for (let index = conversation.length - 1; index >= 0; index -= 1) if (conversation[index]?.role === "user") {
+		target = index;
+		break;
+	}
+	if (target === -1) return conversation;
+	return conversation.map((message, index) => index === target ? attachImages(message, data) : message);
 }
 /**
-* Narrow an `unknown` to a {@link ConversationSnapshot} — the AGENTS §14 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
-* {@link import('@orkestrel/workspace').isWorkspaceSnapshot}.
+* 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
-* 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 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
-* element) resolves `false`, so a
-* {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore}
-* read yields `undefined` rather than a broken conversation.
+* 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 value - The value to test (an opaque storage read)
-* @returns `true` when `value` has the structural shape of a {@link ConversationSnapshot}
+* @param files - The (already scope-filtered) workspace files
+* @returns The `base64` payload of each image file, in file order
 *
 * @example
 * ```ts
-* isConversationSnapshot({ id: 'c1', sections: [], messages: [] }) // true
-* isConversationSnapshot({ id: 'c1', summary: 'recap', sections: [], messages: [] }) // true
-* isConversationSnapshot({ id: 'c1', sections: 'nope', messages: [] }) // false
-* isConversationSnapshot({ sections: [], messages: [] }) // false (missing id)
+* collectImageData([createFile({ path: 'a.png', content: { base64: '<payload>', mime: 'image/png' } })])
+* // ['<payload>']
 * ```
 */
-function isConversationSnapshot(value) {
-	if (!isRecord(value)) return false;
-	if (!isString(value.id)) return false;
-	if (value.summary !== void 0 && !isString(value.summary)) return false;
-	if (!isArray(value.sections) || !value.sections.every(isSection)) return false;
-	return isArray(value.messages) && value.messages.every(isMessage);
+function collectImageData(files) {
+	const data = [];
+	for (const file of files) if (isBinary(file.content) && file.content.mime.startsWith("image/")) data.push(file.content.base64);
+	return data;
 }
 /**
-* 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).
+* Builds the raw synthetic summary message for one compacted section — role `'assistant'`, the
+* section's stable `id`, and its `summary` verbatim as content.
 *
 * @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).
+* 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 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
+* @param section - The compacted section to render
+* @returns The synthetic summary message
 *
 * @example
 * ```ts
-* import { fencedFile } from '@src/core'
+* buildSummaryMessage({ id: 's1', summary: 'recap', messages: [] })
+* // { id: 's1', role: 'assistant', content: 'recap' }
+* ```
+*/
+function buildSummaryMessage(section) {
+	return {
+		id: section.id,
+		role: "assistant",
+		content: section.summary
+	};
+}
+/**
+* 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}.
 *
-* fencedFile('src/main.ts', 'typescript', 'const x = 1')
-* // 'File: src/main.ts\n```typescript\nconst x = 1\n```'
+* @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` }
 * ```
 */
-function fencedFile(path, language, content) {
-	return `File: ${path}\n\`\`\`${language}\n${content}\n\`\`\``;
+function buildRecapMessage(section) {
+	return {
+		id: section.id,
+		role: "assistant",
+		content: `${CONVERSATION_RECAP_PREFIX}${section.summary}`
+	};
 }
 /**
-* Sanitize one reported token count into a safe non-negative integer.
+* Intersects two scope category lists under the "`undefined` is the universal set" rule — a
+* fresh copy that can only tighten, and the primitive a scope narrows through.
 *
-* @param value - The token count to sanitize
-* @returns The floored count, or `0` when the value is non-finite or non-positive
+* @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
+* ```
 */
-function sanitizeToken(value) {
-	return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+function intersectKeys(parent, child) {
+	if (parent === void 0) return child === void 0 ? void 0 : [...child];
+	if (child === void 0) return [...parent];
+	const allowed = new Set(parent);
+	return child.filter((key) => allowed.has(key));
 }
+//#endregion
+//#region src/core/conversations/Conversation.ts
 /**
-* Sanitize 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.
+* Represents a conversation — a live uncompacted tail of messages it owns directly above a flat
+* message store, plus compacted, summarized {@link Section}s, a regenerated rollup `summary`, and
+* a `summarizable` flag, with on-demand `rehydrate` and substring `search`, driven by a
+* provider-agnostic {@link ConversationSummaryHandler} seam so `core` never imports a provider.
+* Observable through its own `emitter`.
 *
 * @remarks
-* Per field (`prompt` / `completion` / `total`): a non-finite value (`NaN`, `+Infinity`,
-* `-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.
+* - **Live tail + sections.** The conversation owns its live tail directly — `#messages` is an
+*   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
+*   summarized slice that retains its originals. `#summary` is the rollup (a
+*   summary-of-summaries over all sections), regenerated on each compaction (`undefined`
+*   until the first).
+* - **`view()`.** Each section folds to one synthetic summary message (role `'assistant'` — a
+*   prior-context recap — keyed by the section's stable `id`), then the live messages
+*   verbatim. The rollup `summary` is not injected (it is separately pull-able); `view()`
+*   carries the per-section summaries, which are the compaction benefit.
+* - **`compact()`.** Folds the oldest `count - keep` live messages into a new section
+*   (its `summary` from `#summarize`), removes them from the live tail by id, regenerates the
+*   rollup (a second `#summarize` over all section summaries), and emits `summary` then
+*   `compact`. Returns the section, or `undefined` when nothing folds (`count <= keep`).
+*   Throws a {@link ConversationError} when no `#summarize` was supplied. A compaction calls
+*   the summarizer for the section digest and again for the rollup.
+* - **`rehydrate(id)` / `search(query)`.** `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; `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.
+*
+* @example
+* ```ts
+* const conversation = new Conversation({ summarize: async (m) => `recap of ${m.length}` })
+* conversation.add([
+* 	{ role: 'user', content: 'Hello' },
+* 	{ role: 'assistant', content: 'Hi there' },
+* ])
+* const section = await conversation.compact() // folds both into one summarized section
+* conversation.view() // [{ role: 'assistant', content: 'recap of 2' }] — the live tail is empty
+* conversation.summary // 'recap of 1' — the rollup over the one section
+* ```
+*/
+var Conversation = class {
+	#id;
+	#emitter;
+	#summarize;
+	#keep;
+	#cap;
+	#sections = [];
+	#summary;
+	#messages = /* @__PURE__ */ new Map();
+	constructor(options) {
+		const snapshot = options?.snapshot;
+		this.#id = snapshot?.id ?? options?.id ?? crypto.randomUUID();
+		this.#emitter = new Emitter({
+			...options?.on === void 0 ? {} : { on: options.on },
+			...options?.error === void 0 ? {} : { error: options.error }
+		});
+		this.#summarize = options?.summarize;
+		this.#keep = options?.keep ?? 0;
+		if (options?.sections !== void 0 && options.sections < 1) throw new ConversationError("SECTIONS", "a sections cap must be >= 1");
+		this.#cap = options?.sections;
+		if (snapshot !== void 0) {
+			this.#summary = snapshot.summary;
+			for (const section of snapshot.sections) this.#sections.push(section);
+			for (const message of snapshot.messages) this.#messages.set(message.id, message);
+		}
+	}
+	get id() {
+		return this.#id;
+	}
+	get emitter() {
+		return this.#emitter;
+	}
+	get summary() {
+		return this.#summary;
+	}
+	get sections() {
+		return [...this.#sections];
+	}
+	get summarizable() {
+		return this.#summarize !== void 0;
+	}
+	get count() {
+		return this.#messages.size;
+	}
+	add(input) {
+		if (isArray(input)) return input.map((one) => this.#create(one));
+		return this.#create(input);
+	}
+	message(id) {
+		return this.#messages.get(id);
+	}
+	messages() {
+		return [...this.#messages.values()];
+	}
+	remove(ids) {
+		if (isArray(ids)) {
+			let removed = true;
+			for (const id of ids) if (!this.#messages.delete(id)) removed = false;
+			return removed;
+		}
+		return this.#messages.delete(ids);
+	}
+	clear() {
+		this.#messages.clear();
+	}
+	view() {
+		return [...this.#sections.map((section) => buildRecapMessage(section)), ...this.#messages.values()];
+	}
+	async compact(options) {
+		const summarize = this.#summarize;
+		if (summarize === void 0) throw new ConversationError("SUMMARIZER", "cannot compact a conversation without a summarizer");
+		const cap = options?.sections ?? this.#cap;
+		if (cap !== void 0 && cap < 1) throw new ConversationError("SECTIONS", "a sections cap must be >= 1");
+		const keep = options?.keep ?? this.#keep;
+		const live = [...this.#messages.values()];
+		const fold = keep <= 0 ? live.length : live.length - keep;
+		if (fold <= 0) return void 0;
+		const slice = live.slice(0, fold);
+		const summary = await summarize(slice);
+		const section = {
+			id: crypto.randomUUID(),
+			summary,
+			messages: slice
+		};
+		for (const message of slice) this.#messages.delete(message.id);
+		this.#sections.push(section);
+		if (cap !== void 0 && this.#sections.length > cap) {
+			const overflow = this.#sections.length - cap + 1;
+			const folded = this.#sections.slice(0, overflow);
+			try {
+				const merged = {
+					id: crypto.randomUUID(),
+					summary: await summarize(folded.map((one) => buildSummaryMessage(one))),
+					messages: folded.flatMap((one) => one.messages)
+				};
+				this.#sections.splice(0, overflow, merged);
+				this.#emitter.emit("collapse", merged);
+			} catch (error) {
+				this.#summary = await summarize(this.#sections.map((one) => buildSummaryMessage(one)));
+				this.#emitter.emit("summary", this.#summary);
+				throw error;
+			}
+		}
+		this.#summary = await summarize(this.#sections.map((one) => buildSummaryMessage(one)));
+		this.#emitter.emit("summary", this.#summary);
+		this.#emitter.emit("compact", section);
+		return section;
+	}
+	rehydrate(id) {
+		const section = this.#sections.find((one) => one.id === id);
+		this.#emitter.emit("rehydrate", id);
+		return section === void 0 ? [] : section.messages;
+	}
+	search(query) {
+		const needle = query.toLowerCase();
+		return [...this.#sections.flatMap((section) => section.messages), ...this.#messages.values()].filter((message) => message.content.toLowerCase().includes(needle));
+	}
+	reference(options) {
+		const lines = [`[Reference — conversation "${options?.label ?? this.#id}" — NOT part of this conversation]`];
+		if (options?.summary !== false && this.#summary !== void 0) lines.push(`Summary: ${this.#summary}`);
+		const messages = options?.messages ?? [];
+		if (messages.length > 0) {
+			lines.push("Relevant messages:");
+			for (const message of messages) lines.push(`- ${message.role}: ${message.content}`);
+		}
+		return lines.join("\n");
+	}
+	snapshot() {
+		return {
+			id: this.#id,
+			...this.#summary === void 0 ? {} : { summary: this.#summary },
+			sections: this.sections,
+			messages: this.messages()
+		};
+	}
+	#create(input) {
+		const message = {
+			id: crypto.randomUUID(),
+			role: input.role,
+			content: input.content,
+			...input.calls === void 0 ? {} : { calls: input.calls },
+			...input.images === void 0 ? {} : { images: input.images }
+		};
+		this.#messages.set(message.id, message);
+		return message;
+	}
+};
+//#endregion
+//#region src/core/conversations/ConversationManager.ts
+/**
+* Registers {@link Conversation}s keyed by `id`, in insertion order, with an active pointer —
+* the id-keyed store over the conversation layer, the `active` / `switch` seam the
+* {@link import('../AgentContext.js').AgentContext} renders, and the durable `open` / `save`
+* store seam. Event-free (a registry, like
+* {@link import('@orkestrel/workspace').WorkspaceManager}); the observability lives on each
+* {@link Conversation}.
 *
-* @param usage - The token usage to sanitize (e.g. a provider's abort-partial usage)
-* @returns A new {@link TokenUsage} with every field a safe non-negative integer
+* @remarks
+* - **Registry.** Conversations live in an insertion-ordered `Map` keyed by `id`. `add(input?)`
+*   mints a {@link Conversation} (its `id` from `input` or `crypto.randomUUID()`), flowing the
+*   manager's default `#summarize` / `#keep` in unless the `input` overrides them, and stores
+*   it (an already-present `id` overwrites — last write wins). `count` is the map size,
+*   `conversation(id)` looks one up, `conversations()` lists them in insertion order.
+* - **Active pointer.** `active` is the active conversation (the agent's message source the
+*   context renders), `undefined` until the first `add` (which auto-activates it — a registry
+*   with conversations always has one active). A subsequent `add` leaves `active` unchanged.
+*   `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 — `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`).
 *
 * @example
 * ```ts
-* sanitizeUsage({ prompt: -5, completion: NaN, total: 12.7 }) // { prompt: 0, completion: 0, total: 12 }
+* const manager = new ConversationManager({ summarize: async (m) => `recap of ${m.length}` })
+* const conversation = manager.add() // auto-activates — active === conversation
+* manager.add({ id: 'scratch' }) // leaves active unchanged
+* manager.switch('scratch') // re-points active to the 'scratch' conversation
+* manager.count // 2
 * ```
 */
-function sanitizeUsage(usage) {
-	return {
-		prompt: sanitizeToken(usage.prompt),
-		completion: sanitizeToken(usage.completion),
-		total: sanitizeToken(usage.total)
-	};
-}
+var ConversationManager = class {
+	#conversations = /* @__PURE__ */ new Map();
+	#active;
+	#summarize;
+	#keep;
+	#sections;
+	#store;
+	constructor(options) {
+		this.#summarize = options?.summarize;
+		this.#keep = options?.keep ?? 0;
+		this.#sections = options?.sections;
+		this.#store = options?.store;
+	}
+	get count() {
+		return this.#conversations.size;
+	}
+	get active() {
+		return this.#active === void 0 ? void 0 : this.#conversations.get(this.#active);
+	}
+	conversation(id) {
+		return this.#conversations.get(id);
+	}
+	conversations() {
+		return [...this.#conversations.values()];
+	}
+	add(input) {
+		const sections = input?.sections ?? this.#sections;
+		const summarize = input?.summarize ?? this.#summarize;
+		const conversation = new Conversation({
+			...input?.id === void 0 ? {} : { id: input.id },
+			...input?.on === void 0 ? {} : { on: input.on },
+			...summarize === void 0 ? {} : { summarize },
+			keep: input?.keep ?? this.#keep,
+			...sections === void 0 ? {} : { sections },
+			...input?.snapshot === void 0 ? {} : { snapshot: input.snapshot }
+		});
+		this.#conversations.set(conversation.id, conversation);
+		if (this.#active === void 0) this.#active = conversation.id;
+		return conversation;
+	}
+	switch(id) {
+		const conversation = this.#conversations.get(id);
+		if (conversation === void 0) return void 0;
+		this.#active = id;
+		return conversation;
+	}
+	async open(id) {
+		const existing = this.#conversations.get(id);
+		if (existing !== void 0) {
+			this.#active = id;
+			return existing;
+		}
+		if (this.#store === void 0) return void 0;
+		const snapshot = await this.#store.get(id);
+		if (snapshot === void 0) return void 0;
+		const conversation = this.add({ snapshot });
+		this.#active = conversation.id;
+		return conversation;
+	}
+	async save(id) {
+		const conversation = this.#conversations.get(id);
+		if (this.#store === void 0 || conversation === void 0) return false;
+		await this.#store.set(conversation.snapshot());
+		return true;
+	}
+	remove(ids) {
+		if (isArray(ids)) {
+			let removed = true;
+			for (const id of ids) if (!this.#drop(id)) removed = false;
+			return removed;
+		}
+		return this.#drop(ids);
+	}
+	clear() {
+		this.#conversations.clear();
+		this.#active = void 0;
+	}
+	#drop(id) {
+		const removed = this.#conversations.delete(id);
+		if (removed && this.#active === id) this.#active = void 0;
+		return removed;
+	}
+};
 //#endregion
 //#region src/core/instructions/Instruction.ts
 /**
-* 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 — an {@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
@@ -986,40 +1286,41 @@ var Instruction = class {
 	name;
 	content;
 	priority;
-	format;
+	override;
 	constructor(input) {
 		this.id = crypto.randomUUID();
 		this.name = input.name;
 		this.content = input.content;
 		this.priority = input.priority ?? 0;
-		if (input.format !== void 0) this.format = input.format;
+		if (input.override !== void 0) this.override = input.override;
 	}
 };
 //#endregion
 //#region src/core/instructions/InstructionManager.ts
 /**
-* 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` so a re-`add` overwrites, last write wins, and listed by descending
+* `priority`, carrying the `open` / `render` build contract and an observable `emitter`.
 *
 * @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
-*   `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
+*   `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
-*   instruction (its `content`). Each ENCAPSULATES the cascade's `[options-override →
+* - **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
+*   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`
 *   handler (the `error` option), so a buggy observer can never corrupt a mutation.
 *
@@ -1050,10 +1351,10 @@ var InstructionManager = class {
 	get count() {
 		return this.#instructions.size;
 	}
-	get description() {
+	get open() {
 		return this.#format?.open ?? "## Instructions";
 	}
-	get framing() {
+	get format() {
 		return this.#format;
 	}
 	add(input) {
@@ -1066,13 +1367,13 @@ var InstructionManager = class {
 	instructions() {
 		return [...this.#instructions.values()].sort((a, b) => b.priority - a.priority);
 	}
-	format(instruction) {
+	render(instruction) {
 		return this.#format?.render?.(instruction) ?? instruction.content;
 	}
 	remove(names) {
 		if (isArray(names)) {
-			let removed = false;
-			for (const name of names) if (this.#delete(name)) removed = true;
+			let removed = true;
+			for (const name of names) if (!this.#delete(name)) removed = false;
 			return removed;
 		}
 		return this.#delete(names);
@@ -1096,63 +1397,64 @@ var InstructionManager = class {
 //#endregion
 //#region src/core/AgentContext.ts
 /**
-* The richer turn context the agent loop assembles a provider request from — 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}.
+* 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}. `build()` folds the scoped managers and the active
+* workspace into one system block, then the conversation, and never reads `tools`.
 *
 * @remarks
 * - **Composition.** `system` is the optional system prompt; `instructions` / `tools` /
 *   `workspaces` / `conversations` are the registries passed in `options` (bring your own), or
-*   fresh empty ones when omitted (so `workspaces` is ALWAYS present); `messages` is the ACTIVE
-*   conversation's live tail (ALWAYS defined — see below). `scope` is the active filter —
+*   fresh empty ones when omitted (so `workspaces` is always present); `messages` is the active
+*   conversation's live tail (always defined — see the following item). `scope` is the active filter —
 *   `undefined` (the default) ⇒ no filtering; change it through `apply(scope)`. The structural
 *   `workspaces` / `conversations` registries are fixed at construction; switch their active
 *   members through their own `switch(id)` methods.
-* - **The message source — the conversation registry's ACTIVE conversation.** `conversations` is a
-*   {@link ConversationManagerInterface}; the context ENSURES it always has an active conversation
-*   (at construction it `add`s a default when the manager has none), so the DYNAMIC `messages`
-*   getter — `this.#conversations.active` — is ALWAYS defined. `messages` returns the active
-*   conversation ITSELF (it owns the live tail + the message verbs directly, satisfying
+* - **The message source — the conversation registry's active conversation.** `conversations` is a
+*   {@link ConversationManagerInterface}; the context ensures it always has an active conversation
+*   (at construction it `add`s a default when the manager has none), so the dynamic `messages`
+*   getter — `this.#conversations.active` — is always defined. `messages` returns the active
+*   conversation itself (it owns the live tail + the message verbs directly, satisfying
 *   {@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`
-*   is read dynamically, an agent SWITCHES the active
-*   conversation BETWEEN runs (`conversations.switch(id)`) to serve MANY threads (the real
+*   authoritative message inclusion — the scope does not filter the conversation (it owns inclusion
+*   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
 *   for concurrent threads.
 * - **`build(format?)` — the scoped assembly + the format cascade.** It folds, in order,
-*   the system prompt then the scope-filtered instructions → the ACTIVE workspace's text files
+*   the system prompt then the scope-filtered instructions → the active workspace's text files
 *   (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
+*   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 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 >
+*   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
-*   the LAST user message (a vision provider reads images off a user turn); when no user message
+*   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
+*   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`,
-*   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
-*   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` /
+* - **The active workspace, rendered by carrier — the sole document/image context.**
+*   `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` 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
@@ -1207,12 +1509,12 @@ var AgentContext = class {
 		const parts = [];
 		if (this.#system !== void 0) parts.push(this.#system);
 		const instructions = filterAllowList(scope?.instructions, this.#instructions.instructions(), (one) => one.name);
-		this.#section(parts, this.#header(this.#instructions, format?.instructions), instructions, (one) => this.#render(this.#instructions, format?.instructions, one), this.#footer(this.#instructions, format?.instructions));
+		const instructed = renderSection(resolveOpen(this.#instructions, format?.instructions), instructions, (one) => resolveItem(this.#instructions, format?.instructions, one), resolveClose(this.#instructions, format?.instructions));
+		if (instructed !== void 0) parts.push(instructed);
 		const files = filterAllowList(scope?.files, this.#workspaces.active?.files() ?? [], (one) => one.path);
-		const workspaceTexts = files.filter((file) => isText(file.content));
-		this.#section(parts, WORKSPACE_SECTION_HEADER, workspaceTexts, (file) => this.#fenced(file), void 0);
-		const conversation = (this.#conversations.active ?? this.#ensure()).view();
-		const tail = this.#attach(conversation, this.#workspaceImages(files));
+		const documented = renderSection(WORKSPACE_SECTION_HEADER, files.filter((file) => isText(file.content)), (file) => isText(file.content) ? renderFencedFile(file.path, file.content.language, file.content.text) : renderFencedFile(file.path, "text", ""), void 0);
+		if (documented !== void 0) parts.push(documented);
+		const tail = attachUserImages((this.#conversations.active ?? this.#ensure()).view(), collectImageData(files));
 		if (parts.length === 0) return tail;
 		return [{
 			id: crypto.randomUUID(),
@@ -1220,55 +1522,6 @@ var AgentContext = class {
 			content: parts.join("\n\n")
 		}, ...tail];
 	}
-	#section(parts, open, items, format, close) {
-		if (items.length === 0) return;
-		const lines = [open, ...items.map(format)];
-		if (close !== void 0) lines.push(close);
-		parts.push(lines.join("\n\n"));
-	}
-	#header(manager, provider) {
-		return manager.framing?.open ?? provider?.open ?? manager.description;
-	}
-	#footer(manager, provider) {
-		return manager.framing?.close ?? provider?.close;
-	}
-	#render(manager, provider, item) {
-		return item.format ?? manager.framing?.render?.(item) ?? provider?.render?.(item) ?? manager.format(item);
-	}
-	#attach(conversation, data) {
-		if (data.length === 0) return conversation;
-		let target = -1;
-		for (let index = conversation.length - 1; index >= 0; index -= 1) if (conversation[index]?.role === "user") {
-			target = index;
-			break;
-		}
-		if (target === -1) return conversation;
-		return conversation.map((message, index) => index === target ? this.#withImages(message, data) : message);
-	}
-	#withImages(message, data) {
-		const images = [...message.images ?? [], ...data];
-		return message.calls === void 0 ? {
-			id: message.id,
-			role: message.role,
-			content: message.content,
-			images
-		} : {
-			id: message.id,
-			role: message.role,
-			content: message.content,
-			calls: message.calls,
-			images
-		};
-	}
-	#fenced(file) {
-		if (isText(file.content)) return fencedFile(file.path, file.content.language, file.content.text);
-		return fencedFile(file.path, "text", "");
-	}
-	#workspaceImages(files) {
-		const data = [];
-		for (const file of files) if (isBinary(file.content) && file.content.mime.startsWith("image/")) data.push(file.content.data);
-		return data;
-	}
 	#ensure() {
 		const conversation = this.#conversations.add();
 		return this.#conversations.active ?? conversation;
@@ -1277,10 +1530,11 @@ var AgentContext = class {
 //#endregion
 //#region src/core/Channel.ts
 /**
-* 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
-* producer make progress without a consumer pulling.
+* Buffers chunks in a minimal unbounded async channel — the eager pump writes them in (`push`)
+* and ends it (`close` / `fail`) regardless of consumption, while 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, and it is why an agent's `result` settles whether or not
+* its `events` are drained.
 *
 * @remarks
 * The standard resolver-swap: a waiting `drain` parks on `#wake` (a void resolver);
@@ -1340,15 +1594,17 @@ var Channel = class {
 //#endregion
 //#region src/core/Agent.ts
 /**
-* The agent loop — 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`.
+* 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` that share one private run — bounded by the
+* run `signal`, the `timeout`, and the `budget` folded through `AbortSignal.any`, paced by
+* `scheduler`, with tool iteration capped at `limit`.
 *
 * @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
@@ -1357,17 +1613,17 @@ var Channel = class {
 *   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
+*   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
 *   provider / tool error rejects.
 * - **Paced + capped.** The `scheduler` (when given) `yield`s between turns; tool
 *   iteration is capped at `limit`.
-* - **Two observation surfaces.** The PULL {@link AgentChunk} stream carries per-token
-*   deltas (+ usage/tool chunks); the PUSH {@link emitter} ({@link AgentEventMap}) carries
+* - **Two observation surfaces.** The pull {@link AgentChunk} stream carries per-token
+*   deltas (+ usage/tool chunks); the push {@link emitter} ({@link AgentEventMap}) carries
 *   lifecycle + usage/tool/deny moments for fire-and-forget observers. Every event is
-*   emitted directly, AFTER the relevant state transition / settle; the emitter isolates a
+*   emitted directly, after the relevant state transition / settle; the emitter isolates a
 *   listener throw and routes it to its `error` handler (the `error` option), so a buggy
 *   observer can never escape into / reorder / corrupt the settle-once loop — observation is
 *   purely a side-channel.
@@ -1380,6 +1636,7 @@ var Channel = class {
 * ```
 */
 var Agent = class {
+	#id;
 	#provider;
 	#context;
 	#limit;
@@ -1391,10 +1648,10 @@ var Agent = class {
 	#window;
 	#strict;
 	#emitter;
-	id = crypto.randomUUID();
-	#status = "idle";
+	#settled = "idle";
 	#runs = /* @__PURE__ */ new Set();
 	constructor(provider, options) {
+		this.#id = crypto.randomUUID();
 		this.#provider = provider;
 		this.#context = new AgentContext({
 			...options?.system === void 0 ? {} : { system: options.system },
@@ -1417,11 +1674,14 @@ var Agent = class {
 			...options?.error === void 0 ? {} : { error: options.error }
 		});
 	}
+	get id() {
+		return this.#id;
+	}
 	get emitter() {
 		return this.#emitter;
 	}
 	get status() {
-		return this.#status;
+		return this.#runs.size > 0 ? "running" : this.#settled;
 	}
 	get context() {
 		return this.#context;
@@ -1440,18 +1700,10 @@ var Agent = class {
 		const signal = this.#parents(timeout, budget, options?.signal);
 		const abort = createAbort(signal === void 0 ? {} : { signal });
 		this.#runs.add(abort);
-		this.#status = "running";
 		this.#emitter.emit("start", this.id);
-		const state = { outcome: {
-			content: "",
-			thinking: void 0,
-			usage: void 0,
-			partial: false,
-			exhausted: false
-		} };
 		const channel = new Channel();
-		const settled = createDeferred();
-		this.#pump(abort, state, timeout, channel, settled, options?.think, options?.schema, limit, budget);
+		const settled = Promise.withResolvers();
+		this.#pump(abort, timeout, channel, settled, options?.think, options?.schema, limit, budget);
 		settled.promise.catch(() => {});
 		return {
 			events: this.#events(channel, abort),
@@ -1462,26 +1714,38 @@ var Agent = class {
 	abort(reason) {
 		for (const abort of [...this.#runs]) abort.abort(reason);
 	}
-	async #pump(abort, state, timeout, channel, settled, think, schema, limit, budget) {
+	async #pump(abort, timeout, channel, settled, think, schema, limit, budget) {
 		let failure;
+		let outcome = {
+			content: "",
+			thinking: void 0,
+			usage: void 0,
+			partial: false,
+			exhausted: false
+		};
 		try {
-			for await (const chunk of this.#run(abort, state, think, schema, limit, budget)) channel.push(chunk);
+			const run = this.#run(abort, think, schema, limit, budget);
+			let next = await run.next();
+			while (next.done !== true) {
+				channel.push(next.value);
+				next = await run.next();
+			}
+			outcome = next.value;
 		} catch (error) {
 			failure = { error };
 		} finally {
 			timeout?.clear();
 			this.#runs.delete(abort);
 			if (failure === void 0) {
-				const outcome = state.outcome;
-				this.#status = "done";
+				this.#settled = "done";
 				channel.close();
-				const result = this.#result(outcome);
+				const result = assembleResult(outcome);
 				settled.resolve(result);
 				if (outcome.exhausted) this.#emitter.emit("exhaust", limit);
 				else if (outcome.partial) this.#emitter.emit("abort", abort.signal.reason);
 				this.#emitter.emit("finish", result);
 			} else {
-				this.#status = "error";
+				this.#settled = "error";
 				channel.fail(failure.error);
 				settled.reject(failure.error);
 				this.#emitter.emit("error", failure.error);
@@ -1495,7 +1759,7 @@ var Agent = class {
 			abort.abort();
 		}
 	}
-	async *#run(abort, state, think, schema, limit, budget) {
+	async *#run(abort, think, schema, limit, budget) {
 		const messages = [...this.#context.build(this.#provider.format)];
 		const tools = this.#context.tools;
 		let content = "";
@@ -1503,11 +1767,13 @@ var Agent = class {
 		let usage;
 		let pending = false;
 		let broke = false;
-		const compaction = { state: { futile: false } };
+		let partial = false;
+		let exhausted = false;
+		let futile = false;
 		const compacting = this.#window !== void 0 && this.#context.conversations.active?.summarizable === true;
 		if (compacting) {
 			this.#window?.clear();
-			if (!abort.signal.aborted) await this.#trim(messages, compaction, false);
+			if (!abort.signal.aborted) futile = await this.#trim(messages, false);
 		}
 		for (let turn = 0; turn < limit; turn += 1) {
 			this.#emitter.emit("turn", turn);
@@ -1515,20 +1781,14 @@ var Agent = class {
 				await this.#scheduler?.yield({ signal: abort.signal });
 			} catch (error) {
 				if (abort.signal.aborted) {
-					state.outcome = {
-						...state.outcome,
-						partial: true
-					};
+					partial = true;
 					broke = true;
 					break;
 				}
 				throw error;
 			}
 			if (abort.signal.aborted) {
-				state.outcome = {
-					...state.outcome,
-					partial: true
-				};
+				partial = true;
 				broke = true;
 				break;
 			}
@@ -1554,7 +1814,7 @@ var Agent = class {
 			} catch (error) {
 				if (abort.signal.aborted) {
 					if (isProviderAbortError(error)) {
-						if (error.partial.thinking !== void 0) thinking = this.#thought(thinking, error.partial.thinking);
+						if (error.partial.thinking !== void 0) thinking = joinThinking(thinking, error.partial.thinking);
 						if (error.partial.usage !== void 0) {
 							const abortUsage = sanitizeUsage(error.partial.usage);
 							budget?.consume({
@@ -1562,19 +1822,16 @@ var Agent = class {
 								completion: Math.max(0, abortUsage.completion - charged),
 								total: Math.max(0, abortUsage.total - charged)
 							});
-							usage = this.#sum(usage, abortUsage);
+							usage = sumUsage(usage, abortUsage);
 						}
 					}
-					state.outcome = {
-						...state.outcome,
-						partial: true
-					};
+					partial = true;
 					broke = true;
 					break;
 				}
 				throw error;
 			}
-			if (result.thinking !== void 0 && result.thinking.length > 0) thinking = this.#thought(thinking, result.thinking);
+			if (result.thinking !== void 0 && result.thinking.length > 0) thinking = joinThinking(thinking, result.thinking);
 			if (result.usage !== void 0) {
 				const resultUsage = sanitizeUsage(result.usage);
 				budget?.consume({
@@ -1582,10 +1839,10 @@ var Agent = class {
 					completion: Math.max(0, resultUsage.completion - charged),
 					total: Math.max(0, resultUsage.total - charged)
 				});
-				usage = this.#sum(usage, resultUsage);
+				usage = sumUsage(usage, resultUsage);
 				this.#emitter.emit("usage", resultUsage);
 				yield {
-					type: "usage",
+					category: "usage",
 					usage: resultUsage
 				};
 			}
@@ -1603,7 +1860,7 @@ var Agent = class {
 					if (call === void 0 || outcomeResult === void 0) continue;
 					this.#emitter.emit("tool", call, outcomeResult);
 					yield {
-						type: "tool",
+						category: "tool",
 						call,
 						result: outcomeResult
 					};
@@ -1613,7 +1870,7 @@ var Agent = class {
 					});
 					messages.push(toolMessage);
 				}
-				if (compacting) await this.#trim(messages, compaction, true);
+				if (compacting && !futile) futile = await this.#trim(messages, true);
 				pending = true;
 				continue;
 			}
@@ -1626,37 +1883,35 @@ var Agent = class {
 			broke = true;
 			break;
 		}
-		if (!broke && pending) state.outcome = {
-			...state.outcome,
-			partial: true,
-			exhausted: !abort.signal.aborted
-		};
-		state.outcome = {
-			...state.outcome,
+		if (!broke && pending) {
+			partial = true;
+			exhausted = !abort.signal.aborted;
+		}
+		return {
 			content,
 			thinking,
-			usage
+			usage,
+			partial,
+			exhausted
 		};
 	}
-	async #trim(messages, compaction, latchFutile) {
+	async #trim(messages, latch) {
 		const conversation = this.#context.conversations.active;
-		if (this.#window === void 0 || conversation?.summarizable !== true || compaction.state.futile) return;
+		if (this.#window === void 0 || conversation?.summarizable !== true) return false;
 		this.#window.clear();
 		this.#window.consume(messages);
-		if (!this.#window.exhausted) return;
+		if (!this.#window.exhausted) return false;
 		let section;
 		try {
 			section = await conversation.compact();
 		} catch (error) {
-			this.#emitter.emit("compactError", error);
+			this.#emitter.emit("fault", error);
 			if (this.#strict) throw error;
-			return;
-		}
-		if (section === void 0) {
-			if (latchFutile) compaction.state = { futile: true };
-			return;
+			return false;
 		}
+		if (section === void 0) return latch;
 		messages.splice(0, messages.length, ...this.#context.build(this.#provider.format));
+		return false;
 	}
 	async #authorize(tools, calls) {
 		if (this.#authority === void 0) return tools.execute(calls);
@@ -1668,32 +1923,21 @@ var Agent = class {
 			try {
 				decision = authority.evaluate({ call });
 			} catch (error) {
-				const reason = this.#reason(error);
-				denials.set(call.id, this.#denial(call, reason));
+				const reason = errorToMessage(error);
+				denials.set(call.id, denyCall(call, reason));
 				this.#emitter.emit("deny", call, reason);
 				continue;
 			}
 			if (decision.allowed) allowed.push(call);
 			else {
-				denials.set(call.id, this.#denial(call, decision.reason));
+				denials.set(call.id, denyCall(call, decision.reason));
 				this.#emitter.emit("deny", call, decision.reason);
 			}
 		}
 		const executed = allowed.length > 0 ? await tools.execute(allowed) : [];
 		const byId = new Map(denials);
 		for (const result of executed) byId.set(result.id, result);
-		return calls.map((call) => byId.get(call.id) ?? this.#denial(call, void 0));
-	}
-	#denial(call, reason) {
-		return {
-			success: false,
-			id: call.id,
-			name: call.name,
-			error: reason !== void 0 ? `denied: ${reason}` : "denied by authority"
-		};
-	}
-	#reason(error) {
-		return error instanceof Error ? error.message : String(error);
+		return calls.map((call) => byId.get(call.id) ?? denyCall(call, void 0));
 	}
 	async *#provide(messages, signal, definitions, think, schema, onDelta) {
 		const options = {};
@@ -1703,14 +1947,14 @@ var Agent = class {
 		let next = await generator.next();
 		while (!next.done) {
 			const delta = next.value;
-			if (delta.type === "content") {
+			if (delta.channel === "content") {
 				onDelta(delta.text);
 				yield {
-					type: "token",
+					category: "token",
 					content: delta.text
 				};
 			} else yield {
-				type: "think",
+				category: "think",
 				content: delta.text
 			};
 			next = await generator.next();
@@ -1727,34 +1971,14 @@ var Agent = class {
 		if (signals.length === 1) return signals[0];
 		return AbortSignal.any(signals);
 	}
-	#thought(running, next) {
-		return running === void 0 ? next : `${running}\n\n${next}`;
-	}
-	#sum(running, next) {
-		if (running === void 0) return next;
-		return {
-			prompt: running.prompt + next.prompt,
-			completion: running.completion + next.completion,
-			total: running.total + next.total
-		};
-	}
-	#result(outcome) {
-		const result = {
-			content: outcome.content,
-			partial: outcome.partial
-		};
-		if (outcome.thinking !== void 0) result.thinking = outcome.thinking;
-		if (outcome.usage !== void 0) result.usage = outcome.usage;
-		return result;
-	}
 };
 //#endregion
 //#region src/core/AgentRegistry.ts
 /**
-* 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), throws on a name
+* absent from its pool, and `build`s a seeded, signal-wired {@link Agent} from a job's names and
+* data.
 *
 * @remarks
 * - **Why it exists.** An `AgentJobInput` is serializable so it can survive a crash in a
@@ -1762,18 +1986,18 @@ var Agent = class {
 *   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.
 *
@@ -1839,33 +2063,34 @@ var AgentRegistry = class {
 	}
 	#resolve(pool, category, name) {
 		const value = pool.get(name);
-		if (value === void 0) throw new Error(`unknown ${category}: ${name}`);
+		if (value === void 0) throw new AgentError("REGISTRY", `unknown ${category}: ${name}`);
 		return value;
 	}
 };
 //#endregion
 //#region src/core/Authority.ts
 /**
-* The synchronous policy gate the agent loop consults before each tool call runs —
-* it turns one {@link AuthorityContextInterface} into an {@link AuthorityDecision}.
+* Gates the agent loop's tool calls — the synchronous policy consulted before each call runs,
+* turning one {@link AuthorityContext} into an {@link AuthorityDecision} by walking the ordered
+* rules first-match-wins and falling back to a configurable default, which allows an unmatched
+* call unless its `fallback` denies.
 *
 * @remarks
 * - **Ordered, first-match-wins.** `evaluate` walks the configured rules in order and
-*   returns the FIRST whose `match(context)` is true as
-*   `{ zone, allowed: rule.allowed ?? true, reason }` — a matched rule ALLOWS by
-*   default and DENIES only when its `allowed` is explicitly `false`.
+*   returns the first whose `match(context)` is true as
+*   `{ zone, allowed: rule.allowed ?? true, reason }` — a matched rule allows by
+*   default and denies only when its `allowed` is explicitly `false`.
 * - **Fallback.** When no rule matches, `evaluate` returns the configured `fallback`.
 *   It defaults to `{ zone: DEFAULT_AUTHORITY_ZONE, allowed: true }` (allow-unmatched),
-*   so a rules list of denials behaves as a DENYLIST. To make the gate deny-by-default
-*   (an ALLOWLIST — only matched rules that allow get through), pass an `allowed: false`
+*   so a rules list of denials behaves as a denylist. To make the gate deny-by-default
+*   (an allowlist — only matched rules that allow get through), pass an `allowed: false`
 *   `fallback`.
 * - **Consulted before each tool call.** The agent loop calls `evaluate({ call })` for
 *   every {@link import('@orkestrel/tool').ToolCall} the model emits; a denied call is fed
 *   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
@@ -1898,47 +2123,155 @@ var Authority = class {
 	}
 };
 //#endregion
+//#region src/core/validators.ts
+/**
+* Checks whether an `unknown` is structurally a {@link Message} record — the per-message step of
+* the {@link isConversationSnapshot} and {@link isSection} read-boundary narrows, where a present
+* `calls` must be an array of valid {@link import('@orkestrel/tool').ToolCall}s. Total, never
+* throwing, and never an assertion; the conversation analogue of
+* {@link import('@orkestrel/workspace').isFile}.
+*
+* @remarks
+* A total guard (it never throws — adversarial input returns `false`). It checks the message's
+* 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
+* 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 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 if `value` has the structural shape of a {@link Message}; false otherwise
+*
+* @example
+* ```ts
+* isMessage({ id: '1', role: 'user', content: 'hi' }) // true
+* isMessage({ id: '1', role: 'assistant', content: '', calls: [] }) // true
+* isMessage({ id: '1', role: 'user' }) // false (missing content)
+* isMessage({ id: '1', role: 'assistant', content: '', calls: [null] }) // false (malformed call)
+* ```
+*/
+function isMessage(value) {
+	if (!isRecord(value)) return false;
+	if (!isString(value.id) || !isString(value.role) || !isString(value.content)) return false;
+	if (value.calls !== void 0 && !(isArray(value.calls) && value.calls.every(isToolCall))) return false;
+	return value.images === void 0 || isArray(value.images);
+}
+/**
+* Checks whether an `unknown` is structurally a {@link Section} record — a `string` `id` and
+* `summary` beside a `messages` array of valid {@link Message}s, the per-section step of the
+* {@link isConversationSnapshot} read-boundary narrow. Total, never throwing, and 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 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 if `value` has the structural shape of a {@link Section}; false otherwise
+*
+* @example
+* ```ts
+* isSection({ id: 's', summary: 'recap', messages: [{ id: '1', role: 'user', content: 'hi' }] }) // true
+* isSection({ id: 's', summary: 'recap', messages: 'nope' }) // false
+* isSection({ id: 's', messages: [] }) // false (missing summary)
+* ```
+*/
+function isSection(value) {
+	if (!isRecord(value)) return false;
+	if (!isString(value.id) || !isString(value.summary)) return false;
+	return isArray(value.messages) && value.messages.every(isMessage);
+}
+/**
+* Narrows an `unknown` to a {@link ConversationSnapshot} — a `string` `id`, an optional `string`
+* `summary`, and valid `sections` and `messages` arrays; 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), never throwing. The exact
+* analogue of {@link import('@orkestrel/workspace').isWorkspaceSnapshot}.
+*
+* @remarks
+* 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 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
+* element) resolves `false`, so a
+* {@link import('./conversations/stores/DatabaseConversationStore.js').DatabaseConversationStore}
+* read yields `undefined` rather than a broken conversation.
+*
+* @param value - The value to test (an opaque storage read)
+* @returns True if `value` has the structural shape of a {@link ConversationSnapshot}; false otherwise
+*
+* @example
+* ```ts
+* isConversationSnapshot({ id: 'c1', sections: [], messages: [] }) // true
+* isConversationSnapshot({ id: 'c1', summary: 'recap', sections: [], messages: [] }) // true
+* isConversationSnapshot({ id: 'c1', sections: 'nope', messages: [] }) // false
+* isConversationSnapshot({ sections: [], messages: [] }) // false (missing id)
+* ```
+*/
+function isConversationSnapshot(value) {
+	if (!isRecord(value)) return false;
+	if (!isString(value.id)) return false;
+	if (value.summary !== void 0 && !isString(value.summary)) return false;
+	if (!isArray(value.sections) || !value.sections.every(isSection)) return false;
+	return isArray(value.messages) && value.messages.every(isMessage);
+}
+//#endregion
 //#region src/core/conversations/stores/DatabaseConversationStore.ts
 /**
-* A {@link ConversationStoreInterface} backed by 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
+* Backs a {@link ConversationStoreInterface} with one table of the `databases` layer — a
+* conversation's durable state is a row holding the snapshot as one opaque JSON column, narrowed
+* back on `get` by {@link import('../../validators.js').isConversationSnapshot}, 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}, and the exact twin of
 * {@link import('@orkestrel/workspace').DatabaseWorkspaceStore}.
 *
 * @remarks
 * The store is driver-agnostic: it holds a single {@link TableInterface} whose backend (memory,
 * JSON, SQLite, IndexedDB) is chosen by whoever builds it (the factories), so a JSON / SQLite /
-* IndexedDB backend swaps in WITHOUT touching the
+* IndexedDB backend swaps in without touching the
 * {@link import('../ConversationManager.js').ConversationManager} or the
 * {@link import('../Conversation.js').Conversation} — the same seam as
 * {@link import('@orkestrel/workspace').DatabaseWorkspaceStore}. The
 * driver defaults to memory ({@link import('../../factories.js').createDatabaseConversationStore}
-* passes `createMemoryDriver()`), so it ALSO works in memory out of the box; you opt into the
+* passes `createMemoryDriver()`), so it also works in memory out of the box; you opt into the
 * durable plumbing by passing a JSON / SQLite / IndexedDB driver.
 *
-* The {@link ConversationSnapshot} is stored as ONE OPAQUE JSON COLUMN — the table is a row of
+* The {@link ConversationSnapshot} is stored as one opaque JSON column — the table is a row of
 * `{ id; snapshot }` ({@link ConversationSnapshotRow}), the snapshot the whole JSON blob (a
 * `rawShape` column the factory builds) — exactly as `DatabaseWorkspaceStore` 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 (`snapshot` reads back as `unknown`).
+* The snapshot is already a complete, self-contained, pure-JSON payload, so storing it whole is
+* lossless and keeps the row type flat (`snapshot` reads back as `unknown`).
 *
-* - **`set(snapshot)` upserts under the snapshot's OWN `id`** (no separate id param) — it writes
+* - **`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
+* 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
+* 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()
@@ -1951,7 +2284,7 @@ var Authority = class {
 var DatabaseConversationStore = class {
 	#table;
 	/**
-	* 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)
@@ -1959,20 +2292,20 @@ var DatabaseConversationStore = class {
 	constructor(table) {
 		this.#table = table;
 	}
-	/** 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`. */
 	async get(id) {
 		const row = await this.#table.get(id);
 		if (row === void 0) return void 0;
 		return isConversationSnapshot(row.snapshot) ? row.snapshot : void 0;
 	}
-	/** 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 }`. */
 	async set(snapshot) {
 		await this.#table.set({
 			id: snapshot.id,
 			snapshot
 		});
 	}
-	/** 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). */
 	async delete(id) {
 		await this.#table.remove(id);
 	}
@@ -1980,34 +2313,35 @@ var DatabaseConversationStore = class {
 //#endregion
 //#region src/core/conversations/stores/MemoryConversationStore.ts
 /**
-* The in-memory {@link ConversationStoreInterface} — 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
+* 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 and the default
+* backing for `open` / `save`. 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
+* 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
 * the {@link import('../ConversationManager.js').ConversationManager} or the
 * {@link import('../Conversation.js').Conversation} — its driver-pluggable twin is
 * {@link import('./DatabaseConversationStore.js').DatabaseConversationStore} (the snapshot as one
 * opaque JSON column).
 *
 * - **`get` resolves the persisted snapshot for an id**, or `undefined` if none is stored.
-* - **`set` inserts / replaces under the snapshot's OWN `id`** (no separate id param).
+* - **`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()
@@ -2019,13 +2353,32 @@ var DatabaseConversationStore = class {
 */
 var MemoryConversationStore = class {
 	#snapshots = /* @__PURE__ */ new Map();
+	/**
+	* 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) {
 		return Promise.resolve(this.#snapshots.get(id));
 	}
+	/**
+	* 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`)
+	* @returns A promise that resolves after the snapshot is stored
+	*/
 	set(snapshot) {
 		this.#snapshots.set(snapshot.id, snapshot);
 		return Promise.resolve();
 	}
+	/**
+	* Drops a snapshot by id; an absent id is a no-op (no throw).
+	*
+	* @param id - The conversation id to drop
+	* @returns A promise that resolves after the snapshot is dropped
+	*/
 	delete(id) {
 		this.#snapshots.delete(id);
 		return Promise.resolve();
@@ -2034,23 +2387,25 @@ var MemoryConversationStore = class {
 //#endregion
 //#region src/core/scopes/Scope.ts
 /**
-* 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`) and read as an allow-list:
+* `undefined` lets everything pass, `[]` lets nothing pass, and a non-empty list passes the listed
+* keys alone. `narrow` composes a tighter child by set intersection.
 *
 * @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`.
-* - **Immutable.** The `id` is minted at construction; every supplied list is COPIED in
+* - **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 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
+*   `readonly`. A `Scope` is never mutated after construction — `narrow` returns a new
 *   one rather than altering this one.
-* - **`narrow` is set-INTERSECTION (immutable composition).** A child scope's visible set
-*   per category is the intersection of THIS scope's list and the config's list — but
+* - **`narrow` is set-intersection (immutable composition).** A child scope's visible set
+*   per category is the intersection of this scope's list and the config's list — but
 *   `undefined` means "no constraint", so it acts as the universal set: intersecting
 *   `undefined` with a list yields the list, and `undefined` with `undefined` stays
-*   `undefined`. Narrowing can only TIGHTEN, never widen — a key excluded by a parent
+*   `undefined`. Narrowing can only tighten, never widen — a key excluded by a parent
 *   can never be re-admitted by a child.
 *
 * @example
@@ -2076,9 +2431,9 @@ var Scope = class Scope {
 		if (input.files !== void 0) this.files = [...input.files];
 	}
 	narrow(config) {
-		const instructions = Scope.#intersect(this.instructions, config.instructions);
-		const tools = Scope.#intersect(this.tools, config.tools);
-		const files = Scope.#intersect(this.files, config.files);
+		const instructions = intersectKeys(this.instructions, config.instructions);
+		const tools = intersectKeys(this.tools, config.tools);
+		const files = intersectKeys(this.files, config.files);
 		return new Scope({
 			name: this.name,
 			...instructions === void 0 ? {} : { instructions },
@@ -2086,18 +2441,13 @@ var Scope = class Scope {
 			...files === void 0 ? {} : { files }
 		});
 	}
-	static #intersect(parent, child) {
-		if (parent === void 0) return child === void 0 ? void 0 : [...child];
-		if (child === void 0) return [...parent];
-		const allowed = new Set(parent);
-		return child.filter((key) => allowed.has(key));
-	}
 };
 //#endregion
 //#region src/core/scopes/ScopeManager.ts
 /**
-* 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, where `create` always mints and stores rather than overwriting,
+* and an observable `emitter` reports each change.
 *
 * @remarks
 * - **Registry.** Scopes live in an insertion-ordered `Map` keyed by their minted `id`;
@@ -2106,11 +2456,11 @@ var Scope = class Scope {
 *   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
+*   directly, strictly after the map mutation completes; the emitter isolates a listener
 *   throw and routes it to its `error` handler (the `error` option), so a buggy observer can
 *   never corrupt a mutation.
 *
@@ -2125,10 +2475,10 @@ var Scope = class Scope {
 var ScopeManager = class {
 	#scopes = /* @__PURE__ */ new Map();
 	#emitter;
-	constructor(on, error) {
+	constructor(options) {
 		this.#emitter = new Emitter({
-			...on === void 0 ? {} : { on },
-			...error === void 0 ? {} : { error }
+			...options?.on === void 0 ? {} : { on: options.on },
+			...options?.error === void 0 ? {} : { error: options.error }
 		});
 	}
 	get emitter() {
@@ -2151,8 +2501,8 @@ var ScopeManager = class {
 	}
 	remove(ids) {
 		if (isArray(ids)) {
-			let removed = false;
-			for (const id of ids) if (this.#delete(id)) removed = true;
+			let removed = true;
+			for (const id of ids) if (!this.#delete(id)) removed = false;
 			return removed;
 		}
 		return this.#delete(ids);
@@ -2170,26 +2520,27 @@ var ScopeManager = class {
 //#endregion
 //#region src/core/ThinkSplitter.ts
 /**
-* 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 the answer alone and surfaces the reasoning as
+* {@link import('./types.js').ProviderResult.thinking}. A tag split across deltas is held until
+* disambiguated, `flush()` settles the stream end, and one splitter serves one stream.
 *
 * @remarks
 * - **Cross-chunk tags.** A tag may arrive split across wire deltas (`'<thi'` then
-*   `'nk>'`): any suffix of the pending text that is a strict PREFIX of a tag being
-*   scanned for is HELD BACK (neither surfaced nor routed) until the next delta — or
+*   `'nk>'`): any suffix of the pending text that is a strict prefix of a tag being
+*   scanned for is held back (neither surfaced nor routed) until the next delta — or
 *   `flush()` — disambiguates it. A held tag prefix that never completes is real
 *   content; a held close-tag prefix inside a span is thinking.
-* - **The IMPLICIT leading open (the qwen3-template shape).** Some chat templates
-*   PRE-SEED `<think>` into the prompt scaffold, so the wire stream begins
-*   MID-REASONING and only a bare `</think>` appears. Before any tag event, a bare
-*   close therefore RECLASSIFIES everything surfaced so far (plus the pre-close
+* - **The implicit leading open (the qwen3-template shape).** Some chat templates
+*   pre-seed `<think>` into the prompt scaffold, so the wire stream begins
+*   mid-reasoning and only a bare `</think>` appears. Before any tag event, a bare
+*   close therefore reclassifies everything surfaced so far (plus the pre-close
 *   pending) as thinking — `content` is corrected retroactively (the already-returned
 *   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.
+*   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.
@@ -2288,58 +2639,80 @@ var ThinkSplitter = class {
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create a conversation — a {@link ConversationInterface} grouping messages above a flat
-* message store it OWNS DIRECTLY, with compaction into summarized sections, a regenerated
+* 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
+* 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
+* @example Conversations & compaction
 * ```ts
-* import type { ProviderInterface } from '@src/core'
-* import { createConversation } from '@src/core'
+* import { createConversation } from '@orkestrel/agent'
+* import type { ProviderInterface } from '@orkestrel/agent'
 *
 * declare const provider: ProviderInterface // any concrete implementation supplied by the host app
+* // The summarizer seam — built from the provider by the runtime; core stays provider-agnostic.
+* // Append the instruction as the FINAL user turn: a chat model emits nothing when the prompt
+* // ends on an assistant turn, so a leading-system instruction is unreliable.
 * const conversation = createConversation({
-* 	// Append the instruction as the FINAL user turn — a chat model emits nothing when the
-* 	// prompt ends on an assistant turn, so a leading-system instruction is unreliable.
 * 	summarize: async (messages) =>
-* 		(await provider.generate([...messages, { id: 's', role: 'user', content: 'Summarize the conversation so far concisely.' }], AbortSignal.timeout(30_000))).content,
+* 		(
+* 			await provider.generate(
+* 				[
+* 					...messages,
+* 					{ id: 's', role: 'user', content: 'Summarize the conversation so far concisely.' },
+* 				],
+* 				AbortSignal.timeout(30_000),
+* 			)
+* 		).content,
+* 	keep: 2, // retain the two most recent turns verbatim on each compaction
 * })
-* conversation.add({ role: 'user', content: 'Hello' })
-* await conversation.compact() // folds the live tail into a summarized section
+* conversation.add([
+* 	{ role: 'user', content: 'My name is Ada.' },
+* 	{ role: 'assistant', content: 'Nice to meet you, Ada.' },
+* 	{ role: 'user', content: 'What did I say my name was?' },
+* ])
+*
+* const section = await conversation.compact() // folds the older turns → a summarized section
+* conversation.view() // [<section summary message>, ...the retained recent tail] — the model input
+* conversation.summary // the regenerated rollup (a summary-of-summaries over all sections)
+* conversation.search('ada') // case-insensitive across sections' originals + the live tail
+* section && conversation.rehydrate(section.id) // the section's full original messages (a pure read)
 * ```
 */
 function createConversation(options) {
 	return new Conversation(options);
 }
 /**
-* Create 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.
+* Creates a conversation registry — a {@link ConversationManagerInterface} holding
+* {@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 context
+* renders. `add` auto-activates the first conversation and flows the registry's default
+* `summarize` / `keep` into every conversation it creates.
 *
 * @remarks
 * Starts empty; `add(input?)` mints a {@link ConversationInterface} (its `id` from the input
 * or a random UUID), flowing the manager's default `summarize` / `keep` in unless the input
 * overrides them, and stores it (an already-present `id` overwrites — last write wins) — and
-* AUTO-ACTIVATES the FIRST one (a registry with conversations always has one `active`); a later
+* 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
-* (each conversation owns its own observable `emitter`). A conversation created with NEITHER a
+* `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`).
 *
 * @param options - Optional default `summarize` / `keep` (see {@link ConversationManagerOptions})
@@ -2347,7 +2720,7 @@ function createConversation(options) {
 *
 * @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
@@ -2358,9 +2731,9 @@ function createConversationManager(options) {
 	return new ConversationManager(options);
 }
 /**
-* 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} /
+* id, the default backing for the durable {@link ConversationManagerInterface.open} /
 * {@link ConversationManagerInterface.save} seam. The exact twin of
 * {@link import('@orkestrel/workspace').createMemoryWorkspaceStore}.
 *
@@ -2368,19 +2741,19 @@ function createConversationManager(options) {
 * A plain `Map` (the snapshot is already pure JSON, so no encoding is needed for the memory tier),
 * the structural twin of {@link import('@orkestrel/workspace').createMemoryWorkspaceStore}.
 * `get` / `set` / `delete` are async (the
-* same shape a durable backend fits); UNLIKE a session store there is NO idle-TTL / eviction — a
+* same shape a durable backend fits); unlike a session store there is no idle-TTL / eviction — a
 * persisted conversation lives until an explicit `delete`. Its driver-pluggable twin is
 * {@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
+* 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 })
@@ -2393,30 +2766,32 @@ function createMemoryConversationStore() {
 	return new MemoryConversationStore();
 }
 /**
-* Create a {@link DatabaseConversationStore} over any {@link DriverInterface} — the durable,
-* driver-pluggable backing for the conversation persistence seam, the opt-in twin of
+* Creates a {@link DatabaseConversationStore} over any {@link DriverInterface}, defaulting to
+* `createMemoryDriver()` — the durable, driver-pluggable backing for the conversation persistence
+* seam, holding each snapshot as one opaque JSON column and standing as the opt-in twin of
 * {@link createMemoryConversationStore}. The exact twin of
 * {@link import('@orkestrel/workspace').createDatabaseWorkspaceStore}.
 *
 * @remarks
 * Builds a one-table database (`conversations`, keyed by `id`) over the supplied driver, the snapshot
-* held as ONE OPAQUE JSON COLUMN — the column map is `{ id; snapshot }` where `snapshot` is a
+* held as one opaque JSON column — the column map is `{ id; snapshot }` where `snapshot` is a
 * `rawShape` (a JSON blob), exactly as
 * {@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 createMemoryDriver}, so the store ALSO works in memory out of the box; pass a server
+* 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('./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
-* {@link ConversationStoreInterface} WITHOUT touching the manager or the conversation.
+* {@link ConversationStoreInterface} without touching the manager or the conversation.
 *
 * @param driver - The storage backend the snapshots persist to (defaults to {@link createMemoryDriver})
 * @returns A {@link ConversationStoreInterface} over the driver
 *
 * @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 })
@@ -2436,7 +2811,7 @@ function createDatabaseConversationStore(driver = createMemoryDriver()) {
 	}).table("conversations"));
 }
 /**
-* 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
@@ -2450,7 +2825,7 @@ function createDatabaseConversationStore(driver = createMemoryDriver()) {
 *
 * @example
 * ```ts
-* import { createInstruction } from '@src/core'
+* import { createInstruction } from '@orkestrel/agent'
 *
 * const instruction = createInstruction({ name: 'tone', content: 'Be concise.', priority: 5 })
 * ```
@@ -2459,28 +2834,28 @@ function createInstruction(input) {
 	return new Instruction(input);
 }
 /**
-* 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 })
@@ -2490,22 +2865,22 @@ function createInstructionManager(options) {
 	return new InstructionManager(options);
 }
 /**
-* 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), `[]` ⇒
-* NONE pass, a non-empty list ⇒ only the listed keys pass. `narrow(config)` composes a
-* tighter child by set-INTERSECTION (an `undefined` side imposing no constraint). Stored
+* Each list is three-way: `undefined` ⇒ no constraint on that category (all pass), `[]` ⇒
+* none pass, a non-empty list ⇒ only the listed keys pass. `narrow(config)` composes a
+* 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
@@ -2515,45 +2890,47 @@ function createScope(input) {
 	return new Scope(input);
 }
 /**
-* 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'] })
 * ```
 */
 function createScopeManager(options) {
-	return new ScopeManager(options?.on, options?.error);
+	return new ScopeManager(options);
 }
 /**
-* Create 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.
+* Creates a richer turn context — an {@link AgentContextInterface} assembling a provider request
+* from the optional system prompt, the instruction registry, the workspace registry (the only
+* document channel), the conversation registry that is its `messages` source, the tool registry,
+* and the active scope, which `build()` folds into the next turn's input.
 *
 * @remarks
 * `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
+* 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
-* instructions — PLUS the ACTIVE workspace's scope-filtered text files (fenced) — into ONE leading
+* 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`
@@ -2562,7 +2939,7 @@ function createScopeManager(options) {
 *
 * @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.' })
@@ -2574,19 +2951,19 @@ function createAgentContext(options) {
 	return new AgentContext(options);
 }
 /**
-* 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`.
 *
 * @remarks
-* One private loop drives the turn; `generate` DRAINS the same stream `stream`
+* 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()`)
-* commits a PARTIAL result (the stream's `result` RESOLVES on a cancel, rejects only
+* `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).
 *
@@ -2597,8 +2974,9 @@ function createAgentContext(options) {
 *
 * @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, {
@@ -2609,7 +2987,7 @@ function createAgentContext(options) {
 *
 * 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 }
 * ```
@@ -2618,25 +2996,26 @@ function createAgent(provider, options) {
 	return new Agent(provider, options);
 }
 /**
-* Create 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}.
+* Creates a fresh 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 clean content alone and surfaces the accumulated
+* reasoning as {@link import('./types.js').ProviderResult.thinking}. One splitter serves one
+* stream.
 *
 * @remarks
 * Feed each raw wire delta through `split(delta)` (it returns the clean content to
 * surface — possibly `''` mid-think) and settle the stream end with `flush()` (a held
-* 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
+* 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.')
@@ -2648,26 +3027,55 @@ function createThinkSplitter() {
 	return new ThinkSplitter();
 }
 /**
-* Create a policy gate — an {@link AuthorityInterface} the agent loop consults before
+* 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
+* }
+* ```
+*/
+function createChannel() {
+	return new Channel();
+}
+/**
+* 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.
 *
 * @remarks
-* `rules` are evaluated in order — the FIRST whose `match` is true decides (a matched
-* rule ALLOWS unless its `allowed` is explicitly `false`). When no rule matches, the
+* `rules` are evaluated in order — the first whose `match` is true decides (a matched
+* rule allows unless its `allowed` is explicitly `false`). When no rule matches, the
 * `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
+* (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` 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({
@@ -2680,16 +3088,17 @@ function createAuthority(options) {
 	return new Authority(options);
 }
 /**
-* 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.
@@ -2699,8 +3108,8 @@ function createAuthority(options) {
 *
 * @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
@@ -2715,79 +3124,80 @@ function createAgentRegistry(options) {
 	return new AgentRegistry(options);
 }
 /**
-* Create a durable, bounded-concurrency agent-job queue — a {@link QueueInterface} over
-* serializable {@link AgentJobInput}s that COMPOSES `createQueue`: each job is rehydrated
+* 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.
 *
 * @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
+* - **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?' }] })
 * ```
 */
 function createAgentQueue(options) {
-	const { registry, allowPartial = false, concurrency, retries, timeout, store } = options;
+	const { registry, partial = false, concurrency, retries, timeout, store } = options;
 	return createQueue({
 		...concurrency === void 0 ? {} : { concurrency },
 		...retries === void 0 ? {} : { retries },
 		...timeout === void 0 ? {} : { timeout },
 		...store === void 0 ? {} : { store },
-		handler: handleAgentQueueJob.bind(void 0, registry, allowPartial)
+		handler: handleAgentQueueJob.bind(void 0, registry, partial)
 	});
 }
 /**
-* Create 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)`.
+* 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 also carries
+* sub-agent fan-out: a parent job's handler can `controller.spawn(childJob)`.
 *
 * @remarks
 * - **Composes the substrate (no new engine).** Bounded `concurrency`, `retries`, the
 *   per-attempt `timeout`, ordered results, and fail-fast are all the backing Runner's;
 *   the handler adds only rehydration + the partial policy.
 * - **Sub-agent fan-out.** Each unit's handler receives a `ControllerInterface` whose
-*   `spawn(childJob)` launches a CHILD agent job through the same bounded queue (the
+*   `spawn(childJob)` launches a child agent job through the same bounded queue (the
 *   child's result joins the run after the declared units, in spawn order). On a bounded
-*   runner, FAN OUT and return — do NOT inline-`await` a spawn from within the handler (a
+*   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 })
@@ -2798,15 +3208,15 @@ function createAgentQueue(options) {
 * ```
 */
 function createAgentRunner(options) {
-	const { registry, allowPartial = false, concurrency, retries, timeout } = options;
+	const { registry, partial = false, concurrency, retries, timeout } = options;
 	return createRunner({
 		...concurrency === void 0 ? {} : { concurrency },
 		...retries === void 0 ? {} : { retries },
 		...timeout === void 0 ? {} : { timeout },
-		handler: handleAgentRunnerJob.bind(void 0, registry, allowPartial)
+		handler: handleAgentRunnerJob.bind(void 0, registry, partial)
 	});
 }
 //#endregion
-export { Agent, AgentContext, AgentError, AgentJobError, AgentRegistry, Authority, CONVERSATION_RECAP_PREFIX, Channel, Conversation, ConversationError, ConversationManager, DEFAULT_AGENT_LIMIT, DEFAULT_AUTHORITY_ZONE, DEFAULT_CONVERSATION_KEEP, DatabaseConversationStore, IMAGE_TOKEN_ESTIMATE, Instruction, InstructionManager, MESSAGE_TOKEN_OVERHEAD, MemoryConversationStore, ProviderAbortError, Scope, ScopeManager, THINK_CLOSE, THINK_OPEN, ThinkSplitter, WORKSPACE_SECTION_HEADER, agentResultToJSON, createAgent, createAgentContext, createAgentQueue, createAgentRegistry, createAgentRunner, createAuthority, createConversation, createConversationManager, createDatabaseConversationStore, createInstruction, createInstructionManager, createMemoryConversationStore, createScope, createScopeManager, createThinkSplitter, estimateMessages, estimateTokens, fencedFile, filterAllowList, handleAgentQueueJob, handleAgentRunnerJob, isAgentError, isAgentJobError, isConversationError, isConversationSnapshot, isMessage, isProviderAbortError, isSection, sanitizeToken, sanitizeUsage, settleAgentJob };
+export { Agent, AgentContext, AgentError, AgentJobError, AgentRegistry, Authority, CONVERSATION_RECAP_PREFIX, Channel, Conversation, ConversationError, ConversationManager, DEFAULT_AGENT_LIMIT, DEFAULT_AUTHORITY_ZONE, DEFAULT_CONVERSATION_KEEP, DatabaseConversationStore, IMAGE_TOKEN_ESTIMATE, Instruction, InstructionManager, MESSAGE_TOKEN_OVERHEAD, MemoryConversationStore, ProviderAbortError, Scope, ScopeManager, THINK_CLOSE, THINK_OPEN, ThinkSplitter, WORKSPACE_SECTION_HEADER, agentResultToJSON, assembleResult, attachImages, attachUserImages, buildRecapMessage, buildSummaryMessage, collectImageData, createAgent, createAgentContext, createAgentQueue, createAgentRegistry, createAgentRunner, createAuthority, createChannel, createConversation, createConversationManager, createDatabaseConversationStore, createInstruction, createInstructionManager, createMemoryConversationStore, createScope, createScopeManager, createThinkSplitter, denyCall, estimateMessages, estimateTokens, filterAllowList, handleAgentQueueJob, handleAgentRunnerJob, intersectKeys, isAgentError, isAgentJobError, isConversationError, isConversationSnapshot, isMessage, isProviderAbortError, isSection, joinThinking, renderFencedFile, renderSection, resolveClose, resolveItem, resolveOpen, sanitizeToken, sanitizeUsage, settleAgentJob, sumUsage };
 
 //# sourceMappingURL=index.js.map