@animalabs/agent-framework 0.9.0 → 0.11.0

package/src/framework.ts

@@ -62,7 +62,7 @@ import { computeGrant, CapabilityGrant, expandAdvertisementShorthand } from './m
 import { maskNegotiatedCapabilities } from './mcpl/capability-mask.js';
 import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler, type McplPushEvent } from './mcpl/push-handler.js';
-import { parseProsePrefix } from './mcpl/prose-grammar.js';
+import { parseProsePrefix, parseHybridProsePrefix } from './mcpl/prose-grammar.js';
 import { ProseStreamRouter } from './mcpl/prose-stream-router.js';
 import { InferenceRouter } from './mcpl/inference-router.js';
 import { ChannelRegistry, type ChannelToolOrigin } from './mcpl/channel-registry.js';
@@ -126,6 +126,9 @@ const SILENCING_TOOLS = new Set([
   'skip_reply', 'channel_publish', 'send_message', 'reply_message', 'send_dm',
 ]);
 
+/** World-surface publication names that outrank hybrid prose envelopes. */
+const HYBRID_PUBLICATION_TOOLS = new Set(['say', 'whisper']);
+
 /**
  * True when an injected message is real conversational input — something the
  * agent might actually be replying to — rather than ambient machinery.
@@ -225,11 +228,18 @@ const isAddressedMessage = (
 // envelopes can never disagree on what is a prefix.
 
 /** One-time primer appended when an agent's proseRouting mode changes. */
-function proseModePrimer(mode: 'explicit' | 'locus'): string {
+function proseModePrimer(mode: 'explicit' | 'hybrid' | 'locus' | 'disabled'): string {
   if (mode === 'locus') {
     return '[prose-routing] Mode change: your plain text auto-routes to the ' +
       'conversational locus again. `>>` destination prefixes are no longer needed.';
   }
+  if (mode === 'hybrid') {
+    return '[prose-routing] Hybrid routing enabled: unprefixed text still lands in the ' +
+      'current conversational locus. A leading `>>>destination` envelope instead routes ' +
+      'that prose to one uniquely resolved authorized Discord or Eidoverse channel. The ' +
+      'envelope remains in your memory but recipients see only its body; delivery or failure ' +
+      'is reported back to you.';
+  }
   // Deliberately terse: a short event-style notice is classifier-safe from
   // the user role (ablation D, 2026-07-24), while the full grammar as a user
   // message drew a deterministic reasoning_extraction refusal (ablation A/B).
@@ -329,7 +339,7 @@ function validateUtilityArgs(
 }
 import { CheckpointManager } from './mcpl/checkpoint-manager.js';
 import { isToolAllowed } from './mcpl/tool-policy.js';
-import { EventGate } from './gate/event-gate.js';
+import { EventGate, formatShadowWarning } from './gate/event-gate.js';
 import { UsageTracker, type PersistedUsageState } from './usage/usage-tracker.js';
 import type { SessionUsageSnapshot, UsageUpdatedEvent } from './usage/types.js';
 import type { McplServerConnection } from './mcpl/server-connection.js';
@@ -465,6 +475,53 @@ const DEFAULT_MAINTENANCE_INTERVAL_MS = 5000;
 /** Bound one pass so a large backlog yields to inference and other agents. */
 const MAINTENANCE_TICKS_PER_PASS = 8;
 
+/** Local per-residence provider admission (AF #114 bounded first slice). */
+interface LocalProviderGate {
+  primaryDepth: number;
+  primaryPending: boolean;
+  auxiliaryInFlight: number;
+  auxiliaryWaiters: Array<() => void>;
+  idleWaiters: Array<() => void>;
+  deferredAuxiliary: number;
+}
+interface ProviderAccelerationCooldown {
+  startedAt: number;
+  until: number;
+  timer: ReturnType<typeof setTimeout>;
+  heldRequests: InferenceRequest[];
+  reason: string;
+  failures: number;
+}
+interface ProviderAccelerationRecovery {
+  startedAt: number;
+  releasedAt?: number;
+  failures: number;
+  heldRequests: number;
+  reason: string;
+}
+interface ProviderAccelerationReceipt {
+  startedAt: number;
+  releasedAt: number;
+  completedAt: number;
+  cooldownMs: number;
+  waitedMs: number;
+  failures: number;
+  heldRequests: number;
+  messageCount: number;
+  toolCount: number;
+  stopReason: string;
+}
+const PROVIDER_ACCELERATION_DEFAULT_COOLDOWN_MS = 65_000;
+const PROVIDER_ACCELERATION_MAX_COOLDOWN_MS = 10 * 60_000;
+const PROVIDER_ACCELERATION_JITTER_MS = 5_000;
+function isOrganizationAccelerationRateLimit(error: Error): error is MembraneError {
+  if (!(error instanceof MembraneError) || error.type !== 'rate_limit') return false;
+  return (
+    /organization(?:'s)?[^\n]{0,120}maximum(?:\s+usage)?\s+increase\s+rate/i.test(error.message) ||
+    /organization(?:'s)?[^\n]{0,120}acceleration(?:\s+limit)?/i.test(error.message)
+  );
+}
+
 /**
  * Extract fields the EventGate cares about from a ProcessEvent. The set of
  * event variants that carry `content`/`mount`/`paths`/`metadata` is open-ended
@@ -613,6 +670,13 @@ export class AgentFramework {
   private maintenanceRunId = 0;
   private currentMaintenanceRun: ContextMaintenanceRun | null = null;
   private maintenanceHistory: ContextMaintenanceRun[] = [];
+  private providerGates: Map<string, LocalProviderGate> = new Map();
+  private providerAccelerationCooldowns: Map<string, ProviderAccelerationCooldown> = new Map();
+  private providerAccelerationRecoveries: Map<string, ProviderAccelerationRecovery> = new Map();
+  private providerAccelerationLastRecovery: Map<string, ProviderAccelerationReceipt> = new Map();
+  private providerAccelerationDefaultCooldownMs = PROVIDER_ACCELERATION_DEFAULT_COOLDOWN_MS;
+  private providerAccelerationJitterMs = PROVIDER_ACCELERATION_JITTER_MS;
+  private providerAdmissionClosed = false;
   /** Last time we reported stale (busy-requeued) inference requests, per agent. */
   private staleWarnAt = new Map<string, number>();
   /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
@@ -684,6 +748,8 @@ export class AgentFramework {
   /** Sticky per-TURN delivery target set by the turn's first `>>` prefix.
    *  Cleared at every non-restart turn start; survives context restarts. */
   private proseTargetPins: Map<string, string> = new Map();
+  /** Hybrid router is fail-closed after a malformed/unresolved envelope until a new valid target. */
+  private proseHybridSuppressed: Set<string> = new Set();
   /** Agents whose current turn requested `!` continuation — re-woken when the
    *  turn completes instead of pausing until the next external event. */
   private proseContinuations: Set<string> = new Set();
@@ -1185,6 +1251,7 @@ export class AgentFramework {
     }
 
     this.running = true;
+    this.providerAdmissionClosed = false;
     this.loopPromise = this.runLoop();
 
     // Start periodic sync timer (if enabled)
@@ -1214,6 +1281,7 @@ export class AgentFramework {
    */
   async stop(): Promise<void> {
     this.running = false;
+    this.providerAdmissionClosed = true;
     this.queue.close();
 
     // Kill running code_execution scripts before cancelling streams: a
@@ -1235,6 +1303,9 @@ export class AgentFramework {
     }
     this.backgroundScripts.clear();
 
+    // A stopped host must never hang behind its own cooldown.
+    this.cancelProviderAdmission();
+
     // Cancel all active streams
     for (const agent of this.agents.values()) {
       if (agent.state.status === 'streaming' ||
@@ -1300,6 +1371,138 @@ export class AgentFramework {
    * schemas are absent. Passes never overlap; each agent gets a bounded drain
    * so maintenance cannot monopolize the framework event loop.
    */
+  private providerGate(agentName: string): LocalProviderGate {
+    let gate = this.providerGates.get(agentName);
+    if (!gate) {
+      gate = { primaryDepth: 0, primaryPending: false, auxiliaryInFlight: 0,
+        auxiliaryWaiters: [], idleWaiters: [], deferredAuxiliary: 0 };
+      this.providerGates.set(agentName, gate);
+    }
+    return gate;
+  }
+  private providerGateBlocked(agentName: string): boolean {
+    const gate = this.providerGates.get(agentName);
+    return (gate?.primaryDepth ?? 0) > 0 || (gate?.primaryPending ?? false) ||
+      this.providerAccelerationCooldowns.has(agentName);
+  }
+  private acquirePrimaryProviderGate(agentName: string): void {
+    const gate = this.providerGate(agentName); gate.primaryPending = false; gate.primaryDepth++;
+  }
+  private releasePrimaryProviderGate(agentName: string): void {
+    const gate = this.providerGate(agentName); gate.primaryDepth = Math.max(0, gate.primaryDepth - 1);
+    this.flushAuxiliaryAdmission(agentName);
+  }
+  private flushAuxiliaryAdmission(agentName: string): void {
+    const gate = this.providerGate(agentName);
+    if (gate.primaryDepth > 0 || gate.primaryPending || this.providerAccelerationCooldowns.has(agentName)) return;
+    for (const resolve of gate.auxiliaryWaiters.splice(0)) resolve();
+  }
+  private async waitForAuxiliaryIdle(agentName: string): Promise<void> {
+    const gate = this.providerGate(agentName);
+    if (gate.auxiliaryInFlight === 0) return;
+    await new Promise<void>((resolve) => gate.idleWaiters.push(resolve));
+  }
+  private async withAuxiliaryAdmission<T>(agentName: string, run: () => Promise<T>): Promise<T> {
+    const gate = this.providerGate(agentName);
+    if (this.providerGateBlocked(agentName)) {
+      gate.deferredAuxiliary++;
+      try {
+        await new Promise<void>((resolve) => gate.auxiliaryWaiters.push(resolve));
+      } finally {
+        gate.deferredAuxiliary = Math.max(0, gate.deferredAuxiliary - 1);
+      }
+    }
+    if (this.providerAdmissionClosed) {
+      throw new Error(`Provider admission closed while stopping (${agentName})`);
+    }
+    gate.auxiliaryInFlight++;
+    try { return await run(); }
+    finally {
+      gate.auxiliaryInFlight = Math.max(0, gate.auxiliaryInFlight - 1);
+      if (gate.auxiliaryInFlight === 0) for (const resolve of gate.idleWaiters.splice(0)) resolve();
+    }
+  }
+  private auxiliaryMembraneFor(agentName: string): Membrane {
+    const target = this.membrane as unknown as Record<PropertyKey, unknown>;
+    return new Proxy(target, { get: (obj, prop, receiver) => {
+      const value = Reflect.get(obj, prop, receiver);
+      if (prop === 'complete' && typeof value === 'function') {
+        return (...args: unknown[]) => this.withAuxiliaryAdmission(
+          agentName, () => Reflect.apply(value, this.membrane, args) as Promise<unknown>);
+      }
+      return typeof value === 'function' ? value.bind(this.membrane) : value;
+    }}) as unknown as Membrane;
+  }
+  private accelerationCooldownMs(agentName: string, error: MembraneError): number {
+    const base = error.retryAfterMs ?? this.providerAccelerationDefaultCooldownMs;
+    let hash = 0; for (const ch of agentName) hash = ((hash * 31) + ch.charCodeAt(0)) >>> 0;
+    const jitter = this.providerAccelerationJitterMs > 0 ? hash % (this.providerAccelerationJitterMs + 1) : 0;
+    return Math.min(PROVIDER_ACCELERATION_MAX_COOLDOWN_MS, Math.max(1_000, base) + jitter);
+  }
+  private sameInferenceRequest(a: InferenceRequest, b: InferenceRequest): boolean {
+    return a.agentName === b.agentName && a.reason === b.reason && a.source === b.source &&
+      a.timestamp === b.timestamp && a.channelId === b.channelId;
+  }
+  private holdProviderAcceleration(agent: Agent, error: Error, trigger?: InferenceRequest): boolean {
+    if (this.ephemeralRuns.has(agent.name) || this.conversationAgentHomes.has(agent.name) || !isOrganizationAccelerationRateLimit(error)) return false;
+    const now = Date.now(); const delayMs = this.accelerationCooldownMs(agent.name, error);
+    const existing = this.providerAccelerationCooldowns.get(agent.name);
+    const held = existing?.heldRequests ?? [];
+    if (trigger && !held.some((r) => this.sameInferenceRequest(r, trigger))) held.push(trigger);
+    if (existing) clearTimeout(existing.timer);
+    const timer = setTimeout(() => this.releaseProviderAccelerationCooldown(agent.name), delayMs); timer.unref?.();
+    this.providerAccelerationCooldowns.set(agent.name, { startedAt: existing?.startedAt ?? now,
+      until: now + delayMs, timer, heldRequests: held, reason: error.message,
+      failures: (existing?.failures ?? 0) + 1 });
+    const gate = this.providerGate(agent.name); gate.primaryPending = true;
+    this.providerAccelerationRecoveries.set(agent.name, { startedAt: existing?.startedAt ?? now,
+      failures: (existing?.failures ?? 0) + 1, heldRequests: held.length, reason: error.message });
+    console.error(`[provider-cooldown] agent=${agent.name} organization acceleration 429 — ` +
+      `holding primary/auxiliary for ${delayMs}ms; ${held.length} request(s) retained`);
+    return true;
+  }
+  private releaseProviderAccelerationCooldown(agentName: string): void {
+    const cooldown = this.providerAccelerationCooldowns.get(agentName); if (!cooldown) return;
+    clearTimeout(cooldown.timer); this.providerAccelerationCooldowns.delete(agentName);
+    const recovery = this.providerAccelerationRecoveries.get(agentName);
+    if (recovery) { recovery.releasedAt = Date.now(); recovery.heldRequests = cooldown.heldRequests.length; }
+    const requests = cooldown.heldRequests.length > 0 ? cooldown.heldRequests : [{ agentName,
+      reason: 'provider-acceleration-retry', source: 'framework', timestamp: Date.now() } satisfies InferenceRequest];
+    this.pendingRequests.push(...requests);
+    console.error(`[provider-cooldown] agent=${agentName} released after ${Date.now() - cooldown.startedAt}ms — ` +
+      `fresh compile queued with ${requests.length} retained request(s)`);
+  }
+  private recordProviderAccelerationRecovery(agent: Agent, request: NormalizedRequest | undefined, stopReason: string): void {
+    const recovery = this.providerAccelerationRecoveries.get(agent.name); if (!recovery?.releasedAt) return;
+    this.providerAccelerationRecoveries.delete(agent.name);
+    const completedAt = Date.now();
+    const receipt: ProviderAccelerationReceipt = {
+      startedAt: recovery.startedAt,
+      releasedAt: recovery.releasedAt,
+      completedAt,
+      cooldownMs: recovery.releasedAt - recovery.startedAt,
+      waitedMs: completedAt - recovery.startedAt,
+      failures: recovery.failures,
+      heldRequests: recovery.heldRequests,
+      messageCount: request?.messages.length ?? 0,
+      toolCount: request?.tools?.length ?? 0,
+      stopReason,
+    };
+    this.providerAccelerationLastRecovery.set(agent.name, receipt);
+    // Operational receipt only: provider admission must never author resident memory.
+    console.error(`[provider-cooldown] recovered ${JSON.stringify({ agent: agent.name, ...receipt })}`);
+  }
+  private cancelProviderAdmission(): void {
+    for (const cooldown of this.providerAccelerationCooldowns.values()) clearTimeout(cooldown.timer);
+    this.providerAccelerationCooldowns.clear(); this.providerAccelerationRecoveries.clear();
+    for (const gate of this.providerGates.values()) {
+      gate.primaryDepth = 0; gate.primaryPending = false;
+      for (const resolve of gate.auxiliaryWaiters.splice(0)) resolve();
+      for (const resolve of gate.idleWaiters.splice(0)) resolve();
+    }
+    this.providerGates.clear();
+  }
+
   private startQueuedMaintenance(): void {
     if (this.maintenancePass || !this.running) return;
     const pass = this.runQueuedMaintenance().catch((error) => {
@@ -1326,6 +1529,7 @@ export class AgentFramework {
       const cm = agent.getContextManager();
       const tools = this.getToolsForAgent(agent.name).filter((tool) => agent.canUseTool(tool.name));
       cm.setToolDefinitions(tools);
+      if (this.providerGateBlocked(agent.name)) return [];
       if (cm.isReady()) return [];
       const pending = cm.getPendingWork()?.description;
       const progress = this.contextProgress(cm);
@@ -1968,12 +2172,14 @@ export class AgentFramework {
   /**
    * 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).
+   * policy is invalid. Placement: `'prepend'` puts a rule ahead of EVERYTHING
+   * (including addressed-message wake rules — see EventGate.lintShadows);
+   * `{before: name}` / `{after: name}` anchor it against a specific rule,
+   * which is usually what a sampler or debounce actually wants.
    */
   addGatePolicy(
     rawPolicy: unknown,
-    options?: { position?: 'append' | 'prepend' },
+    options?: { position?: 'append' | 'prepend' | { before: string } | { after: string } },
   ): import('./gate/types.js').GatePolicy {
     if (!this.eventGate) {
       throw new Error('No EventGate configured (FrameworkConfig.gate is unset).');
@@ -2350,9 +2556,17 @@ export class AgentFramework {
       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' +
+        'A rule with the same `name` replaces the existing one in place (add a ' +
+        'position to move it). ⚠️ ORDERING IS SEMANTICS: first match wins, and a ' +
+        'matched rule CONSUMES the event — a broad rule placed early makes every ' +
+        'later rule unreachable for its scope, including your addressed-message ' +
+        '(DM/mention) wake rules. Prefer `insertBefore`/`insertAfter` to place a ' +
+        'rule relative to a specific existing rule; use `position: "prepend"` only ' +
+        'when the rule really must beat EVERYTHING. For "additionally wake me ' +
+        'every Nth event / at most N per hour" governors, set `passthrough: true` ' +
+        'so non-firing matches fall through to your normal rules instead of ' +
+        'swallowing them. The result includes a before/after probe table and any ' +
+        'shadow warnings — READ THEM before ending the turn. 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"]`), ' +
@@ -2420,7 +2634,30 @@ export class AgentFramework {
           position: {
             type: 'string',
             enum: ['append', 'prepend'],
-            description: 'Where to insert a NEW rule (ignored when replacing by name). Default "append".',
+            description:
+              'Coarse placement. "append" (default) adds at the end; "prepend" puts the rule ' +
+              'ahead of EVERYTHING — including addressed-message wake rules — so prefer ' +
+              'insertBefore/insertAfter unless the rule really must beat every other rule. ' +
+              'When replacing an existing name, giving any placement MOVES the rule there; ' +
+              'omit all placement fields to update it in place.',
+          },
+          insertBefore: {
+            type: 'string',
+            description:
+              'Insert the rule immediately BEFORE the named existing rule (error if absent). ' +
+              'The safe way to order against a specific catch-all, e.g. insertBefore: "discord-ambient".',
+          },
+          insertAfter: {
+            type: 'string',
+            description: 'Insert the rule immediately AFTER the named existing rule (error if absent).',
+          },
+          passthrough: {
+            type: 'boolean',
+            description:
+              'Observer semantics for rateLimit/passiveSample rules: when the rule matches but ' +
+              'does not fire (below N, bucket empty), the event FALLS THROUGH to later rules ' +
+              'instead of being consumed. Use for "additionally wake me every Nth event" ' +
+              'governors so they never swallow DM/mention wakes.',
           },
           resets: {
             type: 'array',
@@ -3693,7 +3930,9 @@ export class AgentFramework {
       store: this.store,
       namespace: `agents/${config.name}`,
       strategy: config.strategy ?? new PassthroughStrategy(),
-      membrane: this.membrane,
+      // Context Manager complete() calls are auxiliary work; the primary
+      // streaming agent keeps the original Membrane.
+      membrane: this.auxiliaryMembraneFor(config.name),
       debugLogContext: !!process.env.DEBUG_CONTEXT,
     });
 
@@ -3948,7 +4187,7 @@ export class AgentFramework {
           // updates lastAnnouncedLocus so the next turn's announce-on-change
           // diffs against what the agent was actually last told.
           if (
-            agent.proseRouting !== 'explicit' &&
+            (agent.proseRouting === 'locus' || agent.proseRouting === 'hybrid') &&
             !shouldEndTurn && !overBudget && currentState.stream
           ) {
             // Two signals qualify an injection to move the pin (n=6 + n=7):
@@ -4417,6 +4656,9 @@ export class AgentFramework {
       isolate: true,
       // Strategy instances are stateful — never share the template's.
       strategy: router.strategyFactory?.() ?? new PassthroughStrategy(),
+      // Dynamic conversation forks retain the established provider policy in
+      // this bounded first slice. Provider cooldown ownership belongs to the
+      // persistent resident only; generation-unique forks must not leak gates.
       membrane: this.membrane,
       debugLogContext: !!process.env.DEBUG_CONTEXT,
     });
@@ -4800,7 +5042,8 @@ export class AgentFramework {
     this.pendingRequests = [];
 
     // Check each agent
-    for (const [agentName, requests] of requestsByAgent) {
+    for (const [agentName, groupedRequests] of requestsByAgent) {
+      let requests = groupedRequests;
       const agent = this.agents.get(agentName);
       if (!agent) {
         // Agent not found — request is orphaned. Emit warning and drop.
@@ -4816,6 +5059,28 @@ export class AgentFramework {
         continue;
       }
 
+      const providerCooldown = this.providerAccelerationCooldowns?.get(agentName);
+      if (providerCooldown) {
+        if (now < providerCooldown.until) {
+          for (const req of requests) {
+            if (!providerCooldown.heldRequests.some((r) => this.sameInferenceRequest(r, req))) {
+              providerCooldown.heldRequests.push(req);
+            }
+          }
+          const recovery = this.providerAccelerationRecoveries.get(agentName);
+          if (recovery) recovery.heldRequests = providerCooldown.heldRequests.length;
+          // The timer owns release. Do not hot-poll these requests.
+          continue;
+        }
+        // Timers can deliver late under load. Release synchronously and merge
+        // the held causes into this one current compile.
+        clearTimeout(providerCooldown.timer);
+        this.providerAccelerationCooldowns.delete(agentName);
+        const recovery = this.providerAccelerationRecoveries.get(agentName);
+        if (recovery) recovery.releasedAt = now;
+        requests = [...providerCooldown.heldRequests, ...requests];
+      }
+
       // Skip if agent is busy (inferring, streaming, or waiting for tools) —
       // or if a turn is alive at all (activeTurnTokens): the state machine
       // goes idle at endTurn's reset while driveStream teardown is still
@@ -4831,9 +5096,14 @@ export class AgentFramework {
       // token; the predecessor frame's late finally no-ops via token-match.
       // This mirrors how the restart has always overwritten activeStreams
       // rather than waiting for the old stream's teardown.
-      const isBudgetRestart = requests.some((r) => r.reason === 'context_budget_restart');
-      const turnAlive = !isBudgetRestart && this.activeTurnTokens.has(agentName);
-      if (turnAlive || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
+      const budgetRestart = requests.find((r) => r.reason === 'context_budget_restart');
+      const turnAlive = !budgetRestart && this.activeTurnTokens.has(agentName);
+      const providerGate = this.providerGates?.get(agentName);
+      // A primary can own provider admission while yielding to an already in-flight
+      // auxiliary call. Keep this agent's later wakes queued, but do not block the
+      // framework event loop or other residents while that auxiliary call settles.
+      const providerPrimaryWaiting = (providerGate?.primaryDepth ?? 0) > 0 && !this.activeTurnTokens.has(agentName);
+      if (providerPrimaryWaiting || turnAlive || agent.state.status === 'inferring' || agent.state.status === 'streaming' || agent.state.status === 'waiting_for_tools') {
         // Re-queue requests, but warn if they've been pending too long
         const oldest = Math.min(...requests.map(r => r.timestamp));
         if (
@@ -4877,11 +5147,22 @@ export class AgentFramework {
           `[inference-dropped] agent=${agentName} reason=policy-skip ` +
           `requests=${requests.length} triggers=${requests.map((r) => r.reason).join(',')}`,
         );
+        const gate = this.providerGates.get(agentName);
+        if (gate?.primaryPending && this.providerAccelerationRecoveries.has(agentName)) {
+          gate.primaryPending = false;
+          this.providerAccelerationRecoveries.delete(agentName);
+          this.flushAuxiliaryAdmission(agentName);
+        }
         continue;
       }
 
       // Start streaming inference (non-blocking — driveStream runs in background)
-      const trigger = requests[0];
+      // The request that grants the turn-alive exception must also define the
+      // downstream turn semantics. An ordinary wake can already be pending
+      // when the tool boundary appends a context-budget restart; selecting
+      // requests[0] in that mixed batch bypassed the turn lock because a
+      // restart existed, then treated the continuation as a fresh turn.
+      const trigger = budgetRestart ?? requests[0];
       // 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):
@@ -4963,7 +5244,9 @@ export class AgentFramework {
     }
     const suppressedNote =
       suppressed > 0
-        ? `${suppressed} plain-speech segment(s) suppressed (explicit send in the same round — resend with a send tool if it was meant to be heard)`
+        ? agent.proseRouting === 'disabled'
+          ? `${suppressed} plain-speech segment(s) suppressed (proseRouting=disabled — publish only with an explicit send tool)`
+          : `${suppressed} plain-speech segment(s) suppressed (explicit send in the same round — resend with a send tool if it was meant to be heard)`
         : '';
     const text =
       shown.length > 0
@@ -5110,6 +5393,97 @@ export class AgentFramework {
     }
   }
 
+  /** Locus-preserving explicit publication. Source remains byte-identical in Chronicle. */
+  private async deliverHybridProse(
+    agent: Agent,
+    rawText: string,
+    locus: string | null,
+    allowLocus: boolean,
+  ): Promise<void> {
+    const lines = rawText.split('\n');
+    const envelopes: string[] = [];
+    let current: string[] = [];
+    for (const line of lines) {
+      if (line.trimStart().startsWith('>>>') && current.length > 0) {
+        envelopes.push(current.join('\n'));
+        current = [];
+      }
+      current.push(line);
+    }
+    if (current.length > 0) envelopes.push(current.join('\n'));
+
+    for (const envelope of envelopes) {
+      if (!envelope.trim()) continue;
+      const normalized = envelope.replace(/^\s+(?=>>>)/, '');
+      const attempted = normalized.startsWith('>>>');
+      const parsed = parseHybridProsePrefix(normalized);
+      if (parsed.continueTurn) this.proseContinuations.add(agent.name);
+      if (parsed.kind === 'private') {
+        this.proseTargetPins.delete(agent.name);
+        this.proseHybridSuppressed.add(agent.name);
+        console.error(`[prose] ${agent.name}: >>>skip_reply — ${parsed.body.length} chars kept in context (not sent)`);
+        continue;
+      }
+      if (parsed.kind === 'target') {
+        const resolved = this.channelRegistry!.resolveProseTarget(parsed.target!);
+        if ('error' in resolved) {
+          this.proseTargetPins.delete(agent.name);
+          this.proseHybridSuppressed.add(agent.name);
+          this.bounceProse(agent, parsed.body, resolved.error, resolved.candidates, '>>>');
+          continue;
+        }
+        let body = parsed.body;
+        const usedClipboard = body.includes('{{unsent}}');
+        if (usedClipboard) body = body.replaceAll('{{unsent}}', this.proseClipboards.get(agent.name) ?? '');
+        this.proseTargetPins.set(agent.name, resolved.channelId);
+        this.proseHybridSuppressed.delete(agent.name);
+        if (!body.trim()) {
+          console.error(`[prose] ${agent.name}: >>>${parsed.target} established target; empty body — nothing sent yet`);
+          continue;
+        }
+        try {
+          const outcome = await this.channelRegistry!.routeSpeech(agent.name, body, resolved.channelId);
+          this.recordProseDelivery(agent.name, outcome);
+          if (outcome?.delivered) {
+            this.proseBounceStreaks.delete(agent.name);
+            if (usedClipboard) this.proseClipboards.delete(agent.name);
+          } else {
+            this.proseTargetPins.delete(agent.name);
+            this.proseHybridSuppressed.add(agent.name);
+            this.bounceProse(agent, parsed.body, `delivery to ${resolved.channelId} was not confirmed`, undefined, '>>>');
+          }
+        } catch (err) {
+          this.proseTargetPins.delete(agent.name);
+          this.proseHybridSuppressed.add(agent.name);
+          this.bounceProse(agent, parsed.body, `delivery to ${resolved.channelId} failed: ${err instanceof Error ? err.message : String(err)}`, undefined, '>>>');
+        }
+        continue;
+      }
+      if (attempted) {
+        this.proseTargetPins.delete(agent.name);
+        this.proseHybridSuppressed.add(agent.name);
+        this.bounceProse(agent, normalized, 'malformed >>> routing envelope: destination is missing', undefined, '>>>');
+        continue;
+      }
+      if (this.proseHybridSuppressed.has(agent.name)) {
+        this.recordProseSuppression(agent.name, 1);
+        continue;
+      }
+      const sticky = this.proseTargetPins.get(agent.name);
+      if (!allowLocus && !sticky) {
+        this.recordProseSuppression(agent.name, 1);
+        continue;
+      }
+      const target = sticky ?? locus;
+      try {
+        const outcome = await this.channelRegistry!.routeSpeech(agent.name, envelope, target);
+        this.recordProseDelivery(agent.name, outcome);
+      } catch (err) {
+        console.error('hybrid locus delivery failed:', err);
+      }
+    }
+  }
+
   private async deliverProseEnvelope(agent: Agent, rawText: string): Promise<void> {
     const name = agent.name;
     const parsed = parseProsePrefix(rawText);
@@ -5169,7 +5543,7 @@ export class AgentFramework {
   /** Cap on consecutive bounce-triggered wakes (notices still append after). */
   private static readonly PROSE_BOUNCE_WAKE_CAP = 2;
 
-  private bounceProse(agent: Agent, text: string, reason: string, candidates?: string[]): void {
+  private bounceProse(agent: Agent, text: string, reason: string, candidates?: string[], prefix: '>>' | '>>>' = '>>'): void {
     const name = agent.name;
     this.proseClipboards.set(name, text);
     const streak = (this.proseBounceStreaks.get(name) ?? 0) + 1;
@@ -5178,8 +5552,9 @@ export class AgentFramework {
     const notice =
       `[prose-routing] Your text (${text.length} chars) was not delivered — ${reason}.${cand} ` +
       'The text is retained; nothing is lost. To deliver it unchanged, reply with a ' +
-      'destination plus the token {{unsent}}, e.g. ">>#channel {{unsent}}" or ">>@person {{unsent}}". ' +
-      '">>skip_reply {{unsent}}" keeps it in context only. The prose_help tool shows the full syntax.';
+      `destination plus the token {{unsent}}, e.g. "${prefix}#channel {{unsent}}" or "${prefix}@person {{unsent}}". ` +
+      `"${prefix}skip_reply {{unsent}}" keeps it in context only.` +
+      (prefix === '>>' ? ' The prose_help tool shows the full syntax.' : '');
     try {
       // Through framework.addMessage, NOT the context manager directly: while
       // the turn is still streaming this defers the notice to the next tool
@@ -5241,6 +5616,13 @@ export class AgentFramework {
       console.error('maybePrimeProseMode: state read/write failed:', err);
       return;
     }
+    // Disabled mode is intentionally silent: no model-visible routing prose.
+    // The resident publishes only through explicit tools. This contains
+    // continuity-summary locus leaks (Host #96).
+    if (mode === 'disabled') {
+      console.error(`[prose] ${agent.name}: disabled mode recorded (no primer injected)`);
+      return;
+    }
     try {
       const id = agent.getContextManager().addMessage(
         'user',
@@ -5254,7 +5636,38 @@ export class AgentFramework {
     }
   }
 
-  private async startAgentStream(agent: Agent, trigger?: InferenceRequest, attempt = 0): Promise<void> {
+  private async startAgentStream(
+    agent: Agent,
+    trigger?: InferenceRequest,
+    attempt = 0,
+    providerGateAlreadyHeld = false,
+  ): Promise<void> {
+    const ownsProviderGate =
+      !this.ephemeralRuns.has(agent.name) && !this.conversationAgentHomes.has(agent.name);
+    if (ownsProviderGate && !providerGateAlreadyHeld) {
+      this.acquirePrimaryProviderGate(agent.name);
+      const gate = this.providerGate(agent.name);
+      if (gate.auxiliaryInFlight > 0) {
+        // Do not await inside processInferenceRequests: one slow auxiliary call for
+        // this resident must not block events or other residents. Admission stays
+        // owned and the continuation receives it after the in-flight call settles.
+        void this.waitForAuxiliaryIdle(agent.name).then(async () => {
+          if (this.providerAdmissionClosed) {
+            this.releasePrimaryProviderGate(agent.name);
+            return;
+          }
+          await this.startAgentStream(agent, trigger, attempt, true);
+        }).catch((error) => {
+          this.releasePrimaryProviderGate(agent.name);
+          console.error(`[provider-cooldown] failed to resume primary for ${agent.name}:`, error);
+        });
+        return;
+      }
+      if (this.providerAdmissionClosed) {
+        this.releasePrimaryProviderGate(agent.name);
+        return;
+      }
+    }
     // Mark the turn alive before ANYTHING awaits (hooks, compile, stream
     // setup): from here until this turn's teardown, cross-turn writers defer
     // (addMessage guard) instead of appending — nothing may enter the window
@@ -5275,11 +5688,12 @@ export class AgentFramework {
     this.activeTurnTokens.set(agent.name, turnToken);
     let tokenHandedOff = false;
     try {
-      tokenHandedOff = await this.beginAgentTurn(agent, trigger, attempt, turnToken);
+      tokenHandedOff = await this.beginAgentTurn(agent, trigger, attempt, turnToken, ownsProviderGate);
     } finally {
       if (!tokenHandedOff && this.activeTurnTokens.get(agent.name) === turnToken) {
         this.activeTurnTokens.delete(agent.name);
       }
+      if (!tokenHandedOff && ownsProviderGate) this.releasePrimaryProviderGate(agent.name);
     }
   }
 
@@ -5293,6 +5707,7 @@ export class AgentFramework {
     trigger: InferenceRequest | undefined,
     attempt: number,
     turnToken: number,
+    ownsProviderGate: boolean,
   ): Promise<boolean> {
     // Flush messages deferred during the PREVIOUS turn — before the
     // checkpoint, the locus announcement, and the compile — so a turn started
@@ -5381,10 +5796,12 @@ export class AgentFramework {
       this.turnEngagedChannels.delete(agent.name);
       this.turnProseDeliveries.delete(agent.name);
       this.turnProseSuppressed.delete(agent.name);
-      if (agent.proseRouting === 'explicit') {
-        // Explicit prose routing: there is no locus. The model names every
-        // destination in-band (`>>` prefixes); the only turn state is the
-        // sticky target, reset for each fresh turn. No freeze, no announce.
+      this.proseHybridSuppressed.delete(agent.name);
+      if (agent.proseRouting === 'hybrid') this.proseTargetPins.delete(agent.name);
+      if (agent.proseRouting === 'explicit' || agent.proseRouting === 'disabled') {
+        // Explicit and disabled prose routing have no inferred locus.
+        // Explicit mode uses a turn-scoped `>>` target; disabled mode has no
+        // prose target at all. Neither mode freezes or announces a locus.
         this.proseTargetPins.delete(agent.name);
         this.proseContinuations.delete(agent.name);
         this.midTurnInputSignals.delete(agent.name);
@@ -5478,6 +5895,7 @@ export class AgentFramework {
         trigger,
         attempt,
         compiledRequest,
+        ownsProviderGate,
       );
       this.activeStreams.set(agent.name, handle);
       // Handoff: driveStream captured the token in its synchronous prefix;
@@ -5497,6 +5915,13 @@ export class AgentFramework {
       });
       agent.reset();
 
+      if (ownsProviderGate && this.holdProviderAcceleration(agent, err, trigger)) {
+        // Capacity scheduling is not poisoned history. The cooldown timer owns
+        // one later fresh compile; no immediate retry or exhaustion marker.
+        this.eventGate?.onInferenceEnded(agent.name);
+        return false;
+      }
+
       const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
       if (action.retry) {
         await new Promise((resolve) => setTimeout(resolve, action.delayMs));
@@ -5550,7 +5975,8 @@ export class AgentFramework {
     requestSnapshot: InferenceToolSnapshot,
     trigger?: InferenceRequest,
     attempt = 0,
-    compiledRequest?: NormalizedRequest
+    compiledRequest?: NormalizedRequest,
+    ownsProviderGate = false,
   ): Promise<void> {
     const startTime = Date.now();
     const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
@@ -5615,9 +6041,11 @@ export class AgentFramework {
     //     sent here", which is true regardless of where the reply goes.
     //     Heartbeat/no-trigger explicit turns show no indicator.
     const typingChannel =
-      agent.proseRouting === 'explicit'
-        ? trigger?.channelId ?? null
-        : resolveTurnLocus();
+      agent.proseRouting === 'disabled'
+        ? null
+        : agent.proseRouting === 'explicit'
+          ? trigger?.channelId ?? null
+          : resolveTurnLocus();
     if (typingChannel) this.channelRegistry!.startTyping(typingChannel);
 
     // MCPL Spec 14.3 outgoing streaming: route text deltas to their
@@ -5647,9 +6075,9 @@ export class AgentFramework {
       turnIndex: 0,
       phase: 'started',
     });
-    const proseStream = this.channelRegistry
+    const proseStream = this.channelRegistry && agent.proseRouting !== 'disabled'
       ? new ProseStreamRouter({
-          mode: agent.proseRouting === 'explicit' ? 'explicit' : 'locus',
+          mode: agent.proseRouting === 'explicit' ? 'explicit' : agent.proseRouting === 'hybrid' ? 'hybrid' : 'locus',
           initialTarget: typingChannel,
           resolve: (spec) => {
             const r = this.channelRegistry!.resolveProseTarget(spec);
@@ -5776,9 +6204,18 @@ export class AgentFramework {
               const rawXml = rawText && /^<(antml:)?function_calls>/.test(rawText)
                 ? rawText
                 : undefined;
+              // Persist THIS round's text only. `roundPreamble` (membrane
+              // ≥0.5.79) is the per-round delta; the legacy `preamble` is
+              // CUMULATIVE in XML mode — persisting it per round stored each
+              // round's text N times and re-persisted injected
+              // <function_results> as the agent's own words (the Evander
+              // 2026-08-08 scaffold-leak pyramid: r1 ×3, r2 ×2).
+              const roundText =
+                (event.context as { roundPreamble?: string }).roundPreamble ??
+                event.context.preamble;
               assistantBlocks = [];
-              if (event.context.preamble) {
-                assistantBlocks.push({ type: 'text', text: event.context.preamble });
+              if (roundText) {
+                assistantBlocks.push({ type: 'text', text: roundText });
               }
               for (const c of event.calls) {
                 assistantBlocks.push({
@@ -5820,14 +6257,33 @@ export class AgentFramework {
               const hasSameRoundPrivateThink =
                 roundToolNames.includes('think') &&
                 requestSnapshot.sameRoundThinkTextPolicy === 'private';
-              if (roundToolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)))) {
+              if (roundToolNames.some((n) =>
+                SILENCING_TOOLS.has(bareToolName(n)) ||
+                (agent.proseRouting === 'hybrid' && HYBRID_PUBLICATION_TOOLS.has(bareToolName(n)))
+              )) {
                 turnSilenced = true;
               }
               if (roundContent && roundContent.length > 0) {
                 liveProseRouting = true;
                 const roundSegments = splitProseSegments(assistantBlocks);
                 if (roundSegments.length > 0) {
-                  if (agent.proseRouting === 'explicit') {
+                  if (agent.proseRouting === 'disabled') {
+                    console.error(
+                      `[routing] ${agent.name}: mid-turn prose NOT routed (proseRouting=disabled)`,
+                    );
+                    this.recordProseSuppression(agent.name, roundSegments.length);
+                  } else if (agent.proseRouting === 'hybrid') {
+                    if (turnSilenced) {
+                      this.recordProseSuppression(agent.name, roundSegments.length);
+                    } else if (!hasSameRoundPrivateThink) {
+                      const locus = resolveTurnLocus();
+                      for (const seg of roundSegments) {
+                        turnSpeechChain = turnSpeechChain
+                          .then(() => this.deliverHybridProse(agent, seg, locus, true))
+                          .catch((err) => console.error('mid-turn hybrid prose delivery failed:', err));
+                      }
+                    }
+                  } else if (agent.proseRouting === 'explicit') {
                     // Explicit mode: every segment through the prose gateway.
                     // Silencing does not apply — unprefixed prose bounces and
                     // prefixed prose is deliberate; think-privacy still holds.
@@ -5932,6 +6388,10 @@ export class AgentFramework {
               agent.addAssistantResponse(terminalContent);
             }
 
+            // Bind the cooldown receipt to this fresh, successful request —
+            // never to the frozen request that received the 429.
+            this.recordProviderAccelerationRecovery(agent, compiledRequest, response.stopReason);
+
             // §10.5: context/afterInference is removed in 0.5.0 — no
             // content leaves the host here. Turn boundaries are announced
             // by the metadata-only inference/lifecycle notifications
@@ -6157,7 +6617,18 @@ export class AgentFramework {
                 .join('\n')
                 .trim();
               if (speechText) {
-                if (agent.proseRouting === 'explicit') {
+                if (agent.proseRouting === 'disabled') {
+                  console.error(`[routing] ${agent.name}: text-only prose NOT routed (proseRouting=disabled)`);
+                  this.recordProseSuppression(agent.name, 1);
+                } else if (agent.proseRouting === 'hybrid') {
+                  const locus = resolveTurnLocus();
+                  console.error(`[prose] ${agent.name}: text-only turn -> hybrid prose gateway`);
+                  try {
+                    await this.deliverHybridProse(agent, speechText, locus, true);
+                  } catch (err) {
+                    console.error('text-only hybrid prose delivery failed:', err);
+                  }
+                } else if (agent.proseRouting === 'explicit') {
                   console.error(`[prose] ${agent.name}: text-only turn -> prose gateway`);
                   try {
                     await this.deliverProse(agent, speechText);
@@ -6204,7 +6675,10 @@ export class AgentFramework {
                 .filter((n): n is string => typeof n === 'string');
               const silenced = liveProseRouting
                 ? turnSilenced
-                : turnSilenced || toolNames.some((n) => SILENCING_TOOLS.has(bareToolName(n)));
+                : turnSilenced || toolNames.some((n) =>
+                  SILENCING_TOOLS.has(bareToolName(n)) ||
+                  (agent.proseRouting === 'hybrid' && HYBRID_PUBLICATION_TOOLS.has(bareToolName(n)))
+                );
 
               const segments = splitProseSegments(liveProseRouting ? terminalContent : response.content);
 
@@ -6213,7 +6687,27 @@ export class AgentFramework {
               // the chain may still be flushing earlier rounds' posts.
               await turnSpeechChain;
 
-              if (agent.proseRouting === 'explicit') {
+              if (agent.proseRouting === 'disabled') {
+                if (segments.length > 0) {
+                  console.error(
+                    `[routing] ${agent.name}: tool-call trailing prose NOT routed (proseRouting=disabled)`,
+                  );
+                  this.recordProseSuppression(agent.name, segments.length);
+                }
+              } else if (agent.proseRouting === 'hybrid') {
+                if (silenced && segments.length > 0) {
+                  this.recordProseSuppression(agent.name, segments.length);
+                } else if (segments.length > 0) {
+                  const locus = resolveTurnLocus();
+                  for (const seg of segments) {
+                    try {
+                      await this.deliverHybridProse(agent, seg, locus, true);
+                    } catch (err) {
+                      console.error('trailing hybrid prose delivery failed:', err);
+                    }
+                  }
+                }
+              } else if (agent.proseRouting === 'explicit') {
                 if (segments.length > 0) {
                   console.error(
                     `[prose] ${agent.name}: tool-call turn [${toolNames.join(', ')}] -> ${segments.length} trailing segment(s) via prose gateway`,
@@ -6314,6 +6808,12 @@ export class AgentFramework {
             this.abortAgentScript(agent.name, 'stream error');
             agent.reset();
 
+            if (ownsProviderGate && this.holdProviderAcceleration(agent, err, trigger)) {
+              lifecyclePhase = 'failed';
+              this.eventGate?.onInferenceEnded(agent.name);
+              break;
+            }
+
             const action = this.errorPolicy.onInferenceError(err, agent.name, attempt);
             if (action.retry) {
               await new Promise((resolve) => setTimeout(resolve, action.delayMs));
@@ -6453,10 +6953,19 @@ export class AgentFramework {
         }
       }
     } catch (error) {
-      // Stream itself threw (unexpected) — no retry path here, so also emit
-      // inference:exhausted so ephemeral agent promises can settle.
+      // Stream itself threw. Organization acceleration is deferred from a
+      // fresh compile; every other throw keeps the ordinary exhausted path.
       const err = error instanceof Error ? error : new Error(String(error));
       const durationMs = Date.now() - startTime;
+      if (ownsProviderGate && this.holdProviderAcceleration(agent, err, trigger)) {
+        this.emitTrace({ type: 'inference:failed', agentName: agent.name, error: err.message, stack: err.stack });
+        this.logInference({ timestamp: startTime, agentName: agent.name, requestId, success: false,
+          error: `Provider acceleration cooldown: ${err.message}`,
+          request: compiledRequest ?? { note: 'streaming request rate-limited' }, durationMs });
+        this.abortAgentScript(agent.name, 'provider acceleration cooldown');
+        lifecyclePhase = 'failed'; agent.reset(); this.eventGate?.onInferenceEnded(agent.name);
+        return;
+      }
       this.emitTrace({
         type: 'inference:failed',
         agentName: agent.name,
@@ -6511,6 +7020,7 @@ export class AgentFramework {
       // 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() });
+      if (ownsProviderGate) this.releasePrimaryProviderGate(agent.name);
 
       // Stop the typing indicator on every exit path (complete, error,
       // exhausted, abort) so it never sticks after the turn ends.
@@ -6576,6 +7086,107 @@ export class AgentFramework {
     });
   }
 
+  /**
+   * Admin puppet: execute ONE tool call AS an agent and persist the
+   * tool_use + tool_result pair in that agent's window exactly as a
+   * model-initiated call is stored.
+   *
+   * Born from the princess exemplar surgery (2026-08-23). Her folded
+   * narrative said "I have no tools"; every past tool_use/tool_result pair
+   * had folded out of her context, so the act of calling had no in-context
+   * exemplar and she could not emit her first call despite 30 eidoverse
+   * tools riding every request. Placing one first-person pair restored the
+   * capacity. That repair required stop → store surgery → restart; this
+   * method is the live path — and the general lever for demonstrating an
+   * affordance to a model that cannot find it (older models especially).
+   *
+   * Semantics:
+   * - Refused unless the agent is idle: puppeting mid-turn would corrupt
+   *   the turn state machine and the live stream's wire ordering.
+   * - Refused for tools outside the agent's own surface (canUseTool): the
+   *   stored pair must be an act the agent could genuinely have taken.
+   * - The call executes FOR REAL through the shared dispatch (MCPL,
+   *   channel tools, utils, modules) with the agent's provenance — a
+   *   puppeted walk_to actually moves the avatar.
+   * - Storage byte-follows the ordinary path: a bare tool_use assistant
+   *   message (no fabricated thinking or text — a stored assistant turn
+   *   with unverifiable thinking is the labclaude 400 class) plus a
+   *   tool_result under the same bounded spill policy (issue #89).
+   * - Does NOT request inference; the agent sees the pair on its next
+   *   wake. Speak to the agent afterward if a wake is wanted.
+   * - Provenance is loud in traces (puppet:tool-call) and the host log,
+   *   deliberately NOT in the stored messages — metadata there would break
+   *   byte-parity with real turns. Whether to disclose to the resident is
+   *   the operator's call; the princess precedent was disclosed first.
+   */
+  async puppetToolCall(
+    agentName: string,
+    toolName: string,
+    input: Record<string, unknown>,
+  ): Promise<{ toolUseId: string; result: ToolResult }> {
+    const agent = this.agents.get(agentName);
+    if (!agent) throw new Error(`Unknown agent: ${agentName}`);
+    if (agent.state.status !== 'idle') {
+      throw new Error(
+        `puppet refused: agent ${agentName} is ${agent.state.status} (requires idle — ` +
+        `injecting a turn under an active stream corrupts wire ordering)`,
+      );
+    }
+    const onSurface = this.getToolsForAgent(agentName)
+      .some((t) => t.name === toolName && agent.canUseTool(t.name));
+    if (!onSurface) {
+      throw new Error(
+        `puppet refused: tool ${toolName} is not on ${agentName}'s surface — ` +
+        `the stored pair must be an act the agent could genuinely have taken`,
+      );
+    }
+
+    // Anthropic-shaped id so the stored pair is indistinguishable from a
+    // provider-issued call.
+    const alphabet = 'ABCDEFGHJKMNPQRSTVWXYZabcdefghjkmnpqrstvwxyz0123456789';
+    let suffix = '';
+    for (let i = 0; i < 22; i++) suffix += alphabet[Math.floor(Math.random() * alphabet.length)];
+    const toolUseId = `toolu_01${suffix}`;
+
+    const started = Date.now();
+    const result = await this.executeToolCall({
+      id: toolUseId,
+      name: toolName,
+      input,
+      callerAgentName: agentName,
+    });
+    const durationMs = Date.now() - started;
+
+    // Store the pair through the same shapes the ordinary path uses. Build
+    // the result blocks BEFORE storing the tool_use: the spill path awaits,
+    // and a message arriving during that await must land before the pair,
+    // never between tool_use and its tool_result. The two addMessage calls
+    // below are synchronous and adjacent — nothing can interleave.
+    const { blocks } = await this.buildStoredToolResultContent(
+      [{ id: toolUseId, name: toolName, input, result, durationMs }],
+      this.resolveToolResultInlineCap(agent).cap,
+    );
+    const cm = agent.getContextManager();
+    cm.addMessage(agentName, [
+      { type: 'tool_use', id: toolUseId, name: toolName, input } as ContentBlock,
+    ]);
+    cm.addMessage('user', blocks);
+
+    this.emitTrace({
+      type: 'puppet:tool-call',
+      agentName,
+      toolName,
+      toolUseId,
+      isError: !!result.isError,
+      durationMs,
+    });
+    console.log(
+      `[puppet] ${agentName}: ${toolName} → ${result.isError ? 'ERROR' : 'ok'} ` +
+      `in ${durationMs}ms (${toolUseId})`,
+    );
+    return { toolUseId, result };
+  }
+
   private async executeToolCallFrom(call: ToolCall, origin: ChannelToolOrigin): Promise<ToolResult> {
     // Client-side programmatic tool calling for promise-based callers
     // (SubagentModule ephemerals). Keyed by callerAgentName so each ephemeral
@@ -7075,6 +7686,9 @@ export class AgentFramework {
     const blocks: ContentBlock[] = toolResults.map(tc => ({
       type: 'tool_result' as const,
       toolUseId: tc.id,
+      // Persisted so XML replay can reconstruct the legacy <tool_name>
+      // element byte-identically to the live injection.
+      toolName: tc.name,
       content: spilled.get(tc.id)!.text,
       isError: tc.result.isError,
     }));
@@ -7334,7 +7948,7 @@ export class AgentFramework {
   /**
    * Effective tool-result inline cap for an agent, with provenance. Desired
    * value: resident's durable agent_settings value → residence
-   * FrameworkConfig.toolResultInlineMaxChars → house default (5000).
+   * FrameworkConfig.toolResultInlineMaxChars → house default (24000).
    * Effective value: min(desired, strategy bound) for EVERY source — the
    * strategy's per-message safety limit is a ceiling, not a suggestion
    * (Sol's #94 ruling: a durable preference must not be a durable path for
@@ -7836,6 +8450,19 @@ export class AgentFramework {
         name,
         status: agent.state.status,
         consecutiveInferenceFailures: this.consecutiveInferenceFailures.get(name) ?? 0,
+        providerAdmission: (() => {
+          const gate = this.providerGates?.get(name);
+          const cooldown = this.providerAccelerationCooldowns?.get(name);
+          return {
+            primaryActive: (gate?.primaryDepth ?? 0) > 0,
+            primaryPending: gate?.primaryPending ?? false,
+            auxiliaryInFlight: gate?.auxiliaryInFlight ?? 0,
+            auxiliaryDeferred: gate?.deferredAuxiliary ?? 0,
+            cooldownUntil: cooldown?.until ?? null,
+            heldRequests: cooldown?.heldRequests.length ?? 0,
+            lastRecovery: this.providerAccelerationLastRecovery?.get(name) ?? null,
+          };
+        })(),
         lastInference: this.lastInferenceAt.get(name) ?? null,
         refusalStats: this.refusalStats.get(name) ?? null,
       })),
@@ -9886,7 +10513,7 @@ export class AgentFramework {
           if (opened) {
             this.activeTriggerChannels.set(agentName, opened);
             const openerAgent = this.agents.get(agentName);
-            if (openerAgent && openerAgent.proseRouting !== 'explicit') {
+            if (openerAgent && (openerAgent.proseRouting === 'locus' || openerAgent.proseRouting === 'hybrid')) {
               this.turnLocusPins.set(agentName, opened);
               this.lastAnnouncedLocus.set(agentName, opened);
               result = {
@@ -9960,6 +10587,7 @@ export class AgentFramework {
       // range/shape checks.
       const input = (call.input ?? {}) as {
         name?: unknown; match?: unknown; resets?: unknown; position?: unknown;
+        insertBefore?: unknown; insertAfter?: unknown; passthrough?: unknown;
         behavior?: unknown; debounceMs?: unknown; rateLimit?: unknown; passiveSample?: unknown;
       };
       const behaviorSources = [
@@ -9990,17 +10618,72 @@ export class AgentFramework {
         : input.passiveSample !== undefined ? { passive_sample: input.passiveSample }
         : input.behavior;
 
-      const position = input.position === 'prepend' ? 'prepend' : 'append';
+      // Placement: at most one of position / insertBefore / insertAfter.
+      // With none given, a replaced rule stays where it was and a new rule
+      // appends (addPolicy's contract).
+      const placementSources = [
+        input.position !== undefined ? 'position' : null,
+        input.insertBefore !== undefined ? 'insertBefore' : null,
+        input.insertAfter !== undefined ? 'insertAfter' : null,
+      ].filter((s): s is string => s !== null);
+      if (placementSources.length > 1) {
+        finish({
+          success: false,
+          error: `wake_add_rule: give at most one placement, got [${placementSources.join(', ')}].`,
+          isError: true,
+        });
+        return;
+      }
+      let position: 'append' | 'prepend' | { before: string } | { after: string } | undefined;
+      if (typeof input.insertBefore === 'string' && input.insertBefore) {
+        position = { before: input.insertBefore };
+      } else if (typeof input.insertAfter === 'string' && input.insertAfter) {
+        position = { after: input.insertAfter };
+      } else if (input.position === 'prepend' || input.position === 'append') {
+        position = input.position;
+      }
+
       const rawPolicy = {
         name: input.name,
         match: input.match ?? {},
         behavior,
+        ...(input.passthrough !== undefined ? { passthrough: input.passthrough } : {}),
         ...(input.resets !== undefined ? { resets: input.resets } : {}),
       };
-      const policy = this.addGatePolicy(rawPolicy, { position });
+
+      // Before/after probe table + shadow lint: the moment a rule changes the
+      // evaluation order is the moment its real semantics must be legible
+      // (af#105 — a prepended catch-all sampler silently disabled the
+      // addressed-message wakes for 12h before anyone could see why).
+      const before = new Map(
+        this.eventGate!.probeTable().map((r) => [r.probe, r]),
+      );
+      const policy = this.addGatePolicy(rawPolicy, position ? { position } : undefined);
+      const after = this.eventGate!.probeTable();
+      const probes = after.map((r) => {
+        const prev = before.get(r.probe);
+        const changed = !!prev && (prev.policy !== r.policy || prev.wouldWake !== r.wouldWake);
+        return {
+          probe: r.probe,
+          rule: r.policy ?? '(default)',
+          behavior: r.behavior,
+          wouldWake: r.wouldWake,
+          ...(changed ? { changed: true, was: `${prev!.policy ?? '(default)'} (wouldWake=${prev!.wouldWake})` } : {}),
+        };
+      });
+      const shadowWarnings = this.eventGate!.lintShadows()
+        .map((w) => formatShadowWarning(w));
       finish({
         success: true,
-        data: { added: policy.name, policies: this.getGatePolicyNames() },
+        data: {
+          added: policy.name,
+          policies: this.getGatePolicyNames(),
+          ...(shadowWarnings.length > 0 ? { shadowWarnings } : {}),
+          probes,
+          ...(probes.some((p) => 'changed' in p)
+            ? {}
+            : { note: 'No canonical probe changed its winning rule — the new rule affects none of the common chat/heartbeat shapes, or only channel/path-specific events the probes do not model.' }),
+        },
       });
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -10048,7 +10731,9 @@ export class AgentFramework {
     if (announce && this.channelRegistry) {
       const text = input.message ?? `💤 Going quiet for ${human}. I'll still see messages, but won't respond until I wake.`;
       const agent = this.agents.get(agentName);
-      if (agent?.proseRouting === 'explicit') {
+      if (agent?.proseRouting === 'disabled') {
+        console.error(`[sleep] ${agentName}: proseRouting=disabled — sleep announcement not posted`);
+      } else if (agent?.proseRouting === 'explicit') {
         // Explicit mode: announce to the turn's sticky prose target if the
         // model has set one; otherwise stay quiet — never guess a channel.
         const target = this.proseTargetPins.get(agentName);