mixdog 0.9.19 → 0.9.21

package/src/runtime/agent/orchestrator/session/manager.mjs

@@ -1,98 +1,44 @@
-import { createRequire } from 'module';
-import { fileURLToPath } from 'url';
-import { randomBytes, createHash } from 'crypto';
-import { getProvider } from '../providers/registry.mjs';
-// Image content is kept in-memory and in the model-visible history so multi-turn
-// recognition works reliably (live transcript always retains images). The
-// stored-history placeholder swap now happens only at disk-serialization time
-// inside the session store, so it is no longer imported here.
-import {
-    normalizeCompactType,
-    DEFAULT_COMPACT_TYPE,
-    SUMMARY_PREFIX,
-} from './compact.mjs';
-import { estimateMessagesTokens, estimateTranscriptContextUsage } from './context-utils.mjs';
-import { executeInternalTool } from '../internal-tools.mjs';
-import { collectPromptSkillsCached, buildSkillManifest, composeSystemPrompt } from '../context/collect.mjs';
-import { saveSession, saveSessionAsync, loadSession, listStoredSessionSummaries, sweepStaleSessions, markSessionClosed, bumpSessionGeneration, setLiveSession } from './store.mjs';
-import { clearReadDedupSession, tryPrefetchCached, setPrefetchCached } from './read-dedup.mjs';
-import { clearOffloadSession } from './tool-result-offload.mjs';
-import { classifyResultKind } from './result-classification.mjs';
-import { createAbortController } from '../../../shared/abort-controller.mjs';
-import { logLlmCall } from '../../../shared/llm/usage-log.mjs';
-import { appendAgentTrace } from '../agent-trace.mjs';
-import { isAgentOwner } from '../agent-owner.mjs';
-import { getHiddenAgent } from '../internal-agents.mjs';
-import { loadConfig } from '../config.mjs';
-import { buildProviderCacheOpts, cacheCapabilityForProvider } from '../agent-runtime/cache-strategy.mjs';
-import { normalizeAutoClearConfig, resolveAutoClearIdleMs } from '../../../../session-runtime/config-helpers.mjs';
-import {
-    recordStandaloneStatusTelemetry,
-} from './manager/status-telemetry.mjs';
-import {
-    normalizeStaleCompactingStage,
-    runSessionCompaction,
-} from './manager/compaction-runner.mjs';
-// Split modules — see manager/ directory. manager.mjs is now a thin facade that
-// orchestrates these cohesive units while keeping the exact public surface.
-import {
-    _buildSharedRules,
-    _buildAgentRules,
-    _buildLeadRules,
-    _buildLeadMetaContext,
-    _buildAgentSpecific,
-} from './manager/rules-cache.mjs';
-import {
-    applyToolPermissionNarrowing,
-    finalizeSessionToolList,
-    resolveSessionTools,
-    previewSessionTools,
-    permissionFromToolSpec,
-} from './manager/tool-resolution.mjs';
-import {
-    guessContextWindow,
-    positiveContextWindow,
-    preserveBufferConfigFields,
-    resolveSessionContextMeta,
-    compactTriggerForSession,
-} from './manager/context-meta.mjs';
-import {
-    promptContentText,
-    hasModelVisiblePromptContent,
-    promptContentBytes,
-    prefixUserTurnContent,
-    prefixSessionStartContent,
-    buildCurrentTimeBlock,
-    buildSessionStartBlock,
-    hasUserConversationMessage,
-    isInternalRuntimeNotificationText,
-} from './manager/prompt-utils.mjs';
-import {
-    _mergePendingMessageEntries,
-    enqueuePendingMessage,
-    drainPendingMessages,
-    _dropPendingMessageState,
-    sweepOrphanedPendingMessages,
-} from './manager/pending-messages.mjs';
-import {
-    bumpUsageMetricsTurnId,
-    resolveUsageMetricsTurnId,
-    bumpUsageMetricsEpoch,
-    resolveUsageMetricsEpoch,
-    usageMetricsSourceKey,
-    usageMetricsIdempotencyKey,
-    uncachedInputTokensForProvider,
-    applyAskTerminalUsageTotals,
-    persistIterationMetrics,
-} from './manager/usage-metrics.mjs';
-// Runtime-liveness map + accessors — extracted (pass-3) to
-// manager/runtime-liveness.mjs. State is a module-level singleton there,
-// preserving the baseline single-process shape. manager.mjs keeps askSession's
-// controller/generation lifecycle and calls these via imports. The two
-// _get/_entries accessors expose the private Map for in-place mutation from
-// closeSession / idle-sweep / askSession.
-import {
-    configureRuntimeLiveness,
+// src/runtime/agent/orchestrator/session/manager.mjs
+// Thin facade over the split session-manager modules in ./manager/. This file
+// re-exports the EXACT public surface the previous monolith exposed so every
+// importer (loop.mjs, loop/tool-exec.mjs, agent-dispatch.mjs, session-builder,
+// abort-lookup, statusline-agents, headless-role, session-runtime, and the
+// smoke scripts) keeps resolving its symbols through manager.mjs unchanged.
+//
+// Module map:
+//   manager/runtime-liveness.mjs       — in-memory stage/heartbeat + accessors
+//   manager/tool-resolution.mjs        — tool policy resolution/narrowing
+//   manager/context-meta.mjs           — context-window / compact-trigger meta
+//   manager/prompt-utils.mjs           — prompt content shaping helpers
+//   manager/pending-messages.mjs       — pending-send queue (enqueue/drain)
+//   manager/usage-metrics.mjs          — usage accounting / persistence
+//   manager/rules-cache.mjs            — cached rule builders
+//   manager/status-telemetry.mjs       — standalone status telemetry
+//   manager/compaction-runner.mjs      — session compaction runner
+//   manager/session-errors.mjs         — SessionClosedError
+//   manager/runtime-loaders.mjs        — lazy code_graph/agent-loop/bash bridges
+//   manager/agent-runtime-singleton.mjs— injected Agent Runtime singleton
+//   manager/session-id.mjs             — monotonic session-id minting
+//   manager/provider-cache-key.mjs     — provider-scoped cache key
+//   manager/prefetch-bridge.mjs        — explicit-prefetch bridge
+//   manager/message-sanitize.mjs       — model-message sanitize + fail persist
+//   manager/session-lock.mjs           — per-session ask mutex
+//   manager/session-lifecycle.mjs      — createSession/updateRoute/resume
+//   manager/ask-session.mjs            — askSession + abort-aware call wrapper
+//   manager/session-crud.mjs           — read/clear/compact/status/flush
+//   manager/session-close.mjs          — closeSession/abortSessionTurn
+//   manager/idle-cleanup.mjs           — periodic idle/tombstone sweep
+import { configureRuntimeLiveness } from './manager/runtime-liveness.mjs';
+import { loadSession, saveSessionAsync } from './store.mjs';
+
+// Wire the store deps the liveness module needs without importing store.mjs
+// back into it via manager.mjs (avoids re-entry / keeps one store contract).
+configureRuntimeLiveness({ loadSession, saveSessionAsync });
+
+// ── Runtime-liveness surface ──────────────────────────────────────────────
+// External importers (loop.mjs, loop/tool-exec.mjs, agent-dispatch.mjs,
+// abort-lookup.mjs, statusline-agents.mjs) resolve these through manager.mjs.
+export {
     updateSessionStage,
     markSessionAskStart,
     markSessionStreamDelta,
@@ -109,44 +55,19 @@ import {
     getSessionAbortSignal,
     getSessionLastProgressAt,
     linkParentSignalToSession,
-    _touchRuntime,
-    _stopToolActivityHeartbeat,
-    _unlinkParentAbortListener,
-    _clearSessionRuntime,
-    _getRuntimeEntry,
-    _runtimeEntries,
 } from './manager/runtime-liveness.mjs';
-// Facade re-exports — external importers (loop.mjs, loop/tool-exec.mjs,
-// agent-dispatch.mjs, abort-lookup.mjs, statusline-agents.mjs) resolve these
-// through manager.mjs unchanged.
+
+// ── Tool resolution / pending messages / prompt utils ─────────────────────
+export { previewSessionTools } from './manager/tool-resolution.mjs';
 export {
-    updateSessionStage,
-    markSessionAskStart,
-    markSessionStreamDelta,
-    markSessionToolCall,
-    markSessionDone,
-    markSessionEmptyFinal,
-    markSessionError,
-    markSessionCancelled,
-    getSessionRuntime,
-    isSessionCompactionBlocked,
-    getSessionProgressSnapshot,
-    forEachSessionRuntime,
-    hideSessionFromList,
-    getSessionAbortSignal,
-    getSessionLastProgressAt,
-    linkParentSignalToSession,
-};
-// Wire the store deps the liveness module needs without importing store.mjs
-// back into it via manager.mjs (avoids re-entry / keeps one store contract).
-configureRuntimeLiveness({ loadSession, saveSessionAsync });
-// Re-export split-module public/test surface unchanged so every importer of the
-// old symbol names keeps resolving through the facade.
-export { previewSessionTools };
-export { _mergePendingMessageEntries, enqueuePendingMessage, drainPendingMessages };
-export { isInternalRuntimeNotificationText as _isInternalRuntimeNotificationText };
-// Usage-metrics surface — re-exported unchanged so loop.mjs / smoke scripts keep
-// resolving these through the facade.
+    _mergePendingMessageEntries,
+    enqueuePendingMessage,
+    drainPendingMessages,
+} from './manager/pending-messages.mjs';
+export { isInternalRuntimeNotificationText as _isInternalRuntimeNotificationText } from './manager/prompt-utils.mjs';
+
+// ── Usage-metrics surface — re-exported unchanged so loop.mjs / smoke scripts
+//    keep resolving these through the facade. ────────────────────────────────
 export {
     bumpUsageMetricsTurnId,
     resolveUsageMetricsTurnId,
@@ -156,2163 +77,45 @@ export {
     usageMetricsIdempotencyKey,
     applyAskTerminalUsageTotals,
     persistIterationMetrics,
-};
-let _codeGraphRuntimePromise = null;
-let _agentLoopPromise = null;
-let _bashSessionRuntimePromise = null;
-async function _executeCodeGraphToolLazy(name, args, cwd, signal = null, options = {}) {
-    _codeGraphRuntimePromise ??= import('../tools/code-graph.mjs');
-    const mod = await _codeGraphRuntimePromise;
-    if (typeof mod.executeCodeGraphTool !== 'function') throw new Error('code_graph runtime is not available');
-    return mod.executeCodeGraphTool(name, args, cwd, signal, options);
-}
-async function _getAgentLoop() {
-    _agentLoopPromise ??= import('./loop.mjs');
-    const mod = await _agentLoopPromise;
-    if (typeof mod.agentLoop !== 'function') throw new Error('agent loop runtime is not available');
-    return mod.agentLoop;
-}
-function _closeBashSessionLazy(sessionId, reason) {
-    if (!sessionId) return;
-    _bashSessionRuntimePromise ??= import('../tools/bash-session.mjs');
-    _bashSessionRuntimePromise
-        .then((mod) => { if (typeof mod.closeBashSession === 'function') mod.closeBashSession(sessionId, reason); })
-        .catch(() => {});
-}
-// Re-export the rules builders so any deep importer of the old symbol names
-// keeps working through the facade.
-export { _buildSharedRules, _buildAgentRules, _buildLeadRules, _buildLeadMetaContext, _buildAgentSpecific };
-
-// Agent Runtime is optional — injected via setAgentRuntime() during plugin init
-// so session creation never depends on a circular import. If never injected,
-// createSession simply falls back to classic preset-only behavior.
-let _agentRuntimeApi = null;
-let _agentRuntimeWarned = false;
-
-/**
- * Inject the Agent Runtime singleton. Called once by agent/index.mjs init()
- * after initAgentRuntime(). Safe to call multiple times — later calls
- * replace the previous reference.
- */
-export function setAgentRuntime(api) {
-    _agentRuntimeApi = api || null;
-}
-
-function getAgentRuntimeSync() {
-    return _agentRuntimeApi;
-}
-
-/**
- * Thrown when a session is closed while a call is in-flight. Callers (agent
- * handler, CLI) should render this as "cancelled" rather than a hard error.
- */
-export class SessionClosedError extends Error {
-    constructor(sessionId, reason, closeReason) {
-        super(reason ? `Session "${sessionId}" closed: ${reason}` : `Session "${sessionId}" closed`);
-        this.name = 'SessionClosedError';
-        this.sessionId = sessionId;
-        this.cancelled = true;
-        // closeReason is the diagnostic enum (request-abort / manual /
-        // idle-sweep / runner-crash). Kept separate from `reason` (the free
-        // -form message) so consumers can branch on it without regex parsing.
-        this.reason = closeReason || null;
-    }
-}
-// Cap how long the terminal unwind blocks on the post-result session save.
-// The result is already produced (and relayed for agent surfaces) before this
-// save, so a stalled disk write must not hold askSession() open — otherwise the
-// owning background task is stranded in `running` and its completion
-// notification never fires. A slow write finishes in the background.
-const TERMINAL_SAVE_TIMEOUT_MS = nonNegativeIntEnv('MIXDOG_TERMINAL_SAVE_TIMEOUT_MS', 5_000);
+} from './manager/usage-metrics.mjs';
 
-// Session tool resolution + permission narrowing moved to
-// manager/tool-resolution.mjs (imported above). The following section-level
-// docs describe the toolSpec contract those helpers implement.
-//
-// Phase D-2 — profile.tools resolution.
-//
-// `toolSpec` may be:
-//   • Array<string>  (profile.tools) — toolset ids like "tools:filesystem",
-//                     "tools:git", "tools:mcp", "tools:search",
-//                     "tools:readonly", or the literal "full"
-//   • 'full' / 'readonly' / 'mcp'  — legacy preset.tools strings
-//   • null / undefined             — same as 'full' (historical default)
-//
-// Array form is the Phase B/D target: each profile declares its tool surface
-// explicitly, BP_1 hash differs across profiles with different tool subsets
-// (by design — sub-task profile cannot see bash; worker-full can), and
-// adding a new toolset id here is a localised change.
-//
-// Unified-shard policy — the session's tool array normally never narrows
-// with permission or role. Agent sessions share the same schema so BP_1
-// stays bit-identical and the provider-side cache shard is shared
-// workspace-wide. Rare specialist roles may pass schemaAllowedTools from a
-// declarative hidden-role toolSchemaProfile to keep their first-turn routing
-// surface intentionally tiny; runtime permission guards in loop.mjs remain
-// the fail-safe either way.
+// ── Rules builders — deep importers of the old symbol names resolve here. ──
+export {
+    _buildSharedRules,
+    _buildAgentRules,
+    _buildLeadRules,
+    _buildLeadMetaContext,
+    _buildAgentSpecific,
+} from './manager/rules-cache.mjs';
 
-let nextId = Date.now();
-// Test-only exports for the legacy auto-compact-limit migration + buffer-config
-// preservation (see scripts/compact-trigger-migration-smoke.mjs).
+// ── Test-only aliases for the legacy auto-compact-limit migration +
+//    buffer-config preservation (scripts/compact-trigger-migration-smoke.mjs). ─
+import {
+    resolveSessionContextMeta,
+    compactTriggerForSession,
+    preserveBufferConfigFields,
+} from './manager/context-meta.mjs';
 export const _resolveSessionContextMeta = resolveSessionContextMeta;
 export const _compactTriggerForSession = compactTriggerForSession;
 export const _preserveBufferConfigFields = preserveBufferConfigFields;
-// Provider-scoped unified cache key. Goal: all orchestrator-internal
-// dispatches (agent/maintenance/mcp/scheduler/webhook) targeting the
-// same provider land in a single server-side cache shard, so the
-// shared prefix (tools + system + pool system prompt) is reused
-// regardless of role. Per-role / per-session differentiation lives after the
-// system prefix (BP3 sessionMarker system block / later messages), which is
-// naturally separated by provider-side content hashing.
-const PROVIDER_ALIAS = {
-    'openai-oauth': 'codex',      // ChatGPT subscription (OpenAI OAuth backend)
-    'anthropic-oauth': 'claude',  // Claude Max subscription
-    'openai': 'openai',
-    'anthropic': 'anthropic',
-    'gemini': 'gemini',
-    'deepseek': 'deepseek',
-    'xai': 'xai',
-};
-function providerCacheKey(provider, override) {
-    if (override) return String(override);
-    if (!provider) return 'mixdog-default';
-    return `mixdog-${PROVIDER_ALIAS[provider] || provider}`;
-}
-
-// ── Prefetch permission guard ─────────────────────────────────────────────────
-// Runs the shared permission evaluator for tool calls that originate in the
-// prefetch path (outside the agent loop). Permission enforcement is disabled
-// (the evaluator always returns allow), so this is effectively a pass-through
-// kept for API compatibility. Returns an error string if blocked, or null.
-const _permEvalForPrefetch = (() => {
-    const _req = createRequire(import.meta.url);
-    try {
-        const { dirname: _pdir, resolve: _pres } = _req('path');
-        const _hooksLib = _pres(_pdir(fileURLToPath(import.meta.url)), '../../../../hooks/lib/permission-evaluator.cjs');
-        return _req(_hooksLib).evaluatePermission;
-    } catch { return null; }
-})();
-function _guardedPrefetchTool(toolName, toolArgs, session) {
-    if (!_permEvalForPrefetch) return null;
-    // When no explicit mode is attached to the session, run the evaluator
-    // under 'default'. The evaluator now always allows, so this never blocks.
-    const permissionMode = session?.permissionMode || 'default';
-    const projectDir = session?.cwd || undefined;
-    const userCwd = session?.cwd || undefined;
-    const MCP_PFX = 'mcp__plugin_mixdog_mixdog__';
-    const fullName = toolName.startsWith(MCP_PFX) || toolName.startsWith('mcp__') ? toolName : `${MCP_PFX}${toolName}`;
-    try {
-        const { decision, reason } = _permEvalForPrefetch({ toolName: fullName, toolInput: toolArgs || {}, permissionMode, projectDir, userCwd });
-        if (decision === 'deny' || decision === 'ask') {
-            return `Error: prefetch tool "${toolName}" blocked (decision=${decision}): ${reason}`;
-        }
-    } catch (e) {
-        process.stderr.write(`[prefetch-guard] evaluator error: ${e?.message}\n`);
-    }
-    return null;
-}
-
-async function _tryBridgeExplicitPrefetch(session, explicitPrefetch) {
-    if (!explicitPrefetch || typeof explicitPrefetch !== 'object') return null;
-    if (!isAgentOwner(session)) return null;
-    const parts = [];
-    const failed = [];
-    const totalEntries = [];
-    // files[] — string entries use the default head excerpt; object entries
-    // {path, n?, full?} let the caller widen the window or pull the full file
-    // so worker doesn't have to re-read deep ranges of an already-prefetched
-    // file (a recurring iter burner observed in baseline session telemetry).
-    const _rawFilesIn = Array.isArray(explicitPrefetch.files) ? explicitPrefetch.files : [];
-    const _readOptsByFile = new Map();
-    const files = [];
-    const _seenFiles = new Set();
-    const _addPrefetchFile = (file, opts = null) => {
-        if (typeof file !== 'string' || !file) return;
-        if (!_seenFiles.has(file)) {
-            _seenFiles.add(file);
-            files.push(file);
-        }
-        if (!opts || Object.keys(opts).length === 0) return;
-        const prev = _readOptsByFile.get(file) || {};
-        const merged = { ...prev };
-        if (opts.mode === 'full') {
-            merged.mode = 'full';
-            delete merged.n;
-        } else if (merged.mode !== 'full' && Number.isFinite(opts.n) && opts.n > 0) {
-            merged.n = Math.max(Number(merged.n) || 0, opts.n);
-        }
-        if (Object.keys(merged).length > 0) _readOptsByFile.set(file, merged);
-    };
-    for (const entry of _rawFilesIn) {
-        if (typeof entry === 'string' && entry) {
-            _addPrefetchFile(entry);
-        } else if (entry && typeof entry === 'object' && typeof entry.path === 'string' && entry.path) {
-            const opts = {};
-            if (entry.full === true) opts.mode = 'full';
-            else if (Number.isFinite(entry.n) && entry.n > 0) opts.n = entry.n;
-            _addPrefetchFile(entry.path, opts);
-        }
-    }
-    if (files.length > 0) {
-        const _pfGuard = _guardedPrefetchTool('read', { path: files }, session);
-        if (_pfGuard) {
-            process.stderr.write(`[agent-prefetch] files read blocked: ${_pfGuard}\n`);
-            failed.push(...files);
-            totalEntries.push(...files);
-        } else {
-        totalEntries.push(...files);
-        // R20: per-file prefetch cache (cross-dispatch, process-local).
-        // Try each file from cache first; batch misses into one disk read.
-        const { resolve: _pfResolve, isAbsolute: _pfIsAbs, normalize: _pfNorm } = await import('path');
-        const _pfCwd = session.cwd || null;
-        function _pfAbsPath(f) {
-            const abs = _pfIsAbs(f) ? f : _pfResolve(_pfCwd || process.cwd(), f);
-            return _pfNorm(abs);
-        }
-        const fileHits = [];   // { file, abs, content } — satisfied from cache
-        const fileMisses = []; // { file, abs } — need disk read
-        for (const f of files) {
-            const abs = _pfAbsPath(f);
-            // Skip the cross-dispatch cache when the caller asked for a
-            // non-default window (custom n or full-file). Cache key is the
-            // path alone, so a default-window cache hit would silently feed
-            // the wrong slice back to the next caller.
-            const hit = _readOptsByFile.has(f) ? null : tryPrefetchCached(abs);
-            if (hit) {
-                fileHits.push({ file: f, abs, content: hit.content });
-            } else {
-                fileMisses.push({ file: f, abs });
-            }
-        }
-        // Disk read for misses (single batch call).
-        const missFiles = fileMisses.map(m => m.file);
-        const missResults = {}; // file → content string
-        if (missFiles.length > 0) {
-            // Read each miss file individually so we can cache per-file.
-            // The files list is small (typically 2-5), so N awaits is fine.
-            await Promise.all(missFiles.map(async (f) => {
-                const opts = _readOptsByFile.get(f) || {};
-                const readArgs = { path: f };
-                if (opts.mode === 'full') {
-                    readArgs.mode = 'full';
-                } else {
-                    readArgs.mode = 'head';
-                    readArgs.n = Number.isFinite(opts.n) ? opts.n : 120;
-                }
-                const out = await executeInternalTool('read', readArgs).catch((e) => {
-                    process.stderr.write(`[agent-prefetch] file read failed (${f}): ${e && e.message || e}\n`);
-                    return null;
-                });
-                if (out !== null) {
-                    missResults[f] = String(out);
-                }
-            }));
-            // Cache successful miss results.
-            for (const { file, abs } of fileMisses) {
-                const content = missResults[file];
-                if (content && classifyResultKind(content) !== 'error') {
-                    // Only cache default-window reads; custom-window results
-                    // would poison the shared cross-dispatch cache.
-                    if (!_readOptsByFile.has(file)) setPrefetchCached(abs, content);
-                } else if (content === undefined || classifyResultKind(content) === 'error') {
-                    failed.push(file);
-                }
-            }
-        }
-        // Assemble combined output preserving original file order.
-        const readParts = [];
-        const hitByFile = new Map(fileHits.map((h) => [h.file, h]));
-        for (const f of files) {
-            const hitEntry = hitByFile.get(f);
-            if (hitEntry) {
-                readParts.push(hitEntry.content);
-                continue;
-            }
-            const content = missResults[f];
-            if (content && classifyResultKind(content) !== 'error') {
-                readParts.push(content);
-            }
-            // else: already pushed to failed above
-        }
-        if (readParts.length > 0) {
-            parts.push(`### prefetch files\nread ${readParts.length}\n\n${readParts.join('\n\n')}`);
-        }
-        // Log hit/miss counters so dispatch telemetry shows prefetch effectiveness.
-        if (process.env.MIXDOG_DEBUG_SESSION_LOG) {
-            process.stderr.write(
-                `[prefetch] files=${files.length} cached=${fileHits.length} miss=${fileMisses.length} failed=${failed.length}\n`
-            );
-        }
-        // Attach stats to session so post-hoc analyzers (inspect-session.mjs)
-        // can see prefetch effectiveness without parsing stderr logs.
-        if (session && typeof session === 'object') {
-            if (!session.prefetchStats) session.prefetchStats = { files: 0, cached: 0, miss: 0, failed: 0 };
-            session.prefetchStats.files += files.length;
-            session.prefetchStats.cached += fileHits.length;
-            session.prefetchStats.miss += fileMisses.length;
-            session.prefetchStats.failed += failed.length;
-        }
-        }
-    }
-    // callers[]
-    const callers = Array.isArray(explicitPrefetch.callers) ? explicitPrefetch.callers.filter(c => c && typeof c.symbol === 'string') : [];
-    {
-        const callerTasks = callers.map(({ symbol, file }) => {
-            const cgArgs = { mode: 'callers', symbol };
-            if (file) cgArgs.file = file;
-            if (session?.cwd) cgArgs.cwd = session.cwd;
-            totalEntries.push(symbol);
-            const blocked = _guardedPrefetchTool('code_graph', cgArgs, session);
-            if (blocked) {
-                process.stderr.write(`[agent-prefetch] callers(${symbol}) blocked: ${blocked}\n`);
-                return Promise.resolve({ symbol, out: null, blocked: true });
-            }
-            return _executeCodeGraphToolLazy('code_graph', cgArgs, session?.cwd)
-                .then(out => ({ symbol, out }))
-                .catch(e => {
-                    process.stderr.write(`[agent-prefetch] callers(${symbol}) failed: ${e && e.message || e}\n`);
-                    return { symbol, out: null };
-                });
-        });
-        const callerResults = await Promise.allSettled(callerTasks);
-        for (const r of callerResults) {
-            const { symbol, out, blocked } = r.status === 'fulfilled' ? r.value : { symbol: '?', out: null };
-            if (blocked) { failed.push(symbol); continue; }
-            if (out && classifyResultKind(String(out)) !== 'error') {
-                parts.push(`### prefetch callers ${symbol}\n${out}`);
-            } else {
-                failed.push(symbol);
-            }
-        }
-    }
-    // references[]
-    const references = Array.isArray(explicitPrefetch.references) ? explicitPrefetch.references.filter(r => r && typeof r.symbol === 'string') : [];
-    {
-        const refTasks = references.map(({ symbol, file }) => {
-            const cgArgs = { mode: 'references', symbol };
-            if (file) cgArgs.file = file;
-            if (session?.cwd) cgArgs.cwd = session.cwd;
-            totalEntries.push(symbol);
-            const blocked = _guardedPrefetchTool('code_graph', cgArgs, session);
-            if (blocked) {
-                process.stderr.write(`[agent-prefetch] references(${symbol}) blocked: ${blocked}\n`);
-                return Promise.resolve({ symbol, out: null, blocked: true });
-            }
-            return _executeCodeGraphToolLazy('code_graph', cgArgs, session?.cwd)
-                .then(out => ({ symbol, out }))
-                .catch(e => {
-                    process.stderr.write(`[agent-prefetch] references(${symbol}) failed: ${e && e.message || e}\n`);
-                    return { symbol, out: null };
-                });
-        });
-        const refResults = await Promise.allSettled(refTasks);
-        for (const r of refResults) {
-            const { symbol, out, blocked } = r.status === 'fulfilled' ? r.value : { symbol: '?', out: null };
-            if (blocked) { failed.push(symbol); continue; }
-            if (out && classifyResultKind(String(out)) !== 'error') {
-                parts.push(`### prefetch references ${symbol}\n${out}`);
-            } else {
-                failed.push(symbol);
-            }
-        }
-    }
-    if (session && typeof session === 'object' && (callers.length > 0 || references.length > 0)) {
-        if (!session.prefetchStats) session.prefetchStats = { files: 0, cached: 0, miss: 0, failed: 0, callers: 0, references: 0 };
-        session.prefetchStats.callers = (session.prefetchStats.callers || 0) + callers.length;
-        session.prefetchStats.references = (session.prefetchStats.references || 0) + references.length;
-    }
-    if (parts.length === 0) {
-        // All entries failed but Lead presence must still be signalled — emit
-        // warn-only so the gate logic can distinguish "prefetch was requested"
-        // from "no prefetch at all".
-        if (totalEntries.length > 0 && failed.length > 0) {
-            return `<prefetch-warn>${failed.length} of ${totalEntries.length} prefetch entries failed: ${[...new Set(failed)].join(', ')}</prefetch-warn>`;
-        }
-        return null;
-    }
-    const warnLine = failed.length > 0
-        ? `<prefetch-warn>${failed.length} of ${totalEntries.length} prefetch entries failed: ${[...new Set(failed)].join(', ')}</prefetch-warn>\n`
-        : '';
-    return `${warnLine}<prefetch>\n${parts.join('\n\n')}\n</prefetch>`;
-}
-
-// --- agent spawn (createSession) ---
-// opts can pass either a `preset` object (from config.presets) or raw provider/model.
-// Preset shape: { name, provider, model, effort?, fast?, tools? }
-//
-// Agent Runtime integration:
-//   opts.taskType / opts.agent / opts.profileId — enables profile-aware routing.
-//     Rule-based SmartRouter resolves these synchronously; the resolved
-//     profile controls context filtering (skip.skills/memory/etc) and cache
-//     strategy. If no rule matches, falls back to classic preset behavior.
-//   opts.profile — pre-resolved profile (bypasses router; used by async
-//     callers who already ran AgentRuntime.resolve()).
-//   opts.providerCacheOpts — pre-resolved cache options merged into ask() sendOpts.
-export function createSession(opts) {
-    const presetObj = opts.preset && typeof opts.preset === 'object' ? opts.preset : null;
-
-    // --- Agent Runtime profile resolution (best-effort, sync) ---
-    let profile = opts.profile || null;
-    let providerCacheOpts = opts.providerCacheOpts || null;
-    if (!profile && (opts.taskType || opts.agent || opts.profileId)) {
-        const agentRuntime = getAgentRuntimeSync();
-        if (agentRuntime) {
-            try {
-                const resolved = agentRuntime.resolveSync({
-                    taskType: opts.taskType,
-                    agent: opts.agent,
-                    profileId: opts.profileId,
-                    preset: presetObj?.name || (typeof opts.preset === 'string' ? opts.preset : null),
-                    provider: opts.provider || presetObj?.provider,
-                });
-                if (resolved) {
-                    profile = resolved.profile;
-                    providerCacheOpts = resolved.providerCacheOpts;
-                }
-            } catch (e) {
-                // Agent Runtime error — log once, fall back to classic behavior.
-                if (!_agentRuntimeWarned) {
-                    _agentRuntimeWarned = true;
-                    process.stderr.write(`[session] agent runtime resolve failed: ${e.message}\n`);
-                }
-            }
-        }
-    }
-
-    const providerName = opts.provider || presetObj?.provider
-        || (profile?.preferredProviders?.[0]);
-    const modelName = opts.model || presetObj?.model;
-    // opts.tools (caller-supplied) wins over presetObj.tools — caller
-    // intent ('tools:readonly' from Pool C, etc.) must override the
-    // preset's default 'full'. Previous priority let HAIKU's tools='full'
-    // shadow Pool C's explicit readonly request, leaking write tools and
-    // bash into a read-only agent.
-    const toolPreset = opts.tools || presetObj?.tools || (typeof opts.preset === 'string' ? opts.preset : null) || 'full';
-    const effort = Object.prototype.hasOwnProperty.call(opts, 'effort')
-        ? (opts.effort || null)
-        : (presetObj?.effort || null);
-    const fast = presetObj?.fast === true || opts.fast === true;
-    if (!providerName)
-        throw new Error('createSession: provider is required');
-    if (!modelName)
-        throw new Error('createSession: model is required');
-    const provider = getProvider(providerName);
-    if (!provider)
-        throw new Error(`Provider "${providerName}" not found or not enabled`);
-    const id = `sess_${process.pid}_${nextId++}_${Date.now()}_${randomBytes(16).toString('hex')}`;
-    // Provider cache strategy — agentRuntime.resolveSync() above is a
-    // best-effort injection point (setAgentRuntime() has no live caller
-    // today, so that branch never fires); build it directly here so every
-    // session still gets a cache strategy. Lead sessions (opts.agent ===
-    // 'lead', or no agent at all — raw/CLI callers) get their BP4 message
-    // tail TTL linked to the user's autoClear idle-sweep config; hidden and
-    // public agents keep the flat 5m default (see cache-strategy.mjs docs).
-    // Scoped to explicit-breakpoint (Anthropic-family) providers only — the
-    // non-Anthropic branches of buildProviderCacheOpts (e.g. the 'openai'
-    // cacheRetention:'24h' shape) were never exercised by createSession
-    // before this change, and are left untouched to avoid altering live
-    // OpenAI/other-provider request shape as a side effect of this fix.
-    if (!providerCacheOpts && cacheCapabilityForProvider(providerName) === 'explicit-breakpoint') {
-        try {
-            let autoClear = null;
-            if (!opts.agent || opts.agent === 'lead') {
-                const loadedConfig = loadConfig({ secrets: false });
-                const normalizedAutoClear = normalizeAutoClearConfig(loadedConfig?.autoClear);
-                autoClear = {
-                    ...normalizedAutoClear,
-                    idleMs: resolveAutoClearIdleMs(loadedConfig, providerName),
-                };
-            }
-            providerCacheOpts = buildProviderCacheOpts(providerName, id, opts.agent, { autoClear });
-        } catch {
-            providerCacheOpts = null;
-        }
-    }
-    const messages = [];
-    const ownerIsAgent = isAgentOwner(opts.owner);
-    const resolvedAgent = opts.agent || opts.role || profile?.taskType || null;
-    const hiddenAgent = getHiddenAgent(resolvedAgent);
-    const isRetrievalAgent = hiddenAgent?.kind === 'retrieval';
-    // Skill schema is fixed for public agent sessions, but hidden retrieval /
-    // maintenance roles are deliberately narrowed away from the Skill tool.
-    // Do not leak a Skill manifest into those hidden prompts when no Skill()
-    // loader is available.
-    const skills = (opts.skipSkills || hiddenAgent) ? [] : collectPromptSkillsCached(opts.cwd);
-
-    // BP1 is shared tool policy (+ compact skill manifest in compose). BP2 is
-    // role/system rules. User-defined schedules/webhooks ride as normal user
-    // context below so event data does not rewrite BP3 memory/meta.
-    const agentRulesAgent = opts.agent || opts.role || profile?.taskType || null;
-    const agentRulesProfile = isRetrievalAgent ? 'retrieval' : 'full';
-    const skipAgentRules = opts.skipAgentRules === true;
-    // BP1 shared tool policy ships to EVERY role (Lead, workers, retrieval,
-    // maintenance): its anti-spiral clauses (one anchor is enough, never
-    // repeat equivalent patterns/scopes, plausible hit → stop) are exactly
-    // what narrow retrieval roles need. Role docs (e.g. 30-explorer.md)
-    // override role-inapplicable entries such as the explore routing row.
-    const injectedRules = skipAgentRules ? '' : _buildSharedRules();
-    const roleRules = skipAgentRules ? '' : (ownerIsAgent ? _buildAgentRules(agentRulesProfile) : _buildLeadRules());
-    const metaContext = skipAgentRules ? '' : (ownerIsAgent ? '' : _buildLeadMetaContext());
-    const roleSpecific = ownerIsAgent && !skipAgentRules ? _buildAgentSpecific(agentRulesAgent) : '';
-    // Prompt permission is metadata for the write bundle, but a read-only role
-    // is stamped BEFORE the toolSpec decision so its schema ships the narrowed
-    // bundle. Resolve toolPermission (with profile/preset fallbacks) first, and
-    // let the stored/logged `permission` reflect that resolved value — not just
-    // opts.permission — so diagnostics show the effective read/write class.
-    const toolPermission = opts.permission
-        || profile?.permission
-        || permissionFromToolSpec(toolPreset)
-        || null;
-    const permission = toolPermission;
-
-    // Agent sessions do not inherit arbitrary role/profile/preset tool
-    // narrowing — that would shatter provider prefix reuse into one shard per
-    // role. Instead they collapse onto exactly TWO stable, bit-identical
-    // bundles, one cache group each:
-    //   - read-only roles (reviewer / debugger / hidden retrieval, i.e. any
-    //     session resolving to permission 'read') -> 'readonly' bundle:
-    //     read builtins (code_graph/find/glob/list/grep/read) + retrieval
-    //     (explore/search/web_fetch/Skill), no apply_patch/shell/task, no
-    //     MCP-write. applyToolPermissionNarrowing('read') below trims the
-    //     bundle to AGENT_STRING_PERMISSION_READ_ALLOW so the final surface is
-    //     bit-identical across these roles regardless of MCP registry state.
-    //   - write roles (worker / heavy-worker / maintainer / …) -> 'full'
-    //     bundle: the historical full schema.
-    // Call-time permission enforcement below is UNCHANGED (defense in depth):
-    // applyToolPermissionNarrowing still runs so the bundle choice never
-    // widens effective access.
-    const isReadOnlyAgentBundle = ownerIsAgent && toolPermission === 'read';
-    const toolSpec = ownerIsAgent
-        ? (isReadOnlyAgentBundle ? 'readonly' : 'full')
-        : (Array.isArray(profile?.tools) ? profile.tools : toolPreset);
-    let toolsForRouting = resolveSessionTools(toolSpec, skills, { ownerIsAgentSession: ownerIsAgent });
-    // Fail-closed permission intersection: when a session declares an explicit
-    // object-form permission, intersect the
-    // resolved tool list with the permission's allow/deny lists. If the
-    // intersection produces an empty set the permission config is broken —
-    // fail closed (zero tools) rather than silently falling back to the full
-    // preset, which would grant the role more surface than declared.
-    if (ownerIsAgent) {
-        toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, toolPermission, opts.agent || null);
-    }
 
-    const { baseRules, stableSystemContext, sessionMarker, volatileTail } = composeSystemPrompt({
-        userPrompt: opts.systemPrompt,
-        agentRules: injectedRules || undefined,
-        roleRules: roleRules || undefined,
-        metaContext: metaContext || undefined,
-        skipRoleCatalog: !ownerIsAgent,
-        profile: profile || undefined,
-        agent: resolvedAgent,
-        workflowContext: opts.workflowContext || null,
-        workspaceContext: opts.workspaceContext || null,
-        coreMemoryContext: opts.coreMemoryContext || null,
-        skillManifest: buildSkillManifest(skills),
-        tools: toolsForRouting,
-        bashIsPersistent: ownerIsAgent && toolsForRouting.some(t => t?.name === 'shell'),
-        // Effective cwd rides in tier3Reminder so explore-like tools know
-        // their search root without needing to shove "Override cwd:" into
-        // the user message body (that used to fragment the shard prefix).
-        cwd: opts.cwd || null,
-        provider: providerName || null,
-    });
-    // 4-BP layout (see composeSystemPrompt docs):
-    //   system block #1 = baseRules — BP1 (1h) shared tool policy + skills
-    //   system block #2 = stableSystemContext — BP2 (1h) role/system rules
-    //   system block #3 = sessionMarker — BP3 (1h) memory/meta + Profile
-    //     Preferences (language/name). It rides as a real `system` block so
-    //     locale/name directives are pinned firmly and do not drift to English
-    //     after a few turns the way a `user <system-reminder>` reminder did.
-    //   later normal messages        = BP4/tail (task, role data, tool history)
-    // Anthropic multi-block system pins each block with cache_control (BP3 is
-    // the 3rd system block and carries the tier3 1h marker). OpenAI/xAI get
-    // stable provider cache keys/session prefixes. Gemini manages explicit
-    // cachedContents inside its provider.
-    if (baseRules) {
-        messages.push({ role: 'system', content: baseRules });
-    }
-    if (stableSystemContext) {
-        messages.push({ role: 'system', content: stableSystemContext });
-    }
-    if (sessionMarker) {
-        // cacheTier:'tier3' tells the Anthropic providers to pin THIS system
-        // block with the tier3 1h cache_control (BP3) — distinct from the
-        // BP1/BP2 system TTL. Harmless on non-Anthropic providers (they ignore
-        // the field and serialize content as a normal system instruction).
-        messages.push({ role: 'system', content: sessionMarker, cacheTier: 'tier3' });
-    }
-    if (volatileTail) {
-        messages.push({ role: 'user', content: `<system-reminder>\n${volatileTail}\n</system-reminder>` });
-        messages.push({ role: 'assistant', content: '.' });
-    }
-    if (roleSpecific) {
-        messages.push({ role: 'user', content: `<system-reminder>\n${roleSpecific}\n</system-reminder>` });
-        messages.push({ role: 'assistant', content: '.' });
-    }
-    if (opts.files?.length) {
-        const fileContext = opts.files
-            .map(f => `### ${f.path}\n\`\`\`\n${f.content}\n\`\`\``)
-            .join('\n\n');
-        messages.push({ role: 'user', content: `Reference files:\n\n${fileContext}` });
-        messages.push({ role: 'assistant', content: '.' });
-    }
-    const hasCallerAllow = Array.isArray(opts.schemaAllowedTools);
-    const tools = finalizeSessionToolList(toolsForRouting, {
-        schemaAllowedTools: hasCallerAllow ? opts.schemaAllowedTools : null,
-        disallowedTools: hiddenAgent ? [...(Array.isArray(opts.disallowedTools) ? opts.disallowedTools : []), 'Skill'] : opts.disallowedTools,
-        ownerIsAgent,
-        resolvedAgent,
-    });
-
-    // Unified-shard policy — no broad role-specific schema filter. Keep
-    // agent schemas shared unless a hidden-role schema profile explicitly
-    // passes schemaAllowedTools for a small specialist; broad role
-    // whitelists would fragment the cache shard.
-    if (resolvedAgent && process.env.MIXDOG_DEBUG_SESSION_LOG) {
-        process.stderr.write(`[session] agent=${resolvedAgent} permission=${permission || 'full'} toolPermission=${toolPermission || 'full'} tools=${tools.length}\n`);
-    }
-    const contextMeta = resolveSessionContextMeta(provider, modelName);
-    const workflowMeta = opts.workflow && typeof opts.workflow === 'object' && String(opts.workflow.id || '').trim()
-        ? {
-            id: String(opts.workflow.id || '').trim(),
-            name: String(opts.workflow.name || opts.workflow.id || '').trim(),
-            description: String(opts.workflow.description || '').trim(),
-            source: String(opts.workflow.source || '').trim(),
-        }
-        : null;
-    const session = {
-        id,
-        provider: providerName,
-        model: modelName,
-        messages,
-        contextWindow: contextMeta.contextWindow,
-        rawContextWindow: contextMeta.rawContextWindow,
-        effectiveContextWindowPercent: contextMeta.effectiveContextWindowPercent,
-        autoCompactTokenLimit: contextMeta.autoCompactTokenLimit,
-        compactBoundaryTokens: contextMeta.compactBoundaryTokens,
-        compaction: {
-            auto: opts.compaction?.auto !== false,
-            prune: opts.compaction?.prune === true,
-            semantic: opts.compaction?.semantic ?? 'auto',
-            type: normalizeCompactType(opts.compaction?.type ?? opts.compaction?.compactType ?? opts.compaction?.compact_type, DEFAULT_COMPACT_TYPE),
-            compactType: normalizeCompactType(opts.compaction?.type ?? opts.compaction?.compactType ?? opts.compaction?.compact_type, DEFAULT_COMPACT_TYPE),
-            model: opts.compaction?.model || null,
-            timeoutMs: positiveContextWindow(opts.compaction?.timeoutMs),
-            tailTurns: positiveContextWindow(opts.compaction?.tailTurns),
-            bufferTokens: positiveContextWindow(opts.compaction?.bufferTokens ?? opts.compaction?.buffer),
-            // Preserve percent/ratio-named buffer config so the manager/loop/
-            // contextStatus parsers (which read bufferPercent/bufferPct/
-            // bufferRatio/bufferFraction) can honor it. createSession previously
-            // only stored bufferTokens, silently dropping a configured percent.
-            ...preserveBufferConfigFields(opts.compaction),
-            keepTokens: positiveContextWindow(opts.compaction?.keepTokens ?? opts.compaction?.keep?.tokens),
-            preserveRecentTokens: positiveContextWindow(opts.compaction?.preserveRecentTokens),
-            reservedTokens: positiveContextWindow(opts.compaction?.reservedTokens),
-            recallIngestLimit: positiveContextWindow(opts.compaction?.recallIngestLimit),
-            recallChunkLimit: positiveContextWindow(opts.compaction?.recallChunkLimit ?? opts.compaction?.recallLimit),
-            recallCycle1BatchSize: positiveContextWindow(opts.compaction?.recallCycle1BatchSize),
-            recallRowsPerSession: positiveContextWindow(opts.compaction?.recallRowsPerSession),
-            recallWindowSize: positiveContextWindow(opts.compaction?.recallWindowSize),
-            recallConcurrency: positiveContextWindow(opts.compaction?.recallConcurrency),
-            recallCycle1DeadlineMs: positiveContextWindow(opts.compaction?.recallCycle1DeadlineMs),
-            boundaryTokens: contextMeta.compactBoundaryTokens,
-        },
-        tools,
-        preset: toolPreset,
-        presetName: presetObj?.name || null,
-        effort,
-        fast,
-        agent: opts.agent,
-        owner: opts.owner || 'user',
-        mcpPid: process.pid,
-        scopeKey: opts.scopeKey || null,
-        lane: opts.lane || 'agent',
-        cwd: opts.cwd,
-        workflow: workflowMeta,
-        createdAt: Date.now(),
-        updatedAt: Date.now(),
-        lastHeartbeatAt: null,
-        totalInputTokens: 0,
-        totalOutputTokens: 0,
-        // Refreshed on each completed ask() — surfaced by agent type=list for
-        // debugging + consumed by store.mjs's idle-sweep to reclaim stalled
-        // agent sessions past RUNNING_STALL_MS.
-        lastUsedAt: Date.now(),
-        tokensCumulative: 0,
-        taskType: opts.taskType || null,
-        maxLoopIterations: Number.isFinite(opts.maxLoopIterations) ? opts.maxLoopIterations : null,
-        // Agent tag (auto worker{n} on spawn) persisted so the forked status
-        // process (statusline) + aggregator can read it from the session JSON.
-        // In-process send/close still resolve via _tagSessionRegistry.
-        agentTag: opts.agentTag || null,
-        // Prompt permission is separate from runtime toolPermission so preset
-        // restrictions do not fragment the agent cache prefix.
-        permission: permission || null,
-        toolPermission: toolPermission || null,
-        schemaAllowedTools: hasCallerAllow ? opts.schemaAllowedTools.map((n) => String(n)) : null,
-        // Origin tag written into every agent-trace usage row so analytics
-        // can slice by (sourceType, sourceName) — e.g. maintenance/cycle1,
-        // scheduler/daily-standup, webhook/github-push, lead/worker.
-        sourceType: opts.sourceType || null,
-        sourceName: opts.sourceName || null,
-        // Provider-scoped unified cache key — one shard per provider,
-        // shared across all roles / sources (agent/maintenance/mcp/
-        // scheduler/webhook). Role or source-specific context must be
-        // injected into the message tail, not the shared prefix.
-        promptCacheKey: providerCacheKey(presetObj?.provider || opts.provider, opts.cacheKeyOverride),
-        // Agent shell continuity: when an agent session explicitly opts into
-        // persistent shell state (`bash` with `persistent:true`, or direct
-        // `bash_session`), the minted bash_session id is stored here so later
-        // opted-in `bash` calls can reuse the same shell state.
-        implicitBashSessionId: null,
-        // Tracks every persistent bash session id minted during this
-        // orchestrator session so closeSession can kill them all, not just
-        // the most recently recorded one.
-        allBashSessionIds: [],
-        // Agent Runtime metadata — optional. Applied on every ask() to merge
-        // profile-driven cache settings into provider sendOpts.
-        profileId: profile?.id || null,
-        permissionMode: opts.permissionMode ?? null,
-        providerCacheOpts: providerCacheOpts || null,
-        ownerSessionId: opts.ownerSessionId || null,
-        clientHostPid: opts.clientHostPid || null,
-    };
-    // In-process registry + async debounced save: same-process create → load
-    // reads live memory; disk flush is for cross-process / restart durability.
-    setLiveSession(session);
-    saveSession(session);
-    return session;
-}
-
-// Runtime liveness map + its accessors moved to manager/runtime-liveness.mjs
-// (imported/re-exported above). _runtimeState is now private to that module;
-// manager.mjs internals that mutate entries in place use _getRuntimeEntry /
-// _runtimeEntries. updateSessionRoute stays here (it's a persistence helper on
-// the session store, not a liveness accessor).
-export function updateSessionRoute(id, route = {}) {
-    if (!id) return null;
-    const session = loadSession(id);
-    if (!session || session.closed === true) return null;
-    const previousProvider = session.provider || null;
-    const previousModel = session.model || null;
-    if (route.provider) session.provider = route.provider;
-    if (route.model) session.model = route.model;
-    if (Object.prototype.hasOwnProperty.call(route, 'fast')) session.fast = route.fast === true;
-    if (Object.prototype.hasOwnProperty.call(route, 'effort')) session.effort = route.effort || null;
-    const provider = session.provider ? getProvider(session.provider) : null;
-    if (provider && session.model) {
-        const contextMeta = resolveSessionContextMeta(provider, session.model);
-        session.contextWindow = contextMeta.contextWindow;
-        session.rawContextWindow = contextMeta.rawContextWindow;
-        session.effectiveContextWindowPercent = contextMeta.effectiveContextWindowPercent;
-        session.autoCompactTokenLimit = contextMeta.autoCompactTokenLimit;
-        session.compactBoundaryTokens = contextMeta.compactBoundaryTokens;
-        session.compaction = {
-            ...(session.compaction || {}),
-            boundaryTokens: contextMeta.compactBoundaryTokens,
-            contextWindow: contextMeta.contextWindow,
-            rawContextWindow: contextMeta.rawContextWindow,
-            effectiveContextWindowPercent: contextMeta.effectiveContextWindowPercent,
-            autoCompactTokenLimit: contextMeta.autoCompactTokenLimit,
-        };
-    } else {
-        delete session.contextWindow;
-        delete session.rawContextWindow;
-        delete session.effectiveContextWindowPercent;
-        delete session.autoCompactTokenLimit;
-        delete session.compactBoundaryTokens;
-    }
-    const routeChanged = (route.provider && route.provider !== previousProvider)
-        || (route.model && route.model !== previousModel);
-    if (routeChanged) {
-        const now = Date.now();
-        session.lastInputTokens = 0;
-        session.lastOutputTokens = 0;
-        session.lastCachedReadTokens = 0;
-        session.lastCacheWriteTokens = 0;
-        session.lastContextTokens = 0;
-        session.lastContextTokensUpdatedAt = now;
-        session.lastContextTokensStaleAfterCompact = false;
-        session.providerState = undefined;
-    }
-    session.updatedAt = Date.now();
-    setLiveSession(session);
-    void saveSessionAsync(session, { expectedGeneration: session.generation })
-        .catch((err) => {
-            try { process.stderr.write(`[session] route update save failed: ${err?.message || err}\n`); } catch {}
-        });
-    return session;
-}
-
-// --- Incremental metric persistence (fix A) ---
-// Usage-metrics accounting (idempotency Set, epoch/turn helpers, terminal +
-// incremental persistence) moved to manager/usage-metrics.mjs. Its runtime
-// accessor is now wired inside manager/runtime-liveness.mjs (which owns the
-// _runtimeState Map), so persistIterationMetrics can read the live in-memory
-// session and flag usageMetricsTurnIncremental.
-//
-// standaloneStatusRouteInfo + recordStandaloneStatusTelemetry moved to
-// manager/status-telemetry.mjs (imported above).
-
-/** Force-flush session metrics to disk. Used by watchdog terminal-reap (fix B). */
-export async function flushSessionMetrics(sessionId) {
-    if (!sessionId) return;
-    const session = loadSession(sessionId);
-    if (!session) return;
-    session.updatedAt = Date.now();
-    await saveSessionAsync(session, { expectedGeneration: session.generation });
-}
-
-/**
- * Wrap an async call so that if the session's controller aborts mid-flight,
- * the wrapper settles with a SessionClosedError even if the underlying promise
- * hasn't returned yet. The original promise is kept alive with a detached
- * `.catch()` to prevent unhandled-rejection warnings once it eventually
- * settles. Callers still must check generation/closed after await returns
- * to handle providers that ignore the AbortSignal entirely.
- */
-export async function _api_call_with_interrupt(sessionId, fn) {
-    const entry = _touchRuntime(sessionId);
-    if (!entry.controller) entry.controller = createAbortController();
-    const signal = entry.controller.signal;
-    const closedFromAbort = (phase) => {
-        const reason = signal.reason;
-        if (reason instanceof SessionClosedError) return reason;
-        const detail = reason instanceof Error
-            ? reason.message
-            : (reason !== undefined && reason !== null && reason !== '' ? String(reason) : '');
-        return new SessionClosedError(sessionId, detail ? `${phase}: ${detail}` : phase);
-    };
-    if (signal.aborted) throw closedFromAbort('aborted before call');
-    const underlying = fn(signal);
-    underlying.catch(() => {}); // prevent unhandled rejection if we race ahead
-    let onAbort = null;
-    const aborted = new Promise((_, reject) => {
-        onAbort = () => reject(closedFromAbort('aborted during call'));
-        if (signal.aborted) onAbort();
-        else signal.addEventListener('abort', onAbort, { once: true });
-    });
-    try {
-        return await Promise.race([underlying, aborted]);
-    } finally {
-        // If the underlying promise settled first, the abort listener is
-        // still attached. Remove it to avoid accumulating listeners across
-        // many asks on the same session.
-        if (onAbort && !signal.aborted) {
-            try { signal.removeEventListener('abort', onAbort); } catch { /* ignore */ }
-        }
-    }
-}
-
-// Per-session mutex: queues concurrent askSession calls to prevent message loss
-const _sessionLocks = new Map();
-// Per-session pending-message queue (in-flight send enqueue pattern).
-// A `agent type=send` to a worker whose turn is still in flight ENQUEUES the
-// message here instead of rejecting; askSession drains the queue after each
-// turn and runs the messages as the next user turn(s), preserving order — the
-// queued send runs AFTER the in-flight prompt, which also closes the spawn
-// startup race (a send landing before the initial turn settles no longer
-// jumps ahead of the original prompt).
-//
-// The in-memory map is mirrored to disk. Without that, a compact/API error or
-// daemon restart after returning queued:true can strand or lose a follow-up:
-// the original ask never reaches its drain point, and no new ask is scheduled.
-// Keeping the queue outside the session JSON avoids racing session saves that
-// loaded before the send arrived.
-//
-// Map<sessionId, Array<string|{text?:string,content:any}>>. Shared with
-// index.mjs's agent send handler via the enqueue/drain accessors below — one
-// queue contract, two call sites. Rich content is kept in memory for the live
-// relay path; the disk mirror stores only a text fallback so image bytes do not
-// leak into the pending-message JSON.
-function isInternalCancelledAssistantMessage(message) {
-    if (!message || message.role !== 'assistant') return false;
-    if (message.cancelled === true) return true;
-    const text = promptContentText(message.content).trim();
-    return /^\[cancelled\]\s+This turn was interrupted before completion\./i.test(text)
-        || /Preserve the user request above as the active task context/i.test(text);
-}
-
-function sanitizeSessionMessagesForModel(messages) {
-    // Drop internal runtime-notification turns and cancelled-assistant stubs so
-    // they never reach the model, but KEEP image content intact. Reference-agent
-    // parity: the live transcript and every model request retain attached
-    // images across turns; only the compaction-summary call strips them. The
-    // disk-stored session JSON replaces image bytes with a text placeholder at
-    // serialization time (see store.mjs), so this no longer touches images.
-    if (!Array.isArray(messages) || messages.length === 0) return [];
-    const out = [];
-    let droppingInternalTurn = false;
-    for (const message of messages) {
-        if (isInternalCancelledAssistantMessage(message)) {
-            droppingInternalTurn = false;
-            continue;
-        }
-        if (message?.role === 'user' && isInternalRuntimeNotificationText(message.content)) {
-            droppingInternalTurn = true;
-            continue;
-        }
-        if (droppingInternalTurn) {
-            if (message?.role === 'user') {
-                droppingInternalTurn = false;
-            } else {
-                continue;
-            }
-        }
-        out.push(message);
-    }
-    return out;
-}
-
-function acquireSessionLock(sessionId) {
-    let entry = _sessionLocks.get(sessionId);
-    if (!entry) {
-        entry = { promise: Promise.resolve(), count: 0 };
-        _sessionLocks.set(sessionId, entry);
-    }
-    entry.count++;
-    const prev = entry.promise;
-    let release;
-    entry.promise = new Promise(r => { release = r; });
-    // Self-heal: if the previous holder rejected, swallow so subsequent
-    // queued waiters don't propagate that rejection and brick the lock chain.
-    return prev.catch(() => {}).then(() => () => {
-        entry.count--;
-        if (entry.count === 0) _sessionLocks.delete(sessionId);
-        release();
-    });
-}
-
-function sessionMessagesSnapshotChanged(before, after) {
-    if (!Array.isArray(before) || !Array.isArray(after)) return before !== after;
-    if (before.length !== after.length) return true;
-    for (let i = 0; i < before.length; i += 1) {
-        if (before[i] !== after[i]) return true;
-        try {
-            if (JSON.stringify(before[i]) !== JSON.stringify(after[i])) return true;
-        } catch {
-            return true;
-        }
-    }
-    return false;
-}
-
-function isCompactedOutgoingFinalAssistantMessage(message) {
-    if (!message || message.role !== 'assistant') return false;
-    if (message.emptyFinal === true) return true;
-    return true;
-}
-
-function sessionMessagesAdvancedBeyondCompactedOutgoing(currentSanitized, compactedSanitized) {
-    if (!Array.isArray(currentSanitized) || !Array.isArray(compactedSanitized)) return false;
-    if (currentSanitized.length !== compactedSanitized.length + 1) return false;
-    const prefix = currentSanitized.slice(0, compactedSanitized.length);
-    if (sessionMessagesSnapshotChanged(compactedSanitized, prefix)) return false;
-    return isCompactedOutgoingFinalAssistantMessage(currentSanitized[currentSanitized.length - 1]);
-}
-
-export const _sessionMessagesAdvancedBeyondCompactedOutgoing = sessionMessagesAdvancedBeyondCompactedOutgoing;
-
-function applyCompactFailurePersistToSession(activeSession, {
-    priorSanitized,
-    sanitized,
-    messagesAdvanced,
-    error = null,
-}) {
-    if (!messagesAdvanced && !sessionMessagesSnapshotChanged(priorSanitized, sanitized)) return false;
-    if (!messagesAdvanced) {
-        activeSession.messages = sanitized;
-        activeSession.providerState = undefined;
-    }
-    activeSession.updatedAt = Date.now();
-    activeSession.lastUsedAt = Date.now();
-    if (activeSession.compaction && typeof activeSession.compaction === 'object'
-        && (activeSession.compaction.lastStage === 'compacting'
-            || activeSession.compaction.lastStage === 'overflow_failed')) {
-        const prev = activeSession.compaction;
-        const cause = error?.cause;
-        const overflow = error?.code === 'AGENT_CONTEXT_OVERFLOW';
-        activeSession.compaction = {
-            ...prev,
-            lastStage: prev.lastStage === 'overflow_failed'
-                ? 'overflow_failed'
-                : (overflow ? 'overflow_failed' : 'failed'),
-            lastCheckedAt: Date.now(),
-            lastError: prev.lastError || cause?.message || error?.message || null,
-            lastSemanticError: prev.lastSemanticError || cause?.message || null,
-            lastRecallFastTrackError: prev.lastRecallFastTrackError
-                || (cause?.message && String(cause?.name || '').includes('Recall') ? cause.message : null),
-        };
-    }
-    return true;
-}
-
-export const _applyCompactFailurePersistToSession = applyCompactFailurePersistToSession;
-
-async function persistCompactedOutgoingAfterAskFailure({
-    sessionId,
-    activeSession,
-    askGeneration,
-    turnOutgoing,
-    error = null,
-}) {
-    if (!activeSession || activeSession.closed === true) return;
-    if (!Array.isArray(turnOutgoing) || turnOutgoing.length === 0) return;
-    const currentRuntime = _getRuntimeEntry(sessionId);
-    if (currentRuntime?.closed || currentRuntime?.generation !== askGeneration) return;
-    const sanitized = sanitizeSessionMessagesForModel(turnOutgoing);
-    const priorSanitized = sanitizeSessionMessagesForModel(
-        Array.isArray(activeSession.messages) ? activeSession.messages : [],
-    );
-    const messagesAdvanced = sessionMessagesAdvancedBeyondCompactedOutgoing(priorSanitized, sanitized);
-    const applied = applyCompactFailurePersistToSession(activeSession, {
-        priorSanitized,
-        sanitized,
-        messagesAdvanced,
-        error,
-    });
-    if (!applied) return;
-    try {
-        await saveSessionAsync(activeSession, { expectedGeneration: askGeneration });
-    } catch { /* best-effort: preserve in-memory compaction even if disk is slow */ }
-    if (currentRuntime) currentRuntime.session = activeSession;
-}
-
-export async function askSession(sessionId, prompt, context, onToolCall, cwdOverride, explicitPrefetch, askOpts = {}) {
-    const _askStartedAt = Date.now();
-    const _promptSrc = 'prompt';
-    const _prefetchFiles = (explicitPrefetch?.files?.length) || 0;
-    const _prefetchCallers = (explicitPrefetch?.callers?.length) || 0;
-    const _prefetchRefs = (explicitPrefetch?.references?.length) || 0;
-    if (process.env.MIXDOG_DEBUG_AGENT) {
-        process.stderr.write(`[agent-trace] t0-ask-start sessionHash=${createHash('sha256').update(String(sessionId)).digest('hex').slice(0, 8)} role=? iteration=0 promptSrc=${_promptSrc} prefetchFiles=${_prefetchFiles} callers=${_prefetchCallers} references=${_prefetchRefs}\n`);
-    }
-    const unlock = await acquireSessionLock(sessionId);
-    const _lockWaitedMs = Date.now() - _askStartedAt;
-    if (process.env.MIXDOG_DEBUG_AGENT) {
-        process.stderr.write(`[agent-trace] lock-acquired waitedMs=${_lockWaitedMs}\n`);
-    }
-    // The mutex is held for the WHOLE askSession call, including any follow-up
-    // turns drained from the pending-message queue below — the single outer
-    // try/finally releases it exactly once. _result holds the last turn's
-    // return value (the queued tail turns supersede the original prompt's
-    // result, mirroring how a live chat returns the latest turn).
-    let _result;
-    // Local FIFO of follow-up prompts drained from the pending-message queue
-    // after each turn — keeps queued `agent type=send` messages in order.
-    const _pendingTail = [];
-    // Hoisted so the outer finally (which runs once after the whole turn loop)
-    // can compare against the last turn's generation.
-    let askGeneration = 0;
-    try {
-      // Turn loop (pendingMessages pattern): run the current prompt, then drain
-      // any `agent type=send` messages that were queued while this turn was in
-      // flight and run them — in order — as the next user turn(s). Because the
-      // queued send always lands AFTER the in-flight prompt here, ordering is
-      // preserved and the spawn/connecting startup race disappears.
-      for (;;) {
-        let _pwstTurnDrained = null;
-        // After the first turn, the next prompt comes from the drained queue.
-        // (On the first iteration _pendingTail is empty and `prompt` is the
-        // caller's original message.)
-        if (_pendingTail.length > 0) {
-            prompt = _pendingTail.shift();
-            // Queued follow-ups are plain user turns — no caller context /
-            // prefetch is re-applied (those belonged to the original ask).
-            context = null;
-            explicitPrefetch = null;
-        } else if (!hasModelVisiblePromptContent(prompt)) {
-            // Idle resume: TUI kicks an empty ask() after execution completions
-            // mirror model-visible bodies into session pending. Drain that queue
-            // here so we never synthesize an empty user turn for the model.
-            const _preDrained = drainPendingMessages(sessionId);
-            if (_preDrained.length > 0) {
-                const _mergedPre = _mergePendingMessageEntries(_preDrained);
-                if (_mergedPre?.content) {
-                    prompt = _mergedPre.content;
-                    context = null;
-                    explicitPrefetch = null;
-                }
-            }
-        }
-        if (!hasModelVisiblePromptContent(prompt)) {
-            _unlinkParentAbortListener(_getRuntimeEntry(sessionId));
-            return _result;
-        }
-        // ── Synchronous pre-await setup (must happen before any await so
-        //    closeSession() can't interleave between load and registration) ──
-        const preSession = loadSession(sessionId);
-        if (!preSession) {
-            throw new Error(`Session "${sessionId}" not found`);
-        }
-        if (preSession.closed === true) {
-            throw new SessionClosedError(sessionId, 'session already closed');
-        }
-        // A prior crash/partial-save during compaction may have pinned
-        // compaction.lastStage='compacting'. This ask is starting fresh, so
-        // recover the stale transient stage before the loop's pre-send compact
-        // path runs (it will overwrite lastStage with real telemetry).
-        normalizeStaleCompactingStage(preSession);
-        askGeneration = typeof preSession.generation === 'number' ? preSession.generation : 0;
-        const runtime = _touchRuntime(sessionId);
-        // Fresh controller per ask — the previous ask's controller may have aborted.
-        runtime.controller = createAbortController();
-        runtime.generation = askGeneration;
-        runtime.closed = false;
-        runtime.session = preSession;
-        markSessionAskStart(sessionId);
-        // Preprocessing is inside try so provider-not-available / trim failures
-        // fall into the catch and mark the session as errored rather than
-        // leaving stage='connecting' forever.
-        let activeSession = preSession;
-        let cancelledUserTurnContent = '';
-        let _turnOutgoing = null;
-        try {
-            const session = activeSession;
-            const provider = getProvider(session.provider);
-            // Register the live session object into runtime so closeSession()
-            // can read allBashSessionIds that loop.mjs appends mid-turn.
-            runtime.session = session;
-            if (!provider)
-                throw new Error(`Provider "${session.provider}" not available`);
-            const contextMeta = resolveSessionContextMeta(provider, session.model, session);
-            session.contextWindow = contextMeta.contextWindow;
-            session.rawContextWindow = contextMeta.rawContextWindow;
-            session.effectiveContextWindowPercent = contextMeta.effectiveContextWindowPercent;
-            session.autoCompactTokenLimit = contextMeta.autoCompactTokenLimit;
-            session.compactBoundaryTokens = contextMeta.compactBoundaryTokens;
-            session.compaction = {
-                ...(session.compaction || {}),
-                auto: session.compaction?.auto !== false,
-                semantic: session.compaction?.semantic ?? 'auto',
-                type: normalizeCompactType(session.compaction?.type ?? session.compaction?.compactType ?? session.compaction?.compact_type, DEFAULT_COMPACT_TYPE),
-                compactType: normalizeCompactType(session.compaction?.type ?? session.compaction?.compactType ?? session.compaction?.compact_type, DEFAULT_COMPACT_TYPE),
-                boundaryTokens: contextMeta.compactBoundaryTokens,
-                bufferTokens: positiveContextWindow(session.compaction?.bufferTokens ?? session.compaction?.buffer) || session.compaction?.bufferTokens || null,
-                keepTokens: positiveContextWindow(session.compaction?.keepTokens ?? session.compaction?.keep?.tokens) || session.compaction?.keepTokens || null,
-                contextWindow: contextMeta.contextWindow,
-                rawContextWindow: contextMeta.rawContextWindow,
-                effectiveContextWindowPercent: contextMeta.effectiveContextWindowPercent,
-                autoCompactTokenLimit: contextMeta.autoCompactTokenLimit,
-            };
-            // Cap caller-supplied / prefetched context so an oversized
-            // payload can't blow the session token budget before the
-            // first model call. 32 KB ~ 8k tokens at the 4 B/tok
-            // working average; longer is silently truncated with a
-            // visible marker so the model still sees the prefix and
-            // a hint about the cut.
-            const _CTX_CHAR_CAP = 32 * 1024;
-            const _capCtx = (text) => {
-                if (typeof text !== 'string') return '';
-                if (text.length <= _CTX_CHAR_CAP) return text;
-                return `${text.slice(0, _CTX_CHAR_CAP)}\n\n... [context truncated; original ${text.length} chars]`;
-            };
-            // Inline context + prefetch INTO the prompt as a single user turn,
-            // marked with explicit section headers. The previous design pushed
-            // context as separate user messages with pre-injected assistant
-            // "Noted." acks; that conversational pattern taught some models a
-            // low-effort rhythm and they responded with "Noted." / empty tags
-            // even to the real task. Single-turn structure with a labelled
-            // `# Task` block forces the model to treat the brief as the work
-            // unit, not as another piece of context to ack.
-            const explicitPrefetchResult = await _tryBridgeExplicitPrefetch(session, explicitPrefetch);
-            let _contextBlock = '';
-            if (context) {
-                _contextBlock += `# Additional context\n${_capCtx(context)}\n\n`;
-            }
-            if (explicitPrefetchResult) {
-                _contextBlock += `# Prefetch\n${_capCtx(explicitPrefetchResult)}\n\n`;
-            }
-            const historyMessages = sanitizeSessionMessagesForModel(session.messages);
-            const beforeCount = historyMessages.length + 1;
-            const promptTextForMetrics = promptContentText(prompt);
-            // Soft warning only; real size management (compaction primary,
-            // byte-budget trim as safety net) lives in agentLoop. Selecting a
-            // 25% pre-trim here would starve compaction's 50% threshold.
-            const softBudget = Math.floor(session.contextWindow * 0.25);
-            const promptTokenEstimate = promptTextForMetrics.length * 0.5; // conservative for CJK
-            if (promptTokenEstimate > softBudget * 0.7) {
-                process.stderr.write(`[session] Warning: prompt is very large (est. ${Math.round(promptTokenEstimate)} tokens vs ${softBudget} soft budget)\n`);
-            }
-            const effectiveCwd = cwdOverride || session.cwd;
-            const shouldInjectSessionStart = session.sessionStartMetaInjected !== true
-                && !hasUserConversationMessage(historyMessages);
-            const _sessionStartBlock = shouldInjectSessionStart
-                ? buildSessionStartBlock(session, effectiveCwd)
-                : '';
-            const _currentTimeBlock = buildCurrentTimeBlock(prompt);
-            const _turnReminderBlock = _currentTimeBlock
-                ? `<system-reminder>\n# Current Time\n${_currentTimeBlock}\n</system-reminder>`
-                : '';
-            const _turnPrefixBlock = [_sessionStartBlock, _turnReminderBlock].filter(Boolean).join('\n\n');
-            const _baseUserTurnContent = prefixUserTurnContent(prompt, _contextBlock);
-            const _userTurnContent = prefixSessionStartContent(_baseUserTurnContent, _turnPrefixBlock);
-            if (shouldInjectSessionStart && _sessionStartBlock) {
-                session.sessionStartMetaInjected = true;
-            }
-            cancelledUserTurnContent = _userTurnContent;
-            const outgoing = [...historyMessages, { role: 'user', content: _userTurnContent }];
-            _turnOutgoing = outgoing;
-            // Expose the in-flight working transcript so contextStatus() can
-            // estimate the LIVE context footprint mid-turn. agentLoop mutates
-            // `outgoing` in place (user turn + tool calls/results + compaction),
-            // so the statusline context gauge climbs as the turn accumulates
-            // tool output instead of freezing at the pre-turn snapshot. Cleared
-            // on turn commit (below) and in the ask finally.
-            session.liveTurnMessages = outgoing;
-            // Per-turn injected-context trace row (complements kind:"usage").
-            // Cheap byte-length accounting — no hashing, no payload bodies.
-            // Honors the same MIXDOG_AGENT_TRACE_DISABLE gate as usage rows;
-            // appendAgentTrace is a no-op when that env is set.
-            try {
-                const _ctxBytes = Buffer.byteLength(context || '', 'utf8');
-                const _prefetchBytes = Buffer.byteLength(explicitPrefetchResult || '', 'utf8');
-                const _promptBytes = promptContentBytes(prompt);
-                const _userTurnBytes = promptContentBytes(_userTurnContent);
-                const _messagesBytes = Buffer.byteLength(JSON.stringify(historyMessages || []), 'utf8');
-                const _totalBytes = _userTurnBytes + _messagesBytes;
-                appendAgentTrace({
-                    kind: 'context',
-                    sessionId,
-                    model: session.model,
-                    provider: session.provider,
-                    totalBytes: _totalBytes,
-                    breakdown: {
-                        contextBytes: _ctxBytes,
-                        prefetchBytes: _prefetchBytes,
-                        promptBytes: _promptBytes,
-                        userTurnBytes: _userTurnBytes,
-                        messagesBytes: _messagesBytes,
-                        messagesCount: historyMessages.length,
-                    },
-                });
-            } catch { /* trace must never break the ask path */ }
-            const agentLoop = await _getAgentLoop();
-            const priorToolApprovalHook = session.toolApprovalHook;
-            if (typeof askOpts?.onToolApproval === 'function') {
-                session.toolApprovalHook = askOpts.onToolApproval;
-            }
-            let result;
-            try {
-            result = await _api_call_with_interrupt(sessionId, (signal) =>
-                agentLoop(provider, outgoing, session.model, session.tools, onToolCall, effectiveCwd, {
-                    effort: session.effort || null,
-                    fast: session.fast === true,
-                    sessionId,
-                    onTextDelta: typeof askOpts?.onTextDelta === 'function' ? askOpts.onTextDelta : undefined,
-                    onReasoningDelta: typeof askOpts?.onReasoningDelta === 'function' ? askOpts.onReasoningDelta : undefined,
-                    onAssistantText: typeof askOpts?.onAssistantText === 'function' ? askOpts.onAssistantText : undefined,
-                    onUsageDelta: (d) => {
-                        persistIterationMetrics(d).catch(() => {});
-                        try { askOpts?.onUsageDelta?.(d); } catch {}
-                    },
-                    onToolResult: typeof askOpts?.onToolResult === 'function' ? askOpts.onToolResult : undefined,
-                    onToolApproval: typeof askOpts?.onToolApproval === 'function' ? askOpts.onToolApproval : undefined,
-                    onCompactEvent: typeof askOpts?.onCompactEvent === 'function' ? askOpts.onCompactEvent : undefined,
-                    // Mid-turn steering drain. agentLoop calls this at every
-                    // tool-batch boundary (before the next provider.send) and
-                    // injects any returned strings as user turns — so input
-                    // (user typing, `agent type=send`) that arrives WHILE a
-                    // long multi-tool turn is in flight is picked up on the
-                    // model's very next iteration instead of waiting for the
-                    // whole task to finish. The post-turn _pendingTail drain
-                    // below still handles "followUp" input that lands after the
-                    // agent would otherwise stop. Same queue, two drain points.
-                    drainSteering: (sid) => {
-                        const out = [];
-                        if (typeof askOpts?.drainSteering === 'function') {
-                            try {
-                                const drained = askOpts.drainSteering(sid || sessionId);
-                                if (Array.isArray(drained)) out.push(...drained);
-                            } catch { /* best-effort steering drain */ }
-                        }
-                        try { out.push(...drainPendingMessages(sid || sessionId)); }
-                        catch { /* best-effort pending drain */ }
-                        return out;
-                    },
-                    onSteerMessage: typeof askOpts?.onSteerMessage === 'function' ? askOpts.onSteerMessage : undefined,
-                    notifyFn: typeof askOpts?.notifyFn === 'function' ? askOpts.notifyFn : undefined,
-                    promptCacheKey: session.promptCacheKey || sessionId,
-                    // Provider-scoped cache key (mixdog-codex, mixdog-claude…).
-                    // Distinct from sessionId — providers that pool sockets
-                    // per-session (openai-oauth WS) use sessionId as the
-                    // pool bucket and providerCacheKey as the server-side
-                    // prompt-cache shard so parallel callers don't collide
-                    // on a mid-turn socket while still sharing prefix cache.
-                    providerCacheKey: session.promptCacheKey || null,
-                    signal,
-                    providerState: session.providerState ?? undefined,
-                    session,
-                    // Agent Runtime cache settings — merged last so session overrides
-                    // don't get overridden by defaults. When session has no profile,
-                    // providerCacheOpts is null and this spread is a no-op.
-                    ...(session.providerCacheOpts || {}),
-                    onStageChange: (stage) => {
-                        updateSessionStage(sessionId, stage);
-                        try { askOpts?.onStageChange?.(stage); } catch {}
-                    },
-                    onStreamDelta: () => {
-                        markSessionStreamDelta(sessionId).catch(() => {});
-                        try { askOpts?.onStreamDelta?.(); } catch {}
-                    },
-                }),
-            );
-            } finally {
-                if (priorToolApprovalHook === undefined) {
-                    delete session.toolApprovalHook;
-                } else {
-                    session.toolApprovalHook = priorToolApprovalHook;
-                }
-            }
-            // Post-loop validation: if closeSession() landed while we were awaiting,
-            // drop the save so the tombstone on disk isn't overwritten.
-            const currentRuntime = _getRuntimeEntry(sessionId);
-            if (currentRuntime?.closed || currentRuntime?.generation !== askGeneration) {
-                const reason = currentRuntime?.closedReason;
-                throw new SessionClosedError(sessionId, `closed during call (reason=${reason || 'unknown'})`, reason || null);
-            }
-            // Update and save. outgoing is mutated in place by agentLoop
-            // (compaction + safety trim), so its length reflects post-loop state.
-            const messagesDropped = Math.max(0, beforeCount - outgoing.length);
-            session.messages = sanitizeSessionMessagesForModel(outgoing);
-            // Turn committed into session.messages; drop the live-turn alias so
-            // contextStatus() reverts to the authoritative committed transcript.
-            session.liveTurnMessages = null;
-            if (result.content || result.reasoningContent) {
-                session.messages.push({
-                    role: 'assistant',
-                    // Keep content as-is in memory (model-visible). Image bytes,
-                    // if any, are swapped for a placeholder only at disk write
-                    // time inside the session store (store.mjs _sessionForDisk).
-                    content: result.content || '',
-                    ...(typeof result.reasoningContent === 'string' && result.reasoningContent
-                        ? { reasoningContent: result.reasoningContent }
-                        : {}),
-                });
-            } else {
-                // Empty terminal turn: still persist a forensic record so
-                // post-mortem inspection can distinguish "work landed but
-                // synthesis missing" from "session never ran". Stop reason,
-                // usage, iterations, and tool-call totals survive even when
-                // the assistant produced no content/reasoning.
-                const _emptyStop = result?.stopReason ?? result?.stop_reason ?? null;
-                const _emptyUsage = result?.usage ? {
-                    inputTokens: result.usage.inputTokens || 0,
-                    outputTokens: result.usage.outputTokens || 0,
-                    cachedTokens: result.usage.cachedTokens || 0,
-                    cacheWriteTokens: result.usage.cacheWriteTokens || 0,
-                } : null;
-                // Provider content-block classification — distinguishes a
-                // thinking-only stall (model emitted reasoning blocks but no
-                // text/tool_use) from a true silent empty turn. Anthropic
-                // providers (anthropic.mjs, anthropic-oauth.mjs) set these
-                // fields on the result; other providers may omit them.
-                const _emptyHasThinking = typeof result?.hasThinkingContent === 'boolean'
-                    ? result.hasThinkingContent
-                    : null;
-                const _emptyBlockTypes = Array.isArray(result?.contentBlockTypes)
-                    ? result.contentBlockTypes.slice()
-                    : null;
-                session.messages.push({
-                    role: 'assistant',
-                    content: '',
-                    emptyFinal: true,
-                    stopReason: _emptyStop,
-                    iterations: result?.iterations ?? null,
-                    toolCallsTotal: result?.toolCallsTotal ?? null,
-                    usage: _emptyUsage,
-                    ...(_emptyHasThinking !== null ? { hasThinkingContent: _emptyHasThinking } : {}),
-                    ...(_emptyBlockTypes !== null ? { contentBlockTypes: _emptyBlockTypes } : {}),
-                    ts: Date.now(),
-                });
-                try {
-                    const _blockTypesStr = _emptyBlockTypes ? _emptyBlockTypes.join(',') || 'none' : 'unknown';
-                    const _thinkingStr = _emptyHasThinking === null ? 'unknown' : String(_emptyHasThinking);
-                    process.stderr.write(`[session] empty-final persisted sessionId=${sessionId} stopReason=${_emptyStop ?? 'unknown'} iterations=${result?.iterations ?? 0} toolCallsTotal=${result?.toolCallsTotal ?? 0} outTokens=${_emptyUsage?.outputTokens ?? 0} hasThinking=${_thinkingStr} blockTypes=${_blockTypesStr}\n`);
-                } catch {}
-            }
-            session.updatedAt = Date.now();
-            session.lastUsedAt = Date.now();
-            applyAskTerminalUsageTotals(session, result, {
-                skipTotalsIfIncremental: runtime?.usageMetricsTurnIncremental === true,
-            });
-            // Agent Runtime cache stats — record hit/miss after every successful
-            // ask so the registry reflects all agent traffic, not just
-            // maintenance cycles. Guarded against any agent-runtime error so
-            // metric recording never breaks the ask itself.
-            let prefixHashForLog = null;
-            if (session.profileId && result.usage && _agentRuntimeApi) {
-                try {
-                    const profile = _agentRuntimeApi.getProfile(session.profileId);
-                    if (profile) {
-                        // Collect every leading system-role message (BP1, BP2, ...)
-                        // until the first non-system message so the registry hash
-                        // captures the full ordered provider prefix, not just BP1.
-                        const systemMsgs = [];
-                        for (const m of session.messages) {
-                            if (m?.role !== 'system') break;
-                            systemMsgs.push(typeof m.content === 'string' ? m.content : '');
-                        }
-                        _agentRuntimeApi.recordCall(profile, session.provider, {
-                            systemPrompt: systemMsgs,
-                            tools: session.tools || [],
-                            usage: result.usage,
-                        });
-                        const entry = _agentRuntimeApi.registry?.data?.profiles?.[session.profileId]?.[session.provider];
-                        prefixHashForLog = entry?.prefixHash || null;
-                    }
-                } catch {}
-            }
-            // Append to the agent trace store with rich usage fields.
-            if (result.usage) {
-                const inputTokens = result.usage.inputTokens || 0;
-                const outputTokens = result.usage.outputTokens || 0;
-                const cacheReadTokens = result.usage.cachedTokens || 0;
-                const cacheWriteTokens = result.usage.cacheWriteTokens || 0;
-                // Unified total-prompt field. Anthropic = input+cache_read+cache_write
-                // (additive); OpenAI OAuth/API/Gemini = input_tokens already includes the
-                // cached portion (inclusive), so the fallback must not double-count.
-                const { isInclusiveProvider, computeCostUsd } = await import('../../../shared/llm/cost.mjs');
-                const inclusive = isInclusiveProvider(session.provider);
-                const promptTokens = typeof result.usage.promptTokens === 'number'
-                    ? result.usage.promptTokens
-                    : (inclusive
-                        ? Math.max(inputTokens, cacheReadTokens + cacheWriteTokens)
-                        : inputTokens + cacheReadTokens + cacheWriteTokens);
-                let costUsd = result.usage.costUsd || 0;
-                if (!costUsd) {
-                    try {
-                        costUsd = computeCostUsd({
-                            model: session.model,
-                            provider: session.provider,
-                            inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens,
-                        });
-                    } catch { /* best-effort */ }
-                }
-                logLlmCall({
-                    ts: new Date().toISOString(),
-                    sourceType: session.sourceType || 'lead',
-                    sourceName: session.sourceName || session.agent || null,
-                    preset: session.presetName || null,
-                    model: session.model,
-                    provider: session.provider,
-                    duration: Date.now() - _askStartedAt,
-                    profileId: session.profileId || null,
-                    sessionId: session.id,
-                    inputTokens,
-                    outputTokens,
-                    cacheReadTokens,
-                    cacheWriteTokens,
-                    promptTokens,
-                    prefixHash: prefixHashForLog,
-                    costUsd,
-                });
-                recordStandaloneStatusTelemetry(session, result, Date.now() - _askStartedAt);
-            }
-            // Persist opaque providerState for future stateful providers.
-            // No provider currently emits it (openai-oauth is stateless per
-            // contract), so this branch is dormant — kept so a future
-            // Responses-API provider with stable continuation can plug in
-            // without reworking the session shape.
-            if (result.providerState !== undefined) {
-                session.providerState = result.providerState;
-            }
-            const terminalResultPreview = {
-                ...result,
-                trimmed: messagesDropped > 0,
-                messagesDropped,
-            };
-            _pwstTurnDrained = drainPendingMessages(sessionId);
-            if (_pwstTurnDrained.length === 0 && typeof askOpts?.onTerminalResult === 'function') {
-                try {
-                    askOpts.onTerminalResult(terminalResultPreview, {
-                        sessionId,
-                        beforeSave: true,
-                        durationMs: Date.now() - _askStartedAt,
-                    });
-                } catch { /* best-effort early completion relay */ }
-            }
-            // Auto-compact runs at the start of the next
-            // query/provider send (agentLoop pre-send), not after the previous
-            // answer. This lets queued follow-up prompts resume immediately;
-            // if they need compaction, their own spinner shows compacting first.
-            // Bounded, best-effort terminal save. The result is already produced
-            // and (for agent surfaces) relayed via onTerminalResult above. If the
-            // disk write stalls, blocking the terminal unwind here would strand the
-            // owning background task in `running` and suppress its completion
-            // notification. Cap the wait; let a slow write finish in the
-            // background instead of holding askSession() open indefinitely.
-            {
-                const savePromise = saveSessionAsync(session, { expectedGeneration: askGeneration });
-                let saveTimer = null;
-                const saveTimeout = new Promise((resolveTimeout) => {
-                    saveTimer = setTimeout(() => resolveTimeout('__save_timeout__'), TERMINAL_SAVE_TIMEOUT_MS);
-                    saveTimer.unref?.();
-                });
-                try {
-                    const outcome = await Promise.race([
-                        savePromise.then(() => '__save_ok__', (err) => { throw err; }),
-                        saveTimeout,
-                    ]);
-                    if (outcome === '__save_timeout__') {
-                        try { process.stderr.write(`[session] terminal save exceeded ${TERMINAL_SAVE_TIMEOUT_MS}ms; continuing best-effort (${sessionId})\n`); } catch {}
-                        // Don't drop the write — let it settle in the background.
-                        savePromise.catch((err) => {
-                            try { process.stderr.write(`[session] deferred terminal save failed: ${err?.message || err}\n`); } catch {}
-                        });
-                    }
-                } finally {
-                    if (saveTimer) { try { clearTimeout(saveTimer); } catch {} }
-                }
-            }
-            activeSession = session;
-            runtime.session = session;
-            // Tag empty-synthesis BEFORE markSessionDone so the watchdog
-            // (which inspects entry.emptyFinal first) classifies the
-            // terminal state correctly even if it ticks during unwind.
-            const isEmptyFinal = !result.content && !result.reasoningContent;
-            if (isEmptyFinal) {
-                markSessionEmptyFinal(sessionId);
-            }
-            markSessionDone(sessionId, { empty: isEmptyFinal });
-            _result = terminalResultPreview;
-        } catch (err) {
-            // Cancellation/error paths bypass the commit point above; drop the
-            // live-turn alias so contextStatus() stops estimating from the
-            // stale in-flight array once the turn unwinds.
-            if (activeSession) activeSession.liveTurnMessages = null;
-            if (err instanceof SessionClosedError) {
-                const currentRuntime = _getRuntimeEntry(sessionId);
-                if (!currentRuntime?.closed) {
-                    if (activeSession) {
-                        const originalMessages = Array.isArray(activeSession.messages) ? activeSession.messages : [];
-                        const cleanedMessages = sanitizeSessionMessagesForModel(originalMessages);
-                        const nextMessages = cleanedMessages.slice();
-                        // In-memory cancelled turn keeps its original content
-                        // (images intact for the next model send); the store
-                        // layer placeholders image bytes on disk serialization.
-                        const cancelledStoredContent = cancelledUserTurnContent;
-                        const shouldPreserveUserTurn = cancelledStoredContent && !isInternalRuntimeNotificationText(cancelledStoredContent);
-                        const lastMessage = nextMessages[nextMessages.length - 1];
-                        if (shouldPreserveUserTurn && !(lastMessage?.role === 'user' && promptContentText(lastMessage.content) === promptContentText(cancelledStoredContent))) {
-                            nextMessages.push({ role: 'user', content: cancelledStoredContent });
-                        }
-                        const messagesChanged = nextMessages.length !== originalMessages.length
-                            || nextMessages.some((message, index) => message !== originalMessages[index]);
-                        if (messagesChanged) {
-                            activeSession.messages = nextMessages;
-                            activeSession.updatedAt = Date.now();
-                            activeSession.lastUsedAt = Date.now();
-                            try {
-                                await saveSessionAsync(activeSession, { expectedGeneration: askGeneration });
-                            } catch { /* cancellation cleanup is best-effort */ }
-                        }
-                    }
-                    markSessionCancelled(sessionId);
-                }
-                // Cancellation is not an error; propagate silently so callers
-                // can render it as "cancelled" rather than a red failure.
-                throw err;
-            }
-            await persistCompactedOutgoingAfterAskFailure({
-                sessionId,
-                activeSession,
-                askGeneration,
-                turnOutgoing: _turnOutgoing,
-                error: err,
-            });
-            markSessionError(sessionId, err && err.message ? err.message : String(err));
-            throw err;
-        }
-        // ── Turn complete. Drain the pending-message queue: any `agent type=send` that arrived while this
-        //    turn was in flight runs next, in order, as a follow-up user turn.
-        //    The mutex is still held, so a send racing this drain either landed
-        //    before (picked up here) or enqueues for the next loop. When the
-        //    queue is empty we return the latest turn's result. ──
-        const _drained = (_pwstTurnDrained && _pwstTurnDrained.length > 0)
-            ? _pwstTurnDrained
-            : drainPendingMessages(sessionId);
-        if (_drained.length > 0) {
-            // Same merge rule as the mid-turn steering drain (loop.mjs) and
-            // the TUI engine.mjs drain(): a single drain batch is joined with
-            // "\n" and delivered as ONE follow-up turn, not N isolated turns.
-            // Keeps every steering/follow-up path on identical
-            // merge-then-deliver semantics. Anything that arrives AFTER this
-            // drain enqueues for the next loop pass and is merged there.
-            const _mergedTail = _mergePendingMessageEntries(_drained);
-            if (_mergedTail?.content) {
-                _pendingTail.push(_mergedTail.content);
-                const refreshed = loadSession(sessionId);
-                if (refreshed && refreshed.closed !== true) {
-                    activeSession = refreshed;
-                    runtime.session = refreshed;
-                }
-                continue;
-            }
-        }
-        _unlinkParentAbortListener(_getRuntimeEntry(sessionId));
-        return _result;
-      }
-    } finally {
-        // Clear the controller only if it's still ours (closeSession may have
-        // swapped it). Leave the rest of the runtime entry intact so agent type=list
-        // can still surface the final stage (done/error/cancelling).
-        const entry = _getRuntimeEntry(sessionId);
-        if (entry && entry.generation === askGeneration) {
-            _unlinkParentAbortListener(entry);
-            entry.controller = null;
-            // Detach the live session reference; ask is over.
-            entry.session = null;
-        }
-        unlock();
-    }
-}
-// Session lookup by scopeKey — used by CLI agent to resume a pinned
-// scope session when the caller passes --scope (agent/<name>).
-export function findSessionByScopeKey(scopeKey) {
-    if (!scopeKey) return null;
-    const summaries = listStoredSessionSummaries();
-    // Exclude tombstoned sessions (`closed === true`) so callers never receive
-    // a session whose controller was aborted by closeSession(). The `closed`
-    // bit is the authoritative tombstone flag; `status === 'error'` is not,
-    // since transient-error sessions remain resumable.
-    const summary = summaries.find(s => s.scopeKey === scopeKey && s.closed !== true) || null;
-    return summary?.id ? loadSession(summary.id) : null;
-}
-// --- resume (reload tools for a stored session) ---
-export async function resumeSession(sessionId, preset) {
-    const session = loadSession(sessionId);
-    if (!session)
-        return null;
-    // Resuming a closed session is a resurrection attempt — refuse. The guarded
-    // save below would also block the write, but failing fast here is cleaner
-    // than silently dropping the tool-refresh side effects.
-    if (session.closed === true) return null;
-    if (!session.owner) session.owner = 'user';
-    // A crash / partial save during compaction can leave compaction.lastStage
-    // pinned at 'compacting'. The TUI (App.jsx openContextPicker) reads that as
-    // an in-progress compaction and would show "Compacting conversation"
-    // forever on resume. No compaction is actually running for a freshly loaded
-    // session, so normalize the stale transient stage back to an interrupted
-    // marker. Successful auto/manual compact persistence (lastStage post_turn /
-    // manual / auto_clear) is untouched.
-    normalizeStaleCompactingStage(session);
-    // Refresh tools (MCP connections may have changed).
-    // Re-resolve from profile.tools when the session stored a profileId —
-    // otherwise fall back to preset.tools. Same resolution order as
-    // createSession so resume and spawn produce identical BP_1 shapes.
-    const oldTools = session.tools || [];
-    const ownerIsAgent = isAgentOwner(session);
-    const skills = ownerIsAgent ? [] : collectPromptSkillsCached(session.cwd);
-    let toolSpec = ownerIsAgent ? 'full' : (preset || session.preset || 'full');
-    if (session.profileId && _agentRuntimeApi?.getProfile) {
-        try {
-            const profile = _agentRuntimeApi.getProfile(session.profileId);
-            if (!ownerIsAgent && Array.isArray(profile?.tools)) toolSpec = profile.tools;
-        } catch { /* ignore lookup failures, keep preset fallback */ }
-    }
-    let toolsForRouting = resolveSessionTools(toolSpec, skills, { ownerIsAgentSession: ownerIsAgent });
-    if (ownerIsAgent) {
-        toolsForRouting = applyToolPermissionNarrowing(toolsForRouting, session.toolPermission, session.agent || null);
-    }
-    session.tools = finalizeSessionToolList(toolsForRouting, {
-        schemaAllowedTools: Array.isArray(session.schemaAllowedTools) ? session.schemaAllowedTools : null,
-        disallowedTools: getHiddenAgent(session.agent || null) ? ['Skill'] : null,
-        ownerIsAgent,
-        resolvedAgent: session.agent || null,
-    });
-    const newTools = session.tools;
-    const missing = oldTools.filter(t => !newTools.find(n => n.name === t.name));
-    if (missing.length) {
-        process.stderr.write(`[session] Warning: ${missing.length} tools no longer available: ${missing.map(t => t.name).join(', ')}\n`);
-    }
-    await saveSessionAsync(session, { expectedGeneration: session.generation });
-    return session;
-}
-// --- CRUD ---
-export function getSession(id) {
-    return loadSession(id);
-}
-export function listSessions(opts = {}) {
-    const includeClosed = opts.includeClosed === true;
-    const sessions = listStoredSessionSummaries();
-    const hiddenIds = new Set([..._runtimeEntries()].filter(([, e]) => e.listHidden).map(([id]) => id));
-    // Tombstoned sessions (closed===true) are excluded unless the caller opts in
-    // (e.g. agent list includeClosed:true).
-    return sessions.filter(s => !hiddenIds.has(s.id) && (includeClosed || s.closed !== true));
-}
-// --- Clear messages (keep system prompt + provider/model/cwd) ---
-export async function clearSessionMessages(sessionId, options = {}) {
-    const session = loadSession(sessionId);
-    if (!session)
-        return false;
-    // Don't resurrect a closed session just to clear its messages.
-    if (session.closed === true) return false;
-    const clearOptions = options && typeof options === 'object' ? options : {};
-    const requestedCompactType = clearOptions.compactType ?? clearOptions.compact_type ?? clearOptions.type;
-    const compactBeforeClear = requestedCompactType != null && requestedCompactType !== false && String(requestedCompactType).trim() !== '';
-    const keep = [];
-    let messages = Array.isArray(session.messages) ? session.messages : [];
-    const beforeMessageTokens = estimateMessagesTokens(messages);
-    let clearCompactType = null;
-    let clearCompactError = null;
-    if (compactBeforeClear && messages.length >= 3) {
-        clearCompactType = normalizeCompactType(requestedCompactType, DEFAULT_COMPACT_TYPE);
-        session.compaction = {
-            ...(session.compaction || {}),
-            type: clearCompactType,
-            compactType: clearCompactType,
-        };
-        try {
-            const compactResult = await runSessionCompaction(session, { mode: 'manual', force: true, sessionId });
-            if (compactResult?.error) {
-                clearCompactError = new Error(compactResult.error);
-            }
-        } catch (err) {
-            clearCompactError = err;
-            try { process.stderr.write(`[session] auto-clear pre-compact failed (sess=${sessionId}): ${err?.message || err}\n`); } catch { /* best-effort */ }
-        }
-        messages = Array.isArray(session.messages) ? session.messages : [];
-    }
-    if (compactBeforeClear && clearOptions.requireCompactSuccess === true) {
-        const hasRetainedSummary = messages.some((m) => (
-            m?.role === 'user'
-            && typeof m.content === 'string'
-            && m.content.startsWith(SUMMARY_PREFIX)
-        ));
-        if (!hasRetainedSummary && !clearCompactError) {
-            clearCompactError = new Error('compact produced no retained summary');
-        }
-    }
-    if (clearCompactError && clearOptions.requireCompactSuccess === true) {
-        const now = Date.now();
-        session.compaction = {
-            ...(session.compaction || {}),
-            lastStage: 'auto_clear_failed',
-            lastCheckedAt: now,
-            lastChanged: false,
-            lastClearAt: session.compaction?.lastClearAt || null,
-            lastClearCompactType: clearCompactType || session.compaction?.compactType || null,
-            lastClearCompactError: clearCompactError?.message || String(clearCompactError),
-        };
-        session.updatedAt = now;
-        await saveSessionAsync(session, { expectedGeneration: session.generation });
-        throw new Error(`auto-clear compact failed; conversation kept: ${session.compaction.lastClearCompactError}`);
-    }
-    const preserveCompactSummary = compactBeforeClear && clearOptions.keepCompactSummary !== false;
-    for (let i = 0; i < messages.length; i += 1) {
-        const m = messages[i];
-        if (!m) continue;
-        if (m.role === 'system') {
-            // BP1/BP2/BP3 all ride `role:'system'` blocks now (BP3 sessionMarker
-            // moved off the `<system-reminder>` user wrapper), so the stable
-            // memory/meta layer is preserved here unconditionally — no sentinel
-            // scan / dummy-assistant pairing needed anymore.
-            keep.push(m);
-            continue;
-        }
-        if (preserveCompactSummary
-            && m.role === 'user'
-            && typeof m.content === 'string'
-            && m.content.startsWith(SUMMARY_PREFIX)) {
-            keep.push(m);
-        }
-    }
-    const afterMessageTokens = estimateMessagesTokens(keep);
-    const beforeTokens = estimateTranscriptContextUsage(messages, session.tools || []);
-    const afterTokens = estimateTranscriptContextUsage(keep, session.tools || []);
-    const now = Date.now();
-    // --- Fork the outgoing transcript to a separate resumable session BEFORE
-    // the wipe below. Runs for every clear path (plain /clear, auto-clear,
-    // compact_clear) using the ORIGINAL `messages` (post-compact-gating, i.e.
-    // whatever survived the requireCompactSuccess throw above), so the
-    // conversation about to be discarded stays reachable via /resume under a
-    // fresh id. Skipped for scratch sessions with no real user turn — nothing
-    // worth resuming. Best-effort: any failure here must never block the
-    // clear itself (mirrors the pre-compact failure handling above).
-    if (hasUserConversationMessage(messages)) {
-        try {
-            const forkId = `sess_${process.pid}_${nextId++}_${Date.now()}_${randomBytes(16).toString('hex')}`;
-            const fork = {
-                ...session,
-                id: forkId,
-                messages: messages.map((m) => (m && typeof m === 'object' ? { ...m } : m)),
-                closed: false,
-                status: 'idle',
-                generation: 0,
-                createdAt: now,
-                updatedAt: now,
-                lastUsedAt: now,
-                lastHeartbeatAt: null,
-                mcpPid: process.pid,
-                // Strip runtime/liveness/routing state — the fork is a cold
-                // snapshot, not a live process-owned session.
-                clientHostPid: null,
-                providerState: undefined,
-                totalInputTokens: 0,
-                totalOutputTokens: 0,
-                totalCachedReadTokens: 0,
-                totalCacheWriteTokens: 0,
-                lastInputTokens: 0,
-                lastOutputTokens: 0,
-                lastCachedReadTokens: 0,
-                lastCacheWriteTokens: 0,
-                lastContextTokens: 0,
-                lastContextTokensUpdatedAt: now,
-                lastContextTokensStaleAfterCompact: false,
-                // Shell state must not alias the live session: resuming the
-                // fork would otherwise reuse/close the original session's
-                // persistent bash shells.
-                implicitBashSessionId: null,
-                allBashSessionIds: undefined,
-            };
-            delete fork.liveTurnMessages;
-            setLiveSession(fork);
-            void saveSessionAsync(fork).catch((err) => {
-                try { process.stderr.write(`[session] clear-fork save failed (sess=${forkId}): ${err?.message || err}\n`); } catch { /* best-effort */ }
-            });
-        } catch (err) {
-            try { process.stderr.write(`[session] clear-fork failed (sess=${sessionId}): ${err?.message || err}\n`); } catch { /* best-effort */ }
-        }
-    }
-    session.messages = keep;
-    session.sessionStartMetaInjected = false;
-    session.totalInputTokens = 0;
-    session.totalOutputTokens = 0;
-    session.totalCachedReadTokens = 0;
-    session.totalCacheWriteTokens = 0;
-    session.lastInputTokens = 0;
-    session.lastOutputTokens = 0;
-    session.lastCachedReadTokens = 0;
-    session.lastCacheWriteTokens = 0;
-    session.lastContextTokens = 0;
-    session.lastContextTokensUpdatedAt = now;
-    session.lastContextTokensStaleAfterCompact = false;
-    session.providerState = undefined;
-    session.compaction = {
-        ...(session.compaction || {}),
-        lastStage: 'auto_clear',
-        lastBeforeTokens: beforeTokens,
-        lastAfterTokens: afterTokens,
-        lastBeforeMessageTokens: beforeMessageTokens,
-        lastAfterMessageTokens: afterMessageTokens,
-        lastPressureTokens: beforeTokens,
-        lastCheckedAt: now,
-        lastChanged: beforeTokens !== afterTokens,
-        lastClearAt: now,
-        lastClearBeforeTokens: beforeTokens,
-        lastClearAfterTokens: afterTokens,
-        lastClearBeforeMessageTokens: beforeMessageTokens,
-        lastClearAfterMessageTokens: afterMessageTokens,
-        lastClearCompactType: clearCompactType || session.compaction?.compactType || null,
-        lastClearCompactError: clearCompactError?.message || null,
-    };
-    session.updatedAt = now;
-    await saveSessionAsync(session, { expectedGeneration: session.generation });
-    return session;
-}
-export async function compactSessionMessages(sessionId) {
-    const session = loadSession(sessionId);
-    if (!session) return null;
-    if (session.closed === true) return null;
-    if (isSessionCompactionBlocked(sessionId)) {
-        return { changed: false, reason: 'compact skipped: turn in progress' };
-    }
-    const result = await runSessionCompaction(session, {
-        mode: 'manual',
-        force: true,
-        provider: getProvider(session.provider),
-        model: session.model,
-        sessionId,
-        signal: getSessionAbortSignal(sessionId),
-    });
-    if (!result) return null;
-    const now = Date.now();
-    if (!result.error) {
-        session.lastInputTokens = 0;
-        session.lastOutputTokens = 0;
-        session.lastCachedReadTokens = 0;
-        session.lastCacheWriteTokens = 0;
-        session.lastContextTokens = 0;
-        session.lastContextTokensUpdatedAt = now;
-        session.lastContextTokensStaleAfterCompact = false;
-    }
-    session.updatedAt = Date.now();
-    await saveSessionAsync(session, { expectedGeneration: session.generation });
-    return result;
-}
-export async function updateSessionStatus(id, status) {
-    const session = loadSession(id);
-    if (!session) return false;
-    // Respect tombstones — don't resurrect a closed session just to update a
-    // status label (agent handler emits running→idle/error around askSession).
-    if (session.closed === true) return false;
-    session.status = status;
-    session.updatedAt = Date.now();
-    await saveSessionAsync(session, { expectedGeneration: session.generation });
-    return true;
-}
-/**
- * Close a session. Plants a `closed=true` tombstone on disk with a bumped
- * generation (so any racing saveSession() drops its write), aborts the
- * in-flight controller if one exists, and clears the in-memory runtime entry.
- *
- * IMPORTANT: we deliberately do NOT unlink the session file here. The tombstone
- * on disk is the authoritative signal that blocks resurrection — a late
- * saveSession() re-reads disk via _shouldDrop() and will find the tombstone.
- * If we delete the file, a late save sees no file, decides nothing to drop,
- * and recreates the session in its pre-close state.
- *
- * Long-term cleanup: `sweepTombstones()` below unlinks tombstones older than
- * TOMBSTONE_MAX_AGE_MS (24h — vastly longer than any realistic in-flight race).
- */
-export function closeSession(id, reason = 'manual', opts = {}) {
-    // tombstone=false: detach runtime resources (heartbeat, bash shells,
-    // controller abort, runtime-map clear) WITHOUT planting the disk
-    // tombstone. Used for non-empty sessions on /resume-away, /new, and
-    // TUI exit — previously every one of those paths unconditionally
-    // tombstoned the outgoing session, which made it vanish from the
-    // Resume list immediately and get hard-deleted by sweepTombstones()
-    // after 24h even though it had real conversation content worth
-    // resuming. Only truly-empty scratch sessions should still tombstone.
-    const tombstone = opts.tombstone !== false;
-    if (!id) return false;
-    _stopToolActivityHeartbeat(id);
-    // Prefer in-memory runtime session — allBashSessionIds may not be persisted
-    // yet for shells opened in the current turn (BL-bash-disk-sync).
-    const inMemory = _getRuntimeEntry(id)?.session;
-    const persisted = inMemory || loadSession(id);
-    const bashSessionId = persisted?.implicitBashSessionId || null;
-    // Collect all persistent bash shells created during this session.
-    const allBashIds = Array.isArray(persisted?.allBashSessionIds)
-        ? persisted.allBashSessionIds.filter(Boolean)
-        : (bashSessionId ? [bashSessionId] : []);
-    // Deduplicate: allBashIds already covers implicitBashSessionId, but guard
-    // against old session records that only have implicitBashSessionId.
-    if (bashSessionId && !allBashIds.includes(bashSessionId)) allBashIds.push(bashSessionId);
-    // 1. Tombstone first — this wins the race against saveSession().
-    //    Skipped when tombstone=false: no closed:true marker is planted, so
-    //    the session file stays intact and resumeSession() will accept it.
-    //    We still bump the on-disk generation via bumpSessionGeneration() —
-    //    that alone is what protects the session from a late save race: any
-    //    saveSession() still in flight from this detached turn (e.g. the
-    //    cancel-cleanup save below) carries the OLD generation as its
-    //    expectedGeneration, so _shouldDrop()'s ownership-counter rule drops
-    //    it once disk generation moves past that. Without this bump the late
-    //    write could silently overwrite the session after the user resumes
-    //    it back (BL: burned-session late-save clobber).
-    const newGen = tombstone ? markSessionClosed(id, reason) : bumpSessionGeneration(id, reason);
-    // 2. Mark runtime as closed so post-await validation in askSession fires.
-    const entry = _getRuntimeEntry(id);
-    if (entry) {
-        entry.closed = true;
-        entry.closedReason = reason;
-        if (typeof newGen === 'number') entry.generation = newGen;
-        entry.stage = 'cancelling';
-        entry.updatedAt = Date.now();
-        // 3. Abort the in-flight controller. Providers that honour the signal
-        //    unwind immediately; providers that don't will still be caught by
-        //    the generation check after their await eventually returns.
-        try { entry.controller?.abort(new SessionClosedError(id, `closeSession (reason=${reason})`, reason)); } catch { /* ignore */ }
-    }
-    // Diagnostic: one-line stderr so operators can distinguish the four close
-    // pathways (request-abort / manual / idle-sweep / runner-crash). iterCount
-    // is not currently tracked on runtime state; askStartedAt is — derive
-    // duration from it when present.
-    try {
-        const askStartedAt = entry?.askStartedAt;
-        const durationMs = (typeof askStartedAt === 'number') ? (Date.now() - askStartedAt) : null;
-        const parts = [`session=${id}`, `reason=${reason}`, `tombstone=${tombstone}`];
-        if (durationMs != null) parts.push(`duration=${durationMs}ms`);
-        if (process.env.MIXDOG_DEBUG_SESSION_LOG) process.stderr.write(`[agent-close] ${parts.join(' ')}\n`);
-    } catch { /* best-effort */ }
-    for (const bsid of allBashIds) {
-        try { _closeBashSessionLazy(bsid, `agent-close:${id}`); } catch { /* ignore */ }
-    }
-    // Drop session-scoped read dedup cache so the Map doesn't accumulate
-    // entries across mcp-server lifetime.
-    try { clearReadDedupSession(id); } catch { /* ignore */ }
-    // Drop offload sidecars + module-level counter for this session so a
-    // long-running mcp-server doesn't leak disk (tool-results/<id>/*.txt)
-    // or Map entries across session lifetime. Fire-and-forget — close path
-    // should not await disk IO; errors are swallowed inside.
-    try { clearOffloadSession(id); } catch { /* ignore */ }
-    // Drop the in-memory pending-message queue and any buffered-persist entry
-    // for this session — otherwise both Maps accumulate one entry per closed
-    // session for the life of the mcp-server.
-    _dropPendingMessageState(id, { clearPersisted: tombstone });
-    // 4. Defer runtime map clear to next tick so any settling askSession can
-    //    observe `closed=true` / bumped generation before we yank the entry.
-    //    Disk tombstone remains — that's what blocks resurrection.
-    setImmediate(() => {
-        _clearSessionRuntime(id);
-    });
-    return true;
-}
-export function abortSessionTurn(id, reason = 'turn-abort') {
-    if (!id) return false;
-    _stopToolActivityHeartbeat(id);
-    const entry = _getRuntimeEntry(id);
-    if (!entry || entry.closed) return false;
-    entry.stage = 'cancelling';
-    entry.closedReason = reason;
-    entry.updatedAt = Date.now();
-    try {
-        entry.controller?.abort(new SessionClosedError(id, `abortSessionTurn (reason=${reason})`, reason));
-    } catch { /* ignore */ }
-    return true;
-}
-
-// --- Periodic idle session cleanup ---
-const CLEANUP_INTERVAL_MS = nonNegativeIntEnv('MIXDOG_SESSION_CLEANUP_INTERVAL_MS', 5 * 60 * 1000); // check every 5 minutes
-const CLEANUP_INITIAL_DELAY_MS = nonNegativeIntEnv('MIXDOG_SESSION_CLEANUP_INITIAL_DELAY_MS', CLEANUP_INTERVAL_MS > 0 ? CLEANUP_INTERVAL_MS : 0);
-const CLEANUP_SLOW_LOG_MS = nonNegativeIntEnv('MIXDOG_SESSION_CLEANUP_SLOW_LOG_MS', 250);
-const TOMBSTONE_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h — far longer than any realistic ask race window
-let _cleanupTimer = null;
-let _cleanupInitialTimer = null;
-
-function nonNegativeIntEnv(name, fallback) {
-    const value = Number(process.env[name]);
-    return Number.isFinite(value) && value >= 0 ? Math.floor(value) : fallback;
-}
-
-function _previewIds(items, limit = 5) {
-    const ids = (items || []).slice(0, limit).map((item) => item.id).filter(Boolean);
-    if (ids.length === 0) return '';
-    const more = items.length > limit ? `, +${items.length - limit} more` : '';
-    return ` (${ids.join(', ')}${more})`;
-}
-
-function sweepIdleSessions({ includeTombstones = true } = {}) {
-    const startedAt = Date.now();
-    try {
-        const result = sweepStaleSessions({
-            tombstoneMaxAgeMs: includeTombstones ? TOMBSTONE_MAX_AGE_MS : 0,
-        });
-        const {
-            cleaned,
-            remaining,
-            details,
-            tombstonesCleaned = 0,
-            tombstoneDetails = [],
-            tombstoneErrors = [],
-        } = result;
-        if (cleaned > 0) {
-            for (const d of details) {
-                // Skip entries with an active in-flight controller — aborting
-                // them via closeSession() is the safe path; clearing the runtime
-                // without signalling the controller leaves orphan provider work.
-                const rtEntry = _getRuntimeEntry(d.id);
-                if (rtEntry && rtEntry.controller && !rtEntry.controller.signal?.aborted) {
-                    try { closeSession(d.id, 'idle-sweep'); } catch { /* ignore */ }
-                } else {
-                    _clearSessionRuntime(d.id);
-                    if (d.bashSessionId) {
-                        try { _closeBashSessionLazy(d.bashSessionId, `idle-sweep:${d.id}`); } catch { /* ignore */ }
-                    }
-                }
-                process.stderr.write(`[agent-session] idle cleanup: closed ${d.id} (idle ${d.idleMinutes}m, owner=${d.owner})\n`);
-            }
-            process.stderr.write(`[agent-session] idle sweep: cleaned ${cleaned} session(s), ${remaining} remaining\n`);
-        }
-        if (tombstonesCleaned > 0) {
-            for (const d of tombstoneDetails) {
-                if (d?.id) _clearSessionRuntime(d.id);
-            }
-            process.stderr.write(`[session-sweep] unlinked ${tombstonesCleaned} tombstone(s)${_previewIds(tombstoneDetails)}\n`);
-        }
-        if (tombstoneErrors.length > 0) {
-            const first = tombstoneErrors[0];
-            process.stderr.write(`[session-sweep] tombstone unlink failed for ${tombstoneErrors.length} session(s): ${first?.id || 'unknown'} ${first?.message || ''}\n`);
-        }
-        const elapsed = Date.now() - startedAt;
-        if (elapsed >= CLEANUP_SLOW_LOG_MS) {
-            process.stderr.write(`[session-sweep] cleanup took ${elapsed}ms (idle=${cleaned}, tombstones=${tombstonesCleaned}, remaining=${remaining})\n`);
-        }
-    } catch (e) {
-        process.stderr.write(`[agent-session] idle sweep error: ${e && e.message || e}\n`);
-    }
-}
-
-/**
- * Unlink tombstone session files (closed=true) older than TOMBSTONE_MAX_AGE_MS.
- *
- * Rationale: closeSession() leaves the tombstone on disk as the authoritative
- * resurrection-blocker for racing saveSession() calls. That race resolves in
- * microseconds (the window inside _doSave between temp write and rename), so
- * 24h is vastly safe. After the TTL expires we reclaim the disk slot.
- *
- * Uses `getStoredSessionsRaw()` rather than `listStoredSessions()` because the
- * latter's inline 30-min idle cleanup would race-unlink tombstones before we
- * get to log them — we want to own the unlink decision and stderr line here.
- */
-export function sweepTombstones() {
-    try {
-        const { tombstonesCleaned = 0, tombstoneDetails = [], tombstoneErrors = [] } = sweepStaleSessions({
-            sweepIdle: false,
-            tombstoneMaxAgeMs: TOMBSTONE_MAX_AGE_MS,
-        });
-        for (const d of tombstoneDetails) {
-            if (d?.id) _clearSessionRuntime(d.id);
-        }
-        if (tombstonesCleaned > 0) {
-            process.stderr.write(`[session-sweep] unlinked ${tombstonesCleaned} tombstone(s)${_previewIds(tombstoneDetails)}\n`);
-        }
-        if (tombstoneErrors.length > 0) {
-            const first = tombstoneErrors[0];
-            process.stderr.write(`[session-sweep] tombstone unlink failed for ${tombstoneErrors.length} session(s): ${first?.id || 'unknown'} ${first?.message || ''}\n`);
-        }
-        return tombstonesCleaned;
-    } catch (e) {
-        process.stderr.write(`[session-sweep] tombstone sweep error: ${e && e.message || e}\n`);
-        return 0;
-    }
-}
-
-function hasActiveRuntimeWork() {
-    for (const [, entry] of _runtimeEntries()) {
-        if (!entry || entry.closed === true) continue;
-        if (entry.controller && !entry.controller.signal?.aborted) return true;
-        if (['connecting', 'requesting', 'streaming', 'tool_running', 'cancelling'].includes(entry.stage)) return true;
-    }
-    return false;
-}
-
-function _runCleanupCycle() {
-    if (hasActiveRuntimeWork()) return;
-    sweepOrphanedPendingMessages();
-    sweepIdleSessions({ includeTombstones: true });
-}
-
-function _startCleanupInterval() {
-    if (_cleanupTimer) return;
-    if (CLEANUP_INTERVAL_MS <= 0) return;
-    _cleanupTimer = setInterval(_runCleanupCycle, CLEANUP_INTERVAL_MS);
-    if (_cleanupTimer.unref) _cleanupTimer.unref(); // don't block process exit
-}
-
-export function startIdleCleanup() {
-    if (_cleanupTimer || _cleanupInitialTimer) return;
-    if (CLEANUP_INITIAL_DELAY_MS <= 0) {
-        _runCleanupCycle();
-        _startCleanupInterval();
-        return;
-    }
-    _cleanupInitialTimer = setTimeout(() => {
-        _cleanupInitialTimer = null;
-        _runCleanupCycle();
-        _startCleanupInterval();
-    }, CLEANUP_INITIAL_DELAY_MS);
-    if (_cleanupInitialTimer.unref) _cleanupInitialTimer.unref();
-}
-
-export function stopIdleCleanup() {
-    if (_cleanupInitialTimer) {
-        clearTimeout(_cleanupInitialTimer);
-        _cleanupInitialTimer = null;
-    }
-    if (_cleanupTimer) {
-        clearInterval(_cleanupTimer);
-        _cleanupTimer = null;
-    }
-}
+// ── Session lifecycle / ask / crud / close / cleanup ──────────────────────
+export { SessionClosedError } from './manager/session-errors.mjs';
+export { setAgentRuntime } from './manager/agent-runtime-singleton.mjs';
+export { createSession, updateSessionRoute, resumeSession } from './manager/session-lifecycle.mjs';
+export { askSession, _api_call_with_interrupt } from './manager/ask-session.mjs';
+export {
+    _sessionMessagesAdvancedBeyondCompactedOutgoing,
+    _applyCompactFailurePersistToSession,
+} from './manager/message-sanitize.mjs';
+export {
+    getSession,
+    listSessions,
+    findSessionByScopeKey,
+    clearSessionMessages,
+    compactSessionMessages,
+    updateSessionStatus,
+    flushSessionMetrics,
+} from './manager/session-crud.mjs';
+export { closeSession, abortSessionTurn } from './manager/session-close.mjs';
+export { sweepTombstones, startIdleCleanup, stopIdleCleanup } from './manager/idle-cleanup.mjs';