@animalabs/agent-framework 0.22.2 → 0.22.3

package/dist/src/framework.d.ts

@@ -104,6 +104,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 +203,22 @@ export declare class AgentFramework {
     private stopPromise;
     private stopCompleted;
     private ownedStoreClosed;
+    /** Whether the latest stop() stopped in time everything it waits on with
+     * its deadline (an operator's operations, modules and MCPL servers),
+     * whatever failed after that. 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. 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 a budget never lets the store close
+     * under work still running. Each leaves once it settles. */
+    private readonly leftRunning;
     private membrane;
     private queue;
     private agents;
@@ -212,6 +237,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;
@@ -252,6 +287,11 @@ export declare class AgentFramework {
     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 +302,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,
@@ -329,7 +372,8 @@ export declare class AgentFramework {
      * 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
@@ -353,7 +397,8 @@ export declare class AgentFramework {
      *  rewind loop — see refusalHandling + rewindTriggeringTurn. */
     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 +432,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;
@@ -434,6 +490,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 +523,7 @@ 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 coalescing commit in flight, if any (see commitCoalescingDurable). */
     private coalescingCommit;
     private inferenceRouter;
     private channelRegistry;
@@ -477,6 +538,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 +553,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
@@ -565,30 +630,95 @@ 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 two cleanup
+     * waits, for an operator's operations already running and then for its
+     * modules and MCPL servers, and a store it opened is closed. A store the
+     * caller passed in is left open.
      */
     static create(config: FrameworkConfig): Promise<AgentFramework>;
+    /**
+     * 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.
      */
     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. After a failed or timed-out wait, storage stays open
+     * and stop() can be called again. 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, then on modules and MCPL together. With a budget, a
+     * stop() can take up to five 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. After it:
+     * - 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 meanwhile 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>;
     private resetCompletedStop;
@@ -791,23 +921,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;
     /**
@@ -873,6 +992,40 @@ export declare class AgentFramework {
      * Abort an in-flight inference for an agent.
      */
     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`, or by just closing, and each of those ends here, so the three
+     * 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.
      */
@@ -935,7 +1088,11 @@ export declare class AgentFramework {
     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. */
@@ -1014,9 +1171,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 +1209,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 +1247,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 +1289,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 —
@@ -1241,13 +1513,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,14 +1588,19 @@ 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.
@@ -1395,6 +1685,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
@@ -1448,6 +1747,13 @@ export declare class AgentFramework {
      * Best-effort; mirrors reactToRefusal's locus resolution.
      */
     private announceRewind;
+    /**
+     * 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 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 +1907,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 +1959,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 +1985,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 +2003,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;
@@ -1808,6 +2123,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 +2182,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 +2274,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 +2302,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;
@@ -1996,8 +2421,113 @@ export declare class AgentFramework {
      * turns, whose rows are stored exactly as before.
      */
     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;
     /**
@@ -2081,10 +2611,11 @@ export declare class AgentFramework {
     /**
      * 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.
+     * delivery into a closed channel. The agent must always learn that the
+     * channel opened, and that `channel_close` opts 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 +2634,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 +2647,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 +2677,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
@@ -2213,6 +2791,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 +2806,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 +2860,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. */
@@ -2320,9 +2921,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 +2932,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,6 +2953,10 @@ 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;
     /** Forget one server's RFC-008 class declarations (see the close handler). */
@@ -2387,20 +2995,127 @@ 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.
+     * both. 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). Where two servers list
+     * the same name, the listing holds the one listed last (#265). A name the
+     * listing doesn't hold (invented by the model, or no longer listed) goes to
+     * the longest matching prefix. Never prefix-map insertion order.
      */
     private resolveMcplTool;
+    /**
+     * 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.
+     *
+     * 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. `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;
     private editMessage;
     private removeMessage;
     private getMessage;
@@ -2509,7 +3224,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.
      */
@@ -2574,6 +3289,13 @@ export declare class AgentFramework {
     private releaseMcplDataPlaneGate;
     private completeMcplDataPlaneGate;
     private failMcplDataPlaneGate;
+    /**
+     * 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 /
@@ -2602,6 +3324,12 @@ 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. 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,7 +3387,9 @@ 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>;
     private runConnectMcplServer;
@@ -2677,6 +3407,8 @@ 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.
+     * A config `connectMcplServer` would refuse for its boolean settings is
+     * refused before the running server is disconnected, so it stays up.
      */
     restartMcplServer(id: string, newConfig?: import('./mcpl/types.js').McplServerConfig): Promise<void>;
     private runRestartMcplServer;
@@ -2732,6 +3464,14 @@ export declare class AgentFramework {
         command?: string;
         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.
+     */
+    private containedInboundHandler;
     /**
      * Wire event listeners on an MCPL server connection.
      * Push events and inference requests are deferred to Steps 6/7.