@animalabs/agent-framework 0.6.0 → 0.6.2

package/dist/src/framework.js

@@ -1,10 +1,11 @@
 import { join } from 'node:path';
+import { appendFileSync, mkdirSync } from 'node:fs';
 import { JsStore } from '@animalabs/chronicle';
 import { MembraneError } from '@animalabs/membrane';
 import { ContextManager, PassthroughStrategy } from '@animalabs/context-manager';
 import { ProcessQueueImpl } from './queue.js';
 import { Agent } from './agent.js';
-import { ModuleRegistry } from './module-registry.js';
+import { ModuleRegistry, isStateExistsError } from './module-registry.js';
 import { McplServerRegistry } from './mcpl/server-registry.js';
 import { FeatureSetManager } from './mcpl/feature-set-manager.js';
 import { ScopeManager } from './mcpl/scope-manager.js';
@@ -24,7 +25,8 @@ const FRAMEWORK_STATE_ID = 'framework/state';
 const CONVERSATION_ROUTER_STATE_ID = 'framework/conversation-router';
 const INFERENCE_LOG_ID = 'framework/inference-log';
 const PROCESS_LOG_ID = 'framework/process-log';
-const TURN_CHECKPOINTS_ID = 'framework/turn-checkpoints';
+const TURN_CHECKPOINTS_ID = 'framework/turn-checkpoints'; // legacy single-map layout, read-only fallback
+const TURN_CHECKPOINTS_TREE_ID = 'framework/turn-checkpoints/tree';
 /** Maximum number of turn checkpoints to keep per agent. */
 const MAX_TURN_CHECKPOINTS = 20;
 /**
@@ -95,6 +97,12 @@ function extractGateFields(event) {
         : undefined;
     return { content, metadata, mount, paths };
 }
+/** Cap an API error message for inline use in a rewind marker: keep enough to
+ *  identify the failure class without pasting a wall of provider JSON into the
+ *  agent's context. */
+function truncateReason(reason, max = 160) {
+    return reason.length <= max ? reason : reason.slice(0, max) + '…';
+}
 export class AgentFramework {
     store;
     ownsStore;
@@ -120,6 +128,10 @@ export class AgentFramework {
     traceListeners = [];
     syncIntervalMs;
     syncTimer = null;
+    /** Last time we console-warned about stale (busy-requeued) inference requests, per agent. */
+    staleWarnAt = new Map();
+    /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
+    lastInferenceAt = new Map();
     processLoggingPersist;
     processLoggingBroadcast;
     activeStreams = new Map();
@@ -130,6 +142,23 @@ export class AgentFramework {
     /** N consecutive failed inferences ⇒ the agent is treated as hard-down and
      *  escalated loudly to stderr. */
     inferenceFailureEscalationThreshold = 3;
+    /** Per-agent count of consecutive refusal-driven rewinds in the current turn
+     *  chain (reset when a turn completes without a refusal). Bounds the auto
+     *  rewind loop — see refusalHandling + rewindTriggeringTurn. */
+    refusalRewinds = new Map();
+    /** Per-agent count of poison-history rewinds performed by the hard-down
+     *  breaker (noteInferenceExhausted). Reset on any successful inference.
+     *  Bounds the automatic quarantine loop the same way refusalRewinds bounds
+     *  the refusal loop, so the breaker can never shed the whole history. */
+    exhaustionRewinds = new Map();
+    /** Per-agent current rewind episode: the single consolidated marker's id and
+     *  how many turns have been shed so far. One marker per episode, updated in
+     *  place (see updateRewindMarker); cleared when the episode ends. */
+    rewindEpisode = new Map();
+    /** Active `/unstick` sessions: an admin-forced rewind-until-clean loop that
+     *  runs even when the agent's autoRewind toggle is off. Tracks the remaining
+     *  budget, what was shed (for the report), and where to post the outcome. */
+    forcedRewind = new Map();
     /** Name of the primary (non-ephemeral) agent for routing framework messages. */
     primaryAgentName = null;
     // Messages deferred while an agent is waiting_for_tools (to preserve
@@ -171,6 +200,13 @@ export class AgentFramework {
     mcplPrefixMap = new Map();
     /** Maps serverId → McplServerConfig for prefix lookup. */
     mcplServerConfigs = new Map();
+    /** Host capabilities advertised during the MCP handshake — stored so servers
+     *  can be connected at runtime (connectMcplServer) after initialization. */
+    mcplHostCapabilities = null;
+    /** Inference routing policy from FrameworkConfig — stored so the MCPL
+     *  subsystem can be lazily initialized by connectMcplServer when the
+     *  framework started with zero configured servers. */
+    mcplInferenceRoutingConfig = null;
     // EventGate (null when FrameworkConfig.gate is omitted)
     eventGate = null;
     // Session-level token usage tracking (always-on)
@@ -237,11 +273,14 @@ export class AgentFramework {
         catch {
             // Already registered
         }
+        // The legacy single-map checkpoint state (TURN_CHECKPOINTS_ID) is no longer
+        // registered for new stores — it's read-only fallback data in old ones.
         try {
-            store.registerState({ id: TURN_CHECKPOINTS_ID, strategy: 'snapshot' });
+            store.registerState({ id: TURN_CHECKPOINTS_TREE_ID, strategy: 'tree' });
         }
-        catch {
-            // Already registered
+        catch (error) {
+            if (!isStateExistsError(error))
+                throw error;
         }
         // Process logging config (default: disabled)
         const processLoggingPersist = config.processLogging?.persist ?? false;
@@ -327,6 +366,9 @@ export class AgentFramework {
             });
             framework.livenessWatchdog.start();
         }
+        // Stored for lazy MCPL initialization (connectMcplServer on a framework
+        // that started with zero configured servers).
+        framework.mcplInferenceRoutingConfig = config.inferenceRouting ?? null;
         // Initialize MCPL subsystems if configured
         if (config.mcplServers && config.mcplServers.length > 0) {
             // Validate tool prefixes: no collisions with module names or between servers
@@ -345,6 +387,30 @@ export class AgentFramework {
             }
             await framework.initializeMcpl(config.mcplServers, config.inferenceRouting);
         }
+        // Diagnostics: `kill -USR2 <pid>` dumps live wake/inference state to stderr
+        // (journal) without a restart — for catching the wake-wedge on the running
+        // process. Shows the gate's `inferring` set + buffered-event count (the
+        // wedge signature), active streams, and pending inference requests.
+        try {
+            process.on('SIGUSR2', () => {
+                try {
+                    const gate = framework.eventGate?.inferenceDiagnostics() ?? null;
+                    console.error('[diagnostics] ' + JSON.stringify({
+                        at: new Date().toISOString(),
+                        gate,
+                        activeStreams: [...framework.activeStreams.keys()],
+                        pendingRequests: framework.pendingRequests.length,
+                        agents: [...framework.agents.keys()],
+                    }));
+                }
+                catch (err) {
+                    console.error('[diagnostics] dump failed:', err instanceof Error ? err.message : err);
+                }
+            });
+        }
+        catch {
+            // SIGUSR2 not available on this platform — non-fatal.
+        }
         return framework;
     }
     /**
@@ -568,8 +634,9 @@ export class AgentFramework {
         // Module gatherContext (fail-open, matches startAgentStream)
         try {
             const moduleInjections = await this.moduleRegistry.gatherContext(agentName);
-            if (moduleInjections.length > 0) {
-                injections = moduleInjections;
+            const scopedModuleInjections = this.scopeInjectionsForAgent(agentName, moduleInjections);
+            if (scopedModuleInjections.length > 0) {
+                injections = scopedModuleInjections;
             }
         }
         catch (error) {
@@ -580,7 +647,7 @@ export class AgentFramework {
         if (this.hookOrchestrator) {
             try {
                 const hookParams = this.buildBeforeInferenceParams(agent);
-                const hookInjections = await this.hookOrchestrator.beforeInference(hookParams);
+                const hookInjections = this.scopeInjectionsForAgent(agentName, await this.hookOrchestrator.beforeInference(hookParams));
                 if (hookInjections.length > 0) {
                     injections = injections ? [...injections, ...hookInjections] : hookInjections;
                 }
@@ -743,6 +810,7 @@ export class AgentFramework {
                 clearInterval(completionWatchdog);
                 this.offTrace(traceListener);
                 this.agents.delete(agent.name);
+                this.evictTurnCheckpoints(agent.name);
             };
             // Watchdog: if inference never starts within 30s, the agent is a zombie.
             // This catches cases where the event loop stalled, the agent was
@@ -1080,6 +1148,181 @@ export class AgentFramework {
             console.error('[inference-refusal] reaction failed:', err instanceof Error ? err.message : err);
         }
     }
+    /**
+     * Rewind the single turn that fed a refused generation: redact the newest
+     * message the agent did NOT author (a tool result, or an incoming message)
+     * and inject a metadata-only marker in its place. The marker carries a
+     * *description* of what was withheld (kind + size), never the content — so it
+     * cannot itself re-trip the classifier — while the raw record survives in the
+     * chronicle log for forensics. Returns a record describing the removal, or
+     * null if there is nothing eligible to rewind (e.g. only the agent's own
+     * turns, or a prior system marker, remain).
+     *
+     * Shared by the auto path (on `stop_reason: refusal`) and the `/rewind`
+     * host command.
+     */
+    shedNewestTurn(agent) {
+        const cm = agent.getContextManager();
+        const all = cm.getAllMessages();
+        const typeOf = (b) => b.type;
+        const hasBlock = (m, t) => Array.isArray(m?.content) && m.content.some((b) => typeOf(b) === t);
+        // Newest message that is not our own episode marker. We shed strictly
+        // newest-first, in sequence — INCLUDING the agent's own turns (poison lives
+        // in tool_use/narration turns too), because newest-first reaches whatever is
+        // poisoning the context if allowed to run deep enough. The one invariant:
+        // shed COMPLETE exchanges. Removing a `tool_result` also removes its paired
+        // `tool_use` assistant turn, so we never leave an orphaned tool_use / signed
+        // `thinking` block — which the API rejects with a 400 ("thinking blocks in
+        // the latest assistant message cannot be modified"). We do NOT add a marker
+        // here; the caller keeps one consolidated marker (updateRewindMarker).
+        let idx = -1;
+        for (let i = all.length - 1; i >= 0; i--) {
+            const meta = (all[i].metadata ?? {});
+            if (meta.system)
+                continue;
+            idx = i;
+            break;
+        }
+        if (idx < 0)
+            return null;
+        const msg = all[idx];
+        const md = (msg.metadata ?? {});
+        const content = Array.isArray(msg.content) ? msg.content : [];
+        const toolBlocks = content.filter((b) => typeOf(b) === 'tool_result');
+        const images = content.filter((b) => typeOf(b) === 'image').length;
+        const textLen = content
+            .filter((b) => typeOf(b) === 'text')
+            .reduce((n, b) => n + String(b.text ?? '').length, 0);
+        // Determine the complete exchange to remove.
+        const removedIds = [msg.id];
+        let kind;
+        let descriptor;
+        if (toolBlocks.length > 0) {
+            kind = 'tool';
+            // Pair the tool_result with the tool_use assistant turn right before it.
+            if (idx - 1 >= 0 && hasBlock(all[idx - 1], 'tool_use')) {
+                removedIds.push(all[idx - 1].id);
+            }
+            const sz = toolBlocks.reduce((n, b) => n + String(b.content ?? '').length, 0);
+            descriptor = `a tool exchange (~${Math.max(1, Math.round(sz / 1024))}KB` +
+                `${images ? `, ${images} image(s)` : ''})`;
+        }
+        else if (md.messageId) {
+            kind = 'human';
+            descriptor = `an incoming message from ${msg.participant} ` +
+                `(${textLen} chars${images ? `, ${images} image(s)` : ''})`;
+        }
+        else {
+            kind = 'other';
+            descriptor = `a ${msg.participant} turn ` +
+                `(${textLen} chars${images ? `, ${images} image(s)` : ''})`;
+        }
+        const discordRef = md.messageId && md.channelId
+            ? { channelId: String(md.channelId), messageId: String(md.messageId) }
+            : undefined;
+        for (const id of removedIds)
+            cm.removeMessage(id);
+        return { kind, descriptor, removedIds, discordRef };
+    }
+    /**
+     * Maintain exactly ONE consolidated marker for the current rewind episode,
+     * updated in place as more turns are shed. Six rewinds ⇒ one message that
+     * says "the 6 most recent turns were set aside", not six separate notes — so
+     * the context converges (shed N, add 1) instead of growing, and the marker
+     * sits at the tail giving the model something actionable to answer once the
+     * refusal clears. Returns the running count.
+     */
+    updateRewindMarker(agent, category, cause = 'refusal') {
+        const cm = agent.getContextManager();
+        const ep = this.rewindEpisode.get(agent.name);
+        const count = (ep?.count ?? 0) + 1;
+        const why = cause === 'refusal'
+            ? `the model refused on them (content filter: ${category}). Their content is ` +
+                `not reproduced here (so this note can't re-trigger the filter); the ` +
+                `originals remain in the raw record`
+            : `the model API kept rejecting the conversation on them (${category}). ` +
+                `Their content is not reproduced here (so this note can't re-trigger the ` +
+                `rejection); the originals remain in the raw record`;
+        const text = `[refusal-rewind] The ${count} most recent turn(s) were set aside because ` +
+            `${why}. You are clear to continue — if you ` +
+            `were mid-task, take a different approach; otherwise carry on with whatever ` +
+            `is now in front of you, or briefly acknowledge the gap and ask what's next.`;
+        const blocks = [{ type: 'text', text }];
+        if (ep) {
+            cm.editMessage(ep.markerId, blocks);
+            this.rewindEpisode.set(agent.name, { markerId: ep.markerId, count, category });
+        }
+        else {
+            const id = cm.addMessage('user', blocks, {
+                system: true, kind: 'refusal-rewind', category, count, cause,
+            });
+            this.rewindEpisode.set(agent.name, { markerId: id, count, category });
+        }
+        return count;
+    }
+    /**
+     * Announce a refusal-rewind on the conversational surface (Discord), used
+     * when the withheld turn was a *human* message so it isn't dropped silently.
+     * Best-effort; mirrors reactToRefusal's locus resolution.
+     */
+    async announceRewind(agentName, rec, category) {
+        try {
+            const incoming = this.channelRegistry?.buildChannelContext()?.incoming;
+            if (!incoming)
+                return;
+            const parts = incoming.channelId.split(':');
+            if (parts[0] !== 'discord')
+                return;
+            const channelId = parts[parts.length - 1];
+            const serverId = this.channelRegistry?.getChannelServerId(incoming.channelId);
+            const server = serverId ? this.mcplServerRegistry?.getServer(serverId) : null;
+            if (!server)
+                return;
+            await server.sendToolsCall('send_message', {
+                channelId,
+                content: `⚠️ I had to set aside ${rec.descriptor} — it tripped a content ` +
+                    `filter (${category}), so it's withheld from my context and I'm ` +
+                    `continuing without it. If it was important, please rephrase or re-send.`,
+            });
+        }
+        catch (err) {
+            console.error('[refusal-rewind] announce failed:', err instanceof Error ? err.message : err);
+        }
+    }
+    /**
+     * Conclude an active `/unstick` session: post the outcome (what was shed and
+     * whether the model stopped refusing) to the channel the command came from,
+     * then clear the session. Idempotent — a no-op if there's no session.
+     */
+    finishUnstick(agentName, success, category) {
+        const s = this.forcedRewind.get(agentName);
+        if (!s)
+            return;
+        this.forcedRewind.delete(agentName);
+        const n = s.removed.length;
+        const list = n
+            ? '\n' + s.removed.map((r) => `• ${r.descriptor}`).join('\n')
+            : '';
+        const content = success
+            ? `🔧 Unstuck **${agentName}** — shed ${n} turn(s); the model responded.${list}`
+            : `⚠️ Couldn't unstick **${agentName}** — still refusing after ${n} rewind(s)` +
+                `${category ? ` (category=${category})` : ''}.${list}`;
+        console.error(`[unstick] agent=${agentName} ${success ? 'succeeded' : 'gave up'} after ${n} rewind(s)`);
+        if (s.channelId)
+            void this.postToChannel(s.serverId, s.channelId, content);
+    }
+    /** Best-effort send_message to a raw channel via a named MCPL server. */
+    async postToChannel(serverId, channelId, content) {
+        try {
+            const server = this.mcplServerRegistry?.getServer(serverId);
+            if (!server)
+                return;
+            await server.sendToolsCall('send_message', { channelId, content });
+        }
+        catch (err) {
+            console.error('[unstick] report post failed:', err instanceof Error ? err.message : err);
+        }
+    }
     /**
      * Handle a `host/command` request from an MCPL surface server (e.g. a
      * Discord slash command). Currently supports:
@@ -1090,13 +1333,41 @@ export class AgentFramework {
      *   `previewActivation` render (no inference, no Chronicle writes).
      */
     async handleHostCommand(serverId, params) {
-        if (params.command !== 'undo' && params.command !== 'hide') {
+        if (params.command !== 'undo' && params.command !== 'hide' && params.command !== 'unstick') {
             return { ok: false, error: `Unknown host command: ${String(params.command)}` };
         }
         const agentName = params.agentName ?? [...this.agents.keys()][0];
         if (!agentName || !this.agents.has(agentName)) {
             return { ok: false, error: `Unknown agent: ${String(agentName)}` };
         }
+        // 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
+        // re-runs, up to `cap` times, until the model stops refusing. Kicks the
+        // loop and returns immediately; the outcome (what was shed + whether it
+        // cleared) is posted to the channel when the chain resolves.
+        if (params.command === 'unstick') {
+            const agent = this.agents.get(agentName);
+            if (agent.state.status !== 'idle') {
+                return { ok: false, error: `Cannot unstick while agent is ${agent.state.status}` };
+            }
+            const cap = Math.max(1, Math.min(10, Math.floor(params.maxRewinds ?? agent.refusalHandling?.maxRewinds ?? 3)));
+            this.forcedRewind.set(agentName, {
+                remaining: cap,
+                removed: [],
+                serverId,
+                channelId: params.channelId ?? '',
+            });
+            this.refusalRewinds.set(agentName, 0);
+            this.pendingRequests.push({
+                agentName,
+                reason: 'unstick',
+                source: 'framework',
+                timestamp: Date.now(),
+            });
+            console.error(`[unstick] agent=${agentName} started cap=${cap} ` +
+                `by=${params.requesterName ?? params.requesterId ?? 'unknown'} (server=${serverId})`);
+            return { ok: true, started: true, cap };
+        }
         // hide: redact a single message (or an inclusive range) from the active
         // branch, addressed by Discord message id. Unlike undo this is a
         // removal-in-place (chronicle redact), not a branch rewind.
@@ -1615,18 +1886,86 @@ export class AgentFramework {
         }
         this.saveTurnCheckpoints(agentName, checkpoints);
     }
+    /**
+     * Checkpoints live in one Tree state (TURN_CHECKPOINTS_TREE_ID) keyed by agent
+     * name, each key pointing at a JSON blob of that agent's ≤MAX_TURN_CHECKPOINTS
+     * list. This kills two unbounded-in-agents-ever dimensions at once:
+     *
+     *  - the original single Record<agentName, list> map was rewritten whole on
+     *    every turn of every agent and never evicted a departed subagent's key;
+     *  - the intermediate design (one state slot per agent) fixed the writes but
+     *    leaked a permanent chronicle state *registration* per spawn — chronicle
+     *    has no deregistration, and the state index is rewritten and fsynced on
+     *    every sync tick, so per-tick cost grew with fleet history anyway.
+     *
+     * A tree gives per-key O(entry) writes, real key removal (treeRemove), and
+     * exactly one registration for the life of the store. The legacy map state
+     * (TURN_CHECKPOINTS_ID) is kept as a read-only fallback for stores written
+     * before the split; eviction tombstones legacy keys so a reused agent name
+     * can't inherit a dead agent's checkpoints through the fallback.
+     */
+    legacyCheckpointKeys = null;
+    hasLegacyCheckpoints(agentName) {
+        if (!this.legacyCheckpointKeys) {
+            const legacy = this.store.getStateJson(TURN_CHECKPOINTS_ID);
+            this.legacyCheckpointKeys = new Set(legacy && typeof legacy === 'object' ? Object.keys(legacy) : []);
+        }
+        return this.legacyCheckpointKeys.has(agentName);
+    }
     getTurnCheckpoints(agentName) {
-        const data = this.store.getStateJson(TURN_CHECKPOINTS_ID);
-        if (!data || typeof data !== 'object')
+        const entry = this.store.treeGet(TURN_CHECKPOINTS_TREE_ID, agentName);
+        if (entry) {
+            const blob = this.store.getBlob(entry.blobHash);
+            if (!blob)
+                return [];
+            try {
+                const parsed = JSON.parse(blob.toString());
+                return Array.isArray(parsed) ? parsed : [];
+            }
+            catch {
+                return [];
+            }
+        }
+        if (!this.hasLegacyCheckpoints(agentName))
             return [];
-        const allCheckpoints = data;
-        return Array.isArray(allCheckpoints[agentName]) ? [...allCheckpoints[agentName]] : [];
+        const legacy = this.store.getStateJson(TURN_CHECKPOINTS_ID);
+        const list = legacy?.[agentName];
+        return Array.isArray(list) ? [...list] : [];
     }
     saveTurnCheckpoints(agentName, checkpoints) {
-        const data = this.store.getStateJson(TURN_CHECKPOINTS_ID);
-        const allCheckpoints = (data && typeof data === 'object' ? data : {});
-        allCheckpoints[agentName] = checkpoints;
-        this.store.setStateJson(TURN_CHECKPOINTS_ID, allCheckpoints);
+        const bytes = Buffer.from(JSON.stringify(checkpoints));
+        const blobHash = this.store.storeBlob(bytes, 'application/json');
+        this.store.treeSet(TURN_CHECKPOINTS_TREE_ID, agentName, {
+            blobHash,
+            size: bytes.length,
+            mode: 0o644,
+        });
+    }
+    /**
+     * Drop a departed agent's checkpoint tree key and turn/redo bookkeeping.
+     * Without this, spawn-and-dispose agents leave a key (and in-memory map
+     * entries) behind for the life of the store/session.
+     */
+    evictTurnCheckpoints(agentName) {
+        this.turnCounters.delete(agentName);
+        this.redoStacks.delete(agentName);
+        // Diagnostics maps are also keyed by agent name and never evicted —
+        // spawn-and-dispose fleets would grow them for the session's life.
+        this.staleWarnAt.delete(agentName);
+        this.lastInferenceAt.delete(agentName);
+        const entry = this.store.treeGet(TURN_CHECKPOINTS_TREE_ID, agentName);
+        if (this.hasLegacyCheckpoints(agentName)) {
+            // A bare treeRemove would resurrect the legacy map's list through the
+            // fallback next time this name is reused — shadow it with an empty
+            // tombstone instead. size <= 2 ⇔ the blob is already "[]".
+            if (!entry || entry.size > 2) {
+                this.saveTurnCheckpoints(agentName, []);
+            }
+            return;
+        }
+        if (entry) {
+            this.store.treeRemove(TURN_CHECKPOINTS_TREE_ID, agentName);
+        }
     }
     /**
      * Run until the queue is empty and all agents are idle.
@@ -1634,6 +1973,9 @@ export class AgentFramework {
      */
     async runUntilIdle() {
         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 ||
             this.activeStreams.size > 0 ||
             Array.from(this.agents.values()).some((a) => a.state.status !== 'idle')) {
             await this.processNextEvent();
@@ -2083,6 +2425,7 @@ export class AgentFramework {
         this.agents.delete(agentName);
         this.agentConfigs.delete(agentName);
         this.conversationAgentHomes.delete(agentName);
+        this.evictTurnCheckpoints(agentName);
         this.emitTrace({
             type: 'mcpl:conversation-disposed',
             agentName,
@@ -2257,6 +2600,7 @@ export class AgentFramework {
                     requestCount: requests.length,
                     oldestRequestAge: now - oldest,
                 });
+                console.error(`[inference-dropped] agent=${agentName} reason=agent_not_found requests=${requests.length}`);
                 continue;
             }
             // Skip if agent is busy (inferring, streaming, or waiting for tools)
@@ -2271,12 +2615,23 @@ export class AgentFramework {
                         requestCount: requests.length,
                         oldestRequestAge: now - oldest,
                     });
+                    // Loud (but throttled) note that requests are waiting on a busy agent.
+                    if ((this.staleWarnAt.get(agentName) ?? 0) < now - 60_000) {
+                        this.staleWarnAt.set(agentName, now);
+                        console.error(`[inference-stale] agent=${agentName} busy (${agent.state.status}) — ` +
+                            `${requests.length} request(s) waiting ${Math.round((now - oldest) / 1000)}s`);
+                    }
                 }
                 this.pendingRequests.push(...requests);
                 continue;
             }
             // Check policy
             if (!this.inferencePolicy.shouldInfer(agentName, requests, state)) {
+                // Loud drop: a queued request that dies here is otherwise invisible —
+                // the 2026-07-09 mythos "not responding" diagnosis burned hours on
+                // exactly this class of silent drop. One stderr line per drop.
+                console.error(`[inference-dropped] agent=${agentName} reason=policy-skip ` +
+                    `requests=${requests.length} triggers=${requests.map((r) => r.reason).join(',')}`);
                 continue;
             }
             // Start streaming inference (non-blocking — driveStream runs in background)
@@ -2313,20 +2668,20 @@ export class AgentFramework {
         }
         this.emitTrace({ type: 'inference:started', agentName: agent.name });
         this.eventGate?.onInferenceStarted(agent.name);
+        this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), startedAt: Date.now() });
         try {
             const allTools = this.getAllTools();
             const tools = allTools.filter((t) => agent.canUseTool(t.name));
             // Gather context from modules (pull-based) and MCPL hooks (push-based)
             // Both produce ContextInjection[] that get merged before inference.
             let injections;
-            // Module gatherContext (fail-open, 5s timeout per module)
-            // NOTE: module injections are NOT channel-scoped — only the MCPL hook
-            // injections below pass through scopeInjectionsForAgent (channel
-            // context arrives via beforeInference hooks by adapter convention). A
-            // module that starts emitting per-channel context must scope it per
-            // agent itself, or conversation forks will see cross-channel content.
+            // Module gatherContext (fail-open, per-module timeout — the module's
+            // contextTimeoutMs, else the registry default). Injections are
+            // channel-scoped via scopeInjectionsForAgent, matching the MCPL hook
+            // injections below, so conversation forks don't see cross-channel
+            // content.
             try {
-                const moduleInjections = await this.moduleRegistry.gatherContext(agent.name);
+                const moduleInjections = this.scopeInjectionsForAgent(agent.name, await this.moduleRegistry.gatherContext(agent.name));
                 if (moduleInjections.length > 0) {
                     injections = moduleInjections;
                 }
@@ -2370,6 +2725,13 @@ export class AgentFramework {
                     type: 'inference:exhausted',
                     agentName: agent.name,
                     error: err.message,
+                    // Drives the poison-history breaker. `retryable` is kept for
+                    // observability, but the breaker gates on `errorType` — only an
+                    // `invalid_request` (a 400-class rejection of the history itself)
+                    // means retrying the same context can never succeed. auth/abort/
+                    // context_length are also non-retryable but must NOT cost history.
+                    retryable: err instanceof MembraneError ? err.retryable : undefined,
+                    errorType: err instanceof MembraneError ? err.type : undefined,
                 });
                 this.eventGate?.onInferenceEnded(agent.name);
                 if (action.emit) {
@@ -2608,7 +2970,73 @@ export class AgentFramework {
                             const category = stopDetails?.category ?? 'unknown';
                             console.error(`[inference-refusal] agent=${agent.name} category=${category}` +
                                 (stopDetails?.explanation ? ` explanation=${stopDetails.explanation}` : ''));
-                            void this.reactToRefusal(agent.name, category);
+                            // Rewind: excise the turn that fed the refusal, drop a
+                            // metadata-only marker, and retry — keeping the agent on its own
+                            // model instead of substituting a fallback. Driven either by an
+                            // admin `/unstick` (forced session) or the agent's autoRewind
+                            // config; both are bounded.
+                            let handledByRewind = false;
+                            const rh = agent.refusalHandling;
+                            const forced = this.forcedRewind.get(agent.name);
+                            // Shed exactly one more (newest, in-sequence) turn and keep the
+                            // single episode marker current. `budgetLeft` bounds the loop.
+                            const doRewind = (budgetLeft, onStep, onGiveUp) => {
+                                if (!budgetLeft) {
+                                    onGiveUp();
+                                    return;
+                                }
+                                const rec = this.shedNewestTurn(agent);
+                                if (!rec) {
+                                    onGiveUp();
+                                    return;
+                                }
+                                const count = this.updateRewindMarker(agent, category);
+                                onStep(count);
+                                if (forced)
+                                    forced.removed.push(rec);
+                                this.pendingRequests.push({
+                                    agentName: agent.name,
+                                    reason: forced ? 'unstick-retry' : 'refusal-rewind-retry',
+                                    source: 'framework',
+                                    timestamp: Date.now(),
+                                });
+                                handledByRewind = true;
+                            };
+                            if (forced) {
+                                doRewind(forced.remaining > 0, (count) => {
+                                    forced.remaining -= 1;
+                                    console.error(`[unstick] agent=${agent.name} shed ${count} turn(s) ` +
+                                        `(remaining ${forced.remaining})`);
+                                }, () => this.finishUnstick(agent.name, false, category));
+                            }
+                            else if (rh?.autoRewind) {
+                                const cap = Math.max(1, rh.maxRewinds ?? 3);
+                                const used = this.refusalRewinds.get(agent.name) ?? 0;
+                                doRewind(used < cap, (count) => {
+                                    this.refusalRewinds.set(agent.name, used + 1);
+                                    console.error(`[refusal-rewind] agent=${agent.name} shed ${count} turn(s) so far ` +
+                                        `(cap ${cap})`);
+                                }, () => {
+                                    console.error(`[refusal-rewind] agent=${agent.name} gave up: ` +
+                                        `${used >= cap ? `cap ${cap} reached` : 'nothing left to shed'}`);
+                                    this.refusalRewinds.set(agent.name, 0);
+                                    this.rewindEpisode.delete(agent.name);
+                                });
+                            }
+                            if (!handledByRewind)
+                                void this.reactToRefusal(agent.name, category);
+                        }
+                        else {
+                            // A turn that completed WITHOUT a refusal ends the rewind episode:
+                            // the model responded. Leave the consolidated marker in place as
+                            // the durable record; just clear the per-episode counters.
+                            if (this.forcedRewind.has(agent.name)) {
+                                this.finishUnstick(agent.name, true);
+                            }
+                            if (this.refusalRewinds.get(agent.name)) {
+                                this.refusalRewinds.set(agent.name, 0);
+                            }
+                            this.rewindEpisode.delete(agent.name);
                         }
                         // Dispatch speech (and thoughts if any)
                         if (speechContent.length > 0 || thoughts.length > 0) {
@@ -2692,11 +3120,19 @@ export class AgentFramework {
                                     `(${silenced ? 'silencing tool / explicit send' : 'no prose'})`);
                             }
                             else {
-                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> routing ${segments.length} prose segment(s) in order`);
+                                // Snapshot the locus ONCE. This loop dispatches AFTER the agent
+                                // is idle (see PR #32 note below), so a queued inbound from
+                                // another channel can start a NEW turn and overwrite the per-agent
+                                // triggering channel (`activeTriggerChannels`) BETWEEN segments —
+                                // splitting one turn's reply across channels (the residual
+                                // multi-segment race left by 83dedf8's per-agent locus). Pin every
+                                // segment of THIS turn to the channel resolved right now.
+                                const turnLocus = this.channelRegistry.resolveLocus(agent.name);
+                                console.error(`[routing] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> routing ${segments.length} prose segment(s) in order -> ${turnLocus ?? '(default)'}`);
                                 // Deliver sequentially (await each) so the segments land in order.
                                 for (const seg of segments) {
                                     try {
-                                        await this.channelRegistry.routeSpeech(agent.name, seg);
+                                        await this.channelRegistry.routeSpeech(agent.name, seg, turnLocus);
                                     }
                                     catch (err) {
                                         console.error('speech routing failed:', err);
@@ -2742,6 +3178,12 @@ export class AgentFramework {
                                 type: 'inference:exhausted',
                                 agentName: agent.name,
                                 error: err.message,
+                                // Drives the poison-history breaker. `retryable` is kept for
+                                // observability, but the breaker gates on `errorType` — only an
+                                // `invalid_request` (a 400-class rejection of the history
+                                // itself) means retrying the same context can never succeed.
+                                retryable: err instanceof MembraneError ? err.retryable : undefined,
+                                errorType: err instanceof MembraneError ? err.type : undefined,
                             });
                             this.eventGate?.onInferenceEnded(agent.name);
                             if (action.emit) {
@@ -2755,18 +3197,51 @@ export class AgentFramework {
                         // Only reset if this is still the active stream (a budget restart
                         // may have already started a new stream, bumping streamId)
                         if (agent.streamId === myStreamId) {
+                            const durationMs = Date.now() - startTime;
                             agent.reset();
                             this.emitTrace({
                                 type: 'inference:exhausted',
                                 agentName: agent.name,
                                 error: `Stream aborted: ${reason}`,
                             });
+                            // Postmortem 2026-05-28 P2 #7: persist the abort to the
+                            // inference log so future investigations can attribute the
+                            // terminal cause without relying on live in-memory reducer
+                            // state. Without this, abort-terminated inferences are
+                            // invisible to forensic queries (only request-side telemetry
+                            // via llm-calls.jsonl shows them, and only by absence).
+                            this.logInference({
+                                timestamp: startTime,
+                                agentName: agent.name,
+                                requestId,
+                                success: false,
+                                error: `Stream aborted: ${reason}`,
+                                request: compiledRequest ?? { note: 'streaming request aborted' },
+                                durationMs,
+                            });
                             this.eventGate?.onInferenceEnded(agent.name);
                         }
                         break;
                     }
-                    case 'usage':
+                    case 'usage': {
                         agent.lastStreamInputTokens = event.usage.inputTokens;
+                        // Closed-loop estimator calibration (2026-07-12). Sample the REAL
+                        // prefix size of THIS API call (fresh + cache write + cache read)
+                        // and hand it to the context strategy, which accepts exactly one
+                        // sample per compile (its arm-once gate) and rejects out-of-band
+                        // ratios. It must be sampled HERE, per call: `response.details.
+                        // usage` at turn completion is CUMULATIVE across the tool-use
+                        // loop (5 calls x ~160k reported as 884k), which is not a
+                        // window-shaped number and drove the multiplier to 2.37 before
+                        // the guards caught it.
+                        try {
+                            const realTotal = (event.usage.inputTokens ?? 0) +
+                                (event.usage.cacheCreationTokens ?? 0) +
+                                (event.usage.cacheReadTokens ?? 0);
+                            const strat = agent.getContextManager?.()?.getStrategy?.();
+                            strat?.reportRealInputTokens?.(realTotal);
+                        }
+                        catch { /* calibration is best-effort */ }
                         this.emitTrace({
                             type: 'inference:usage',
                             agentName: agent.name,
@@ -2778,6 +3253,7 @@ export class AgentFramework {
                             },
                         });
                         break;
+                    }
                 }
             }
         }
@@ -2785,6 +3261,7 @@ export class AgentFramework {
             // Stream itself threw (unexpected) — no retry path here, so also emit
             // inference:exhausted so ephemeral agent promises can settle.
             const err = error instanceof Error ? error : new Error(String(error));
+            const durationMs = Date.now() - startTime;
             this.emitTrace({
                 type: 'inference:failed',
                 agentName: agent.name,
@@ -2796,10 +3273,31 @@ export class AgentFramework {
                 agentName: agent.name,
                 error: err.message,
             });
+            // Postmortem 2026-05-28 P2 #7: catch-path failures (stream itself
+            // threw) were previously only visible via in-memory trace listeners.
+            // Persist to inference log for forensic attribution.
+            this.logInference({
+                timestamp: startTime,
+                agentName: agent.name,
+                requestId,
+                success: false,
+                error: `Stream threw: ${err.message}`,
+                request: compiledRequest ?? { note: 'streaming request threw' },
+                durationMs,
+            });
             agent.reset();
             this.eventGate?.onInferenceEnded(agent.name);
         }
         finally {
+            // Clear the gate's inference flag on EVERY exit path (paired with the
+            // onInferenceStarted in startAgentStream). The branch-level calls above
+            // are kept but are best-effort; if any exit path bypassed them the agent
+            // stayed stuck in the gate's `inferring` set, which permanently BUFFERS
+            // all incoming events → the agent silently stops waking on messages
+            // (typing still stops, compression still runs — matching the observed
+            // wedge). onInferenceEnded is idempotent, so a redundant call is safe.
+            this.eventGate?.onInferenceEnded(agent.name);
+            this.lastInferenceAt.set(agent.name, { ...this.lastInferenceAt.get(agent.name), endedAt: Date.now() });
             // Stop the typing indicator on every exit path (complete, error,
             // exhausted, abort) so it never sticks after the turn ends.
             this.channelRegistry?.stopTyping();
@@ -2884,7 +3382,10 @@ export class AgentFramework {
         if (blocks) {
             return { toolUseId: callId, content: blocks, isError: false };
         }
-        let content = JSON.stringify(afResult.data);
+        // JSON.stringify returns the VALUE undefined (not a string) for undefined
+        // input — a module tool returning `{ success: true }` with no data would
+        // otherwise make `content.length` below throw a TypeError mid-turn.
+        let content = JSON.stringify(afResult.data) ?? '';
         if (maxChars && content.length > maxChars) {
             content = safeSlice(content, 0, maxChars)
                 + '\n\n[truncated — original was ' + content.length + ' chars]';
@@ -2954,11 +3455,11 @@ export class AgentFramework {
                 entryToStore.response = { blobId };
             }
         }
-        // Append to the inference log state
-        const data = this.store.getStateJson(INFERENCE_LOG_ID);
-        const entries = Array.isArray(data) ? data : [];
-        entries.push(entryToStore);
-        this.store.setStateJson(INFERENCE_LOG_ID, entries);
+        // Append one record per inference. A read-modify-write via setStateJson
+        // would emit a whole-array Set — record size then grows with accumulated
+        // history (O(n²) aggregate disk) and the append_log strategy registered
+        // for this state never sees an append.
+        this.store.appendToStateJson(INFERENCE_LOG_ID, entryToStore);
     }
     logProcessEvent(event, responses) {
         const entry = {
@@ -2974,11 +3475,8 @@ export class AgentFramework {
             const blobId = this.store.storeBlob(Buffer.from(responsesJson), 'application/json');
             entryToStore.responses = { blobId };
         }
-        // Append to the process log state
-        const data = this.store.getStateJson(PROCESS_LOG_ID);
-        const entries = Array.isArray(data) ? data : [];
-        entries.push(entryToStore);
-        this.store.setStateJson(PROCESS_LOG_ID, entries);
+        // Append one record per event — same rationale as logInference.
+        this.store.appendToStateJson(PROCESS_LOG_ID, entryToStore);
     }
     /**
      * Find the MCPL server for a tool call by checking against the prefix map.
@@ -3175,15 +3673,19 @@ export class AgentFramework {
         // without this the only durable record of a failed inference is a field in
         // llm-calls.jsonl — invisible to operator, agent, and monitoring.
         if (event.type === 'inference:exhausted') {
-            this.noteInferenceExhausted(event.agentName ?? 'unknown', event.error ?? 'unknown error');
+            this.noteInferenceExhausted(event.agentName ?? 'unknown', event.error ?? 'unknown error', event.retryable, event.errorType);
         }
         else if (event.type === 'inference:completed') {
             // A successful response — even mid-turn between tool calls — proves the
-            // agent isn't hard-down; clear its consecutive-failure streak.
+            // agent isn't hard-down; clear its consecutive-failure streak (and the
+            // poison-history breaker's rewind budget).
             const name = event.agentName;
             if (name && this.consecutiveInferenceFailures.get(name)) {
                 this.consecutiveInferenceFailures.set(name, 0);
             }
+            if (name && this.exhaustionRewinds.get(name)) {
+                this.exhaustionRewinds.set(name, 0);
+            }
         }
         const traceEvent = {
             ...event,
@@ -3212,12 +3714,49 @@ export class AgentFramework {
      *      inference, so this never causes a retry/wake loop.
      *   3. escalation — after N consecutive failures the agent is hard-down;
      *      log that loudly (a repeated identical failure is the textbook signal).
+     *   4. breaker — when the failures are an `invalid_request` (a 400-class
+     *      rejection of the history itself, e.g. corrupted tool_use/tool_result
+     *      pairing or an oversized attachment), retrying the same context can
+     *      never succeed: every new push event wakes the agent onto the same
+     *      poisoned history forever. At the hard-down threshold, automatically
+     *      quarantine: shed the newest complete exchange (the same forced-rewind
+     *      primitive `/unstick` uses — shedNewestTurn never orphans a
+     *      tool_use/thinking block) and retry, bounded by the same rewind cap so
+     *      the breaker can never eat the whole history.
+     */
+    /**
+     * Live health snapshot for /healthz and doctor tooling: gate state, queued
+     * work, per-agent status + last inference activity. Cheap and read-only.
      */
-    noteInferenceExhausted(agentName, reason) {
+    healthSnapshot() {
+        return {
+            at: new Date().toISOString(),
+            uptimeSec: Math.round(process.uptime()),
+            gate: this.eventGate?.inferenceDiagnostics() ?? null,
+            pendingRequests: this.pendingRequests.length,
+            activeStreams: [...this.activeStreams.keys()],
+            agents: [...this.agents.entries()].map(([name, agent]) => ({
+                name,
+                status: agent.state.status,
+                consecutiveInferenceFailures: this.consecutiveInferenceFailures.get(name) ?? 0,
+                lastInference: this.lastInferenceAt.get(name) ?? null,
+            })),
+        };
+    }
+    noteInferenceExhausted(agentName, reason, retryable, errorType) {
         const streak = (this.consecutiveInferenceFailures.get(agentName) ?? 0) + 1;
         this.consecutiveInferenceFailures.set(agentName, streak);
+        this.lastInferenceAt.set(agentName, { ...this.lastInferenceAt.get(agentName), failedAt: Date.now(), lastError: reason.slice(0, 300) });
         // (1) Durable stderr line — works in headless/daemon mode with no client.
         console.error(`[inference-failed] agent=${agentName} consecutive=${streak}: ${reason}`);
+        // (1b) Machine-greppable durable record, independent of journald/unit log
+        // redirects: logs/failures.log under the host's working directory. This is
+        // what connectome-doctor reads.
+        try {
+            mkdirSync('logs', { recursive: true });
+            appendFileSync('logs/failures.log', JSON.stringify({ at: new Date().toISOString(), agent: agentName, consecutive: streak, reason }) + '\n');
+        }
+        catch { /* best-effort */ }
         // (2) Agent-facing chronicle marker (no inference triggered → no loop).
         const agent = this.agents.get(agentName);
         if (agent && process.env.SUPPRESS_INFERENCE_FAILED_MARKER !== '1') {
@@ -3239,8 +3778,71 @@ export class AgentFramework {
         if (streak >= this.inferenceFailureEscalationThreshold) {
             console.error(`[inference-hard-down] agent=${agentName} has FAILED ${streak} consecutive ` +
                 `inferences — it cannot complete a turn. Last reason: ${reason}`);
+            // Optional ops alert: set CONNECTOME_OPS_WEBHOOK to a Discord webhook URL.
+            const hook = process.env.CONNECTOME_OPS_WEBHOOK;
+            if (hook) {
+                fetch(hook, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({
+                        content: `\u{1F6A8} **${agentName}** hard-down: ${streak} consecutive inference failures.\nLast reason: ${reason.slice(0, 500)}`,
+                    }),
+                }).catch((err) => console.error('[inference-hard-down] webhook post failed:', err instanceof Error ? err.message : err));
+            }
+            // (4) Poison-history breaker: ONLY for `invalid_request` — a 400-class
+            // rejection of the history itself. Deliberately NOT keyed on
+            // `retryable === false`, which membrane also returns for auth (expired
+            // key), abort (deliberate cancel), context_length (compression's job,
+            // and shedding newest is the wrong direction), safety and unsupported —
+            // none of which mean the history is poisoned, and all of which would
+            // otherwise shed good exchanges and stamp a false "the API kept
+            // rejecting your history" marker. `retryable` is kept only for the trace.
+            void retryable;
+            if (errorType === 'invalid_request' && agent) {
+                this.quarantinePoisonedHistory(agent, reason);
+            }
         }
     }
+    /**
+     * Automatic poison-history quarantine (the actual "breaker"). Sheds the
+     * newest complete exchange from the agent's history — reusing the same
+     * primitives as the refusal auto-rewind / `/unstick` (shedNewestTurn +
+     * the single consolidated episode marker) — and queues a retry so the
+     * rewound history is verified immediately instead of waiting for the next
+     * push event to wake the agent onto the same poisoned context.
+     *
+     * Bounded: at most `refusalHandling.maxRewinds` (default 3, hard cap 10)
+     * sheds per failure episode; the budget resets on any successful inference.
+     * At the cap (or with nothing left to shed) it stops — the agent stays up
+     * and hard-down logging continues, but no further history is consumed.
+     */
+    quarantinePoisonedHistory(agent, reason) {
+        const cap = Math.max(1, Math.min(10, agent.refusalHandling?.maxRewinds ?? 3));
+        const used = this.exhaustionRewinds.get(agent.name) ?? 0;
+        if (used >= cap) {
+            console.error(`[inference-rewind] agent=${agent.name} rewind cap ${cap} reached — ` +
+                `not shedding further history. Manual repair (/unstick or /undo) needed.`);
+            return;
+        }
+        const rec = this.shedNewestTurn(agent);
+        if (!rec) {
+            console.error(`[inference-rewind] agent=${agent.name} has nothing left to shed — ` +
+                `history is only system markers. Manual repair needed.`);
+            return;
+        }
+        this.exhaustionRewinds.set(agent.name, used + 1);
+        const count = this.updateRewindMarker(agent, truncateReason(reason), 'inference-failure');
+        console.error(`[inference-rewind] agent=${agent.name} auto-quarantined ${rec.descriptor} ` +
+            `(${count} turn(s) shed this episode, cap ${cap}) after non-retryable ` +
+            `inference failures — retrying on the rewound history.`);
+        // Retry immediately on the repaired history (bounded by the cap above).
+        this.pendingRequests.push({
+            agentName: agent.name,
+            reason: 'inference-failure-rewind-retry',
+            source: 'framework',
+            timestamp: Date.now(),
+        });
+    }
     // ==========================================================================
     // MCPL subsystem wiring
     // ==========================================================================
@@ -3314,8 +3916,9 @@ export class AgentFramework {
                 }
             },
         });
-        // Host capabilities advertised during the MCP handshake
-        const hostCapabilities = {
+        // Host capabilities advertised during the MCP handshake — stored so
+        // servers can also be connected later at runtime (connectMcplServer).
+        this.mcplHostCapabilities = {
             version: '0.4',
             pushEvents: true,
             contextHooks: {
@@ -3326,56 +3929,193 @@ export class AgentFramework {
         };
         for (const config of serverConfigs) {
             try {
-                // Record per-server channel subscription policy before the server
-                // registers channels — handleRegister fires during the handshake.
-                if (config.channelSubscription !== undefined && this.channelRegistry) {
-                    this.channelRegistry.setSubscriptionPolicy(config.id, config.channelSubscription);
-                }
-                const connection = await this.mcplServerRegistry.addServer(config, hostCapabilities);
-                // Wire event listeners then flush any events that arrived during the
-                // handshake window (between setupMessageRouting and now).
-                this.wireMcplEvents(connection);
-                connection.ready();
-                // Initialize feature sets if server advertises MCPL capabilities
-                if (connection.capabilities) {
-                    const updateParams = this.featureSetManager.initializeServer(config.id, connection.capabilities, {
-                        enabledFeatureSets: config.enabledFeatureSets,
-                        disabledFeatureSets: config.disabledFeatureSets,
-                    });
-                    // Inform server which feature sets are enabled/disabled
-                    if (updateParams.enabled?.length || updateParams.disabled?.length) {
-                        connection.sendFeatureSetsUpdate(updateParams);
-                    }
-                    // Configure scope whitelist/blacklist patterns
-                    if (config.scopes) {
-                        this.scopeManager.configureAll(config.scopes);
-                    }
-                    // Register stateful feature sets with checkpoint manager (Step 8)
-                    if (this.checkpointManager) {
-                        const declared = this.featureSetManager.getDeclaredFeatureSets(config.id);
-                        if (declared) {
-                            for (const [fsName, fsDecl] of Object.entries(declared)) {
-                                if (fsDecl.rollback || fsDecl.hostState) {
-                                    this.checkpointManager.registerFeatureSet(config.id, fsName, {
-                                        hostState: fsDecl.hostState ?? false,
-                                        rollback: fsDecl.rollback ?? false,
-                                    });
-                                }
-                            }
-                        }
-                    }
-                }
-                this.emitTrace({ type: 'module:added', moduleName: `mcpl:${config.id}` });
+                await this.connectMcplServerInternal(config);
             }
             catch (error) {
                 // Fail-open: log and continue with remaining servers
                 const err = error instanceof Error ? error : new Error(String(error));
                 console.error(`Failed to connect MCPL server "${config.id}":`, err.message);
+                // Reaching this catch means no stub was created, so nothing will
+                // retry — except in the edge case where addServer succeeded (with a
+                // reconnecting stub) and a later setup step threw; config.reconnect
+                // is the best cheap approximation of that.
+                this.emitTrace({
+                    type: 'mcpl:server-connect-failed',
+                    serverId: config.id,
+                    error: err.message,
+                    attempt: 0,
+                    willRetry: config.reconnect === true,
+                });
             }
         }
         // Discover tools from all connected servers
         await this.refreshMcplTools();
     }
+    /**
+     * Connect a single MCPL server: register routing entries, open the
+     * connection, wire events, and initialize feature sets / scopes /
+     * checkpoints. Shared by startup (initializeMcpl) and the runtime
+     * lifecycle API (connectMcplServer). Throws on connection failure.
+     */
+    async connectMcplServerInternal(config) {
+        if (!this.mcplServerRegistry || !this.mcplHostCapabilities) {
+            throw new Error('MCPL subsystem is not initialized');
+        }
+        // Register prefix + config for tool dispatch routing (idempotent with
+        // the pre-registration pass in initializeMcpl).
+        const prefix = config.toolPrefix ?? `mcpl--${config.id}`;
+        this.mcplPrefixMap.set(prefix, config.id);
+        this.mcplServerConfigs.set(config.id, config);
+        // Record per-server channel subscription policy before the server
+        // registers channels — handleRegister fires during the handshake.
+        if (config.channelSubscription !== undefined && this.channelRegistry) {
+            this.channelRegistry.setSubscriptionPolicy(config.id, config.channelSubscription);
+        }
+        const connection = await this.mcplServerRegistry.addServer(config, this.mcplHostCapabilities);
+        // Wire event listeners then flush any events that arrived during the
+        // handshake window (between setupMessageRouting and now).
+        this.wireMcplEvents(connection);
+        connection.ready();
+        // Initialize feature sets if server advertises MCPL capabilities
+        this.registerMcplServerFeatures(config, connection);
+        this.emitTrace({ type: 'module:added', moduleName: `mcpl:${config.id}` });
+    }
+    /**
+     * (Re-)establish a server's host-side MCPL registration: feature-set state
+     * (plus the featureSets/update sent to the server), scope patterns, and
+     * stateful-feature-set checkpoint registration.
+     *
+     * Called on initial connect (connectMcplServerInternal) AND after every
+     * auto-reconnect. The 'close' handler drops the feature-set registration, so
+     * without the reconnect re-run FeatureSetManager.validateInbound would throw
+     * "Unknown server" forever — every push event and inference request from the
+     * revived server silently rejected until a full host restart.
+     *
+     * CheckpointManager.registerFeatureSet is idempotent (no-op for a key that
+     * already has a tree), so checkpoint trees preserved across a transient
+     * disconnect are resumed, not reset.
+     */
+    registerMcplServerFeatures(config, connection) {
+        if (!connection.capabilities)
+            return;
+        const updateParams = this.featureSetManager.initializeServer(config.id, connection.capabilities, {
+            enabledFeatureSets: config.enabledFeatureSets,
+            disabledFeatureSets: config.disabledFeatureSets,
+        });
+        // Inform server which feature sets are enabled/disabled
+        if (updateParams.enabled?.length || updateParams.disabled?.length) {
+            connection.sendFeatureSetsUpdate(updateParams);
+        }
+        // Configure scope whitelist/blacklist patterns
+        if (config.scopes) {
+            this.scopeManager.configureAll(config.scopes);
+        }
+        // Register stateful feature sets with checkpoint manager (Step 8)
+        if (this.checkpointManager) {
+            const declared = this.featureSetManager.getDeclaredFeatureSets(config.id);
+            if (declared) {
+                for (const [fsName, fsDecl] of Object.entries(declared)) {
+                    if (fsDecl.rollback || fsDecl.hostState) {
+                        this.checkpointManager.registerFeatureSet(config.id, fsName, {
+                            hostState: fsDecl.hostState ?? false,
+                            rollback: fsDecl.rollback ?? false,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // ==========================================================================
+    // Runtime MCPL server lifecycle (agent-facing hot deploy/restart/unload)
+    // ==========================================================================
+    /**
+     * Connect a new MCPL server at runtime. Refreshes the tool list and
+     * notifies the agent of newly available tools. Throws if the MCPL
+     * subsystem is not initialized, the id is already connected, or the
+     * connection/handshake fails.
+     */
+    async connectMcplServer(config) {
+        // Lazily bring up the MCPL subsystem — a framework that started with zero
+        // configured servers can still deploy its first one at runtime.
+        if (!this.mcplServerRegistry || !this.mcplHostCapabilities) {
+            await this.initializeMcpl([], this.mcplInferenceRoutingConfig ?? undefined);
+        }
+        // Same collision rules create() enforces at startup: the tool prefix must
+        // not shadow a module name or another server's prefix.
+        const prefix = config.toolPrefix ?? `mcpl--${config.id}`;
+        if (this.moduleRegistry.getAllModules().some(m => m.name === prefix)) {
+            throw new Error(`MCPL server "${config.id}" toolPrefix "${prefix}" collides with module "${prefix}"`);
+        }
+        const prefixOwner = this.mcplPrefixMap.get(prefix);
+        if (prefixOwner && prefixOwner !== config.id) {
+            throw new Error(`MCPL server "${config.id}" toolPrefix "${prefix}" collides with server "${prefixOwner}"`);
+        }
+        const oldToolNames = new Set(this.mcplTools.map(t => t.name));
+        await this.connectMcplServerInternal(config);
+        await this.refreshMcplTools();
+        this.emitMcplToolDiff(oldToolNames, config.id);
+    }
+    /**
+     * Disconnect an MCPL server at runtime: close the connection, destroy its
+     * feature-set and checkpoint state (permanent removal — unlike a transient
+     * transport close, which preserves checkpoints for the reconnect), remove
+     * its channels from the registry, drop routing entries, and refresh tools.
+     * No-op-ish if the server is not connected (still clears routing state).
+     */
+    async disconnectMcplServer(id) {
+        if (!this.mcplServerRegistry) {
+            throw new Error('MCPL subsystem is not initialized');
+        }
+        const config = this.mcplServerConfigs.get(id);
+        const oldToolNames = new Set(this.mcplTools.map(t => t.name));
+        await this.mcplServerRegistry.removeServer(id);
+        this.channelRegistry?.removeServer(id);
+        // Permanent removal: also destroy feature-set and checkpoint state
+        // explicitly. The 'close' handler usually does this, but a connection that
+        // already transiently closed (reconnect pending) emits no second 'close'
+        // from close(), and the transient path deliberately preserves checkpoints.
+        this.featureSetManager?.removeServer(id);
+        this.checkpointManager?.removeServer(id);
+        const prefix = config?.toolPrefix ?? `mcpl--${id}`;
+        this.mcplPrefixMap.delete(prefix);
+        this.mcplServerConfigs.delete(id);
+        await this.refreshMcplTools();
+        this.emitMcplToolDiff(oldToolNames, id);
+    }
+    /**
+     * Restart an MCPL server at runtime: disconnect, then reconnect with the
+     * same (or an updated) config. This actually respawns a stdio child —
+     * unlike `reconnect: true`, which only retries after transport-level
+     * failures. Throws if the server has no stored config and none is given.
+     */
+    async restartMcplServer(id, newConfig) {
+        const config = newConfig ?? this.mcplServerConfigs.get(id);
+        if (!config) {
+            throw new Error(`MCPL server "${id}" is not configured`);
+        }
+        await this.disconnectMcplServer(id);
+        await this.connectMcplServer(config);
+    }
+    /**
+     * List configured MCPL servers with live connection status and the number
+     * of tools each currently contributes.
+     */
+    listMcplServers() {
+        const result = [];
+        for (const [id, config] of this.mcplServerConfigs) {
+            const prefix = config.toolPrefix ?? `mcpl--${id}`;
+            const connection = this.mcplServerRegistry?.getServer(id) ?? null;
+            result.push({
+                id,
+                connected: connection?.isConnected ?? false,
+                toolPrefix: prefix,
+                toolCount: this.mcplTools.filter(t => t.name.startsWith(`${prefix}--`)).length,
+                command: config.command,
+                url: config.url,
+            });
+        }
+        return result;
+    }
     /**
      * Wire event listeners on an MCPL server connection.
      * Push events and inference requests are deferred to Steps 6/7.
@@ -3446,14 +4186,95 @@ export class AgentFramework {
         connection.on('tools-list-changed', () => {
             this.handleToolsListChanged(connection.id);
         });
-        // Also refresh tools on reconnect (server may have different tools)
-        connection.on('reconnect', () => {
+        // Re-establish full server registration on reconnect. The 'close' handler
+        // removed the feature-set state, so pushes / inference requests from the
+        // revived server would otherwise be rejected with "Unknown server" until a
+        // host restart. Re-runs the same init as the initial connect path (the
+        // fresh handshake refreshed connection.capabilities); checkpoint trees
+        // preserved across the transient close are resumed by idempotent
+        // registration. Then refresh tools (server may have different tools).
+        connection.on('reconnect', (info) => {
+            try {
+                const config = this.mcplServerConfigs.get(connection.id);
+                if (config) {
+                    this.registerMcplServerFeatures(config, connection);
+                }
+            }
+            catch (error) {
+                console.error(`MCPL server "${connection.id}" re-registration after reconnect failed:`, error instanceof Error ? error.message : error);
+            }
             this.handleToolsListChanged(connection.id);
+            this.emitTrace({
+                type: 'mcpl:server-reconnected',
+                serverId: connection.id,
+                attempts: info?.attempts ?? 0,
+            });
+            // Mirror the module:removed emitted on 'close' so module-lifecycle
+            // consumers see the server come back, not just vanish.
+            this.emitTrace({ type: 'module:added', moduleName: `mcpl:${connection.id}` });
         });
-        // Cleanup on disconnect
-        connection.on('close', () => {
+        // Surface connect/reconnect failures. Before these traces existed the
+        // only receipt was a console.error on the host's own stderr — invisible
+        // unless someone ssh'd in and read the process log.
+        connection.on('connect-failed', (params) => {
+            this.emitTrace({
+                type: 'mcpl:server-connect-failed',
+                serverId: connection.id,
+                error: params.error,
+                attempt: params.attempt,
+                willRetry: connection.willReconnect,
+            });
+        });
+        connection.on('reconnect-failed', (params) => {
+            this.emitTrace({
+                type: 'mcpl:server-connect-failed',
+                serverId: connection.id,
+                error: params.error,
+                attempt: params.attempt,
+                willRetry: connection.willReconnect,
+            });
+        });
+        // A late response to a tools/call that already timed out, carrying
+        // stateful data the server advanced to. The host can't re-inject it (the
+        // dispatch context is gone), but surfacing it makes the checkpoint-tree
+        // divergence greppable instead of a silent drift into stale state.
+        connection.on('orphaned-response', (info) => {
+            this.emitTrace({
+                type: 'mcpl:orphaned-response',
+                serverId: connection.id,
+                responseId: info.id,
+                hadState: info.hadState,
+                hadCheckpoint: info.hadCheckpoint,
+            });
+        });
+        // Connection-level errors (e.g. child process 'error' after spawn).
+        // Attaching this listener also keeps an unhandled EventEmitter 'error'
+        // from crashing the host process.
+        connection.on('error', (err) => {
+            this.emitTrace({
+                type: 'mcpl:server-error',
+                serverId: connection.id,
+                error: err.message,
+            });
+        });
+        // Cleanup on disconnect. Feature-set state is always dropped (the server
+        // can't be validated while down; reconnect re-registers it). Checkpoint
+        // trees, however, are durable state: CheckpointManager.removeServer deletes
+        // them AND persists the deletion to Chronicle. The close handler must
+        // therefore NEVER destroy checkpoints — `willReconnect` is false on a clean
+        // stop() too (reconnectEnabled is cleared before 'close' fires), so gating
+        // on it would erase every checkpoint tree on an ordinary host restart while
+        // a SIGKILL preserves them. Permanent removal is owned solely by
+        // disconnectMcplServer, which deletes the trees explicitly.
+        connection.on('close', (code, signal) => {
             this.featureSetManager?.removeServer(connection.id);
-            this.checkpointManager?.removeServer(connection.id);
+            this.emitTrace({
+                type: 'mcpl:server-closed',
+                serverId: connection.id,
+                code: code ?? null,
+                signal: signal ?? null,
+                willReconnect: connection.willReconnect,
+            });
             this.emitTrace({ type: 'module:removed', moduleName: `mcpl:${connection.id}` });
         });
     }
@@ -3822,7 +4643,7 @@ export class AgentFramework {
             finish({ success: false, error: 'sleep: `seconds` must be a positive number', isError: true });
             return;
         }
-        const { until } = gate.setSleep(seconds, input.message);
+        const { until } = gate.setSleep(seconds, input.message, agentName);
         const announce = input.announce !== false; // default true
         const human = seconds >= 3600 ? `${(seconds / 3600).toFixed(1)}h`
             : seconds >= 60 ? `${Math.round(seconds / 60)}m`