comisai 1.0.36 → 1.0.40

package/node_modules/@comis/agent/dist/executor/pi-executor.js

@@ -1,1202 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * PiExecutor: Wraps pi-coding-agent's createAgentSession() behind the
- * AgentExecutor interface with all Comis safety controls.
- *
- * This is the replacement for the legacy agent-executor.ts. It delegates
- * session management, compaction, and streaming to AgentSession while
- * maintaining Comis's safety controls, event system, and error handling.
- *
- * Integrates:
- * - Circuit breaker: blocks calls when provider is failing
- * - Budget guard: pre-checks cost before each LLM call
- * - Step counter: halts after MAX_STEPS tool executions
- * - PiEventBridge: maps AgentSessionEvent to TypedEventBus
- * - JSONL session adapter: per-session write lock serialization
- * - Orphaned message repair: fixes trailing user messages
- * - System prompt override: via public DefaultResourceLoader.systemPromptOverride API
- * - Model fallback: retries with fallback models on prompt error
- * - Execution bookend log: INFO-level summary stats on every execution
- *
- * @module
- */
-import { createAgentSession, DefaultResourceLoader, } from "@mariozechner/pi-coding-agent";
-import { formatSessionKey, 
-// safePath moved to executor-command-handlers.ts
-tryGetContext, ContextEngineConfigSchema, } from "@comis/core";
-import { suppressError } from "@comis/shared";
-import { createToolRetryBreaker } from "../safety/tool-retry-breaker.js";
-import { createMessageSendLimiter } from "../safety/message-send-limiter.js";
-import { resolveProviderApiKey } from "../model/resolve-provider-api-key.js";
-import { repairOrphanedMessages, scrubPoisonedThinkingBlocks } from "../session/orphaned-message-repair.js";
-import { scrubRedactedToolCalls } from "../session/scrub-redacted-tool-calls.js";
-import { createPiEventBridge } from "../bridge/pi-event-bridge.js";
-import { assertThinkingBlocksUnchanged, restoreCanonicalThinkingBlocks } from "../bridge/thinking-block-hash-invariant.js";
-import { createAdaptiveCacheRetention, createStaticRetention } from "./adaptive-cache-retention.js";
-// SessionLatch types and createSessionLatch moved to executor-session-state.ts
-import { createContextWindowGuard } from "../safety/context-window-guard.js";
-import { composeStreamWrappers } from "./stream-wrappers/index.js";
-import { setupStreamWrappers } from "./executor-stream-setup.js";
-import { resetTrackerTimers } from "./tool-lifecycle.js";
-import { applyCommandDirectives } from "./executor-command-handlers.js";
-import { setupContextEngine } from "./executor-context-engine-setup.js";
-import { runPrompt } from "./executor-prompt-runner.js";
-import { tryInjectSilentFailure } from "./fault-injector.js";
-import { wrapToolResultWithGuide } from "./jit-guide-injector.js";
-import { postExecution } from "./executor-post-execution.js";
-import { assembleTools } from "./executor-tool-assembly.js";
-import { getDeliveredGuides, setDeliveredGuides, setBreakpointIndex, 
-// deleteBreakpointIndex, getBreakpointIndexMapSize moved to executor-post-execution.ts
-setCacheWarm, clearSessionCacheWarm, clearSessionLatches, getCacheBreakDetector, setEvictionCooldown, decrementEvictionCooldown as decrementEvictionCooldownForSession, recordCacheSavings, getCacheSavings, clearSessionCacheSavings, } from "./executor-session-state.js";
-import { validateInput } from "./executor-input-guard.js";
-import { scanWithOutputGuard } from "./executor-response-filter.js";
-import { normalizeModelCompat } from "../provider/model-compat.js";
-import { normalizeModelId } from "../provider/model-id-normalize.js";
-import { isAnthropicFamily, isGoogleFamily, resolveProviderCapabilities } from "../provider/capabilities.js";
-import { detectOnboardingState } from "../workspace/onboarding-detector.js";
-import { PromptTimeoutError } from "./prompt-timeout.js";
-import { classifyError, classifyPromptTimeout } from "./error-classifier.js";
-import { installDagIngestionHook, validateRoleAttribution } from "../context-engine/index.js";
-import { CHARS_PER_TOKEN_RATIO } from "../context-engine/constants.js";
-import { getElapsedSinceLastResponse } from "./ttl-guard.js";
-import { clearSessionBlockStability } from "./block-stability-tracker.js";
-import { wrapToolForAutoBackground } from "../background/index.js";
-import { BackgroundTasksConfigSchema } from "@comis/core";
-import { OPERATION_TIMEOUT_DEFAULTS } from "../model/operation-model-defaults.js";
-import { randomUUID } from "node:crypto";
-/** Number of turns to restrict breakpoints after server eviction. */
-const EVICTION_COOLDOWN_TURNS = 2;
-// ---------------------------------------------------------------------------
-// R-12: Proactive tool-call safety guard
-// ---------------------------------------------------------------------------
-/**
- * Create a beforeToolCall guard that proactively blocks tool execution when
- * safety limits are already reached: step counter exhausted, budget exceeded,
- * or circuit breaker open.
- *
- * Layering: beforeToolCall is PRIMARY (prevents execution).
- * Bridge's reactive checks on tool_execution_end (step counter) and
- * turn_end (budget/circuit breaker) are FALLBACK for limits crossed
- * during execution (e.g., budget consumed by the LLM call that
- * triggered the tool, not the tool itself).
- *
- * Extracted as a named function for independent unit testing.
- */
-export function createBeforeToolCallGuard(stepCounter, budgetGuard, circuitBreaker, toolRetryBreaker, messageSendLimiter) {
-    return async (context, _signal) => {
-        // Proactive step limit check
-        if (stepCounter.shouldHalt()) {
-            return { block: true, reason: "Step limit reached -- blocking tool execution" };
-        }
-        // Proactive budget check (cost 0 = just check remaining budget)
-        const budgetCheck = budgetGuard.checkBudget(0);
-        if (!budgetCheck.ok) {
-            return { block: true, reason: "Token budget exhausted" };
-        }
-        // Proactive circuit breaker check
-        if (circuitBreaker.isOpen()) {
-            return { block: true, reason: "Provider circuit breaker open" };
-        }
-        // Tool retry breaker check -- block tools after repeated failures
-        if (toolRetryBreaker && context && typeof context === "object") {
-            const ctx = context;
-            const toolName = ctx.toolCall?.name;
-            const args = ctx.args;
-            if (toolName && args && typeof args === "object") {
-                const verdict = toolRetryBreaker.beforeToolCall(toolName, args);
-                if (verdict.block) {
-                    return { block: true, reason: verdict.reason ?? "Tool blocked by retry breaker" };
-                }
-            }
-        }
-        // Per-execution message send limiter -- prevent spam
-        if (messageSendLimiter && context && typeof context === "object") {
-            const ctx = context;
-            const toolName = ctx.toolCall?.name;
-            const args = ctx.args;
-            if (toolName && args && typeof args === "object") {
-                const verdict = messageSendLimiter.check(toolName, args);
-                if (verdict)
-                    return verdict;
-            }
-        }
-        return undefined; // allow execution
-    };
-}
-// ---------------------------------------------------------------------------
-// R-13: Session stats delegation helper
-// ---------------------------------------------------------------------------
-/**
- * Merge SDK session stats into execution result for token totals (R-13).
- *
- * Token counts (input, output, cacheRead, cacheWrite, total) are sourced
- * from the SDK's cumulative session stats -- single source of truth.
- * Cost is intentionally NOT overridden: the bridge's `resolveModelPricing()`
- * provides `cacheSaved` and maintains consistency with per-turn
- * `observability:token_usage` events.
- *
- * Exported for independent unit testing.
- */
-export function mergeSessionStats(result, getSessionStats) {
-    if (!getSessionStats)
-        return;
-    try {
-        const stats = getSessionStats();
-        if (stats?.tokens) {
-            result.tokensUsed = {
-                input: stats.tokens.input,
-                output: stats.tokens.output,
-                total: stats.tokens.total,
-                cacheRead: stats.tokens.cacheRead ?? result.tokensUsed.cacheRead,
-                cacheWrite: stats.tokens.cacheWrite ?? result.tokensUsed.cacheWrite,
-            };
-        }
-    }
-    catch {
-        // Non-fatal: fall back to existing bridge-accumulated values.
-        // This can happen if the session was aborted before any LLM calls completed.
-    }
-}
-// ---------------------------------------------------------------------------
-// Timeout cost estimation
-// ---------------------------------------------------------------------------
-// Re-export for backward compatibility with consumers that import from pi-executor.ts
-export { clearSessionDeliveredGuides, clearSessionToolSchemaSnapshot, clearSessionToolSchemaSnapshotHash, clearSessionBreakpointIndex, clearSessionCacheWarm, clearSessionLatches, clearSessionLatches as _clearSessionLatchesForTest, getOrCreateSessionLatches as _getOrCreateSessionLatchesForTest, } from "./executor-session-state.js";
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-/**
- * Create a PiExecutor that wraps pi-coding-agent's AgentSession behind
- * the AgentExecutor interface.
- *
- * @param config - Per-agent configuration including session/compaction settings
- * @param deps - All required dependencies (injected for testability)
- */
-export function createPiExecutor(config, deps) {
-    // Compaction resets lifecycle timers (prevents stale demotion data).
-    // Uses resetTrackerTimers which checks Map membership -- never creates phantom entries.
-    deps.eventBus.on("compaction:flush", (event) => {
-        const key = formatSessionKey(event.sessionKey);
-        if (resetTrackerTimers(key)) {
-            deps.logger.info({ sessionKey: key }, "Tool lifecycle timers reset after compaction");
-        }
-        // Notify cache break detector of compaction (resets baseline).
-        getCacheBreakDetector(deps.logger).notifyCompaction(key);
-        // Reset latches for fresh cache cycle after compaction
-        clearSessionLatches(key);
-    });
-    // Mutable ref for per-execution cache retention override.
-    // Set at execution start, cleared in finally. Read by wrapper chain getter closures.
-    let executionCacheRetention;
-    // Adaptive retention strategy for Anthropic cold-start optimization.
-    // Starts "short" (5m), escalates to "long" (1h) after cache reads confirm utilization.
-    let adaptiveRetention;
-    // Mutable ref for per-execution minTokens override.
-    // Sub-agents use a lower threshold (512) since their short sessions still benefit from caching.
-    let executionMinTokensOverride;
-    return {
-        async execute(msg, sessionKey, tools, onDelta, agentId, _directives, _prevTimestamp, overrides) {
-            // a. Record execution start time
-            const executionStartMs = Date.now();
-            // a-bis. Pre-resolve OAuth token before any pi-coding-agent
-            // dispatch. The setRuntimeApiKey side-effect inside resolveProviderApiKey
-            // carries the token into pi-coding-agent's outbound LLM request via the
-            // runtime-override priority path. For OAuth-eligible
-            // providers (openai-codex, anthropic, github-copilot via pi-ai's
-            // built-in registry) the resolver chain (agent-config -> lastGood ->
-            // first available) runs and refreshes the token if expired. For
-            // non-OAuth providers the helper falls through to authStorage.getApiKey.
-            //
-            // Throw-propagation: on OAuthError the helper throws
-            // an Error containing the OAuthError.message. Outer async callers
-            // (gateway routes via Hono, channel handlers via try/catch) lift the
-            // throw into a user-facing error response. OAuthError
-            // is fatal — no env-var fallback, no retry, no silent rotation.
-            // CLAUDE.md "no empty catch" honored because we don't add a catch
-            // here at all; the resolver itself logs via the oauth-resolver module.
-            await resolveProviderApiKey(config.provider, {
-                authStorage: deps.authStorage,
-                oauthManager: deps.oauthManager,
-                agentConfig: config,
-            });
-            // b. Initialize result
-            const result = {
-                response: "",
-                sessionKey,
-                tokensUsed: { input: 0, output: 0, total: 0 },
-                cost: { total: 0 },
-                stepsExecuted: 0,
-                llmCalls: 0,
-                finishReason: "stop",
-            };
-            // SEP: Initialize execution plan ref (shared with bridge via mutable ref)
-            const sepEnabled = config.sep?.enabled !== false && !overrides?.skipSep;
-            const executionPlanRef = { current: undefined };
-            // : Structural validation, jailbreak scoring, rate limiting
-            // Extracted to executor-input-guard.ts
-            const inputGuardResult = validateInput({
-                msg,
-                sessionKey,
-                agentId,
-                inputValidator: deps.inputValidator,
-                inputGuard: deps.inputGuard,
-                rateLimiter: deps.rateLimiter,
-                eventBus: deps.eventBus,
-                logger: deps.logger,
-            });
-            if (!inputGuardResult.passed) {
-                result.finishReason = (inputGuardResult.earlyFinishReason ?? "error");
-                result.response = inputGuardResult.earlyResponse ?? "";
-                return result;
-            }
-            const safetyReinforcement = inputGuardResult.safetyReinforcement;
-            // c. Provider-level degradation pre-check (before per-agent circuit breaker)
-            if (deps.providerHealth?.isDegraded(config.provider)) {
-                result.finishReason = "provider_degraded";
-                deps.logger.warn({
-                    provider: config.provider,
-                    hint: "Provider is degraded across multiple agents; skipping execution",
-                    errorKind: "dependency",
-                }, "Provider degraded, skipping execution");
-                return result;
-            }
-            // d. Circuit breaker pre-check
-            if (deps.circuitBreaker.isOpen()) {
-                result.finishReason = "circuit_open";
-                deps.logger.warn({
-                    hint: "Circuit breaker is open, skipping execution",
-                    errorKind: "dependency",
-                }, "Circuit breaker open");
-                return result;
-            }
-            // d'. Test-only silent-LLM-failure fault injection.
-            // Gated by COMIS_TEST_SILENT_FAIL_FLAG env var. Lets operators validate
-            // the FINDING-2 retry/reuseSessionKey path end-to-end without waiting
-            // for real Anthropic instability. Env var is absent in all shipped
-            // configs; see packages/agent/src/executor/fault-injector.ts for the
-            // safety analysis.
-            {
-                const injection = tryInjectSilentFailure(deps.logger, {
-                    agentId,
-                    sessionKey: formatSessionKey(sessionKey),
-                });
-                if (injection) {
-                    result.finishReason = injection.finishReason;
-                    result.response = injection.response;
-                    result.llmCalls = injection.llmCalls;
-                    result.stepsExecuted = injection.stepsExecuted;
-                    return result;
-                }
-            }
-            // d. Reset per-execution state
-            // Capture execution overrides before local SettingsOverrides shadows the name
-            const executionOverrides = overrides;
-            // Per-execution cache retention override (mutable ref read by wrapper chain getter)
-            executionCacheRetention = executionOverrides?.cacheRetention;
-            // Per-operation timeout merge.
-            // 3-tier priority: explicit override > OPERATION_TIMEOUT_DEFAULTS[operationType] > agent-level config.
-            const operationDefaultTimeout = executionOverrides?.operationType
-                ? OPERATION_TIMEOUT_DEFAULTS[executionOverrides.operationType]
-                : undefined;
-            const effectiveTimeout = {
-                promptTimeoutMs: executionOverrides?.promptTimeout?.promptTimeoutMs
-                    ?? operationDefaultTimeout
-                    ?? config.promptTimeout.promptTimeoutMs,
-                retryPromptTimeoutMs: executionOverrides?.promptTimeout?.retryPromptTimeoutMs
-                    ?? config.promptTimeout.retryPromptTimeoutMs,
-            };
-            // Create adaptive retention.
-            // Parent agents start at configRetention directly (typically "long"/1h) so the
-            // initial system prompt write gets 1h TTL -- surviving gaps >5m (e.g. graph execution).
-            // Sub-agents start at "short" (5m) since they complete in <60s and share prefix via stagger.
-            // Session-scoped warm state is still useful for escalation tracking (onEscalated callback).
-            const configRetention = executionCacheRetention ?? config.cacheRetention;
-            if (configRetention && configRetention !== "none") {
-                const formattedKeyForRetention = formatSessionKey(sessionKey);
-                const isSubAgent = !!executionOverrides?.spawnPacket;
-                // + Design 2.2: Sub-agents use static retention. Graph subagents
-                // (cacheRetention: "long" from setup-cross-session) get static "long" --
-                // they never escalate but get 1h TTL. Non-graph subagents get static "short".
-                // Design 2.4: Parent agents use turn-based escalation (3+ turns required).
-                const configRetentionForSubagent = (executionOverrides?.cacheRetention ?? "short");
-                adaptiveRetention = isSubAgent
-                    ? createStaticRetention(configRetentionForSubagent)
-                    : createAdaptiveCacheRetention({
-                        coldStartRetention: configRetention,
-                        warmRetention: configRetention,
-                        escalationThreshold: 1000,
-                        onEscalated: () => setCacheWarm(formattedKeyForRetention, true),
-                    });
-            }
-            else {
-                adaptiveRetention = undefined;
-            }
-            // Lower threshold for parent agents (1024) to enable message breakpoints.
-            // Parent conversations have 500-2000 token messages -- 4096 default is too high.
-            // Sub-agents: 512 (short sessions, system prompt dominates).
-            executionMinTokensOverride = executionOverrides?.spawnPacket ? 512 : 1024;
-            const activeStepCounter = executionOverrides?.stepCounter ?? deps.stepCounter;
-            activeStepCounter.reset();
-            deps.budgetGuard.resetExecution();
-            // e. Resolve model using ModelRegistry
-            // Apply per-node model override from ExecutionOverrides and normalize shortcuts before registry lookup
-            const normalizedPrimary = normalizeModelId(config.provider, config.model);
-            let resolvedModel = deps.modelRegistry.find(config.provider, normalizedPrimary.modelId);
-            if (!resolvedModel && deps.providerAliases) {
-                const builtInName = deps.providerAliases.get(config.provider);
-                if (builtInName) {
-                    resolvedModel = deps.modelRegistry.find(builtInName, normalizedPrimary.modelId);
-                }
-            }
-            if (normalizedPrimary.normalized) {
-                deps.logger.debug({ original: config.model, resolved: normalizedPrimary.modelId }, "Model ID normalized via shortcut");
-            }
-            if (!resolvedModel
-                && config.provider.toLowerCase() !== "default"
-                && config.model.toLowerCase() !== "default") {
-                deps.logger.warn({
-                    agentId,
-                    configuredProvider: config.provider,
-                    configuredModel: normalizedPrimary.modelId,
-                    hint: "Provider not registered in pi ModelRegistry. Check providers.entries.<name> in config.yaml has type/baseUrl/apiKeyName set, the API key resolves via SecretManager, and the provider is enabled. Without a match, pi-coding-agent silently falls back to whatever built-in provider has env-var credentials.",
-                    errorKind: "config",
-                }, "Configured provider/model not found in registry; pi-coding-agent will fall back");
-            }
-            if (executionOverrides?.model) {
-                // Model override format: "provider:modelId" (same as compactionModel pattern)
-                const parts = executionOverrides.model.split(":");
-                const overrideProvider = parts[0];
-                const overrideModelId = parts.slice(1).join(":"); // Handle model IDs with colons
-                if (overrideProvider && overrideModelId) {
-                    // Normalize override model ID before registry lookup
-                    const normalizedOverride = normalizeModelId(overrideProvider, overrideModelId);
-                    const overrideResolved = deps.modelRegistry.find(overrideProvider, normalizedOverride.modelId);
-                    if (normalizedOverride.normalized) {
-                        deps.logger.debug({ original: overrideModelId, resolved: normalizedOverride.modelId }, "Override model ID normalized via shortcut");
-                    }
-                    if (overrideResolved) {
-                        resolvedModel = overrideResolved;
-                        deps.logger.info({ defaultModel: config.model, overrideModel: executionOverrides.model }, "Model override applied from execution overrides");
-                    }
-                    else {
-                        deps.logger.warn({
-                            overrideModel: executionOverrides.model,
-                            provider: overrideProvider,
-                            modelId: overrideModelId,
-                            hint: "Model override not found in registry; falling back to agent default model",
-                            errorKind: "config",
-                        }, "Model override resolution failed");
-                    }
-                }
-            }
-            // Store resolved model on ALS context for sub-agent parent inheritance
-            const alsCtx = tryGetContext();
-            if (alsCtx && resolvedModel) {
-                alsCtx.resolvedModel = `${resolvedModel.provider}:${resolvedModel.id}`;
-            }
-            // Derive compat config via normalizeModelCompat (xAI auto-detection).
-            // Model<Api> from pi-ai has no comisCompat field -- normalizeModelCompat() provides it.
-            const modelCompat = resolvedModel ? normalizeModelCompat({
-                provider: resolvedModel.provider,
-                id: resolvedModel.id,
-            }) : undefined;
-            // f. Execute within session adapter (R-11: use ephemeral adapter if provided)
-            const sessionAdapter = overrides?.ephemeralSessionAdapter ?? deps.sessionAdapter;
-            const lockResult = await sessionAdapter.withSession(sessionKey, async (sm) => {
-                // Repair orphaned messages
-                const repairResult = repairOrphanedMessages(sm);
-                if (repairResult.repaired) {
-                    deps.logger.info({ reason: repairResult.reason }, "Repaired orphaned message");
-                }
-                // One-time scrub for sessions poisoned by an earlier on-disk thinking-signature stripper.
-                // Must run before buildSessionContext so the context pipeline sees the clean fileEntries.
-                const scrubResult = scrubPoisonedThinkingBlocks(sm);
-                if (scrubResult.scrubbed) {
-                    deps.logger.info({ blocksRemoved: scrubResult.blocksRemoved }, "Scrubbed poisoned thinking blocks");
-                }
-                // Neutralize tool_use/tool_result pairs whose args were redacted by
-                // sanitizeSessionSecrets. Must run before buildSessionContext so the
-                // model never sees its own prior env_set tool calls with
-                // env_value:"[REDACTED]" (which it would otherwise copy forward into
-                // the next env_set call — observed in production).
-                const redactScrub = scrubRedactedToolCalls(sm);
-                if (redactScrub.scrubbed) {
-                    deps.logger.info({
-                        blocksRewritten: redactScrub.blocksRewritten,
-                        resultsRewritten: redactScrub.resultsRewritten,
-                    }, "Scrubbed redacted tool-call pairs from replay context");
-                }
-                // Detect first message in session for BOOT.md injection
-                const sessionContext = sm.buildSessionContext();
-                // Diagnostic assertion -- detect role attribution anomalies
-                // in continued sessions. Fires WARN log only; repair is handled by
-                // repairOrphanedMessages() above.
-                validateRoleAttribution(sessionContext.messages, deps.logger);
-                const isFirstMessageInSession = sessionContext.messages.length === 0;
-                // Get or create session-scoped guide delivery tracking.
-                // Clear on session reset (isFirstMessageInSession) so guides re-inject.
-                const formattedKeyForGuides = formatSessionKey(sessionKey);
-                let deliveredGuides = getDeliveredGuides(formattedKeyForGuides);
-                if (!deliveredGuides || isFirstMessageInSession) {
-                    deliveredGuides = new Set();
-                    setDeliveredGuides(formattedKeyForGuides, deliveredGuides);
-                }
-                // Detect onboarding state for post-execution completion check
-                const isOnboarding = await detectOnboardingState(deps.workspaceDir);
-                // Capture prompt skills XML once at execution start.
-                // Skills registered during tool calls (e.g., skill-creator creating stock-scanner)
-                // do not mutate the system prompt until the next execution.
-                const frozenPromptSkillsXml = deps.getPromptSkillsXml?.();
-                const stableGetPromptSkillsXml = frozenPromptSkillsXml !== undefined
-                    ? () => frozenPromptSkillsXml
-                    : deps.getPromptSkillsXml;
-                const frozenDeps = { ...deps, getPromptSkillsXml: stableGetPromptSkillsXml };
-                // Tool assembly pipeline: merge, settings, prompt, deferral, JIT, pruning, snapshot, normalization, serializer
-                // Extracted to executor-tool-assembly.ts
-                const toolAssembly = await assembleTools({
-                    config, deps: frozenDeps, sessionKey, msg, tools, executionOverrides,
-                    isFirstMessageInSession, sm, formattedKeyForGuides, deliveredGuides,
-                    resolvedModel, modelCompat, agentId, safetyReinforcement, _directives,
-                });
-                const { mergedCustomTools, } = toolAssembly;
-                const { deferralResult, deferredContext, modelTier, discoveryTracker, settingsManager, resourceLoaderOptions, promptResult, cachedSystemTokensEstimate, } = toolAssembly;
-                const currentDiscoveryTracker = toolAssembly.currentDiscoveryTracker;
-                const { systemPrompt, systemPromptBlocks, dynamicPreamble, inlineMemory } = promptResult;
-                // DAG ingestion hook -- install BEFORE microcompaction
-                // so microcompaction is the outer wrapper. Execution order: microcompaction first -> DAG ingest second.
-                // DAG ingest receives the post-microcompaction message (with disk offload references).
-                const baseContextEngineConfigForHook = config.contextEngine ?? ContextEngineConfigSchema.parse({});
-                if (baseContextEngineConfigForHook.version === "dag" && deps.contextStore) {
-                    const tenantId = deps.tenantId ?? "default";
-                    const hookFormattedKey = formatSessionKey(sessionKey);
-                    const existingConv = deps.contextStore.getConversationBySession(tenantId, hookFormattedKey);
-                    let hookConversationId;
-                    if (existingConv) {
-                        hookConversationId = existingConv.conversation_id;
-                    }
-                    else {
-                        hookConversationId = deps.contextStore.createConversation({
-                            tenantId,
-                            agentId: agentId ?? config.name,
-                            sessionKey: hookFormattedKey,
-                        });
-                    }
-                    // Store for later use by context engine
-                    sm.__dagConversationId = hookConversationId;
-                    installDagIngestionHook(sm, deps.contextStore, hookConversationId, deps.logger, (text) => Math.ceil(text.length / CHARS_PER_TOKEN_RATIO));
-                }
-                const resourceLoader = new DefaultResourceLoader(resourceLoaderOptions);
-                await resourceLoader.reload();
-                // The SDK's `tools` is an allowlist of tool *names* (not definitions).
-                // An empty array is treated as a non-empty allowlist that allows zero
-                // tools, including all customTools — which is why the agent ran
-                // tool-less from every entry point (chat API, SSE, Telegram, etc.):
-                // every Comis tool was filtered out of the SDK's tool registry, the
-                // Anthropic API request went out with `tools: []`, and the model
-                // emitted `<tool_call>...</tool_call>` markup as plaintext that
-                // Comis's loop never parsed back.
-                //
-                // Pass our customTool names as the explicit allowlist so:
-                //   1. All customTools land in the SDK's tool registry (their names
-                //      pass `isAllowedTool`).
-                //   2. SDK built-ins like `bash` that conflict with Comis's policy
-                //      controls are filtered out (Comis uses `exec` instead, with
-                //      its own sandbox/audit hooks).
-                //   3. Where names overlap (read/edit/write), Comis's customTools
-                //      override the SDK built-ins via Map.set() in the registry
-                //      build (`agent-session.js:1810-1813` in pi-coding-agent@0.68.0).
-                const sessionOptions = {
-                    cwd: deps.workspaceDir,
-                    authStorage: deps.authStorage,
-                    modelRegistry: deps.modelRegistry,
-                    model: resolvedModel ?? undefined,
-                    sessionManager: sm,
-                    settingsManager,
-                    resourceLoader,
-                    tools: mergedCustomTools.map((t) => t.name),
-                    customTools: mergedCustomTools,
-                };
-                const { session, modelFallbackMessage } = await createAgentSession(sessionOptions);
-                if (modelFallbackMessage) {
-                    deps.logger.warn({ hint: modelFallbackMessage, errorKind: "config" }, "SDK model fallback during session creation");
-                }
-                // Compute formatted key early for trace file paths and active run registry
-                const formattedKey = formatSessionKey(sessionKey);
-                // Per-execution tool retry breaker (state resets each message)
-                const toolRetryBreakerConfig = config.toolRetryBreaker;
-                const toolRetryBreaker = toolRetryBreakerConfig?.enabled !== false
-                    ? createToolRetryBreaker({
-                        maxConsecutiveFailures: toolRetryBreakerConfig?.maxConsecutiveFailures ?? 3,
-                        maxToolFailures: toolRetryBreakerConfig?.maxToolFailures ?? 5,
-                        suggestAlternatives: toolRetryBreakerConfig?.suggestAlternatives ?? true,
-                    })
-                    : undefined;
-                // Per-execution message send limiter
-                // maxSendsPerExecution lives in global MessagesConfigSchema (AppConfig.messages),
-                // not PerAgentConfig. Use deps injection or default (3).
-                const messageSendLimiter = createMessageSendLimiter({
-                    maxSendsPerExecution: deps.maxSendsPerExecution ?? 3,
-                });
-                // R-12: Proactive safety -- block tool execution before it starts
-                // when safety limits are already reached. Existing reactive checks in
-                // pi-event-bridge remain as fallback for limits crossed during execution.
-                // NOTE: beforeToolCall replaces the extension runner's hook. Comis does
-                // not load pi-mono extensions, so this override is safe.
-                // v0.65.0: setBeforeToolCall() removed; beforeToolCall is now a direct property.
-                session.agent.beforeToolCall =
-                    createBeforeToolCallGuard(activeStepCounter, deps.budgetGuard, deps.circuitBreaker, toolRetryBreaker, messageSendLimiter);
-                // Mid-turn tool injection -- when discover_tools returns sideEffects.discoveredTools,
-                // inject the full ToolDefinitions into the live agentic loop tools array so the LLM can
-                // call them in the same turn (not just the next message).
-                session.agent.afterToolCall = async (ctx) => {
-                    const sideEffects = ctx.result?.sideEffects;
-                    if (!sideEffects?.discoveredTools?.length)
-                        return undefined;
-                    const contextTools = ctx.context.tools;
-                    if (!contextTools)
-                        return undefined;
-                    // Skip mid-turn injection for providers without explicit cache control.
-                    // Discovery state is already persisted via markDiscovered() in the tool execution
-                    // wrapper. Next execution includes these tools via applyToolDeferral() -> isDiscovered().
-                    if (!resolvedModel || (!isAnthropicFamily(resolvedModel.provider) && !isGoogleFamily(resolvedModel.provider))) {
-                        deps.logger.debug({ discoveredCount: sideEffects.discoveredTools.length, provider: resolvedModel?.provider }, "Skipped mid-turn injection (provider uses automatic prefix caching)");
-                        return undefined;
-                    }
-                    let injectedCount = 0;
-                    for (const name of sideEffects.discoveredTools) {
-                        // Skip if already in the live tools array
-                        if (contextTools.some((t) => t.name === name))
-                            continue;
-                        // Look up the full ToolDefinition from deferralResult.deferredEntries
-                        const entry = deferralResult.deferredEntries.find(e => e.name === name);
-                        if (!entry)
-                            continue;
-                        // Create AgentTool-compatible wrapper and push into the live array.
-                        // The agentic loop's currentContext.tools is this same array reference,
-                        // so pushed tools are immediately findable by agent-loop.js prepareToolCall().
-                        //
-                        // IMPORTANT: the execute() closure routes the result through
-                        // wrapToolResultWithGuide so deferred tools (agents_manage,
-                        // sessions_spawn, MCP tools, ...) receive their TOOL_GUIDES entry
-                        // on first successful call. The session-start createJitGuideWrapper
-                        // only wrapped tools present then; without this, discovered tools
-                        // silently skipped their guides. Uses the same deliveredGuides Set
-                        // as the session-start wrapper so the "once per session" contract
-                        // holds whether the tool arrives initially or via discover_tools.
-                        const original = entry.original;
-                        contextTools.push({
-                            name: original.name,
-                            label: original.label,
-                            description: original.description,
-                            parameters: original.parameters,
-                            execute: async (toolCallId, params, signal, onUpdate) => {
-                                const res = await original.execute(toolCallId, params, signal, onUpdate, undefined);
-                                return wrapToolResultWithGuide(original.name, res, deliveredGuides, deps.logger);
-                            },
-                        });
-                        injectedCount++;
-                    }
-                    if (injectedCount > 0) {
-                        deps.logger.info({ injectedCount, discoveredTools: sideEffects.discoveredTools, toolName: ctx.toolCall.name }, "Mid-turn tool injection -- discovered tools added to live agentic loop");
-                    }
-                    return undefined; // No result modification needed
-                };
-                // Stream wrapper chain composition (extracted to executor-stream-setup.ts)
-                // Gemini cache hit tracking for Execution complete log
-                let geminiCacheHit = false;
-                let geminiCachedTokens = 0;
-                const streamSetup = setupStreamWrappers({
-                    config, deps, sessionKey, formattedKey, sm,
-                    resolvedModel, modelTier, executionOverrides,
-                    deferralResult, systemPromptBlocks, agentId,
-                    getAdaptiveRetention: () => adaptiveRetention,
-                    getExecutionCacheRetention: () => executionCacheRetention,
-                    getExecutionMinTokensOverride: () => executionMinTokensOverride,
-                    onBreakpointsPlaced: (highestIdx) => {
-                        const trimOffset = streamSetup.contextEngineRef.current?.lastTrimOffset ?? 0;
-                        const preCeIdx = highestIdx + trimOffset;
-                        if (streamSetup.contextEngineRef.current) {
-                            streamSetup.contextEngineRef.current.lastBreakpointIndex = preCeIdx;
-                        }
-                        setBreakpointIndex(formattedKey, preCeIdx);
-                    },
-                    onGeminiCacheHit: (entry) => {
-                        geminiCacheHit = true;
-                        geminiCachedTokens = entry.cachedTokens;
-                    },
-                });
-                const { contextEngineRef, cacheBreakDetector, truncationMetaRegistry, getTruncationSummary, getTurnBudgetSummary, ttlSplit, } = streamSetup;
-                session.agent.streamFn = composeStreamWrappers(streamSetup.wrappers, session.agent.streamFn, deps.logger);
-                // Context engine: transformContext hook
-                // Runs BEFORE convertToLlm in the SDK pipeline (pre-LLM-call context management).
-                // Same runtime override pattern as streamFn above.
-                // TypeScript declares transformContext as private, but it's a plain instance property
-                // accessible at runtime. Same pattern as streamFn override above (line ~651).
-                const ceSetup = setupContextEngine({
-                    config, deps: frozenDeps, formattedKey, sessionKey: formattedKey, msg, sm, session,
-                    resolvedModel, executionOverrides,
-                    cacheBreakDetector,
-                    contextEngineRef,
-                    getCachedSystemTokensEstimate: () => cachedSystemTokensEstimate,
-                    getTokenAnchor: () => tokenAnchor,
-                    onAnchorReset: () => { tokenAnchor = null; },
-                    currentDiscoveryTracker,
-                });
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK internal: no public type for agent.transformContext
-                session.agent.transformContext = ceSetup.contextEngine.transformContext;
-                // Freeze thinking block stripping threshold for this execution.
-                // On the first transformContext call, snapshot the pre-execution assistant count
-                // as a ceiling so new assistant turns during the agentic loop don't shift the
-                // stripping cutoff. Cleared in the finally block.
-                if (ceSetup?.contextEngine?.setThinkingCeiling) {
-                    let ceilingSet = false;
-                    const originalTransform = ceSetup.contextEngine.transformContext;
-                    ceSetup.contextEngine.transformContext = async (messages, signal) => {
-                        if (!ceilingSet) {
-                            const assistantCount = messages.filter((m) => m.role === "assistant").length;
-                            ceSetup.contextEngine.setThinkingCeiling(assistantCount);
-                            ceilingSet = true;
-                        }
-                        return originalTransform(messages, signal);
-                    };
-                    // Re-assign to session.agent so the SDK calls the wrapped version
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    session.agent.transformContext = ceSetup.contextEngine.transformContext;
-                }
-                // Register active run for mid-execution steering
-                if (deps.activeRunRegistry) {
-                    const handle = {
-                        steer: (text) => session.steer(text),
-                        followUp: (text) => session.followUp(text),
-                        abort: async () => { session.abortCompaction(); await session.abort(); },
-                        isStreaming: () => session.isStreaming,
-                        isCompacting: () => session.isCompacting,
-                    };
-                    const registered = deps.activeRunRegistry.register(formattedKey, handle);
-                    if (!registered) {
-                        deps.logger.warn({ sessionKey: formattedKey, hint: "Session already has an active run; concurrent execution may cause issues", errorKind: "resource" }, "Active run already registered");
-                    }
-                }
-                // SDK tool management validation and introspection.
-                // Comis assembles tools per-request (platform tools, skill tools, policy filtering).
-                // After session creation, we use SDK APIs to validate registration and provide
-                // debug introspection. setActiveToolsByName() is safe here because
-                // systemPromptOverride on DefaultResourceLoader caches the Comis-assembled
-                // prompt during reload(), and _rebuildSystemPrompt reads it on every rebuild.
-                try {
-                    const allSdkTools = session.getAllTools?.() ?? [];
-                    const activeToolNames = session.getActiveToolNames?.() ?? [];
-                    const mergedToolNames = mergedCustomTools.map(t => t.name);
-                    deps.logger.debug({
-                        sdkRegisteredCount: allSdkTools.length,
-                        activeCount: activeToolNames.length,
-                        comisCount: mergedToolNames.length,
-                    }, "SDK tool registry introspection");
-                    const allSdkToolNames = allSdkTools.map(t => t.name);
-                    const ghostTools = allSdkToolNames.filter(n => !mergedToolNames.includes(n));
-                    const missingTools = mergedToolNames.filter(n => !allSdkToolNames.includes(n));
-                    if (ghostTools.length > 0 || missingTools.length > 0) {
-                        deps.logger.debug({
-                            ghostTools,
-                            missingTools,
-                            hint: "ghostTools = in SDK but not Comis (e.g. SDK base bash); missingTools = in Comis but not SDK",
-                        }, "SDK/Comis tool set mismatch diagnostic");
-                    }
-                    // Validate: call setActiveToolsByName with our tool set.
-                    // This confirms SDK recognizes all tools and updates agent.tools.
-                    // systemPromptOverride on DefaultResourceLoader prevents prompt clobbering.
-                    session.setActiveToolsByName?.(mergedToolNames);
-                    // Check for SDK-filtered tools (tools Comis registered but SDK rejected)
-                    const postActiveNames = session.getActiveToolNames?.() ?? [];
-                    if (postActiveNames.length < mergedToolNames.length) {
-                        const rejected = mergedToolNames.filter(n => !postActiveNames.includes(n));
-                        const allRejected = postActiveNames.length === 0 && rejected.length === mergedToolNames.length;
-                        deps.logger.warn({
-                            rejected,
-                            rejectedCount: rejected.length,
-                            registeredCount: mergedToolNames.length,
-                            postActiveCount: postActiveNames.length,
-                            allRejected,
-                            hint: allRejected
-                                ? "SDK has 0 active tools after setActiveToolsByName -- not a name collision (empty active list, every Comis tool dropped). Indicates the SDK ResourceLoader / agent.tools handoff is broken; the LLM will receive no structured tool definitions and may emit `<tool_call>` markup as plaintext instead of using tool_use content blocks."
-                                : "SDK filtered some Comis tools; likely name collisions with SDK built-ins (e.g. SDK reserves `bash`, `read_file`, etc.). Rename or omit the listed tools to avoid the conflict.",
-                            errorKind: "validation",
-                        }, allRejected
-                            ? "SDK rejected ALL tool registrations -- agent will run with no tools"
-                            : "SDK rejected some tool registrations");
-                    }
-                }
-                catch (toolMgmtError) {
-                    // Non-fatal: SDK tool management is validation/introspection only.
-                    // Comis's tool pipeline already registered tools via customTools.
-                    deps.logger.debug({ err: toolMgmtError }, "SDK tool management call failed (non-fatal)");
-                }
-                // Populate Comis registry from SDK-discovered skills.
-                // After session creation, the ResourceLoader has discovered skills from
-                // Comis's configured paths. We populate the registry so that content
-                // scanning, audit, and progressive disclosure work on SDK-discovered skills.
-                try {
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK internal API not typed
-                    const sdkSkillResult = sessionOptions.resourceLoader?.getSkills?.();
-                    const sdkSkills = sdkSkillResult?.skills;
-                    if (sdkSkills && sdkSkills.length > 0 && deps.skillRegistry) {
-                        deps.skillRegistry.initFromSdkSkills(sdkSkills);
-                        deps.logger.debug({ sdkSkillCount: sdkSkills.length }, "Comis registry populated from SDK discovery");
-                    }
-                }
-                catch (sdkSkillError) {
-                    deps.logger.debug({ err: sdkSkillError, hint: "SDK skill population failed, Comis discovery still active", errorKind: "dependency" }, "SDK skill population non-fatal error");
-                }
-                // session.sendCustomMessage() is available for operator annotations.
-                // REQUIREMENTS.md refers to appendCustomEntry() which is the SessionManager-level API;
-                // the AgentSession wrapper exposes this as sendCustomMessage({ customType, content, display, details }).
-                // Future commands or hooks can call this to inject custom entries into the JSONL session.
-                // Apply command directives (thinking, compact, model, export, fork, branch)
-                const cmdResult = await applyCommandDirectives({
-                    directives: _directives,
-                    session: session,
-                    result, config, deps, sessionKey,
-                });
-                // Create context guard from per-agent config
-                const contextGuardConfig = config.contextGuard;
-                const contextGuard = contextGuardConfig?.enabled !== false
-                    ? createContextWindowGuard({
-                        warnPercent: contextGuardConfig?.warnPercent,
-                        blockPercent: contextGuardConfig?.blockPercent,
-                    })
-                    : undefined;
-                // Quick 215: Resettable prompt timeout -- tool completions reset the timer
-                let currentResetTimer;
-                // API-grounded token anchor -- updated on each turn_end, reset on compaction
-                let tokenAnchor = null;
-                // Create event bridge
-                // Capture for bridge closures (separate scope from wrapper closures above).
-                const capturedBridgeRetention = adaptiveRetention;
-                const executionId = randomUUID();
-                // Budget trajectory warning: shared mutable ref between bridge (writer) and prompt runner (reader)
-                const budgetWarningRef = { current: false };
-                const bridge = createPiEventBridge({
-                    eventBus: deps.eventBus,
-                    budgetGuard: deps.budgetGuard,
-                    costTracker: deps.costTracker,
-                    stepCounter: activeStepCounter,
-                    circuitBreaker: deps.circuitBreaker,
-                    sessionKey,
-                    agentId: agentId ?? "default",
-                    channelId: msg.channelId ?? "",
-                    executionId,
-                    provider: config.provider,
-                    model: config.model,
-                    operationType: executionOverrides?.operationType ?? "interactive", // all callers supply operationType; fallback guards the optional `overrides` param
-                    logger: deps.logger,
-                    onDelta,
-                    memoryPort: deps.memoryPort,
-                    onAbort: () => {
-                        // Abort compaction first to prevent compaction results from being
-                        // saved -- the session file retains its pre-compaction state.
-                        session.abortCompaction();
-                        suppressError(session.abort(), "session abort on compaction cancel");
-                    },
-                    // Cancel the SDK's internal auto-retry loop when the
-                    // bridge classifies the auto_retry_start error as `rate_limited`.
-                    // Rate-limit windows (per-minute) outlast the SDK's retry budget
-                    // (~30s), so retrying within the window cannot succeed.
-                    // `abortRetry()` is sync void -- no error suppression needed.
-                    onAbortRetry: () => session.abortRetry(),
-                    getContextUsage: () => {
-                        // Defensive try-catch: upstream estimateTokens() in pi-coding-agent
-                        // crashes with "message.content is not iterable" when an assistant
-                        // message has content: null (OpenAI Responses API, tool-call-only turns).
-                        // See: https://github.com/badlogic/pi-mono/issues/3120
-                        try {
-                            const usage = session.getContextUsage?.();
-                            return usage ?? undefined;
-                        }
-                        catch {
-                            return undefined;
-                        }
-                    },
-                    contextGuard,
-                    compactionSettings: {
-                        enabled: true,
-                        reserveTokens: config.session?.compaction?.reserveTokens ?? 16384,
-                        keepRecentTokens: config.session?.compaction?.keepRecentTokens ?? 32768,
-                    },
-                    providerHealth: deps.providerHealth,
-                    onToolExecutionEnd: () => { currentResetTimer?.(); },
-                    // Model ID getter for bridge per-turn pricing re-resolution.
-                    getCurrentModel: () => session.model?.id ?? config.model,
-                    // Feed cache reads back to adaptive retention for TTL escalation.
-                    onCacheReads: capturedBridgeRetention
-                        ? (tokens) => { capturedBridgeRetention.recordCacheReads(tokens); }
-                        : undefined,
-                    // Wire turn completion with cache write tokens for fast-path escalation.
-                    onTurnWithCacheWrite: capturedBridgeRetention
-                        ? (cacheWriteTokens) => { capturedBridgeRetention.recordTurnWithCacheWrite(cacheWriteTokens); }
-                        : undefined,
-                    // Pass truncation metadata registry to bridge for audit event enrichment.
-                    getTruncationMeta: (toolCallId) => truncationMetaRegistry.get(toolCallId),
-                    // SEP: Pass execution plan ref to bridge for step tracking
-                    executionPlan: sepEnabled ? executionPlanRef : undefined,
-                    // SEP: Mid-loop extraction config, message text, and start time
-                    sepConfig: sepEnabled ? { maxSteps: config.sep?.maxSteps ?? 15, minSteps: config.sep?.minSteps ?? 3 } : undefined,
-                    sepMessageText: sepEnabled ? (msg.text ?? "") : undefined,
-                    sepExecutionStartMs: sepEnabled ? executionStartMs : undefined,
-                    // Cache break detection post-call callback.
-                    // Enrich with elapsed time for tiered server-side attribution.
-                    checkCacheBreak: (input) => cacheBreakDetector.checkResponseForCacheBreak({
-                        ...input,
-                        lastResponseElapsedMs: getElapsedSinceLastResponse(formattedKey),
-                        // W4: Thread message block count for lookback window detection.
-                        messageBlockCount: session.agent.state.messages?.length ?? 0,
-                    }),
-                    // Record per-turn input tokens as TokenAnchor
-                    onTurnUsage: (inputTokens) => {
-                        // usage.input counts prompt tokens (NOT output). The turn_end fires AFTER
-                        // the assistant message is appended to session.agent.state.messages, so
-                        // messageCount = messages.length - 1 (the count AT the API call, before response).
-                        const messages = session.agent.state.messages;
-                        const messageCount = messages ? messages.length - 1 : 0;
-                        tokenAnchor = {
-                            inputTokens,
-                            messageCount: Math.max(0, messageCount),
-                            timestamp: Date.now(),
-                        };
-                    },
-                    // Pre-LLM-call hook -- runs once per `turn_start`,
-                    // BEFORE pi-ai serializes the next request. Asserts the
-                    // cross-turn hash invariant (logs ERROR per mutated block, with
-                    // module:"agent.bridge.hash-invariant"), then heals any mutated
-                    // thinking blocks against the canonical stream-close snapshot
-                    // and writes the healed array back into session.agent.state.messages
-                    // so persistence and downstream layers see the same shape pi-ai
-                    // serializes. Order matters: assert FIRST so the diagnostic
-                    // captures every mutation before the heal overwrites it. Both
-                    // helpers swallow throws internally; the outer try/catch is a
-                    // belt-and-braces fallback -- the pre-call hook must NEVER abort
-                    // agent flow.
-                    getSessionMessages: () => {
-                        const live = session.agent.state.messages;
-                        if (!Array.isArray(live))
-                            return live;
-                        try {
-                            const stores = bridge.getThinkingBlockStores();
-                            if (stores.hashes.size > 0) {
-                                for (const sessMsg of live) {
-                                    if (!sessMsg || typeof sessMsg !== "object")
-                                        continue;
-                                    const sm = sessMsg;
-                                    if (sm.role !== "assistant")
-                                        continue;
-                                    if (typeof sm.responseId !== "string")
-                                        continue;
-                                    const prior = stores.hashes.get(sm.responseId);
-                                    if (!prior)
-                                        continue;
-                                    const currentContent = Array.isArray(sm.content)
-                                        ? sm.content
-                                        : [];
-                                    assertThinkingBlocksUnchanged(prior, currentContent, sm.responseId, {
-                                        logger: deps.logger,
-                                    });
-                                }
-                            }
-                            if (stores.canonical.size > 0) {
-                                const result = restoreCanonicalThinkingBlocks(live, stores.canonical, { logger: deps.logger });
-                                if (result.restoredCount > 0) {
-                                    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK interop boundary; healed array preserves AgentMessage shape
-                                    session.agent.state.messages = result.messages;
-                                    return result.messages;
-                                }
-                            }
-                        }
-                        catch {
-                            // Pre-call hook must NEVER abort agent flow.
-                        }
-                        return live;
-                    },
-                    // Wire-edge diagnostic: resolves the per-session JSONL
-                    // path on demand. The bridge invokes this only after detecting the
-                    // signed-replay rejection signature on a 400 — never on the happy
-                    // path. Path comes from the same sessionAdapter that already
-                    // governs read/write of the file, so safePath / sessionKey routing
-                    // is reused (sessionKeyToPath -> safePath under the hood).
-                    getSessionJsonlPath: () => sessionAdapter.getSessionPath(sessionKey),
-                    // Budget trajectory warning: shared ref and per-execution cap
-                    perExecutionBudgetCap: config.budgets?.perExecution,
-                    budgetWarningRef,
-                    // Tool retry breaker for recording results
-                    toolRetryBreaker,
-                    // Shared mutable TTL split estimate for per-TTL cost calculation.
-                    ttlSplit,
-                    // Thread graphId/nodeId for cache write signal emission
-                    graphId: executionOverrides?.graphId,
-                    nodeId: executionOverrides?.nodeId,
-                    // Coordinated reset on server-side cache eviction.
-                    onCacheBreakDetected: capturedBridgeRetention
-                        ? (event) => {
-                            // Skip coordinated reset for lookback window misses.
-                            // Lookback misses need MORE breakpoints (which multi-zone already provides),
-                            // not the destructive 4-step reset that reduces caching.
-                            if (event.reason === "lookback_window_exceeded") {
-                                deps.logger.warn({
-                                    sessionKey: formattedKey,
-                                    reason: event.reason,
-                                    tokenDrop: event.tokenDrop,
-                                    conversationBlockCount: event.conversationBlockCount,
-                                    hint: "Long conversation exceeded lookback window. Multi-zone breakpoints mitigate this. No action needed.",
-                                    errorKind: "performance",
-                                }, "Cache miss from lookback window exceeded (not server eviction)");
-                                return; // Skip coordinated reset
-                            }
-                            if (event.reason === "likely_server_eviction" || event.reason === "server_eviction") {
-                                // 4-step coordinated reset (matching ttlGuard.onTtlExpiry pattern):
-                                capturedBridgeRetention.reset(); // 1. Reset adaptive retention to cold-start
-                                clearSessionCacheWarm(formattedKey); // 2. Clear session warm state
-                                setEvictionCooldown(formattedKey, EVICTION_COOLDOWN_TURNS); // 3. Activate 2-turn cooldown
-                                clearSessionBlockStability(formattedKey); // 4. Reset block stability tracker
-                                // Also reset cost gate savings (cost profile changes after eviction)
-                                clearSessionCacheSavings(formattedKey);
-                                deps.logger.info({ sessionKey: formattedKey, reason: event.reason, tokenDrop: event.tokenDrop, cooldownTurns: EVICTION_COOLDOWN_TURNS }, "Server eviction detected, coordinated reset activated");
-                            }
-                        }
-                        : undefined,
-                    // Decrement cooldown each turn (unconditional).
-                    decrementEvictionCooldown: () => {
-                        decrementEvictionCooldownForSession(formattedKey);
-                    },
-                    // Track per-turn cache savings for cost gate evaluation.
-                    onTurnCacheSavings: capturedBridgeRetention
-                        ? (savedUsd) => {
-                            recordCacheSavings(formattedKey, savedUsd);
-                            const state = getCacheSavings(formattedKey);
-                            if (state && state.turnCount >= 3) {
-                                const isNetPositive = state.cumulativeSavingsUsd > 0;
-                                capturedBridgeRetention.setCostGateOpen(isNetPositive);
-                                if (!isNetPositive) {
-                                    deps.logger.debug({ sessionKey: formattedKey, cumulativeSavingsUsd: state.cumulativeSavingsUsd, turnCount: state.turnCount }, "Negative savings, requiring extra evidence turns for escalation");
-                                }
-                            }
-                        }
-                        : undefined,
-                });
-                const unsubscribe = session.subscribe(bridge.listener);
-                // Execution started bookend (Finding 1, )
-                deps.logger.info({
-                    agentId,
-                    sessionKey: formattedKey,
-                    modelId: resolvedModel?.id,
-                    modelTier,
-                    activeToolCount: mergedCustomTools.length,
-                }, "Execution started");
-                // Generic sideEffects processing for tool results.
-                // IN-PLACE mutation: The SDK's agentic loop reads tool.execute at CALL TIME from
-                // the original objects passed to createAgentSession(). A .map() spread creates new
-                // objects the SDK never sees. Mutating tool.execute in-place IS picked up.
-                for (const tool of mergedCustomTools) {
-                    const origExecute = tool.execute;
-                    tool.execute = async function (toolCallId, params, signal, onUpdate, ctx) {
-                        // Inject parent discovery state into sessions_spawn params
-                        // so sub-agent-runner can persist it in session metadata.
-                        if (tool.name === "sessions_spawn" && discoveryTracker.getDiscoveredNames().size > 0) {
-                            const paramsObj = typeof params === "object" && params !== null ? params : {};
-                            paramsObj.discoveredDeferredTools = discoveryTracker.serialize();
-                            params = paramsObj;
-                        }
-                        const toolResult = await origExecute(toolCallId, params, signal, onUpdate, ctx);
-                        // Process sideEffects from any tool result
-                        const sideEffects = toolResult?.sideEffects;
-                        if (sideEffects?.discoveredTools?.length) {
-                            discoveryTracker.markDiscovered(sideEffects.discoveredTools);
-                            deps.logger.debug({ discoveredTools: sideEffects.discoveredTools, toolName: tool.name }, "Deferred tools discovered via side-effect");
-                        }
-                        return toolResult;
-                    };
-                }
-                // Auto-background middleware -- promotes long-running tool executions to background.
-                // IN-PLACE mutation: same rationale as sideEffects above -- .map() spread was dead code.
-                // Applied AFTER sideEffects so the background placeholder is returned instead of
-                // waiting for sideEffects processing. When the tool completes in background,
-                // the sideEffects are still processed by the original wrapped execute.
-                // Capture origin at wrap-time via explicit threading.
-                // The closure reads runPrompt-scope variables synchronously each invocation
-                // so the captured origin reflects the originating session, not the
-                // background-continuation context (which lacks these locals).
-                if (deps.backgroundTaskManager && config.backgroundTasks?.enabled !== false) {
-                    const bgConfig = BackgroundTasksConfigSchema.parse(config.backgroundTasks ?? {});
-                    const resolvedAgentId = agentId ?? "default";
-                    const originResolver = () => {
-                        // Defensive: if any required field is unexpectedly missing, fall through
-                        // to foreground execution (no background promotion). Promotion requires
-                        // a complete origin.
-                        if (!formattedKey || formattedKey.length === 0)
-                            return undefined;
-                        if (!msg.channelType || msg.channelType.length === 0)
-                            return undefined;
-                        if (!msg.channelId || msg.channelId.length === 0)
-                            return undefined;
-                        // Read incoming hop count off msg.metadata so the runner can enforce
-                        // the recursion bound. Top-level user messages have no
-                        // metadata.backgroundHopCount -> default to 0.
-                        // Cast metadata defensively because NormalizedMessageSchema.metadata
-                        // is z.record(z.string(), z.unknown()).
-                        const meta = msg.metadata;
-                        const rawHopCount = meta?.backgroundHopCount;
-                        const incomingHopCount = typeof rawHopCount === "number" && Number.isFinite(rawHopCount) && rawHopCount >= 0
-                            ? Math.floor(rawHopCount)
-                            : 0;
-                        return {
-                            agentId: resolvedAgentId,
-                            sessionKey: formattedKey,
-                            channelType: msg.channelType,
-                            channelId: msg.channelId,
-                            traceId: executionId ?? null,
-                            backgroundHopCount: incomingHopCount,
-                        };
-                    };
-                    for (const tool of mergedCustomTools) {
-                        const wrapped = wrapToolForAutoBackground(
-                        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK interop boundary
-                        tool, deps.backgroundTaskManager, bgConfig, deps.backgroundNotifyFn ?? (async () => { }), originResolver);
-                        tool.execute = wrapped.execute;
-                    }
-                }
-                // Prompt execution: envelope, preamble, images, budget, retry, escalation, recovery
-                // Extracted to executor-prompt-runner.ts
-                try {
-                    const promptRunResult = await runPrompt({
-                        msg, session, config, sessionKey, formattedKey, agentId, result,
-                        executionOverrides, executionStartMs, effectiveTimeout, executionId,
-                        bridge, dynamicPreamble, deferredContext, inlineMemory,
-                        systemPrompt,
-                        mergedCustomTools,
-                        cmdResult, sepEnabled, executionPlanRef,
-                        _directives, _prevTimestamp, resolvedModel,
-                        deps: {
-                            eventBus: deps.eventBus,
-                            logger: deps.logger,
-                            budgetGuard: deps.budgetGuard,
-                            costTracker: deps.costTracker,
-                            authRotation: deps.authRotation,
-                            fallbackModels: deps.fallbackModels,
-                            modelRegistry: deps.modelRegistry,
-                            providerHealth: deps.providerHealth,
-                            lastKnownModel: deps.lastKnownModel,
-                            envelopeConfig: deps.envelopeConfig,
-                            outputGuard: deps.outputGuard,
-                            canaryToken: deps.canaryToken,
-                        },
-                        onResetTimer: (fn) => { currentResetTimer = fn; },
-                        // Provide last cache write tokens for improved timeout cost estimation
-                        getLastCacheWriteTokens: () => bridge.getResult().tokensUsed?.cacheWrite ?? 0,
-                        budgetWarningRef,
-                    });
-                    // Aggregate ghost cost from timed-out request into bridge metrics
-                    if (promptRunResult.ghostCost) {
-                        bridge.addGhostCost(promptRunResult.ghostCost);
-                    }
-                    // Handle stuck session -- flag for post-withSession destroy
-                    if (promptRunResult.stuckSessionDetected) {
-                        deps.logger.warn({
-                            agentId,
-                            sessionKey: formattedKey,
-                            hint: "Resetting stuck session -- user must resend their message",
-                            errorKind: "internal",
-                        }, "Destroying stuck session");
-                        result.finishReason = "session_reset";
-                        result.response = "Session was in an inconsistent state and has been reset. Please send your message again.";
-                    }
-                }
-                catch (error) {
-                    deps.logger.warn({
-                        err: error,
-                        hint: "PiExecutor unexpected error",
-                        errorKind: "internal",
-                    }, "Unexpected execution error");
-                    result.finishReason = "error";
-                    // Never expose raw error internals (API keys, URLs, stack traces) to users.
-                    // The raw error is already logged to deps.logger.warn above for operator diagnostics.
-                    // Classify the error to give the user an actionable (but safe) message.
-                    const classifiedOuter = error instanceof PromptTimeoutError
-                        ? classifyPromptTimeout(error.timeoutMs)
-                        : classifyError(error);
-                    result.response = classifiedOuter.userMessage;
-                    result.errorContext = {
-                        errorType: error instanceof PromptTimeoutError ? "PromptTimeout" : "UnexpectedError",
-                        retryable: classifiedOuter.retryable,
-                        originalError: error instanceof Error ? error.message : String(error),
-                    };
-                    // OutputGuard: scan catch-block error responses (unified in executor-response-filter.ts)
-                    if (deps.outputGuard && result.response) {
-                        const guardScan = scanWithOutputGuard({
-                            outputGuard: deps.outputGuard, response: result.response, context: "exception",
-                            canaryToken: deps.canaryToken, agentId: agentId ?? "unknown",
-                            tenantId: sessionKey.tenantId, sessionKey, eventBus: deps.eventBus, logger: deps.logger,
-                        });
-                        result.response = guardScan.response;
-                    }
-                }
-                finally {
-                    // Clear thinking ceiling so next execution recalculates from current state.
-                    // Defense-in-depth: context engine is recreated per execute(), but explicit clear
-                    // ensures no stale ceiling if engine lifetime changes in the future.
-                    ceSetup?.contextEngine?.setThinkingCeiling?.(undefined);
-                    // Post-execution cleanup: stats merge, cache metrics, memory persist, session cleanup
-                    // Extracted to executor-post-execution.ts
-                    await postExecution({
-                        result, session, sm, config, msg, sessionKey, formattedKey, agentId,
-                        executionStartMs, executionId, executionOverrides,
-                        bridge, unsubscribe,
-                        contextEngineRef, ceSetup, streamSetup,
-                        getTruncationSummary, getTurnBudgetSummary,
-                        executionPlanRef, sepEnabled, isOnboarding,
-                        geminiCacheHit, geminiCachedTokens, modelTier,
-                        // Provider attribution tag for the bookend log.
-                        // resolvedModel?.provider is the post-resolution / post-override
-                        // provider; falling back to config.provider records operator
-                        // INTENT on the silent-fallback misconfig path (resolvedModel
-                        // undefined). resolveProviderCapabilities is computed once here
-                        // to keep executor-post-execution.ts free of capability-cascade
-                        // imports.
-                        provider: resolvedModel?.provider ?? config.provider,
-                        providerFamily: resolveProviderCapabilities(resolvedModel?.provider ?? config.provider).providerFamily,
-                        deferralResult, mergedCustomTools, deliveredGuides,
-                        deps: {
-                            eventBus: deps.eventBus,
-                            logger: deps.logger,
-                            memoryPort: deps.memoryPort,
-                            activeRunRegistry: deps.activeRunRegistry,
-                            embeddingEnqueue: deps.embeddingEnqueue,
-                            workspaceDir: deps.workspaceDir,
-                        },
-                        sessionAdapter,
-                        executionCacheRetentionClear: () => { executionCacheRetention = undefined; },
-                        adaptiveRetentionClear: () => { adaptiveRetention = undefined; },
-                        executionMinTokensOverrideClear: () => { executionMinTokensOverride = undefined; },
-                    });
-                }
-                return result;
-            });
-            // Destroy session file after withSession releases the lock.
-            // This must happen outside withSession to avoid file conflicts under lock.
-            if (lockResult.ok && lockResult.value.finishReason === "session_reset") {
-                await sessionAdapter.destroySession(sessionKey);
-            }
-            // Handle lock failure
-            if (!lockResult.ok) {
-                result.finishReason = "error";
-                result.response =
-                    lockResult.error === "locked"
-                        ? "Session is currently locked. Please try again."
-                        : "Session access error.";
-                deps.logger.warn({
-                    error: lockResult.error,
-                    hint: "Session lock failed",
-                    errorKind: "resource",
-                }, "Session lock error");
-                return result;
-            }
-            return lockResult.value;
-        },
-    };
-}