@animalabs/agent-framework 0.6.0 → 0.6.2

package/src/framework.ts

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { appendFileSync, mkdirSync } from 'node:fs';
 import { JsStore } from '@animalabs/chronicle';
 import type { Membrane, ContentBlock, NormalizedRequest, YieldingStream, ToolResult as MembraneToolResult, ToolResultContentBlock } from '@animalabs/membrane';
 import { MembraneError } from '@animalabs/membrane';
@@ -42,7 +43,7 @@ import type {
 } from './types/index.js';
 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';
@@ -80,7 +81,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;
@@ -198,10 +200,34 @@ interface HostCommandParams {
   fromMessageId?: string;
   /** For the `hide` command: Discord message id ending an inclusive range. */
   toMessageId?: string;
+  /** For the `unstick` command: max rewind/retry attempts (default = the
+   *  agent's refusalHandling.maxRewinds, else 3). */
+  maxRewinds?: number;
+  /** For the `unstick` command: raw channel id to post the outcome report to. */
+  channelId?: string;
   requesterId?: string;
   requesterName?: string;
 }
 
+/** Descriptor of a single refusal-driven rewind (see rewindTriggeringTurn). */
+interface RewindRecord {
+  /** tool = machine tool exchange; human = an ingested message; other = else. */
+  kind: 'tool' | 'human' | 'other';
+  /** Content-free, safe-to-replay description of what was withheld. */
+  descriptor: string;
+  /** All message ids removed in this shed (a tool exchange removes 2+). */
+  removedIds: MessageId[];
+  /** Discord (channelId, messageId) of the removed message, if it had one. */
+  discordRef?: { channelId: string; messageId: string };
+}
+
+/** 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: string, max = 160): string {
+  return reason.length <= max ? reason : reason.slice(0, max) + '…';
+}
+
 export class AgentFramework {
   private store: JsStore;
   private ownsStore: boolean;
@@ -227,6 +253,10 @@ export class AgentFramework {
   private traceListeners: TraceEventListener[] = [];
   private syncIntervalMs: number;
   private syncTimer: ReturnType<typeof setInterval> | null = null;
+  /** Last time we console-warned about stale (busy-requeued) inference requests, per agent. */
+  private staleWarnAt = new Map<string, number>();
+  /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
+  private lastInferenceAt = new Map<string, { startedAt?: number; endedAt?: number; failedAt?: number; lastError?: string }>();
   private processLoggingPersist: boolean;
   private processLoggingBroadcast: boolean;
   private activeStreams: Map<string, Promise<void>> = new Map();
@@ -237,6 +267,28 @@ export class AgentFramework {
   /** N consecutive failed inferences ⇒ the agent is treated as hard-down and
    *  escalated loudly to stderr. */
   private readonly 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. */
+  private refusalRewinds: Map<string, number> = 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. */
+  private exhaustionRewinds: Map<string, number> = 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. */
+  private rewindEpisode: Map<string, { markerId: MessageId; count: number; category: string }> = 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. */
+  private forcedRewind: Map<string, {
+    remaining: number;
+    removed: RewindRecord[];
+    serverId: string;
+    channelId: string;
+  }> = new Map();
   /** Name of the primary (non-ephemeral) agent for routing framework messages. */
   private primaryAgentName: string | null = null;
 
@@ -283,6 +335,13 @@ export class AgentFramework {
   private mcplPrefixMap: Map<string, string> = new Map();
   /** Maps serverId → McplServerConfig for prefix lookup. */
   private mcplServerConfigs: Map<string, import('./mcpl/types.js').McplServerConfig> = new Map();
+  /** Host capabilities advertised during the MCP handshake — stored so servers
+   *  can be connected at runtime (connectMcplServer) after initialization. */
+  private mcplHostCapabilities: McplHostCapabilities | null = 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. */
+  private mcplInferenceRoutingConfig: import('./mcpl/types.js').InferenceRoutingPolicy | null = null;
 
   // EventGate (null when FrameworkConfig.gate is omitted)
   private eventGate: EventGate | null = null;
@@ -363,10 +422,12 @@ export class AgentFramework {
       // 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' });
-    } catch {
-      // Already registered
+      store.registerState({ id: TURN_CHECKPOINTS_TREE_ID, strategy: 'tree' });
+    } catch (error) {
+      if (!isStateExistsError(error)) throw error;
     }
 
     // Process logging config (default: disabled)
@@ -472,6 +533,10 @@ 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
@@ -496,6 +561,31 @@ 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;
   }
 
@@ -749,8 +839,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) {
       console.error('Module gatherContext error (preview):', error);
@@ -761,7 +852,10 @@ 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;
         }
@@ -951,6 +1045,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.
@@ -1309,6 +1404,194 @@ export class AgentFramework {
     }
   }
 
+  /**
+   * 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.
+   */
+  private shedNewestTurn(agent: Agent): RewindRecord | null {
+    const cm = agent.getContextManager();
+    const all = cm.getAllMessages();
+    const typeOf = (b: unknown) => (b as { type?: string }).type;
+    const hasBlock = (m: { content?: unknown } | undefined, t: string) =>
+      Array.isArray(m?.content) && (m!.content as unknown[]).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 ?? {}) as { system?: unknown };
+      if (meta.system) continue;
+      idx = i; break;
+    }
+    if (idx < 0) return null;
+    const msg = all[idx];
+    const md = (msg.metadata ?? {}) as {
+      messageId?: unknown; channelId?: unknown; system?: unknown;
+    };
+
+    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 as { text?: string }).text ?? '').length, 0);
+
+    // Determine the complete exchange to remove.
+    const removedIds: MessageId[] = [msg.id];
+    let kind: RewindRecord['kind'];
+    let descriptor: string;
+    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 as { content?: unknown }).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.
+   */
+  private updateRewindMarker(
+    agent: Agent,
+    category: string,
+    cause: 'refusal' | 'inference-failure' = 'refusal',
+  ): number {
+    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: ContentBlock[] = [{ 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.
+   */
+  private async announceRewind(
+    agentName: string,
+    rec: RewindRecord,
+    category: string,
+  ): Promise<void> {
+    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.
+   */
+  private finishUnstick(agentName: string, success: boolean, category?: string): void {
+    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. */
+  private async postToChannel(serverId: string, channelId: string, content: string): Promise<void> {
+    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:
@@ -1332,8 +1615,12 @@ export class AgentFramework {
      *  that carried one — so the surface can mark them with a reaction. */
     hiddenRefs?: Array<{ channelId: string; messageId: string }>;
     lastVisible?: { participant?: string; role?: string; preview?: string } | null;
+    /** For `unstick`: acknowledges the forced-rewind loop has started; the
+     *  outcome report is posted to the channel asynchronously. */
+    started?: boolean;
+    cap?: number;
   }> {
-    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)}` };
     }
 
@@ -1342,6 +1629,38 @@ export class AgentFramework {
       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.
@@ -1959,18 +2278,91 @@ 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.
+   */
+  private legacyCheckpointKeys: Set<string> | null = null;
+
+  private hasLegacyCheckpoints(agentName: string): boolean {
+    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);
+  }
+
   private getTurnCheckpoints(agentName: string): TurnCheckpoint[] {
-    const data = this.store.getStateJson(TURN_CHECKPOINTS_ID);
-    if (!data || typeof data !== 'object') return [];
-    const allCheckpoints = data as Record<string, TurnCheckpoint[]>;
-    return Array.isArray(allCheckpoints[agentName]) ? [...allCheckpoints[agentName]] : [];
+    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 legacy = this.store.getStateJson(TURN_CHECKPOINTS_ID) as
+      | Record<string, TurnCheckpoint[]>
+      | null;
+    const list = legacy?.[agentName];
+    return Array.isArray(list) ? [...list] : [];
   }
 
   private saveTurnCheckpoints(agentName: string, checkpoints: TurnCheckpoint[]): void {
-    const data = this.store.getStateJson(TURN_CHECKPOINTS_ID);
-    const allCheckpoints = (data && typeof data === 'object' ? data : {}) as Record<string, TurnCheckpoint[]>;
-    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.
+   */
+  private evictTurnCheckpoints(agentName: string): void {
+    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);
+    }
   }
 
   /**
@@ -1980,6 +2372,9 @@ export class AgentFramework {
   async runUntilIdle(): Promise<void> {
     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')
     ) {
@@ -2512,6 +2907,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,
@@ -2718,6 +3114,7 @@ export class AgentFramework {
           requestCount: requests.length,
           oldestRequestAge: now - oldest,
         });
+        console.error(`[inference-dropped] agent=${agentName} reason=agent_not_found requests=${requests.length}`);
         continue;
       }
 
@@ -2733,6 +3130,14 @@ 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;
@@ -2740,6 +3145,13 @@ export class AgentFramework {
 
       // 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;
       }
 
@@ -2782,6 +3194,7 @@ 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();
@@ -2791,14 +3204,16 @@ export class AgentFramework {
       // Both produce ContextInjection[] that get merged before inference.
       let injections: ContextInjection[] | undefined;
 
-      // 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;
         }
@@ -2845,6 +3260,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) {
@@ -3121,7 +3543,84 @@ export class AgentFramework {
                 `[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: boolean,
+                onStep: (count: number) => void,
+                onGiveUp: () => void,
+              ): void => {
+                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)
@@ -3212,13 +3711,21 @@ export class AgentFramework {
                   `(${silenced ? 'silencing tool / explicit send' : 'no prose'})`,
                 );
               } else {
+                // 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`,
+                  `[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);
                   }
@@ -3267,6 +3774,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) {
@@ -3281,19 +3794,58 @@ 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 as unknown as {
+                getContextManager?: () => { getStrategy?: () => unknown };
+              }).getContextManager?.()?.getStrategy?.() as
+                | { reportRealInputTokens?: (n: number) => void }
+                | undefined;
+              strat?.reportRealInputTokens?.(realTotal);
+            } catch { /* calibration is best-effort */ }
+
             this.emitTrace({
               type: 'inference:usage',
               agentName: agent.name,
@@ -3305,12 +3857,14 @@ export class AgentFramework {
               },
             });
             break;
+          }
         }
       }
     } catch (error) {
       // 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,
@@ -3322,9 +3876,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();
@@ -3414,7 +3990,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]';
@@ -3486,11 +4065,11 @@ export class AgentFramework {
       }
     }
 
-    // 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);
   }
 
   private logProcessEvent(event: ProcessEvent, responses: ModuleProcessResponse[]): void {
@@ -3510,11 +4089,8 @@ export class AgentFramework {
       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);
   }
 
   /**
@@ -3744,14 +4320,20 @@ export class AgentFramework {
       this.noteInferenceExhausted(
         (event.agentName as string) ?? 'unknown',
         (event.error as string) ?? 'unknown error',
+        event.retryable as boolean | undefined,
+        event.errorType as string | undefined,
       );
     } 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 as string | undefined;
       if (name && this.consecutiveInferenceFailures.get(name)) {
         this.consecutiveInferenceFailures.set(name, 0);
       }
+      if (name && this.exhaustionRewinds.get(name)) {
+        this.exhaustionRewinds.set(name, 0);
+      }
     }
 
     const traceEvent = {
@@ -3782,14 +4364,60 @@ 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.
    */
-  private noteInferenceExhausted(agentName: string, reason: string): void {
+  healthSnapshot(): Record<string, unknown> {
+    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,
+      })),
+    };
+  }
+
+  private noteInferenceExhausted(
+    agentName: string,
+    reason: string,
+    retryable?: boolean,
+    errorType?: string,
+  ): void {
     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') {
@@ -3818,9 +4446,84 @@ export class AgentFramework {
         `[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.
+   */
+  private quarantinePoisonedHistory(agent: Agent, reason: string): void {
+    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
   // ==========================================================================
@@ -3930,8 +4633,9 @@ export class AgentFramework {
       },
     );
 
-    // Host capabilities advertised during the MCP handshake
-    const hostCapabilities: McplHostCapabilities = {
+    // 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: {
@@ -3943,66 +4647,242 @@ 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);
-        }
+        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,
+        });
+      }
+    }
 
-        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,
-            },
-          );
+    // Discover tools from all connected servers
+    await this.refreshMcplTools();
+  }
 
-          // Inform server which feature sets are enabled/disabled
-          if (updateParams.enabled?.length || updateParams.disabled?.length) {
-            connection.sendFeatureSetsUpdate(updateParams);
-          }
+  /**
+   * 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.
+   */
+  private async connectMcplServerInternal(
+    config: import('./mcpl/types.js').McplServerConfig,
+  ): Promise<void> {
+    if (!this.mcplServerRegistry || !this.mcplHostCapabilities) {
+      throw new Error('MCPL subsystem is not initialized');
+    }
 
-          // Configure scope whitelist/blacklist patterns
-          if (config.scopes) {
-            this.scopeManager.configureAll(config.scopes);
-          }
+    // 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);
 
-          // 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,
-                  });
-                }
-              }
-            }
+    // 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.
+   */
+  private registerMcplServerFeatures(
+    config: import('./mcpl/types.js').McplServerConfig,
+    connection: McplServerConnection,
+  ): void {
+    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,
+            });
           }
         }
-
-        this.emitTrace({ type: 'module:added', moduleName: `mcpl:${config.id}` });
-      } 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);
       }
     }
+  }
+
+  // ==========================================================================
+  // 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: import('./mcpl/types.js').McplServerConfig,
+  ): Promise<void> {
+    // 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: string): Promise<void> {
+    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);
 
-    // Discover tools from all connected servers
     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: string,
+    newConfig?: import('./mcpl/types.js').McplServerConfig,
+  ): Promise<void> {
+    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(): Array<{
+    id: string;
+    connected: boolean;
+    toolPrefix: string;
+    toolCount: number;
+    command?: string;
+    url?: string;
+  }> {
+    const result: Array<{
+      id: string; connected: boolean; toolPrefix: string; toolCount: number;
+      command?: string; url?: string;
+    }> = [];
+    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;
   }
 
   /**
@@ -4100,15 +4980,105 @@ export class AgentFramework {
       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?: { attempts?: number }) => {
+      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: { error: string; attempt: number }) => {
+      this.emitTrace({
+        type: 'mcpl:server-connect-failed',
+        serverId: connection.id,
+        error: params.error,
+        attempt: params.attempt,
+        willRetry: connection.willReconnect,
+      });
+    });
+    connection.on('reconnect-failed', (params: { error: string; attempt: number }) => {
+      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: {
+      id: string | number;
+      hadState: boolean;
+      hadCheckpoint: boolean;
+    }) => {
+      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: Error) => {
+      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?: number | null, signal?: string | null) => {
       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}` });
     });
   }
@@ -4507,7 +5477,7 @@ export class AgentFramework {
       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`