@animalabs/agent-framework 0.22.2 → 0.23.0

package/dist/src/framework.d.ts

@@ -83,9 +83,15 @@ export interface HostModeStatus {
     /** Context writes (module events, api message.send) withheld because the
      * host is quiesced. Persisted while quiesced and flushed by resume(). */
     deferredWrites: number;
-    /** Agents whose turn `abandon` could NOT cancel: the turn token is held but
-     * no stream exists yet (still in hooks/compile) or ever will (puppet tool
-     * turns). Present only after an abandon that left such turns behind. */
+    /** Agents whose turn `abandon` had not ended when its grace ran out: a
+     * turn token held with no stream to cancel and no check ahead to stop it
+     * at (a puppet tool turn, a store surgery's reservation, a turn finishing
+     * its last delivery), or a turn with no stream that hasn't reached its
+     * next check, such as one in a hook that hasn't returned. A turn whose
+     * stream the abandon cancelled isn't listed, even one still running when
+     * the grace runs out, as one whose tool-result guard waits on its speech
+     * may be. Present only after an abandon that left such turns behind, while
+     * the host stays quiesced. */
     unabandonable?: string[];
 }
 /**
@@ -104,6 +110,19 @@ export declare class ResumeBlockedError extends Error {
         preview: RuntimeSettingsPreview;
     }>);
 }
+/**
+ * Thrown by `quiesce()` without `abandon` when the queue of deferred context
+ * writes can't reach disk: it's over its cap, so its record can't hold it, or
+ * its write failed, and that error is the `cause`. So the queue as it
+ * stands isn't on disk. The host's mode is as it was, and the
+ * message names the ways out, among them quiescing with `abandon: true`,
+ * which goes on with the queue in memory.
+ */
+export declare class QuiesceBlockedError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * How `runEphemeralToCompletion` rejects when a retryable provider failure
  * states a wait the run won't sleep: one longer than an ephemeral run sleeps
@@ -190,10 +209,26 @@ export declare class AgentFramework {
     private stopPromise;
     private stopCompleted;
     private ownedStoreClosed;
+    /** 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
+     * the stop. A step that threw may have left part of its work running, as
+     * a wait that ran out does. create()'s release reads it to say whether part
+     * of what a failed create() started may still be running. */
+    private stopFinishedTeardown;
     /** An operator's operations in flight, and the config materializations they
      * start. stop() waits until this set is empty before it tears down, unless
      * its wait budget runs out. */
     private readonly operatorOperations;
+    /** What a wait of stop()'s left running when its budget ran out, by its
+     * 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
+     * threw lets the store close under work still running. Each leaves once it
+     * settles. */
+    private readonly leftRunning;
     private membrane;
     private queue;
     private agents;
@@ -212,6 +247,16 @@ export declare class AgentFramework {
      * running; only new turns (wake gate in processInferenceRequests) and MCPL
      * data planes are held. */
     private quiesced;
+    /** Whether the host-mode record may say quiesced, as this process last read
+     * or wrote it. quiesce() writes the record before it sets `quiesced`, and
+     * resume() clears `quiesced` before the record, so after a resume whose
+     * clear failed, or a quiesce whose write failed partway, memory can say
+     * serving while the record says quiesced, until a resume() clears it. */
+    private hostModeRecordMayBeQuiesced;
+    /** Whether a resume() is between serving and clearing the record: it has
+     * cleared `quiesced` and is flushing the deferred writes, then clearing the
+     * record. A resume() on the serving host leaves the record to it. */
+    private resumeInFlight;
     private quiesceReason?;
     private quiescedAt?;
     private traceListeners;
@@ -250,8 +295,12 @@ export declare class AgentFramework {
     /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
     private lastInferenceAt;
     private processLoggingPersist;
-    private processLoggingBroadcast;
     private activeStreams;
+    /** Told once per inbound acceptance (mcpl/inbound-source.ts). An internal
+     *  seam, unset here: the receipt work (shelf-354) assigns it inside the
+     *  framework, and tests set it by cast. */
+    private inboundAcceptanceObserver?;
+    private streamBoundaryEnds;
     /** A tool boundary injected fresh CONVERSATIONAL input (a real message —
      *  not a reaction or a system marker) into the live stream. Tells
      *  driveStream to clear sticky explicit-send suppression before handling
@@ -262,8 +311,11 @@ export declare class AgentFramework {
      *  (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. */
     private lastAnnouncedLocus;
-    /** Latest bounced (undelivered) prose per agent — the `{{unsent}}` source. */
-    private proseClipboards;
+    /** Every resident's held drafts: plain speech that was suppressed, bounced
+     *  or left without a destination, never published except by their
+     *  resident's resend, kept until resent or dismissed. A logical turn's own
+     *  drafts, for its receipt, are its TurnRouting's. */
+    private proseDrafts;
     /**
      * Each agent's routing state for its current logical turn (TurnRouting):
      * its trigger channel, locus and engaged channels, the sticky destination,
@@ -321,15 +373,20 @@ export declare class AgentFramework {
     private ephemeralRuns;
     /** Ephemeral namespaces/names are single-generation for this framework
      * lifetime. Reusing one while an old stream drains would let name-keyed
-     * liveness/settlement state cross generations. */
+     * liveness/settlement state cross generations. Each name records what
+     * reserved it: an ephemeral run (createEphemeralAgent), which takes no
+     * global fallback even after its release, or a conversation fork. */
     private usedEphemeralAgentNames;
     /** One-shot generation tickets minted by createEphemeralAgent. */
     private ephemeralCandidates;
+    /** Warn only once per Agent instance after utilities are registered. */
+    private emptyUtilityPermissionWarnings;
     /** Physical ephemeral frames deliberately disposed by their run watchdog/caller.
      * The name is single-generation, so these frames still own their terminal
      * typing/outgoing close even after runEphemeralToCompletion deregisters them. */
     private disposedEphemeralFrames;
-    /** Per-agent count of consecutive exhausted inferences (reset on any success).
+    /** Per-agent count of consecutive exhausted inferences, reset when a turn
+     *  completes (inference:completed), not when a call answers mid-turn.
      *  Drives hard-down escalation — see noteInferenceExhausted. */
     private consecutiveInferenceFailures;
     /** N consecutive failed inferences ⇒ the agent is treated as hard-down and
@@ -350,10 +407,11 @@ export declare class AgentFramework {
     private refusalStreak;
     /** Per-agent count of consecutive refusal-driven rewinds in the current turn
      *  chain (reset when a turn completes without a refusal). Bounds the auto
-     *  rewind loop — see refusalHandling + rewindTriggeringTurn. */
+     *  rewind loop — see refusalHandling + shedNewestTurn. */
     private refusalRewinds;
     /** Per-agent count of poison-history rewinds performed by the hard-down
-     *  breaker (noteInferenceExhausted). Reset on any successful inference.
+     *  breaker (noteInferenceExhausted). Reset when a turn completes
+     *  (inference:completed).
      *  Bounds the automatic quarantine loop the same way refusalRewinds bounds
      *  the refusal loop, so the breaker can never shed the whole history. */
     private exhaustionRewinds;
@@ -387,9 +445,20 @@ export declare class AgentFramework {
     /** Agents an abandon could not cancel (token held, no stream) — surfaced
      *  in HostModeStatus until the next quiesce/resume. */
     private lastUnabandonable;
-    /** True while the deferred-write queue has a persisted mirror (quiesced). */
+    /** True while the deferred-write queue is mirrored to its record, so each
+     *  change of it writes it: from a write of it that reached or may reach
+     *  the record, one that failed or met the cap unless quiesce() rejected
+     *  for it (deferredWritesFellBehind), or a boot that restored it, until a
+     *  write clears the record once the queue drains. */
     private deferredWritesPersisted;
-    private deferredWritesCapWarned;
+    /** True from a write of the queue that failed or met the cap, unless
+     *  quiesce() rejected for it, until one succeeds: a run of failures
+     *  (deferredWritesFellBehind). A quiesce({ abandon: true }) over the cap
+     *  goes on rather than rejecting, so its write begins a run too. */
+    private deferredWritesBehind;
+    /** 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;
     /** Branch-independent recovery files (see FrameworkConfig.hostModePath /
      *  deferredWritesPath). Undefined → branch-local slot fallback. */
     private hostModePath;
@@ -405,7 +474,9 @@ export declare class AgentFramework {
     private unackedDeferredWrites;
     /** Monotonic order stamp for deferred writes: the durable queue is always
      *  written, restored, drained and flushed in `seq` order, whatever the
-     *  pending/un-acked split — a re-deferred entry keeps its place. */
+     *  pending/un-acked split — a re-deferred entry keeps its place. Boot
+     *  recovery numbers the restored queue 1..N in that order, and the stamp
+     *  goes on from N (restorePersistedDeferredWrites). */
     private deferredSeq;
     /**
      * Per target agent: the store's message count when the OLDEST currently
@@ -424,8 +495,38 @@ export declare class AgentFramework {
      * guessing from the newest message in the window.
      */
     private activeTurnTriggers;
+    /**
+     * The `[Continue]` prompt the current round of each turn follows, keyed by
+     * the turn's trigger. Each stream start sets it from what the Agent read in
+     * its request (`StartStreamResult.continuePrompt`), and a tool boundary
+     * that hands the live stream messages after the results clears it, since
+     * the next round follows those messages. `silentTurnRowMetadata` stamps the
+     * round's rows with it.
+     */
+    private readonly turnPrompts;
     /** The trigger of `agentName`'s turn in progress, if a turn is running. */
     getActiveTurnTrigger(agentName: string): InferenceRequest | undefined;
+    /**
+     * The window of the frame that holds an agent's turn with no stream to
+     * carry a stop and one of its checks ahead: a start, from its entry until
+     * it hands its turn to a stream or ends (its checks after the hooks, after
+     * the compile, at a failure and after a wait to retry its compile),
+     * driveStream's wait to retry a failed inference (its check after the
+     * wait), and the tool-result guard's wait for the agent's speech (its
+     * check after the wait, which the window lets the abandon reach once a
+     * caller's cancelStream() has left the agent holding no stream). Each
+     * frame opens a window of its own and closes it only while it
+     * is still the agent's, so a start that ends after a later frame opened
+     * one, such as its retry's stream waiting to retry, leaves that one open.
+     * An operator's abandon marks the window, and the frame's check collects
+     * the mark, which goes with the window. abortInference() and the abandon
+     * count a turn with no stream only here; a stop made anywhere else, as
+     * while an agent is idle, a turn finishes its last delivery or a provider
+     * hold has parked it, has no check to end it, and the next start drops
+     * it. Keyed by the Agent, so a replacement agent under the same name
+     * never shares one.
+     */
+    private checkAhead;
     /** Structured calls executed in the current logical turn. Unlike the
      * per-stream local this survives framework retries and budget restarts. */
     private logicalTurnToolCalls;
@@ -434,6 +535,11 @@ export declare class AgentFramework {
     private redoStacks;
     /** Liveness watchdog (fail hard on a wedged main thread). Null unless enabled. */
     private livenessWatchdog;
+    /** The frameworks a SIGUSR2 dumps (joinDiagnostics): each joins in create()
+     *  where the liveness watchdog starts, or would if it isn't enabled, and
+     *  leaves in stop() where the watchdog stops. */
+    private static readonly diagnosed;
+    private static diagnosticsListenerInstalled;
     private mcplServerRegistry;
     private featureSetManager;
     private hookOrchestrator;
@@ -462,7 +568,10 @@ export declare class AgentFramework {
      * ephemeral agents have isolated slots and are their own only readers.
      */
     private readonly sharedSlotAgents;
-    /** 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; resume() releases them (releaseWindowNowOrAfterResume). */
+    private readonly releasesAfterResume;
+    /** The coalescing commit in flight, if any (see commitCoalescingDurable). */
     private coalescingCommit;
     private inferenceRouter;
     private channelRegistry;
@@ -477,6 +586,9 @@ export declare class AgentFramework {
      * 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
@@ -489,7 +601,8 @@ export declare class AgentFramework {
      *  result marks the script that made the call, and is applied to that
      *  script's code_execution result instead of cancelling the stream
      *  mid-script (which would wedge the turn). A stopped script's late result
-     *  marks only that script, never the agent's next one. */
+     *  marks only that script, never the agent's next one. Its `turnId` is the
+     *  turn of the code_execution call running it, which its calls carry. */
     private scriptDeferredEndTurn;
     /** RFC-007: per agent, the origin of the foreground script its runner is
      *  executing, handed to that script's inner calls (scripts run one at a
@@ -522,11 +635,20 @@ export declare class AgentFramework {
     private mcplToolRefreshPending;
     /** Maps tool prefix → serverId for dispatch routing. */
     private mcplPrefixMap;
-    /** Namespaced tool name → the server whose tools/list produced it. Prefixes
-     *  can nest (`foo`, `foo--bar`), so a prefix match alone can name two. */
+    /** Namespaced tool name → the server whose tools/list produced it, from
+     *  its first listing of the name. resolveMcplTool reads it first. */
     private mcplToolServers;
     /** Servers whose tools/list answered in the latest refresh. */
     private mcplListedServers;
+    /** refreshMcplTools' starts, and the start whose result was published
+     *  last: a refresh that a later-started one has overtaken publishes
+     *  nothing, since that one listed every server after it. */
+    private mcplToolsRefreshStarted;
+    private mcplToolsRefreshPublished;
+    /** How many times each server's connection has closed. A listing that
+     *  began before its server's latest close is of a session that's over,
+     *  and refreshMcplTools publishes none of it. */
+    private mcplServerCloses;
     /** Zero-match tool-pattern diagnostics (checkToolPatterns): set at the end
      *  of create(), when the tool universe is first complete. */
     private toolPatternChecksArmed;
@@ -537,6 +659,27 @@ export declare class AgentFramework {
     private toolPatternKnownPrefixes;
     /** Maps serverId → McplServerConfig for prefix lookup. */
     private mcplServerConfigs;
+    /** Modern-MCP (2026-07-28) servers, by id; read through modernServers().
+     *  They are kept apart from the MCPL registry on purpose: they have no
+     *  grant, planes or server→host traffic, so the MCPL machinery (quiesce's
+     *  plane pauses, awareness gates, policy) never sees them. They take part
+     *  only through the tool paths, and their list changes reach agents
+     *  through ordinary admission. */
+    private modernMcpConnections;
+    /** Connects and disconnects in flight, by server id (holdMcpServerId);
+     *  created on first use, like modernMcpConnections. */
+    private mcpServerOps;
+    /** Each legacy connect in flight's own abort (connectHeldMcplServer):
+     *  stop() and a disconnect of its id end it at once, its launch reaped,
+     *  rather than waiting out its handshake. Created on first use, as the
+     *  restart claims are (legacyConnectAborts()). */
+    private legacyConnectAbortMap;
+    /** The ids and tool prefixes restarts hold, each with the claim of the
+     *  restart holding it, from the restart's checks through its connect
+     *  (restartMcplServer): no other connect or restart takes them while the
+     *  old server is torn down. Created on first use (restartClaims), like
+     *  mcpServerOps. */
+    private mcpRestartClaims;
     /** Host capabilities advertised during the MCP handshake — stored so servers
      *  can be connected at runtime (connectMcplServer) after initialization. */
     private mcplHostCapabilities;
@@ -565,32 +708,120 @@ export declare class AgentFramework {
     private discordAwarenessBarrierGeneration;
     private eventGate;
     private usageTracker;
-    /** Explicit-send suppression carried into a tool-result-guard retry. */
+    /** Explicit-send or private suppression carried into a tool-result-guard retry. */
     private guardRetryTurnSilenced;
     /** Presentation-only wall-clock zone; persistence remains UTC/epoch. */
     private readonly timeZone;
     private constructor();
     /**
-     * Create and start the framework.
+     * Create and start the framework. A create() that fails releases what it
+     * had acquired before its error reaches the caller, so that the caller can
+     * try again in the same process: the framework it had begun is stopped, as
+     * stop() stops one, but giving up after 30 s on each of stop()'s cleanup
+     * waits, for an operator's operations already running, then for its
+     * modules and MCPL servers, and then for awareness drains a failed startup
+     * barrier left running, and a store it opened is closed. A store the
+     * caller passed in is left open.
      */
     static create(config: FrameworkConfig): Promise<AgentFramework>;
     /**
-     * Start the event loop.
+     * The error a failed create() rejects with, once what it acquired is
+     * released: the framework it had begun is stopped, with
+     * FAILED_CREATE_TEARDOWN_TIMEOUT_MS as stop()'s teardownTimeoutMs, and a
+     * store create() opened is closed even when that stop failed or timed out.
+     * stop() keeps an owned store open when any of its waits fails or times
+     * out, so that it can be called again, but no one can call it on a
+     * framework that create() never returned. When the release doesn't finish
+     * cleanly, the rejection carries create()'s error and then the release's,
+     * and its message says what didn't finish.
+     */
+    private static releaseFailedCreate;
+    /** create()'s work once it holds its store. The framework is named in
+     *  `building` as soon as it exists, so that create() can stop it if a later
+     *  step fails. */
+    private static createOn;
+    /**
+     * Diagnostics: `kill -USR2 <pid>` dumps live wake/inference state to stderr
+     * (journal) without a restart — for catching the wake-wedge on the running
+     * process. Each framework prints its own line: the gate's `inferring` set
+     * and buffered-event count (the wedge signature), active streams, and
+     * pending inference requests. A framework joins partway through create(),
+     * once its agents, modules and event gate are built, where the liveness
+     * watchdog starts (or would, when it isn't enabled). It leaves in stop()
+     * where the watchdog stops: after stop() has waited on its streams,
+     * 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.
+     *
+     * One listener serves the process, installed by the first create() to
+     * reach the join and kept: once a process's last SIGUSR2 listener is
+     * removed, the signal's default action ends the process, and a dump can
+     * arrive between one framework's stop() and the next one's create(), as on
+     * a host's session switch. Until a create() first reaches the join, the
+     * process has no listener, and the default action applies.
+     */
+    private static joinDiagnostics;
+    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.
      */
     start(): void;
     /**
-     * Stop the event loop. After a failed or timed-out wait on operator, module
-     * or MCPL cleanup, storage stays open and stop() can be called again. A
-     * timed-out wait lets teardown go on while that work may still act on what
-     * is being torn down.
-     * @param teardownTimeoutMs Optional budget for each wait on cleanup: an
-     * operator's operations already running, then modules and MCPL together.
-     * Omit to wait until cleanup settles, as required by existing module/child
-     * contracts. This does not bound earlier stream, event-loop or maintenance
-     * quiescence (a maintenance pass or over-budget drain kick in flight), or
-     * cancel cleanup.
+     * 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() 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
+     * act on what is being torn down.
+     * @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
+     * 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
+     * wait until each settles, as required by existing module/child contracts.
+     * A wait whose budget runs out fails the stop() with a ShutdownTimeoutError
+     * naming what it waited for; with more than one, or beside another failure,
+     * stop() fails with an AggregateError of them all. A stream whose cancel
+     * threw is treated as one whose wait ran out, whatever the budget, and the
+     * stop() fails with the cancel's error: that stop() doesn't wait for it,
+     * even with no budget, and a later stop() waits for it as for anything an
+     * earlier one left running (the last point below). After either:
+     * - an agent still registered whose stream is still running keeps its
+     *   deferred writes queued, since the stream may still write. The stream's
+     *   own turn-end flush takes them when it settles, if the process lives on,
+     *   and a later stop() takes what that leaves; a memory-only queue loses
+     *   them if the process exits first.
+     * - every ephemeral run still registered is ended, as after any stop(), and
+     *   its end stores what is queued for it, as at any run's end, whatever its
+     *   stream is doing: once a run has left, its stream's late events are
+     *   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.
+     * - 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.
      */
     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, which is 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;
     /** Register before invoking the body, so the set holds the operation for
      * its whole life: its synchronous trace callbacks can reenter stop(), and
@@ -603,6 +834,22 @@ export declare class AgentFramework {
      * queue (after a failed or completed stop()). The admission rule for every
      * operator entry point, the host/command listener included. */
     private stopHasBegun;
+    /** stop()'s first step for each connect still in flight, in either engine:
+     *  end it, so it fails at once and its operation ends, its launch reaped,
+     *  rather than holding stop()'s wait until its handshake's deadline. A
+     *  modern connect's connection is registered before it starts and is
+     *  closed; a legacy one's handshake, and the access provider a WebSocket
+     *  dial waits for, are aborted (legacyConnectAborts). A modern close's
+     *  outcome is the teardown's to report (closeModernMcpConnections). */
+    private endConnectsInFlight;
+    /** Wakers for the waits a connect makes that a stop() ends: see
+     *  untilStopBegins. Made on first use. */
+    private stopWaiters;
+    /** `work`, or undefined once stop() has begun, whichever comes first: a
+     *  connect's last step (its tool listing, which asks every server) needn't
+     *  hold stop()'s wait for operator operations on a server that doesn't
+     *  answer. The work goes on; the teardown's close ends what it waits for. */
+    private untilStopBegins;
     private refuseOperatorAfterStop;
     /** Wait in rounds until the set is empty: admitted work can still start work
      * of its own. All rounds share the caller's deadline rather than renewing
@@ -707,7 +954,9 @@ export declare class AgentFramework {
      * Wait an error policy's retry delay, all of it: the delay can be a
      * provider's retry-after, and a single timer past 2^31-1 ms fires almost at
      * once. Steps through longer waits; stop() wakes it so a shutting-down
-     * framework is never left with a wait parked for days.
+     * framework is never left with a wait parked for days. The frame's window
+     * (checkWindow) carries a waker that ends the whole wait: a stop
+     * abortInference() records, or an operator's abandon, wakes it.
      */
     private waitForRetry;
     /**
@@ -791,23 +1040,12 @@ export declare class AgentFramework {
     /** The strategy's progress snapshot, for diagnostics: one it can't give reads as none. */
     private contextProgress;
     /**
-     * A server's request or notification the host couldn't handle, answered
-     * with a JSON-RPC error when it is a request (a notification has no one to
-     * answer, and is logged), rather than thrown out of the connection's
-     * listener, where it was an unhandled rejection and the server's request
-     * waited for its timeout.
-     * - `refused`: the listener turned it away before its handler ran; the
-     *   host is stopping, and none of it was taken. Answered -32000, "the host
-     *   is stopping", the code the push coalescer already gives a stopping
-     *   host: the server can send it again to the host's next run.
-     * - `failed`: the handler threw, whatever it threw, `undefined` included.
-     *   While the host stops (its queue closed), that's answered -32000 too,
-     *   with the handler's own message after the stop wording; on a live host
-     *   it's a fault, answered -32603 with the handler's message. The handler
-     *   may have admitted part of the request first (an earlier message of a
-     *   batch), so nothing here claims that none of it was taken.
-     * A request the handler already answered before it threw isn't answered
-     * again: the failure is logged.
+     * A server's request turned away before its handler ran, because the host
+     * is stopping and none of it was taken: answered -32000, "the host is
+     * stopping", the code the push coalescer already gives a stopping host, so
+     * the server can send it again to the host's next run, and logged. A
+     * handler's own failure is answered by containedInboundHandler, with
+     * -32000 and the stop wording alone once the host is stopping.
      */
     private refuseServerItem;
     /**
@@ -849,7 +1087,10 @@ export declare class AgentFramework {
     offTrace(listener: TraceEventListener): void;
     private removeTraceRegistration;
     /**
-     * Add a module at runtime.
+     * 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.
      */
     addModule(module: Module): Promise<void>;
     /**
@@ -870,13 +1111,53 @@ export declare class AgentFramework {
      */
     getConversationRouter(): ConversationRouter | null;
     /**
-     * Abort an in-flight inference for an agent.
+     * Abort an in-flight inference for an agent. True when there was one to
+     * stop: a stream, or a turn with no stream and one of its checks ahead (its
+     * hooks or compile, a wait to retry, the tool-result guard's wait), which
+     * ends at that check, before it sends anything more.
      */
     abortInference(agentName: string, reason?: string): boolean;
+    /**
+     * Terminal for a deliberate cancellation of a live stream: the host's Stop
+     * button, an admin abort, a subagent reclaim — anything that went through
+     * Agent.cancelStream(reason) / abortInference(reason). Both of a stream's
+     * cancel twins land here (`aborted` with wire reason 'user', or `error`
+     * for implementations that report cancel() that way — see
+     * host-quiesce.test.ts), so the two cannot drift: settle the turn, ONE
+     * inference:aborted carrying the caller's reason, the neutral
+     * [turn-interrupted] marker, an attributable inference-log terminal, gate
+     * release. Deliberately none of the failure accounting: inference:failed /
+     * inference:exhausted feed the consecutive-failure streak, hard-down ops
+     * alerts, the poison-history breaker and the "[inference-failed]" marker —
+     * all of which told a resident, in the user's voice, that its turn failed
+     * and advised remediation for a failure that never happened — and
+     * errorPolicy would relaunch the very inference someone just stopped.
+     *
+     * Only called while `agent` still owns stream `myStreamId`.
+     */
+    private settleDeliberateCancel;
+    /**
+     * Terminal for a stop the framework itself made: stop()'s shutdown and an
+     * operator's quiesce abandon, each recorded in frameworkCancelledStreams
+     * before the cancel. A stream may report that cancel as `aborted`, as
+     * `error`, by just closing, or by throwing, and each of those ends here
+     * (through endFrameworkCancel()), so the four cannot drift: settle the
+     * turn (an ephemeral run rejects with the stop's own text), an
+     * attributable inference-log terminal, ONE inference:aborted
+     * carrying the framework's reason, gate release. No [turn-interrupted]
+     * marker, since nobody stopped the agent, and none of the failure
+     * accounting that inference:failed / inference:exhausted drive.
+     *
+     * The script abort, reset and settle happen only while `agent` still owns
+     * stream `myStreamId`; the log line and the trace are written either way.
+     */
+    private settleFrameworkCancel;
     /**
      * Get all registered modules.
      */
     getAllModules(): Module[];
+    /** Read the namespaced utility catalogue without adding first-class model tools. */
+    getAllUtilities(): import('./types/index.js').ToolDefinition[];
     /**
      * Get all available tools from all modules and MCPL servers.
      */
@@ -887,11 +1168,22 @@ export declare class AgentFramework {
      *  a writable workspace mount for storage). */
     private referenceFetcherInstance?;
     private getReferenceFetcher;
-    /** Register every RFC-005 reference in a tool-result content array against
-     *  its server, then eagerly fetch the ones inside the autofetch envelope
-     *  (below the eager ceiling, connection origin — never worse than the
-     *  server having inlined the bytes). Failures are non-fatal: the stub then
-     *  says fetch_reference instead of a path. */
+    /** Register every RFC-005 reference in an MCPL peer's tool-result content
+     *  against its server, then fetch by `mode`:
+     *  - `register`: nothing. An in-process caller (executeMcplToolCall) may
+     *    never show the result to an agent, and an eager fetch would spend the
+     *    server's fetch budget, which the agent's own fetch_reference needs, on
+     *    bytes nobody asked for. A stub later made of a registered reference is
+     *    bound, so fetch_reference can fetch it.
+     *  - `model`: eagerly fetch the ones inside the autofetch envelope (below
+     *    the eager ceiling, connection origin — never worse than the server
+     *    having inlined the bytes). Failures are non-fatal: the stub then says
+     *    fetch_reference instead of a path.
+     *  - `script`: as `model`, then fetch every reference ("eagerly lazy"): a
+     *    script receiving a result is the strongest available signal that the
+     *    bytes are wanted (scripts process, they do not browse), so the stub it
+     *    receives carries a workspace path it can open directly.
+     *  A uri the result calls expired is fetched in no mode. */
     private autoFetchReferences;
     /** Core agent_settings keys — extension keys must not collide with these. */
     private static readonly AGENT_SETTINGS_CORE_KEYS;
@@ -931,18 +1223,24 @@ export declare class AgentFramework {
      *  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 draining isn't a supported order. */
+     *  made while a stop() is still running is refused. */
     private guardSpillsClosedFor;
     /** 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). */
+     *  (agent-framework #277). The setting is read from framework/state's
+     *  toolResultGuards by the agent's own name. A read that fails, or a
+     *  toolResultGuards that isn't an object, throws, naming the state: taken
+     *  as no setting, the agent would take its recipe's guard, and the next
+     *  guard change would store over a toolResultGuards that isn't an object. */
     private adoptToolResultGuard;
     /** Each guard that may have queued storage work, once, by agent name: the
      *  live agents' and every other that isn't idle. */
     private guardsWithStorageWork;
+    /** `think` for one agent: its same-round policy, and `skip_reply` named only where the agent may call it. */
     private buildThinkTool;
     /** agent_settings tool definition with module extension fields merged in. */
     private buildAgentSettingsTool;
+    private warnEmptyUtilityPermissions;
     private getToolsForAgent;
     /** Available is independent of presentation visibility; execution callers keep this surface. */
     private availableToolsForPresentation;
@@ -1014,9 +1312,15 @@ export declare class AgentFramework {
     static readonly QUIESCE_TIMEOUT_MAX_MS = 600000;
     static readonly QUIESCE_TIMEOUT_DEFAULT_MS = 120000;
     /**
-     * Enter quiesce mode: persist the flag, suppress gate deliveries, pause all
-     * MCPL data planes, and wait for in-flight turns to settle (turn-alive is
-     * `activeTurnTokens`, which spans dequeue → settled teardown). Idempotent.
+     * Enter quiesce mode: write the deferred-write queue, persist the flag,
+     * suppress gate deliveries, pause all MCPL data planes, and wait for
+     * in-flight turns to settle (turn-alive is `activeTurnTokens`, which spans
+     * dequeue → settled teardown). Idempotent, but for the queue's write, which
+     * every call makes first: when the queue can't reach disk, because its
+     * write fails or it's over the cap, the call rejects with a
+     * QuiesceBlockedError and the host's mode as it was, unless it has
+     * `abandon`, which goes on with the queue in memory and an alert
+     * (writeDeferredWritesForQuiesce).
      *
      * On drain timeout the host STAYS quiesced (`drained: false` in the
      * result); with `abandon: true` the undrained streams are cancelled via a
@@ -1046,12 +1350,18 @@ export declare class AgentFramework {
     }): Promise<HostModeStatus>;
     private runResume;
     /**
-     * Land every deferred write whose target has no turn alive, one at a time,
-     * acknowledging each durably as it lands (the persisted queue is rewritten
-     * after every message). A crash mid-flush therefore replays exactly the
-     * un-acked remainder at the next boot — no loss, no duplicates. A write
-     * the store REJECTS is logged and acked too: replaying a poison message
-     * forever would wedge every later boot on it.
+     * Land every deferred write whose target has no turn alive, as one batch
+     * acknowledged once: the chronicle is synced, then the persisted queue is
+     * rewritten without the batch (ackDeferredWrites). Until then the batch
+     * stays in the durable queue, so a crash mid-flush replays it at the next
+     * boot, which skips each entry that already landed, by its deferredWriteId
+     * — no loss, no duplicates. The batch is stored in queue order, whatever
+     * its targets (writeDrainedInOrder). A write the store rejects stays
+     * queued, logged, with what is queued behind it for its target, so the
+     * flush never stores that target's later entries ahead of it, and other
+     * targets' entries go on. (A write that isn't deferred can still land
+     * ahead of it, such as one for an idle agent once the host has resumed.)
+     * A boot that meets it again logs it and goes on.
      *
      * Per-target: an agent whose turn is still alive keeps ITS messages
      * deferred for its own turn boundary; everyone else's flush now.
@@ -1078,12 +1388,38 @@ export declare class AgentFramework {
      * Which of `ids` already exist in some agent's store as a landed deferred
      * write (`metadata.deferredWriteId`). Scans each context manager's recent
      * tail blob-free — an interrupted flush is always within the last few
-     * hundred slots — and tolerates facades without windowed reads.
+     * hundred slots — and tolerates facades without windowed reads. A context
+     * that can't be read throws, naming its agent: counted as holding none, a
+     * write that landed there before its ack would land a second time.
      */
     private landedDeferredWriteIds;
-    /** Atomic JSON write for the recovery files (tmp + rename, 0600) — the
-     *  same idiom as the Discord awareness outbox. */
+    /** Atomic, durable JSON write for the recovery files. The document goes to
+     *  a temp file at 0600, which is synced and renamed over the record, so
+     *  the new record's data is asked to reach the disk before the rename
+     *  publishes it. Then the directory is synced, for the record's entry in
+     *  it, and its parent, for the directory's own entry, which is new when a
+     *  write, this one or an earlier one, had to make the directory; levels
+     *  above are left to the filesystem. Directories aren't synced on win32,
+     *  which syncs the file alone, or where the filesystem can't sync one
+     *  (syncRecoveryDirectory). A failure before the rename removes the temp
+     *  file, if it was made, and throws an error saying the record was left as
+     *  it was, with the original as its cause and its code kept. A directory
+     *  sync that fails, other than where the filesystem can't sync one, is
+     *  raised as an ops alert, not thrown: the new record is in place, and the
+     *  callers go on to record it as written. */
     private writeRecoveryFile;
+    /** Syncs the directory a recovery file is in, or that directory's parent,
+     *  so its entries reach the disk. win32 is left out. So is a sync refused
+     *  with EINVAL or EBADF, the answer where the filesystem or system can't
+     *  sync a directory: that refusal would come again on every write, and
+     *  PostgreSQL's fsync_fname_ext lets the same two go. Any other failure is
+     *  raised as an ops alert naming the record. */
+    private syncRecoveryDirectory;
+    /** A recovery file's document, or undefined when there's no file. Only a
+     *  missing file means none was written: any other failure to read it
+     *  (EACCES, ENOTDIR, EIO, which existsSync would answer false for)
+     *  throws, and text that isn't JSON throws a StoredFormError carrying
+     *  the parser's reason, since reading it again won't change it. */
     private readRecoveryFile;
     private warnRecoveryFallbackOnce;
     /**
@@ -1094,9 +1430,86 @@ export declare class AgentFramework {
      * window is operator-length, not turn-length. Lives in the
      * branch-independent recovery file so a rollback cannot orphan it.
      * Deferrals outside a quiesce window (turn-alive, mid-tool-cycle) are
-     * still memory-only: they flush within the turn, as before.
+     * mirrored only while such a queue is still persisted; otherwise they are
+     * 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 can't carry injected messages, 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
+     * whose sync failed is in the store, where a later sync can still put it
+     * on disk (writeDeferredWritesSlot). The queue stays in memory and
+     * mirrored, so its next change writes it again. Until a write succeeds, a
+     * restart restores what the record holds, or doesn't start if it can't
+     * read the record: it loses writes queued since, and brings back an entry
+     * withdrawn since (removePlacement, RFC-006's removal of an unread
+     * deferred write) that it still lists. The callers go on: a
+     * deferral's caller has already answered its source, so failing it would
+     * lose a write that can still land at resume. The first such write after
+     * one that succeeded raises an ops alert, and a line says when a write
+     * succeeds again (deferredWritesFellBehind). quiesce() writes the queue
+     * itself before it changes the host's mode, and refuses instead, unless
+     * the call has `abandon` (writeDeferredWritesForQuiesce).
      */
     private persistDeferredWrites;
+    /**
+     * Write the queue to its record as it stands, when the host is quiesced
+     * (`quiesced`, which quiesce() passes before it sets the flag) or the
+     * queue is mirrored: the queue when it holds anything, and an empty one
+     * over a record that held one. What the write throws is thrown. A queue
+     * whose JSON is longer than the cap writes nothing.
+     */
+    private writeDeferredWrites;
+    /** Store only, the slot is the record, and a write isn't on disk until the
+     *  store syncs, so a sync that fails is the write's failure, as in
+     *  persistHostMode. The slot is set by then, and a later sync can still
+     *  put it on disk, so writeDeferredWrites marks the queue mirrored before
+     *  it writes; a boot that restores such a queue skips each entry that
+     *  already landed. */
+    private writeDeferredWritesSlot;
+    /** The durable queue: every deferred write not yet acked, pending and
+     *  un-acked, in deferral order. */
+    private durableDeferredWrites;
+    /** Where the queue is recorded, as an operator would look for it. */
+    private deferredWritesRecord;
+    /**
+     * quiesce()'s write of the queue, before it changes the host's mode, as a
+     * quiesced host keeps it: a write held only in memory, such as one
+     * deferred behind a turn still alive, is on disk before quiesce() goes on,
+     * as its record is. When the queue can't reach disk, because its write
+     * fails or it's over the cap, which writes nothing, a call with `abandon`
+     * goes on with the queue in memory and the failure's or the cap's alert.
+     * Any other throws a QuiesceBlockedError naming the ways out, so quiesce()
+     * rejects with the host's mode as it was (store only, the slot set before
+     * a sync that failed leaves the queue mirrored: writeDeferredWritesSlot).
+     * Writes a flush landed stay in the queue until a store sync acks them, so
+     * it first retries an ack whose sync failed: once a sync succeeds they're
+     * on disk, and they leave the queue rather than count against the cap.
+     */
+    private writeDeferredWritesForQuiesce;
+    /**
+     * A write of the queue failed, or met the cap, and quiesce() didn't reject
+     * for it. The queue stays mirrored, so its next change writes it again.
+     * The first such write since one that succeeded raises an ops alert naming
+     * the record, and the rest of the run raises none. A failed write's own
+     * line is logged each time (persistDeferredWrites), and the cap's line the
+     * first time the cap is met in a run, whatever began it. On a host that is
+     * or is about to be quiesced, both say to resume before any restart, since
+     * a quiesced host lands its deferred writes only at a resume.
+     */
+    private deferredWritesFellBehind;
+    /** A write of the queue succeeded after a run of failures: say that the
+     *  record has caught up. */
+    private deferredWritesCaughtUp;
+    /**
+     * Restore the deferred-write queue a crash or a stop left durable. Nothing
+     * stored is an empty queue. A queue that can't be read, or that reads as
+     * anything but a queue, throws, since taken as empty the next deferral
+     * would replace the stored one; so does a context that can't be checked
+     * for writes that already landed (see landedDeferredWriteIds).
+     */
     private restorePersistedDeferredWrites;
     /**
      * Operator-driven maintenance: run (or join) one bounded compression pass —
@@ -1200,11 +1613,12 @@ export declare class AgentFramework {
     /** previewAgentRuntimeSettings for an agent in hand: boot restore previews one not yet registered. */
     private previewRuntimeSettingsFor;
     /**
-     * Check if process logging is enabled.
+     * Whether process events and their responses are written to Chronicle
+     * (`processLogging.persist`). `process:completed` trace events are emitted
+     * either way.
      */
     isProcessLoggingEnabled(): {
         persist: boolean;
-        broadcast: boolean;
     };
     /**
      * Get the underlying store.
@@ -1241,13 +1655,26 @@ export declare class AgentFramework {
      */
     getMembrane(): Membrane;
     getSessionUsage(): SessionUsageSnapshot;
+    /** Restore the usage totals a prior session stored. None stored starts
+     *  fresh (the constructor's tracker). Totals that can't be read, or that
+     *  read as anything but totals, throw: taken as none, the next inference's
+     *  persistUsageState would store fresh totals over them.
+     *
+     *  This is create()'s first read of framework/state, so it also refuses a
+     *  framework/state that isn't an object: every reader of that state would
+     *  take it as holding nothing, and its first write would replace it. */
     private restoreUsageState;
     private persistUsageState;
-    /** An agent's persisted record, or null when it has none; throws when the store can't be read. */
+    /** An agent's persisted record, or null when it has none. Throws the
+     *  store's error when it can't be read, and a StoredFormError when what's
+     *  stored for the agent, or the map that holds every agent's, isn't a record. */
     private readAgentRuntimeSettings;
     private validatePersistedAgentRuntimeSettings;
     /** Load resident-set inline caps from framework state, dropping (loudly)
-     *  anything that fails the same validation the live update enforces. */
+     *  anything that fails the same validation the live update enforces. A
+     *  failed read is logged and boot goes on without them: nothing is lost,
+     *  since persistToolResultInlineCap reads the stored caps again before it
+     *  writes one. */
     private readPersistedToolResultInlineCaps;
     /** Write (cap) or clear (null) one agent's resident-set inline cap. */
     private persistToolResultInlineCap;
@@ -1303,20 +1730,27 @@ export declare class AgentFramework {
      */
     private recordCompiledContextBudget;
     private persistAgentRuntimeSettings;
-    /** Persist (or clear, with null) the host quiesce mode. First process-global
-     * key in the framework/state slot: quiesce survives a restart BY DESIGN — a
-     * crash mid-surgery must come back up NOT serving against a half-repaired
-     * store. Resume is always reachable (public method, WS/HTTP, control-plane
-     * host/command), and every quiesced boot logs a loud banner. */
+    /** Persist (or clear, with null) the host quiesce mode: in the recovery file
+     * when there's a path for one, and in framework/state's hostMode otherwise.
+     * (A boot with a path reads that legacy hostMode only while no file exists.)
+     * Quiesce survives a restart BY DESIGN — a crash mid-surgery must come back
+     * up NOT serving against a half-repaired store. Resume is always reachable
+     * (public method, WS/HTTP, control-plane host/command), and every quiesced
+     * boot logs a loud banner. */
     private persistHostMode;
     /** The recovery file wins whenever it exists; the branch-local slot is
-     *  read only for stores that predate it (or store-only configs). */
+     *  read only for stores that predate it (or store-only configs). No record
+     *  is a host that was never quiesced. A record that can't be read, or that
+     *  reads as anything but a host-mode record, throws: taken as "not
+     *  quiesced", a host that stopped mid-maintenance would boot serving. */
     private readHostMode;
     /**
      * Create an ephemeral agent that is NOT registered in the main event loop.
      *
-     * Used by SubagentModule (and similar) to create short-lived agents
-     * that are driven externally (not by the framework's event loop).
+     * Used by SubagentModule (and similar) to prepare short-lived agents.
+     * Call runEphemeralToCompletion(agent, contextManager) to register and run
+     * the returned agent. Framework-created identities have tool authority only
+     * while registered; public tool calls before a run or after retirement fail.
      * The returned agent has its own ContextManager on a namespaced state
      * within the framework's shared Chronicle store — messages go to
      * `{namespace}/messages`, context log to `{namespace}/context`.
@@ -1395,6 +1829,15 @@ export declare class AgentFramework {
     /** Discoverability for event tags (MCPL RFC-001): the reserved chat:* core,
      *  each connected server's declared tag ontology, and gate.js status. */
     private static readonly EVENT_TAGS_TOOL;
+    /** How long, in days, a draft beyond a resident's newest is kept (KEEP_IDLE_MS). */
+    private static readonly DRAFT_KEEP_DAYS;
+    /** 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". */
+    private static readonly DRAFTS_TOOL;
     /** Synthesized save_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
@@ -1414,23 +1857,24 @@ export declare class AgentFramework {
     private static readonly CHAT_CORE_TAGS;
     /**
      * Mark an inference refusal visibly: react on the message that holds the
-     * conversational locus (the most recent incoming channel message) with a
-     * category-specific emoji. Best-effort — failures are logged, never thrown,
-     * and non-Discord loci are silently skipped.
+     * refused agent's conversational locus (the most recent incoming channel
+     * message; an ephemeral run has none, so a subagent's refusal marks no
+     * message) with a category-specific emoji. Best-effort — failures are
+     * logged, never thrown, and non-Discord loci are silently skipped.
      */
     private reactToRefusal;
     /**
-     * Rewind the single turn that fed a refused generation: redact the newest
-     * message the agent did NOT author (a tool result, or an incoming message)
-     * and inject a metadata-only marker in its place. The marker carries a
-     * *description* of what was withheld (kind + size), never the content — so it
-     * cannot itself re-trip the classifier — while the raw record survives in the
-     * chronicle log for forensics. Returns a record describing the removal, or
-     * null if there is nothing eligible to rewind (e.g. only the agent's own
-     * turns, or a prior system marker, remain).
+     * Shed the newest turn: remove the newest message that isn't a system
+     * message, whoever wrote it, with the rest of its exchange (the tool_use
+     * turn paired with a tool result, and the whole of a body stored in
+     * shards). It adds no marker; the caller keeps one consolidated marker for
+     * the episode (updateRewindMarker). The returned record's descriptor says
+     * what was removed and its size, never the content, while the raw record
+     * survives in the chronicle log for forensics. Returns null when only
+     * system messages remain.
      *
-     * Shared by the auto path (on `stop_reason: refusal`) and the `/rewind`
-     * host command.
+     * Shared by the refusal rewind, automatic or forced by `/unstick`, and by
+     * the shed after inference exhaustion (quarantinePoisonedHistory).
      */
     private shedNewestTurn;
     /**
@@ -1443,11 +1887,12 @@ export declare class AgentFramework {
      */
     private updateRewindMarker;
     /**
-     * Announce a refusal-rewind on the conversational surface (Discord), used
-     * when the withheld turn was a *human* message so it isn't dropped silently.
-     * Best-effort; mirrors reactToRefusal's locus resolution.
+     * A turn that ended WITHOUT a refusal (a natural completion that wasn't
+     * one, or a tool-ended turn) ends the rewind episode: the model responded.
+     * Leave the consolidated marker in place as the durable record; just
+     * clear the per-episode counters, and report a forced `/unstick` done.
      */
-    private announceRewind;
+    private endRefusalEpisode;
     /**
      * Conclude an active `/unstick` session: post the outcome (what was shed and
      * whether the model stopped refusing) to the channel the command came from,
@@ -1601,6 +2046,14 @@ export declare class AgentFramework {
     }): OperatorLogEntry[];
     /** Where the operator log is written, or undefined when disabled. */
     getOperatorLogPath(): string | undefined;
+    /**
+     * A default name for an operator branch: `base`, the timestamped name the
+     * caller passes, when the store doesn't hold it, else the first of `base-2`,
+     * `base-3`, … that it doesn't hold (firstFreeBranchName). Two changes of one
+     * kind made one after the other in a millisecond then get a branch each,
+     * where the second used to be refused under the first one's name.
+     */
+    private newOperatorBranchName;
     /**
      * The surgery gate — STORE-wide, not per agent. A branch switch moves the
      * active chronicle branch for every context manager sharing this store,
@@ -1645,7 +2098,7 @@ export declare class AgentFramework {
         messageId: string;
         requester?: OperatorRequester;
         note?: string;
-        /** Branch name for the fork (default `rollback/<agent>/<ts>`). */
+        /** Branch name for the fork (default `rollback/<agent>/<ts>`, or with `-2`, `-3`, … appended when the store already holds that name). */
         branchName?: string;
     }): Promise<{
         agentName: string;
@@ -1671,7 +2124,8 @@ export declare class AgentFramework {
     }>;
     /**
      * Suppress specific messages from the live context without touching the
-     * source branch: fork at the current head (`suppress/<agent>/<ts>`), redact
+     * source branch: fork at the current head (by default `suppress/<agent>/<ts>`,
+     * numbered `-2`, `-3`, … when the store already holds that name), redact
      * the messages on the fork, switch to it. Shards of a body group are always
      * removed together. Discord originals get awareness markers via the outbox;
      * the batch is `explicit`-activated only after every removal succeeded, and
@@ -1688,7 +2142,7 @@ export declare class AgentFramework {
         messageIds: string[];
         requester?: OperatorRequester;
         note?: string;
-        /** Branch name for the fork (default `suppress/<agent>/<ts>`). */
+        /** Branch name for the fork (default `suppress/<agent>/<ts>`, or with `-2`, `-3`, … appended when the store already holds that name). */
         branchName?: string;
     }): Promise<{
         agentName: string;
@@ -1755,13 +2209,13 @@ export declare class AgentFramework {
      * reconnect or start delivers what is still pending.
      *
      * Like a server's drain, the delivery runs apart from the operation that
-     * started it: it isn't an operator's operation, so stop() doesn't wait for
-     * it. A drain already running when stop() begins runs on while the
-     * connections close, and what it can't deliver stays pending in the
-     * durable outbox. Once stop() has begun, none is started, since there's
-     * no point opening a drain that the teardown is about to cut off: the
-     * marks stay pending, and the next start's barrier reconciles the outbox
-     * with the branch and delivers them.
+     * started it: it isn't an operator's operation. A drain already running
+     * when stop() begins sends nothing more, and stop() waits for it to record
+     * the call it had in flight, which closing the connections ends; what it
+     * hasn't sent stays pending in the durable outbox, unrecorded. Once stop()
+     * has begun, none is started, since there's no point opening a drain that
+     * the teardown is about to cut off: the marks stay pending, and the next
+     * start's barrier reconciles the outbox with the branch and delivers them.
      *
      * @param after What moved the branch, for the log and the alert
      *   ("rollback", "branch switch", "undo" …).
@@ -1808,6 +2262,14 @@ export declare class AgentFramework {
      * Drop a departed agent's checkpoint tree key and turn/redo bookkeeping.
      * Without this, spawn-and-dispose agents leave a key (and in-memory map
      * entries) behind for the life of the store/session.
+     *
+     * Its callers are tearing an agent down: a conversation fork's disposal and
+     * an ephemeral run's end. A throw from the store here would stop that
+     * teardown partway, reject a finished ephemeral run in place of its result,
+     * and at a closure turn's end reject a stream promise that nothing holds.
+     * So a failed removal is logged and goes no further, and the agent's
+     * checkpoints stay in the store under its name, as a crash before its
+     * teardown leaves them.
      */
     private evictTurnCheckpoints;
     /**
@@ -1859,8 +2321,53 @@ export declare class AgentFramework {
      * primary.
      */
     private createConversationAgent;
-    /** Persist the router's generation counters (see hydration in create()). */
-    private persistConversationRouterState;
+    /**
+     * The router's decision for a message or batch on `facts.channelId`, made
+     * once no spawn is in flight for that channel, with a spawn it decides on
+     * already started. A routing that finds its channel's fork being spawned
+     * waits for that spawn to settle and decides then, whatever it would have
+     * decided meanwhile: once the fork is bound, the decision is the fork, and
+     * if the spawn failed, it decides as a message arriving next would, which
+     * proposes the spawn again if the message qualifies. The check, the
+     * decision and the spawn's start are one synchronous step, so at most one
+     * spawn per channel is in flight. Without the wait, a second spawn of the
+     * fork's name failed ("already registered or reserved"), and a message
+     * that didn't qualify on its own was dropped as unrouted; either way its
+     * message was lost. Each path that delivers messages handles them one at
+     * a time, but the event queue and the coalescer run beside each other, and
+     * a spawn can wait, as on its template's annotations
+     * (createConversationAgent); the waiting routing holds its own path for as
+     * long, which none of the spawn's awaits needs.
+     */
+    private routeConversation;
+    /**
+     * Store the router's counters with the spawn's generation, create the fork
+     * the decision names and bind its channel to it, registered in
+     * conversationSpawns under the channel until it settles. The store runs
+     * inside the spawn's promise, still in routeConversation's synchronous
+     * step, so a store that throws rejects the spawn, which each caller reports
+     * as a failed spawn, rather than throwing out of routeConversation before
+     * the caller's try. routeConversation registers a spawn only when none is
+     * in flight for the channel, and only this spawn's settlement removes it,
+     * so the entry it removes is its own. It's removed before anyone waiting
+     * on it resumes, so a waiter that decides again doesn't find it.
+     */
+    private spawnConversationAgent;
+    /**
+     * Store the router's generation counters with a spawn's generation, before
+     * the spawn it names (see hydration in create()). A fork whose counter isn't
+     * stored would have its name reused at the next restart, reopening its
+     * namespace, so a failed read or write throws and the caller refuses the
+     * spawn. The stored counters, the router's own and this spawn's are
+     * merged, each at its highest, in one synchronous step: another channel's
+     * spawn still in flight has stored its counter but not bound it yet, so
+     * the router's map alone would write that counter back down, and the
+     * router's own counters keep the stored ones from going back down when
+     * they read lower, as on a branch with older counters. The merge is a Map,
+     * so a channel id such as "constructor" is a key like any other. The
+     * callers name the channel; the errors name the state and what failed.
+     */
+    private storeConversationGeneration;
     /**
      * Remove a closed conversation fork from the framework: its closure turn
      * has finished, so the home mapping has served its purpose and keeping the
@@ -1906,11 +2413,26 @@ export declare class AgentFramework {
      * replies to the agent) DO still arrive, and nothing warned that answering
      * via option 1 leaves the human's natural un-@'d follow-up invisible (Sol
      * answered four #architecture mentions over four days while the follow-ups
-     * to her own replies were silently dropped). The wording now states the
-     * actual delivery model, and option 1 carries the consequence inline. When
-     * the surface tracks a missed-ambient tally (discord-mcpl sends
-     * `missedMessages`/`missedCharacters` in push origin), the invitation shows
-     * the count — the cost of staying out, as a number, at decision time.
+     * to her own replies were silently dropped). That pass stated discord-mcpl's
+     * delivery model here.
+     *
+     * #406: what reaches the agent from a channel, open or closed, is its
+     * server's delivery, which MCPL leaves to each server. discord-mcpl
+     * subscribes a channel on channels/open and unsubscribes it on
+     * channels/close. slack-mcpl keeps its own subscription, which decides
+     * whether a conversation's ordinary messages arrive, open or closed; open
+     * state only picks channels/incoming or push/event. So the invitation says
+     * only that messages addressing the agent reach it whether or not it opens
+     * the channel: it is shown only when one has arrived from a closed channel,
+     * and both servers deliver them either way. What else arrives is for the
+     * server to say on its push. Option 1 says a reply opens the channel,
+     * because routeSpeech opens a closed channel before delivering into it. Its
+     * old follow-up warning assumed the channel stays closed after the reply,
+     * which that open makes false (and on discord-mcpl, channels/open also
+     * subscribes). When the surface tracks a missed-ambient tally
+     * (discord-mcpl sends `missedMessages`/`missedCharacters` in push origin),
+     * the invitation shows the count — the cost of staying out, as a number, at
+     * decision time.
      */
     private buildClosedChannelInvitation;
     /**
@@ -1919,13 +2441,55 @@ export declare class AgentFramework {
      * id is reassigned to another endpoint (restartMcplServer with a new config).
      */
     private coalescingBinding;
-    private initializePushCoalescer;
+    /**
+     * Report one inbound acceptance to the observer, if one is installed
+     * (InboundAcceptanceObserver). Called where an envelope is first created —
+     * never for a delivery that reuses a frozen one. A failing observer is
+     * reported loudly (stderr + trace) and never affects delivery.
+     */
+    private noteInboundAccepted;
+    /**
+     * The inbound source envelope (mcpl/inbound-source.ts) of an item that
+     * belongs to a registered channel. The one place the framework decides
+     * which conversation an inbound item came from; every lane calls it at the
+     * point the host accepted the item, or reuses the envelope frozen then.
+     * `acceptedAt` falls back to now only for an event no admission path
+     * stamped (a direct framework caller), which is the closest observation.
+     */
+    private channelSource;
+    /** Source envelope of a channels/incoming event (lane facts as given). */
+    private channelEventSource;
+    /** Source envelope of a push event: its derived channel, else unscoped. */
+    private pushSource;
+    /**
+     * Source envelope for conversational input from a non-channel surface: a
+     * module's messages in response to an `external-message` (console, TUI) or
+     * `api:message` event. An event whose metadata names a channel is not a
+     * surface conversation and gets none (never a guessed identity).
+     */
+    private surfaceSourceFor;
+    /**
+     * The push coalescer, built and restored from its stored receipts and
+     * batches. initializeMcpl calls this before it builds anything else, so a
+     * refusal here leaves the MCPL subsystem as it was. Nothing stored is a
+     * coalescer with no history. What can't be read, reads as anything but
+     * this version's snapshot and receipts, or can't be restored, throws, and
+     * so does an agent's context that can't be checked for an occurrence
+     * already delivered (wasPublished): taken as no history, the next
+     * acceptance's receipt and the next flush would replace what's stored, and
+     * taken as undelivered, an occurrence would be delivered again.
+     */
+    private restorePushCoalescer;
+    /** Install a coalescer restorePushCoalescer built: none of this can fail. */
+    private installPushCoalescer;
     /**
      * Durability barrier for coalescing (RFC-006 §3.1/§3.2): everything
-     * written so far is fsynced before the caller proceeds. Group-committed —
-     * all acceptances that arrive in one event-loop turn share one
-     * `store.sync()` — so throughput is bounded by fsync rate per batch, not
-     * per message.
+     * written so far is fsynced before the caller proceeds. Commits asked for
+     * in the same event-loop turn would share one `store.sync()`, but the
+     * coalescer asks for every commit under its lock and holds the lock until
+     * the commit resolves, so no two share one. Each acceptance makes an fsync
+     * of its own, and so does each coalesced message a channels/incoming
+     * request newly admits, one at a time.
      */
     private commitCoalescingDurable;
     private scheduleCoalescingSnapshot;
@@ -1941,6 +2505,11 @@ export declare class AgentFramework {
     /** Deliver through the lane's ordinary path; report where it landed. */
     private deliverCoalesced;
     private wakeForCoalescedBatch;
+    /** Queue a wake for each agent of the batch's audience, when its latest
+     *  occurrence triggers inference. `plain`: an ordinary push wake, without
+     *  the subject a withdrawal of the batch's wakes goes by, for a render
+     *  placed in its agent's deferred queue (wakeToRead). */
+    private queueCoalescedWakes;
     /** Withdraw unstarted wakes whose sole cause is this subject (§4.2). */
     private cancelCoalescedWakes;
     /**
@@ -1987,17 +2556,134 @@ export declare class AgentFramework {
     private derivePushEventChannel;
     private processInferenceRequests;
     /**
-     * Metadata for rows the agent's current turn stores: a silent heartbeat
-     * tick stamps each of them (assistant responses, tool_result rows) so they
-     * stay identifiable after the turn — request builds key the tick separator
-     * on it, and a later retention policy can find or collapse them. The stamp
-     * names the agent: residents share one message slot and a broadcast tick
-     * reaches each of them with the same eventId. Undefined for ordinary
-     * turns, whose rows are stored exactly as before.
+     * Stamps for the rows the agent's reply stores in its current turn: its
+     * assistant responses, its tool_result rows (through `storeResults`), and
+     * the contained-wrapper row that stands in for a response. The turn's other
+     * stores (a delivery receipt, a routing notice, a deferred flush) aren't the
+     * reply's, and carry none.
+     * - A silent heartbeat tick stamps each of them for the whole turn, with the
+     *   separator text its request rendered. The stamps keep every row of the
+     *   tick identifiable after the turn, for a later retention policy to find
+     *   or collapse. The stamp names the agent: residents share one message
+     *   slot, and a broadcast tick reaches each of them with the same eventId.
+     * - A `[Continue]` prompt stamps the rows of each round that follows it
+     *   (`turnPrompts`).
+     * Request builds render each turn before the first surviving assistant row
+     * that carries its stamp and that they can recognise: one with a tool call,
+     * or with signed or redacted thinking (see silent-heartbeat.ts). The
+     * tool_result rows and the wrapper row are stored as `user`, so their
+     * stamps place nothing: they mark each row as the reply's.
+     * Undefined for ordinary turns, whose rows are stored exactly as before.
+     * (Named for its first use, the silent tick.)
      */
     private silentTurnRowMetadata;
-    /** Record plain-prose segments this turn suppressed. */
+    /** Record plain-prose segments this turn suppressed without drafts (proseRouting=disabled). */
     private recordProseSuppression;
+    /**
+     * Silenced plain speech: an explicit send holds it as resendable drafts; a
+     * deliberate silence (skip_reply, a silent turn, or a private think in
+     * the same native round, where that policy applies: an XML-mode round has
+     * no verbatim content to route live, so its prose is routed at the turn's
+     * end as ordinary speech) keeps it private —
+     * counted for the receipt, never drafted. `segments` are the runs exactly
+     * as written (splitProseRuns), so a draft keeps the resident's words byte
+     * for byte. What it holds, keeps or moves is the round's turn's
+     * (round.routing), whenever the hold runs.
+     */
+    private holdSilencedProse;
+    /**
+     * Hold plain speech as drafts (src/prose-drafts.ts) instead of
+     * letting it vanish: journaled durably and recorded for the receipt of the
+     * turn whose round it came from (opts.routing). `notice: 'now'` also
+     * queues a private notice naming them, which
+     * the resident hears at its next tool boundary — only when the live stream
+     * presents mid-turn injections. Otherwise the turn-end receipt names them
+     * (or, after a crash, the next turn's catch-up). Drafts the journal cannot
+     * hold are reported in the receipt: their words remain in history only.
+     */
+    private holdProseDrafts;
+    private static readonly DRAFT_REASON_TEXT;
+    private static readonly DRAFT_REASON_SHORT;
+    private draftsHeldNotice;
+    /** Compact local time for draft listings. */
+    private draftTime;
+    /** A draft's opening words, for the drafts tool's listing only. */
+    private static draftPreview;
+    private static destinationText;
+    /** One line per draft: id, state, when, why, size, preview. */
+    private draftLine;
+    /** A draft's state in words that claim only what is known. */
+    private draftStateText;
+    /** Why an unconfirmed draft may already have been posted, in full. */
+    private riskText;
+    /** Whether an attempt with no outcome is still out: its draft's latest,
+     *  while that draft is being sent. Otherwise it never got one (a crash). */
+    private attemptIsOut;
+    /** Why an attempt has no outcome, in a risk's words. */
+    private noOutcomeText;
+    /** A delivered draft's historical receipt. */
+    private draftReceipt;
+    /**
+     * Turn start (or after a crash): name, privately and before the turn's
+     * compile, any open drafts no notice on the current branch names: none
+     * reached the history (a crash, an aborted turn), or a rollback or branch
+     * move took the notices away. Every draft it marks is named by id, newest
+     * first: the newest eight with their state and why each was held, the rest
+     * by id. Like every notice, it quotes none of their words; the drafts tool
+     * shows them. A draft a recent message already names is recorded as
+     * noticed rather than named again: its notice landed after its turn ended,
+     * as a bounce does when a delivery runs after a tool ends an explicit turn.
+     * It reads only the recent history (draftsNamedInHistory), so its notice
+     * claims no more than that. Left out are the open logical turn's own
+     * drafts, which its receipt names and its settlement records
+     * (settleTurnDrafts), and drafts a notice still waiting in the deferred
+     * queue names.
+     */
+    private noticeUnnoticedDrafts;
+    /**
+     * Logical turn end, after the turn's deferred notices are flushed: record
+     * as noticed exactly the drafts a stored message names (the receipt, a
+     * held-draft notice, a bounce notice), each with the message that names
+     * it. One whose notice never reached the history stays unnoticed, for the
+     * next turn's catch-up. The turn's draft tallies are spent here.
+     */
+    private settleTurnDrafts;
+    /** Record each named draft as noticed, with the message that names it
+     *  (draftsNamedInHistory). */
+    private recordDraftNotices;
+    /** How far back draftsNamedInHistory looks: this turn's notices are near
+     *  the end. One beyond it leaves its draft for the next turn's catch-up. */
+    private static readonly DRAFT_NOTICE_SCAN;
+    /** Which of these drafts a stored notice or receipt OF THIS RESIDENT names
+     *  (draft ids are unique only per resident, and residents can share one
+     *  history), each with the newest message that names it, reading only the
+     *  recent history, where this turn's notices are. */
+    private draftsNamedInHistory;
+    /** Page size for drafts(action: "list"). */
+    private static readonly DRAFTS_PAGE;
+    /** Drafts with a delivery attempt in flight, `${agent}\u0000${id}`: a
+     *  parallel resend (or `{{unsent}}`) of the same draft is refused. */
+    private draftsInFlight;
+    /** The drafts in draftsInFlight whose attempt is out right now (journaled,
+     *  its publish awaited). A dismissal of one is refused, and the resident
+     *  told to wait for that result, since a dismissal can't call back words
+     *  already on their way. A draft only queued in a resend batch can still
+     *  be dismissed: the batch honours that when it reaches the draft. */
+    private draftsSending;
+    /** The drafts tool's answer to a resident's call, from the model's own
+     *  dispatch or an agent-origin call through executeToolCall (a puppet's):
+     *  a failure the handler throws is answered as one. */
+    private draftsToolResult;
+    /**
+     * The resident's `drafts` tool: list, read, resend and dismiss its own held
+     * drafts. Private to the calling resident. `resend` is an explicit send:
+     * each draft is published verbatim, in order, through the normal publish
+     * executor, its attempt journaled durably before the request leaves.
+     */
+    private handleDraftsTool;
+    /** Why a draft can't be resent now (dismissed, or possibly already posted
+     *  without the resident's confirmation), or undefined when it can. */
+    private resendRefusal;
     /** Record a successful plain-prose delivery for this turn's receipt. */
     private recordProseDelivery;
     /**
@@ -2079,12 +2765,15 @@ export declare class AgentFramework {
      */
     private repinTurnLocus;
     /**
-     * Durable window notice for a channel the agent did not ask to open —
-     * subscription-policy admission, or an open forced by the agent's own
-     * delivery into a closed channel. The agent must always learn that new
-     * traffic will start flowing, and that `channel_close` opts out (their
-     * decision outranks policy). System message: never triggers inference,
-     * never conversational, never locus-eligible.
+     * Durable window notice for a channel the agent did not ask to open: a
+     * subscription-policy admission, announced as the decision before its
+     * transport RPC (a failed open keeps the decision, and channel_list shows
+     * transport state), or an open that the agent's own delivery or reply
+     * caused (`opened-by-delivery`, `opened-by-reply`), once its transport is
+     * confirmed. Either way it names `channel_close` as the opt-out (their
+     * decision outranks policy). What an open channel delivers is its server's
+     * to say (#406), so the notice doesn't promise its traffic. System message:
+     * never triggers inference, never conversational, never locus-eligible.
      */
     private recordChannelAutoOpenNotice;
     /**
@@ -2103,7 +2792,7 @@ export declare class AgentFramework {
      * Explicit-prose-routing delivery gateway (docs/explicit-prose-routing.md).
      * Every prose segment of an `explicit`-mode agent flows through here:
      * parse the `>>` prefix, resolve the target, deliver — or bounce to the
-     * clipboard with a resend notice. Misdelivery is structurally impossible:
+     * held bounce draft with a resend notice. Misdelivery is structurally impossible:
      * nothing is ever sent to a destination the model did not name (directly
      * or via the turn's sticky target).
      */
@@ -2116,6 +2805,27 @@ export declare class AgentFramework {
      */
     private admitProse;
     private deliverAdmittedProse;
+    /**
+     * `{{unsent}}` in an envelope body: the latest bounce draft's words. One
+     * that is out (being sent, or queued in a resend) or unconfirmed (its last
+     * attempt may have been posted) is never substituted — nothing is sent,
+     * and the resident gets the facts and the explicit route (drafts resend
+     * with confirmDuplicate) instead. The envelope's own words are held, as a
+     * bounced envelope's would be (unsentWords): one bounce draft with the
+     * whole text, `{{unsent}}` written out and its risk carried, so nothing
+     * the resident wrote has to be typed again. A bare `{{unsent}}` holds
+     * nothing new: its words already are that draft.
+     */
+    private takeUnsent;
+    /**
+     * Deliver an envelope that substituted `{{unsent}}`: the substituted
+     * draft's attempt is journaled durably before the request leaves, and its
+     * outcome after, exactly as a drafts resend would.
+     */
+    private deliverWithUnsent;
+    /** A draft's state as the journal reads it now: after a write that failed
+     *  and was reconciled, whatever reached the journal counts. */
+    private draftStateNow;
     /**
      * Where a delivered round leaves its turn's sticky destination, as the
      * explicit gateway sets it once the round's envelopes run: each `>>`
@@ -2125,9 +2835,35 @@ export declare class AgentFramework {
     private roundDestination;
     /** Locus-preserving explicit publication. Source remains byte-identical in Chronicle. */
     private deliverHybridProse;
+    /** `>>skip_reply {{unsent}}` and its hybrid form: set the latest bounce
+     *  draft aside — unless it is being sent right now, which a dismissal
+     *  can't call back: the resident is told instead. So are a dismissal whose
+     *  recording fails (with the state the draft reads as after it, and whether
+     *  `{{unsent}}` still names it) and one whose draft may already have been
+     *  posted. */
+    private dismissLatestBounce;
     private deliverProseEnvelope;
     /** Cap on consecutive bounce-triggered wakes (notices still append after). */
     private static readonly PROSE_BOUNCE_WAKE_CAP;
+    /**
+     * Words about to be held that may use `{{unsent}}` (a bounce, or an
+     * envelope an explicit send suppressed), under the one re-bounce rule. A
+     * bare `{{unsent}}` is the latest bounce itself, which stays the one draft
+     * of those words rather than being copied. Otherwise the whole authored
+     * text is kept, the token expanded to the latest bounce's words, nothing
+     * stripped or substituted. When that draft may already have been posted
+     * (unconfirmed, or in flight) the words carry its duplication risk: they
+     * can be resent only with confirmDuplicate, like the draft they copy. The
+     * evidence is the risk's own: the copied draft's uncertain attempt, else
+     * the risk that draft itself inherited, else (truly) that it was in flight
+     * when copied.
+     */
+    private unsentWords;
+    /**
+     * A routing envelope that could not be delivered: its words are held as a
+     * draft (the `{{unsent}}` source) and the resident is told, privately.
+     * `{{unsent}}` in it follows the re-bounce rule (unsentWords).
+     */
     private bounceProse;
     /**
      * One-time mode primer (docs/explicit-prose-routing.md): when an agent's
@@ -2149,6 +2885,27 @@ export declare class AgentFramework {
      * newer turn instead.
      */
     private abortDroppedTurn;
+    /**
+     * The stop no stream will carry, collected at a check of the frame whose
+     * window it is (a start's checks before it sends anything, and the checks
+     * at a failure and after a wait to retry): an operator's quiesce abandon of
+     * the turn (the window's mark), else a caller's cancelStream() or
+     * abortInference() made while the agent held no stream, since the start
+     * that dropped an older one at its entry. When both are there, the
+     * framework's own stop is the one that ends the turn, as at a stream's
+     * terminal, and the caller's goes with it.
+     */
+    private takeStartStop;
+    /**
+     * End a start that a stop reached before it sent anything, through the
+     * terminal the same stop gets on a live stream: a caller's stop as
+     * settleDeliberateCancel ends a cancelled stream, with the note saying the
+     * turn was stopped before it sent anything (or, for a start that continues
+     * a turn, before it finished), and a quiesce abandon as
+     * settleFrameworkCancel ends one. Each settles the turn, an ephemeral run
+     * included, and emits the one inference:aborted.
+     */
+    private endStoppedStart;
     /**
      * Body of startAgentStream, split out so the caller's try/finally owns the
      * turn token unconditionally. Returns true iff the token was handed off to
@@ -2166,8 +2923,12 @@ export declare class AgentFramework {
      * call entered through — a public method shared with model callers can
      * never confer module trust, whatever the input claims. Module origin
      * exists only through the private closure handed to ModuleRegistry
-     * (ctx.callTool → executeToolCallFrom with {kind:'module'}). Callers that
-     * don't identify themselves fail safe to agent semantics too.
+     * (ctx.callTool → executeToolCallFrom with {kind:'module'}), which is exempt
+     * from agent allowlists. Registered agents' allowedTools is enforced at
+     * dispatch, including namespaced utility names; utils only grants the
+     * list/describe/run slot. Genuinely unidentified public callers (including
+     * unknown legacy names) remain unrestricted. Framework-created identities
+     * are refused while unregistered, even if their configured list allows it.
      */
     executeToolCall(call: ToolCall): Promise<ToolResult>;
     /**
@@ -2213,6 +2974,7 @@ export declare class AgentFramework {
     /** puppetToolCall's work, run where stop() can wait for it. */
     private runPuppetToolCall;
     private executeToolCallFrom;
+    /** A programmatic call of an MCPL tool: `serverId` and `prefix` as resolveMcplTool matched them. */
     private executeMcplToolCall;
     /** Event-pushing wrapper for the model-driven dispatch path. */
     private dispatchCodeExecutionToolCall;
@@ -2227,6 +2989,12 @@ export declare class AgentFramework {
      * results reach the running script and never the model context.
      */
     private runCodeExecution;
+    /** Background scripts are the primary agent's, or any agent's when no primary agent is named. */
+    private runsBackgroundScripts;
+    /** How many background scripts an agent may have running at once. */
+    private maxBackgroundScripts;
+    /** How many of this agent's background scripts are running now. */
+    private runningBackgroundScripts;
     /**
      * Start a background script: dedicated interpreter, output journaled to a
      * workspace file, wake_agent() available in-script. The tool result
@@ -2275,6 +3043,22 @@ export declare class AgentFramework {
      * live wire copy can reuse the identical strings.
      */
     private buildStoredToolResultContent;
+    /**
+     * A tool result's text as its stored copy is written before any cut, and
+     * what its live copy showed beside that text (see cutStoredToolResult). An
+     * error result is its error text. Any other is serialized by
+     * nonErrorResultText, which retains each inline image BEFORE its
+     * placeholder is written (issue #104): the placeholder embeds the ref, so
+     * the image stays reachable by provenance after the bytes leave the wire.
+     *
+     * The live copy is the stored text itself unless the result is a content
+     * array carrying an inline image, which tryNativeToolResultContent sends
+     * as native blocks. It takes the same arrays the serializer takes block by
+     * block, and shows each image and each reference block's stub whole and
+     * each text block up to where it cuts that block at the cap (`maxChars`,
+     * toolResultCutAt), so those are the ranges of the text it showed.
+     */
+    private storedToolResultText;
     /** Where a tool result labelled `label` is written: `<first writable
      *  mount>/tool-results/<label>.txt`, or null when there is no writable
      *  workspace. */
@@ -2303,14 +3087,45 @@ export declare class AgentFramework {
     private getOrCreateScriptRunner;
     /**
      * Resolve one script-inner tool call to the string the script's tool
-     * function returns. Never rejects — errors become "Error: ..." strings,
-     * matching the managed PTC runtime ("Claude's code receives this error").
+     * function returns, and whether that result is an error (the script's
+     * `.is_error`). Never rejects: a failure without structured content becomes
+     * an "Error: ..." string, matching the managed PTC runtime ("Claude's code
+     * receives this error"), and a structured one its JSON object.
      *
-     * Results are serialized with the HISTORY serializer (images become
-     * placeholders): programmatic tool results are text-only by contract, and
-     * a script variable holding megabytes of base64 helps nobody.
+     * A result without structured content is serialized with the HISTORY
+     * serializer: images become placeholders, since a script variable holding
+     * megabytes of base64 helps nobody. A result with structured content is
+     * one JSON object holding both of the server's views
+     * (scriptStructuredResult), so its content blocks reach the script as the
+     * dispatch gave them, images and payloads included. A module's result that
+     * can't be stored or sent, such as a cyclic object or a BigInt, is already
+     * an error naming the tool when the dispatch returns it (storableToolResult),
+     * so a script reads that error's text.
      */
     private handleScriptToolCall;
+    /** The 5MB protocol safety cap on what a script receives. */
+    private static readonly SCRIPT_RESULT_MAX_CHARS;
+    /**
+     * A structured MCP result as a script receives it: one JSON object holding
+     * both of the server's views, `{ content, structuredContent, isError }`,
+     * plus `error` (the text) on a tool error. `content` is the content array
+     * the dispatch gave this call (the direct reading): the server's blocks as
+     * sent, so payloads and images survive, except that an MCPL peer's blocks
+     * get the treatment RFC-005 gives them on every lane the model reads
+     * (referenceBlockForScript). `structuredContent` is the tool's own JSON, as
+     * sent. Past the size cap the result stays valid JSON: the whole object is
+     * saved to the workspace, and the script gets
+     * `{ isError, oversized: { chars, savedTo } }`. If it can't be saved, the
+     * script gets a failure to materialize the result, saying the tool may
+     * already have completed, never a success missing its result. A result
+     * that can't be converted to JSON (a cyclic object, a BigInt), which the
+     * dispatch's own check makes unlikely here, gets the same object empty,
+     * `{ content: [], structuredContent: null, isError: true, error }`, the
+     * error naming the tool. In every form, the script's `.is_error` is the
+     * `isError` of the object its string holds, and its `.structured` is read
+     * from that string.
+     */
+    private scriptStructuredResult;
     /**
      * Dispatch a script-inner tool call through the NORMAL dispatch path and
      * resolve with its result. The waiter intercept in handleProcessEvent
@@ -2320,9 +3135,10 @@ export declare class AgentFramework {
      * RFC-007: with an `origin`, observers see the call as they see a model
      * call (register, dispatch with its refusal sites, open; the terminal at
      * the waiter intercept), under the inner tool's own name and class.
+     * `turnId` is the turn the call was made in (dispatchToolCall).
      */
     private dispatchScriptToolCall;
-    /** Abort a running script when the agent's turn dies underneath it. */
+    /** Abort the agent's script, running or still starting, when the turn it belongs to ends or is reset to run again. */
     private abortAgentScript;
     private toMembraneToolResult;
     /**
@@ -2330,7 +3146,9 @@ export declare class AgentFramework {
      * convert to Membrane's native ToolResultContentBlock[]. Returns null when
      * the array is text-only (let JSON path handle it; saves a code path).
      * `maxChars`, when provided, caps each accompanying text block so an image
-     * inlined alongside an enormous text payload can't blow the context.
+     * inlined alongside an enormous text payload can't blow the context. A
+     * block is cut as the stored copy is (toolResultCutAt), never inside a
+     * slot, so the stored copy can keep exactly the slots this showed (#403).
      */
     private tryNativeToolResultContent;
     private toolImageLedgerFor;
@@ -2349,8 +3167,15 @@ export declare class AgentFramework {
     private resolveToolResultInlineCap;
     private approximateDecodedBase64Bytes;
     private sanitizeProcessLogValue;
+    /** Writes one inference-log entry. A stream's entries go through its
+     *  driveStream's `logStream`, which gives the stream's usage to one entry
+     *  only; an end that calls this directly for a stream writes a second
+     *  entry for it, and its usage can be counted twice in the log. */
     private logInference;
     private logProcessEvent;
+    /** Count one server's close (see mcplServerCloses). Partially-constructed
+     *  frameworks (tests build them with Object.create) have no map yet. */
+    private noteMcplServerClosed;
     /** Forget one server's RFC-008 class declarations (see the close handler). */
     private dropMcplToolClasses;
     /**
@@ -2386,21 +3211,283 @@ export declare class AgentFramework {
     }>;
     /**
      * Find the MCPL server for a tool: [serverId, prefix], or null.
-     * Prefixes can nest (`foo` and `foo--bar`), so `foo--bar--x` can match
-     * both. The server whose tools/list produced the name decides; a name no
-     * live server listed (stale, or invented by the model) goes to the longest
-     * matching prefix. Never prefix-map insertion order.
+     * The tool listing decides: the server whose tools/list offered the
+     * name, after its tool policy, as of the last tool refresh (a server that
+     * closed since keeps its names until the next one). A name the listing
+     * doesn't hold (invented by the model, or no longer listed) goes to the
+     * longest matching prefix. Prefixes that meet, such as `foo` and
+     * `foo--bar`, are refused at configuration (prefixesMeet, #265), so a name
+     * fits at most one configured server's prefix; this rule doesn't rely on
+     * 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. */
+    private canAgentUseTool;
+    private agentToolPermissionFailure;
+    /**
+     * Why this host refuses a skip_reply call, as the model will read it, or
+     * undefined when it doesn't (skipReplyWakeRefusal): without an EventGate,
+     * any wake_in_seconds; with one, a wake_in_seconds that isn't a number of
+     * seconds. Only when the channel registry handles skip_reply. The dispatch
+     * that refuses the call reads it here, and so does the turn's bookkeeping of
+     * a refused round, for the model's own calls: the silence before it, which
+     * comes back after its round, and in XML mode which round's prose stays
+     * private. A skip_reply round's own prose stays private by the tool's name,
+     * refused or not.
+     */
+    private skipReplyRefusal;
+    private refusesSelfWake;
+    /**
+     * 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
+     * whose stream made it; a foreground script's inner call, the turn of the
+     * code_execution call whose script is running when the call arrives. A
+     * background script's call has none.
+     */
     private dispatchToolCall;
     private dispatchToolCallEvent;
     private addMessage;
+    /** Where addMessage delivers: the named agent, else the primary, else the
+     *  first registered agent. Undefined when there is no such agent. */
+    private deliveryAgent;
+    /** The notes addMessage takes for a message it stored: an arrival for the
+     *  agent when none of its turns is alive or the message was assembled for
+     *  the start now beginning (no tool boundary will weigh it), and one for
+     *  every other resident's open turn. */
+    private noteStored;
     /**
      * Splice out the deferred messages addressed to `agentName` (explicitly
      * via forAgent, or implicitly when it is the primary), leaving other
-     * targets' messages queued for their own boundaries.
+     * targets' messages queued for their own boundaries. With `stopAt`, the
+     * drain ends at the first of them (in queue order) that it matches: that
+     * message and every later one stay queued, so what is drained is always a
+     * prefix of the agent's queue.
      */
     private drainDeferredFor;
+    /**
+     * Put drained entries back into the queue under their ids and seq: out of
+     * the un-acked set, and persisted when the queue is. A memory-only queue
+     * keeps them while the framework runs.
+     */
+    private requeueDrained;
+    /**
+     * Write drained entries in queue (seq) order, whatever their targets:
+     * residents share one message slot, so the order entries arrived in is the
+     * order they're stored. Each target is cut at its own first entry that
+     * can't be stored: that entry and every later one for the same target go
+     * back into the queue under their ids and seq (requeueDrained) before
+     * anything is logged, and other targets' entries go on. Left in the
+     * un-acked set, the next ack would drop them from the durable queue.
+     *
+     * So none of a target's entries lands ahead of an earlier one, and a queued
+     * tool_use that can't be stored keeps the tool_result queued behind it from
+     * being stored alone. (A tool_use that is stored, followed by a tool_result
+     * that can't be, stays stored without it until the tool_result lands at a
+     * later flush. The only queued pair is puppetToolCall's defensive one,
+     * which no path reaches today.) An entry that keeps failing is logged by
+     * id at each flush, and holds its target's later queued writes rather than
+     * letting them land out of order.
+     *
+     * The hold is the queue's alone. A write that isn't deferred is stored at
+     * once and can land ahead of a held entry: a fresh tool_result, whatever
+     * its agent's state, and any write while its agent's turn, stream and tool
+     * cycle are all idle and the host isn't quiesced. So an entry that keeps
+     * failing holds only what is deferred behind it.
+     *
+     * A write can throw after its message is stored: a store listener, the
+     * strategy's handling of the add, or a later shard of a sharded body can
+     * throw once a record is written. Before an entry that threw is put back,
+     * its target's store is read from where it stood before the write, for
+     * messages carrying the entry's `deferredWriteId`. What it finds counts as
+     * written, at most once: the entry isn't requeued and stored a second
+     * time, and what landed, as later compiles render it (asCompiled), is what
+     * it returns as the entry's content. For a sharded body, that can be its
+     * first shards alone, since the append loop stops at the throw; the rest
+     * of the body isn't stored. (Requeued, the
+     * landed shards would be stored twice, and only the rest could not be
+     * appended later without splitting the body.) Boot's scan for landed
+     * writes counts a landed shard the same way. When the store can't be read
+     * back (storedCopiesOf logs it), nothing is found, and the entry is put
+     * back as one that couldn't be stored: if it had landed, a later flush
+     * stores it again.
+     *
+     * Returns what was written (stored, or deferred again by addMessage, whose
+     * id is then empty), in queue order: for one target, a prefix of its
+     * entries. Each comes with its content: as given, unless the store took it
+     * as more than one message (a sharded body) and can be read back, when its
+     * copies are returned joined, as later compiles render them (asCompiled),
+     * or its write threw after storing it (above). `onLanded` hears an entry
+     * whose write threw after storing it, with the id it landed under, as soon
+     * as it's found: before the writes after it, so whatever it records keeps
+     * their order.
+     */
+    private writeDrainedInOrder;
+    /** How many messages the agent's store holds: undefined when its store
+     *  can't say. */
+    private storedCountOf;
+    /** The messages carrying `deferredWriteId` among those the agent's store
+     *  gained from position `from` on, in store order, with their blobs
+     *  resolved, as a request carries them. A sharded body's carry its
+     *  `bodyGroupId`. */
+    private storedCopiesOf;
+    /** The line naming a drained write that threw: one that couldn't be stored,
+     *  which is already back in the queue, or, with `landed`, one stored before
+     *  the throw (for a sharded body, how many of its shards). Logging mustn't
+     *  fail the flush that met it, so a thrown value that has no text is named
+     *  as such. */
+    private logDeferredWriteError;
+    /** Re-add drained entries through addMessage, which stores each or defers
+     *  it again, in queue order and cut per target (writeDrainedInOrder). With
+     *  `bypassDeferral`, each is stored past its target's deferral (stop()). A
+     *  write that threw after storing missed the notes addMessage takes after a
+     *  store, so they're taken for what landed as soon as it's found, before
+     *  the writes after it: an open turn's arrivals keep the order the writes
+     *  landed in, and its newest stays the newest (remainingArrival). */
+    private readdDrained;
+    /**
+     * Where a notice about an agent's own action belongs: its failed reply, its
+     * bounced prose (beside its `{{unsent}}` clipboard), its background script's
+     * wake, the notices about its drafts. Every registered agent's notice is
+     * addressed to that agent, so it lands in the window that agent reads and
+     * waits on that agent's own turn, stream and tool cycle: a conversation
+     * fork or an ephemeral run reads only its isolated slot, and a resident's
+     * notice would otherwise wait on the primary's turn rather than its own.
+     * Residents share one message slot, so a resident's notice can land there
+     * while another resident's turn is alive; agent-framework #291 covers that.
+     *
+     * null when the agent is no longer registered (a fork or a run already
+     * released): there is no window to write, so the caller writes nothing,
+     * traces nothing and requests no wake. The drop is logged here, once. A
+     * failed reply is passed on by name instead (passFailedReplyToPrimary). The
+     * notice of a channel an agent's own send opened follows the same rule in
+     * recordChannelAutoOpenNotice, which passes it on by name too.
+     */
+    private noticeTargetFor;
+    /**
+     * A conversation fork or an ephemeral run has been deregistered. A release
+     * never runs while the host is quiesced: it waits for resume()
+     * (releaseWindowNowOrAfterResume), since a write could land mid-surgery.
+     *
+     * The agent never reads its window again, so every failed-reply notice it
+     * never read is passed to the primary, by name, once: each one stored in
+     * its window above its consumed watermark (flushed there at its turn's end,
+     * or stored while it was idle) and not heard at a tool boundary, and each
+     * one still queued for it. Writes still
+     * queued would wait for a boundary it never reaches, and the flush that
+     * finds it gone would drop them, so they land in its own window now, which
+     * Chronicle keeps for investigation. Its stream is over or cancelled, so it
+     * compiles nothing more. One path still stores after these writes: a
+     * `complete` that arrived while the agent still waited for tools awaits
+     * the spill of its last tool results, and stores them once that resolves,
+     * even if a watchdog has ended the run meanwhile. A tool boundary stores
+     * nothing for a round whose turn was stopped while its results were
+     * prepared.
+     */
+    private releaseWindow;
+    /**
+     * The failed-reply notices stored in `agent`'s window that it never read:
+     * those above the lower of its consumed watermark and the point where the
+     * watermark's branch and the current one part (branchesPartAt), or every
+     * one, when it never compiled. The watermark moves at a compile, and at a
+     * tool boundary whose
+     * stream declares it carries the messages injected there
+     * (markContextConsumed), so a notice the live stream heard is under it, and
+     * one a boundary stored without sending (a turn a tool ended, a budget
+     * restart, a stream that may drop injections) is above it.
+     */
+    private unreadFailedReplies;
+    /**
+     * The last sequence two branches' histories share: Infinity for one branch,
+     * and for two, the point where they part. A branch's records are numbered
+     * on from its branch point (Chronicle gives each record its branch's head
+     * plus one), so up to that point both hold the same records under the same
+     * numbers, and past it each branch's numbers are its own. -Infinity when
+     * the store knows no shared history for them, as for an empty branch.
+     */
+    private branchesPartAt;
+    /**
+     * Release a deregistered fork's or run's window (releaseWindow) now, or,
+     * while the host is quiesced, when it resumes. A release lands the agent's
+     * queued writes in its window, and while quiesced a write could land
+     * mid-surgery; dropping them instead would lose them from both the window
+     * and the recovery queue. Only the window waits: the agent is already
+     * deregistered, so its stream can't dispatch anything more and resume
+     * doesn't weigh its context, and a write addressed to it meanwhile is
+     * treated as for any agent no longer registered (dropped, or passed to the
+     * primary if it's a failed reply).
+     */
+    private releaseWindowNowOrAfterResume;
+    /** resume(): the windows whose release the quiesce window postponed, each on its own. */
+    private runReleasesAfterResume;
+    /**
+     * A fork or an ephemeral run ended before reading that its reply's delivery
+     * to a channel failed: it was released with the notice stored in its window
+     * unread, or its delivery failed after release. (A notice still queued for
+     * it, at release or restored at boot, goes on as the queue entry itself:
+     * queuedFailedReplyForPrimary.) Tell the primary instead, naming the
+     * speaker, so an agent who can still act learns of it and can tell the
+     * human. It gives the reply's length, not its words, which stay in the
+     * speaker's window. Its wording follows the speaker's own notice
+     * (onRouteFailure): a delivery that wasn't confirmed may have been posted,
+     * and neither text says no one saw the reply, since only this channel's
+     * routing failed. Only for a delivery to a channel; a reply that had no
+     * channel to go to (no locus) had no human waiting for it. Never throws:
+     * it runs inside a release, which must complete whatever this write meets.
+     */
+    private passFailedReplyToPrimary;
+    /**
+     * A queued failed-reply entry for `speaker`, who is gone, as the primary's
+     * by-name notice (passFailedReplyToPrimary's words): the same entry, under
+     * its own id and seq, now addressed to the primary. Written through the
+     * drain, it lands stamped with that id, or waits in the queue under it, so
+     * boot's exactly-once holds for it: a crash before the original's ack
+     * replays one entry, never the original and a separate notice. null when no
+     * one is told (logged): a reply that had no channel to reach, or no primary.
+     */
+    private queuedFailedReplyForPrimary;
+    /** The primary's by-name notice of `speaker`'s failed reply, or null when no
+     *  one is told, which is logged here (see passFailedReplyToPrimary). */
+    private failedReplyNoticeForPrimary;
+    /**
+     * A channel as a notice names it: the label when the registry has one, since
+     * a bare snowflake is unresolvable for the agent (the 2026-07-21 incident
+     * read as "a stale artifact", not a live failure).
+     */
+    private channelForNotice;
+    /**
+     * A module's write through its context: addMessage's, except that a write
+     * the framework holds is answered by its handle (heldHandle) rather than
+     * '', so the module can find, read, edit and remove what it wrote before
+     * the write lands. The framework's own callers keep the '' they've always
+     * had, which their traces and checks take as a write not stored yet.
+     */
+    private addModuleMessage;
+    /**
+     * 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:
+     * 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 passing to the primary as its notice
+     * (queuedFailedReplyForPrimary).
+     */
+    private heldWritesFor;
+    /**
+     * The writes held for `reader`'s store (heldWritesFor) as the rows a
+     * module's context reads: each under its handle, marked `held`, with the
+     * participant, content and metadata it was written with, the time it was
+     * first held as its timestamp, and a sequence after every row the store
+     * holds, in queue order. The sequence and timestamp are provisional: the
+     * stored row has the store's own.
+     */
+    private heldRows;
+    /** The row a held write landed as, found by the id it's stored with
+     *  (`metadata.deferredWriteId`): the first, for a body stored in shards,
+     *  as addMessage answers a stored write. Null when it hasn't landed, or is
+     *  no longer in the store. */
+    private landedRow;
     private editMessage;
     private removeMessage;
     private getMessage;
@@ -2509,7 +3596,7 @@ export declare class AgentFramework {
      * push event to wake the agent onto the same context.
      *
      * Bounded: at most `refusalHandling.maxRewinds` (default 3, hard cap 10)
-     * sheds per failure episode; the budget resets on any successful inference.
+     * sheds per failure episode; the budget resets when a turn completes.
      * At the cap (or with nothing left to shed) it stops — the agent stays up
      * and hard-down logging continues, but no further history is consumed.
      */
@@ -2519,6 +3606,44 @@ export declare class AgentFramework {
      * Fail-open: individual server connection failures don't prevent framework startup.
      */
     private initializeMcpl;
+    /** The modern connections, created on first use, so a framework assembled
+     *  field by field (as unit tests do) needs no setup for them. */
+    private modernServers;
+    /** The restarts' claims (mcpRestartClaims), created on first use, as the
+     *  modern connections are. */
+    private restartClaims;
+    private legacyConnectAborts;
+    /**
+     * Hold a server id for one connect or disconnect, until `release()`.
+     * Together with the live connections (the MCPL registry and the modern
+     * map) this is what holds an id: from a connect's admission until its
+     * teardown is done, one owner at a time. So a connect is refused while
+     * anything holds its id, and a teardown never removes what a later
+     * connection registered. A disconnect takes the hold over, and waits for
+     * the operation it displaced (`previous`); a connect that finds itself
+     * `displaced` ends rather than setting up a server being removed. Each
+     * release frees only its own hold.
+     */
+    private holdMcpServerId;
+    /** Whether a server's connection still serves it, or is reconnecting to
+     *  it. One the host is closing or has closed doesn't, and neither does one
+     *  lost for good, whose reconnecting has stopped. */
+    private static mcpConnectionServes;
+    /**
+     * A connect whose failed launch couldn't be confirmed exited. Its
+     * connection stays registered, closed, and holds the id, so nothing
+     * launches beside a child that may still be running; a disconnect retries
+     * the reap, and completes once the exit is confirmed. Once stop() has
+     * begun it refuses a disconnect, and retries the reap itself, so no
+     * disconnect is offered then.
+     */
+    private unreapedConnectFailure;
+    /** Close every modern-MCP connection, including any connect still in
+     *  flight, so none outlives a failed startup or stop(). One whose close
+     *  fails or is still pending stays registered, holding its id, as a failed
+     *  connect's does, and every failure is thrown, as the MCPL registry's
+     *  closeAll does. `timeoutMs` bounds the wait without cancelling cleanup. */
+    private closeModernMcpConnections;
     /**
      * Reconcile the durable ledger with Chronicle, then deliver every server's
      * work. A drain still running is waited for and then followed by a fresh
@@ -2537,6 +3662,10 @@ export declare class AgentFramework {
      * Deliver every due ref independently. Permanent Discord failures are kept
      * in the ledger for audit but do not block later operations; retryable
      * failures remain pending for the next reconnect/list-change attempt.
+     * Once stop() has begun, a drain sends nothing more and records nothing
+     * for what it hasn't sent: that stays pending, as it was, for the next
+     * start's barrier. stop() closes the connections and then waits for each
+     * drain still running to record the call it had in flight.
      */
     private drainDiscordAwarenessOutbox;
     private readDiscordAwarenessPending;
@@ -2552,7 +3681,9 @@ export declare class AgentFramework {
      * its last read of the ledger, missing a batch activated since. So a
      * generation that finds a drain running waits for it, then drains again
      * with a fresh pass that reads the ledger anew. Two generations waiting on
-     * the same drain share the fresh pass that follows it.
+     * the same drain share the fresh pass that follows it. Once stop() has
+     * begun, a drain sends nothing more, so a gate armed then completes with
+     * what it found pending left for the next start.
      */
     private drainForGeneration;
     /**
@@ -2563,10 +3694,57 @@ export declare class AgentFramework {
      * meanwhile. Rejects as the generation it waited for rejects.
      */
     private awaitDiscordAwarenessBarriers;
+    /**
+     * Per connection, the transport epoch whose §5.3 policy exchange is in
+     * flight: a connect's, from when the registry hands the connection back,
+     * or a reconnect's, from its 'reconnect' event. Until the exchange settles,
+     * that transport's traffic must wait for its grant, so a gate that opens
+     * every connection's planes meanwhile (another server's list change, a
+     * resume, an awareness sync, startup's staged open) passes it by
+     * (mcplPlanesMayOpen), and the exchange's own caller opens them once it
+     * settles (openMcplPlanesAfterExchange).
+     */
+    private readonly mcplPolicyExchanges;
+    /** Whether a gate may open this connection's planes: no policy exchange is
+     *  in flight on its current transport (see mcplPolicyExchanges). */
+    private mcplPlanesMayOpen;
+    /**
+     * Run a connection's §5.3 policy exchange with its planes held: it is
+     * marked in flight for the transport it runs on, so no gate releases that
+     * transport's traffic before its grant exists. With `epoch`, it runs only
+     * on that transport: a runtime connect passes the one it registered, and
+     * if that transport is gone, the exchange isn't run, since a reconnect
+     * that adopts a next transport, if one comes, runs that one's. With
+     * `closeOnFailure`, as for a runtime connect or restart, an exchange that
+     * throws closes the connection for good, through the registry, before it
+     * lifts the marker: left live, the connection would be half registered,
+     * and unmarked before its close, a gate completing in between would let
+     * out what it held with no grant. A close that fails keeps the connection
+     * registered, but closed for good, it readies nothing but its own reports.
+     * Without `closeOnFailure`, as for a reconnect or a staged startup connect,
+     * an exchange that throws leaves the connection live with the grant it
+     * reached, empty if the policy step itself threw, and the marker lifts.
+     */
+    private settlePolicyExchange;
+    /**
+     * Open a connection's planes once its exchange has settled, when the gate
+     * its connect or reconnect installed was replaced during the exchange: the
+     * newer gate passed the connection by, and if it has completed, nothing
+     * else would open it. A connection whose transport dropped meanwhile is
+     * readied as any gate readies one between transports, so its own reports
+     * go on. How far follows what is held now: while a gate is up, only the
+     * control plane opens, since a gate holds data planes alone, and its
+     * completion, which no longer passes this connection by, opens the data
+     * plane; a quiesced host (issue #122) likewise opens only control planes;
+     * otherwise both open.
+     */
+    private openMcplPlanesAfterExchange;
     /**
      * Install one framework-global Discord-awareness generation before releasing
      * any inference-bearing event. With pending work or a drain still running,
-     * every MCPL data plane is paused while all control planes remain live.
+     * every MCPL data plane is paused while the control planes remain live,
+     * but for a connection whose policy exchange is in flight, which neither
+     * the release nor the completion opens (mcplPlanesMayOpen).
      * With neither, ready() runs synchronously so request responders preserve
      * their historical same-stack behavior.
      */
@@ -2574,6 +3752,21 @@ export declare class AgentFramework {
     private releaseMcplDataPlaneGate;
     private completeMcplDataPlaneGate;
     private failMcplDataPlaneGate;
+    /**
+     * Close a legacy connection for good through the registry. A close that
+     * can't confirm its child exited keeps the connection registered, holding
+     * its id, and emits no 'close', so no close listener takes its tools off
+     * the agents' list: this does, then rethrows the failure for the caller to
+     * report. A server the host has given up on leaves the list either way.
+     */
+    private closeMcplServerForGood;
+    /**
+     * Close a runtime connect's new connection for good, through the registry,
+     * after a step of that connect failed. A close that fails keeps the entry,
+     * so a later disconnect, restart or shutdown can close it again, and is
+     * logged here rather than replacing the failure the connect reports.
+     */
+    private closeFailedRuntimeConnect;
     /**
      * Connect a single MCPL server: register routing entries, open the
      * connection, wire events, and initialize feature sets / scopes /
@@ -2581,11 +3774,23 @@ export declare class AgentFramework {
      * lifecycle API (connectMcplServer). Throws on connection failure.
      */
     private connectMcplServerInternal;
-    /** Per-connection §17.8 fetch limiter: at most one in-flight fetch, at
-     *  most one queued behind it (announcements coalesce), floor between
-     *  completed fetches. Exceeding the floor drops the excess with a
-     *  diagnostic — the host bounds the rate; it never depends on server
-     *  coalescing. */
+    /** The part of a connect that runs holding its id, handing back the
+     *  connection it registered. `displaced`: whether a disconnect has taken
+     *  the id over and is waiting for this connect, which a legacy connect asks
+     *  once its handshake is done. */
+    private connectHeldMcplServer;
+    /** Per-connection §17.8 fetch limiter, keyed by the connection, so one
+     *  that replaces a removed server under its id starts its own: at most one
+     *  fetch in flight; announcements during it coalesce into one refresh run
+     *  after it, and announcements within the floor after a fetch into one run
+     *  once the floor has passed — the host bounds the rate; it never depends
+     *  on server coalescing. A queued refresh runs only on the transport of
+     *  the latest announcement it holds (`queuedEpoch`), and its receipt
+     *  reports the domains of the announcements coalesced into it there
+     *  (`queuedDomains`), since its fetch answers them all. The next
+     *  transport's initialize and policy exchange start afresh, and its own
+     *  announcements queue their own, so an earlier transport's hints are
+     *  dropped. */
     private manifestRefreshState;
     private static readonly MANIFEST_FETCH_FLOOR_MS;
     /**
@@ -2602,6 +3807,14 @@ export declare class AgentFramework {
      * tell→receipt→activate), emit ONE change receipt (§17.6).
      */
     private handleManifestChanged;
+    /** A refresh handleManifestChanged schedules for itself, after the fetch
+     *  floor or behind a fetch in flight. Its announcement is the domains of
+     *  the announcements it coalesced (`{ domains }`), the one field
+     *  handleManifestChanged reads of one. It's contained as the announcement's
+     *  own run is. Its fetch's own failure is logged by the fetch's catch, as
+     *  in 0.22.x; any other failure emits mcpl:request-handler-error and a
+     *  stderr line through the containment. */
+    private rerunManifestRefresh;
     /**
      * (Re-)establish a server's host-side MCPL registration: feature-set state
      * (plus the featureSets/update sent to the server), scope patterns, and
@@ -2659,16 +3872,30 @@ export declare class AgentFramework {
      * Connect a new MCPL server at runtime. Refreshes the tool list and
      * notifies the agent of newly available tools. Throws if the MCPL
      * subsystem is not initialized, the id is already connected, or the
-     * connection/handshake fails.
+     * connection/handshake fails. A config whose `inheritEnv` (on a stdio
+     * server), `reconnect` or `allowHostCommands` holds anything but true,
+     * false or null is refused, as `create()` refuses one.
      */
     connectMcplServer(config: import('./mcpl/types.js').McplServerConfig): Promise<void>;
+    /** connectMcplServer's work, for a restart's connect too: the id and tool
+     *  prefix its `claim` holds are free to it, and refused to everyone else. */
     private runConnectMcplServer;
     /**
-     * Disconnect an MCPL server at runtime: close the connection, destroy its
-     * feature-set and checkpoint state (permanent removal — unlike a transient
-     * transport close, which preserves checkpoints for the reconnect), remove
-     * its channels from the registry, drop routing entries, and refresh tools.
+     * Disconnect an MCPL server at runtime: remove its channels from the
+     * registry (first, cancelling their queued lifecycle work), close the
+     * connection, destroy its feature-set and checkpoint state (permanent
+     * removal — unlike a transient transport close, which preserves checkpoints
+     * for the reconnect), drop routing entries, and refresh tools.
      * No-op-ish if the server is not connected (still clears routing state).
+     *
+     * It holds the id throughout (holdMcpServerId): a connect for it is
+     * refused meanwhile, and a connect already in flight is ended (closed, or
+     * displaced when its legacy handshake finishes) and settles before
+     * anything but the channel entries the disconnect found when it began is
+     * removed. A close that can't confirm a child exited fails the disconnect
+     * before anything but those entries is removed: the server stays
+     * registered, closed, so nothing launches beside a child that may still be
+     * running, and disconnecting again retries the reap.
      */
     disconnectMcplServer(id: string): Promise<void>;
     private runDisconnectMcplServer;
@@ -2677,9 +3904,63 @@ export declare class AgentFramework {
      * 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.
+     * 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,
+     * and a module added meanwhile is refused that tool prefix. The id and
+     * prefix it moves the server from are free once its disconnect is done, as
+     * after any disconnect.
+     *
+     * A disconnect of the id the restart moves the server to (its own id, for
+     * a restart under the same id), or a `stop()`, that begins during the
+     * restart ends it, as a disconnect ends a connect in flight: the restart
+     * rejects, saying the server is down, and its holds are released, and the
+     * server isn't left configured, as after any disconnect. A restart whose
+     * connect fails on its own leaves the server down, configured under the
+     * new configuration and its id, and holding its tool prefix, as any failed
+     * connect does: `listMcplServers()` lists it as not connected, and a
+     * restart or a disconnect under that id tries it again or removes it.
+     *
+     * Treat a submitted configuration and its nested values as immutable for
+     * as long as the server uses them. Apply changed settings with
+     * `restartMcplServer(id, newConfig)`; use `accessProvider` for a network
+     * server's rotating credentials (a stdio server's changed `env` goes
+     * through a restart with the new configuration).
      */
     restartMcplServer(id: string, newConfig?: import('./mcpl/types.js').McplServerConfig): Promise<void>;
     private runRestartMcplServer;
+    /**
+     * A redactor for text that may come from any configured server, with every
+     * server's credentials replaced: those of the configurations present when
+     * it's made, then those present when it's used. An operation makes it
+     * before it waits, so a server removed meanwhile, and one connected
+     * meanwhile, both have their credentials replaced. When one of them can't
+     * be read, the text is withheld, as redactServerText withholds it.
+     */
+    private everyServerRedactor;
+    /** Why a connect for this id is refused, or null when the id is free. One
+     *  owner per id, across both engines (holdMcpServerId): a connect or
+     *  disconnect in flight holds it, and so does a registered connection,
+     *  including one kept because its launch couldn't be confirmed exited, and
+     *  a restart moving its server to the id (mcpRestartClaims), except to
+     *  that restart's own connect (`claim`). That connect is still refused
+     *  while a disconnect of the id is in flight: the restart's own disconnect
+     *  has finished by then, so that one began during the restart, and it ends
+     *  the restart. `restarting` words the refusal for a restart of that
+     *  server checking the id it would move to. */
+    private mcpServerIdTaken;
+    /** The collision rules create() enforces at startup, as a runtime connect
+     *  (or a restart, before its disconnect) meets them, in either engine: the
+     *  tool prefix must not shadow a module name or another server's prefix,
+     *  or meet another server's (prefixesMeet, #265), and must neither be nor
+     *  meet one a restart is moving its server to (mcpRestartClaims). The
+     *  server's own prefix is free to keep, so is that of the server a restart
+     *  is about to disconnect (`leaving`), and so is the prefix a restart's own
+     *  connect holds (`claim`). */
+    private mcplPrefixCollision;
+    /** The protocol family a configuration resolves to, or a refusal naming
+     *  every problem with it, before anything is spawned, dialed or torn down. */
+    private static usableConfigFamily;
     /**
      * List configured MCPL servers with live connection status and the number
      * of tools each currently contributes.
@@ -2688,10 +3969,22 @@ export declare class AgentFramework {
         id: string;
         connected: boolean;
         retrying: boolean;
+        /** Which engine serves it: `legacy` (MCP 2024-11-05 + MCPL) or `modern`
+         *  (MCP 2026-07-28), as its configuration selects; null when the
+         *  configuration names no usable transport (see `refused`). */
+        family: 'legacy' | 'modern' | null;
+        /** The MCP revision its last handshake established; null until one has. */
+        protocolVersion: string | null;
+        /** How it is reached; null when the configuration names no usable transport. */
+        transport: 'stdio' | 'websocket' | 'http' | null;
+        /** Why connecting refuses this configuration, before anything is spawned
+         *  or dialed; null when it is usable. */
+        refused: string | null;
         toolPrefix: string;
         toolCount: number;
-        /** True only after the §5.3 policy receipt activated the grant. */
-        policyEstablished: boolean;
+        /** True only after the §5.3 policy receipt activated the grant. Null for
+         *  a modern server, which has no MCPL policy. */
+        policyEstablished: boolean | null;
         /** Sole normative authorization allowlist for the connection (§5.4). */
         effectiveGrant: string[];
         /** Advertised paths removed by host enabled/disabled capability config. */
@@ -2730,16 +4023,51 @@ export declare class AgentFramework {
             lastNegotiatedAt: number | null;
         };
         command?: string;
+        /** The url as {@link redactUrl} shows it, since a credential may ride in
+         *  it: no userinfo, each query parameter's value replaced, and any path
+         *  segment or query parameter name that looks like a credential
+         *  replaced. */
         url?: string;
     }>;
+    /**
+     * An inbound MCPL handler, contained: EventEmitter doesn't consume the
+     * promise a listener returns, so this keeps each handler's throw or
+     * rejection at this boundary, including failures after channels/register or
+     * channels/changed has acknowledged the request. It's invoked at once, so
+     * control-plane replies keep their acknowledge-before-reconcile order.
+     * Each text a failure records, in its trace and its log line, goes through
+     * `recorded`, the server's redactor where the caller has one, since a
+     * handler's error can quote what the server sent.
+     */
+    private containedInboundHandler;
     /**
      * Wire event listeners on an MCPL server connection.
      * Push events and inference requests are deferred to Steps 6/7.
      */
     private wireMcplEvents;
+    /**
+     * Wire a modern-MCP connection's events. There's less here than for MCPL
+     * on purpose: no push, inference, channels or policy exist on this family.
+     * A list change, including the relist after a reconnect, takes the legacy
+     * engine's refresh path (`handleToolsListChanged`), so any wake it causes
+     * goes through ordinary admission: it parks under quiesce or a hold like
+     * every other wake. It installs no awareness gate, since that gate orders
+     * MCPL data-plane traffic, which this family doesn't carry.
+     */
+    private wireModernEvents;
+    /** An MCP tool call's trace: a result the server marked an error (or one
+     *  the reading couldn't complete) is tool:failed, as on the other tool
+     *  paths; anything else is tool:completed. */
+    private traceMcpToolOutcome;
     /**
      * Discover tools from all connected MCPL servers and cache them.
      * Tools are namespaced as `{toolPrefix}--{toolName}` per server config.
+     * No two servers' prefixes meet (prefixesMeet, refused at create(), a
+     * runtime connect and a restart), so no two servers give one name. A
+     * server that lists one name more than once keeps its first listing, and
+     * an ops alert at each refresh that finds it says so (#265): a tool list
+     * holding one name twice is refused by membrane's native formatter and by
+     * Anthropic's API.
      */
     private refreshMcplTools;
     /**
@@ -2769,11 +4097,47 @@ export declare class AgentFramework {
      * Emit a trace event and push an external-message listing newly added tools.
      */
     private emitMcplToolDiff;
+    /** The refusal of a tool call whose server isn't one to call yet, for the
+     *  model's call, a script's and an in-process one alike: none registered,
+     *  or a modern connection whose connect is still under way
+     *  (modernStillConnecting). It says "connecting" while a connect of its id
+     *  is in flight (mcpServerOps) or a restart holds the id, and "gone"
+     *  otherwise. */
+    private mcplServerAbsentText;
+    /** A modern connection a connect still under way registered: it registers
+     *  before it starts, so until its first session is up it's no server to
+     *  call, and a call reads the "connecting" text, as one during a legacy
+     *  connect's handshake does. Once that session is up, a call goes to it,
+     *  even while the connect lists its tools. */
+    private modernStillConnecting;
     /**
      * Dispatch a tool call to an MCPL server.
      * Strips the configured toolPrefix and routes to the server.
      */
     private dispatchMcplToolCall;
+    /**
+     * The direct path's reading of an MCP tool result (executeToolCall,
+     * ModuleContext.callTool). `data` stays the raw content array, as module
+     * callers have always received it. Two things change: a tool error
+     * (`isError: true`) is now a failure, where every answer used to count as
+     * success, and `structured` is added by presence.
+     */
+    private static directToolResult;
+    /**
+     * The framework's ToolResult for an MCP tool result on the model path
+     * (model dispatch, and scripts, which ride it). A standard peer, meaning an MCP-only legacy
+     * server or any modern server, gets the standard reading
+     * (tool-result-normalize.ts): typed content blocks, workspace-saved
+     * payloads, and `structured` kept by presence. An MCPL peer keeps the
+     * RFC-005 reading. Its content array passes through when it holds
+     * non-text blocks, so references and images render natively. It gets
+     * `structured` too, with the JSON view when its content is empty. The
+     * direct path (a module's callTool, a channel's tool call) doesn't come
+     * here: it returns the server's result itself (directToolResult), for
+     * either engine, as does a script's call whose result is structured, with
+     * an MCPL peer's blocks given RFC-005's treatment (referenceBlockForScript).
+     */
+    private mcpToolResult;
     /**
      * Build BeforeInferenceParams from agent state and trigger context.
      */