@animalabs/agent-framework 0.15.0 → 0.17.0

package/dist/src/framework.js

@@ -1,7 +1,7 @@
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { INLINE_WITHHELD_TEXT, classifyBlock, isInlineContradiction, referenceRegistry, referenceStubOrNull } from './mcpl/references.js';
 import { ReferenceFetcher, DEFAULT_FETCH_MAX_BYTES, EAGER_FETCH_TIMEOUT_MS } from './mcpl/reference-fetcher.js';
-import { appendFileSync, mkdirSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { JsStore } from '@animalabs/chronicle';
 import { MembraneError } from '@animalabs/membrane';
 import { ContextManager, PassthroughStrategy, WindowedPassthroughStrategy } from '@animalabs/context-manager';
@@ -284,7 +284,23 @@ import { EventGate, formatShadowWarning } from './gate/event-gate.js';
 import { UsageTracker } from './usage/usage-tracker.js';
 import { formatZonedDateTime, resolveTimeZone } from './timezone.js';
 import { DEFAULT_DISCORD_AWARENESS_EMOJI, DiscordAwarenessOutbox, defaultDiscordAwarenessOutboxPath, extractDiscordAwarenessRefs, } from './recovery/discord-awareness-outbox.js';
+import { OperatorActionError, OperatorLog, capIds, defaultOperatorLogPath, } from './operator-log.js';
 const FRAMEWORK_STATE_ID = 'framework/state';
+/** Snapshot slot mirroring context writes deferred while quiesced (#122). */
+const DEFERRED_WRITES_ID = 'framework/deferred-writes';
+/** Above this serialized size the deferred-write mirror is skipped (kept in
+ *  memory only) rather than rewriting a multi-MB snapshot per deferral. */
+const DEFERRED_WRITES_PERSIST_CAP_BYTES = 4 * 1024 * 1024;
+const bySeq = (a, b) => a.seq - b.seq;
+/** Stamp a deferred write's durable id into the metadata it is stored with
+ *  (boot recovery dedups replays by it). Idempotent for an already-stamped
+ *  message. */
+function withDeferredWriteId(metadata, id) {
+    return { ...(metadata ?? {}), deferredWriteId: id };
+}
+function isTurnContinuation(reason) {
+    return reason === 'context_budget_restart' || reason === 'tool_results_ready';
+}
 const CONVERSATION_ROUTER_STATE_ID = 'framework/conversation-router';
 const INFERENCE_LOG_ID = 'framework/inference-log';
 const PROCESS_LOG_ID = 'framework/process-log';
@@ -308,6 +324,37 @@ class DiscordAwarenessAccountingError extends Error {
         this.name = 'DiscordAwarenessAccountingError';
     }
 }
+/**
+ * Thrown by `updateAgentRuntimeSettings` when an immediate budget change would
+ * put the agent in an un-compilable layout: the folded floor renders more
+ * tokens than the hard budget admits, so every subsequent compile would
+ * OverBudget-wedge the agent (2026-08-21: mythos, 550k→260k set live against a
+ * ~450k floor — hours of hard-down). Overridable with `{ allowInfeasible: true }`.
+ * Paced descents never throw this: a non-immediate decrease leaves the compile
+ * budget untouched and converges only as far as the floor allows.
+ */
+export class BudgetPreflightError extends Error {
+    preview;
+    constructor(message, preview) {
+        super(message);
+        this.preview = preview;
+        this.name = 'BudgetPreflightError';
+    }
+}
+/**
+ * Thrown by `resume()` when the current runtime settings do not compile for
+ * one or more agents — returning to service would OverBudget-wedge them on
+ * the first wake. Drain quarantine / advance merges to lower the floor, or
+ * pass `{ force: true }` after deciding the verdicts are acceptable.
+ */
+export class ResumeBlockedError extends Error {
+    verdicts;
+    constructor(message, verdicts) {
+        super(message);
+        this.verdicts = verdicts;
+        this.name = 'ResumeBlockedError';
+    }
+}
 /**
  * Default inference policy - infer if any request exists for the agent.
  */
@@ -316,6 +363,64 @@ class DefaultInferencePolicy {
         return requests.some((r) => r.agentName === agentName);
     }
 }
+const SURGERY_SCAN_WINDOW = 500;
+/**
+ * Slot index of `messageId` on the active branch, or -1. Scans from the tail
+ * in blob-free windows: operator targets are almost always recent, and a
+ * full `getAllMessages()` re-inflates every attachment on the branch.
+ */
+function locateMessageIndex(cm, messageId) {
+    const hit = locateMessageIndices(cm, new Set([messageId])).get(messageId);
+    return hit ? hit.index : -1;
+}
+/** Tail-first scan resolving many ids at once; stops as soon as all are found. */
+function locateMessageIndices(cm, ids) {
+    const found = new Map();
+    const total = cm.getMessageCount();
+    for (let end = total; end > 0 && found.size < ids.size; end -= SURGERY_SCAN_WINDOW) {
+        const start = Math.max(0, end - SURGERY_SCAN_WINDOW);
+        const { messages, startIndex } = cm.getMessageWindow(start, end - start, { resolveBlobs: false });
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const id = String(messages[i].id);
+            if (ids.has(id) && !found.has(id)) {
+                found.set(id, {
+                    index: startIndex + i,
+                    ...(messages[i].bodyGroupId ? { bodyGroupId: messages[i].bodyGroupId } : {}),
+                });
+            }
+        }
+    }
+    return found;
+}
+/**
+ * Inclusive slot range of the body-group run containing `index` (the slot
+ * itself when it is not sharded). Delegates to the store's own
+ * `alignToBodyGroups` edge walk — one contiguity assumption, not two.
+ */
+function bodyGroupRun(cm, index) {
+    const win = cm.getMessageWindow(index, 1, { alignToBodyGroups: true, resolveBlobs: false });
+    const from = win.startIndex;
+    const to = win.startIndex + win.messages.length - 1;
+    return {
+        from,
+        to,
+        fromId: String(win.messages[0].id),
+        toId: String(win.messages[win.messages.length - 1].id),
+        group: win.messages[0].bodyGroupId !== undefined,
+    };
+}
+function describeRequester(r) {
+    if (!r)
+        return 'unknown';
+    return `${r.name ?? r.id ?? 'unknown'} (${r.via})`;
+}
+function hostCommandRequester(serverId, params) {
+    return {
+        via: `host-command:${serverId}`,
+        ...(params.requesterName ? { name: params.requesterName } : {}),
+        ...(params.requesterId ? { id: params.requesterId } : {}),
+    };
+}
 function isPermanentDiscordReactionFailure(message) {
     return /unknown message|unknown channel|missing access|missing permissions|missing permission|cannot access|channel .* not found|message .* not found/i
         .test(message);
@@ -421,6 +526,17 @@ export class AgentFramework {
     activeTriggerChannels = new Map();
     running = false;
     loopPromise = null;
+    /** Quiesce/maintenance mode (issue #122). DELIBERATELY separate from
+     * `running`, which is overloaded as the runLoop condition, the maintenance
+     * admission guard, AND the per-tick loop condition — expressing "paused" by
+     * clearing `running` would kill the very maintenance machinery quiesce
+     * exists to keep hot, plus store sync and tool-result processing. While
+     * quiesced: runLoop, syncTimer, maintenanceTimer, and the watchdog all keep
+     * running; only new turns (wake gate in processInferenceRequests) and MCPL
+     * data planes are held. */
+    quiesced = false;
+    quiesceReason;
+    quiescedAt;
     traceListeners = [];
     syncIntervalMs;
     syncTimer = null;
@@ -436,6 +552,7 @@ export class AgentFramework {
     providerAccelerationLastRecovery = new Map();
     providerAccelerationDefaultCooldownMs = PROVIDER_ACCELERATION_DEFAULT_COOLDOWN_MS;
     providerAccelerationJitterMs = PROVIDER_ACCELERATION_JITTER_MS;
+    providerHoldHook;
     providerAdmissionClosed = false;
     /** Last time we reported stale (busy-requeued) inference requests, per agent. */
     staleWarnAt = new Map();
@@ -591,6 +708,36 @@ export class AgentFramework {
     subconsciousConfig = null;
     /** Tune-out coordinator (issue #77); non-null iff subconscious + channels. */
     tuneOutCoordinator = null;
+    /** Agents an abandon could not cancel (token held, no stream) — surfaced
+     *  in HostModeStatus until the next quiesce/resume. */
+    lastUnabandonable = [];
+    /** True while the deferred-write queue has a persisted mirror (quiesced). */
+    deferredWritesPersisted = false;
+    deferredWritesCapWarned = false;
+    /** Branch-independent recovery files (see FrameworkConfig.hostModePath /
+     *  deferredWritesPath). Undefined → branch-local slot fallback. */
+    hostModePath;
+    deferredWritesPath;
+    recoveryFallbackWarned = false;
+    /**
+     * Deferred writes that have been handed to a context manager but whose
+     * chronicle state is NOT yet durably synced. They stay in the durable
+     * recovery queue until `ackDeferredWrites()` syncs the store — chronicle
+     * persists the slot-chain head only on sync(), so acknowledging on append
+     * alone would let a hard exit forget an accepted message.
+     */
+    unackedDeferredWrites = [];
+    /** Monotonic order stamp for deferred writes: the durable queue is always
+     *  written, restored, drained and flushed in `seq` order, whatever the
+     *  pending/un-acked split — a re-deferred entry keeps its place. */
+    deferredSeq = 0;
+    /**
+     * Per target agent: the store's message count when the OLDEST currently
+     * un-acked entry for it was handed off. Persisted with the queue so a boot
+     * after an interrupted flush knows exactly which slot range the batch
+     * could occupy and dedups against all of it — never a fixed tail.
+     */
+    deferredScanFrom = new Map();
     deferredMessages = [];
     // Turn-alive markers (2026-07-31 Mythos phantom-skip incident): agentName →
     // token of the turn currently in progress. Set at startAgentStream ENTRY —
@@ -702,6 +849,16 @@ export class AgentFramework {
     discordAwarenessOutbox = null;
     discordAwarenessEmoji = DEFAULT_DISCORD_AWARENESS_EMOJI;
     discordAwarenessDeadlineMs = DEFAULT_DISCORD_AWARENESS_DEADLINE_MS;
+    /** Durable JSONL record of operator-initiated mutations (see operator-log.ts). */
+    operatorLog;
+    /**
+     * Store-wide admission barrier while a live surgery (rollback/suppress)
+     * holds the store. Per-agent turn tokens cover the agents registered when
+     * the reservation was taken; this flag covers everyone else — an ephemeral
+     * agent admitted mid-switch, a wake for an agent created later — at the
+     * scheduler, ephemeral admission and puppet entry points.
+     */
+    surgeryHold = null;
     /** Serialize per-server drains so reconnect and an online undo cannot race. */
     discordAwarenessDrains = new Map();
     /** Framework-global inference gate; older generations cannot release it. */
@@ -713,7 +870,8 @@ export class AgentFramework {
     usageTracker;
     /** Presentation-only wall-clock zone; persistence remains UTC/epoch. */
     timeZone;
-    constructor(store, ownsStore, membrane, inferencePolicy, errorPolicy, syncIntervalMs, maintenanceIntervalMs, processLoggingPersist, processLoggingBroadcast, timeZone, discordAwarenessOutbox, discordAwarenessEmoji, discordAwarenessDeadlineMs) {
+    constructor(store, ownsStore, membrane, inferencePolicy, errorPolicy, syncIntervalMs, maintenanceIntervalMs, processLoggingPersist, processLoggingBroadcast, timeZone, discordAwarenessOutbox, discordAwarenessEmoji, discordAwarenessDeadlineMs, operatorLog = new OperatorLog(undefined)) {
+        this.operatorLog = operatorLog;
         this.store = store;
         this.ownsStore = ownsStore;
         this.membrane = membrane;
@@ -774,6 +932,12 @@ export class AgentFramework {
         catch {
             // Already registered
         }
+        try {
+            store.registerState({ id: DEFERRED_WRITES_ID, strategy: 'snapshot' });
+        }
+        catch {
+            // Already registered
+        }
         try {
             store.registerState({
                 id: INFERENCE_LOG_ID,
@@ -816,7 +980,17 @@ export class AgentFramework {
         const discordAwarenessOutbox = discordAwarenessOutboxPath
             ? new DiscordAwarenessOutbox(discordAwarenessOutboxPath)
             : null;
-        const framework = new AgentFramework(store, ownsStore, config.membrane, config.inferencePolicy ?? new DefaultInferencePolicy(), config.errorPolicy ?? new DefaultErrorPolicy(), config.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, config.maintenanceIntervalMs ?? DEFAULT_MAINTENANCE_INTERVAL_MS, processLoggingPersist, processLoggingBroadcast, resolveTimeZone(config.timeZone), discordAwarenessOutbox, config.discordAwarenessEmoji ?? DEFAULT_DISCORD_AWARENESS_EMOJI, normalizeDiscordAwarenessDeadline(config.discordAwarenessDeadlineMs));
+        const operatorLogPath = config.operatorLogPath === false
+            ? undefined
+            : config.operatorLogPath
+                ?? (config.storePath ? defaultOperatorLogPath(config.storePath) : undefined);
+        if (operatorLogPath === undefined && config.operatorLogPath !== false) {
+            // An audit log that is silently off is worse than none: say so once.
+            console.error('[operator-log] disabled: no storePath and no operatorLogPath configured — ' +
+                'operator actions will only be visible as operator:action traces');
+        }
+        const framework = new AgentFramework(store, ownsStore, config.membrane, config.inferencePolicy ?? new DefaultInferencePolicy(), config.errorPolicy ?? new DefaultErrorPolicy(), config.syncIntervalMs ?? DEFAULT_SYNC_INTERVAL_MS, config.maintenanceIntervalMs ?? DEFAULT_MAINTENANCE_INTERVAL_MS, processLoggingPersist, processLoggingBroadcast, resolveTimeZone(config.timeZone), discordAwarenessOutbox, config.discordAwarenessEmoji ?? DEFAULT_DISCORD_AWARENESS_EMOJI, normalizeDiscordAwarenessDeadline(config.discordAwarenessDeadlineMs), new OperatorLog(operatorLogPath));
+        framework.providerHoldHook = config.providerHold;
         // If an offline recovery process crashed after switching Chronicle but
         // before committing its prepared marker batch, the active branch is the
         // commit record. Promote it now; no quarantined content is read.
@@ -936,6 +1110,56 @@ export class AgentFramework {
         for (const [agentName, cap] of Object.entries(framework.readPersistedToolResultInlineCaps())) {
             framework.toolResultInlineMaxCharsOverride.set(agentName, cap);
         }
+        // Restore persisted quiesce mode (issue #122) BEFORE initializeMcpl: the
+        // flag must be set before any data-plane barrier completion can run, or
+        // the startup funnel would open the data planes on a host that shut down
+        // mid-maintenance. Staged connections boot with both planes closed, so a
+        // quiesced boot needs no re-pause — completeMcplDataPlaneGate consults
+        // the flag and holds data planes (control planes come up normally). The
+        // gate already exists at this point, so the suppression is wired here too.
+        //
+        // Both records live OUTSIDE branch history (recovery/ files next to the
+        // store): a historical rollback must not be able to erase the marker of
+        // the very surgery it belongs to, nor orphan the writes deferred by it.
+        framework.hostModePath = config.hostModePath
+            ?? (config.storePath ? join(config.storePath, 'recovery', 'host-mode.json') : undefined);
+        framework.deferredWritesPath = config.deferredWritesPath
+            ?? (config.storePath ? join(config.storePath, 'recovery', 'deferred-writes.json') : undefined);
+        {
+            const hostMode = framework.readHostMode();
+            // Deferred writes are recovered REGARDLESS of the mode flag: a crash
+            // between a resume's flag clear and the end of its flush must not
+            // strand accepted messages. Per-message acks mean only the remainder
+            // replays. Serving boot with a remainder → flush it right now (no turn
+            // is alive yet, so this is a safe boundary).
+            const restoredWrites = framework.restorePersistedDeferredWrites();
+            if (!hostMode?.quiesced && restoredWrites > 0) {
+                console.error(`[host-mode] ${restoredWrites} deferred context write(s) found at a serving boot ` +
+                    `(an earlier resume did not finish its flush) — landing them now`);
+                await framework.flushDeferredWrites('boot-recovery');
+            }
+            if (hostMode?.quiesced) {
+                framework.quiesced = true;
+                framework.quiesceReason = hostMode.reason;
+                framework.quiescedAt = hostMode.since;
+                framework.eventGate?.setQuiesced(true);
+                console.error(`[host-mode] ============================================================\n` +
+                    `[host-mode] BOOTING QUIESCED (persisted${hostMode.reason ? `: ${hostMode.reason}` : ''}, ` +
+                    `since ${hostMode.since ? new Date(hostMode.since).toISOString() : 'unknown'}).\n` +
+                    `[host-mode] No wakes will start turns and MCPL data planes stay paused\n` +
+                    `[host-mode] until resume() — via host/command, the API server, or the\n` +
+                    `[host-mode] framework API. Wakes parked before the restart were in-memory\n` +
+                    `[host-mode] and are gone; recurring sources re-deliver on their own cadence.\n` +
+                    `[host-mode] ${restoredWrites} deferred context write(s) restored from the store;\n` +
+                    `[host-mode] they land at resume().\n` +
+                    `[host-mode] ============================================================`);
+                framework.emitTrace({
+                    type: 'host:quiesced_boot',
+                    ...(hostMode.reason ? { reason: hostMode.reason } : {}),
+                    ...(hostMode.since !== undefined ? { since: hostMode.since } : {}),
+                });
+            }
+        }
         // Initialize MCPL subsystems if configured
         if (config.mcplServers && config.mcplServers.length > 0) {
             // Validate tool prefixes: no collisions with module names or between servers
@@ -1040,6 +1264,9 @@ export class AgentFramework {
      */
     async stop() {
         this.running = false;
+        // Flushed-but-unsynced deferred writes: sync and ack now, while the
+        // store is still open, rather than leaving them to a reboot replay.
+        this.ackDeferredWrites();
         this.providerAdmissionClosed = true;
         this.queue.close();
         this.tuneOutCoordinator?.stop();
@@ -1177,6 +1404,15 @@ export class AgentFramework {
         try {
             return await run();
         }
+        catch (error) {
+            // Compression can be the first call to find a spent quota (idle agent,
+            // scheduled maintenance). Arm the host hold so later passes wait at the
+            // gate instead of retrying into it; this pass still fails to its caller.
+            const agent = this.agents.get(agentName);
+            if (agent && error instanceof Error)
+                this.holdProviderAcceleration(agent, error, undefined, true);
+            throw error;
+        }
         finally {
             gate.auxiliaryInFlight = Math.max(0, gate.auxiliaryInFlight - 1);
             if (gate.auxiliaryInFlight === 0)
@@ -1206,11 +1442,51 @@ export class AgentFramework {
         return a.agentName === b.agentName && a.reason === b.reason && a.source === b.source &&
             a.timestamp === b.timestamp && a.channelId === b.channelId;
     }
-    holdProviderAcceleration(agent, error, trigger) {
-        if (this.ephemeralRuns.has(agent.name) || this.conversationAgentHomes.has(agent.name) || !isOrganizationAccelerationRateLimit(error))
+    consultProviderHold(error, agentName) {
+        if (!this.providerHoldHook)
+            return undefined;
+        try {
+            const hold = this.providerHoldHook(error, agentName, { model: this.agents.get(agentName)?.model });
+            if (!hold || !Number.isFinite(hold.holdMs) || hold.holdMs <= 0)
+                return undefined;
+            return { holdMs: Math.min(PROVIDER_ACCELERATION_MAX_COOLDOWN_MS, Math.max(1_000, hold.holdMs)),
+                reason: typeof hold.reason === 'string' && hold.reason ? hold.reason : error.message };
+        }
+        catch (err) {
+            console.error(`[provider-cooldown] providerHold hook threw for ${agentName}; treating as no hold:`, err);
+            return undefined;
+        }
+    }
+    /** A host hold whose slice expired: ask the host again before spending an
+     *  inference on it. True = extended in place (held requests stay held). */
+    extendHostProviderHold(agentName, cooldown) {
+        if (!cooldown.hostHoldError)
+            return false;
+        const hold = this.consultProviderHold(cooldown.hostHoldError, agentName);
+        if (!hold)
+            return false;
+        clearTimeout(cooldown.timer);
+        cooldown.until = Date.now() + hold.holdMs;
+        cooldown.timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agentName), hold.holdMs);
+        cooldown.timer.unref?.();
+        if (hold.reason !== cooldown.reason) {
+            cooldown.reason = hold.reason;
+            console.error(`[provider-cooldown] agent=${agentName} host hold extended — ${hold.reason}`);
+        }
+        return true;
+    }
+    holdProviderAcceleration(agent, error, trigger, auxiliary = false) {
+        if (this.ephemeralRuns.has(agent.name) || this.conversationAgentHomes.has(agent.name))
+            return false;
+        // The host knows more than the message wording does: ask it first. An
+        // auxiliary failure arms host holds only — the built-in acceleration
+        // cooldown stays a primary-path mechanism.
+        const hostHold = this.consultProviderHold(error, agent.name);
+        const acceleration = !hostHold && !auxiliary && isOrganizationAccelerationRateLimit(error);
+        if (!acceleration && !hostHold)
             return false;
         const now = Date.now();
-        const delayMs = this.accelerationCooldownMs(agent.name, error);
+        const delayMs = hostHold ? hostHold.holdMs : this.accelerationCooldownMs(agent.name, error);
         const existing = this.providerAccelerationCooldowns.get(agent.name);
         const held = existing?.heldRequests ?? [];
         if (trigger && !held.some((r) => this.sameInferenceRequest(r, trigger)))
@@ -1220,13 +1496,20 @@ export class AgentFramework {
         const timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agent.name), delayMs);
         timer.unref?.();
         this.providerAccelerationCooldowns.set(agent.name, { startedAt: existing?.startedAt ?? now,
-            until: now + delayMs, timer, heldRequests: held, reason: error.message,
-            failures: (existing?.failures ?? 0) + 1 });
+            until: now + delayMs, timer, heldRequests: held, reason: hostHold?.reason ?? error.message,
+            failures: (existing?.failures ?? 0) + 1, ...(hostHold ? { hostHoldError: error } : {}),
+            ...(auxiliary && (!existing || existing.auxiliaryOrigin) ? { auxiliaryOrigin: true } : {}) });
+        if (auxiliary && !existing) {
+            console.error(`[provider-cooldown] agent=${agent.name} host hold (${hostHold.reason}) from an auxiliary call — ` +
+                `holding primary/auxiliary for ${delayMs}ms`);
+            return true;
+        }
         const gate = this.providerGate(agent.name);
         gate.primaryPending = true;
         this.providerAccelerationRecoveries.set(agent.name, { startedAt: existing?.startedAt ?? now,
             failures: (existing?.failures ?? 0) + 1, heldRequests: held.length, reason: error.message });
-        console.error(`[provider-cooldown] agent=${agent.name} organization acceleration 429 — ` +
+        console.error(`[provider-cooldown] agent=${agent.name} ` +
+            `${hostHold ? `host hold (${hostHold.reason})` : 'organization acceleration 429'} — ` +
             `holding primary/auxiliary for ${delayMs}ms; ${held.length} request(s) retained`);
         return true;
     }
@@ -1234,8 +1517,16 @@ export class AgentFramework {
         const cooldown = this.providerAccelerationCooldowns.get(agentName);
         if (!cooldown)
             return;
+        if (this.extendHostProviderHold(agentName, cooldown))
+            return;
         clearTimeout(cooldown.timer);
         this.providerAccelerationCooldowns.delete(agentName);
+        if (cooldown.auxiliaryOrigin && cooldown.heldRequests.length === 0) {
+            // Nobody asked for an inference while parked: just reopen the gate.
+            console.error(`[provider-cooldown] agent=${agentName} auxiliary hold released after ${Date.now() - cooldown.startedAt}ms`);
+            this.flushAuxiliaryAdmission(agentName);
+            return;
+        }
         const recovery = this.providerAccelerationRecoveries.get(agentName);
         if (recovery) {
             recovery.releasedAt = Date.now();
@@ -1766,10 +2057,60 @@ export class AgentFramework {
         const agent = this.agents.get(agentName);
         if (!agent)
             throw new Error(`Unknown agent: ${agentName}`);
+        // Feasibility preflight — only a budget-bearing patch can wedge, and only
+        // on the immediate path (a paced descent leaves the compile budget alone
+        // and converges only as far as the folded floor allows). Boot restore
+        // deliberately bypasses this wrapper (createAgent → restoreRuntimeSettings),
+        // so a persisted-but-now-infeasible budget can never brick startup.
+        if (patch.contextBudgetTokens !== undefined) {
+            const preview = this.previewAgentRuntimeSettings(agentName, patch);
+            if (preview.available && preview.effective) {
+                const e = preview.effective;
+                // Block only a LOWERING that doesn't fit. A no-op rewrite or an
+                // increase on an already-over-floor agent never makes things worse —
+                // refusing those would throw on exactly the wedged population the
+                // guard exists to protect (and block stepwise remediation).
+                const lowering = patch.contextBudgetTokens < preview.liveBudgetTokens;
+                if (preview.path === 'immediate' && !e.fits && lowering) {
+                    const msg = `[budget-preflight] contextBudgetTokens=${patch.contextBudgetTokens} would NOT fit ` +
+                        `${agentName}: the folded floor renders ${e.finalTokens} tokens against hard budget ` +
+                        `${e.budgetTokens} (head=${e.headTokens ?? '?'} tail=${e.tailTokens ?? '?'} ` +
+                        `middle=${e.middleTokens ?? '?'}, deepest L${e.deepestLevel ?? '?'}` +
+                        `${e.exhausted ? ', picker exhausted' : ''}). Every compile at this budget would ` +
+                        `OverBudget-wedge the agent. Lower the floor first (drain compression quarantine / ` +
+                        `advance the merge ladder), use a paced descent (no \`immediate\`), or pass allowInfeasible.`;
+                    if (!opts?.allowInfeasible)
+                        throw new BudgetPreflightError(msg, preview);
+                    console.warn(`${msg} — applying anyway (allowInfeasible).`);
+                }
+                else if (preview.path === 'immediate' && !e.fits) {
+                    console.warn(`[budget-preflight] ${agentName} remains over the folded floor at ` +
+                        `${patch.contextBudgetTokens} (floor renders ${e.finalTokens}); this patch does ` +
+                        `not lower the budget, so applying — drain quarantine / advance merges to clear it.`);
+                }
+                else if (preview.path === 'paced' && preview.advisory && !preview.advisory.fits) {
+                    console.warn(`[budget-preflight] paced descent for ${agentName} targets ` +
+                        `${preview.advisory.targetTokens} tokens, below the current folded floor — the ` +
+                        `transition will converge only as far as the floor allows (drain quarantine / ` +
+                        `advance merges to go lower). Applying; the live compile budget is unchanged.`);
+                }
+            }
+            else if (preview.reason) {
+                console.warn(`[budget-preflight] preview unavailable for ${agentName} (${preview.reason}); ` +
+                    `applying without preflight`);
+            }
+        }
         const result = agent.updateRuntimeSettings(patch);
         if (opts?.persist !== false) {
             this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
         }
+        this.recordOperatorAction({
+            kind: 'settings-update',
+            agent: agentName,
+            ...(opts?.requester ? { requester: opts.requester } : {}),
+            ...(opts?.note ? { note: opts.note } : {}),
+            params: { patch: { ...patch }, persist: opts?.persist !== false },
+        });
         return result;
     }
     resetAgentRuntimeSettings(agentName, keys, opts) {
@@ -1780,16 +2121,616 @@ export class AgentFramework {
         if (opts?.persist !== false) {
             this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
         }
+        this.recordOperatorAction({
+            kind: 'settings-reset',
+            agent: agentName,
+            ...(opts?.requester ? { requester: opts.requester } : {}),
+            ...(opts?.note ? { note: opts.note } : {}),
+            params: { keys: keys ?? 'all', persist: opts?.persist !== false },
+        });
         return result;
     }
-    cancelAgentRuntimeSettingsTransition(agentName) {
+    cancelAgentRuntimeSettingsTransition(agentName, opts) {
         const agent = this.agents.get(agentName);
         if (!agent)
             throw new Error(`Unknown agent: ${agentName}`);
         const result = agent.cancelRuntimeSettingsTransition();
         this.persistAgentRuntimeSettings(agentName, agent.getRuntimeSettingsOverrides());
+        this.recordOperatorAction({
+            kind: 'settings-cancel-transition',
+            agent: agentName,
+            ...(opts?.requester ? { requester: opts.requester } : {}),
+        });
         return result;
     }
+    // -------------------------------------------------------------------------
+    // Host quiesce / maintenance mode (issue #122)
+    //
+    // Pause the inference thread and MCPL data planes while keeping the
+    // framework + context managers + membrane loaded and hot, so maintenance
+    // (compression ticks, refold, quarantine drains, budget descents) runs
+    // through the exact machinery the agent uses live — with live config, live
+    // tool definitions, and full llm-calls logging — instead of offline rigs
+    // that re-derive all of it and drift.
+    //
+    // While quiesced: runLoop, store sync, the maintenance timer, and the
+    // liveness watchdog all keep running. Wakes park in pendingRequests
+    // (coalesced per reason) and fire at resume; MCPL events buffer on the
+    // paused data planes; gate debounces buffer in the gate. Background
+    // code-execution scripts are NOT stopped (they hold no turn token) — they
+    // are reported in the status so the operator sees what still acts.
+    //
+    // NOTE: do not call quiesce() from inside a queue event handler — the drain
+    // wait depends on the event loop continuing to run.
+    // -------------------------------------------------------------------------
+    /**
+     * Wakes that passed the scheduler and now own provider admission while
+     * waiting for an in-flight auxiliary call to settle — no turn token yet,
+     * so `activeTurnTokens` alone would call the host drained while a turn is
+     * one promise-resolution away from starting. The admission continuation
+     * rechecks quiesce and requeues, but until it runs the wake is live.
+     */
+    parkedAdmissionCount() {
+        let n = 0;
+        for (const [agentName, gate] of this.providerGates) {
+            if (gate.primaryDepth > 0 && !this.activeTurnTokens.has(agentName))
+                n++;
+        }
+        return n;
+    }
+    getHostModeStatus() {
+        const parkedAdmissions = this.parkedAdmissionCount();
+        return {
+            quiesced: this.quiesced,
+            ...(this.quiesceReason ? { reason: this.quiesceReason } : {}),
+            ...(this.quiescedAt !== undefined ? { since: this.quiescedAt } : {}),
+            drained: this.activeTurnTokens.size === 0 && parkedAdmissions === 0,
+            activeTurns: this.activeTurnTokens.size,
+            parkedAdmissions,
+            gatedRequests: this.pendingRequests.filter((r) => !isTurnContinuation(r.reason)).length,
+            backgroundScripts: [...this.backgroundScripts.values()]
+                .filter((record) => record.status === 'running').length,
+            deferredWrites: this.deferredMessages.length,
+            ...(this.lastUnabandonable.length > 0 ? { unabandonable: [...this.lastUnabandonable] } : {}),
+        };
+    }
+    /** Drain window bounds shared by every ingress (framework API, WS, HTTP,
+     *  host/command). Below the floor a drain is meaningless; above the ceiling
+     *  an awaited call would poll for days. */
+    static QUIESCE_TIMEOUT_MIN_MS = 1_000;
+    static QUIESCE_TIMEOUT_MAX_MS = 600_000;
+    static QUIESCE_TIMEOUT_DEFAULT_MS = 120_000;
+    /**
+     * 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.
+     *
+     * On drain timeout the host STAYS quiesced (`drained: false` in the
+     * result); with `abandon: true` the undrained streams are cancelled via a
+     * dedicated cancel kind that settles the turn without feeding the
+     * inference-failure accounting.
+     */
+    async quiesce(opts) {
+        if (this.quiesced) {
+            // Idempotent — EXCEPT abandon escalation: a first quiesce that timed
+            // out undrained must be escalatable with a second quiesce({abandon})
+            // without resume()+re-quiesce (which would reopen data planes and
+            // release parked wakes mid-surgery).
+            if (opts?.abandon && this.activeTurnTokens.size > 0) {
+                const unabandonable = await this.abandonActiveTurns();
+                this.emitTrace({
+                    type: 'host:quiesce',
+                    ...(this.quiesceReason ? { reason: this.quiesceReason } : {}),
+                    drained: this.activeTurnTokens.size === 0,
+                    activeTurns: this.activeTurnTokens.size,
+                    abandoned: true,
+                    ...(unabandonable.length > 0 ? { unabandonable } : {}),
+                });
+            }
+            return this.getHostModeStatus();
+        }
+        this.quiesced = true;
+        this.quiesceReason = opts?.reason;
+        this.quiescedAt = Date.now();
+        this.lastUnabandonable = [];
+        this.persistHostMode({
+            quiesced: true,
+            ...(opts?.reason ? { reason: opts.reason } : {}),
+            since: this.quiescedAt,
+        });
+        console.error(`[host-mode] quiescing${opts?.reason ? ` (${opts.reason})` : ''}: parking wakes, ` +
+            `pausing MCPL data planes, draining ${this.activeTurnTokens.size} in-flight turn(s)`);
+        this.eventGate?.setQuiesced(true);
+        for (const connection of this.mcplServerRegistry?.getAllServers() ?? []) {
+            connection.pauseDataPlane();
+        }
+        // Clamp HERE, for every ingress. NaN-proof too: timeoutMs arrives via
+        // Number()/blind casts, and Math.max(1_000, NaN) is NaN — which would
+        // silently collapse the drain window to zero (`Date.now() < NaN` is
+        // false). The ceiling matters because this call is awaited: an
+        // unbounded value polls the event loop for as long as it says.
+        const rawTimeout = opts?.timeoutMs;
+        const timeoutMs = typeof rawTimeout === 'number' && Number.isFinite(rawTimeout)
+            ? Math.max(AgentFramework.QUIESCE_TIMEOUT_MIN_MS, Math.min(AgentFramework.QUIESCE_TIMEOUT_MAX_MS, Math.floor(rawTimeout)))
+            : AgentFramework.QUIESCE_TIMEOUT_DEFAULT_MS;
+        const deadline = Date.now() + timeoutMs;
+        // Drain = no turn token AND no wake parked on provider admission (the
+        // latter becomes a turn the moment its auxiliary settles unless the
+        // continuation's quiesce recheck requeues it — wait for that to happen).
+        while (this.quiesced &&
+            (this.activeTurnTokens.size > 0 || this.parkedAdmissionCount() > 0) &&
+            Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+        // A concurrent resume() ended this window while we waited. Nothing here
+        // may act any more — an abandon now would cancel a turn that started
+        // legitimately AFTER the resume, and the trace/log would describe a mode
+        // the host is no longer in.
+        if (!this.quiesced) {
+            console.error('[host-mode] quiesce superseded by a concurrent resume during drain');
+            return this.getHostModeStatus();
+        }
+        let abandoned = false;
+        let unabandonable = [];
+        if (this.activeTurnTokens.size > 0 && opts?.abandon) {
+            abandoned = true;
+            unabandonable = await this.abandonActiveTurns();
+            if (!this.quiesced)
+                return this.getHostModeStatus();
+        }
+        const status = this.getHostModeStatus();
+        this.emitTrace({
+            type: 'host:quiesce',
+            ...(this.quiesceReason ? { reason: this.quiesceReason } : {}),
+            drained: status.drained,
+            activeTurns: status.activeTurns,
+            ...(status.parkedAdmissions > 0 ? { parkedAdmissions: status.parkedAdmissions } : {}),
+            ...(abandoned ? { abandoned: true } : {}),
+            ...(unabandonable.length > 0 ? { unabandonable } : {}),
+        });
+        console.error(status.drained
+            ? `[host-mode] quiesced — drained, ${status.gatedRequests} wake(s) parked`
+            : `[host-mode] quiesced but drain ${abandoned ? 'needed abandon and' : 'timed out —'} ` +
+                `${status.activeTurns} turn(s) still alive` +
+                (status.parkedAdmissions > 0
+                    ? `, ${status.parkedAdmissions} wake(s) parked on provider admission`
+                    : ''));
+        return status;
+    }
+    /** 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. */
+    async abandonActiveTurns() {
+        const unabandonable = [];
+        for (const agentName of [...this.activeTurnTokens.keys()]) {
+            const agent = this.agents.get(agentName);
+            const state = agent?.state;
+            const stream = state && 'stream' in state ? state.stream : undefined;
+            if (agent && stream) {
+                console.error(`[host-mode] abandoning in-flight turn for ${agentName}`);
+                this.frameworkCancelledStreams.set(`${agent.name}:${agent.streamId}`, 'quiesce_abandoned');
+                stream.cancel();
+            }
+            else {
+                // Token held, no stream to cancel: the turn is between dequeue and
+                // stream registration (hooks/compile), or it is a puppet tool turn,
+                // which never has one. Say so — silence here reads as "abandon acted
+                // and teardown is slow", which is a different operator decision.
+                unabandonable.push(agentName);
+                console.error(`[host-mode] cannot abandon turn for ${agentName}: turn token held with no stream ` +
+                    `(status=${state?.status ?? 'unknown'}) — it must settle on its own`);
+            }
+        }
+        // Bounded grace for the cancelled streams' teardown to settle.
+        const grace = Date.now() + 10_000;
+        while (this.quiesced && this.activeTurnTokens.size > 0 && Date.now() < grace) {
+            await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+        // Only turns still alive after the grace are worth reporting.
+        this.lastUnabandonable = unabandonable.filter((name) => this.activeTurnTokens.has(name));
+        return this.lastUnabandonable;
+    }
+    /**
+     * Leave quiesce mode. Gates on a FRESH feasibility preview of every agent's
+     * CURRENT settings — maintenance may have moved the folded floor and the
+     * branch generation, so verdicts are computed at resume time, never reused.
+     * Throws ResumeBlockedError (with all failing verdicts) unless `force`.
+     * Unavailable previews warn and pass — refusing to resume because the
+     * strategy cannot preview would hold hosts hostage to a diagnostic.
+     */
+    async resume(opts) {
+        if (!this.quiesced)
+            return this.getHostModeStatus();
+        // The canonical operator flow is `maintain; resume`, and a timer-driven
+        // pass may still be mid-flight: previewContext refuses to overlap one
+        // ("already running"), which used to degrade the gate to "no opinion".
+        // Wait for the pass first, then retry a few times for the case where a
+        // fresh pass started in between.
+        if (this.maintenancePass) {
+            await this.maintenancePass.catch(() => { });
+        }
+        const failing = [];
+        for (const agentName of this.agents.keys()) {
+            let preview = this.previewAgentRuntimeSettings(agentName);
+            for (let attempt = 0; attempt < 8 && !preview.available && preview.reason === 'preview_in_flight'; attempt++) {
+                await new Promise((resolve) => setTimeout(resolve, 250));
+                if (this.maintenancePass)
+                    await this.maintenancePass.catch(() => { });
+                preview = this.previewAgentRuntimeSettings(agentName);
+            }
+            if (preview.available && preview.effective && !preview.effective.fits) {
+                failing.push({ agentName, preview });
+            }
+            else if (!preview.available && preview.reason !== 'no_preview_support') {
+                console.warn(`[host-mode] resume: feasibility preview unavailable for ${agentName} ` +
+                    `(${preview.reason}) — proceeding without a verdict`);
+            }
+        }
+        if (failing.length > 0 && !opts?.force) {
+            const detail = failing.map(({ agentName, preview }) => `${agentName}: folded floor ${preview.effective.finalTokens} > hard budget ` +
+                `${preview.effective.budgetTokens}` +
+                (preview.transition === 'blocked'
+                    ? ` (transition blocked: ${preview.transitionReason ?? 'unknown'})`
+                    : '')).join('; ');
+            throw new ResumeBlockedError(`resume refused: returning to service would OverBudget-wedge — ${detail}. ` +
+                `Drain compression quarantine / advance the merge ladder to lower the floor ` +
+                `(maintenanceTick()), or resume({ force: true }).`, failing);
+        }
+        if (failing.length > 0) {
+            console.warn(`[host-mode] resume FORCED past ${failing.length} failing feasibility verdict(s)`);
+        }
+        const releasedRequests = this.pendingRequests.length;
+        // In-memory first: addMessage must stop deferring so the flush below can
+        // land. The DURABLE flag is cleared only after the flush completes — a
+        // crash in between then boots quiesced with the un-acked remainder
+        // restored (and a serving boot recovers any remainder anyway).
+        this.quiesced = false;
+        this.quiesceReason = undefined;
+        this.quiescedAt = undefined;
+        this.lastUnabandonable = [];
+        this.eventGate?.setQuiesced(false);
+        try {
+            // Flush context writes deferred by the quiesce window (module events,
+            // api message.send) — with no turn alive there is no other flush
+            // point. Per-message try/catch and per-message durable ack (see
+            // flushDeferredWrites); nothing here may reach the plane reopen below.
+            await this.flushDeferredWrites('resume');
+            this.persistHostMode(null);
+        }
+        finally {
+            // Reopen MCPL data planes through the existing barrier funnel — NOT a
+            // bespoke ready() loop. The funnel inherits completeMcplDataPlaneGate's
+            // nested-install guard (a flushed tools-list-changed can install a
+            // newer barrier mid-flush), drains any awareness work accumulated
+            // during the window before opening, and replaces a stale failed
+            // barrier by identity. In `finally` so that nothing above can leave
+            // the host un-quiesced with every data plane still paused.
+            if (this.mcplServerRegistry) {
+                const barrier = this.installMcplDataPlaneGate();
+                this.releaseMcplDataPlaneGate(barrier);
+                try {
+                    await barrier.promise;
+                    this.completeMcplDataPlaneGate(barrier);
+                }
+                catch (error) {
+                    // The host IS resumed — don't rethrow. failMcplDataPlaneGate
+                    // recycles the connections, and their reconnect flows re-run the
+                    // funnel with quiesced=false, self-healing the data planes.
+                    await this.failMcplDataPlaneGate(barrier, 'quiesce resume', error);
+                }
+            }
+            this.emitTrace({
+                type: 'host:resume',
+                ...(opts?.force && failing.length > 0 ? { forced: true } : {}),
+                releasedRequests,
+            });
+            // NOTE: parked wakes and gate buffers are in-memory only — a restart
+            // mid-quiesce boots quiesced but with these queues empty (sources like
+            // heartbeats re-deliver on their own cadence; one-shot wakes are lost).
+            // Deferred context WRITES are persisted while quiesced and survive.
+            console.error(`[host-mode] resumed — ${releasedRequests} parked wake(s) released`);
+        }
+        return this.getHostModeStatus();
+    }
+    /**
+     * 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.
+     *
+     * Per-target: an agent whose turn is still alive keeps ITS messages
+     * deferred for its own turn boundary; everyone else's flush now.
+     */
+    async flushDeferredWrites(label) {
+        if (this.deferredMessages.length === 0) {
+            this.persistDeferredWrites();
+            return;
+        }
+        const keep = [];
+        const flush = [];
+        for (const msg of this.deferredMessages) {
+            const target = msg.forAgent ?? this.primaryAgentName;
+            (target && this.activeTurnTokens.has(target) ? keep : flush).push(msg);
+        }
+        // Hand-off: the batch leaves the pending queue and enters the un-acked
+        // set. The DURABLE queue (pending + un-acked) is unchanged by this, so a
+        // crash anywhere below replays the whole batch, and the deferredWriteId
+        // stamped on each stored message lets boot skip the ones that did land.
+        flush.sort(bySeq);
+        this.deferredMessages = keep;
+        this.handOffDeferredWrites(flush);
+        let stored = 0;
+        for (const msg of flush) {
+            try {
+                this.addMessage(msg.participant, msg.content, msg.metadata, {
+                    deferredWriteId: msg.id,
+                    ...(msg.forAgent ? { forAgent: msg.forAgent } : {}),
+                });
+                stored++;
+            }
+            catch (err) {
+                console.error(`[host-mode] ${label}: failed to store a deferred context write ` +
+                    `(participant=${msg.participant}, forAgent=${msg.forAgent ?? 'primary'}):`, err);
+            }
+        }
+        // Ack = sync the chronicle FIRST, then rewrite the durable queue without
+        // the batch. Never the other way round.
+        this.ackDeferredWrites();
+        console.error(`[host-mode] ${label}: flushed ${stored}/${flush.length} deferred context write(s)` +
+            (keep.length > 0 ? `, ${keep.length} kept for a still-alive turn` : ''));
+    }
+    /**
+     * Acknowledge every deferred write that has been handed to a context
+     * manager: sync the chronicle so the appended slots are durable, and only
+     * then drop them from the recovery queue. If the sync fails they stay in
+     * the durable queue (the next ack, or stop(), retries); a reboot in that
+     * state replays them, deduplicated by `deferredWriteId` for any that did
+     * reach disk. Idempotent and cheap when nothing is un-acked.
+     */
+    ackDeferredWrites() {
+        if (this.unackedDeferredWrites.length === 0)
+            return;
+        // Nothing durable to reconcile against unless the queue was persisted.
+        if (!this.deferredWritesPersisted && !this.quiesced) {
+            this.unackedDeferredWrites = [];
+            return;
+        }
+        try {
+            this.store.sync();
+        }
+        catch (err) {
+            console.error(`[host-mode] chronicle sync failed — ${this.unackedDeferredWrites.length} flushed deferred ` +
+                `write(s) stay in the recovery queue until a sync succeeds:`, err);
+            return;
+        }
+        this.unackedDeferredWrites = [];
+        this.deferredScanFrom.clear();
+        this.persistDeferredWrites();
+    }
+    /**
+     * Move drained entries into the un-acked set and record, per target
+     * agent, the store position they will be appended after — then persist
+     * that receipt BEFORE any of them is written. Boot recovery scans from the
+     * recorded position to the tail, so every member of an interrupted batch
+     * is visible to the dedup, however large the batch.
+     */
+    handOffDeferredWrites(entries) {
+        if (entries.length === 0)
+            return;
+        const durable = this.deferredWritesPersisted || this.quiesced;
+        if (!durable)
+            return; // memory-only deferrals: nothing to reconcile at boot
+        for (const entry of entries) {
+            const target = entry.forAgent ?? this.primaryAgentName;
+            const agent = target ? this.agents.get(target) : undefined;
+            if (!agent)
+                continue;
+            let count = 0;
+            try {
+                const cm = agent.getContextManager();
+                count = typeof cm.getMessageCount === 'function' ? cm.getMessageCount() : cm.getAllMessages().length;
+            }
+            catch {
+                count = 0;
+            }
+            const prev = this.deferredScanFrom.get(target);
+            this.deferredScanFrom.set(target, prev === undefined ? count : Math.min(prev, count));
+        }
+        this.unackedDeferredWrites.push(...entries);
+        this.persistDeferredWrites();
+    }
+    /**
+     * 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.
+     */
+    landedDeferredWriteIds(ids, scanFrom) {
+        const landed = new Set();
+        if (ids.size === 0)
+            return landed;
+        const WINDOW = 500;
+        for (const agent of this.agents.values()) {
+            try {
+                const cm = agent.getContextManager();
+                const consider = (m) => {
+                    const id = m.metadata?.deferredWriteId;
+                    if (typeof id === 'string' && ids.has(id))
+                        landed.add(id);
+                };
+                if (typeof cm.getMessageCount === 'function' && typeof cm.getMessageWindow === 'function') {
+                    const total = cm.getMessageCount();
+                    // From the receipt position (0 = whole store when unknown) to the
+                    // tail, in blob-free windows — the batch can only be after it.
+                    const from = Math.min(scanFrom.get(agent.name) ?? 0, total);
+                    for (let start = from; start < total; start += WINDOW) {
+                        const win = cm.getMessageWindow(start, Math.min(WINDOW, total - start), { resolveBlobs: false });
+                        for (const m of win.messages)
+                            consider(m);
+                    }
+                }
+                else {
+                    for (const m of cm.getAllMessages())
+                        consider(m);
+                }
+            }
+            catch (err) {
+                console.error(`[host-mode] could not scan ${agent.name} for landed deferred writes:`, err);
+            }
+        }
+        return landed;
+    }
+    /** Atomic JSON write for the recovery files (tmp + rename, 0600) — the
+     *  same idiom as the Discord awareness outbox. */
+    writeRecoveryFile(path, document) {
+        mkdirSync(dirname(path), { recursive: true });
+        const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    readRecoveryFile(path) {
+        if (!existsSync(path))
+            return undefined;
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    warnRecoveryFallbackOnce() {
+        if (this.recoveryFallbackWarned)
+            return;
+        this.recoveryFallbackWarned = true;
+        console.error('[host-mode] no storePath / hostModePath / deferredWritesPath: quiesce state and deferred ' +
+            'writes persist in the branch-local framework/state slot — a historical rollback while ' +
+            'quiesced can erase them; configure the recovery paths');
+    }
+    /**
+     * Mirror the deferred-write queue durably while quiesced (and until an
+     * already-persisted queue drains). The quiesce flag itself is persisted
+     * because a crash mid-surgery is an expected event; the messages withheld
+     * BECAUSE of that surgery would otherwise die with the process — and the
+     * 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.
+     */
+    persistDeferredWrites() {
+        try {
+            // The durable queue is everything not yet acked: writes still pending
+            // AND writes handed to a context manager whose sync has not happened.
+            // Always in original deferral order, whatever the pending/un-acked
+            // split: a re-deferred entry must not jump the queue.
+            const durable = [...this.unackedDeferredWrites, ...this.deferredMessages].sort(bySeq);
+            const scanFrom = Object.fromEntries(this.deferredScanFrom);
+            if ((this.quiesced || this.deferredWritesPersisted) && durable.length > 0) {
+                const payload = JSON.stringify(durable);
+                if (payload.length > DEFERRED_WRITES_PERSIST_CAP_BYTES) {
+                    if (!this.deferredWritesCapWarned) {
+                        this.deferredWritesCapWarned = true;
+                        console.error(`[host-mode] deferred context writes exceed ${DEFERRED_WRITES_PERSIST_CAP_BYTES} bytes ` +
+                            `serialized (${durable.length} message(s)) — kept in memory only; ` +
+                            `a crash before resume loses them`);
+                    }
+                    return;
+                }
+                if (this.deferredWritesPath) {
+                    this.writeRecoveryFile(this.deferredWritesPath, { version: 2, pending: durable, scanFrom });
+                }
+                else {
+                    this.warnRecoveryFallbackOnce();
+                    this.store.setStateJson(DEFERRED_WRITES_ID, { version: 2, pending: durable, scanFrom });
+                }
+                this.deferredWritesPersisted = true;
+            }
+            else if (this.deferredWritesPersisted) {
+                if (this.deferredWritesPath) {
+                    this.writeRecoveryFile(this.deferredWritesPath, { version: 1, pending: [] });
+                }
+                else {
+                    this.store.setStateJson(DEFERRED_WRITES_ID, []);
+                }
+                this.deferredWritesPersisted = false;
+            }
+        }
+        catch (err) {
+            console.error('[host-mode] failed to persist deferred context writes:', err);
+        }
+    }
+    restorePersistedDeferredWrites() {
+        try {
+            let raw;
+            if (this.deferredWritesPath && existsSync(this.deferredWritesPath)) {
+                raw = this.readRecoveryFile(this.deferredWritesPath);
+            }
+            else {
+                // Stores that predate the recovery file (or store-only configs).
+                raw = this.store.getStateJson(DEFERRED_WRITES_ID);
+            }
+            // v1 slot payloads were a bare array; v1/v2 files and v2 slots are
+            // `{ pending, scanFrom? }`.
+            const doc = Array.isArray(raw) ? { pending: raw } : raw;
+            const data = doc?.pending;
+            if (!Array.isArray(data) || data.length === 0)
+                return 0;
+            const scanFrom = new Map();
+            if (doc?.scanFrom && typeof doc.scanFrom === 'object') {
+                for (const [k, v] of Object.entries(doc.scanFrom)) {
+                    if (typeof v === 'number' && Number.isFinite(v))
+                        scanFrom.set(k, Math.max(0, Math.floor(v)));
+                }
+            }
+            const candidates = data
+                .filter((m) => !!m && typeof m === 'object' && typeof m.participant === 'string'
+                && Array.isArray(m.content))
+                .map((m, i) => ({
+                ...m,
+                id: typeof m.id === 'string' ? m.id : randomUUID(),
+                // Files that predate `seq` are in write order already.
+                seq: typeof m.seq === 'number' ? m.seq : i + 1,
+            }))
+                .sort(bySeq);
+            this.deferredSeq = Math.max(this.deferredSeq, ...candidates.map((m) => m.seq));
+            // Exactly-once: a message that landed before its ack was written is
+            // already in the store under its deferredWriteId — do not replay it.
+            // The scan covers every slot the interrupted batch could occupy (from
+            // the receipt's per-agent position), or the whole store when the
+            // receipt predates the position field.
+            const landed = this.landedDeferredWriteIds(new Set(candidates.map((m) => m.id)), scanFrom);
+            const restored = candidates.filter((m) => !landed.has(m.id));
+            if (landed.size > 0) {
+                console.error(`[host-mode] ${landed.size} deferred context write(s) had already landed before their ack ` +
+                    `(interrupted flush) — skipped, not replayed`);
+            }
+            this.deferredMessages.push(...restored);
+            this.deferredWritesPersisted = true;
+            // Rewrite the durable queue without the already-landed entries so a
+            // second interrupted boot does not re-scan them.
+            if (landed.size > 0)
+                this.persistDeferredWrites();
+            return restored.length;
+        }
+        catch (err) {
+            console.error('[host-mode] failed to restore persisted deferred context writes:', err);
+            return 0;
+        }
+    }
+    /**
+     * Operator-driven maintenance: run (or join) one bounded compression pass —
+     * the same runQueuedMaintenance the timer drives, so tool definitions are
+     * refreshed and ticks are bounded/serialized identically — and return the
+     * maintenance snapshot. Works while quiesced by design: `running` stays
+     * true in quiesce mode precisely so this machinery stays hot.
+     */
+    async maintenanceTick() {
+        if (!this.running) {
+            // startQueuedMaintenance no-ops on a stopped/never-started framework —
+            // a bare snapshot would masquerade as a completed pass, so say so.
+            console.warn('[host-mode] maintenanceTick: framework is not running — no pass executed');
+            return { ...this.getContextMaintenanceSnapshot(), ran: false };
+        }
+        this.startQueuedMaintenance();
+        await this.maintenancePass;
+        return { ...this.getContextMaintenanceSnapshot(), ran: true };
+    }
     /** Counts-only context-maintenance diagnostics for authenticated debug UIs. */
     getContextMaintenanceSnapshot() {
         const agents = [...this.agents.values()].map((agent) => {
@@ -1907,6 +2848,90 @@ export class AgentFramework {
         // large store, and older context-manager builds ignore the argument.
         return cm.previewContext({ maxTokens: budgetTokens, reserveForResponse: agent.maxTokens }, overrides, opts);
     }
+    /**
+     * Feasibility preview for a runtime-settings patch — or, with no patch, for
+     * the agent's CURRENT settings (the resume-gate case: quiesce maintenance
+     * may have moved the folded floor and the branch generation, so the verdict
+     * must be computed fresh at resume time).
+     *
+     * Models the patch through the same immediate-vs-paced semantics as the
+     * apply path (`Agent.planRuntimeSettings`): a non-immediate budget decrease
+     * is previewed at the UNCHANGED live compile budget, with a best-effort
+     * advisory verdict at the descent target. This is what the superseded
+     * `feat/budget-preflight-guard` got wrong — it previewed the patch value as
+     * 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.
+     */
+    previewAgentRuntimeSettings(agentName, patch) {
+        const agent = this.agents.get(agentName);
+        if (!agent)
+            throw new Error(`Unknown agent: ${agentName}`);
+        const plan = agent.planRuntimeSettings(patch);
+        const settings = agent.getRuntimeSettings();
+        const base = {
+            available: false,
+            path: plan.path,
+            liveBudgetTokens: plan.liveBudgetTokens,
+            transition: settings.transition,
+            ...(settings.transitionReason ? { transitionReason: settings.transitionReason } : {}),
+        };
+        const runPreview = (budgetTokens) => {
+            try {
+                const result = this.previewContextSettings(agentName, budgetTokens, Object.keys(plan.overrides).length > 0 ? plan.overrides : undefined);
+                if (result === null || typeof result !== 'object') {
+                    return { reason: 'no_preview_support' };
+                }
+                return { result: result };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                // Structured mapping of the strategy's known throw paths. Message
+                // matching is fragile by nature, so unknown messages surface verbatim
+                // as the reason rather than being swallowed or rethrown.
+                if (message.includes('requires reinitialization for the current branch generation')) {
+                    return { reason: 'branch_generation_changed' };
+                }
+                if (message.includes('already running; previews must not overlap')) {
+                    return { reason: 'preview_in_flight' };
+                }
+                if (message.includes('requires adaptiveResolution')) {
+                    return { reason: 'no_adaptive_resolution' };
+                }
+                return { reason: message };
+            }
+        };
+        const effective = runPreview(plan.effectiveBudgetTokens);
+        if (!effective.result) {
+            return { ...base, reason: effective.reason };
+        }
+        const preview = {
+            ...base,
+            available: true,
+            effective: {
+                ...effective.result,
+                budgetTokens: plan.effectiveBudgetTokens,
+                fits: effective.result.fits === true,
+                finalTokens: Number(effective.result.finalTokens ?? 0),
+            },
+        };
+        if (plan.advisoryTargetTokens !== undefined) {
+            // Best-effort: an advisory failure never flips `available` — the
+            // effective verdict above is the one that gates anything.
+            const advisory = runPreview(plan.advisoryTargetTokens);
+            if (advisory.result) {
+                preview.advisory = {
+                    ...advisory.result,
+                    targetTokens: plan.advisoryTargetTokens,
+                    fits: advisory.result.fits === true,
+                };
+            }
+        }
+        return preview;
+    }
     /**
      * Check if process logging is enabled.
      */
@@ -2066,6 +3091,81 @@ export class AgentFramework {
         state.agentRuntimeSettings = all;
         this.store.setStateJson(FRAMEWORK_STATE_ID, state);
     }
+    /** 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. */
+    persistHostMode(mode) {
+        if (this.hostModePath) {
+            // Branch-independent: the recovery file is the record. (`quiesced:
+            // false` is written explicitly rather than deleting the file so that
+            // its presence, not its content, decides precedence over the legacy
+            // branch-local slot below.)
+            this.writeRecoveryFile(this.hostModePath, mode === null ? { version: 1, quiesced: false, clearedAt: Date.now() } : { version: 1, ...mode });
+            if (mode === null) {
+                // Also drop any legacy slot marker so a downgrade cannot resurrect it.
+                try {
+                    const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+                    if (data && typeof data === 'object' && 'hostMode' in data) {
+                        const state = { ...data };
+                        delete state.hostMode;
+                        this.store.setStateJson(FRAMEWORK_STATE_ID, state);
+                    }
+                }
+                catch { /* best effort */ }
+            }
+        }
+        else {
+            this.warnRecoveryFallbackOnce();
+            const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+            const state = (data && typeof data === 'object' ? data : {});
+            if (mode === null)
+                delete state.hostMode;
+            else
+                state.hostMode = { ...mode };
+            this.store.setStateJson(FRAMEWORK_STATE_ID, state);
+        }
+        // The whole feature rests on the flag surviving a crash — close the
+        // window between the write and the next periodic sync.
+        try {
+            this.store.sync();
+        }
+        catch (err) {
+            console.error('[host-mode] store sync after host-mode change failed:', err);
+        }
+    }
+    /** The recovery file wins whenever it exists; the branch-local slot is
+     *  read only for stores that predate it (or store-only configs). */
+    readHostMode() {
+        try {
+            let record = null;
+            if (this.hostModePath && existsSync(this.hostModePath)) {
+                const doc = this.readRecoveryFile(this.hostModePath);
+                if (doc && typeof doc === 'object')
+                    record = doc;
+            }
+            else {
+                const data = this.store.getStateJson(FRAMEWORK_STATE_ID);
+                if (!data || typeof data !== 'object')
+                    return null;
+                const mode = data.hostMode;
+                if (!mode || typeof mode !== 'object')
+                    return null;
+                record = mode;
+            }
+            if (!record)
+                return null;
+            return {
+                quiesced: record.quiesced === true,
+                ...(typeof record.reason === 'string' ? { reason: record.reason } : {}),
+                ...(typeof record.since === 'number' ? { since: record.since } : {}),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Create an ephemeral agent that is NOT registered in the main event loop.
      *
@@ -2176,18 +3276,36 @@ export class AgentFramework {
      * The task message should already be in the context manager.
      */
     async runEphemeralToCompletion(agent, contextManager, watchdogs) {
+        // Refused at admission while quiesced rather than requeued: the caller
+        // awaits the settle promise under an idle-stall watchdog, so a gate-parked
+        // ephemeral would ride out its timeout and reject with a misleading
+        // "stalled" error hours later. A clear refusal now beats that. Checked
+        // before the generation ticket is consumed so the same (agent, cm) pair
+        // can be retried after resume().
+        if (this.quiesced) {
+            throw new Error(`framework is quiesced${this.quiesceReason ? ` (${this.quiesceReason})` : ''}: ` +
+                `refusing new ephemeral run for ${agent.name} — resume() first`);
+        }
         // Only a fresh object returned by createEphemeralAgent may enter this path.
         // Never overwrite a resident/conversation owner or a concurrent run: their
         // cleanup is name-keyed and could cancel/deregister the legitimate owner.
         if (this.ephemeralCandidates.get(agent) !== contextManager) {
             throw new Error(`Ephemeral agent "${agent.name}" has no fresh generation ticket from this framework`);
         }
+        // A live surgery holds the whole store: an agent admitted now would
+        // compile against a history that is being replaced under it. Refuse
+        // BEFORE consuming the ticket so the caller can retry once it completes.
+        if (this.surgeryHold) {
+            throw new Error(`Ephemeral agent "${agent.name}" refused: the store is under live ${this.surgeryHold.verb} ` +
+                `for ${this.surgeryHold.agentName} — retry when it completes`);
+        }
         // Consume before any await/registration: the exact (Agent, ContextManager)
         // generation is one-shot even if startup later fails.
         this.ephemeralCandidates.delete(agent);
         if (this.agents.has(agent.name) || this.ephemeralRuns.has(agent.name)) {
             throw new Error(`Ephemeral agent "${agent.name}" is already registered or running`);
         }
+        // Register temporarily so the event loop can drive it
         this.agents.set(agent.name, agent);
         const run = {
             settle: this.createDeferred(),
@@ -2890,8 +4008,15 @@ export class AgentFramework {
             source: 'admin',
             timestamp: Date.now(),
         });
-        console.error(`[nudge] agent=${name} queued by=${requestedBy ?? 'unknown'} status=${agentStatus}`);
-        return { ok: true, agentName: name, agentStatus };
+        console.error(`[nudge] agent=${name} queued by=${requestedBy ?? 'unknown'} status=${agentStatus}` +
+            (this.quiesced ? ' (host quiesced — parked until resume)' : ''));
+        this.recordOperatorAction({
+            kind: 'nudge',
+            agent: name,
+            requester: { via: 'nudge', ...(requestedBy ? { name: requestedBy } : {}) },
+            result: { agentStatus, ...(this.quiesced ? { quiesced: true } : {}) },
+        });
+        return { ok: true, agentName: name, agentStatus, ...(this.quiesced ? { quiesced: true } : {}) };
     }
     /**
      * Handle a `host/command` request from an MCPL surface server (e.g. a
@@ -2904,14 +4029,65 @@ export class AgentFramework {
      *
      *   nudge — run inference on the current context with NO new events
      *   (see `nudgeAgent`).
+     *
+     *   quiesce — enter host maintenance mode (issue #122): park wakes, pause
+     *   MCPL data planes, drain in-flight turns (optionally `abandon` on
+     *   timeout). Host-scoped, no agentName.
+     *
+     *   resume — leave maintenance mode behind a fresh feasibility preview of
+     *   every agent's current settings (`force` overrides a failing verdict).
+     *
+     *   maintain — run (or join) one bounded compression/maintenance pass and
+     *   return the snapshot; the operator lever for draining quarantine or
+     *   advancing merges during a quiesce window.
+     *
+     *   host-status — report the quiesce state (drained / parked wakes /
+     *   running background scripts).
      */
     async handleHostCommand(serverId, params) {
         if (params.command !== 'undo' &&
             params.command !== 'hide' &&
             params.command !== 'unstick' &&
-            params.command !== 'nudge') {
+            params.command !== 'nudge' &&
+            params.command !== 'quiesce' &&
+            params.command !== 'resume' &&
+            params.command !== 'maintain' &&
+            params.command !== 'host-status') {
             return { ok: false, error: `Unknown host command: ${String(params.command)}` };
         }
+        // Host-scoped verbs (issue #122) — no agent resolution.
+        const requester = params.requesterName ?? params.requesterId ?? `mcpl:${serverId}`;
+        if (params.command === 'quiesce') {
+            // quiesce() clamps timeoutMs to [1s, 10m] itself — one clamp for every ingress.
+            console.error(`[host-command] quiesce by=${requester} (server=${serverId})`);
+            const hostMode = await this.quiesce({
+                reason: params.reason ?? `host/command by ${requester}`,
+                ...(params.timeoutMs !== undefined ? { timeoutMs: params.timeoutMs } : {}),
+                ...(params.abandon ? { abandon: true } : {}),
+            });
+            return { ok: true, hostMode };
+        }
+        if (params.command === 'resume') {
+            console.error(`[host-command] resume by=${requester} (server=${serverId})`);
+            try {
+                const hostMode = await this.resume(params.force ? { force: true } : undefined);
+                return { ok: true, hostMode };
+            }
+            catch (error) {
+                if (error instanceof ResumeBlockedError) {
+                    return { ok: false, error: error.message, hostMode: this.getHostModeStatus() };
+                }
+                throw error;
+            }
+        }
+        if (params.command === 'maintain') {
+            console.error(`[host-command] maintain by=${requester} (server=${serverId})`);
+            const maintenance = await this.maintenanceTick();
+            return { ok: true, maintenance, hostMode: this.getHostModeStatus() };
+        }
+        if (params.command === 'host-status') {
+            return { ok: true, hostMode: this.getHostModeStatus() };
+        }
         const agentName = params.agentName ?? [...this.agents.keys()][0];
         if (!agentName || !this.agents.has(agentName)) {
             return { ok: false, error: `Unknown agent: ${String(agentName)}` };
@@ -2920,7 +4096,7 @@ export class AgentFramework {
         // event, no context mutation (see nudgeAgent).
         if (params.command === 'nudge') {
             const r = this.nudgeAgent(agentName, params.requesterName ?? params.requesterId ?? `mcpl:${serverId}`);
-            return { ok: r.ok, error: r.error, agentStatus: r.agentStatus };
+            return { ok: r.ok, error: r.error, agentStatus: r.agentStatus, ...(r.quiesced ? { quiesced: true } : {}) };
         }
         // unstick: force the refusal-rewind loop on demand (even if the agent's
         // autoRewind toggle is off). Redacts the turn that fed the refusal and
@@ -2948,7 +4124,14 @@ export class AgentFramework {
             });
             console.error(`[unstick] agent=${agentName} started cap=${cap} ` +
                 `by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`);
-            return { ok: true, started: true, cap };
+            this.recordOperatorAction({
+                kind: 'unstick',
+                agent: agentName,
+                requester: hostCommandRequester(serverId, params),
+                params: { cap },
+                result: { started: true, ...(this.quiesced ? { quiesced: true } : {}) },
+            });
+            return { ok: true, started: true, cap, ...(this.quiesced ? { quiesced: true } : {}) };
         }
         // hide: redact a single message (or an inclusive range) from the active
         // branch, addressed by Discord message id. Unlike undo this is a
@@ -2993,9 +4176,23 @@ export class AgentFramework {
                     }
                     const [lo, hi] = fromIdx <= toIdx ? [fromIdx, toIdx] : [toIdx, fromIdx];
                     const refs = refsIn(lo, hi);
+                    const rangeIds = all.slice(lo, hi + 1).map((m) => String(m.id));
                     cm.removeMessages(all[lo].id, all[hi].id);
                     console.error(`[host-command] hide agent=${agentName} range removed=${hi - lo + 1} ` +
                         `(${params.fromMessageId}..${params.toMessageId}) by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`);
+                    const loggedRange = capIds(rangeIds);
+                    this.recordOperatorAction({
+                        kind: 'hide',
+                        agent: agentName,
+                        requester: hostCommandRequester(serverId, params),
+                        params: { fromMessageId: params.fromMessageId, toMessageId: params.toMessageId },
+                        result: {
+                            branch: this.store.currentBranch().name,
+                            hidden: hi - lo + 1,
+                            removedIds: loggedRange.ids,
+                            ...(loggedRange.truncated ? { removedIdsTruncated: true } : {}),
+                        },
+                    });
                     return {
                         ok: true,
                         hidden: hi - lo + 1,
@@ -3004,9 +4201,17 @@ export class AgentFramework {
                     };
                 }
                 const refs = refsIn(fromIdx, fromIdx);
+                const hiddenId = String(all[fromIdx].id);
                 cm.removeMessage(all[fromIdx].id);
                 console.error(`[host-command] hide agent=${agentName} removed=1 (${params.fromMessageId}) ` +
                     `by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`);
+                this.recordOperatorAction({
+                    kind: 'hide',
+                    agent: agentName,
+                    requester: hostCommandRequester(serverId, params),
+                    params: { fromMessageId: params.fromMessageId },
+                    result: { branch: this.store.currentBranch().name, hidden: 1, removedIds: [hiddenId] },
+                });
                 return {
                     ok: true,
                     hidden: 1,
@@ -3029,55 +4234,40 @@ export class AgentFramework {
             }
             const n = Math.max(1, Math.min(50, Math.floor(params.messages)));
             const cm = agent.getContextManager();
-            const allMessages = cm.getAllMessages();
-            if (n >= allMessages.length) {
+            const total = cm.getMessageCount();
+            if (n >= total) {
                 return {
                     ok: false,
-                    error: `Cannot remove ${n} message(s) — history has ${allMessages.length}; at least one must remain.`,
+                    error: `Cannot remove ${n} message(s) — history has ${total}; at least one must remain.`,
+                };
+            }
+            const target = cm.getMessageWindow(total - 1 - n, 1, { resolveBlobs: false }).messages[0];
+            try {
+                const r = await this.rollbackToMessage(agentName, {
+                    messageId: String(target.id),
+                    branchName: `undo-msgs/${agentName}/${Date.now()}`,
+                    requester: hostCommandRequester(serverId, params),
+                });
+                return {
+                    ok: true,
+                    messagesRemoved: r.messagesRemoved,
+                    removedRefs: r.removedRefs,
+                    lastVisible: r.lastVisible,
+                };
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    ...(error instanceof OperatorActionError ? { code: error.code } : {}),
                 };
             }
-            const target = allMessages[allMessages.length - 1 - n];
-            const discarded = allMessages.slice(allMessages.length - n);
-            const removedRefs = extractDiscordAwarenessRefs(discarded);
-            const sourceBranch = this.store.currentBranch().name;
-            const targetBranch = `undo-msgs/${agentName}/${Date.now()}`;
-            // Prepare the external side effect before switching Chronicle. If the
-            // process dies after the switch but before activate(), startup promotes
-            // this batch by matching targetBranch to the active branch.
-            const markerBatch = this.discordAwarenessOutbox?.prepare({
-                agentName,
-                sourceBranch,
-                targetBranch,
-                refs: removedRefs,
-                emoji: this.discordAwarenessEmoji,
-            }) ?? null;
-            const branchName = cm.branchAt(target.id, targetBranch);
-            await cm.switchBranch(branchName);
-            if (markerBatch)
-                this.discordAwarenessOutbox.activate(markerBatch.id);
-            await this.syncDiscordAwarenessMarkers();
-            // Materialize config files from the new branch (fire-and-forget; gate
-            // picks up via mtime) — mirrors undoLastTurn.
-            const wsUndo = this.moduleRegistry.getModule('workspace');
-            if (wsUndo && 'materializeMount' in wsUndo) {
-                wsUndo
-                    .materializeMount('_config')
-                    .catch(() => { });
-            }
-            console.error(`[host-command] undo-messages agent=${agentName} removed=${n} branch=${branchName}` +
-                ` by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`);
-            return {
-                ok: true,
-                messagesRemoved: n,
-                removedRefs,
-                lastVisible: await this.lastVisiblePreview(agentName),
-            };
         }
         const requested = Math.max(1, Math.min(20, Math.floor(params.turns ?? 1)));
         let undone = 0;
         try {
             for (let i = 0; i < requested; i++) {
-                const r = this.undoLastTurn(agentName);
+                const r = this.undoLastTurn(agentName, hostCommandRequester(serverId, params));
                 if (!r.undone)
                     break;
                 undone++;
@@ -3367,7 +4557,7 @@ export class AgentFramework {
      * The undone branch is saved so `redo()` can restore it.
      * Returns the checkpoint that was undone, or null if nothing to undo.
      */
-    undoLastTurn(agentName) {
+    undoLastTurn(agentName, requester) {
         const agent = this.agents.get(agentName);
         if (!agent) {
             throw new Error(`Unknown agent: ${agentName}`);
@@ -3404,6 +4594,13 @@ export class AgentFramework {
             fromBranch: currentBranch.name,
             toBranch: undoBranchName,
         });
+        this.recordOperatorAction({
+            kind: 'undo-turn',
+            agent: agentName,
+            ...(requester ? { requester } : {}),
+            params: { turnIndex: checkpoint.turnIndex },
+            result: { sourceBranch: currentBranch.name, targetBranch: undoBranchName },
+        });
         return {
             undone: true,
             turnIndex: checkpoint.turnIndex,
@@ -3417,7 +4614,7 @@ export class AgentFramework {
      * Switches back to the branch that was active before the last undo.
      * Returns false if there's nothing to redo.
      */
-    redo(agentName) {
+    redo(agentName, requester) {
         const agent = this.agents.get(agentName);
         if (!agent) {
             throw new Error(`Unknown agent: ${agentName}`);
@@ -3447,12 +4644,424 @@ export class AgentFramework {
             fromBranch: currentBranch.name,
             toBranch: branchName,
         });
+        this.recordOperatorAction({
+            kind: 'redo-turn',
+            agent: agentName,
+            ...(requester ? { requester } : {}),
+            result: { sourceBranch: currentBranch.name, targetBranch: branchName },
+        });
         return {
             redone: true,
             fromBranch: currentBranch.name,
             toBranch: branchName,
         };
     }
+    // ---------------------------------------------------------------------------
+    // Live operator surgery — rollback / suppress on the OPEN store, without a
+    // restart — plus the durable action log every operator mutation writes to.
+    //
+    // Both follow the same idiom the offline surgeries use (recovery/
+    // offline-branch.ts): fork first, mutate the fork, and make the fork the
+    // active branch. The parent branch keeps everything, so restore is a
+    // checkout. Mutations are refused (never queued) while the agent is not
+    // idle — quiesce the host first if it is busy.
+    // ---------------------------------------------------------------------------
+    /**
+     * Append a record to the operator action log and broadcast it as an
+     * `operator:action` trace. Hosts use this directly for actions the
+     * framework does not own (e.g. a WebUI toggling quiesce). Never throws.
+     */
+    recordOperatorAction(input) {
+        // Observability never fails the action: OperatorLog.append never throws,
+        // and a misbehaving trace listener is contained here.
+        const entry = this.operatorLog.append(input);
+        try {
+            this.emitTrace({
+                type: 'operator:action',
+                kind: entry.kind,
+                ...(entry.agent !== undefined ? { agentName: entry.agent } : {}),
+                ...(entry.requester !== undefined ? { requester: entry.requester } : {}),
+                ...(entry.note !== undefined ? { note: entry.note } : {}),
+                ...(entry.params !== undefined ? { params: entry.params } : {}),
+                ...(entry.result !== undefined ? { result: entry.result } : {}),
+                ...(entry.error !== undefined ? { error: entry.error } : {}),
+            });
+        }
+        catch {
+            // swallowed by design
+        }
+        return entry;
+    }
+    /** Newest `limit` operator-log entries, oldest first. */
+    getOperatorLog(opts) {
+        return this.operatorLog.readTail(opts?.limit ?? 100);
+    }
+    /** Where the operator log is written, or undefined when disabled. */
+    getOperatorLogPath() {
+        return this.operatorLog.path;
+    }
+    /**
+     * The surgery gate — STORE-wide, not per agent. A branch switch moves the
+     * active chronicle branch for every context manager sharing this store,
+     * so an in-flight turn on *any* agent would have its next writes land on
+     * a history its request was never compiled against. Every agent must be
+     * idle with no turn alive (`state.status === 'idle'` alone is not enough:
+     * status reads idle from dequeue until the stream registers and again
+     * during teardown — the scheduler's own busy test is status + turn-alive,
+     * the predicate `puppetToolCall` uses).
+     *
+     * Passing the gate RESERVES the store for the caller: a turn token is
+     * held for every agent until the returned release runs, so no wake — via
+     * the scheduler or a parked provider admission, both of which re-test
+     * turn-alive — can start a turn while the switch is awaited. Release also
+     * flushes messages that deferred behind the reservation, as the puppet
+     * does. Always release in `finally`: a token nobody clears wedges the fleet.
+     */
+    reserveStoreForSurgery(verb, agentName) {
+        if (this.surgeryHold) {
+            throw new OperatorActionError('agent-busy', `Cannot ${verb}: a live ${this.surgeryHold.verb} for ${this.surgeryHold.agentName} is already in progress`);
+        }
+        const busy = [];
+        for (const [name, a] of this.agents) {
+            if (a.state.status !== 'idle')
+                busy.push(`${name} is ${a.state.status}`);
+            else if (this.activeTurnTokens.has(name))
+                busy.push(`${name} is idle+turn-alive`);
+        }
+        for (const name of this.activeTurnTokens.keys()) {
+            if (!this.agents.has(name))
+                busy.push(`${name} is turn-alive`);
+        }
+        if (busy.length > 0) {
+            throw new OperatorActionError('agent-busy', `Cannot ${verb} while ${busy.join(', ')} — every agent sharing the store must be idle (quiesce the host first)`);
+        }
+        const reserved = new Map();
+        for (const name of this.agents.keys()) {
+            const token = this.nextTurnToken++;
+            this.activeTurnTokens.set(name, token);
+            reserved.set(name, token);
+        }
+        // The token snapshot only covers agents that exist now; the hold covers
+        // arrivals during the awaited switch (see surgeryHold).
+        const hold = { verb, agentName, since: Date.now() };
+        this.surgeryHold = hold;
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            if (this.surgeryHold === hold)
+                this.surgeryHold = null;
+            for (const [name, token] of reserved) {
+                if (this.activeTurnTokens.get(name) === token)
+                    this.activeTurnTokens.delete(name);
+            }
+            // Writers that deferred behind the reservation land now, on the branch
+            // the operator chose (or the restored source) — the same end-of-turn
+            // flush driveStream/puppet perform, under the same guard.
+            if (this.deferredMessages.length > 0 && this.pendingAssistantBlocks.size === 0) {
+                for (const name of reserved.keys()) {
+                    if (this.activeTurnTokens.has(name))
+                        continue;
+                    for (const msg of this.drainDeferredFor(name)) {
+                        try {
+                            this.addMessage(msg.participant, msg.content, msg.metadata, msg.forAgent ? { forAgent: msg.forAgent } : undefined);
+                        }
+                        catch (error) {
+                            console.error(`[operator] post-surgery deferred flush failed for ${name}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
+            }
+        };
+    }
+    /**
+     * After a failed switch or redaction: put the store back on `sourceBranch`
+     * if it moved, and return a sentence saying what actually happened. Never
+     * throws — the caller reports the original failure with this appended.
+     */
+    async restoreSourceBranch(cm, sourceBranch, failedBranch, agentName) {
+        const current = this.store.currentBranch().name;
+        if (current !== failedBranch)
+            return `active branch is ${current}`;
+        try {
+            await cm.switchBranch(sourceBranch);
+            return `active branch restored to ${sourceBranch}`;
+        }
+        catch (restoreError) {
+            const detail = restoreError instanceof Error ? restoreError.message : String(restoreError);
+            const status = `RESTORE TO ${sourceBranch} ALSO FAILED (${detail}); agent is still on ${failedBranch}`;
+            console.error(`[operator] agent=${agentName} ${status}`);
+            return status;
+        }
+    }
+    /**
+     * Roll the active branch back so `messageId` becomes its tail: fork the
+     * chronicle at that message (origin-sequence time-travel branch) and switch
+     * to the fork. Everything after the message stays on the source branch.
+     * Discord messages that left the live context get awareness markers via the
+     * durable outbox, exactly as message-granular `undo` does.
+     *
+     * Throws `OperatorActionError` (`agent-busy`, `unknown-message`, …) — the
+     * agent must be idle; nothing is queued.
+     */
+    async rollbackToMessage(agentName, opts) {
+        const logBase = {
+            kind: 'rollback',
+            agent: agentName,
+            ...(opts.requester ? { requester: opts.requester } : {}),
+            ...(opts.note ? { note: opts.note } : {}),
+            params: { messageId: opts.messageId },
+        };
+        try {
+            const agent = this.agents.get(agentName);
+            if (!agent)
+                throw new OperatorActionError('unknown-agent', `Unknown agent: ${agentName}`);
+            const cm = agent.getContextManager();
+            const total = cm.getMessageCount();
+            const requestedIndex = locateMessageIndex(cm, opts.messageId);
+            if (requestedIndex < 0) {
+                throw new OperatorActionError('unknown-message', `Message ${opts.messageId} is not on the active branch`);
+            }
+            // Never bisect a body group: chronicle refuses that for removals
+            // (byte-faithful reassembly needs the whole run) and branchAt has no
+            // such guard of its own. Snap to the run's last shard.
+            const run = bodyGroupRun(cm, requestedIndex);
+            const targetIndex = run.to;
+            const tailMessageId = run.toId;
+            const messagesRemoved = total - targetIndex - 1;
+            if (messagesRemoved <= 0) {
+                throw new OperatorActionError('invalid', `Message ${opts.messageId} is already the tail of the active branch`);
+            }
+            const discarded = cm.getMessageWindow(targetIndex + 1, messagesRemoved, { resolveBlobs: false }).messages;
+            const removedRefs = extractDiscordAwarenessRefs(discarded);
+            const sourceBranch = this.store.currentBranch().name;
+            const targetBranch = opts.branchName ?? `rollback/${agentName}/${Date.now()}`;
+            if (targetBranch === sourceBranch) {
+                throw new OperatorActionError('invalid', 'Rollback branch name must differ from the active branch');
+            }
+            // Gate + reserve the whole store (see reserveStoreForSurgery); held
+            // until the switch has landed or been rolled back.
+            const release = this.reserveStoreForSurgery('roll back', agentName);
+            let branchName;
+            try {
+                // Prepare the external side effect before switching Chronicle. If the
+                // process dies after the switch but before activate(), startup
+                // promotes this batch by matching targetBranch to the active branch.
+                // If the fork/switch itself throws, the batch is retired so it cannot
+                // arm a later branch that happens to reuse the name.
+                const markerBatch = this.discordAwarenessOutbox?.prepare({
+                    agentName,
+                    sourceBranch,
+                    targetBranch,
+                    refs: removedRefs,
+                    emoji: this.discordAwarenessEmoji,
+                }) ?? null;
+                try {
+                    branchName = cm.branchAt(tailMessageId, targetBranch);
+                    await cm.switchBranch(branchName);
+                }
+                catch (error) {
+                    // switchBranch moves the chronicle branch BEFORE awaiting strategy
+                    // initialization, so a rejection here can leave the store on the
+                    // new branch with an uninitialized strategy. Retire the batch and
+                    // go back to the source; keep the branch for diagnosis.
+                    if (markerBatch)
+                        this.discordAwarenessOutbox.discard(markerBatch.id);
+                    const restored = await this.restoreSourceBranch(cm, sourceBranch, targetBranch, agentName);
+                    throw new OperatorActionError('failed', `Rollback failed; ${restored}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+                }
+                if (markerBatch)
+                    this.discordAwarenessOutbox.activate(markerBatch.id);
+                await this.syncDiscordAwarenessMarkers();
+                this.materializeConfigMountAfterBranchSwitch();
+            }
+            finally {
+                release();
+            }
+            console.error(`[operator] rollback agent=${agentName} to=${tailMessageId}` +
+                `${tailMessageId !== opts.messageId ? ` (requested ${opts.messageId}, snapped to end of body group)` : ''}` +
+                ` removed=${messagesRemoved} branch=${branchName} by=${describeRequester(opts.requester)}`);
+            this.recordOperatorAction({
+                ...logBase,
+                result: {
+                    sourceBranch,
+                    targetBranch: branchName,
+                    tailMessageId,
+                    messagesRemoved,
+                    discordRefs: removedRefs.length,
+                },
+            });
+            return {
+                agentName,
+                sourceBranch,
+                targetBranch: branchName,
+                messagesRemoved,
+                tailMessageId,
+                removedRefs,
+                lastVisible: await this.lastVisiblePreview(agentName),
+            };
+        }
+        catch (error) {
+            this.recordOperatorAction({ ...logBase, error: error instanceof Error ? error.message : String(error) });
+            throw error;
+        }
+    }
+    /**
+     * Suppress specific messages from the live context without touching the
+     * source branch: fork at the current head (`suppress/<agent>/<ts>`), 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
+     * a crash mid-way is finished at next boot (resumePreparedDiscordSuppressions).
+     *
+     * Not retroactive over derived state: a message already folded into an
+     * autobiographical summary stays in that summary — roll back to before it
+     * entered if that matters.
+     */
+    async suppressMessages(agentName, opts) {
+        const requestedIds = [...new Set(opts.messageIds.map(String))];
+        const logBase = {
+            kind: 'suppress',
+            agent: agentName,
+            ...(opts.requester ? { requester: opts.requester } : {}),
+            ...(opts.note ? { note: opts.note } : {}),
+            params: { messageIds: requestedIds },
+        };
+        try {
+            const agent = this.agents.get(agentName);
+            if (!agent)
+                throw new OperatorActionError('unknown-agent', `Unknown agent: ${agentName}`);
+            if (requestedIds.length === 0)
+                throw new OperatorActionError('invalid', 'No message ids given');
+            const cm = agent.getContextManager();
+            const total = cm.getMessageCount();
+            const located = locateMessageIndices(cm, new Set(requestedIds));
+            const missing = requestedIds.filter((id) => !located.has(id));
+            if (missing.length > 0) {
+                throw new OperatorActionError('unknown-message', `Not on the active branch: ${missing.slice(0, 5).join(', ')}${missing.length > 5 ? ` (+${missing.length - 5})` : ''}`);
+            }
+            // Build removal intervals (index-ordered, newest first). A shard expands
+            // to its whole body group — chronicle refuses to bisect one — and a
+            // group interval is always removed as a RANGE: `removeMessage` refuses
+            // any sharded message even when the group is down to one shard.
+            const intervals = new Map();
+            for (const id of requestedIds) {
+                const run = bodyGroupRun(cm, located.get(id).index);
+                intervals.set(`${run.from}-${run.to}`, run);
+            }
+            const ordered = [...intervals.values()].sort((a, b) => b.from - a.from);
+            const messagesRemoved = ordered.reduce((n, iv) => n + (iv.to - iv.from + 1), 0);
+            if (messagesRemoved >= total) {
+                throw new OperatorActionError('invalid', `Cannot suppress all ${total} message(s) — at least one must remain`);
+            }
+            const targeted = ordered.flatMap((iv) => cm.getMessageWindow(iv.from, iv.to - iv.from + 1, { resolveBlobs: false }).messages);
+            const removedIds = targeted.map((m) => String(m.id));
+            const removedRefs = extractDiscordAwarenessRefs(targeted);
+            const sourceBranch = this.store.currentBranch().name;
+            const targetBranch = opts.branchName ?? `suppress/${agentName}/${Date.now()}`;
+            if (targetBranch === sourceBranch) {
+                throw new OperatorActionError('invalid', 'Suppression branch name must differ from the active branch');
+            }
+            // Gate + reserve the whole store (see reserveStoreForSurgery); held
+            // until the fork is fully redacted or the source is restored.
+            const release = this.reserveStoreForSurgery('suppress', agentName);
+            let createdBranch;
+            try {
+                const markerBatch = this.discordAwarenessOutbox?.prepare({
+                    agentName,
+                    sourceBranch,
+                    targetBranch,
+                    refs: removedRefs,
+                    emoji: this.discordAwarenessEmoji,
+                    // Seeing targetBranch active does not prove the removals finished;
+                    // only this operation activates the batch, after the last redaction.
+                    activationPolicy: 'explicit',
+                    suppressionIntervals: ordered.map((iv) => ({ fromId: iv.fromId, toId: iv.toId })),
+                }) ?? null;
+                // Anything short of activation retires the batch: a prepared explicit
+                // batch re-arms through preparedSuppressionsForBranch the moment its
+                // target branch (or a descendant) becomes active — e.g. an operator
+                // opening the failed fork to look — and an un-completable resume
+                // there aborts framework start.
+                const retireBatch = () => {
+                    if (markerBatch)
+                        this.discordAwarenessOutbox.discard(markerBatch.id);
+                };
+                try {
+                    createdBranch = await cm.fork(targetBranch);
+                }
+                catch (error) {
+                    // fork() switches the chronicle branch before awaiting strategy
+                    // initialization; a rejection can leave the store on the new
+                    // branch. Retire the batch and go back to the source.
+                    retireBatch();
+                    const restored = await this.restoreSourceBranch(cm, sourceBranch, targetBranch, agentName);
+                    throw new OperatorActionError('failed', `Suppression failed creating ${targetBranch}; ${restored}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+                }
+                try {
+                    for (const iv of ordered) {
+                        if (iv.group || iv.fromId !== iv.toId)
+                            cm.removeMessages(iv.fromId, iv.toId);
+                        else
+                            cm.removeMessage(iv.fromId);
+                    }
+                    if (markerBatch)
+                        this.discordAwarenessOutbox.activate(markerBatch.id);
+                }
+                catch (error) {
+                    // A partially suppressed branch is not safe to serve from. Keep it
+                    // for diagnosis, put the agent back on the untouched source — and
+                    // say honestly whether that restore happened.
+                    retireBatch();
+                    const restored = await this.restoreSourceBranch(cm, sourceBranch, createdBranch, agentName);
+                    throw new OperatorActionError('failed', `Suppression failed on ${createdBranch}; ${restored}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+                }
+                await this.syncDiscordAwarenessMarkers();
+                this.materializeConfigMountAfterBranchSwitch();
+            }
+            finally {
+                release();
+            }
+            console.error(`[operator] suppress agent=${agentName} removed=${messagesRemoved} branch=${createdBranch} ` +
+                `by=${describeRequester(opts.requester)}`);
+            const loggedIds = capIds(removedIds);
+            this.recordOperatorAction({
+                ...logBase,
+                result: {
+                    sourceBranch,
+                    targetBranch: createdBranch,
+                    messagesRemoved,
+                    removedIds: loggedIds.ids,
+                    ...(loggedIds.truncated ? { removedIdsTruncated: true } : {}),
+                    discordRefs: removedRefs.length,
+                },
+            });
+            return {
+                agentName,
+                sourceBranch,
+                targetBranch: createdBranch,
+                messagesRemoved,
+                removedIds,
+                removedRefs,
+                lastVisible: await this.lastVisiblePreview(agentName),
+            };
+        }
+        catch (error) {
+            this.recordOperatorAction({ ...logBase, error: error instanceof Error ? error.message : String(error) });
+            throw error;
+        }
+    }
+    /** Re-materialize config files from the (new) active branch — fire and
+     *  forget; the gate picks changes up via mtime. Mirrors undoLastTurn. */
+    materializeConfigMountAfterBranchSwitch() {
+        const ws = this.moduleRegistry.getModule('workspace');
+        if (ws && 'materializeMount' in ws) {
+            ws
+                .materializeMount('_config')
+                .catch(() => { });
+        }
+    }
     /**
      * Check if undo/redo is available for an agent.
      */
@@ -3576,7 +5185,10 @@ export class AgentFramework {
         while (!this.queue.isEmpty ||
             // Direct inference requests (e.g. runEphemeralToCompletion) bypass the
             // event queue — without this the loop can exit before they're drained.
-            this.pendingRequests.length > 0 ||
+            // While quiesced, gate-parked requests are NOT progress and must not
+            // block idle (only a budget restart can still run); identity-equivalent
+            // to `.length > 0` when not quiesced.
+            this.pendingRequests.some((r) => !this.quiesced || isTurnContinuation(r.reason)) ||
             this.activeStreams.size > 0 ||
             Array.from(this.agents.values()).some((a) => a.state.status !== 'idle')) {
             await this.processNextEvent();
@@ -3805,7 +5417,7 @@ export class AgentFramework {
                         const deferred = this.drainDeferredFor(agent.name);
                         if (deferred.length > 0) {
                             for (const msg of deferred) {
-                                agent.getContextManager().addMessage(msg.participant, msg.content, msg.metadata);
+                                agent.getContextManager().addMessage(msg.participant, msg.content, withDeferredWriteId(msg.metadata, msg.id));
                                 // Injection guards: tool blocks would corrupt the tool-cycle
                                 // structure the membrane enforces, and a message named as the
                                 // agent itself would render as an ASSISTANT turn on the wire
@@ -3822,6 +5434,9 @@ export class AgentFramework {
                             }
                         }
                     }
+                    // Deferred writes handed to the store above: sync, then drop them
+                    // from the durable recovery queue (no-op unless one is persisted).
+                    this.ackDeferredWrites();
                     // A newly injected CONVERSATIONAL message begins a new
                     // conversational round inside the same provider inference. Remember
                     // that boundary for driveStream: an explicit send in the preceding
@@ -4680,7 +6295,7 @@ export class AgentFramework {
             }
             const providerCooldown = this.providerAccelerationCooldowns?.get(agentName);
             if (providerCooldown) {
-                if (now < providerCooldown.until) {
+                if (now < providerCooldown.until || this.extendHostProviderHold(agentName, providerCooldown)) {
                     for (const req of requests) {
                         if (!providerCooldown.heldRequests.some((r) => this.sameInferenceRequest(r, req))) {
                             providerCooldown.heldRequests.push(req);
@@ -4717,16 +6332,60 @@ export class AgentFramework {
             // This mirrors how the restart has always overwritten activeStreams
             // rather than waiting for the old stream's teardown.
             const budgetRestart = requests.find((r) => r.reason === 'context_budget_restart');
+            // Host quiesce (issue #122): park wakes instead of starting turns —
+            // the requeue mirrors the busy path below, so requests survive and
+            // fire at resume. A context-budget restart passes through: it
+            // CONTINUES a turn whose token is held (see the deadlock note below),
+            // and quiesce's drain is exactly the phase where such a turn must be
+            // allowed to finish. Parked requests are coalesced per reason (newest
+            // kept): heartbeat/gate wakes arrive once per tick and nothing else
+            // bounds a multi-day maintenance window's accumulation.
+            if (this.quiesced) {
+                // Continuations of a held turn (budget restart, non-streaming tool
+                // results) pass; everything else parks.
+                const passThrough = requests.filter((r) => isTurnContinuation(r.reason));
+                const parked = requests.filter((r) => !isTurnContinuation(r.reason));
+                // Coalesce per (reason, addressed): every channel wake shares one
+                // reason, so keying on reason alone would let an ambient message
+                // parked later evict a DM/mention parked earlier — and the
+                // addressed-outranks-ambient trigger selection below would then
+                // route the resumed turn into the wrong channel.
+                const newestByKey = new Map();
+                for (const request of parked) {
+                    const key = `${request.reason}|${request.addressed ? 'a' : 'n'}`;
+                    const prev = newestByKey.get(key);
+                    if (!prev || request.timestamp >= prev.timestamp) {
+                        newestByKey.set(key, request);
+                    }
+                }
+                this.pendingRequests.push(...newestByKey.values());
+                if (passThrough.length === 0)
+                    continue;
+                // The continuation continues its held turn; its parked siblings must
+                // NOT be consumed by that turn — they were re-parked above, so narrow
+                // the batch to the continuation(s) alone before the trigger selection.
+                requests.length = 0;
+                requests.push(...passThrough);
+            }
             const turnAlive = !budgetRestart && this.activeTurnTokens.has(agentName);
             const providerGate = this.providerGates?.get(agentName);
             // A primary can own provider admission while yielding to an already in-flight
             // auxiliary call. Keep this agent's later wakes queued, but do not block the
             // framework event loop or other residents while that auxiliary call settles.
             const providerPrimaryWaiting = (providerGate?.primaryDepth ?? 0) > 0 && !this.activeTurnTokens.has(agentName);
-            if (providerPrimaryWaiting || turnAlive || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
-                // Re-queue requests, but warn if they've been pending too long
+            // A live surgery (rollback/suppress) holds the whole store: no turn may
+            // start for ANY agent — including one registered after the reservation's
+            // token snapshot — until the switch has landed or been rolled back.
+            // Truthiness, not `!== null`: prototype-built harnesses (and any field
+            // added later) leave the slot undefined, which must read as "not held".
+            const surgeryHeld = !!this.surgeryHold;
+            if (surgeryHeld || providerPrimaryWaiting || turnAlive || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
+                // Re-queue requests, but warn if they've been pending too long.
+                // Suppressed while quiesced: a drain-phase busy requeue is expected,
+                // not a wedge tell.
                 const oldest = Math.min(...requests.map(r => r.timestamp));
-                if (now - oldest > STALE_REQUEST_MS &&
+                if (!this.quiesced &&
+                    now - oldest > STALE_REQUEST_MS &&
                     (this.staleWarnAt.get(agentName) ?? 0) < now - 60_000) {
                     // Trace and stderr share the throttle. The old code throttled only
                     // stderr, so a long-running tool call generated one trace per poll
@@ -4737,9 +6396,11 @@ export class AgentFramework {
                     // read 'idle' while a turn's teardown is pending, and a LEAKED turn
                     // token would look exactly like this — permanently requeued wakes.
                     // This line is the wedge's tell (idle+turn-alive, forever).
-                    const shownStatus = turnAlive && agent.state.status === 'idle'
-                        ? 'idle+turn-alive'
-                        : agent.state.status;
+                    const shownStatus = surgeryHeld && agent.state.status === 'idle'
+                        ? `idle+surgery(${this.surgeryHold.verb})`
+                        : turnAlive && agent.state.status === 'idle'
+                            ? 'idle+turn-alive'
+                            : agent.state.status;
                     this.emitTrace({
                         type: 'inference:request_stale',
                         agentName,
@@ -5282,6 +6943,20 @@ export class AgentFramework {
                         console.error(`[provider-admission] ${agent.name}: turn-alive while parked — wake requeued, not started`);
                         return;
                     }
+                    // Same gap, second hazard (#122): the host may have QUIESCED while
+                    // this wake was parked. The scheduler's quiesce gate ran before the
+                    // park; starting here would bypass it and run a turn against a
+                    // context the operator believes frozen. Give admission back and
+                    // requeue — the scheduler re-parks it (coalesced) until resume.
+                    // Continuations of a held turn pass, as they do at the gate.
+                    if (this.quiesced && !isTurnContinuation(trigger?.reason ?? '')) {
+                        this.releasePrimaryProviderGate(agent.name);
+                        this.pendingRequests.push(trigger ?? {
+                            agentName: agent.name, reason: 'provider-admission:requeue', source: 'scheduler', timestamp: Date.now(),
+                        });
+                        console.error(`[provider-admission] ${agent.name}: host quiesced while parked — wake requeued, not started`);
+                        return;
+                    }
                     await this.startAgentStream(agent, trigger, attempt, true);
                 }).catch((error) => {
                     this.releasePrimaryProviderGate(agent.name);
@@ -5356,7 +7031,7 @@ export class AgentFramework {
                     // poison message — or a transient store-write failure — must not
                     // abort the turn or drop the messages behind it in the queue.
                     try {
-                        const id = agent.getContextManager().addMessage(msg.participant, msg.content, msg.metadata);
+                        const id = agent.getContextManager().addMessage(msg.participant, msg.content, withDeferredWriteId(msg.metadata, msg.id));
                         this.emitTrace({ type: 'message:added', messageId: id, source: 'deferred-flush:turn-start' });
                     }
                     catch (err) {
@@ -5364,6 +7039,7 @@ export class AgentFramework {
                             `(participant=${msg.participant}):`, err);
                     }
                 }
+                this.ackDeferredWrites();
             }
         }
         // Record turn checkpoint before inference (only on first attempt, not retries)
@@ -6419,6 +8095,40 @@ export class AgentFramework {
                             break;
                         this.abortAgentScript(agent.name, 'stream error');
                         agent.reset();
+                        // A quiesce-abandoned cancel may surface as `error` instead of
+                        // `aborted` depending on how the stream implementation reports
+                        // the cancellation. Same contract as the aborted branch: settle
+                        // honestly, no errorPolicy retry (which would relaunch inference
+                        // mid-maintenance-window), no inference:exhausted (which feeds
+                        // the failure streak / hard-down / poison-history accounting).
+                        {
+                            const cancelKey = `${agent.name}:${myStreamId}`;
+                            if (this.frameworkCancelledStreams.get(cancelKey) === 'quiesce_abandoned') {
+                                this.frameworkCancelledStreams.delete(cancelKey);
+                                // Same terminal as the `aborted` twin: §10.5 lifecycle reads
+                                // 'aborted' (not 'completed'), and the gate is released only
+                                // for THIS agent instance — a name re-registered meanwhile
+                                // (ephemeral disposal, conversation replacement) owns its own
+                                // gate liveness. The inference-log terminal was already
+                                // written at the top of this case (`Stream error`).
+                                lifecyclePhase = 'aborted';
+                                this.settleAgent(agent.name, {
+                                    stopReason: 'exhausted',
+                                    speech: '',
+                                    error: 'Turn abandoned by operator quiesce',
+                                });
+                                this.emitTrace({
+                                    type: 'inference:aborted',
+                                    agentName: agent.name,
+                                    durationMs,
+                                    reason: 'quiesce_abandoned',
+                                });
+                                if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId) {
+                                    this.eventGate?.onInferenceEnded(agent.name);
+                                }
+                                break;
+                            }
+                        }
                         if (ownsProviderGate && this.holdProviderAcceleration(agent, err, trigger)) {
                             lifecyclePhase = 'failed';
                             if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId)
@@ -6476,6 +8186,30 @@ export class AgentFramework {
                                 else if (this.agents.get(agent.name) === agent && agent.streamId === myStreamId) {
                                     this.eventGate?.onInferenceEnded(agent.name);
                                 }
+                                if (cancelKind === 'quiesce_abandoned') {
+                                    // Operator-initiated cancel during a quiesce drain. Settle
+                                    // the turn honestly — deliberately NO inference:exhausted:
+                                    // that trace centrally drives the consecutive-failure
+                                    // streak, hard-down ops alerts, and the poison-history
+                                    // breaker, none of which an operator cancel represents.
+                                    // inference:aborted carries the observability instead.
+                                    if (agent.streamId === myStreamId) {
+                                        this.abortAgentScript(agent.name, 'turn abandoned by quiesce');
+                                        agent.reset();
+                                        this.settleAgent(agent.name, {
+                                            stopReason: 'exhausted',
+                                            speech: '',
+                                            error: 'Turn abandoned by operator quiesce',
+                                        });
+                                    }
+                                    this.emitTrace({
+                                        type: 'inference:aborted',
+                                        agentName: agent.name,
+                                        durationMs: Date.now() - startTime,
+                                        reason: 'quiesce_abandoned',
+                                    });
+                                    return;
+                                }
                                 // endTurn IS a logical turn end — earlier rounds may have
                                 // live-routed prose (narrate → skip_reply is a real shape),
                                 // so settle the delivery chain and drop the receipt. A
@@ -6749,8 +8483,12 @@ export class AgentFramework {
             if (frameReachedTerminal && this.deferredMessages.length > 0 && this.pendingAssistantBlocks.size === 0) {
                 const deferred = this.drainDeferredFor(agent.name);
                 for (const msg of deferred) {
-                    this.addMessage(msg.participant, msg.content, msg.metadata, msg.forAgent ? { forAgent: msg.forAgent } : undefined);
+                    this.addMessage(msg.participant, msg.content, msg.metadata, {
+                        deferredWriteId: msg.id,
+                        ...(msg.forAgent ? { forAgent: msg.forAgent } : {}),
+                    });
                 }
+                this.ackDeferredWrites();
             }
         }
     }
@@ -6816,6 +8554,9 @@ export class AgentFramework {
         // Idle AND no turn alive: status reads 'idle' from dequeue until the
         // stream registers, and again while a turn's teardown is pending
         // (the scheduler's own busy test, 'idle+turn-alive').
+        if (this.surgeryHold) {
+            throw new Error(`puppet refused: the store is under live ${this.surgeryHold.verb} for ${this.surgeryHold.agentName} — retry when it completes`);
+        }
         if (agent.state.status !== 'idle' || this.activeTurnTokens.has(agentName)) {
             const shown = agent.state.status === 'idle' ? 'idle+turn-alive' : agent.state.status;
             throw new Error(`puppet refused: agent ${agentName} is ${shown} (requires idle — ` +
@@ -6881,7 +8622,7 @@ export class AgentFramework {
                 cm.addMessage('user', blocks);
             }
             else {
-                this.deferredMessages.push({ participant: agentName, content: toolUse, forAgent: agentName }, { participant: 'user', content: blocks, forAgent: agentName });
+                this.deferredMessages.push({ id: randomUUID(), seq: ++this.deferredSeq, participant: agentName, content: toolUse, forAgent: agentName }, { id: randomUUID(), seq: ++this.deferredSeq, participant: 'user', content: blocks, forAgent: agentName });
             }
             this.emitTrace({
                 type: 'puppet:tool-call',
@@ -6909,8 +8650,12 @@ export class AgentFramework {
             if (!this.activeTurnTokens.has(agentName)
                 && this.deferredMessages.length > 0 && this.pendingAssistantBlocks.size === 0) {
                 for (const msg of this.drainDeferredFor(agentName)) {
-                    this.addMessage(msg.participant, msg.content, msg.metadata, msg.forAgent ? { forAgent: msg.forAgent } : undefined);
+                    this.addMessage(msg.participant, msg.content, msg.metadata, {
+                        deferredWriteId: msg.id,
+                        ...(msg.forAgent ? { forAgent: msg.forAgent } : {}),
+                    });
                 }
+                this.ackDeferredWrites();
             }
         }
     }
@@ -8010,6 +9755,10 @@ export class AgentFramework {
         // their own wake), at the agent's next tool boundary (where they are
         // ALSO injected into the live stream — hear-while-acting), or in
         // driveStream's finally when the turn ends.
+        // Quiesce (issue #122): the window exists to run compression/refold
+        // against a FROZEN context — module events and api message.send must not
+        // append mid-surgery. Deferred here, flushed by resume(). tool_result
+        // still lands (a draining turn's continuation depends on it).
         const hasToolResult = content.some(b => b.type === 'tool_result');
         // Explicitly-targeted deliveries scope the tool-cycle check to the
         // target (pendingAssistantBlocks is keyed by agent); the default path
@@ -8019,13 +9768,25 @@ export class AgentFramework {
             ? this.pendingAssistantBlocks.has(agent.name)
             : this.pendingAssistantBlocks.size > 0;
         if (!hasToolResult &&
-            (midToolCycle ||
+            (this.quiesced ||
+                midToolCycle ||
                 this.activeTurnTokens.has(agent.name) ||
                 this.activeStreams.has(agent.name))) {
-            this.deferredMessages.push({ participant, content, metadata, forAgent: opts?.forAgent });
+            // A re-deferral of a drained entry keeps its id and leaves the un-acked
+            // set: one logical message, one durable identity — never two entries.
+            const id = opts?.deferredWriteId ?? randomUUID();
+            let seq;
+            if (opts?.deferredWriteId) {
+                const prior = this.unackedDeferredWrites.find((m) => m.id === id);
+                seq = prior?.seq;
+                this.unackedDeferredWrites = this.unackedDeferredWrites.filter((m) => m.id !== id);
+            }
+            this.deferredMessages.push({ id, seq: seq ?? ++this.deferredSeq, participant, content, metadata, forAgent: opts?.forAgent });
+            if (this.quiesced || this.deferredWritesPersisted)
+                this.persistDeferredWrites();
             return ''; // Deferred — flushed at the target's next boundary
         }
-        return agent.getContextManager().addMessage(participant, content, metadata);
+        return agent.getContextManager().addMessage(participant, content, opts?.deferredWriteId ? withDeferredWriteId(metadata, opts.deferredWriteId) : metadata);
     }
     /**
      * Splice out the deferred messages addressed to `agentName` (explicitly
@@ -8042,6 +9803,12 @@ export class AgentFramework {
             (target === agentName ? mine : rest).push(msg);
         }
         this.deferredMessages = rest;
+        mine.sort(bySeq);
+        // The drained messages are about to be written by the caller; they stay
+        // in the DURABLE queue (as un-acked) until the caller's
+        // ackDeferredWrites() has synced the chronicle. Removing them here would
+        // acknowledge before the write is durable.
+        this.handOffDeferredWrites(mine);
         return mine;
     }
     editMessage(id, content) {
@@ -8179,6 +9946,8 @@ export class AgentFramework {
                         auxiliaryInFlight: gate?.auxiliaryInFlight ?? 0,
                         auxiliaryDeferred: gate?.deferredAuxiliary ?? 0,
                         cooldownUntil: cooldown?.until ?? null,
+                        cooldownReason: cooldown?.reason ?? null,
+                        hostHold: cooldown?.hostHoldError !== undefined,
                         heldRequests: cooldown?.heldRequests.length ?? 0,
                         lastRecovery: this.providerAccelerationLastRecovery?.get(name) ?? null,
                     };
@@ -8850,9 +10619,22 @@ export class AgentFramework {
         for (const connection of this.mcplServerRegistry?.getAllServers() ?? []) {
             // ready() can synchronously flush a nested list-change notification that
             // installs a newer global generation. Never let this older completion
-            // release any remaining server behind that newer gate.
+            // release any remaining server behind that newer gate. (The quiesce
+            // check sits AFTER this guard: readyControlPlane can also synchronously
+            // flush a control event that installs a newer barrier.)
             if (this.discordAwarenessBarrier !== null)
                 return false;
+            // Host quiesce (issue #122): this is the single point every barrier
+            // completion and reconnect flow funnels through, so holding here keeps
+            // data planes paused across awareness drains and reconnects for the
+            // whole window. Control planes come up normally (host/command rides the
+            // control plane, so resume stays deliverable); resume() performs the
+            // real ready() flush through this same funnel once its feasibility gate
+            // passes and the flag is cleared.
+            if (this.quiesced) {
+                connection.readyControlPlane();
+                continue;
+            }
             connection.ready();
         }
         return this.discordAwarenessBarrier === null;