@animalabs/agent-framework 0.9.0 → 0.11.0

package/dist/src/framework.js

@@ -13,7 +13,7 @@ import { computeGrant, CapabilityGrant, expandAdvertisementShorthand } from './m
 import { maskNegotiatedCapabilities } from './mcpl/capability-mask.js';
 import { HookOrchestrator } from './mcpl/hook-orchestrator.js';
 import { PushHandler } 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 } from './mcpl/channel-registry.js';
@@ -64,6 +64,8 @@ function sniffImageMediaType(data) {
 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.
@@ -159,6 +161,13 @@ function proseModePrimer(mode) {
         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).
@@ -249,7 +258,7 @@ function validateUtilityArgs(input, schema) {
 }
 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 } from './usage/usage-tracker.js';
 import { formatZonedDateTime, resolveTimeZone } from './timezone.js';
 import { DEFAULT_DISCORD_AWARENESS_EMOJI, DiscordAwarenessOutbox, defaultDiscordAwarenessOutboxPath, extractDiscordAwarenessRefs, } from './recovery/discord-awareness-outbox.js';
@@ -322,6 +331,15 @@ const DEFAULT_SYNC_INTERVAL_MS = 1000;
 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;
+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) {
+    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
@@ -390,6 +408,13 @@ export class AgentFramework {
     maintenanceRunId = 0;
     currentMaintenanceRun = null;
     maintenanceHistory = [];
+    providerGates = new Map();
+    providerAccelerationCooldowns = new Map();
+    providerAccelerationRecoveries = new Map();
+    providerAccelerationLastRecovery = new Map();
+    providerAccelerationDefaultCooldownMs = PROVIDER_ACCELERATION_DEFAULT_COOLDOWN_MS;
+    providerAccelerationJitterMs = PROVIDER_ACCELERATION_JITTER_MS;
+    providerAdmissionClosed = false;
     /** Last time we reported stale (busy-requeued) inference requests, per agent. */
     staleWarnAt = new Map();
     /** Per-agent last inference activity (epoch ms), for /healthz + doctor tooling. */
@@ -459,6 +484,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. */
     proseTargetPins = new Map();
+    /** Hybrid router is fail-closed after a malformed/unresolved envelope until a new valid target. */
+    proseHybridSuppressed = new Set();
     /** Agents whose current turn requested `!` continuation — re-woken when the
      *  turn completes instead of pausing until the next external event. */
     proseContinuations = new Set();
@@ -886,6 +913,7 @@ export class AgentFramework {
             return;
         }
         this.running = true;
+        this.providerAdmissionClosed = false;
         this.loopPromise = this.runLoop();
         // Start periodic sync timer (if enabled)
         if (this.syncIntervalMs > 0) {
@@ -913,6 +941,7 @@ export class AgentFramework {
      */
     async stop() {
         this.running = false;
+        this.providerAdmissionClosed = true;
         this.queue.close();
         // Kill running code_execution scripts before cancelling streams: a
         // zombie script must not keep firing side-effectful tool calls into a
@@ -932,6 +961,8 @@ export class AgentFramework {
             record.runner.dispose();
         }
         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' ||
@@ -988,6 +1019,168 @@ export class AgentFramework {
      * schemas are absent. Passes never overlap; each agent gets a bounded drain
      * so maintenance cannot monopolize the framework event loop.
      */
+    providerGate(agentName) {
+        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;
+    }
+    providerGateBlocked(agentName) {
+        const gate = this.providerGates.get(agentName);
+        return (gate?.primaryDepth ?? 0) > 0 || (gate?.primaryPending ?? false) ||
+            this.providerAccelerationCooldowns.has(agentName);
+    }
+    acquirePrimaryProviderGate(agentName) {
+        const gate = this.providerGate(agentName);
+        gate.primaryPending = false;
+        gate.primaryDepth++;
+    }
+    releasePrimaryProviderGate(agentName) {
+        const gate = this.providerGate(agentName);
+        gate.primaryDepth = Math.max(0, gate.primaryDepth - 1);
+        this.flushAuxiliaryAdmission(agentName);
+    }
+    flushAuxiliaryAdmission(agentName) {
+        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();
+    }
+    async waitForAuxiliaryIdle(agentName) {
+        const gate = this.providerGate(agentName);
+        if (gate.auxiliaryInFlight === 0)
+            return;
+        await new Promise((resolve) => gate.idleWaiters.push(resolve));
+    }
+    async withAuxiliaryAdmission(agentName, run) {
+        const gate = this.providerGate(agentName);
+        if (this.providerGateBlocked(agentName)) {
+            gate.deferredAuxiliary++;
+            try {
+                await new Promise((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();
+        }
+    }
+    auxiliaryMembraneFor(agentName) {
+        const target = this.membrane;
+        return new Proxy(target, { get: (obj, prop, receiver) => {
+                const value = Reflect.get(obj, prop, receiver);
+                if (prop === 'complete' && typeof value === 'function') {
+                    return (...args) => this.withAuxiliaryAdmission(agentName, () => Reflect.apply(value, this.membrane, args));
+                }
+                return typeof value === 'function' ? value.bind(this.membrane) : value;
+            } });
+    }
+    accelerationCooldownMs(agentName, error) {
+        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);
+    }
+    sameInferenceRequest(a, b) {
+        return a.agentName === b.agentName && a.reason === b.reason && a.source === b.source &&
+            a.timestamp === b.timestamp && a.channelId === b.channelId;
+    }
+    holdProviderAcceleration(agent, error, trigger) {
+        if (this.ephemeralRuns.has(agent.name) || this.conversationAgentHomes.has(agent.name) || !isOrganizationAccelerationRateLimit(error))
+            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;
+    }
+    releaseProviderAccelerationCooldown(agentName) {
+        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() }];
+        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)`);
+    }
+    recordProviderAccelerationRecovery(agent, request, stopReason) {
+        const recovery = this.providerAccelerationRecoveries.get(agent.name);
+        if (!recovery?.releasedAt)
+            return;
+        this.providerAccelerationRecoveries.delete(agent.name);
+        const completedAt = Date.now();
+        const receipt = {
+            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 })}`);
+    }
+    cancelProviderAdmission() {
+        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();
+    }
     startQueuedMaintenance() {
         if (this.maintenancePass || !this.running)
             return;
@@ -1007,6 +1200,8 @@ 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;
@@ -1570,8 +1765,10 @@ 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, options) {
         if (!this.eventGate) {
@@ -1904,9 +2101,17 @@ export class AgentFramework {
             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' +
+                '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"]`), ' +
@@ -1973,7 +2178,27 @@ 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',
@@ -3063,7 +3288,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,
         });
         const agent = new Agent(config, contextManager, this.membrane);
@@ -3290,7 +3517,7 @@ export class AgentFramework {
                     // classifier-safe D-class from the 2026-07-24 ablation). It also
                     // updates lastAnnouncedLocus so the next turn's announce-on-change
                     // diffs against what the agent was actually last told.
-                    if (agent.proseRouting !== 'explicit' &&
+                    if ((agent.proseRouting === 'locus' || agent.proseRouting === 'hybrid') &&
                         !shouldEndTurn && !overBudget && currentState.stream) {
                         // Two signals qualify an injection to move the pin (n=6 + n=7):
                         //  - chat:addressed — someone explicitly spoke TO the agent
@@ -3693,6 +3920,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,
         });
@@ -4026,7 +4256,8 @@ export class AgentFramework {
         // Clear pending (we'll re-add if inference doesn't run)
         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.
@@ -4041,6 +4272,29 @@ export class AgentFramework {
                 console.error(`[inference-dropped] agent=${agentName} reason=agent_not_found requests=${requests.length}`);
                 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
@@ -4056,9 +4310,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 (now - oldest > STALE_REQUEST_MS &&
@@ -4095,10 +4354,21 @@ export class AgentFramework {
                 // 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(',')}`);
+                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):
@@ -4177,7 +4447,9 @@ export class AgentFramework {
                 : id);
         }
         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
             ? `[delivered] plain speech → ${shown.join(' · ')}${suppressedNote ? ` · ${suppressedNote}` : ''}`
@@ -4307,6 +4579,98 @@ export class AgentFramework {
             await this.deliverProseEnvelope(agent, envelope.replace(/^\s+(?=>>)/, ''));
         }
     }
+    /** Locus-preserving explicit publication. Source remains byte-identical in Chronicle. */
+    async deliverHybridProse(agent, rawText, locus, allowLocus) {
+        const lines = rawText.split('\n');
+        const envelopes = [];
+        let current = [];
+        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);
+            }
+        }
+    }
     async deliverProseEnvelope(agent, rawText) {
         const name = agent.name;
         const parsed = parseProsePrefix(rawText);
@@ -4365,7 +4729,7 @@ export class AgentFramework {
     }
     /** Cap on consecutive bounce-triggered wakes (notices still append after). */
     static PROSE_BOUNCE_WAKE_CAP = 2;
-    bounceProse(agent, text, reason, candidates) {
+    bounceProse(agent, text, reason, candidates, prefix = '>>') {
         const name = agent.name;
         this.proseClipboards.set(name, text);
         const streak = (this.proseBounceStreaks.get(name) ?? 0) + 1;
@@ -4373,8 +4737,9 @@ export class AgentFramework {
         const cand = candidates?.length ? ` Known channels it could mean: ${candidates.join(', ')}.` : '';
         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
@@ -4437,6 +4802,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', [{ type: 'text', text: proseModePrimer(mode) }], { system: true, kind: 'prose-routing-primer' });
             this.emitTrace({ type: 'message:added', messageId: id, source: 'prose-routing-primer' });
@@ -4446,7 +4818,32 @@ export class AgentFramework {
             console.error('maybePrimeProseMode: failed to append primer:', err);
         }
     }
-    async startAgentStream(agent, trigger, attempt = 0) {
+    async startAgentStream(agent, trigger, attempt = 0, providerGateAlreadyHeld = false) {
+        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
@@ -4467,12 +4864,14 @@ 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);
         }
     }
     /**
@@ -4480,7 +4879,7 @@ export class AgentFramework {
      * turn token unconditionally. Returns true iff the token was handed off to
      * driveStream (whose finally then owns clearing it).
      */
-    async beginAgentTurn(agent, trigger, attempt, turnToken) {
+    async beginAgentTurn(agent, trigger, attempt, turnToken, ownsProviderGate) {
         // Flush messages deferred during the PREVIOUS turn — before the
         // checkpoint, the locus announcement, and the compile — so a turn started
         // by a queued wake actually CONTAINS the message that woke it. (2026-07-31
@@ -4563,10 +4962,13 @@ 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);
@@ -4646,7 +5048,7 @@ export class AgentFramework {
                 }
             }
             const { stream, request: compiledRequest } = await agent.startStreamWithInjections(tools, injections);
-            const handle = this.driveStream(agent, stream, requestSnapshot, trigger, attempt, compiledRequest);
+            const handle = this.driveStream(agent, stream, requestSnapshot, trigger, attempt, compiledRequest, ownsProviderGate);
             this.activeStreams.set(agent.name, handle);
             // Handoff: driveStream captured the token in its synchronous prefix;
             // its finally now owns clearing it. The caller's finally must not.
@@ -4665,6 +5067,12 @@ export class AgentFramework {
                 stack: err.stack,
             });
             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));
@@ -4712,7 +5120,7 @@ export class AgentFramework {
             return false;
         }
     }
-    async driveStream(agent, stream, requestSnapshot, trigger, attempt = 0, compiledRequest) {
+    async driveStream(agent, stream, requestSnapshot, trigger, attempt = 0, compiledRequest, ownsProviderGate = false) {
         const startTime = Date.now();
         const requestId = `${agent.name}-${startTime}-${Math.random().toString(36).slice(2, 8)}`;
         const myStreamId = agent.streamId;
@@ -4769,9 +5177,11 @@ export class AgentFramework {
         //     this doesn't violate never-guess: it says "attending to what you
         //     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();
+        const typingChannel = 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
@@ -4799,9 +5209,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);
@@ -4917,9 +5327,17 @@ 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.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({
@@ -4956,14 +5374,32 @@ export class AgentFramework {
                             const roundToolNames = event.calls.map((c) => c.name);
                             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.
@@ -5051,6 +5487,9 @@ export class AgentFramework {
                         else {
                             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
@@ -5243,7 +5682,21 @@ 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);
@@ -5292,13 +5745,36 @@ export class AgentFramework {
                                 .filter((n) => 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);
                             // Preserve in-channel ordering: everything enqueued live must
                             // land before the trailing prose. Awaited even when silenced —
                             // 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`);
                                     for (const seg of segments) {
@@ -5390,6 +5866,11 @@ export class AgentFramework {
                             break;
                         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));
@@ -5523,10 +6004,21 @@ 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,
@@ -5582,6 +6074,8 @@ 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.
             this.channelRegistry?.stopTyping();
@@ -5640,6 +6134,91 @@ export class AgentFramework {
             agentName: call.callerAgentName ?? '__ephemeral__',
         });
     }
+    /**
+     * 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, toolName, input) {
+        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 },
+        ]);
+        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 };
+    }
     async executeToolCallFrom(call, origin) {
         // Client-side programmatic tool calling for promise-based callers
         // (SubagentModule ephemerals). Keyed by callerAgentName so each ephemeral
@@ -6082,6 +6661,9 @@ export class AgentFramework {
         const blocks = toolResults.map(tc => ({
             type: 'tool_result',
             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,
         }));
@@ -6316,7 +6898,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
@@ -6759,6 +7341,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,
             })),
@@ -8426,7 +9021,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 = {
@@ -8520,17 +9115,70 @@ export class AgentFramework {
                 : input.rateLimit !== undefined ? { rate_limit: input.rateLimit }
                     : 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 !== 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;
+            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) {
@@ -8572,7 +9220,10 @@ 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);