@animalabs/agent-framework 0.5.7 → 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';
@@ -53,6 +54,7 @@ import { ChannelRegistry } from './mcpl/channel-registry.js';
 import { ConversationRouter } from './mcpl/conversation-router.js';
 import { safeSlice } from './safe-slice.js';
 import { toolResultDataToHistoryString } from './tool-result-history.js';
+import { splitProseSegments } from './prose-segments.js';
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
 import { EventGate } from './gate/event-gate.js';
@@ -79,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;
@@ -197,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;
@@ -211,11 +238,25 @@ export class AgentFramework {
   private inferencePolicy: InferencePolicy;
   private errorPolicy: ErrorPolicy;
   private pendingRequests: InferenceRequest[] = [];
+  /**
+   * Per-agent channel that triggered the agent's CURRENT inference turn, if any
+   * (item-3 redux). Read by the ChannelRegistry's `activeChannelResolver` to
+   * route a single-trunk agent's plain-text speech back to the channel it is
+   * answering, instead of the process-global most-recent-inbound locus that a
+   * concurrent message elsewhere can hijack. Set at turn start (or cleared for a
+   * heartbeat / no-trigger turn) in startAgentStream; overwritten by the next
+   * turn. Never read between turns (a given agent runs one turn at a time).
+   */
+  private activeTriggerChannels: Map<string, string> = new Map();
   private running = false;
   private loopPromise: Promise<void> | null = null;
   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();
@@ -226,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;
 
@@ -237,6 +300,9 @@ export class AgentFramework {
   private turnCounters: Map<string, number> = new Map(); // agentName → next turnIndex
   private redoStacks: Map<string, RedoEntry[]> = new Map(); // agentName → redo entries
 
+  /** Liveness watchdog (fail hard on a wedged main thread). Null unless enabled. */
+  private livenessWatchdog: import('./runtime/liveness-watchdog.js').LivenessWatchdog | null = null;
+
   // MCPL subsystems (null when no mcplServers configured)
   private mcplServerRegistry: McplServerRegistry | null = null;
   private featureSetManager: FeatureSetManager | null = null;
@@ -269,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;
@@ -309,6 +382,7 @@ export class AgentFramework {
       queryMessages: (filter) => this.queryMessages(filter),
       pushEvent: (event) => this.pushEvent(event),
       onTrace: (listener) => this.onTrace(listener),
+      callTool: (call) => this.executeToolCall(call),
     });
   }
 
@@ -348,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)
@@ -444,6 +520,23 @@ export class AgentFramework {
       });
     }
 
+    // Liveness watchdog: fail hard if the main thread wedges (opt-in).
+    if (config.watchdog?.enabled) {
+      const { LivenessWatchdog } = await import('./runtime/liveness-watchdog.js');
+      framework.livenessWatchdog = new LivenessWatchdog({
+        enabled: true,
+        thresholdMs: config.watchdog.thresholdMs,
+        action: config.watchdog.action,
+        reportPath: config.watchdog.reportPath
+          ?? (config.storePath ? join(config.storePath, 'watchdog-wedge.jsonl') : undefined),
+      });
+      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
@@ -468,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;
   }
 
@@ -529,6 +647,7 @@ export class AgentFramework {
 
     // Dispose EventGate (clear debounce timers)
     this.eventGate?.dispose();
+    this.livenessWatchdog?.stop();
 
     // Stop modules and MCPL servers in parallel
     const shutdownPromises: Promise<void>[] = [this.moduleRegistry.stopAll()];
@@ -658,7 +777,12 @@ export class AgentFramework {
     const moduleTools = this.moduleRegistry.getAllTools();
     const channelTools = this.channelRegistry?.getChannelTools() ?? [];
     const gateTools = this.eventGate
-      ? [this.eventGate.getToolDefinition(), ...AgentFramework.SLEEP_TOOLS]
+      ? [
+          this.eventGate.getToolDefinition(),
+          ...AgentFramework.SLEEP_TOOLS,
+          ...AgentFramework.WAKE_RULE_TOOLS,
+          AgentFramework.EVENT_TAGS_TOOL,
+        ]
       : [];
     if (this.mcplTools.length === 0 && channelTools.length === 0 && gateTools.length === 0) {
       return moduleTools;
@@ -715,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);
@@ -727,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;
         }
@@ -763,6 +891,45 @@ export class AgentFramework {
     return this.moduleRegistry.getModule(name);
   }
 
+  // =========================================================================
+  // Wake-rule surface (gate policy mutation) — backs wake_add_rule /
+  // wake_remove_rule and lets host modules compose higher-level wake modes
+  // (e.g. an "every-message-debounced" channel mode) without reaching into
+  // the private EventGate.
+  // =========================================================================
+
+  /**
+   * Add or replace (upsert) a gate policy at runtime. Validated and persisted
+   * to gate.json; hot-applied in memory. Throws if no gate is configured or the
+   * policy is invalid. `position: 'prepend'` puts a wake rule ahead of broad
+   * defer/debounce rules (first match wins).
+   */
+  addGatePolicy(
+    rawPolicy: unknown,
+    options?: { position?: 'append' | 'prepend' },
+  ): import('./gate/types.js').GatePolicy {
+    if (!this.eventGate) {
+      throw new Error('No EventGate configured (FrameworkConfig.gate is unset).');
+    }
+    return this.eventGate.addPolicy(rawPolicy, options);
+  }
+
+  /**
+   * Remove a gate policy by name at runtime. Returns false if it didn't exist.
+   * Throws if no gate is configured.
+   */
+  removeGatePolicy(name: string): boolean {
+    if (!this.eventGate) {
+      throw new Error('No EventGate configured (FrameworkConfig.gate is unset).');
+    }
+    return this.eventGate.removePolicy(name);
+  }
+
+  /** Current gate policy names (freshest on-disk view). Empty when no gate. */
+  getGatePolicyNames(): string[] {
+    return this.eventGate?.listPolicyNames() ?? [];
+  }
+
   /**
    * Get the Membrane instance.
    */
@@ -878,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.
@@ -1037,6 +1205,154 @@ export class AgentFramework {
     },
   ];
 
+  /** Synthesized wake-rule tools: add/remove a gate.json policy at runtime.
+   *  Present when a gate is wired. They write validated policies into the
+   *  hot-reloaded gate.json (same validation as load), so a rule takes effect
+   *  immediately and survives restart. */
+  private static readonly WAKE_RULE_TOOLS: import('./types/index.js').ToolDefinition[] = [
+    {
+      name: 'wake_add_rule',
+      description:
+        'Add or replace a wake rule (a gate.json policy) at runtime — no need to ' +
+        'hand-edit the file. The rule is validated and hot-applied immediately. ' +
+        'A rule with the same `name` replaces the existing one in place. Use ' +
+        '`position: "prepend"` to put a wake rule ahead of broad defer/debounce ' +
+        'rules (first match wins). Two common shapes:\n' +
+        '• Watch a FILE/workspace path: match on `mount` + `pathGlob`, e.g. ' +
+        '`{ name: "watch-notes", match: { scope: ["workspace:modified"], mount: "project", pathGlob: "notes/*.md" }, behavior: "always" }`.\n' +
+        '• Watch a CHANNEL: match on `source` + `channel` (and/or `tagsAny: ["chat:ambient"]`), ' +
+        'e.g. `{ name: "watch-cairn", match: { source: "discord", channel: "discord:*:12345", tagsAny: ["chat:ambient"] }, behavior: { debounce: 60000 } }` ' +
+        '(the channel must be subscribed for ambient events to arrive — see channel mode).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'Unique rule name. Reusing a name replaces that rule.' },
+          match: {
+            type: 'object',
+            description: 'Match criteria (all AND together). Omitted fields match anything.',
+            properties: {
+              scope: { type: 'array', items: { type: 'string' }, description: 'Event types, e.g. ["mcpl:channel-incoming","workspace:modified"].' },
+              source: { type: 'string', description: 'Integration/serverId, glob ok (e.g. "discord").' },
+              channel: { type: 'string', description: 'Channel id, glob ok (e.g. "discord:*:12345").' },
+              mount: { type: 'string', description: 'Workspace mount name, glob ok (workspace:* events).' },
+              pathGlob: { type: 'string', description: 'Glob over touched paths (workspace:* events).' },
+              tagsAny: { type: 'array', items: { type: 'string' }, description: 'Match if ANY tag matches (globs ok).' },
+              tagsAll: { type: 'array', items: { type: 'string' }, description: 'Match only if EVERY tag matches.' },
+              tagsNone: { type: 'array', items: { type: 'string' }, description: 'Match only if NONE match.' },
+              metadataTrue: { type: 'array', items: { type: 'string' }, description: 'Match if ANY listed metadata field is truthy.' },
+              filter: {
+                type: 'object',
+                description: 'Content filter.',
+                properties: {
+                  type: { type: 'string', enum: ['text', 'regex'] },
+                  pattern: { type: 'string' },
+                },
+                required: ['type', 'pattern'],
+              },
+            },
+          },
+          behavior: {
+            type: 'string',
+            enum: ['always', 'defer', 'skip'],
+            description:
+              'Simple behavior: "always" (wake now) or "defer" (don\'t wake; still enters ' +
+              'context). For debounce / rate-limit / sampling, use debounceMs / rateLimit / ' +
+              'passiveSample below instead of this field. Exactly one behavior must be given.',
+          },
+          debounceMs: {
+            type: 'number',
+            description: 'Shorthand for { debounce: ms }: wake once after ms of quiet (100–300000).',
+          },
+          rateLimit: {
+            type: 'object',
+            description: 'Token-bucket wake: at most `tokens` wakes per window; refills one per refillIntervalMs.',
+            properties: {
+              tokens: { type: 'number', description: 'Bucket capacity (> 0).' },
+              refillIntervalMs: { type: 'number', description: 'Ms between token refills (> 0).' },
+              keyBy: { type: 'string', description: 'Metadata field to partition buckets by (e.g. "channelId").' },
+            },
+            required: ['tokens', 'refillIntervalMs'],
+          },
+          passiveSample: {
+            type: 'object',
+            description: 'Wake every Nth matching event.',
+            properties: {
+              every: { type: 'number', description: 'Fire every N matches (positive integer).' },
+              keyBy: { type: 'string', description: 'Metadata field for separate per-key counters.' },
+            },
+            required: ['every'],
+          },
+          position: {
+            type: 'string',
+            enum: ['append', 'prepend'],
+            description: 'Where to insert a NEW rule (ignored when replacing by name). Default "append".',
+          },
+          resets: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Names of other rules whose runtime state to clear when this rule fires.',
+          },
+        },
+        required: ['name'],
+      },
+    },
+    {
+      name: 'wake_remove_rule',
+      description:
+        'Remove a wake rule (gate.json policy) by name at runtime. Any pending ' +
+        'debounce batch for that rule is delivered first. Returns whether a rule ' +
+        'was removed (false if no rule had that name).',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          name: { type: 'string', description: 'The rule name to remove.' },
+        },
+        required: ['name'],
+      },
+    },
+  ];
+
+  /** Discoverability for event tags (MCPL RFC-001): the reserved chat:* core,
+   *  each connected server's declared tag ontology, and gate.js status. */
+  private static readonly EVENT_TAGS_TOOL: import('./types/index.js').ToolDefinition = {
+    name: 'event_tags',
+    description:
+      'List the event tags available for gating: the reserved cross-platform ' +
+      'chat:* core, each connected server\'s declared tag ontology (descriptions, ' +
+      'implications, suggested treatments), and the status of your programmable ' +
+      'gate (gate.js). Use these tag names in gate.json policies (tagsAny / ' +
+      'tagsAll / tagsNone) or in gate.js.',
+    inputSchema: { type: 'object' },
+  };
+
+  /** Reserved chat:* core vocabulary (MCPL RFC-001 §4) — short descriptions so
+   *  the agent can author rules without reading the spec. */
+  private static readonly CHAT_CORE_TAGS: Record<string, string> = {
+    'chat:addressed': 'Directed at you (umbrella: dm/mention/reply)',
+    'chat:mention': 'You were explicitly @-mentioned',
+    'chat:reply': 'A reply to your own message',
+    'chat:dm': 'A direct/private message to you',
+    'chat:ambient': 'Overheard in a followed channel; not addressed',
+    'chat:broadcast': 'Channel-wide ping (@everyone / channel post)',
+    'chat:to-self': 'Acts on your own content (reaction/reply to you)',
+    'chat:from-human': 'Authored by a human',
+    'chat:from-bot': 'Authored by a bot/automation',
+    'chat:from-self': 'Your own message, echoed back',
+    'chat:from-agent': 'Authored by another persona/agent',
+    'chat:edited': 'An edit of an existing message',
+    'chat:deleted': 'A deletion',
+    'chat:reaction': 'An emoji reaction was added',
+    'chat:reaction-remove': 'A reaction was removed',
+    'chat:has-image': 'Has an image attachment',
+    'chat:has-audio': 'Has an audio attachment',
+    'chat:has-file': 'Has a file attachment',
+    'chat:has-link': 'Contains a link',
+    'chat:command': 'A slash/bot command invocation',
+    'chat:private': 'Private conversation',
+    'chat:group': 'Group (multi-party) conversation',
+    'chat:thread': 'Occurred in a thread',
+  };
+
   /** Refusal category → Discord reaction emoji. Unknown categories get 🛑. */
   private static readonly REFUSAL_REACTIONS: Record<string, string> = {
     bio: '☣️',
@@ -1088,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:
@@ -1111,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)}` };
     }
 
@@ -1121,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.
@@ -1738,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);
+    }
   }
 
   /**
@@ -1759,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')
     ) {
@@ -2115,6 +2731,9 @@ export class AgentFramework {
           reason: 'mcpl:channel-incoming',
           source: event.serverId,
           timestamp: Date.now(),
+          // Route this turn's auto-published speech back to THIS channel, not
+          // the global most-recent-inbound locus (item-3 redux, trunk agents).
+          channelId: event.channelId,
         });
       }
     }
@@ -2209,6 +2828,9 @@ export class AgentFramework {
         reason: 'mcpl:channel-incoming',
         source: event.serverId,
         timestamp: Date.now(),
+        // A fork's home channel wins in routeSpeech regardless, but carry the
+        // triggering channel too so the trunk/active path stays consistent.
+        channelId: event.channelId,
       });
     }
   }
@@ -2285,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,
@@ -2390,6 +3013,20 @@ export class AgentFramework {
     const id = this.addMessage('user', event.content, metadata);
     this.emitTrace({ type: 'message:added', messageId: id, source: 'mcpl:push-event' });
 
+    // Some push events carry a channel of origin (Discord DMs arrive here, not
+    // via channels/incoming, because discord-mcpl forwards them with the channel
+    // closed). Register + open that channel so routeSpeech can resolve it, and
+    // thread it onto the wake request so the reply routes back to it instead of
+    // the global locus (item-3 redux, DM sub-case).
+    const triggerChannel = this.derivePushEventChannel(event.origin);
+    if (triggerChannel && this.channelRegistry) {
+      this.channelRegistry.ensureChannelRegistered(
+        event.serverId,
+        triggerChannel.channelId,
+        triggerChannel.label,
+      );
+    }
+
     if (event.triggerInference) {
       // Default broadcast excludes conversation forks (channel-driven).
       const targetAgents = event.targetAgents
@@ -2400,11 +3037,50 @@ export class AgentFramework {
           reason: 'mcpl:push-event',
           source: event.serverId,
           timestamp: Date.now(),
+          channelId: triggerChannel?.channelId,
         });
       }
     }
   }
 
+  /**
+   * Derive the MCPL composite channel id (the outbound routing locus) for a
+   * push event from its server-defined `origin`, if it carries one.
+   *
+   * Discord DMs are the motivating case: discord-mcpl forwards them via
+   * push/event (the DM channel is closed), so they never pass through
+   * channels/incoming and their channel is never registered — leaving the
+   * agent's reply with nowhere to route (item-3 redux, DM sub-case). Prefers an
+   * explicit `origin.mcplChannelId` (a surface declaring its own composite id —
+   * the surface-agnostic contract); otherwise reconstructs the Discord form
+   * `discord:{guildId|dm}:{channelId}` from origin fields, matching
+   * discord-mcpl's `mcplChannelId()` / `parseMcplChannelId()` convention so the
+   * fix works even against a discord-mcpl build that predates `mcplChannelId`.
+   * Returns undefined for push events with no channel provenance (heartbeats,
+   * timers), which correctly keep the global fallback.
+   */
+  private derivePushEventChannel(
+    origin: Record<string, unknown> | undefined,
+  ): { channelId: string; label?: string } | undefined {
+    if (!origin) return undefined;
+    const label = typeof origin.channelName === 'string' ? origin.channelName : undefined;
+
+    const explicit = origin.mcplChannelId;
+    if (typeof explicit === 'string' && explicit) {
+      return { channelId: explicit, label };
+    }
+
+    // Discord fallback: reconstruct the composite from origin parts. `guildId`
+    // is null for a DM (→ 'dm'); a real guild id for a non-open guild channel.
+    if (origin.source === 'discord' && typeof origin.channelId === 'string' && origin.channelId) {
+      const guild =
+        typeof origin.guildId === 'string' && origin.guildId ? origin.guildId : 'dm';
+      return { channelId: `discord:${guild}:${origin.channelId}`, label };
+    }
+
+    return undefined;
+  }
+
   private async processInferenceRequests(): Promise<void> {
     if (this.pendingRequests.length === 0) {
       return;
@@ -2438,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;
       }
 
@@ -2453,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;
@@ -2460,12 +3145,31 @@ 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;
       }
 
       // Start streaming inference (non-blocking — driveStream runs in background)
       const trigger = requests[0];
-      await this.startAgentStream(agent, trigger);
+      // Route this turn's auto-published speech to the channel that triggered
+      // it (item-3 redux). A batched wake may carry several triggering channels
+      // (messages arrived in >1 channel while the agent was busy/idle) — reply
+      // in the MOST-RECENT one: it matches the legacy last-inbound semantics and
+      // is the message the agent is most likely answering. The common case is
+      // 1 message → 1 channel (unambiguous). Non-channel wakes carry no
+      // channelId, leaving the field undefined → global fallback. `reduce`
+      // keeps the last defined channelId across the (FIFO-ordered) batch.
+      const triggerChannel = requests.reduce<string | undefined>(
+        (acc, r) => r.channelId ?? acc,
+        undefined,
+      );
+      await this.startAgentStream(agent, { ...trigger, channelId: triggerChannel });
     }
   }
 
@@ -2476,8 +3180,21 @@ export class AgentFramework {
       this.redoStacks.delete(agent.name); // new work invalidates redo
     }
 
+    // Establish this turn's outbound routing locus (item-3 redux). Set it to the
+    // triggering channel for a channel/DM-triggered turn; clear it otherwise so
+    // a heartbeat / no-trigger turn doesn't inherit a previous turn's channel and
+    // instead falls back to the global default. A given agent runs one turn at a
+    // time, so a set here is only read during THIS turn's routeSpeech /
+    // buildChannelContext; retries re-run with the same trigger, re-setting it.
+    if (trigger?.channelId) {
+      this.activeTriggerChannels.set(agent.name, trigger.channelId);
+    } else {
+      this.activeTriggerChannels.delete(agent.name);
+    }
+
     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();
@@ -2487,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;
         }
@@ -2541,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) {
@@ -2817,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)
@@ -2888,23 +3691,44 @@ export class AgentFramework {
                 .map((b) => (b as unknown as { name?: string }).name)
                 .filter((n): n is string => typeof n === 'string');
               const silenced = toolNames.some((n) => SILENCING.has(bare(n)));
-              const t = allText
-                .map((b) => (b as ContentBlock & { type: 'text' }).text)
-                .join('\n')
-                .trim();
-              if (silenced || !t) {
+
+              // Split the turn's content into ordered prose segments, broken at
+              // each tool_use / tool_result boundary. `response.content` holds the
+              // WHOLE turn's blocks in provider order — earlier tool rounds
+              // included (see the trailing-slice note above, which slices exactly
+              // because the full turn is present) — so a left-to-right walk
+              // reconstructs the emission order. Interleaved prose
+              // ("msgA → [tool] → msgB → [tool] → msgC") is then delivered as
+              // separate messages IN ORDER instead of being collapsed into one
+              // trailing post (item 4). The silencing rule stays turn-wide: an
+              // explicit send / skip suppresses ALL auto-routed prose this turn,
+              // preserving the double-post guard.
+              const segments = splitProseSegments(response.content);
+
+              if (silenced || segments.length === 0) {
                 console.error(
                   `[routing] ${agent.name}: tool-call turn [${toolNames.join(', ') || 'none'}] -> NOT routed ` +
                   `(${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 trailing prose (${t.length} chars) as reply`,
+                  `[routing] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> routing ${segments.length} prose segment(s) in order -> ${turnLocus ?? '(default)'}`,
                 );
-                try {
-                  await this.channelRegistry.routeSpeech(agent.name, t);
-                } catch (err) {
-                  console.error('speech routing failed:', err);
+                // Deliver sequentially (await each) so the segments land in order.
+                for (const seg of segments) {
+                  try {
+                    await this.channelRegistry.routeSpeech(agent.name, seg, turnLocus);
+                  } catch (err) {
+                    console.error('speech routing failed:', err);
+                  }
                 }
               }
             }
@@ -2950,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) {
@@ -2964,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,
@@ -2988,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,
@@ -3005,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();
@@ -3097,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]';
@@ -3169,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 {
@@ -3193,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);
   }
 
   /**
@@ -3242,6 +4135,18 @@ export class AgentFramework {
       return;
     }
 
+    // Route wake-rule tools (runtime gate.json policy add/remove)
+    if ((enrichedCall.name === 'wake_add_rule' || enrichedCall.name === 'wake_remove_rule') && this.eventGate) {
+      this.dispatchWakeRuleToolCall(agentName, enrichedCall);
+      return;
+    }
+
+    // Route event_tags (tag/ontology discovery)
+    if (enrichedCall.name === 'event_tags' && this.eventGate) {
+      this.dispatchEventTagsToolCall(agentName, enrichedCall);
+      return;
+    }
+
     // Route synthesized 'think' (private reasoning) and 'skip_reply' (deliberate
     // stay-silent) tools — handled by the channel registry like the other
     // synthesized channel tools, but they aren't `channel_`-prefixed so they
@@ -3415,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 = {
@@ -3453,17 +4364,63 @@ 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.
    */
-  private noteInferenceExhausted(agentName: string, reason: string): void {
+  /**
+   * Live health snapshot for /healthz and doctor tooling: gate state, queued
+   * work, per-agent status + last inference activity. Cheap and read-only.
+   */
+  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) {
+    if (agent && process.env.SUPPRESS_INFERENCE_FAILED_MARKER !== '1') {
       try {
         agent.getContextManager().addMessage(
           'user',
@@ -3489,7 +4446,82 @@ 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(),
+    });
   }
 
   // ==========================================================================
@@ -3562,6 +4594,22 @@ export class AgentFramework {
           }
         },
         shouldTriggerInference: triggerFilter,
+        // Route a conversation fork's plain-text speech to its HOME channel, not
+        // the process-global most-recent-inbound locus (item 3). The trunk agent
+        // has no home entry, so this returns undefined and routeSpeech falls back
+        // to defaultPublishChannel. `conversationAgentHomes` is the permanent
+        // spawn-time binding; `channelForAgent` is the router's live binding as a
+        // belt-and-suspenders fallback.
+        homeChannelResolver: (agentName) =>
+          this.conversationAgentHomes.get(agentName)
+          ?? this.conversationRouter?.channelForAgent(agentName),
+        // Route a single TRUNK agent's plain-text speech to the channel that
+        // triggered its CURRENT turn (item-3 redux). connectome-host runs every
+        // agent as a trunk (it never exposes conversation forks), so without this
+        // a reply falls back to the process-global most-recent-inbound locus and
+        // a concurrent message in another channel hijacks it. Empty for
+        // heartbeat / no-trigger turns → correct global fallback.
+        activeChannelResolver: (agentName) => this.activeTriggerChannels.get(agentName),
         // A text-only turn whose speech couldn't be delivered must not vanish
         // silently: record a `[discord-send-failed]` marker in chronicle so the
         // agent sees, on her next turn, that her reply never reached the human.
@@ -3585,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: {
@@ -3598,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);
       }
     }
+  }
 
-    // Discover tools from all connected servers
+  // ==========================================================================
+  // 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);
+
+    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;
   }
 
   /**
@@ -3755,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}` });
     });
   }
@@ -3894,14 +5209,20 @@ export class AgentFramework {
     const startTime = Date.now();
     const args = (call.input && typeof call.input === 'object') ? call.input as Record<string, unknown> : {};
 
-    // Build state params for stateful tools (Step 8)
+    // Build state params for stateful tools (Step 8).
+    // Host-managed state is single-valued per server, so inject the host-managed
+    // set's `state` for any call; otherwise fall back to a server-managed set's
+    // opaque `checkpoint`. Never blindly pick "first stateful" — when a server
+    // mixes host-managed (e.g. a feed) and server-managed (e.g. post/undo) sets,
+    // that misattributes the feed's state.
     let stateParams: { state?: unknown; checkpoint?: string } | undefined;
     if (this.checkpointManager) {
-      const fs = this.checkpointManager.getStatefulFeatureSet(serverId);
-      if (fs) {
-        if (this.checkpointManager.isHostManaged(serverId, fs)) {
-          stateParams = { state: this.checkpointManager.getCurrentState(serverId, fs) };
-        } else {
+      const hostFs = this.checkpointManager.getHostManagedFeatureSet(serverId);
+      if (hostFs) {
+        stateParams = { state: this.checkpointManager.getCurrentState(serverId, hostFs) };
+      } else {
+        const fs = this.checkpointManager.getStatefulFeatureSet(serverId);
+        if (fs) {
           const cp = this.checkpointManager.getCurrentCheckpoint(serverId, fs);
           if (cp) stateParams = { checkpoint: cp };
         }
@@ -3913,10 +5234,17 @@ export class AgentFramework {
         const durationMs = Date.now() - startTime;
         this.emitTrace({ type: 'tool:completed', module: `mcpl:${serverId}`, tool: toolName, callId: call.id, durationMs });
 
-        // Record checkpoint from stateful tool response (Step 8)
+        // Record checkpoint from stateful tool response (Step 8).
+        // Attribute to the set the server tagged (result.state.featureSet) first;
+        // else the host-managed set (host-managed checkpoints carry data/patch);
+        // else the single stateful set. Avoids recording a feed checkpoint onto a
+        // server-managed set just because it registered first.
         if (result.state && this.checkpointManager) {
-          const fs = this.checkpointManager.getStatefulFeatureSet(serverId);
-          if (fs) {
+          const tagged = result.state.featureSet;
+          const fs = tagged
+            ?? this.checkpointManager.getHostManagedFeatureSet(serverId)
+            ?? this.checkpointManager.getStatefulFeatureSet(serverId);
+          if (fs && this.checkpointManager.isStateful(serverId, fs)) {
             this.checkpointManager.recordCheckpoint(serverId, fs, result.state);
           }
         }
@@ -4037,6 +5365,91 @@ export class AgentFramework {
       });
   }
 
+  /**
+   * Handle the synthesized `wake_add_rule` / `wake_remove_rule` tools: mutate
+   * the hot-reloaded gate.json at runtime. Validation lives in the EventGate
+   * (same path as gate.json load), so an invalid rule is surfaced as a tool
+   * error and nothing is written.
+   */
+  private dispatchWakeRuleToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
+    const finish = (result: ToolResult) => {
+      this.emitTrace({
+        type: result.isError ? 'tool:failed' : 'tool:completed',
+        module: 'gate', tool: call.name, callId: call.id, durationMs: 0,
+        ...(result.isError ? { error: result.error } : {}),
+      });
+      this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'gate', result });
+    };
+
+    try {
+      if (call.name === 'wake_remove_rule') {
+        const input = (call.input ?? {}) as { name?: unknown };
+        if (typeof input.name !== 'string' || !input.name) {
+          finish({ success: false, error: 'wake_remove_rule: `name` (string) is required', isError: true });
+          return;
+        }
+        const removed = this.removeGatePolicy(input.name);
+        finish({
+          success: true,
+          data: { removed, name: input.name, policies: this.getGatePolicyNames() },
+        });
+        return;
+      }
+
+      // wake_add_rule — assemble the canonical behavior from the typed fields
+      // (exactly one), then let the gate's own validator do the authoritative
+      // range/shape checks.
+      const input = (call.input ?? {}) as {
+        name?: unknown; match?: unknown; resets?: unknown; position?: unknown;
+        behavior?: unknown; debounceMs?: unknown; rateLimit?: unknown; passiveSample?: unknown;
+      };
+      const behaviorSources = [
+        input.behavior !== undefined ? 'behavior' : null,
+        input.debounceMs !== undefined ? 'debounceMs' : null,
+        input.rateLimit !== undefined ? 'rateLimit' : null,
+        input.passiveSample !== undefined ? 'passiveSample' : null,
+      ].filter((s): s is string => s !== null);
+      if (behaviorSources.length === 0) {
+        finish({
+          success: false,
+          error: 'wake_add_rule: specify exactly one behavior — `behavior` ("always"/"defer"/"skip"), `debounceMs`, `rateLimit`, or `passiveSample`.',
+          isError: true,
+        });
+        return;
+      }
+      if (behaviorSources.length > 1) {
+        finish({
+          success: false,
+          error: `wake_add_rule: give only one behavior, got [${behaviorSources.join(', ')}].`,
+          isError: true,
+        });
+        return;
+      }
+      const behavior: unknown =
+        input.debounceMs !== undefined ? { debounce: input.debounceMs }
+        : input.rateLimit !== undefined ? { rate_limit: input.rateLimit }
+        : input.passiveSample !== undefined ? { passive_sample: input.passiveSample }
+        : input.behavior;
+
+      const position = input.position === 'prepend' ? 'prepend' : 'append';
+      const rawPolicy = {
+        name: input.name,
+        match: input.match ?? {},
+        behavior,
+        ...(input.resets !== undefined ? { resets: input.resets } : {}),
+      };
+      const policy = this.addGatePolicy(rawPolicy, { position });
+      finish({
+        success: true,
+        data: { added: policy.name, policies: this.getGatePolicyNames() },
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      finish({ success: false, error: msg, isError: true });
+    }
+  }
+
   /**
    * Handle the synthesized `sleep` / `wake` tools. `sleep` arms the gate's
    * suppression window, optionally announces in the sticky channel, and ends
@@ -4064,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`
@@ -4084,6 +5497,42 @@ export class AgentFramework {
     finish({ success: true, data: { sleepingFor: human, until }, endTurn: true });
   }
 
+  /** Aggregate the event-tag vocabulary: reserved chat:* core + each connected
+   *  server's declared tag ontology + gate.js status. */
+  private buildEventTagsResult(): Record<string, unknown> {
+    const servers: Record<string, Record<string, unknown>> = {};
+    for (const conn of this.mcplServerRegistry?.getAllServers() ?? []) {
+      const declared = this.featureSetManager?.getDeclaredFeatureSets(conn.id) ?? {};
+      const sets: Record<string, unknown> = {};
+      for (const [name, decl] of Object.entries(declared)) {
+        if (decl.tagOntology) sets[name] = decl.tagOntology;
+      }
+      if (Object.keys(sets).length > 0) servers[conn.id] = sets;
+    }
+    return {
+      core: AgentFramework.CHAT_CORE_TAGS,
+      servers,
+      gateScript: this.eventGate?.getStatus().script ?? null,
+      hint:
+        'Use these in gate.json policies (match.tagsAny / tagsAll / tagsNone) or ' +
+        'in gate.js. Unknown/undeclared tags are tolerated (open ontologies).',
+    };
+  }
+
+  private dispatchEventTagsToolCall(agentName: string, call: ToolCall): void {
+    this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
+    let result: import('./types/events.js').ToolResult;
+    try {
+      result = { success: true, data: this.buildEventTagsResult() };
+      this.emitTrace({ type: 'tool:completed', module: 'gate', tool: call.name, callId: call.id, durationMs: 0 });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.emitTrace({ type: 'tool:failed', module: 'gate', tool: call.name, callId: call.id, error: err.message });
+      result = { success: false, error: err.message, isError: true };
+    }
+    this.pushEvent({ type: 'tool-result', callId: call.id, agentName, moduleName: 'gate', result });
+  }
+
   private dispatchGateToolCall(agentName: string, call: ToolCall): void {
     this.emitTrace({ type: 'tool:started', module: 'gate', tool: call.name, callId: call.id, input: call.input });
     const startTime = Date.now();
@@ -4117,7 +5566,13 @@ export class AgentFramework {
     const inferenceId = `${agent.name}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     return {
       inferenceId,
-      conversationId: agent.name, // Simplified; proper conversation tracking TODO
+      // Conversation identity = the agent (a trunk agent IS its own conversation;
+      // forks get their own agent). The turn's channel LOCUS — the "proper
+      // conversation tracking" this once flagged as a TODO — is now tracked
+      // per-agent in `activeTriggerChannels` and surfaced to the agent via
+      // buildChannelContext (channels.defaultOutgoing) below, so the agent is
+      // told the same channel its speech will route to (item-3 redux).
+      conversationId: agent.name,
       turnIndex: 0, // Simplified; needs per-conversation counter TODO
       userMessage: null, // Could extract from trigger context
       model: {
@@ -4126,7 +5581,7 @@ export class AgentFramework {
         contextWindow: 200000,
         capabilities: ['tools'],
       },
-      channels: this.channelRegistry?.buildChannelContext(),
+      channels: this.channelRegistry?.buildChannelContext(agent.name),
     };
   }
 }