@animalabs/agent-framework 0.29.0 → 0.31.0

package/dist/src/framework.d.ts

@@ -1,14 +1,15 @@
 import { type PresentationSnapshot } from "./tool-presentation.js";
 import { JsStore } from '@animalabs/chronicle';
-import type { Membrane, NormalizedRequest } from '@animalabs/membrane';
+import type { Membrane, ContentBlock, NormalizedRequest } from '@animalabs/membrane';
 import { type RetrySettings } from '@animalabs/membrane/retry';
 import { ContextManager } from '@animalabs/context-manager';
-import type { TokenBudget } from '@animalabs/context-manager';
+import type { MessageMetadata, TokenBudget } from '@animalabs/context-manager';
 import type { FrameworkConfig, ErrorPolicy, ErrorAction, TraceEventListener, InferenceLogQuery, InferenceLogQueryResult, InferenceLogEntryWithId, ProcessLogQuery, ProcessLogQueryResult, ProcessLogEntryWithId, ProcessEvent, ToolCall, ToolResult, AgentConfig, InferenceRequest, Module, ContextMaintenanceSnapshot, AgentRuntimeSettingsPatch, AgentRuntimeSettingsSnapshot, SameRoundThinkTextPolicy } from './types/index.js';
 import { Agent, type RenderStats } from './agent.js';
 import { type ToolClass, type ToolClassSource } from './mcpl/tool-classes.js';
 import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { ConversationRouter } from './mcpl/conversation-router.js';
+import type { ActivationRecord, AgentEndReason, AgentRecord, AgentSpec, EndOutcome, HeldMail, PolicyEpoch } from './dendrite/index.js';
 /**
  * The framework's own tools that belong to the host's built-in toolset
  * ("settings", host-presentation.ts) rather than the tool list: the ones an
@@ -17,6 +18,7 @@ import { ConversationRouter } from './mcpl/conversation-router.js';
  */
 export declare const BUILTIN_TOOLSET_TOOLS: ReadonlySet<string>;
 import type { SessionUsageSnapshot } from './usage/types.js';
+import type { ContextStrategy } from '@animalabs/context-manager';
 import { type DiscordAwarenessView, type DiscordAwarenessCancelReceipt, type DiscordAwarenessMarks, type DiscordAwarenessRetractReceipt } from './recovery/discord-awareness-outbox.js';
 import { type SurgeryMarkerReceipt, type SurgeryMarksPreview, type OperatorLogEntry, type OperatorLogInput, type OperatorRequester } from './operator-log.js';
 /**
@@ -91,15 +93,16 @@ export interface HostModeStatus {
     activeTurnAgents: string[];
     /** Wakes that own provider admission while waiting for an in-flight
      * auxiliary call — no turn token yet, but a turn is one settle away. The
-     * admission continuation rechecks quiesce and requeues them; `drained`
-     * is false until it has. A parked continuation of a turn is counted here
-     * and, as a turn alive, in `activeTurns` and `activeTurnAgents`. */
+     * admission continuation rechecks quiesce and provider holds, and requeues
+     * a wake either keeps from starting; `drained` is false until it has. A
+     * parked continuation of a turn is counted here and, as a turn alive, in
+     * `activeTurns` and `activeTurnAgents`. */
     parkedAdmissions: number;
     /** Inference requests waiting to start: queued (parked by the quiesce wake
      * gate while quiesced, or, while serving, until the scheduler's next pass
      * takes them), in a scheduler pass's hands, or held by a provider hold (an
      * acceleration or host hold, or a provider's stated wait). There, a start
-     * that carries a turn on counts as the wakes merged into it. A start parked
+     * merged from several requests counts as those it took in. A start parked
      * on provider admission behind an auxiliary call counts once in
      * `parkedAdmissions` instead, however many wakes are merged into it.
      * Continuations of a turn (budget restart, tool results) and a held turn's
@@ -191,9 +194,15 @@ interface InferenceToolSnapshot {
  *   schedule, jittered, 10 s doubling to 5 min (by default 13 tries, where
  *   membrane's settings have 7: about 30 min).
  * - rate limited (429): the base schedule with at least 5 tries.
- * - any other retryable failure, a stream deadline on a sent request
- *   included (membrane leaves those to its caller): the base schedule (by
- *   default 3 tries, 1 s then 2 s).
+ * - a deadline expiry, which membrane leaves to its caller: a progress
+ *   bound's cut (FrameworkConfig.inferenceBounds), the adapter's own
+ *   watchdogs, the SDK's request timeout or a runtime's fetch timeout. The
+ *   deadline schedule: by default 2 tries, 1 s apart, so one fresh call. For
+ *   one, the framework's `attempt` counts that call's consecutive expiries,
+ *   not the turn's other failures, so each call a deadline cuts gets its
+ *   fresh call. Settings with no deadline schedule give it their base one.
+ * - any other retryable failure: the base schedule (by default 3 tries, 1 s
+ *   then 2 s).
  * A provider's stated wait (`retryAfterMs`) is waited when it is longer than
  * the backoff, up to the schedule's ceiling, which by default is at least the
  * framework's own cap (PROVIDER_ACCELERATION_MAX_COOLDOWN_MS, ten minutes);
@@ -211,6 +220,92 @@ export declare class DefaultErrorPolicy implements ErrorPolicy {
     constructor(settings?: RetrySettings);
     onInferenceError(error: Error, _agentName: string, attempt: number): ErrorAction;
 }
+/**
+ * For tests only: `framework`'s abandon takes `ms` as its grace in place of
+ * {@link ABANDON_GRACE_MS}. Set it only where the test holds every turn the
+ * abandon reaches past the grace, so no turn can end within it and a short
+ * grace only brings the abandon's report sooner.
+ */
+export declare function setAbandonGraceForTests(framework: AgentFramework, ms: number): void;
+/**
+ * The admission record on a stored message: it was held from the residents
+ * by a policy epoch (`metadata.tuneOut = { epochId }`). ONE predicate for
+ * "held from the resident", read by the compiled-view filter and by the
+ * mid-turn injection alike (#232 H1), so the window and the wire agree.
+ */
+export declare const heldFromResidents: (metadata: Record<string, unknown> | undefined) => boolean;
+/** Options for {@link AgentFramework.deriveAgent}. */
+export interface DeriveAgentOptions {
+    /** The new agent's name. Single-use within this framework's lifetime. */
+    name: string;
+    /** The live agent whose context and configuration are inherited. */
+    from: string;
+    /** How context is inherited. Default `'shared'`. */
+    mode?: 'shared' | 'copy';
+    /** `'shared'` only. Default `'reuse'`. */
+    solve?: 'reuse' | 'fresh';
+    /**
+     * `'shared'` only. Also inherit the parent's refusal ledger (what it
+     * declined to compress). Default false; set for a fork that stands in
+     * for the parent's attention. Recorded as `inherit.refusals`.
+     */
+    inheritRefusals?: boolean;
+    /**
+     * A fresh strategy instance for the child. Strategy instances hold state
+     * and are never shared; to reuse the parent's rendering it must be the
+     * same class with compatible configuration. Default: passthrough.
+     */
+    strategy?: ContextStrategy;
+    /** Identity and settings overrides. Everything not named is the parent's. */
+    config?: Partial<Omit<AgentConfig, 'name' | 'strategy'>>;
+    /**
+     * The parent's tool round in flight, if any. While a tool call runs, the
+     * assistant turn that made it is not in the parent's store yet. By
+     * default the child's branch gets that turn verbatim (as its own, like
+     * the rest of the inheritance) followed by a tool-result message: results
+     * the parent has already received as they are; the call that derived the
+     * child with `madeBy.result`, or a note saying it did; and any other call
+     * still running with a note that its result was not available. So a fork
+     * sees the call that made it and never meets a dangling `tool_use`.
+     * `madeBy` defaults to the only open call when there is exactly one.
+     * `include: false` leaves the round out, and the child starts from the
+     * last stored message before it.
+     */
+    pendingRound?: {
+        include?: boolean;
+        madeBy?: {
+            toolUseId: string;
+            result: string;
+        };
+        /** Results, from the child's side, for other calls still open, by tool-use id. */
+        results?: Record<string, string>;
+    };
+    /** Ordinary messages appended to the child before it runs. */
+    framing?: Array<{
+        participant: string;
+        content: ContentBlock[];
+        metadata?: MessageMetadata;
+    }>;
+    /** Who spawned it. Default: `from`. */
+    spawnedBy?: string;
+    /** Where its completion returns. */
+    resultTo?: import('./dendrite/index.js').ResultRoute;
+    /** What happens to it when its spawner ends. Default `'orphan'`. */
+    onParentEnd?: import('./dendrite/index.js').ParentEndPolicy;
+    deadlineMs?: number;
+    idleTimeoutMs?: number;
+    maxTurns?: number;
+    /** Preset label for discovery. Default `'task-fork'`. */
+    kind?: string;
+    metadata?: Record<string, unknown>;
+}
+/** Rejection delivered to the caller awaiting a bounded run that was ended from outside. */
+export declare class AgentStoppedError extends Error {
+    readonly agentName: string;
+    readonly reason: AgentEndReason;
+    readonly by?: string | undefined;
+    constructor(agentName: string, reason: AgentEndReason, by?: string | undefined, detail?: string);
+}
 export interface ReinitAlertText {
     opening: string;
     message: string;
@@ -333,9 +428,9 @@ export declare class AgentFramework {
     private store;
     private ownsStore;
     private stopPromise;
-    private stopCompleted;
+    private stopState;
+    private closedStopFailure;
     private ownedStoreClosed;
-    private ownedStoreManagersClosed;
     /** Whether the latest stop() got through its teardown with nothing failed:
      * every step and every wait up to and including the one on awareness
      * drains, whatever failed after that, in the storage work that finishes
@@ -351,8 +446,8 @@ export declare class AgentFramework {
      * promise: a stream it cancelled or an event loop still in a call; and a
      * stream whose cancel threw, which stop() doesn't wait for. A later
      * stop() waits for each again, beside what it finds, whatever has happened
-     * since to the entry it was found under (a run's end removes its stream's,
-     * a start() replaces the loop), so neither a budget nor a cancel that
+     * since to the entry it was found under (a run's end removes its stream's),
+     * so neither a budget nor a cancel that
      * threw lets the store close under work still running. Each leaves once it
      * settles. */
     private readonly leftRunning;
@@ -389,6 +484,13 @@ export declare class AgentFramework {
     private quiesceReason?;
     private quiescedAt?;
     private traceListeners;
+    /** Traces emitted before start() — registry restore, interrupted work,
+     *  resumed epochs — replayed to listeners that attach afterwards, since a
+     *  host attaches its sinks after create() returns. Dropped at start().
+     *  It keeps the first 1,000, the start of the stream, and counts the rest
+     *  (earlyTracesDropped), which a replay ends by naming. */
+    private earlyTraces;
+    private earlyTracesDropped;
     private syncIntervalMs;
     private syncTimer;
     private maintenanceIntervalMs;
@@ -411,6 +513,9 @@ export declare class AgentFramework {
     private providerAccelerationLastRecovery;
     private providerAccelerationDefaultCooldownMs;
     private providerAccelerationJitterMs;
+    private inferenceBounds;
+    private readonly deadlineCuts;
+    private readonly freshCallsCut;
     private providerHoldHook;
     /** Provider waits (stated retry-after) per (agent, model), kept across restarts. */
     private providerWaits;
@@ -418,8 +523,6 @@ export declare class AgentFramework {
     private retryWaitWakers;
     private waitingTraceEveryMs;
     private providerAdmissionClosed;
-    /** Invalidates framework turns still assembling when stop begins. */
-    private lifecycleGeneration;
     /** Last time we reported stale (busy-requeued) inference requests, per agent. */
     private staleWarnAt;
     /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
@@ -442,8 +545,9 @@ export declare class AgentFramework {
     private midTurnInputSignals;
     /** Last outbound locus announced to each agent as a durable `[routing]`
      *  window message. Announce-on-change only: steady state emits nothing
-     *  (KV-safe, no per-turn chatter). In-memory — after a process restart the
-     *  first turn's locus is announced once to re-establish the baseline. */
+     *  (KV-safe, no per-turn chatter). Kept in the store as well
+     *  (rememberAnnouncedLocus), so a restart compares with what the agent was
+     *  last told rather than with nothing. */
     private lastAnnouncedLocus;
     /** Every resident's held drafts: plain speech that was suppressed, bounced
      *  or left without a destination, never published except by their
@@ -527,6 +631,13 @@ export declare class AgentFramework {
     private usedEphemeralAgentNames;
     /** One-shot generation tickets minted by createEphemeralAgent. */
     private ephemeralCandidates;
+    /**
+     * Derived agent → the agent whose tool presentation it shows. A derived
+     * agent that inherits its parent's tools must advertise the identical
+     * tool block (it is the front of the shared request prefix), including
+     * the parent's resident-edited visibility and descriptions.
+     */
+    private toolSurfaceOwners;
     /** Every agent createEphemeralAgent made, for as long as the object lives:
      *  its usage counts in the usage record's one shared ephemeral entry. Kept
      *  by the object, not the run's record (ephemeralRuns), which its cleanup
@@ -543,6 +654,7 @@ export declare class AgentFramework {
     private turnRearmMs;
     private turnRearms;
     private exhaustingRearms;
+    private rearmDeadlineCuts;
     private statedWaitRuns;
     /** N consecutive failed inferences ⇒ the agent is treated as hard-down and
      *  escalated loudly to stderr. */
@@ -595,8 +707,25 @@ export declare class AgentFramework {
     private subconsciousStrategy;
     /** Its config (speak_in_channel gate, voice block provenance). */
     private subconsciousConfig;
-    /** Tune-out coordinator (issue #77); non-null iff subconscious + channels. */
+    /** Tune-out coordinator (issue #77); non-null iff a reader is configured + channels. */
     private tuneOutCoordinator;
+    /** Residents are offered `tune_out` (a reader is configured, or `tuneOut.enabled`). */
+    private tuneOutOffered;
+    /**
+     * The reply anchor a coalesced delivery would set, parked until the
+     * acceptance is acknowledged to the server (handleCoalescedIncoming): an
+     * acceptance whose commit fails after its delivery moves no anchor, and the
+     * retry the receipt answers, which delivers nothing again, commits the one
+     * its first attempt parked. Keyed by server and event id; bounded.
+     */
+    private parkedAnchors;
+    /** `tuneOut.announce`: the excepted channel hears the all-except scope open and close. */
+    private tuneOutAnnounce;
+    /** `speech.locus`: where prose goes when nothing names a destination (see FrameworkConfig). */
+    private speechLocus;
+    /** `subconscious.reader: 'forks'`: the reader is a succession of forks (Dendrite). */
+    private readerForks;
+    private readerForkCounter;
     /** Agents an abandon could not cancel (token held, no stream) — surfaced
      *  in HostModeStatus until the next quiesce/resume. */
     private lastUnabandonable;
@@ -614,6 +743,24 @@ export declare class AgentFramework {
     /** True once the cap has been met in the current run, so its line is
      *  logged once a run, whatever began the run. */
     private deferredWritesCapLogged;
+    /** The agent registry and its ended log, as recovery files beside the store
+     *  (nissa's #546 finding 3): Chronicle state follows the store's branch, and
+     *  an undo or an operator's surgery must not erase a result held for
+     *  delivery or the record of work that ran. The file wins where it exists;
+     *  the branch-local state is read only for stores that predate it. */
+    private agentRegistryPath;
+    private agentRegistryEndedPath;
+    /** The ended log as the recovery file keeps it: the newest records, bounded. */
+    private endedRecovery;
+    /** The branch-local ended log by name (its newest entry for each), and how far it is indexed (findEndedAgentRecord). */
+    private readonly endedLogIndex;
+    /** The ended log's entries by the namespace their context holds (the latest for each). */
+    private readonly endedLogNamespaceIndex;
+    /** Namespaces this process opened for an ephemeral agent's context, by owner: candidates not yet registered included. */
+    private readonly namespaceOwners;
+    private endedLogIndexed;
+    /** The last indexed entry's mark, so a log that changed under the index is seen. */
+    private endedLogTail;
     /** Branch-independent recovery files (see FrameworkConfig.hostModePath /
      *  deferredWritesPath). Undefined → branch-local slot fallback. */
     private hostModePath;
@@ -743,12 +890,27 @@ export declare class AgentFramework {
     private coalescingSnapshotDirty;
     private coalescingRecentReceipts;
     /**
-     * Agents that read the residents' shared un-namespaced message slot: every
-     * ordinary resident (their context managers are not isolated) and the
-     * subconscious (isolated, but merging that slot read-only). A message in
-     * that slot is unread only if NONE of them has compiled past it. Forks and
-     * ephemeral agents have isolated slots and are their own only readers.
-     */
+     * Dendrite agent registry — every agent this framework runs, with its
+     * roles, lifetime and relationships. `agents` stays the map of live Agent
+     * OBJECTS (the generation identity streams are checked against); the
+     * registry is what says what each of them is for. Selection sites read
+     * roles from here instead of excluding kinds by hand.
+     */
+    private readonly registry;
+    /** Tell the first adoption candidate when task work is orphaned (config.dendrite.announceOrphans). */
+    private announceOrphans;
+    /**
+     * After this many derivations of one kind from one agent, that agent hears
+     * a count line every so many instead of a line per fork
+     * (config.dendrite.collapseDerivationNoticesAfter; 0 = never collapse).
+     */
+    private collapseDerivationNoticesAfter;
+    /** The host's say over each derivation, ephemeral spawn and resume (config.dendrite.beforeDerive). */
+    private beforeDerive?;
+    /** What a source is told of a derivation (config.dendrite.derivationNotice); absent, the default line. */
+    private derivationNoticeHook?;
+    /** Per source agent, per kind: how many derivations, since when, and at which count the last note went. */
+    private derivationTallies;
     private readonly sharedSlotAgents;
     /** The batched-wake lines already written (placeWakeLines), so every agent a
      *  wake was for, and every later start of it, writes each at most once. */
@@ -757,6 +919,7 @@ export declare class AgentFramework {
      *  in the round counted by their share of the bound: such a round is
      *  stored by its share whether or not it fits (buildStoredToolResultContent). */
     private readonly toolRoundsByShare;
+    /** Group commit: one fsync per event-loop turn, shared by every waiter. */
     /** The windows of forks and runs deregistered while the host was quiesced,
      *  by agent name (releaseWindowNowOrAfterResume); resume() releases them
      *  (runReleasesAfterResume), or stop() passes on what they left, unread or
@@ -765,6 +928,7 @@ export declare class AgentFramework {
     private readonly releasesAfterResume;
     private readonly managerReleases;
     private readonly releasedByCleanup;
+    private readonly resumesPending;
     private readonly openManagers;
     private readonly openManagerRefs;
     private readonly storeSees;
@@ -778,19 +942,13 @@ export declare class AgentFramework {
     private conversationRouter;
     /** Agent configs by name — fork agents are built from the template's config. */
     private agentConfigs;
-    /**
-     * Fork agent → its home channel. Permanent (unlike router bindings, which
-     * expire): publish/injection scoping must survive unbinding so the closure
-     * turn still lands in the right channel.
-     */
-    private conversationAgentHomes;
     /** Forks being spawned, by channel id, each until its spawn settles (see
      *  routeConversation). The promise never rejects. */
     private readonly conversationSpawns;
     /** Last idle-TTL sweep timestamp. */
     private lastConversationSweep;
     /** Forks whose TTL closure turn has been queued — disposed (removed from
-     * agents/agentConfigs/conversationAgentHomes) when their stream ends. */
+     * agents/agentConfigs and ended in the registry) when their stream ends. */
     private closingConversationAgents;
     private codeExecution;
     private scriptToolWaiters;
@@ -977,9 +1135,7 @@ export declare class AgentFramework {
      * maintenance, event loop and operator operations, so a dump shows what
      * those waits are on, and before its modules and MCPL servers stop, so a
      * stop() whose teardown hangs, fails or times out doesn't keep it listed.
-     * With none in the set, one line says no framework is running. A framework
-     * started again after a completed stop() doesn't rejoin; whether that
-     * lifecycle is supported is #315.
+     * With none in the set, one line says no framework is running.
      *
      * One listener serves the process, installed by the first create() to
      * reach the join and kept: once a process's last SIGUSR2 listener is
@@ -992,18 +1148,35 @@ export declare class AgentFramework {
     private printDiagnostics;
     /**
      * Start the event loop. A start() on a running framework does nothing.
-     * Refused, with an error, from a stop() call until that stop() settles,
-     * since that stop would wait on the lifecycle a start() begins, or tear it
-     * down under it. What a start() after a settled stop() should do is #315's
-     * question.
+     * A stop ends its instance (#315): once a stop() is admitted, start() and
+     * addModule() are refused with an error, for good. While that stop() runs,
+     * the error says the framework is stopping. Once it has settled, the error
+     * says what to do: create a new AgentFramework on the store, and after a
+     * failed stop(), call stop() again first, until one resolves. When a
+     * failed stop() left its owned store closed, so that it can't be tried
+     * again, the error carries that failure as its cause.
+     *
+     * A new instance on the store keeps what the store holds. With the
+     * heartbeat on and the same heartbeat state file (heartbeat.statePath, or
+     * its default), it keeps the heartbeat's schedule as it reads it from that
+     * file: a tick or a reminder that fell due meanwhile fires once, shortly
+     * after it starts. What an instance holds only in memory is lost with it,
+     * as on a process restart: an agent's sleep and its wake, a self-wake, the
+     * inference requests still queued (a budget restart, a heartbeat's wake, a
+     * nudge), a re-armed turn's wait and count, and the redo stack. #627 is
+     * about keeping a sleep and a self-wake across a restart. To pause and
+     * resume one framework in place, use quiesce() and resume().
      */
     start(): void;
     /**
-     * Stop the event loop. Until it settles, start() and addModule() are
-     * refused. Each step of the teardown runs whatever an earlier one did: one
-     * that throws, such as a host stream's cancel(), fails the stop() once the
-     * rest has run. When a step or a wait up to and including
-     * the wait on awareness drains fails or times out, storage stays open and
+     * Stop the event loop, and with it this framework, for good: once a stop()
+     * is admitted, start() and addModule() are refused, as start() says. A
+     * stop() whose budget is refused, which it rejects with a RangeError, is
+     * not admitted and changes nothing. Each step of the teardown runs
+     * whatever an earlier one did: one that throws, such as a host stream's
+     * cancel(), fails the stop() once the rest has run. When a step or a wait
+     * up to and including the wait on awareness drains fails or times out,
+     * storage stays open and
      * stop() can be called again; one that fails after it, in the storage work
      * that finishes the stop, fails the stop() without keeping storage open.
      * A timed-out wait lets teardown go on while what it waited for may still
@@ -1011,7 +1184,10 @@ export declare class AgentFramework {
      * @param teardownTimeoutMs Optional budget for each of stop()'s waits, in
      * turn: on the streams it cancels, on maintenance in flight (a pass or an
      * over-budget drain kick), on the event loop, on an operator's operations
-     * already running, on modules and MCPL together, then on Discord awareness
+     * already running, on modules and MCPL (its servers and the inference
+     * requests they made) together, where a module whose start() is still
+     * running counts until that start() has settled and its stop() returned,
+     * then on Discord awareness
      * drains, which send nothing once stop() has begun, recording the call the
      * close ended. With a budget, a stop() can take up to six of them, besides
      * the withheld-spill deadline of a guard's write still under way. Omit to
@@ -1034,9 +1210,7 @@ export declare class AgentFramework {
      *   dropped, though a write the stream already had under way can still
      *   land in the run's namespace after them.
      * - an event loop still in a call, such as a module's onProcess, finishes
-     *   that call and the rest of its iteration, and then exits. A start()
-     *   made once that stop() has failed runs its own loop beside that last
-     *   iteration.
+     *   that call and the rest of its iteration, and then exits.
      * - a later stop() waits again, within its own budget, for any stream or
      *   loop this one left running, so the store never closes under it.
      *
@@ -1049,14 +1223,7 @@ export declare class AgentFramework {
      * entries, and once it has left, its stream's late events are dropped.
      */
     stop(teardownTimeoutMs?: number | undefined): Promise<void>;
-    /** What start() and addModule() pass before either begins work of a
-     * lifecycle. A stop() still running refuses both, from the moment it
-     * claims its attempt until that attempt settles. A failed stop() has
-     * cleared its attempt, unless it closed an owned store, or the context
-     * managers it closes before that store, which are refused first. A
-     * completed stop() is cleared, and the call goes on as before;
-     * whether a lifecycle should begin after a stop() is #315's question. */
-    private resetCompletedStop;
+    private refuseOnceStopped;
     /** Register before invoking the body, so the set holds the operation for
      * its whole life: its synchronous trace callbacks can reenter stop(), and
      * that stop() must find it. Invocation stays in this stack, preserving
@@ -1155,7 +1322,10 @@ export declare class AgentFramework {
      */
     private heartbeatWakeBefore;
     /** The agents the heartbeat wakes: the residents, not conversation forks,
-     *  ephemeral runs or the subconscious, which keep windows of their own. */
+     *  ephemeral runs or the subconscious, which keep windows of their own.
+     *  Read from the registry by role, as an untargeted push's recipients are
+     *  (the heartbeat's wakes were heartbeat-mcpl's pushes): the agents whose
+     *  spec takes untargeted inbound, in registration order. */
     private heartbeatTargets;
     /**
      * The event a heartbeat wake is to the gate: a push from the server id
@@ -1245,6 +1415,7 @@ export declare class AgentFramework {
      *  inference on it. True = extended in place (held requests stay held). */
     private extendHostProviderHold;
     private holdProviderAcceleration;
+    private takeAsTransient;
     private rearmExhaustedTurn;
     /**
      * A provider's stated wait on a turn that doesn't own provider admission:
@@ -1402,10 +1573,13 @@ export declare class AgentFramework {
      * it, or, through the deprecated queue handle, without the trace.
      */
     private pushModuleEvent;
+    private dropRetiredModuleEvent;
     /**
      * Add a trace event listener for observability.
      */
-    onTrace(listener: TraceEventListener): () => void;
+    onTrace(listener: TraceEventListener, options?: {
+        replay?: boolean;
+    }): () => void;
     /**
      * Public accessor for the MCPL channel registry.
      * Null when no MCPL servers are configured.
@@ -1420,14 +1594,20 @@ export declare class AgentFramework {
     offTrace(listener: TraceEventListener): void;
     private removeTraceRegistration;
     /**
-     * Add a module at runtime. Refused, with a rejection, while a stop() is
-     * still running: a module added then would either be stopped by that stop
-     * or, once the stop has taken its list of modules to stop, stay started
-     * past it.
+     * Add a module at runtime. Refused, with a rejection, once a stop() has
+     * been admitted, before anything else is checked: while that stop() runs,
+     * a module added then would either be stopped by it or, once it has taken
+     * its list of modules to stop, stay started past it; once it has settled,
+     * the framework has stopped for good, as start() says. A stop() admitted
+     * while the module's start() runs stops the module once that start() has
+     * settled; if that start() fulfils, this rejects the same way then, with
+     * no `module:added`, and if it rejects, this rejects with its error.
      */
     addModule(module: Module): Promise<void>;
     /**
-     * Remove a module at runtime.
+     * Remove a module at runtime. A module whose start() is still running is
+     * stopped once that start() has settled; this waits for that and for its
+     * stop(), with no time limit.
      */
     removeModule(name: string): Promise<void>;
     /**
@@ -1497,7 +1677,7 @@ export declare class AgentFramework {
      * Get all available tools from all modules and MCPL servers.
      */
     getAllTools(): import('./types/index.js').ToolDefinition[];
-    /** The registered workspace module, if any (used by save_image). */
+    /** The registered workspace module, if any (used by save_recent_image). */
     private getWorkspaceModule;
     /** RFC-005 host-mediated reference fetcher (lazy; needs server configs +
      *  a read-write workspace mount without an include for storage). */
@@ -1628,15 +1808,11 @@ export declare class AgentFramework {
     private stallSkips;
     /** See WITHHELD_SPILL_DEADLINE_MS; an instance field so tests can shorten it. */
     private withheldSpillDeadlineMs;
-    /** The lifecycle generation whose stop() has let the running annotations
-     *  finish: a withheld original is then no longer written to a workspace
-     *  that is stopping, and its stub names the audit record. A start() after
-     *  that stop() has finished has a generation of its own, so the spill gate
-     *  is open again for an instance kept with a store it doesn't own and that
-     *  is still open (start() doesn't restore stopped modules or MCPL
-     *  connections, and refuses an owned store that stop() closed). A start()
-     *  made while a stop() is still running is refused. */
-    private guardSpillsClosedFor;
+    /** Set once a stop() has let the running annotations finish, and cleared
+     *  as each stop() begins: while set, a withheld original is no longer
+     *  written to a workspace that is stopping, and its stub names the audit
+     *  record. */
+    private guardSpillsClosed;
     /** A new agent's guard: its persisted setting, the tool-results spill its
      *  withheld originals are written to, and the set stop() waits on
      *  (agent-framework #277). The setting is read from framework/state's
@@ -1879,8 +2055,9 @@ export declare class AgentFramework {
      * memory-only: they land within the turn, at a tool boundary or at its
      * end, and a crash before then loses them. That window runs to the turn's
      * end for a message held there and what is queued behind it, and, on a
-     * stream that declares it can't carry injected messages (membrane's XML
-     * prefill path, from 0.6.0), for every message deferred during the turn.
+     * stream that doesn't declare it carries injected messages (membrane's XML
+     * prefill path declares it can't), for every message deferred during the
+     * turn.
      *
      * A write that fails, or a queue over the cap, which writes nothing,
      * leaves the record as it last held it, except that store only, a write
@@ -2248,11 +2425,336 @@ export declare class AgentFramework {
      * ContextManager, before the store. Until then the ContextManager stays
      * open.
      */
-    createEphemeralAgent(config: AgentConfig): Promise<{
+    createEphemeralAgent(config: AgentConfig, 
+    /**
+     * How the registry should describe this agent. Omitted: an independent
+     * fresh worker with no spawner and no result route, which is what every
+     * caller of this method got before the registry existed. Supplying a
+     * spec (see the presets in `dendrite/`) declares who spawned it, where
+     * its result goes and what it inherited, so lifecycle rules — orphan
+     * notice, reparenting, held results — apply to it.
+     */
+    spec?: Omit<AgentSpec, 'name'>): Promise<{
         agent: Agent;
         contextManager: ContextManager;
         cleanup: () => void;
     }>;
+    /**
+     * Derive a new agent from a live one: the parent's context at a
+     * checkpoint, a private continuation, and — unless overridden — the
+     * parent's whole configuration (model, thinking, cache TTL, provider
+     * params, prompt, tools). The parent keeps running.
+     *
+     * The returned agent is a bounded job, driven with
+     * `runEphemeralToCompletion` exactly like one from `createEphemeralAgent`.
+     *
+     * **Inheritance.** `mode: 'shared'` (the default) gives the child the
+     * parent's messages and fold state through shared storage: nothing is
+     * copied, the child folds with the parent's memory tree, and neither can
+     * alter what the other reads. It needs a store that supports derivation
+     * (`ContextManager.supportsDerivation`), and is refused, not silently
+     * downgraded, without one. `mode: 'copy'`
+     * is the historical mechanism — the parent's compiled context re-added as
+     * the child's own messages — and works everywhere.
+     *
+     * **Rendering.** With `solve: 'reuse'` (the default) and nothing
+     * overridden, the child's first request is the parent's request plus the
+     * child's framing: the same system prompt and tool block, the parent's
+     * turns presented as the child's own, and a cache marker on the end of
+     * the parent's request so the prefix it wrote is read back. `solve:
+     * 'fresh'` deliberately re-solves, e.g. at another budget; so does any
+     * override that changes what is rendered. Those are operating choices —
+     * the presentation changes and the provider cache misses.
+     *
+     * **Framing** is ordinary messages appended to the child before it runs:
+     * the task, and whatever tells it which stream it is. The parent's turn
+     * in flight is not in its store yet (see `getPendingAssistantRound`), so
+     * a fork made from inside a tool call starts from the message before the
+     * turn that made it.
+     *
+     * Context isolation is not process or filesystem isolation: parent and
+     * child share tools, any shell and the workspace.
+     */
+    deriveAgent(options: DeriveAgentOptions): Promise<{
+        agent: Agent;
+        contextManager: ContextManager;
+        cleanup: () => void;
+    }>;
+    private discardEphemeralCandidate;
+    /**
+     * The default wording for the call that derived a child: who it is, what
+     * kind, and how long — the fields the consent event names, so the fork
+     * never has to infer its own lifetime from context (Linn, 10-09).
+     */
+    private derivedNote;
+    /**
+     * The parent's in-flight tool round, reproduced on the child's branch so
+     * the child sees the call that made it (see `DeriveAgentOptions.pendingRound`).
+     */
+    private framePendingRound;
+    /**
+     * The assistant turn an agent has produced but not yet stored: its tool
+     * calls and any text before them, held until every tool result is in so
+     * the pair lands adjacently. A host deriving an agent from inside one of
+     * those tool calls can reproduce the turn in the child's framing.
+     */
+    getPendingAssistantRound(agentName: string): ContentBlock[] | undefined;
+    /**
+     * Bring an ended bounded job back as a new incarnation of the same
+     * identity, on the context it left: an isolated agent's own namespace, or
+     * a derived agent's own branch. Nothing is re-derived and nothing is
+     * re-seeded — the agent continues from its last stored message, which is
+     * the end of its last complete round (a round whose tool results never
+     * all arrived was never stored).
+     *
+     * Use it for a job that was stopped, failed, or was interrupted by a
+     * restart. Configuration is not persisted with an agent, so the caller
+     * supplies it again; the role mapping a derived agent used is restored
+     * from its record unless the config sets one. Relationships are kept
+     * where the other agent still exists; a job whose spawner or result
+     * recipient is gone resumes without that edge and can be reparented.
+     *
+     * External effects are not replayed and not undone: a tool the previous
+     * incarnation ran before it ended has had its effect, and a call it never
+     * received a result for may be made again by the model. Drive the result
+     * with `runEphemeralToCompletion`.
+     */
+    resumeAgent(name: string, config: Omit<AgentConfig, 'name'>): Promise<{
+        agent: Agent;
+        contextManager: ContextManager;
+        cleanup: () => void;
+    }>;
+    /**
+     * A context to read an agent's history from, without changing the live
+     * system.
+     *
+     * - A live agent: a snapshot derived from its context — at the head, or
+     *   at `atSequence` for an earlier state. The snapshot is its own branch;
+     *   the agent keeps running and is not affected by anything done to it.
+     * - An ended agent: the context it left, reopened where it lives.
+     *
+     * The returned manager uses a passthrough strategy: it shows what is
+     * stored, raw. An ended agent's context is the real one — treat it as
+     * read-only unless you mean to change what a later resume starts from.
+     */
+    inspectAgentContext(name: string, options?: {
+        atSequence?: number;
+    }): Promise<ContextManager>;
+    /** Open the context an ended agent left, wherever it lives. */
+    private reopenAgentContext;
+    /** Open a derived agent's context on a branch of its own (see deriveAgent). */
+    private deriveSharedContext;
+    /** Flat list of registered agents with their roles, lifetime and relationships. */
+    listAgents(options?: {
+        includeEnded?: boolean;
+    }): AgentRecord[];
+    /** One agent's record: the live one, else its most recent ended one. */
+    getAgentRecord(name: string): AgentRecord | null;
+    /** The agent that owns default delivery, or null before any is declared. */
+    getPrimaryAgentName(): string | null;
+    /**
+     * Activations in flight, each with the agent that owns the work. Derived
+     * from the live turn state, so it cannot disagree with what is running.
+     */
+    listActivations(): ActivationRecord[];
+    /**
+     * Policy epochs currently in force (tune-out holds), read from the
+     * coordinator's own durable state — not mirrored. An epoch is neither an
+     * agent nor a task: ending one leaves both running.
+     */
+    listPolicyEpochs(): PolicyEpoch[];
+    /**
+     * Cancel an agent's activation in flight, leaving the agent registered.
+     * For a bounded job, whose lifetime is that one run, this ends the job.
+     * Returns false when nothing was running.
+     */
+    cancelActivation(name: string, options?: {
+        by?: string;
+        reason?: string;
+    }): boolean;
+    /**
+     * End an agent: cancel its run, remove it from the framework, and settle
+     * what it spawned — attention tenants end with it; task work is orphaned,
+     * notified and offered for reparenting, and keeps running.
+     *
+     * The default-delivery owner cannot be stopped (the framework needs
+     * exactly one); cancel its activation instead. A persistent agent stopped
+     * here is declared by configuration and returns at the next boot.
+     */
+    stopAgent(name: string, options?: {
+        by?: string;
+        reason?: string;
+    }): EndOutcome;
+    /**
+     * Give an agent a new parent. Clears its orphan state; a result route
+     * whose recipient is gone follows the new parent, and the mail it already
+     * produced for the lost recipient, results and messages, is delivered to
+     * the new one.
+     */
+    reparentAgent(name: string, newParent: string, options?: {
+        by?: string;
+    }): AgentRecord;
+    /**
+     * An explicit message from one agent to another: the sender's verbatim
+     * content, in the recipient's context under the SENDER's name, with the
+     * sender's identity and incarnation and the causal chain in metadata.
+     * Never an unmarked insertion into the recipient's own voice.
+     */
+    sendAgentMessage(from: string, to: string, content: ContentBlock[], options?: {
+        causedBy?: string[];
+        wake?: boolean;
+    }): {
+        mailId: string;
+        delivered: boolean;
+    };
+    /**
+     * Return a bounded job's result along the agent's declared result route.
+     * The result is recorded durably before delivery is attempted, so it is
+     * neither lost nor delivered twice across a restart; if the recipient is
+     * gone it is held as attributed mail until the agent is reparented.
+     *
+     * May be called after the agent's run has ended — its record stays
+     * inspectable. Refused for a `tool-result` route: there the awaiting
+     * caller already holds the result and delivers it itself.
+     */
+    deliverAgentResult(from: string, content: ContentBlock[], options?: {
+        causedBy?: string[];
+    }): {
+        mailId: string;
+        delivered: boolean;
+        to: string;
+    };
+    /** Communications not yet handed to their recipient, and why. */
+    listHeldMail(filter?: {
+        to?: string;
+        from?: string;
+    }): HeldMail[];
+    /**
+     * Try to hand one held item to its recipient. True when the message is in
+     * (or queued for) the recipient's context; false when it stays held
+     * because nobody can receive it. The held copy is released by
+     * `addMessage` at the moment the message enters the store.
+     */
+    private attemptMailDelivery;
+    /**
+     * An ended orphan's result held for a recipient that is gone: its first
+     * adoption candidate is told it exists and how it arrives, since nothing
+     * else would surface it (reparentAgent delivers it).
+     */
+    private tellResultHeld;
+    /** A host-framed lifecycle fact in an agent's context. Never voiced as anyone. */
+    private lifecycleNotice;
+    /**
+     * The creation ("consent") event: names what kind of agent this is, what
+     * ends it and what happens to it when its spawner ends. A derived agent's
+     * creation is also told to the agent it was derived from (#270, Linn:
+     * "told when the body changes" as a property, not a courtesy): one
+     * host-framed line in the source's context, built from the same facts as
+     * the trace, with no wake; a host's derivationNotice can replace the line
+     * or send none. Both derivation paths announce after the
+     * fork's branch or copy exists, so a fork never inherits the notice about
+     * itself; a source that has ended is told nothing (lifecycleNotice).
+     */
+    private announceAgentCreated;
+    /** The derivation notice's text, addressed to the agent `from` the record was derived. */
+    private derivationNotice;
+    /** What a derived agent is, to the agent it was derived from: "a task-fork on your weights, …; …; …". */
+    private derivationDescription;
+    /**
+     * Remove an ended agent's live object from the framework. A bounded run
+     * is ended through its awaiting caller (whose teardown owns the
+     * name-keyed state); any other agent is torn down here.
+     */
+    private teardownEndedAgent;
+    private forgetFailureAccounting;
+    /**
+     * Everything the process holds for a live, non-ephemeral agent that has
+     * ended, released once, on every path an agent ends by — stopAgent, the
+     * idle reap of a conversation fork, an end that cascades from a parent's
+     * (nissa's #546 finding 5: a stop that skipped the window release dropped a
+     * write queued for the agent at the next flush, and a failure notice it
+     * never read reached no one). The window release delivers what the agent
+     * never read to the primary, now or after a resume, as the idle reap did.
+     */
+    private releaseAgentRuntime;
+    /**
+     * Carry out what the registry decided when an agent ended: tear down the
+     * attention tenants that end with it, and tell each orphan — and the
+     * first agent that could adopt it — what happened.
+     */
+    private settleEndedAgent;
+    /** An agent whose spawner has ended, and its first adoption candidate, are told; the trace says so. */
+    private announceOrphaned;
+    /** The registry's snapshot: the recovery file first (atomic, fsynced; it
+     *  wins at the next boot), then the branch-local state, kept for inspection
+     *  and for stores read by older code. Either write failing fails the call
+     *  that changed the registry (nissa's #546 finding 2): a change that isn't
+     *  durable isn't a success. */
+    private persistAgentRegistry;
+    /** An ended record: appended to the branch-local log, and the recovery
+     *  file rewritten with the newest records (as many as a restart reads). */
+    private appendEndedAgentRecord;
+    /**
+     * A requested change was put back in the registry's memory: the recovery
+     * files, each written before the branch-local store, are rewritten from it
+     * (the snapshot's and the ended log's), so neither keeps the change the
+     * caller was told failed. The branch-local snapshot needs no rewrite: it is
+     * the last write a change makes, so a change that failed never reached it.
+     * The branch-local ended log is append-only, so an end appended before the
+     * failure stays there. It is read at boot only where no ended recovery
+     * file exists (or the rewrite of that file failed too); the restore then
+     * drops a bounded agent it lists as ended for the reason recorded, with no
+     * restart notice to its recipient, while a persistent agent waits to be
+     * re-declared as it would anyway. A rewrite that fails is reported, the
+     * next is still made, and the caller's own error goes on.
+     */
+    private rewriteAgentRegistryAfterRollback;
+    /**
+     * An ended record past the registry's memory, from the branch-local ended
+     * log. A scan of the whole log takes tens of milliseconds at a few thousand
+     * ends, and a name nobody used (a tool call's typo) is a miss, so the log is
+     * indexed by name once, at the first lookup, and each later lookup indexes
+     * only what was appended since. A log that changed under the index (a
+     * branch switch) is indexed again: one that shrank, one whose last indexed
+     * entry is no longer the one indexed, or one whose entry no longer carries
+     * the name indexed for it.
+     */
+    private findEndedAgentRecord;
+    /**
+     * The ended log's latest record whose own context a namespace holds. A
+     * shared fork's record names its parent's namespace, where it owns only a
+     * branch, so it is indexed by name alone.
+     */
+    private findInEndedLog;
+    /** Another agent whose context a namespace holds: opened in this process, in the registry, or in the ended log. */
+    private namespaceHolder;
+    /** The ended log's recovery file, rewritten as the newest records (as many as a restart reads). */
+    private rewriteEndedRecovery;
+    /**
+     * Load the previous process's registry. Returns the bounded work it
+     * interrupted. A registry that can't be read, or that reads as anything
+     * but a version-1 registry, refuses the start and names the state (nissa's
+     * #546 finding 1, main's rule for the framework's own state): taken as
+     * empty, the results it holds for delivery and the records of the work it
+     * ran would be overwritten by this boot's first registration.
+     */
+    private restoreAgentRegistry;
+    /**
+     * Boot reconciliation, once configuration has declared its agents.
+     * Restart behaviour follows from lifetime: persistent agents were just
+     * re-created; everything else that was live was interrupted, and the
+     * recipient of an interrupted job's result is told so. Results held from
+     * before the restart are delivered now, exactly once.
+     */
+    private reconcileAgentRegistry;
+    /**
+     * Deliver held mail that hasn't landed. Its copy may have reached the
+     * recipient's store in the same sync that the release missed, and then it
+     * is released instead; and a write the deferred queue still holds for it
+     * lands at the next flush and releases it then (releaseLandedMail). Either
+     * way a second delivery would put it in the window twice under one mail id.
+     */
+    private deliverHeldMail;
     private createDeferred;
     /** Liveness ping for an active ephemeral run (no-op otherwise). */
     private touchEphemeralRun;
@@ -2262,15 +2764,16 @@ export declare class AgentFramework {
     private recordEphemeralToolCalls;
     /**
      * A start dropped before its stream sends anything (its agent was replaced,
-     * or stop() closed admission or ended the lifecycle the start began in)
-     * ends the logical turn it was running. stop() ends every open turn
-     * (openLogical), but a fresh start that awaited its batches' assembly
-     * across a stop() reaches its routing after it and opens its turn. That
-     * turn would then stay open, and the agent's first start after a restart
-     * would continue the dropped turn's routing. The identity check leaves any
-     * other turn open.
+     * or stop() closed admission) ends the logical turn it was running. stop()
+     * ends every open turn (openLogical), but a fresh start that awaited its
+     * batches' assembly across a stop() reaches its routing after it and opens
+     * its turn. That turn would then stay open, and the next start of the
+     * agent's name would continue the dropped turn's routing. The identity
+     * check leaves any other turn open.
      */
     private endDroppedTurn;
+    private pinTurnInputs;
+    private releaseTurnInputs;
     /** A logical turn's end, for every agent: it closes the agent's open
      *  logical turn when it is the settling stream's own (openLogical), and
      *  settles an active ephemeral run. The run's tool-call count comes from
@@ -2310,8 +2813,11 @@ export declare class AgentFramework {
     /** Tune-out (issue #77): divert a channel to your subconscious. Present
      *  only when the subconscious resident is configured. */
     private static readonly TUNE_OUT_TOOL;
+    /** `focus`: the resident-facing alias for `tune_out` with scope "all-except" (#232 decision 2). */
+    private static readonly FOCUS_TOOL;
     /** Synthesized sleep/wake tool definitions (present when a gate is wired). */
     private static readonly SLEEP_TOOLS;
+    private static readonly WAKE_ADD_RULE_FIELDS;
     /** Synthesized wake-rule tools: add/remove a gate.json policy at runtime.
      *  Present when a gate is wired. They write validated policies into the
      *  hot-reloaded gate.json (same validation as load), so a rule takes effect
@@ -2326,14 +2832,14 @@ export declare class AgentFramework {
     /** Synthesized drafts tool — present whenever MCPL channels are
      *  configured. A resident's held drafts (src/prose-drafts.ts): plain speech
      *  that was not sent, never published except by its resident's resend, and
-     *  kept as that module's retention says. Nullable
-     *  fields, cast like save_recent_image's: a caller whose provider presents
-     *  every property as required can still say "not in use". */
+     *  kept as that module's retention says. Its optional fields are nullable,
+     *  as save_recent_image's selectors are: a caller whose provider presents
+     *  every property as required can still say "not in use" (fieldInUse). */
     private static readonly DRAFTS_TOOL;
-    /** Synthesized save_image tool — present when a workspace module is
+    /** Synthesized save_recent_image tool — present when a workspace module is
      *  registered. Lets the agent persist an image it has already seen in its
      *  own context (Discord attachments arrive inlined as base64 and are
-     *  otherwise unreachable as files). */
+     *  otherwise unreachable as files). Its three selectors are nullable. */
     private static readonly SAVE_IMAGE_TOOL;
     /** Synthesized fetch_reference tool — RFC-005 on-demand dereference.
      *  Present when a workspace module is registered (storage target). */
@@ -2870,6 +3376,28 @@ export declare class AgentFramework {
      * into the resident's window, which accumulates there.
      */
     private createSubconsciousAgent;
+    /**
+     * `subconscious.reader: 'forks'`: no persistent agent. The coordinator
+     * asks for a fork per invocation (see invokeReaderFork); the config is
+     * kept for the voice block, the speech switch and the strategy factory.
+     */
+    private configureReaderForks;
+    /**
+     * One reader invocation: derive a fork of the resident at its head with
+     * the resident's refusals, hand it the held traffic since the last look
+     * as ordinary framing, and run it. It reports through `deliver_summary`
+     * (attributed mail), may cancel the hold, and ends when its turn ends.
+     */
+    private invokeReaderFork;
+    /**
+     * Held messages still queued behind the resident's turn, as rows of a
+     * reader fork's backlog: each named by its held handle, as module rows name
+     * it until it lands (heldRows), at a provisional sequence past the
+     * resident's last stored message, and timed when it was first held.
+     */
+    private queuedReaderRows;
+    /** A reader fork's own words to the resident: attributed mail when it has a route, else under its name. */
+    private deliverFromReader;
     private runLoop;
     private processNextEvent;
     private handleProcessEvent;
@@ -2895,6 +3423,14 @@ export declare class AgentFramework {
      * Convert an incoming MCPL channel message to a context message.
      * This replaces the old MCPLModule.onProcess() message conversion.
      */
+    /**
+     * A delivered inbound message becomes the latest delivered inbound (the
+     * channel context's reply anchor; the legacy speech fallback) through the
+     * registry's noteDelivered — at once for a plain channels/incoming, whose
+     * acceptance the registry answers synchronously; parked for a coalesced one
+     * until its acceptance is acknowledged (see parkedAnchors).
+     */
+    private noteDeliveredOrPark;
     private handleMcplChannelIncoming;
     /**
      * Route an incoming channel message through the ConversationRouter:
@@ -3142,7 +3678,8 @@ export declare class AgentFramework {
      *  placed in its agent's deferred queue (wakeToRead), at `readsDeferredWrite`,
      *  marked ambient when every notice the render folds was (`allAmbient`). */
     private queueCoalescedWakes;
-    /** Withdraw unstarted wakes whose sole cause is this subject (§4.2). */
+    /** Withdraw unstarted wakes whose sole cause is this subject (§4.2), and
+     *  a merged start whose every request is withdrawn. */
     private cancelCoalescedWakes;
     /**
      * A placement in the deferred queue is upgraded in place once the flush has
@@ -3185,6 +3722,27 @@ export declare class AgentFramework {
      * channels answer to is never resolved to either.
      */
     private channelNamed;
+    /**
+     * A live agent's home channel, from its registry record (channelOfHome):
+     * defined for a conversation fork, and only for one. Undefined for an agent
+     * with none, and for one that has ended.
+     */
+    private homeOf;
+    /**
+     * The channel a registry record's `homeChannel` names: the channel on its
+     * server. A bare channel id, as a record written before homes carried
+     * their server keeps, is read as a wake that names its channel without its
+     * server is (channelNamed): the one registered channel it names, read when
+     * it's used, since the servers registered at that moment are what it can
+     * mean. An id that names no one registered channel, as one no server
+     * registers now or two servers do, is the home on no server (an empty
+     * serverId, which channelNamed reads as none given), so the agent keeps a
+     * home. A path that reads the pair finds no server registering it, and
+     * refuses it; one that reads the name reads what the name means then: none
+     * or two channels, which it refuses, or, once one server alone registers
+     * the id, that server's channel.
+     */
+    private channelOfHome;
     /**
      * Explicit mode's typing channel for one start of a turn, which has no
      * locus, read once as the start opens (driveStream then shows what the
@@ -3225,6 +3783,23 @@ export declare class AgentFramework {
      *  it takes their agent up (passRequests). */
     private processInferenceRequests;
     private runInferencePass;
+    /**
+     * `channel_publish` with no channel goes where the turn's plain speech
+     * would: the frozen turn locus (the waking delivery's channel, or one
+     * opened this turn), then the registry's own resolution. Under
+     * `speech.locus: 'delivery'` the registry alone has no default, and the
+     * tool failed on the very turn its own delivery woke (first live run,
+     * 2026-10-12). Both dispatch paths — the stream driver's and
+     * executeToolCall's — pass through here. Only a call made inside the turn
+     * (callingTurnOf) takes the turn's locus: one made outside it, as a script
+     * left running after its turn makes or a host's executeToolCall naming the
+     * agent, takes none of the turn's channels. A conversation fork's home
+     * isn't the turn's but the fork's own, so such a call from a fork naming
+     * no channel still goes there (homeOf), as the fork's dispatched calls do
+     * (dispatchChannelToolCall); anyone else's takes the registry's own
+     * default.
+     */
+    private publishInputWithTurnLocus;
     /**
      * Stamps for the rows the agent's reply stores in its current turn: its
      * assistant responses, its tool_result rows (through `storeResults`), and
@@ -3426,14 +4001,20 @@ export declare class AgentFramework {
      * announced baseline alone (announceLocusIfChanged).
      */
     private noticeHeartbeatTurn;
+    private rememberAnnouncedLocus;
+    private forgetAnnouncedLocus;
+    /** The stored baseline's entry for the agent set (rememberAnnouncedLocus),
+     *  or removed (undefined) when the agent ends without coming back. */
+    private writeAnnouncedLocus;
     /**
      * Announce-on-change locus notice (turn-frozen routing). Appends a durable
      * `[routing]` window message when the turn's effective outbound locus
      * differs from the last one announced — the agent must never have to guess
      * where its plain prose lands. Durable append (never retracted) keeps the
-     * KV prefix stable; change-only keeps it out of steady-state turns. The
-     * first resolution after boot announces only a non-null locus ("prose has
-     * no destination" is the unremarkable boot default). Never triggers
+     * KV prefix stable; change-only keeps it out of steady-state turns. An
+     * agent never told of a locus, here or before a restart, hears only of a
+     * non-null one ("prose has no destination" is the unremarkable start).
+     * Never triggers
      * inference; never locus-eligible itself (system + no channel metadata).
      */
     private announceLocusIfChanged;
@@ -3445,7 +4026,11 @@ export declare class AgentFramework {
      * as the agent's first view) that addressed the agent, or that follows up
      * in a channel the turn sent into (TurnRouting.engaged). Undefined for any
      * other message. A tool boundary weighs the messages it injects by it,
-     * and noteArrival the ones no boundary of the turn weighs.
+     * and noteArrival the ones no boundary of the turn weighs. The rule is
+     * pure; what is done with its answer is `speech.locus`'s: under
+     * `'latest-inbound'` the locus moves, under `'delivery'` (the default) the
+     * agent is told it was addressed from elsewhere and the locus stays
+     * (addressedElsewhereNotice).
      */
     private repinChannel;
     /** Whether `agent` has a turn alive: starting, streaming or waiting on its tools. */
@@ -3544,13 +4129,15 @@ export declare class AgentFramework {
      * Weigh a message that no tool boundary of the agent's open logical turn
      * will weigh: one that would re-pin the locus becomes one of the turn's
      * arrivals (TurnRouting.arrivals). A message the agent's own view leaves
-     * out, such as one a tune-out diverted (metadata.tuneOut), never enters
-     * its compiled view, so the agent won't see it, and it moves nothing.
+     * out (agentSees), such as one held from the residents (heldFromResidents,
+     * the admission stage's one predicate, which every resident's view filter
+     * reads) or another agent's stored context injection, never enters its
+     * compiled view, so the agent won't see it, and it moves nothing.
      */
     private noteArrival;
     /**
      * Whether `agent`'s store is the residents' one message slot, which every
-     * ordinary resident reads (sharedSlotAgents). The subconscious reads that
+     * ordinary resident reads (`readsSharedSlot` in the registry). The subconscious reads that
      * slot through a merged view, but its own store is isolated, as a fork's
      * or an ephemeral agent's is.
      */
@@ -3591,6 +4178,23 @@ export declare class AgentFramework {
      * so the agent's next turn announces where its speech lands.
      */
     private repinTurnLocus;
+    /**
+     * Under `speech.locus: 'delivery'`: tell the agent that someone addressed
+     * it from another channel while its turn was busy, since incoming traffic
+     * never moves the locus and a neutral message carries nothing that names
+     * its channel (first live run, 2026-10-12, finding C). Once per channel
+     * per turn (TurnRouting.addressedElsewhere); nothing for the turn's own
+     * locus. Stored durably; returned as stored for a live stream to inject
+     * with its boundary's other messages. Undefined when nothing was stored.
+     */
+    private addressedElsewhereNotice;
+    /**
+     * The arrivals a start of the turn consumes under `speech.locus:
+     * 'delivery'`: each one that addressed the agent, whose message is still
+     * in the store, gets the addressed-elsewhere notice, oldest first. A
+     * follow-up in an engaged channel addressed nobody and is not announced.
+     */
+    private noticeAddressedArrivals;
     /**
      * Durable window notice for a channel the agent did not ask to open: a
      * subscription-policy admission, announced as the decision before its
@@ -3956,9 +4560,8 @@ export declare class AgentFramework {
      * gets inference:aborted with `reason`, and lastInference records its end
      * as driveStream's would, when the record is still this turn's. Nothing of
      * the kind when another turn of this agent's name holds the turn token (one
-     * begun after a stop and start, or by a replacement agent object): the
-     * event and the record carry only the name, so this frame's would end that
-     * newer turn instead.
+     * begun by a replacement agent object): the event and the record carry only
+     * the name, so this frame's would end that newer turn instead.
      */
     private abortDroppedTurn;
     /**
@@ -4027,7 +4630,11 @@ export declare class AgentFramework {
     private driveStream;
     /**
      * Execute a tool call and return the result.
-     * Routes to the appropriate handler (module registry or MCPL).
+     * Routes it where the agent's own call of the name goes: to the
+     * framework's own tools the agent has (agent_settings, the workspace and
+     * gate tools, think, journal, prose_help and the rest), the channel tools,
+     * MCPL or the module registry. skip_reply, which ends the turn it's called
+     * in, is refused, since this call isn't made in one.
      * Its one caller in the framework is the operator's puppet
      * (puppetToolCall), which puts the agent's inline cap on the call as
      * resultMaxChars; a host may call it as well.
@@ -4041,8 +4648,10 @@ export declare class AgentFramework {
      * (ctx.callTool → executeToolCallFrom with {kind:'module'}), which is exempt
      * from agent allowlists. Registered agents' allowedTools is enforced at
      * dispatch, including namespaced utility names. Genuinely unidentified public callers (including
-     * unknown legacy names) remain unrestricted. Framework-created identities
-     * are refused while unregistered, even if their configured list allows it.
+     * unknown legacy names) remain unrestricted. A name the framework made in
+     * this process is refused while it isn't registered, even if its configured
+     * list allows the tool; after a restart, such a name is a host's caller name
+     * like any other.
      */
     executeToolCall(call: ToolCall): Promise<ToolResult>;
     /**
@@ -4066,8 +4675,11 @@ export declare class AgentFramework {
      *   wire ordering. For its own duration the puppet HOLDS the turn-alive
      *   marker (wakes requeue, cross-turn writers defer), so a wake landing
      *   during the tool's execution cannot start a turn underneath the pair.
-     * - Refused for tools outside the agent's own surface (canUseTool): the
-     *   stored pair must be an act the agent could genuinely have taken.
+     * - Refused for tools outside the agent's own surface (the tools it may
+     *   call, availableToolsForPresentation), and for skip_reply, by name or
+     *   through a toolsets--act that reaches it, which ends the turn it's
+     *   called in: the stored pair must be an act the agent could genuinely
+     *   have taken.
      * - The call executes FOR REAL through the shared dispatch (MCPL,
      *   channel tools, utils, modules) with the agent's provenance — a
      *   puppeted walk_to actually moves the avatar.
@@ -4107,6 +4719,29 @@ export declare class AgentFramework {
      *  tool it makes, under that tool's model-facing name and with its
      *  arguments, its id kept; or the reason it can't be sent. */
     private resolveToolsetAct;
+    /**
+     * A reader reads and reports: a reader fork (registry kind
+     * 'subconscious-fork', in every incarnation) may call only its own tools,
+     * and speak_in_channel where allowChannelSpeech allows it. Every other
+     * tool the resident has stays in its block (the shared prefix) and is
+     * refused here, so with speech off a fork can post nowhere (scout's
+     * condition, 2026-10-19). It's decided at each call from what the reader
+     * may call, not from what it is shown, so a tool added or moved out of
+     * the block later is refused too.
+     */
+    private readerRefuses;
+    /**
+     * What a reader fork may call: exactly its own tools and the speech its
+     * configuration allows, never widened or narrowed by its resident's
+     * allowedTools. The resident's list bounds the resident's own surface;
+     * the reader's tools are the framework's, for reading on its behalf. A
+     * denyToolsAtDispatch entry the fork takes from its resident that names
+     * one of them still refuses it (mayCallTool checks the deny first): a
+     * resident never holds a reader tool, so such an entry is about readers.
+     * The fork still shows its resident's block (the shared prefix): what it
+     * may call is decided here, at each call, apart from what it is shown.
+     */
+    private readerMayCall;
     /** A toolsets--act call a host toolset resolved (HostPresentation.resolveAct):
      *  its refusal answered, or the tool's own call dispatched in its place,
      *  with the act's id, so its result is the act's. */
@@ -4456,9 +5091,15 @@ export declare class AgentFramework {
      * that. Never prefix-map insertion order.
      */
     private resolveMcplTool;
-    /** Registered policy; framework-created identities have no dispatch authority
-     * while unregistered. Genuine legacy caller names retain their surface. */
+    /** Registered policy. Within this process, a name the framework made has no
+     * dispatch authority while it isn't registered; after a restart, a host call names
+     * its caller as any host call does. Genuine legacy caller names retain
+     * their surface. */
     private canAgentUseTool;
+    /** Whether a call of `toolName` as `agentName` is refused at dispatch (AgentConfig.denyToolsAtDispatch, or a reader's own rule). */
+    private deniedAtDispatch;
+    /** Whether `agentName` may call `toolName`: the one rule dispatch applies (agentToolPermissionFailure), for whatever else judges a call. */
+    private mayCallTool;
     private agentToolPermissionFailure;
     private markedInputFailure;
     private cutOffResults;
@@ -4496,6 +5137,9 @@ export declare class AgentFramework {
      * (`refusedHere`) counts as one the list refuses.
      */
     private roundCallOf;
+    private toolRoute;
+    private pushToolResult;
+    private awaitedToolAnswer;
     /**
      * Dispatch a call the agent made. `turnId` is the turn it was made in
      * (TurnRouting.turnId), as its caller knows it: a model's call, the turn
@@ -4571,6 +5215,14 @@ export declare class AgentFramework {
      *  the start now beginning (no tool boundary will weigh it), and one for
      *  every other resident's open turn. */
     private noteStored;
+    /**
+     * Held agent mail is released only when its message has actually entered
+     * the recipient's store — never on a deferral. Called at every site that
+     * writes a message into a context: the direct path above and the two
+     * deferred-write flushes (turn start, tool boundary). Both writes reach
+     * disk in the same sync, so a crash keeps either both or neither.
+     */
+    private releaseLandedMail;
     /**
      * Splice out the deferred messages addressed to `agentName` (explicitly
      * via forAgent, or implicitly when it is the primary), leaving other
@@ -4873,11 +5525,9 @@ export declare class AgentFramework {
      * at a tool boundary whose stream declares it carries the messages
      * injected there (markContextConsumed). So a notice such a stream carried
      * is under it. One a boundary stored without sending (a turn a tool ended,
-     * a budget restart) is above it, and so is one injected into a stream that
-     * doesn't declare it carries injections, which may have dropped it:
-     * counted as unread, it goes to the primary even if the agent heard it,
-     * rather than to no one where the stream dropped it. null when the window
-     * can't be read, which is logged.
+     * a budget restart, the direct API's boundary, which has no stream) is
+     * above it until a compile sends it, and counts as unread. null when the
+     * window can't be read, which is logged.
      */
     private releasedWindow;
     /**
@@ -5008,7 +5658,7 @@ export declare class AgentFramework {
      * The writes the framework holds for the store `reader` reads, in queue
      * order: those addressed to it and, when it's an ordinary resident, those
      * addressed to any ordinary resident, since residents share one message
-     * slot (sharedSlotAgents). A write whose target is gone isn't among them:
+     * slot (`readsSharedSlot` in the registry). A write whose target is gone isn't among them:
      * no module reads that agent's store, and the write waits for its window's
      * release (drainDeferredFor) or, at its flush, is dropped (addMessage), a
      * failed reply, or a channel notice its reader could act on, passing to the
@@ -5669,9 +6319,10 @@ export declare class AgentFramework {
     private runDisconnectMcplServer;
     /**
      * Restart an MCPL server at runtime: disconnect, then reconnect with the
-     * same (or an updated) config. This actually respawns a stdio child —
-     * unlike `reconnect: true`, which only retries after transport-level
-     * failures. Throws if the server has no stored config and none is given.
+     * same (or an updated) config. This respawns a stdio child at once,
+     * whatever its state; `reconnect: true` spawns a fresh child only after
+     * the connection fails or its child exits. Throws if the server has no
+     * stored config and none is given.
      * What its connect would refuse is refused before the running server is
      * torn down. Until the connect, a connect or a restart started meanwhile
      * is refused the id and the tool prefix the restart moves the server to,
@@ -5944,6 +6595,15 @@ export declare class AgentFramework {
      * error and nothing is written.
      */
     private dispatchWakeRuleToolCall;
+    /**
+     * A reader's own tool (SUBCONSCIOUS_TOOL_NAMES), for both entries that run
+     * an agent's call: the dispatcher's, for the model's call, and
+     * executeToolCallFrom's, for a host's or the puppet's. The tools are
+     * advertised to residents so reader forks share their prefix, and only a
+     * registered reader may use them. A rejection is answered with a failed
+     * result, never left unhandled.
+     */
+    private readerToolCall;
     /**
      * Handle the synthesized `sleep` / `wake` tools. `sleep` arms the gate's
      * suppression window, optionally announces in the sticky channel, and ends
@@ -5951,6 +6611,35 @@ export declare class AgentFramework {
      */
     /** tune_out tool (residents): enter or cancel a channel tune-out. */
     private dispatchTuneOutToolCall;
+    /** `focus` is `tune_out` with scope "all-except". */
+    private handleFocusTool;
+    /**
+     * A tune-out call's refusal for a channel it can't resolve: main's words
+     * for a name no registered channel, and none of the calling turn's own,
+     * answers to, and the registry's own otherwise, as for an id that is
+     * ambiguous across servers (#232 gap 8).
+     */
+    private unknownChannelWords;
+    /**
+     * The tune_out tool's body. Channel resolution is server-qualified
+     * (ChannelRegistry.resolveChannel): with a `serverId`, that server's
+     * channel with the id; inside the calling turn, a name one of the turn's
+     * own channels answers to by its id means that channel; otherwise the one
+     * channel the name means, which may be server-qualified, and a name two
+     * servers' channels answer to is refused with them as candidates (#232
+     * gap 8). `turn` is the turn that made the call (callingTurnOf), the only
+     * one whose speech an all-except entry moves.
+     */
+    private handleTuneOutTool;
+    /**
+     * The admission stage for one inbound event: the pure decision over the
+     * framework's policy inputs (recipients, the hold in force, the wake
+     * gate), traced. Callers apply it; nothing downstream re-asks.
+     */
+    private admitInbound;
+    private commitDeliveries;
+    /** The history-reading tool the primary resident actually has, if any (#232 gap 11). */
+    private residentHistoryTool;
     private dispatchSleepToolCall;
     /**
      * Handle the synthesized `read_image` tool: read image bytes from a
@@ -5972,10 +6661,9 @@ export declare class AgentFramework {
      * every sibling in the round to settle; if one never does, fail closed
      * rather than trust an index the batch may still change. Sibling saves
      * produce no images and are not waited on (two saves in one batch would
-     * otherwise deadlock into a double timeout). A script's own calls
-     * (`pytc-…`) skip the barrier: the batch's pending siblings include the
-     * code_execution call running that script, so waiting on them would wait
-     * on itself.
+     * otherwise deadlock into a double timeout). Only the round's own calls
+     * wait: a call that isn't among its pending calls, a script's (`pytc-…`)
+     * or an awaited call's, counts the images the agent has now.
      */
     private awaitSiblingToolCalls;
     /**