@animalabs/agent-framework 0.29.0 → 0.30.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';
 /**
@@ -211,6 +213,85 @@ export declare class DefaultErrorPolicy implements ErrorPolicy {
     constructor(settings?: RetrySettings);
     onInferenceError(error: Error, _agentName: string, attempt: number): ErrorAction;
 }
+/**
+ * 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;
@@ -389,6 +470,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;
@@ -442,8 +530,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 +616,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
@@ -595,8 +691,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 +727,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 +874,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 +903,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 +912,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 +926,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;
@@ -1155,7 +1297,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
@@ -1405,7 +1550,9 @@ export declare class AgentFramework {
     /**
      * 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.
@@ -2248,11 +2395,334 @@ 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 branch-bound store handles and is
+     * refused, not silently downgraded, where they are missing. `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;
+    /**
+     * 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;
@@ -2310,6 +2780,8 @@ 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;
     /** Synthesized wake-rule tools: add/remove a gate.json policy at runtime.
@@ -2870,6 +3342,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 +3389,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:
@@ -3185,6 +3687,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 +3748,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 +3966,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 +3991,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 +4094,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 +4143,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
@@ -4041,8 +4610,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>;
     /**
@@ -4107,6 +4678,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 +5050,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;
@@ -4571,6 +5171,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
@@ -5008,7 +5616,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
@@ -5944,6 +6552,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 +6568,40 @@ 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;
+    /**
+     * Make delivered messages durable now, including those the delivery left
+     * in the deferred queue: a tune-out release flips durable epoch state
+     * first, so its dump must not be lost to a crash in between (#232 gap 6).
+     */
+    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