@animalabs/agent-framework 0.22.1 → 0.22.2

package/dist/src/framework.d.ts

@@ -104,6 +104,22 @@ export declare class ResumeBlockedError extends Error {
         preview: RuntimeSettingsPreview;
     }>);
 }
+/**
+ * How `runEphemeralToCompletion` rejects when a retryable provider failure
+ * states a wait the run won't sleep: one longer than an ephemeral run sleeps
+ * in its turn (600 s), an infinite one, or one that is `NaN`. The run ends at
+ * once, without retrying inside the wait, and every other ending of the run
+ * rejects with a plain `Error`. `retryAfterMs` is the wait as the provider
+ * stated it, in milliseconds, so `Infinity` or `NaN` in those two cases: a
+ * host that schedules a rerun from it handles a value that isn't finite, and
+ * one past the 2,147,483,647 ms a timer can hold. The message says the same
+ * in words. A host can test `instanceof` or the `name`, which also holds for
+ * an error from another copy of this package.
+ */
+export declare class ProviderWaitNotSleptError extends Error {
+    readonly retryAfterMs: number;
+    constructor(message: string, retryAfterMs: number);
+}
 interface InferenceToolSnapshot {
     sameRoundThinkTextPolicy: SameRoundThinkTextPolicy;
 }
@@ -115,18 +131,19 @@ interface InferenceToolSnapshot {
  *
  * 400 and 422 are how a provider answers a request that fails its
  * validation, as a history it can't accept does, but other refusals come
- * back the same way, such as Anthropic's 400 for a credit balance that's too
- * low. A 413 is the request's size. When the newest exchange made it too
- * large, as an oversized attachment does, shedding that exchange may bring
- * the request back under the limit, and nothing else in the framework
- * recovers a 413; when the history as a whole is too large, the shed doesn't
- * help, and the breaker stops at its rewind cap. The 413 arm takes both
- * labels a 413 arrives under, invalid_request and context_length, because
- * membrane's label for a 413 differs by version and adapter. Other statuses
- * keep the history, since shed history can't be got back and the status
- * gives no sign that a shed would help: a 404 is a model or an endpoint that
- * doesn't exist, and 405, 409, 410 and 415 are about the HTTP request or the
- * resource, as a rule, rather than the conversation.
+ * back the same way, such as a refusal of the account that membrane doesn't
+ * recognize by its text. A 413 is the request's size. When the newest
+ * exchange made it too large, as an oversized attachment does, shedding that
+ * exchange may bring the request back under the limit, and nothing else in
+ * the framework recovers a 413; when the history as a whole is too large,
+ * the shed doesn't help, and the breaker stops at its rewind cap. The 413 arm
+ * takes both labels membranes have given a 413, invalid_request and
+ * context_length (see the notes below). Other statuses keep the history,
+ * since a shed takes the exchange out of the agent's context, which only an
+ * operator's undo brings back, and the status gives no sign that a shed
+ * would help: a 404 is a model or an endpoint that doesn't exist, and 405,
+ * 409, 410 and 415 are about the HTTP request or the resource, as a rule,
+ * rather than the conversation.
  *
  * The table test in test/inference-exhaustion-rewind.test.ts is this
  * predicate's contract. The notes below on which membrane version gives which
@@ -141,13 +158,24 @@ interface InferenceToolSnapshot {
  *   adapter files every status it doesn't list (404, 405, 409, 410, 413,
  *   415, 422 …) as invalid_request, so it alone produces an invalid_request
  *   at 413 or 422, and no 0.5.86 adapter produces a context_length at 413.
- * - From membrane #56 (merged, not yet in a release), one table serves every
- *   adapter. Auth codes and context overflow are checked on a 400 or 422
- *   first, a 404 is invalid_request, a 413 is context_length, and other 4xx
- *   are invalid_request. So a 413 still sheds, an Anthropic one included,
- *   while a context_length at 400 or 422, a token overflow, keeps the
- *   history. The 422 arm then also covers an OpenAI-compatible server, such
- *   as a FastAPI one, that answers a validation failure with 422.
+ * - From membrane 0.5.87 (membrane #56 and #107), this package's floor, every
+ *   adapter sends an HTTP failure through one status table
+ *   (errorFromProviderStatus). On a 400 or 422, auth codes and reasons and
+ *   the two account refusals it recognizes by their text (a balance too low,
+ *   usage limits reached) are auth, and a context overflow, by its code or
+ *   text, is context_length. A 401, 402 or 403 is auth, a 408 timeout, a 429
+ *   rate_limit, a 404 invalid_request and a 413 context_length; other 4xx
+ *   are invalid_request. So a 413 the table types sheds, an Anthropic one
+ *   included, while a context_length at 400 or 422, a token overflow, keeps
+ *   the history, and so does an account refusal, which is auth. An adapter
+ *   can type a failure before the table does, as Anthropic's does for a
+ *   gateway's aggregate error (server). A failure with no HTTP status takes
+ *   the status its provider code implies when the table knows the code, as
+ *   for Anthropic's mid-stream errors, and is otherwise typed from its
+ *   message, with no status. The 422 arm also covers an
+ *   OpenAI-compatible server, such as a FastAPI one, that answers a
+ *   validation failure with 422. The test of provider answers through the
+ *   table, beside the table test, pins how the two meet at the floor.
  *
  * An error with no status, from a membrane that reports none, keeps the rule
  * the breaker had before: the type alone.
@@ -162,6 +190,10 @@ export declare class AgentFramework {
     private stopPromise;
     private stopCompleted;
     private ownedStoreClosed;
+    /** 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;
     private membrane;
     private queue;
     private agents;
@@ -169,16 +201,6 @@ export declare class AgentFramework {
     private inferencePolicy;
     private errorPolicy;
     private pendingRequests;
-    /**
-     * Per-agent channel that triggered the agent's CURRENT inference turn, if any
-     * (item-3 redux). Read by the ChannelRegistry's `activeChannelResolver` to
-     * route a single-trunk agent's plain-text speech back to the channel it is
-     * answering, instead of the process-global most-recent-inbound locus that a
-     * concurrent message elsewhere can hijack. Set at turn start (or cleared for a
-     * heartbeat / no-trigger turn) in startAgentStream; overwritten by the next
-     * turn. Never read between turns (a given agent runs one turn at a time).
-     */
-    private activeTriggerChannels;
     private running;
     private loopPromise;
     /** Quiesce/maintenance mode (issue #122). DELIBERATELY separate from
@@ -201,6 +223,14 @@ export declare class AgentFramework {
     private maintenanceRunId;
     private currentMaintenanceRun;
     private maintenanceHistory;
+    /** Each agent's last reported maintenance failure, its whole text and when
+     *  it was alerted, until its maintenance goes without one
+     *  (reportMaintenanceFailure). */
+    private maintenanceFailureReported;
+    /** Run records whose failure repeated one already reported, and whose report was suppressed. */
+    private maintenanceRepeats;
+    /** An operator's maintain (maintenanceTick) asked for the pass running or about to run: the run it records is kept in the history whatever it met. A pass with nothing to run records none. */
+    private maintenancePassRequested;
     private providerGates;
     private providerAccelerationCooldowns;
     private providerAccelerationRecoveries;
@@ -222,32 +252,6 @@ export declare class AgentFramework {
     private processLoggingPersist;
     private processLoggingBroadcast;
     private activeStreams;
-    /** Per-agent output locus FROZEN for the CURRENT logical turn. Resolved
-     *  eagerly in startAgentStream (home → addressed trigger → global default)
-     *  and never moved until the next turn: mid-turn injected messages — ambient
-     *  chatter, reactions, system markers — must not hijack where the agent's
-     *  plain prose lands (2026-07-21 Cairn lounge misroute). Lives here — not in
-     *  driveStream locals — so the pin survives a context-budget stream restart,
-     *  which continues the same logical turn in a fresh driveStream. Cleared or
-     *  re-set at the start of every non-restart turn. Since 2026-07-31 the pin
-     *  is no longer fully frozen: an ADDRESSED conversational injection — or a
-     *  conversational follow-up in a channel the agent itself explicitly sent
-     *  into this turn (turnEngagedChannels) — re-pins it at the boundary (see
-     *  the addressed re-pin block in the tool-result handler). Ambient chatter
-     *  elsewhere, reactions, and system markers still cannot move it. */
-    private turnLocusPins;
-    /** Channels the agent EXPLICITLY sent into during the CURRENT turn
-     *  (SEND_ENGAGEMENT_TOOLS, successful calls), per agent. Second re-pin
-     *  signal: a conversational reply in a channel the agent just engaged is
-     *  addressed by context even without a mention (2026-07-31 n=7: q's
-     *  #portables follow-up — no @mention — was answered in trailing prose
-     *  that followed the stale pin into repligate's DM). No author-kind
-     *  filter: agent-residents are full participants, and the bot flag
-     *  tracks nothing that matters (antra). Reactions/system markers are
-     *  excluded by isConversationalInjection; the engaged-this-turn scope
-     *  keeps unrelated channels from moving the pin. Cleared at every fresh
-     *  turn's start; budget restarts keep it. */
-    private turnEngagedChannels;
     /** 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
@@ -261,12 +265,13 @@ export declare class AgentFramework {
     /** Latest bounced (undelivered) prose per agent — the `{{unsent}}` source. */
     private proseClipboards;
     /**
-     * Each agent's routing state for its current turn (TurnRouting): the
-     * sticky destination, the turn's destination for a resumed stream,
-     * hybrid's hold, a `!` continuation and receipt tallies. A fresh turn starts a new object
-     * instead of clearing the old one, and a stream that resumes the turn
-     * (resumesLogicalTurn) keeps it. A queued delivery holds the object of the
-     * turn that queued it, so prose a turn leaves queued when it ends (a
+     * Each agent's routing state for its current logical turn (TurnRouting):
+     * its trigger channel, locus and engaged channels, the sticky destination,
+     * the turn's destination, hybrid's hold, a ` !` continuation and receipt
+     * tallies. The start that opens a turn makes a
+     * new object instead of clearing the old one, and every later stream of
+     * the turn shares it (openLogical). A queued delivery holds the object of
+     * the turn that queued it, so prose a turn leaves queued when it ends (a
      * skip_reply ends it before its posts have run) still follows that turn's
      * destination, and its late writes can't reach the next turn.
      */
@@ -278,23 +283,25 @@ export declare class AgentFramework {
      */
     private proseSpeechChains;
     /**
-     * Each agent's open logical turn (LogicalTurn). It stays open from the
-     * fresh start that opens it until the turn settles (settleAgent: it
-     * completes, a tool ends it, or it fails or is abandoned), and every fresh
-     * start that routes prose while it is open continues it: a framework
-     * retry, the start that consumes tool results the non-streaming fallback
-     * left (whichever wake the scheduler starts it with), the later compile a
-     * provider-capacity hold defers a turn to. A silent start neither
-     * continues nor opens one. A stream that ends without settling needs to do
-     * nothing to carry its turn. Settling only detaches the turn from future
-     * starts: the settling stream keeps its own object, which its remaining
-     * deliveries, its receipt and its ` !` check go on using (a completion
-     * settles before it awaits its chain and writes its receipt). So every
-     * logical end must close inheritance once, before the next fresh start:
-     * a turn left open would hand its object, late writes and all, to an
-     * unrelated turn. A tool-ended turn settles before the next turn can
-     * start. Only the stream that holds the open turn closes it; disposal
-     * drops it, and stop() clears every agent's.
+     * Each agent's open logical turn: its routing state and receipt tallies
+     * (TurnRouting). It stays open from the start that opens it until the
+     * turn settles (settleAgent: it completes, a tool ends it, or it fails or
+     * is abandoned), and every start that routes prose while it is open
+     * continues it with that object: a framework retry, the start that
+     * consumes tool results the non-streaming fallback left (whichever wake
+     * the scheduler starts it with), the later compile a provider-capacity
+     * hold defers a turn to. A silent start neither continues nor opens one,
+     * and leaves the open turn's object untouched (its own is the live routing
+     * while it runs: turnRouting). A stream that ends without
+     * settling needs to do nothing to carry its turn. Settling only detaches
+     * the turn from future starts: the settling stream keeps its own object,
+     * which its remaining deliveries, its receipt and its ` !` check go on
+     * using (a completion settles before it awaits its chain and writes its
+     * receipt). So every logical end must close inheritance once, before the
+     * next fresh start: a turn left open would hand its object, late writes
+     * and all, to an unrelated turn. A tool-ended turn settles before the
+     * next turn can start. Only the stream that holds the open turn closes
+     * it; disposal drops it, and stop() clears every agent's.
      */
     private openLogical;
     /** Consecutive bounce-wakes per agent; capped so an agent that keeps
@@ -357,6 +364,8 @@ export declare class AgentFramework {
      *  tick counts in the success log stop meaning anything. One kick per agent
      *  at a time; cleared when the kick settles (success or failure). */
     private overBudgetDrainInFlight;
+    /** The over-budget drain kicks running, which a branch move waits for as it waits for a maintenance pass. */
+    private overBudgetDrains;
     /** Per-agent current rewind episode: the single consolidated marker's id and
      *  how many turns have been shed so far. One marker per episode, updated in
      *  place (see updateRewindMarker); cleared when the episode ends. */
@@ -570,14 +579,35 @@ export declare class AgentFramework {
      */
     start(): void;
     /**
-     * Stop the event loop. Failed module/MCPL cleanup can be retried with its
-     * original context; storage stays open until that cleanup succeeds.
-     * @param teardownTimeoutMs Optional module/MCPL wait budget. Omit to wait
-     * until cleanup settles, as required by existing module/child contracts. This
-     * does not bound earlier stream or event-loop quiescence, or cancel cleanup.
+     * 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(teardownTimeoutMs?: number | undefined): Promise<void>;
     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
+     * that stop() must find it. Invocation stays in this stack, preserving
+     * immediate mode changes; the returned promise carries its result to the
+     * caller. */
+    private trackOperatorOperation;
+    /** Whether stop() has begun: an attempt in flight (stopPromise is set before
+     * its body runs, which emits traces before the queue closes) or a closed
+     * queue (after a failed or completed stop()). The admission rule for every
+     * operator entry point, the host/command listener included. */
+    private stopHasBegun;
+    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
+     * its budget. */
+    private waitForOperatorOperations;
     private stopOwned;
     /**
      * Advance queued ContextManager work without requiring a new message.
@@ -597,6 +627,20 @@ export declare class AgentFramework {
     private flushAuxiliaryAdmission;
     private waitForAuxiliaryIdle;
     private withAuxiliaryAdmission;
+    /**
+     * Maintenance makes no provider call while a surgery holds the store. The
+     * surgery waits for the maintenance work that is running before it moves
+     * the branch, so a call that parked at the gate would make it wait on
+     * whatever reopens the gate: the end of a cooldown, or the retry turn a
+     * cooldown queues, which the hold itself keeps from starting.
+     */
+    private withdrawMaintenanceUnderSurgery;
+    /**
+     * Nor once stop() has closed provider admission: a stop that catches a
+     * tick is the framework stopping on purpose, so the call is withdrawn, as
+     * under a surgery's hold, and no failure is reported for it.
+     */
+    private withdrawMaintenanceWhenStopping;
     private auxiliaryMembraneFor;
     /**
      * A conversation agent's auxiliary calls (its context manager's
@@ -606,7 +650,11 @@ export declare class AgentFramework {
      * as a resident's are, so they bind its auxiliary calls too: a held model
      * is refused without a call, and an auxiliary call's own stated wait is
      * recorded for it. (An ephemeral run records nothing, its name being
-     * single-use, so its context manager keeps the plain membrane.)
+     * single-use, so its context manager keeps the plain membrane.) Its
+     * compression is the background work a resident's is, whether a
+     * maintenance tick or a drain after a message starts it, so it is withdrawn
+     * as a resident's is: a call made while a surgery holds the store, or once
+     * stop() has closed provider admission, is withdrawn without being sent.
      */
     private conversationAuxiliaryMembraneFor;
     /** The framework's membrane, with each complete() call passed through
@@ -645,7 +693,8 @@ export declare class AgentFramework {
      */
     private nonOwningProviderWait;
     /** Why an ephemeral run ended instead of sleeping a provider's stated wait,
-     *  for its caller. */
+     *  for its caller: the text, and the wait itself, which its rejection
+     *  carries (ProviderWaitNotSleptError). */
     private statedWaitNotSlept;
     /** When a hold's timer next fires: at its deadline, stepped past what one
      *  timer can hold. A hold with no deadline (a wait held until released, or
@@ -710,7 +759,36 @@ export declare class AgentFramework {
     private recordProviderAccelerationRecovery;
     private cancelProviderAdmission;
     private startQueuedMaintenance;
+    /** resume()'s refusal while a surgery holds the store. */
+    private refuseResumeUnderSurgery;
+    /** Whether maintenance work is running: a pass, or an over-budget drain kick. */
+    private maintenanceRunning;
+    /** Wait for the maintenance work that is running, whatever its outcome. */
+    private settleMaintenancePass;
     private runQueuedMaintenance;
+    /**
+     * One agent's maintenance failure: recorded on its run, bounded as every
+     * failure sink is (`record.error`), and logged and alerted for that agent
+     * with the whole text. A failure that lasts, such as a manager whose
+     * strategy failed to initialize, meets every pass, a few seconds apart. It
+     * is logged and alerted again only when its whole text changes, once
+     * opsAlert's cooldown for it has passed since the webhook last posted it
+     * (so the webhook, which posts a kind at most once per cooldown, hears a
+     * failure that lasts), or after a pass in which that agent's maintenance
+     * went without a failure (maintenanceFailureReported). A record whose
+     * failure isn't reported again is marked as a repeat, and a pass whose
+     * every record is a repeat that took no tick stays out of the history.
+     */
+    private reportMaintenanceFailure;
+    /**
+     * An agent's context readiness, or the error that reading it threw. The
+     * context manager refuses while its strategy's initialization is pending
+     * or has failed (context-manager 0.14), and a strategy can refuse on its
+     * own, as the autobiographical one does after a store-level branch switch
+     * it hasn't reloaded for. Every such throw is that agent's failure.
+     */
+    private contextReadiness;
+    /** 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
@@ -950,6 +1028,7 @@ export declare class AgentFramework {
         timeoutMs?: number;
         abandon?: boolean;
     }): Promise<HostModeStatus>;
+    private runQuiesce;
     /** Cancel every turn-alive stream via the quiesce_abandoned kind and give
      *  teardown a bounded grace to settle. Shared by the drain-timeout path and
      *  the already-quiesced escalation path. */
@@ -965,6 +1044,7 @@ export declare class AgentFramework {
     resume(opts?: {
         force?: boolean;
     }): 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
@@ -1035,13 +1115,28 @@ export declare class AgentFramework {
      * were activated right now — WITHOUT running inference, opening a stream, or
      * mutating agent state. Intended for debug/preview tooling.
      *
-     * Transparency contract (default): the preview is side-effect-free and
-     * leaves no trace on the system. It does only read-only work —
-     * `ContextManager.compile` (which never triggers compression itself;
-     * compression runs in the background out-of-band), tool filtering, and
-     * system-prompt assembly — then delegates to `Agent.buildActivationRequest`.
-     * No tokens are spent, nothing is written to Chronicle, and no external
-     * MCPL server is contacted.
+     * What a preview commits (default): nothing of its own. It compiles as a
+     * dry run (`dryRun`), filters tools and assembles the system prompt, then
+     * delegates to `Agent.buildActivationRequest`. No tokens are spent, no
+     * external MCPL server is contacted, no fold resolution is persisted and
+     * none of the compression its fold plan calls for is queued; the consumed
+     * watermark and any prepared budget change are left alone; and once
+     * context-manager's thinking binding (context-manager#160, not yet
+     * released) ships, no stamps are committed and no compile awaits
+     * acceptance. In context-manager 0.14 its dry run leaves nothing else
+     * behind but the release of an expired compression hold, as any compile
+     * does (see `Agent.compileWithInjections`). The preview keeps in-memory
+     * bookkeeping of its own, such as handing the context manager the
+     * compression tool definitions, as every activation request does.
+     * Under the autobiographical strategy, a budget the context can't fit
+     * still throws, as for a committing compile: a dry run skips only
+     * context-manager's post-pick check, and an adaptive fold plan that
+     * doesn't fit then overruns at the middle's emission, with a refusal that
+     * names the tokens and the limit. Windowed passthrough's newest message
+     * alone is the one window that comes back larger than the budget. For a
+     * verdict instead of the refusal, `previewContextSettings` returns
+     * context-manager's own at a budget, with the agent's `maxTokens` reserved
+     * for the response.
      *
      * The trade-off is fidelity: the dynamically-gathered ContextInjection[]
      * (module `gatherContext` + MCPL `beforeInference` hooks) are NOT included
@@ -1066,15 +1161,18 @@ export declare class AgentFramework {
      *
      * Unlike `previewActivation` (which renders a request), this returns the
      * picker's plan: resulting tokens, whether it fits, how many summaries would
-     * have to be produced first, and the per-chunk fold levels. Commits nothing:
-     * no resolution persistence, no compression enqueue, no transition
-     * bookkeeping — see `AutobiographicalStrategy.previewContext`.
+     * have to be produced first, and the per-chunk fold levels. It commits
+     * nothing: its select is a dry run, which in context-manager 0.14 leaves
+     * what a select leaves behind as the last committing compile left it —
+     * see `AutobiographicalStrategy.previewContext` and
+     * `Agent.compileWithInjections`.
      *
      * Returns null when the agent's strategy has no fold plan (non-adaptive).
      */
     previewContextSettings(agentName: string, budgetTokens: number, overrides?: Record<string, unknown>, opts?: {
         render?: boolean;
     }): unknown;
+    private previewContextFor;
     /**
      * Feasibility preview for a runtime-settings patch — or, with no patch, for
      * the agent's CURRENT settings (the resume-gate case: quiesce maintenance
@@ -1089,11 +1187,18 @@ export declare class AgentFramework {
      * the compile budget and rejected safe-by-construction paced descents.
      *
      * Never throws for preview-layer reasons: strategy without previewContext,
-     * preview overlap, stale branch generation, and the hierarchical (non-
-     * adaptive) path all come back as `{available: false, reason}`. Unknown
-     * agent still throws, matching the sibling accessors.
+     * preview overlap, stale branch generation, the hierarchical (non-
+     * adaptive) path, and a context manager that refuses its queries (its
+     * strategy's initialization pending or failed) all come back as
+     * `{available: false, reason}`. Unknown agent still throws, matching the
+     * sibling accessors, and so does a patch whose values the agent refuses,
+     * whatever its context manager's state. Whether the strategy takes live
+     * tail and pace settings is the manager's to say, so while it refuses, a
+     * patch that sets them gets no verdict either.
      */
     previewAgentRuntimeSettings(agentName: string, patch?: AgentRuntimeSettingsPatch): RuntimeSettingsPreview;
+    /** previewAgentRuntimeSettings for an agent in hand: boot restore previews one not yet registered. */
+    private previewRuntimeSettingsFor;
     /**
      * Check if process logging is enabled.
      */
@@ -1138,6 +1243,7 @@ export declare class AgentFramework {
     getSessionUsage(): SessionUsageSnapshot;
     private restoreUsageState;
     private persistUsageState;
+    /** An agent's persisted record, or null when it has none; throws when the store can't be read. */
     private readAgentRuntimeSettings;
     private validatePersistedAgentRuntimeSettings;
     /** Load resident-set inline caps from framework state, dropping (loudly)
@@ -1145,6 +1251,57 @@ export declare class AgentFramework {
     private readPersistedToolResultInlineCaps;
     /** Write (cap) or clear (null) one agent's resident-set inline cap. */
     private persistToolResultInlineCap;
+    /**
+     * Apply an agent's persisted settings at boot, each on its own, the budget
+     * last. A persisted setting never stops the agent booting, except a
+     * think-text policy, which fails closed: an invalid one is refused before
+     * this (validatePersistedAgentRuntimeSettings), and a valid one always
+     * applies. A tail, pace or budget that can't be applied now (a tail or pace
+     * on a strategy without live settings, a budget no longer above maxTokens,
+     * a lower one restored paced on a strategy that can't prepare a smaller
+     * window) is kept set but unapplied (Agent.keepRuntimeSettings), so a later
+     * persisting write keeps it in the record.
+     *
+     * A budget below the recipe's restores as a paced descent from it, unless
+     * the record carries its marker (`contextBudgetReachedTokens`, written when
+     * a compile fit at it) and the preflight says it fits now: then it is
+     * applied at once. The preflight plans the stored context as the context
+     * manager will, with the restored tail and pace, so it sees what a restart
+     * can change there: a new maxTokens (the response reserve) or strategy
+     * configuration. It also sees a context that grew while the agent ran at
+     * another budget after the record was written, through a persist: false
+     * change. The system prompt, tools and injections are outside the context
+     * manager's budget, so they don't enter it (context-manager #162). If a
+     * compile at a budget applied at once this way is refused, the agent
+     * restores it paced then (armed by Agent.restoreRuntimeSettings, run in
+     * Agent.compileAtLiveBudgetNoting). A budget at or above the recipe's is
+     * applied at once with or without the marker, as an increase always is.
+     *
+     * When a marked budget isn't applied at once or a setting can't be
+     * applied, one line says why, what couldn't be applied, and the budget set
+     * beside the one compiles plan at.
+     */
+    private restorePersistedRuntimeSettings;
+    /**
+     * What persists for an agent: its overrides, and `contextBudgetReachedTokens`
+     * when the agent's proof stands for the overridden budget: a compile fit at
+     * it, or the boot applied it at once on the record's proof, and the live
+     * budget hasn't changed since (context-manager #162). A
+     * change of budget, immediate or not, carries none until a compile at it
+     * fits; arming or cancelling a descent leaves the proof as it was.
+     */
+    private persistedRuntimeSettingsOf;
+    /**
+     * A compile at the agent's live budget came out differently from the last
+     * (Agent.onContextBudgetCompiled). Keep the persisted record's
+     * `contextBudgetReachedTokens` true to it: written when a compile fits at
+     * the record's own budget, withdrawn when the context manager refuses that
+     * budget. Nothing else in the record changes, and a budget other than the
+     * record's (one applied with `persist: false`, or a descent's starting
+     * budget) writes nothing. A record that can't be read, or written, is
+     * logged, and the next compile at that budget tells it again.
+     */
+    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
@@ -1179,6 +1336,17 @@ export declare class AgentFramework {
      * events after an ephemeral/conversation agent has been disposed. */
     private recordLogicalTurnToolCalls;
     private recordEphemeralToolCalls;
+    /**
+     * A start dropped before its stream sends anything (its agent was replaced,
+     * or stop() closed admission or ended the lifecycle the start began in)
+     * ends the logical turn it was running. stop() ends every open turn
+     * (openLogical), but a fresh start that awaited its batches' assembly
+     * across a stop() reaches its routing after it and opens its turn. That
+     * turn would then stay open, and the agent's first start after a restart
+     * would continue the dropped turn's routing. The identity check leaves any
+     * other turn open.
+     */
+    private endDroppedTurn;
     /** A logical turn's end, for every agent: it closes the agent's open
      *  logical turn when it is the settling stream's own (openLogical), and
      *  settles an active ephemeral run. The run's tool-call count comes from
@@ -1191,6 +1359,9 @@ export declare class AgentFramework {
      * The agent is temporarily registered, inference is triggered, and the
      * framework drives the stream (emitting traces, logging, dispatching tools).
      * Returns the agent's speech output when it finishes (no more tool calls).
+     * Rejects with ProviderWaitNotSleptError when the run ends rather than sleep
+     * a retryable failure's stated wait, and with a plain Error for any other
+     * ending.
      *
      * The caller provides a pre-created agent + contextManager (from createEphemeralAgent).
      * The task message should already be in the context manager.
@@ -1340,6 +1511,8 @@ export declare class AgentFramework {
      *   explicit, recorded operator override.
      */
     private handleHostCommand;
+    /** handleHostCommand's work, run where stop() can wait for it. */
+    private runHostCommand;
     /**
      * The last message the agent would see in its context right now, via the
      * transparent `previewActivation` render (no inference, no Chronicle
@@ -1370,6 +1543,22 @@ export declare class AgentFramework {
      * Get the most recent process logs (tail).
      */
     tailProcessLogs(count?: number, eventType?: string): ProcessLogEntryWithId[];
+    /**
+     * Switch the store to an existing branch, start the delivery of the
+     * Discord awareness marks the move changes (startDiscordAwarenessDelivery),
+     * and re-materialize the config mount from it. Resolves once the mount has
+     * run; if it fails, it rejects with the store already moved. The marks'
+     * delivery isn't awaited, and its failure doesn't fail the switch. The
+     * store has moved by the time the call returns, before its promise
+     * settles, and a refusal moves nothing. An operator's operation: refused
+     * once stop() has begun, and waited for by stop() while it runs.
+     *
+     * The branch moves under every agent sharing the store, so the switch
+     * reserves the store as a surgery does: every agent must be idle, or it is
+     * refused (OperatorActionError 'agent-busy'), and no turn starts until the
+     * switch is done.
+     */
+    switchBranch(name: string): Promise<void>;
     /**
      * Undo the last inference turn for an agent.
      *
@@ -1386,6 +1575,9 @@ export declare class AgentFramework {
         fromBranch?: string;
         toBranch?: string;
     };
+    /** undoLastTurn's work, for a host/command undo already admitted: a stop()
+     *  begun by a trace of one of its turns doesn't refuse the next. */
+    private runUndoLastTurn;
     /**
      * Redo a previously undone turn for an agent.
      *
@@ -1543,9 +1735,9 @@ export declare class AgentFramework {
      * undo or redo) without the caller awaiting it. No operator response waits
      * for Discord to accept marks: the MCPL data-plane gate alone holds channel
      * traffic that arrives after it until they are attempted.
-     * `syncDiscordAwarenessMarkers` installs that gate synchronously, before
-     * its first await, so calling this while a surgery still holds the store
-     * puts the gate up before the store is released. With no drain running, the
+     * The sync's body installs that gate synchronously, before its first
+     * await, so calling this while a surgery still holds the store puts the
+     * gate up before the store is released. With no drain running, the
      * drain starts in the same synchronous run (the first reaction request can
      * be written before this returns); with one running, this generation's pass
      * follows it (drainForGeneration). Either way delivery continues
@@ -1556,10 +1748,20 @@ export declare class AgentFramework {
      * (queued when a surgery began, or arriving during its switch or fork): the
      * surgery's store reservation, which used to hold such a turn through the
      * drain, now ends once the gate is up. A failure is accounted by the gate
-     * itself: the current generation's failure recycles the connections, and a
-     * superseded one leaves that to the newer generation, whose own pass meets
-     * the same ledger. Here it is logged and raised as an ops alert, and the
-     * next sync, reconnect or start delivers what is still pending.
+     * itself: the current generation's failure recycles the connections (or,
+     * once the host is stopping, releases the gate instead), and a superseded
+     * one leaves that to the newer generation, whose own pass meets the same
+     * ledger. Here it is logged and raised as an ops alert, and the next sync,
+     * 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.
      *
      * @param after What moved the branch, for the log and the alert
      *   ("rollback", "branch switch", "undo" …).
@@ -1567,8 +1769,8 @@ export declare class AgentFramework {
      *   branch switch that names none.
      */
     startDiscordAwarenessDelivery(after: string, agentName?: string): void;
-    /** Re-materialize config files from the (new) active branch — fire and
-     *  forget; the gate picks changes up via mtime. Mirrors undoLastTurn. */
+    /** Start config file IO without holding the caller or a surgery's store
+     * reservation. The gate picks it up by mtime; stop() still waits for it. */
     private materializeConfigMountAfterBranchSwitch;
     /**
      * Check if undo/redo is available for an agent.
@@ -1651,9 +1853,10 @@ export declare class AgentFramework {
     /**
      * Spawn a persistent per-channel conversation agent ("fork") from the
      * template agent: own ContextManager under `conversations/{name}`, seeded
-     * with a copy of the template's compiled context (the SubagentModule
-     * wholesale-copy pattern), registered in the event loop like any agent —
-     * but never primary.
+     * with the template's compiled context without its thinking or its unpaired
+     * tool blocks (the SubagentModule wholesale-copy pattern; see the seeding
+     * comment below), registered in the event loop like any agent — but never
+     * primary.
      */
     private createConversationAgent;
     /** Persist the router's generation counters (see hydration in create()). */
@@ -1822,6 +2025,59 @@ export declare class AgentFramework {
      * inference; never locus-eligible itself (system + no channel metadata).
      */
     private announceLocusIfChanged;
+    /**
+     * The channel a message moves its turn's locus to, by the addressed
+     * re-pin rule (2026-07-31, n=6 and n=7): a conversational message (not a
+     * reaction or a system marker) that addressed the agent, or that follows
+     * up in a channel the turn sent into (TurnRouting.engaged). Undefined for
+     * any other message. A tool boundary weighs the messages it injects by it,
+     * and noteArrival the ones no boundary of the turn weighs.
+     */
+    private repinChannel;
+    /**
+     * Weigh a message that no tool boundary of the agent's open logical turn
+     * will weigh: one that would re-pin the locus becomes one of the turn's
+     * arrivals (TurnRouting.arrivals). A message tune-out diverted
+     * (metadata.tuneOut) never enters a resident's compiled view, so the agent
+     * won't see it, and it moves nothing.
+     */
+    private noteArrival;
+    /**
+     * Whether `agent`'s store is the residents' one message slot, which every
+     * ordinary resident reads (sharedSlotAgents). The subconscious reads that
+     * slot through a merged view, but its own store is isolated, as a fork's
+     * or an ephemeral agent's is.
+     */
+    private isOrdinaryResident;
+    /**
+     * Weigh a message just stored in an ordinary resident's store for every
+     * other ordinary resident's open turn, running or not: residents read one
+     * message slot, and a tool boundary weighs only the messages drained for
+     * its own agent, so no boundary of another resident's turn weighs it.
+     */
+    private noteForOtherResidents;
+    /**
+     * The channel of the turn's newest arrival whose message is still in the
+     * agent's store (TurnRouting.arrivals). A message removed since it was
+     * stored, such as an unread coalesced message its server retracted, moves
+     * nothing, and an earlier one that remains still does. Compression keeps a
+     * message in the store; the last compile can't be the test, since an
+     * arrival between the turn's streams isn't in it yet.
+     */
+    private remainingArrival;
+    /**
+     * Move a turn's locus to the channel its conversation moved to: an
+     * addressed message, or a follow-up in a channel the turn engaged (the
+     * addressed re-pin, repinChannel). Ambient chatter never moves it. Leaves
+     * a durable `[routing]` notice in the window and updates
+     * lastAnnouncedLocus once it's stored, so the next turn's announce-on-change
+     * diffs against what the agent was last told. Returns the notice as stored, for a live
+     * stream to inject with its boundary's other messages. Returns undefined
+     * when the locus is already there, and when the notice couldn't be
+     * stored. The locus has moved then too, but the announce baseline hasn't,
+     * so the agent's next turn announces where its speech lands.
+     */
+    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
@@ -1881,6 +2137,18 @@ export declare class AgentFramework {
      */
     private maybePrimeProseMode;
     private startAgentStream;
+    /**
+     * End a turn that beginAgentTurn drops before it sends anything. The turn
+     * emitted inference:started, and listeners that bracket a turn, such as a
+     * typing loop or an activity indicator, end it on a terminal event, so it
+     * gets inference:aborted with `reason`, and lastInference records its end
+     * as driveStream's would, when the record is still this turn's. Nothing of
+     * the kind when another turn of this agent's name holds the turn token (one
+     * begun after a stop and start, or by a replacement agent object): the
+     * event and the record carry only the name, so this frame's would end that
+     * newer turn instead.
+     */
+    private abortDroppedTurn;
     /**
      * 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
@@ -1942,6 +2210,8 @@ export declare class AgentFramework {
         toolUseId: string;
         result: ToolResult;
     }>;
+    /** puppetToolCall's work, run where stop() can wait for it. */
+    private runPuppetToolCall;
     private executeToolCallFrom;
     private executeMcplToolCall;
     /** Event-pushing wrapper for the model-driven dispatch path. */
@@ -2252,9 +2522,16 @@ export declare class AgentFramework {
     /**
      * 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
-     * pass (drainForGeneration).
-     */
-    syncDiscordAwarenessMarkers(_onlyServerId?: string): Promise<void>;
+     * pass (drainForGeneration). Like the other operator entry points, it's
+     * refused once stop() has begun, and stop() waits for one already running.
+     * The framework's own branch moves start their delivery without awaiting
+     * it (startDiscordAwarenessDelivery).
+     */
+    syncDiscordAwarenessMarkers(onlyServerId?: string): Promise<void>;
+    /** The sync's work. It installs the MCPL data-plane gate before its first
+     *  await, so a caller that starts it while holding the store puts the gate
+     *  up before releasing the store. */
+    private runDiscordAwarenessSync;
     private resumePreparedDiscordSuppressions;
     /**
      * Deliver every due ref independently. Permanent Discord failures are kept
@@ -2385,6 +2662,7 @@ export declare class AgentFramework {
      * connection/handshake fails.
      */
     connectMcplServer(config: import('./mcpl/types.js').McplServerConfig): Promise<void>;
+    private runConnectMcplServer;
     /**
      * Disconnect an MCPL server at runtime: close the connection, destroy its
      * feature-set and checkpoint state (permanent removal — unlike a transient
@@ -2393,6 +2671,7 @@ export declare class AgentFramework {
      * No-op-ish if the server is not connected (still clears routing state).
      */
     disconnectMcplServer(id: string): Promise<void>;
+    private runDisconnectMcplServer;
     /**
      * Restart an MCPL server at runtime: disconnect, then reconnect with the
      * same (or an updated) config. This actually respawns a stdio child —
@@ -2400,6 +2679,7 @@ export declare class AgentFramework {
      * failures. Throws if the server has no stored config and none is given.
      */
     restartMcplServer(id: string, newConfig?: import('./mcpl/types.js').McplServerConfig): Promise<void>;
+    private runRestartMcplServer;
     /**
      * List configured MCPL servers with live connection status and the number
      * of tools each currently contributes.