muonroi-cli 1.8.4 → 1.8.5

package/dist/src/orchestrator/stall-watchdog.js

@@ -70,36 +70,63 @@ export function shouldContinueAfterMidLoopStall(s) {
 export function stallRepromptBackoffMs(attempt) {
     return Math.min(500 * 2 ** (Math.max(1, attempt) - 1), 4_000);
 }
-export function createStallWatchdog(timeoutMs, onFire) {
+export function createStallWatchdog(timeoutMs, onFire, progressOpts) {
     const controller = new AbortController();
     let firedFlag = false;
     let timer = null;
     const enabled = Number.isFinite(timeoutMs) && timeoutMs > 0;
+    const progressTimeoutMs = progressOpts?.progressTimeoutMs ?? 0;
+    const progressEnabled = Number.isFinite(progressTimeoutMs) && progressTimeoutMs > 0;
+    let progressTimer = null;
+    const fire = (onSpecificFire) => {
+        if (firedFlag)
+            return;
+        firedFlag = true;
+        // Stop the OTHER timer so it can't also fire after the abort (e.g. the
+        // any-activity stall timer that was armed just before the progress timer
+        // tripped — otherwise both onFire callbacks would run).
+        clearBoth();
+        // DOMException(TimeoutError) mirrors AbortSignal.timeout() semantics so
+        // downstream isAbortError-style checks treat it as an abort.
+        controller.abort(new DOMException(STALL_ABORT_REASON, "TimeoutError"));
+        try {
+            onSpecificFire?.();
+        }
+        catch {
+            /* callback must not break the watchdog */
+        }
+    };
     const arm = () => {
         if (!enabled)
             return;
-        timer = setTimeout(() => {
-            firedFlag = true;
-            // DOMException(TimeoutError) mirrors AbortSignal.timeout() semantics so
-            // downstream isAbortError-style checks treat it as an abort.
-            controller.abort(new DOMException(STALL_ABORT_REASON, "TimeoutError"));
-            try {
-                onFire?.();
-            }
-            catch {
-                /* callback must not break the watchdog */
-            }
-        }, timeoutMs);
+        timer = setTimeout(() => fire(onFire), timeoutMs);
         // Don't keep the event loop alive solely for the watchdog (Node).
         timer.unref?.();
     };
+    const armProgress = () => {
+        if (!progressEnabled)
+            return;
+        progressTimer = setTimeout(() => fire(progressOpts?.onProgressFire), progressTimeoutMs);
+        progressTimer.unref?.();
+    };
     const clear = () => {
         if (timer) {
             clearTimeout(timer);
             timer = null;
         }
     };
+    const clearProgress = () => {
+        if (progressTimer) {
+            clearTimeout(progressTimer);
+            progressTimer = null;
+        }
+    };
+    function clearBoth() {
+        clear();
+        clearProgress();
+    }
     arm();
+    armProgress();
     return {
         signal: controller.signal,
         pet() {
@@ -108,8 +135,15 @@ export function createStallWatchdog(timeoutMs, onFire) {
             clear();
             arm();
         },
+        petProgress() {
+            if (!progressEnabled || firedFlag)
+                return;
+            clearProgress();
+            armProgress();
+        },
         dispose() {
             clear();
+            clearProgress();
         },
         fired() {
             return firedFlag;

package/dist/src/orchestrator/stream-runner.js

@@ -25,7 +25,7 @@
 //   - C1 (DeepSeek cache split read)        — onFinish normalization
 //   - C3 (cross-turn dedup wrap)            — wrapToolSetWithDedup
 //   - F1 (sub-agent cumulative cap)         — wrapToolSetWithCap
-//   - siliconflow reasoning-strip           — taskCaps.sanitizeHistory
+//   - reasoning-strip (provider quirk)       — taskCaps.sanitizeHistory
 import { stepCountIs, streamText } from "ai";
 import { recordArtifact } from "../ee/artifact-cache.js";
 import { getDefaultEEClient } from "../ee/intercept.js";
@@ -36,14 +36,14 @@ import { injectCheapModelWorkbook, shouldInjectCheapModelWorkbook, subagentTaskT
 import { getProviderCapabilities } from "../providers/capabilities.js";
 import { getVisionGuidanceForTextOnly } from "../providers/mcp-vision-bridge.js";
 import { captureToolSchemas } from "../providers/patch-zod-schema.js";
-import { buildTurnProviderOptions, requireRuntimeProvider, resolveModelRuntime, shouldDropParam, } from "../providers/runtime.js";
+import { buildTurnProviderOptions, requireRuntimeProvider, resolveModelRuntime, resolveTemperatureParam, shouldDropParam, } from "../providers/runtime.js";
 import { needsVisionProxy } from "../providers/vision-proxy.js";
 import { wireDebug } from "../providers/wire-debug.js";
+import { statusBarStore } from "../state/status-bar-store.js";
 import { BashTool } from "../tools/bash.js";
 import { createBuiltinTools } from "../tools/registry.js";
-import { statusBarStore } from "../ui/status-bar/store.js";
 import { openUrl } from "../utils/open-url.js";
-import { getCurrentShellSettings, getProviderStallTimeoutMs, getSubAgentBudgetChars, getSubAgentCompactKeepLast, getSubAgentCompactThresholdChars, loadMcpServers, loadValidSubAgents, } from "../utils/settings.js";
+import { getCurrentShellSettings, getProviderProgressTimeoutMs, getProviderStallTimeoutMs, getSubAgentBudgetChars, getSubAgentCompactKeepLast, getSubAgentCompactThresholdChars, loadMcpServers, loadValidSubAgents, } from "../utils/settings.js";
 import { resolveShell } from "../utils/shell.js";
 import { prepareVerifySandbox } from "../verify/entrypoint.js";
 import { asNumber } from "./batch-utils.js";
@@ -58,7 +58,7 @@ import { attachReminderToMessages, buildScopeReminder, cadenceForSize, shouldInj
 import { recordCompaction, recordElision } from "./session-experience.js";
 import { createStallWatchdog, STALL_ERROR_MESSAGE } from "./stall-watchdog.js";
 import { wrapToolSetWithCap } from "./sub-agent-cap.js";
-import { compactSubAgentMessages, applyAnthropicPromptCaching } from "./subagent-compactor.js";
+import { applyAnthropicPromptCaching, compactSubAgentMessages } from "./subagent-compactor.js";
 import { combineAbortSignals, firstLine, formatSubagentActivity } from "./tool-utils.js";
 /**
  * StreamRunner — extracted sub-agent stream lifecycle.
@@ -137,23 +137,36 @@ export class StreamRunner {
         });
         // Resolve child model early so we can pass modelId to createBuiltinTools
         // (needed for vision-proxy tools: analyze_image / ask_vision_proxy).
-        const childModelId = normalizeModelId(isVision
-            ? VISION_MODEL
-            : isComputer
-                ? COMPUTER_MODEL
-                : custom
-                    ? custom.model
-                    : this.deps.resolveModelForTask(isExplore ? "explore" : isVerify || isVerifyDetect || isVerifyManifest ? "verify" : "general"));
+        const childModelId = normalizeModelId(request.modelId
+            ? request.modelId
+            : isVision
+                ? VISION_MODEL
+                : isComputer
+                    ? COMPUTER_MODEL
+                    : custom
+                        ? custom.model
+                        : this.deps.resolveModelForTask(isExplore ? "explore" : isVerify || isVerifyDetect || isVerifyManifest ? "verify" : "general"));
         // Mirror the file-local `createTools` wrapper from orchestrator.ts —
         // pass modelId so registry can inject analyze_image/ask_vision_proxy for
         // text-only child models (needsVisionProxy).
-        const childBaseToolsRaw = createBuiltinTools(childBash, childMode, { modelId: childModelId });
+        const childBaseToolsRaw = createBuiltinTools(childBash, childMode, {
+            modelId: childModelId,
+            sessionId: this.deps.getSessionId(),
+        });
         // Wrap with the cumulative cap so the sub-agent's tool loop cannot
         // accumulate unbounded tool_result tokens. See sub-agent-cap.ts for the
         // tiered compression schedule. The cap is per-invocation; each sub-agent
         // gets a fresh budget.
         const subAgentCapBudget = getSubAgentBudgetChars();
-        const subAgentCap = wrapToolSetWithCap(childBaseToolsRaw, { maxCumulativeChars: subAgentCapBudget });
+        const subAgentCap = wrapToolSetWithCap(childBaseToolsRaw, {
+            maxCumulativeChars: subAgentCapBudget,
+            // Opt-out toggle (default ON). The cap dedups identical tool outputs by
+            // content hash; set MUONROI_SUBAGENT_CAP_DEDUP=0 to disable. Used by the
+            // B3 compaction E2E, where the harness re-processes each tool result and
+            // the self-dedup would otherwise collapse distinct reads into pointer
+            // stubs before cumulative history can grow enough to trigger compaction.
+            dedupRepeatOutputs: process.env.MUONROI_SUBAGENT_CAP_DEDUP !== "0",
+        });
         // Phase C3: layer cross-turn dedup ON TOP of the per-invocation cap. The
         // cap sees raw output (for accurate cumulative accounting); dedup sees
         // the already-trimmed output that will actually reach the model.
@@ -255,7 +268,7 @@ export class StreamRunner {
         void signal;
         const childMessages = [{ role: "user", content: childPrompt }];
         // The main agent manages its sub-agents, so don't apply an arbitrary hard limit.
-        const maxSteps = request.maxToolRounds ?? (this.deps.getMaxToolRounds() * 2);
+        const maxSteps = request.maxToolRounds ?? this.deps.getMaxToolRounds() * 2;
         // F1 parity — derive per-turn providerOptions so the sub-agent OpenAI calls
         // carry a stable session-derived promptCacheKey (every tool round routes to
         // the same cache node, keeping the unchanging prefix cached). The top-level
@@ -328,7 +341,6 @@ export class StreamRunner {
         // already strips it via `dropParam`, the sub-agent path was missing
         // the same guard, causing G1: "Task failed: No output generated.").
         const childDropMaxOutput = shouldDropParam(childRuntime, "maxOutputTokens");
-        const childDropTemperature = shouldDropParam(childRuntime, "temperature");
         // Phase B3: compact older tool_results out of the running message history
         // before each AI SDK step. First step (stepNumber === 0) has no history
         // worth compacting; later steps are where cumulative input balloons.
@@ -346,8 +358,8 @@ export class StreamRunner {
                 providerOptions: childProviderOptions,
             });
         }
-        // SiliconFlow DeepSeek thinking-mode rejects assistant history with
-        // `reasoning` parts (HTTP 400 code 20015). The siliconflow capability
+        // Some DeepSeek thinking-mode endpoints reject assistant history with
+        // `reasoning` parts (HTTP 400 code 20015). A provider capability
         // override strips them; every other provider's capability is identity.
         const subMessagesForCall = taskCaps.sanitizeHistory(childMessages);
         // Phase 4 Plan 04 (4B) — mirror top-level scope-ceiling integration.
@@ -377,8 +389,26 @@ export class StreamRunner {
         // and is re-armed by stall.pet() on every chunk. Cheap models (which run
         // mostly as sub-agents via SAMR) hit this most.
         let stallTriggered = false;
+        // Second timer (progressTimeoutMs) is the no-forward-progress guard: the
+        // stall timer re-arms on EVERY chunk — including a reasoning model's
+        // `reasoning-delta` chunks — so a sub-agent stuck in an endless
+        // chain-of-thought keeps petting it and it never fires (observed live
+        // 2026-07-10: a deepseek-v4-flash sprint sub-agent churned reasoning for
+        // 30+ min, 1.4M input tokens, ZERO text/tool output; the 2-min stall
+        // watchdog never tripped). The progress timer is reset ONLY by
+        // stall.petProgress() on real output (text-delta / tool-call), so a runaway
+        // reasoning loop is aborted while a legitimately long reasoning burst that
+        // DOES eventually emit output survives. Both timers abort the same signal
+        // and set stallTriggered, so the existing surface-and-return path handles it.
         const stall = createStallWatchdog(getProviderStallTimeoutMs(), () => {
             stallTriggered = true;
+        }, {
+            progressTimeoutMs: getProviderProgressTimeoutMs(),
+            onProgressFire: () => {
+                stallTriggered = true;
+                console.error(`[stream-runner] sub-agent aborted: no text/tool output for ${getProviderProgressTimeoutMs()}ms ` +
+                    `(runaway reasoning / no forward progress) model=${childRuntime.modelId}`);
+            },
         });
         const result = streamText({
             model: childRuntime.model,
@@ -396,11 +426,11 @@ export class StreamRunner {
             prepareStep: ({ messages, stepNumber }) => {
                 if (stepNumber < 1)
                     return undefined;
-                // SiliconFlow internal multi-step loop: AI-SDK accumulates streamed
-                // reasoning parts into in-flight assistant history and re-POSTs them
-                // on the next step within the same streamText call — orchestrator-
-                // level strip at call setup never sees this. Strip per step too via
-                // the capability hook (identity for non-siliconflow providers).
+                // Internal multi-step loop: AI-SDK accumulates streamed reasoning
+                // parts into in-flight assistant history and re-POSTs them on the
+                // next step within the same streamText call — orchestrator-level
+                // strip at call setup never sees this. Strip per step too via the
+                // capability hook (identity for providers without the quirk).
                 const stripped = taskCaps.sanitizeHistory(messages);
                 // G1 + G2 — pass the sub-agent's model context window so the
                 // compactor can use a token-aware threshold and shrink the keep
@@ -428,17 +458,16 @@ export class StreamRunner {
                         break;
                     }
                 }
-                // Idea 4 persist for sub-agent elisions (best-effort; may lack full session but EE can still index the artifact content).
-                const persistSubArtifact = (toolCallId, toolName, fullContent, reason) => {
+                const persistSubArtifact = (toolCallId, toolName, fullContent, reason, summary) => {
                     // Local-first durable cache so ee_query rehydrates even when EE is down.
                     recordArtifact(toolCallId, toolName, fullContent);
-                    recordElision(toolCallId, toolName, fullContent.length, stepNumber);
+                    recordElision(toolCallId, toolName, fullContent.length, stepNumber, summary);
                     try {
                         getDefaultEEClient()
                             .extract({
                             transcript: fullContent.slice(0, 4000),
                             projectPath: process.cwd(),
-                            meta: { source: "tool-artifact", toolCallId, toolName, reason },
+                            meta: { source: "tool-artifact", toolCallId, toolName, reason, summary },
                         }, AbortSignal.timeout(600))
                             .catch(() => { });
                     }
@@ -494,7 +523,7 @@ export class StreamRunner {
                     return undefined;
                 return { messages: finalMessages };
             },
-            ...(childDropTemperature ? {} : { temperature: isExplore ? 0.2 : 0.5 }),
+            ...resolveTemperatureParam(childRuntime, isExplore ? 0.2 : 0.5),
             ...(childDropMaxOutput ? {} : { maxOutputTokens: Math.min(this.deps.getMaxTokens(), 8_192) }),
             ...(childProviderOptions ? { providerOptions: childProviderOptions } : {}),
             onFinish: ({ totalUsage, finishReason }) => {
@@ -557,6 +586,7 @@ export class StreamRunner {
                     });
                 }
                 if (part.type === "text-delta") {
+                    stall.petProgress(); // real forward progress — reset the no-progress guard
                     textDeltaCount++;
                     assistantText += part.text;
                     // Task 2.6b — emit llm-token (agent-mode only; high-volume, default-off per Phase 4).
@@ -576,6 +606,7 @@ export class StreamRunner {
                     continue;
                 }
                 if (part.type === "tool-call") {
+                    stall.petProgress(); // real forward progress — reset the no-progress guard
                     toolCallCount++;
                     lastActivity = formatSubagentActivity(part.toolName, part.input);
                     onActivity?.(lastActivity);
@@ -653,7 +684,9 @@ export class StreamRunner {
                         ...priorMessages,
                         {
                             role: "user",
-                            content: "You've reached your investigation budget and have not written your findings yet. Stop now — do NOT call any more tools. Write your final synthesis FOR THE PARENT AGENT: lead with the answer to the delegated task, cite the concrete file:line behind each claim, then note any gaps or the recommended next step. Be concise; the parent only ingests this message.",
+                            content: "You've reached your tool execution budget (max steps) for this turn and have not written your final answer yet. Stop now — do NOT call any more tools.\n\n" +
+                                "Option A: If you have enough findings, write your final synthesis FOR THE PARENT AGENT: lead with the answer to the delegated task, cite the concrete file:line behind each claim, then note any gaps or the recommended next step. Be concise; the parent only ingests this message.\n\n" +
+                                "Option B: If you need to continue working but are blocked by this limit, you can request the system to compact the context and start a fresh turn. To do this, reply with EXACTLY this format and nothing else:\n/compact <instructions on what to focus on after compaction>",
                         },
                     ],
                     tools: {},

package/dist/src/orchestrator/sub-agent-cap.d.ts

@@ -18,7 +18,19 @@
  * returns a fresh wrapper with its own counters. Don't share across
  * sub-agent runs.
  *
- * Tiers (default 120_000 chars cumulative ≈ ~30k tokens):
+ * BUDGET SOURCE — do not read the 120_000 below as "the sub-agent budget".
+ * DEFAULT_MAX_CUMULATIVE_CHARS (120_000) is only the fallback used when
+ * wrapToolSetWithCap() is called WITHOUT maxCumulativeChars. The wired
+ * budgets come from settings, not this constant:
+ *   - sub-agent (`task`) turns: getSubAgentBudgetChars() → default 240_000
+ *     (settings.ts), passed at stream-runner.ts.
+ *   - top-level orchestrator turn: getTopLevelToolBudgetChars() → default
+ *     400_000, wired at tool-engine.ts with looser 0.5/0.8 tier ratios.
+ * See docs/agent-harness/CONTEXT-CONTROL-LAYERS.md for how this cap relates
+ * to the other four context-control layers (compactor, rotation, reactive
+ * sub-session, top-level cap).
+ *
+ * Tiers (percentages of whichever budget is in effect, NOT of 120_000):
  *   < 30%   → pass through (A1's 32KB per-call cap already applied)
  *   30-70%  → truncate each new result to 8_000 chars head/tail
  *   70-100% → truncate to 2_000 chars head + "[budget low, finalize work]" note

package/dist/src/orchestrator/sub-agent-cap.js

@@ -18,13 +18,28 @@
  * returns a fresh wrapper with its own counters. Don't share across
  * sub-agent runs.
  *
- * Tiers (default 120_000 chars cumulative ≈ ~30k tokens):
+ * BUDGET SOURCE — do not read the 120_000 below as "the sub-agent budget".
+ * DEFAULT_MAX_CUMULATIVE_CHARS (120_000) is only the fallback used when
+ * wrapToolSetWithCap() is called WITHOUT maxCumulativeChars. The wired
+ * budgets come from settings, not this constant:
+ *   - sub-agent (`task`) turns: getSubAgentBudgetChars() → default 240_000
+ *     (settings.ts), passed at stream-runner.ts.
+ *   - top-level orchestrator turn: getTopLevelToolBudgetChars() → default
+ *     400_000, wired at tool-engine.ts with looser 0.5/0.8 tier ratios.
+ * See docs/agent-harness/CONTEXT-CONTROL-LAYERS.md for how this cap relates
+ * to the other four context-control layers (compactor, rotation, reactive
+ * sub-session, top-level cap).
+ *
+ * Tiers (percentages of whichever budget is in effect, NOT of 120_000):
  *   < 30%   → pass through (A1's 32KB per-call cap already applied)
  *   30-70%  → truncate each new result to 8_000 chars head/tail
  *   70-100% → truncate to 2_000 chars head + "[budget low, finalize work]" note
  *   ≥ 100%  → return error stub that signals the agent to stop expanding scope
  */
 import { createHash } from "node:crypto";
+// Fallback ONLY — used when wrapToolSetWithCap gets no maxCumulativeChars.
+// Real wired budgets are 240_000 (sub-agent) / 400_000 (top-level) from
+// settings; see the header note. Keep this in sync only as the no-arg floor.
 const DEFAULT_MAX_CUMULATIVE_CHARS = 120_000;
 const DEFAULT_DEDUP_MIN_CHARS = 500;
 const DEFAULT_MID_TIER_RATIO = 0.3;

package/dist/src/orchestrator/sub-agent-model-tier.d.ts

@@ -9,5 +9,17 @@ export type TierLookup = (tier: "fast" | "balanced" | "premium", preferProvider?
  * Resolve the model id for a task kind on a given provider. Walks the tier
  * preference list, accepting only same-provider matches, and falls back to
  * `fallbackModelId` (the parent model) when nothing matches.
+ *
+ * `opts.parentTier` (the top-level / parent model's tier) acts as a ceiling:
+ * a delegated sub-task never runs on a HIGHER tier than the parent. Without
+ * this cap, a `verify` sub-agent (prefs `["premium","balanced"]`) spawned from
+ * a flash (fast) parent silently promotes to premium — e.g. on a DeepSeek-only
+ * setup (no balanced model) every verify sub-agent lands on deepseek-v4-pro.
+ * The parent already did the hard thinking; the sub-task should not exceed it.
+ *
+ * The cap is skipped when `parentTier` is omitted (preserves legacy behavior
+ * for callers that have not been threaded yet).
  */
-export declare function resolveModelForTask(task: ModelTaskKind, providerId: string, fallbackModelId: string, lookup?: TierLookup): string;
+export declare function resolveModelForTask(task: ModelTaskKind, providerId: string, fallbackModelId: string, lookup?: TierLookup, opts?: {
+    parentTier?: "fast" | "balanced" | "premium";
+}): string;

package/dist/src/orchestrator/sub-agent-model-tier.js

@@ -16,7 +16,7 @@
  *  - verify          : validation/verification → premium first; rigor matters
  *                      more than cost here, so we do NOT downgrade by default.
  */
-import { getModelByTier } from "../models/registry.js";
+import { getRoutedModelByTier } from "../router/peak-hour.js";
 export const TASK_TIER_PREFS = {
     compact: ["fast", "balanced"],
     title: ["fast", "balanced"],
@@ -29,13 +29,27 @@ export const TASK_TIER_PREFS = {
     // exists to perform. Mirrors council `verify` role preference.
     verify: ["premium", "balanced"],
 };
+const TIER_RANK = { fast: 0, balanced: 1, premium: 2 };
 /**
  * Resolve the model id for a task kind on a given provider. Walks the tier
  * preference list, accepting only same-provider matches, and falls back to
  * `fallbackModelId` (the parent model) when nothing matches.
+ *
+ * `opts.parentTier` (the top-level / parent model's tier) acts as a ceiling:
+ * a delegated sub-task never runs on a HIGHER tier than the parent. Without
+ * this cap, a `verify` sub-agent (prefs `["premium","balanced"]`) spawned from
+ * a flash (fast) parent silently promotes to premium — e.g. on a DeepSeek-only
+ * setup (no balanced model) every verify sub-agent lands on deepseek-v4-pro.
+ * The parent already did the hard thinking; the sub-task should not exceed it.
+ *
+ * The cap is skipped when `parentTier` is omitted (preserves legacy behavior
+ * for callers that have not been threaded yet).
  */
-export function resolveModelForTask(task, providerId, fallbackModelId, lookup = getModelByTier) {
+export function resolveModelForTask(task, providerId, fallbackModelId, lookup = getRoutedModelByTier, opts) {
+    const ceilingRank = opts?.parentTier ? TIER_RANK[opts.parentTier] : undefined;
     for (const tier of TASK_TIER_PREFS[task] ?? ["balanced"]) {
+        if (ceilingRank !== undefined && TIER_RANK[tier] > ceilingRank)
+            continue;
         const m = lookup(tier, providerId);
         if (m?.provider === providerId)
             return m.id;

package/dist/src/orchestrator/subagent-compactor.d.ts

@@ -95,7 +95,7 @@ export interface SubAgentCompactorOptions {
      * stub (full raw content available here). Fire-and-forget EE persist under
      * source:"tool-artifact" so layer3/ee.query can later fetch "full tool result id=xxx".
      */
-    persistArtifact?: (toolCallId: string, toolName: string, fullContent: string, reason: string) => void;
+    persistArtifact?: (toolCallId: string, toolName: string, fullContent: string, reason: string, summary?: string) => void;
     /**
      * T1.1 — strip reasoning parts from old assistant turns (older than
      * keepLastTurns). Reasoning tokens (CoT / <think>) from prior turns are
@@ -104,6 +104,18 @@ export interface SubAgentCompactorOptions {
      * models, false otherwise.
      */
     stripOldReasoning?: boolean;
+    /**
+     * O2 — max cumulative chars of the verbatim tail (the last keepLastTurns
+     * turns). The G2 shrink is FILL-ratio based, so on a large-context model a
+     * read-heavy tail (five 8-30k tool results) stays verbatim at only ~50%
+     * fill — pinning every tool round at 60-80k input (measured: July-8 message
+     * calls, 83 in the 60-80k bucket = 44% of message-fresh). When set, keepLast
+     * is reduced further (floor 2) until the kept tail fits this budget,
+     * regardless of fill ratio. High-value results (isHighValueToolResult) are
+     * still kept verbatim independently, so only bulk dumps get stubbed.
+     * Undefined = off (sub-agent path unchanged).
+     */
+    tailBudgetChars?: number;
 }
 /**
  * G1 — coarse char→token conversion. The real ratio is provider/tokenizer
@@ -136,6 +148,7 @@ export declare const HIGH_VALUE_MCP_PREFIXES: readonly ["mcp_muonroi-docs__"];
  */
 export declare function isHighValueToolResult(toolName: string, preview: string, explicitKeepIds?: Set<string>, toolCallId?: string): boolean;
 export declare function cumulativeMessageChars(messages: ReadonlyArray<ModelMessage>): number;
+export declare function buildSlimContext(msgs: ModelMessage[]): ModelMessage[];
 /**
  * Compact a sub-agent message array in place-like fashion. The input is never
  * mutated. When compaction actually elides something a NEW array is returned.
@@ -148,6 +161,45 @@ export declare function cumulativeMessageChars(messages: ReadonlyArray<ModelMess
  * step.
  */
 export declare function compactSubAgentMessages(messages: ReadonlyArray<ModelMessage>, opts?: SubAgentCompactorOptions): ModelMessage[];
+/**
+ * O3 — compaction hysteresis state, threaded across `prepareStep` calls within
+ * a single top-level turn. `frozenCompacted` is the compacted history captured
+ * at the last real compaction; `frozenStrippedLen` is the message count of the
+ * (un-compacted) history at that moment, so the append delta can be recovered.
+ */
+export interface CompactionHysteresisState {
+    frozenCompacted: ModelMessage[] | null;
+    frozenStrippedLen: number;
+    lastCompactTriggerChars: number;
+}
+export declare function initCompactionHysteresisState(): CompactionHysteresisState;
+/**
+ * Decide whether to hold the frozen compacted prefix or (re)compact.
+ *
+ * Re-running the compactor on every step slides the keepLast boundary forward
+ * one tool result per step, flipping that result verbatim→stub and breaking the
+ * provider prompt-cache prefix at its position — measured as 63% of a real
+ * session's FRESH input (session 1afb2728e67a). Between compactions we instead
+ * reuse the frozen compacted prefix and append only the messages added since
+ * (history is append-only within a turn), keeping the cached prefix byte-stable
+ * until cumulative size grows past `lastCompactTriggerChars * hysteresis`.
+ *
+ * Pure: returns the next state rather than mutating. `hysteresis <= 1.0`
+ * disables the freeze (legacy per-step compaction). The delta slice uses the
+ * ORIGINAL (pre-compaction) length, so it is correct whether or not the
+ * compactor preserves message count.
+ */
+export declare function applyCompactionHysteresis(args: {
+    stripped: ModelMessage[];
+    currChars: number;
+    hysteresis: number;
+    state: CompactionHysteresisState;
+    runCompaction: () => ModelMessage[];
+}): {
+    compacted: ModelMessage[];
+    didRecompact: boolean;
+    state: CompactionHysteresisState;
+};
 /**
  * Injects Anthropic prompt caching (cacheControl) into the last message's content
  * block(s) if the model is Claude (starts with 'claude').