mixdog 0.7.18 → 0.8.0

package/src/runtime/agent/orchestrator/session/tool-result-offload.mjs

@@ -0,0 +1,166 @@
+import { existsSync, mkdirSync } from 'fs';
+import { readdir, rmdir, unlink, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { getPluginData } from '../config.mjs';
+import { normalizeOutputPath } from '../tools/builtin/path-utils.mjs';
+import { classifyResultKind } from './result-classification.mjs';
+
+const TOOL_RESULT_OFFLOAD_THRESHOLD_CHARS = 50_000;
+const TOOL_RESULT_PREVIEW_CHARS = 2_000;
+const TOOL_RESULT_SHELL_THRESHOLD_CHARS = 30_000;
+const TOOL_RESULT_SEARCH_THRESHOLD_CHARS = 50_000;
+const TOOL_RESULT_GREP_THRESHOLD_CHARS = 20_000;
+export const TOOL_RESULT_OFFLOAD_PREFIX = '[tool output offloaded:';
+
+// Per-tool persistence limits mirror Claude Code's per-tool maxResultSizeChars
+// rather than a single global value: Grep persists at 20k (CC GrepTool), Glob
+// and list/find_* at the 50k system default (CC DEFAULT_MAX_RESULT_SIZE_CHARS;
+// tighter than CC Glob's 100k by design), and shell/bash_session/task at 30k
+// (CC BASH_MAX_OUTPUT_LENGTH default). Read/head/tail/diff stay inline
+// (Infinity) — they are self-bound by FileRead semantics and the upstream
+// READ_MAX_SIZE_BYTES cap, so persisting to a sidecar to be re-read would be
+// circular. These values keep context-rich IO tools from turning into "read
+// saved output" loops while bounding the per-call inline footprint per CC.
+const INLINE_THRESHOLD_BY_TOOL = new Map([
+    ['read', Infinity],
+    ['head', Infinity],
+    ['tail', Infinity],
+    ['diff', Infinity],
+    ['grep', TOOL_RESULT_GREP_THRESHOLD_CHARS],
+    ['glob', TOOL_RESULT_SEARCH_THRESHOLD_CHARS],
+    ['list', TOOL_RESULT_SEARCH_THRESHOLD_CHARS],
+    ['tree', TOOL_RESULT_SEARCH_THRESHOLD_CHARS],
+    ['find_files', TOOL_RESULT_SEARCH_THRESHOLD_CHARS],
+    ['code_graph', TOOL_RESULT_SEARCH_THRESHOLD_CHARS],
+    ['shell', TOOL_RESULT_SHELL_THRESHOLD_CHARS],
+    ['bash_session', TOOL_RESULT_SHELL_THRESHOLD_CHARS],
+    ['task', TOOL_RESULT_SHELL_THRESHOLD_CHARS],
+]);
+
+function getOffloadThreshold(toolName) {
+    const key = String(toolName || '').toLowerCase();
+    return INLINE_THRESHOLD_BY_TOOL.get(key) ?? TOOL_RESULT_OFFLOAD_THRESHOLD_CHARS;
+}
+
+// Sanitize sessionId before using it as a path segment. A raw `..` or slash
+// would let the sidecar dir — and clearOffloadSession's readdir+unlink — escape
+// the tool-results root (arbitrary .txt deletion). Strip to [A-Za-z0-9_-];
+// dropping '.' collapses '..' to '__'. Real ids are sess_<digits>, unaffected.
+function safeSessionSegment(sessionId) {
+    return String(sessionId ?? '').replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 200) || '_invalid';
+}
+
+function ensureToolResultsDir(sessionId) {
+    const dir = join(getPluginData(), 'tool-results', safeSessionSegment(sessionId));
+    // R4 data-at-rest: offloaded tool output may contain secrets / file
+    // contents; clamp dir to owner-only on POSIX (advisory on Windows).
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
+
+// Map tool-call IDs to safe generated filenames. toolCallId arrives from
+// the provider and may contain path-unsafe characters (slashes, dots, etc.).
+// Use a monotonic counter keyed by sessionId so the sidecar path is
+// deterministic-ish within a session but never tainted by provider input.
+const _offloadCounters = new Map();
+
+function buildPreview(text, maxChars = TOOL_RESULT_PREVIEW_CHARS) {
+    if (text.length <= maxChars) {
+        return { preview: text, truncated: false };
+    }
+    const headBudget = Math.floor(maxChars * 0.6);
+    const tailBudget = maxChars - headBudget;
+    let head = text.slice(0, headBudget);
+    const headCut = head.lastIndexOf('\n');
+    if (headCut > Math.floor(headBudget * 0.6)) head = head.slice(0, headCut);
+    let tail = text.slice(Math.max(0, text.length - tailBudget));
+    const tailCut = tail.indexOf('\n');
+    if (tailCut !== -1 && tailCut < Math.floor(tailBudget * 0.4)) tail = tail.slice(tailCut + 1);
+    const omittedKb = Math.max(1, Math.round((text.length - head.length - tail.length) / 1024));
+    return {
+        preview: `${head}\n\n... [preview middle omitted — ${omittedKb} KB] ...\n\n${tail}`,
+        truncated: true,
+    };
+}
+
+function countLines(text) {
+    if (!text) return 0;
+    let lines = 1;
+    for (let i = 0; i < text.length; i += 1) {
+        if (text.charCodeAt(i) === 10) lines += 1;
+    }
+    return lines;
+}
+
+export async function maybeOffloadToolResult(sessionId, toolCallId, toolName, result) {
+    if (!sessionId || !toolCallId) return result;
+    if (typeof result !== 'string') return result;
+    if (result.length <= getOffloadThreshold(toolName)) return result;
+    // Keep error surfaces inline so the model can self-correct without an
+    // extra read turn — but only up to the global default. A giant error
+    // (e.g. a megabyte of stack/diff/dump) still offloads so it can't blow up
+    // context; small errors (the overwhelming majority) stay inline.
+    if (classifyResultKind(result) === 'error'
+        && result.length <= TOOL_RESULT_OFFLOAD_THRESHOLD_CHARS) return result;
+
+    // Generate a safe filename — never trust toolCallId as a path component.
+    const count = (_offloadCounters.get(sessionId) ?? 0) + 1;
+    _offloadCounters.set(sessionId, count);
+    const safeId = `r${count}`;
+
+    const dir = ensureToolResultsDir(sessionId);
+    const filePath = join(dir, `${safeId}.txt`);
+
+    // Count lines while the string is in hand — single pass, no re-read.
+    const lines = countLines(result);
+    await writeFile(filePath, result, { encoding: 'utf-8', mode: 0o600 });
+
+    const { preview, truncated } = buildPreview(result);
+    const sizeKb = Math.max(1, Math.round(result.length / 1024));
+    const displayPath = normalizeOutputPath(filePath);
+    const header = `${TOOL_RESULT_OFFLOAD_PREFIX} ${toolName} → ${displayPath} (${sizeKb} KB, ${lines} lines)]`;
+    const suffix = truncated ? '\n... [preview truncated — use read on the saved path for full output]' : '';
+    return `${header}\n\n${preview}${suffix}`;
+}
+
+// Drop a session's offload sidecars on session close. Unlinks every
+// tool-results/<sessionId>/*.txt entry, rmdirs the directory, and drops
+// the sessionId entry from the module-level counter Map so a long-running
+// mcp-server process doesn't accumulate per-session state across the
+// lifetime of the bridge.
+export async function clearOffloadSession(sessionId) {
+    if (!sessionId) return;
+    _offloadCounters.delete(sessionId);
+    const dir = join(getPluginData(), 'tool-results', safeSessionSegment(sessionId));
+    if (!existsSync(dir)) return;
+    try {
+        const entries = await readdir(dir);
+        await Promise.all(entries
+            .filter((name) => name.endsWith('.txt'))
+            .map((name) => unlink(join(dir, name)).catch(() => { /* best-effort */ })));
+        await rmdir(dir).catch(() => { /* best-effort: non-empty / already gone */ });
+    } catch { /* best-effort */ }
+}
+
+export function isOffloadedToolResultText(text) {
+    return typeof text === 'string' && text.startsWith(TOOL_RESULT_OFFLOAD_PREFIX);
+}
+
+export function compactOffloadedToolResultText(text) {
+    if (!isOffloadedToolResultText(text)) return text;
+    const value = String(text);
+    const lineEnd = value.indexOf('\n');
+    const firstLine = lineEnd === -1 ? value : value.slice(0, lineEnd);
+    return `${firstLine}\n[preview omitted — use read on the saved path if needed]`;
+}
+
+export const _internals = {
+    TOOL_RESULT_OFFLOAD_THRESHOLD_CHARS,
+    TOOL_RESULT_SHELL_THRESHOLD_CHARS,
+    TOOL_RESULT_SEARCH_THRESHOLD_CHARS,
+    TOOL_RESULT_GREP_THRESHOLD_CHARS,
+    getOffloadThreshold,
+    TOOL_RESULT_PREVIEW_CHARS,
+    buildPreview,
+    countLines,
+};

package/src/runtime/agent/orchestrator/smart-bridge/bridge-llm.mjs

@@ -0,0 +1,339 @@
+/**
+ * Smart Bridge — Internal LLM Helper (session-based).
+ *
+ * Every one-shot LLM dispatch from internal callers (memory-cycle,
+ * scheduler, webhook) now flows through the SAME session pipeline as the
+ * MCP `bridge` tool. No more parallel `provider.send()` helper — one code
+ * path = one message shape = one usage log = "bridge single path".
+ *
+ * The returned function uses the existing caller signature, so call sites
+ * do not need changes:
+ *
+ *   const llm = makeBridgeLlm({ role: 'maintenance', preset: 'haiku' });
+ *   const text = await llm({ prompt });
+ *
+ * Internally it:
+ *   1. Resolves the preset (explicit arg > opts.preset > user-workflow.json[role])
+ *   2. Creates or reuses a session via the session manager
+ *   3. Applies stateless-reset for stateless profiles so the prefix handle
+ *      stays warm while per-dispatch transcripts never leak
+ *   4. Calls `askSession` → provider.send() → usage logged via
+ *      `session/manager.mjs` (mode='active')
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { loadConfig } from '../config.mjs';
+import { resolveRuntimeSpec } from '../config.mjs';
+import { getHiddenRole, resolveBridgeSessionPermission } from '../internal-roles.mjs';
+import { prepareBridgeSession } from './session-builder.mjs';
+import { resolvePluginData } from '../../../shared/plugin-paths.mjs';
+import {
+    askSession,
+    updateSessionStatus,
+    closeSession,
+} from '../session/manager.mjs';
+
+// Cap bridge role synthesis to ~3000 tokens (~12 KB at the 4 B/tok
+// working average). Pool B explore/recall/search answers occasionally land
+// 8-10k-token walls that then ride in the Lead context for the rest of the
+// turn; the cap keeps those outliers bounded without touching the 95%+ of
+// answers already under the threshold.
+const BRIEF_CAP_BYTES = 12 * 1024;
+function envTimeoutMs(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '') return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+const DEFAULT_FIRST_RESPONSE_TIMEOUT_MS = envTimeoutMs('MIXDOG_BRIDGE_FIRST_RESPONSE_TIMEOUT_MS', 120_000);
+const DEFAULT_STALE_TIMEOUT_MS = envTimeoutMs('MIXDOG_BRIDGE_STALE_TIMEOUT_MS', 30 * 60_000);
+function applyBriefCap(text) {
+    if (typeof text !== 'string') return text;
+    if (text.length <= BRIEF_CAP_BYTES) return text;
+    const head = text.slice(0, BRIEF_CAP_BYTES);
+    const approxTokens = Math.round(text.length / 4);
+    return `${head}\n\n... [TRUNCATED — full answer was ~${approxTokens} tokens / ${Math.round(text.length / 1024)} KB. Re-run with brief:false for the complete synthesis]`;
+}
+
+// Unified-shard policy — most bridge sessions (Pool B + Pool C) share the
+// same tool schema so BP_1 is bit-identical across roles and one provider-side
+// cache shard serves every caller. Per-role behaviour is steered by:
+//   1. rules/bridge/*.md concatenated into BP2 roleCatalog (via
+//      loadScopedRoleCatalog — every bridge session carries the full
+//      hidden-role catalog so the shard stays bit-identical across roles)
+//   2. call-time guards (loop.mjs write-block + ai-wrapped-dispatch
+//      recursion break)
+// Hidden-role exceptions are declarative: defaults/hidden-roles.json may set
+// toolSchemaProfile when first-turn routing quality is worth a separate tool
+// prefix. Keep "unified" as the default; new profiles must justify the cache
+// shard split.
+// See manager.mjs resolveSessionTools for the single source of truth;
+// bridge visibility is declared via annotations.bridgeHidden on each tool def.
+const HIDDEN_ROLE_TOOL_SCHEMA_PROFILES = Object.freeze({
+    unified: null,
+    'llm-only': Object.freeze([]),
+    'filesystem-read': Object.freeze([
+        'code_graph',
+        'glob',
+        'list',
+        'grep',
+        'read',
+    ]),
+});
+
+export function resolveHiddenRoleSchemaAllowedTools(hidden) {
+    if (!hidden) return null;
+    if (Array.isArray(hidden.schemaAllowedTools)) {
+        return hidden.schemaAllowedTools.map((name) => String(name || '').trim()).filter(Boolean);
+    }
+    const profile = String(hidden.toolSchemaProfile || 'unified').trim() || 'unified';
+    if (Object.prototype.hasOwnProperty.call(HIDDEN_ROLE_TOOL_SCHEMA_PROFILES, profile)) {
+        return HIDDEN_ROLE_TOOL_SCHEMA_PROFILES[profile];
+    }
+    process.stderr.write(`[bridge-llm] unknown hidden-role toolSchemaProfile="${profile}" role="${hidden.name || 'unknown'}"; using unified schema\n`);
+    return null;
+}
+
+/**
+ * Resolve a preset name from (preset arg | opts.preset | hidden-role | user-workflow).
+ *
+ * Hidden roles (explorer, cycle1/cycle2, scheduler-task, etc.) are
+ * Mixdog-managed and take precedence over user-workflow.json — users cannot
+ * override them by redefining the same name.
+ */
+export function resolvePresetName({ preset, optsPreset, role, config: cfgIn = null }) {
+    if (preset) return preset;
+    if (optsPreset) return optsPreset;
+    if (!role) return null;
+    // Hidden roles resolve their maintenance preset by SLOT. Every slot carries
+    // a concrete default in DEFAULT_MAINTENANCE, so `maint[slot]` resolves
+    // directly; the Setup panel can still tune each slot independently.
+    // (explorer.slot = 'explore', cycle1-agent.slot = 'cycle1', …). A hidden
+    // role may override which maintenance key it reads via `maintKey`
+    // (e.g. the cycle1/2/3 agents all read `maint.memory` instead of their
+    // own slot) so several agents can share one model knob while keeping
+    // distinct slots/identity.
+    const hidden = getHiddenRole(role);
+    if (hidden) {
+        try {
+            const config = cfgIn || loadConfig();
+            const maint = config?.maintenance || {};
+            return maint[hidden.maintKey || hidden.slot] || null;
+        } catch { return null; }
+    }
+    try {
+        const pluginData = resolvePluginData();
+        if (!pluginData) return null;
+        const wf = JSON.parse(readFileSync(join(pluginData, 'user-workflow.json'), 'utf8'));
+        if (!Array.isArray(wf.roles)) return null;
+        const entry = wf.roles.find((r) => r.name === role);
+        return entry ? entry.preset : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Build a bridge-backed LLM callback.
+ *
+ * @param {object} opts
+ * @param {string} opts.role        — REQUIRED; canonical role name (worker, cycle1-agent, scheduler-task, ...)
+ * @param {string} [opts.taskType]  — optional internal classification stamped on the session
+ * @param {string} [opts.preset]    — explicit preset override (bypasses role → preset lookup)
+ * @param {string} [opts.parentSessionId] — parent bridge session for trace aggregation
+ * @param {string|null} [opts.ownerSessionId] — owning Mixdog session for statusline isolation
+ * @param {AbortSignal} [opts.parentSignal] — optional AbortSignal from the fan-out coordinator;
+ *   when aborted the bridge role session's own controller is also aborted so the
+ *   provider call tears down promptly (parent→child cascade).
+ * @returns {(args: { prompt, preset?, sourceName? }) => Promise<string>}
+ */
+export function makeBridgeLlm(opts = {}) {
+    if (!opts.role || typeof opts.role !== 'string') {
+        throw new Error('[bridge-llm] opts.role is required');
+    }
+    const role = opts.role;
+
+    return async function bridgeLlm({ prompt, preset: presetArg, sourceName: sourceNameArg, parentSignal: callParentSignal, idleTimeoutMs: callIdleTimeoutMs }) {
+        if (typeof prompt !== 'string' || !prompt) {
+            throw new Error(`[bridge-llm] prompt required for role "${role}"`);
+        }
+
+        const config = opts.config || loadConfig();
+        const presetName = resolvePresetName({
+            preset: presetArg,
+            optsPreset: opts.preset,
+            role,
+            config,
+        });
+        if (!presetName) {
+            throw new Error(
+                `[bridge-llm] preset unresolved for role "${role}" `
+                + `(preset="${presetArg || opts.preset || ''}")`,
+            );
+        }
+
+        const preset = config.presets?.find((p) => p.id === presetName || p.name === presetName);
+        if (!preset) {
+            throw new Error(`[bridge-llm] preset "${presetName}" not found in mixdog-config.json`);
+        }
+
+        const runtimeSpec = resolveRuntimeSpec(preset, {
+            lane: 'bridge',
+            agentId: role,
+        });
+
+        // Callers (e.g. aiWrapped explore dispatch) may pass an explicit
+        // `cwd` to scope the agent's filesystem view. Absolute path expected
+        // (aiWrapped already expands `~` and resolves relatives). When unset
+        // we pass `null` through instead of falling back to `process.cwd()`
+        // — the MCP server's launch dir is not deterministic across callers,
+        // and the downstream skill-discovery path tolerates null. Combined
+        // with the frozen bridge skill meta-tools (collect.mjs) this keeps
+        // every caller on the same provider cache shard.
+        const cwd = (typeof opts.cwd === 'string' && opts.cwd) ? opts.cwd : null;
+
+        // Unified dispatch: Pool B/C share bit-identical tools + system prompt
+        // unless a hidden role declares a narrow toolSchemaProfile. Per-role
+        // differentiation rides in the user-message header (permission + role
+        // line) plus an optional short Pool C snippet. The read-only contract
+        // is still enforced at call time via loop.mjs's READ_BLOCKED_TOOLS
+        // guard; schema profiles are a routing-efficiency layer, not safety.
+        const hidden = getHiddenRole(role);
+        const isPoolC = Boolean(hidden);
+        // Permission: read-declared hidden roles are locked in
+        // resolveBridgeSessionPermission (prepareBridgeSession applies the same).
+        const permission = resolveBridgeSessionPermission(
+            role,
+            opts.permission ?? (isPoolC ? (hidden?.permission || 'read') : null),
+        );
+        // Pool C hidden-role instructions live in BP2 roleCatalog (loaded
+        // by loadScopedRoleCatalog from rules/bridge/*.md) — the Tier 3
+        // reminder is suppressed so the shard stays bit-identical across
+        // every bridge role.
+        //
+        // User message = pure query. Permission / role ride in BP3
+        // sessionMarker (composeSystemPrompt) — only the query varies per
+        // call, so provider cache reuses the shared prefix.
+        //
+        // Stateless ephemeral session — created fresh per call, never
+        // pooled or resumed. Cache prefix matching happens at the provider
+        // layer (account-level), not the session level.
+        const finalPrompt = prompt;
+        const { session } = prepareBridgeSession({
+            role,
+            presetName,
+            preset,
+            runtimeSpec,
+            permission,
+            cwd,
+            sourceType: opts.sourceType,
+            sourceName: sourceNameArg || opts.sourceName,
+            parentSessionId: opts.parentSessionId || null,
+            ownerSessionId: opts.ownerSessionId === undefined ? (opts.parentSessionId || null) : opts.ownerSessionId,
+            clientHostPid: opts.clientHostPid,
+            skipRoleReminder: isPoolC,
+            schemaAllowedTools: resolveHiddenRoleSchemaAllowedTools(hidden),
+            taskType: opts.taskType,
+            maxLoopIterations: opts.maxLoopIterations,
+        });
+        // Diagnostic — dump the actual tool names exposed to this LLM call,
+        // visible from the worker log instead of being hidden behind a
+        // count-only "tools=N" line.
+        try {
+            const _toolNames = (session.tools || []).map((t) => t?.name).filter(Boolean);
+            process.stderr.write(`[bridge-llm] role=${role} tool-list (${_toolNames.length}): ${_toolNames.join(',')}\n`);
+        } catch { /* best-effort diagnostic */ }
+
+        await updateSessionStatus(session.id, 'running');
+        // Parent→child abort cascade: when opts.parentSignal (factory) or
+        // callParentSignal (per-call) fires, abort the sub-session's own
+        // controller so the provider call tears down promptly. Best-effort:
+        // if the session/manager import is unavailable we fall back silently.
+        const _managerMod = await import('../session/manager.mjs').catch(() => null);
+        const _linkSignal = _managerMod?.linkParentSignalToSession;
+        const _getProgressSnapshot = _managerMod?.getSessionProgressSnapshot;
+        const _getLastProgressAt = _managerMod?.getSessionLastProgressAt;
+        if (_linkSignal) {
+            if (opts.parentSignal instanceof AbortSignal) {
+                try { _linkSignal(session.id, opts.parentSignal); } catch { /* ignore */ }
+            }
+            if (callParentSignal instanceof AbortSignal) {
+                try { _linkSignal(session.id, callParentSignal); } catch { /* ignore */ }
+            }
+        }
+        // Watchdog policy is split:
+        // - firstResponseTimeoutMs cuts quickly only when the model produces no
+        //   first stream/tool activity at all.
+        // - idleTimeoutMs is a stale watchdog after work has started.
+        //   0 disables that stale abort; default is 30 minutes.
+        const _staleMs = Number.isFinite(callIdleTimeoutMs)
+            ? callIdleTimeoutMs
+            : (Number.isFinite(opts.idleTimeoutMs) ? opts.idleTimeoutMs : DEFAULT_STALE_TIMEOUT_MS);
+        const _firstMs = Number.isFinite(opts.firstResponseTimeoutMs)
+            ? opts.firstResponseTimeoutMs
+            : DEFAULT_FIRST_RESPONSE_TIMEOUT_MS;
+        const _idleController = ((_staleMs > 0 || _firstMs > 0) && _linkSignal) ? new AbortController() : null;
+        if (_idleController) {
+            try { _linkSignal(session.id, _idleController.signal); } catch { /* ignore */ }
+        }
+        const _idleTimer = (_idleController && (typeof _getProgressSnapshot === 'function' || typeof _getLastProgressAt === 'function'))
+            ? setInterval(() => {
+                const now = Date.now();
+                const snapshot = typeof _getProgressSnapshot === 'function' ? _getProgressSnapshot(session.id) : null;
+                if (snapshot) {
+                    if (snapshot.waitingForFirstActivity) {
+                        const startedAt = snapshot.modelRequestStartedAt || snapshot.askStartedAt;
+                        if (_firstMs > 0 && startedAt && now - startedAt > _firstMs) {
+                            try { _idleController.abort(new Error(`first response stale (${_firstMs}ms)`)); } catch { /* ignore */ }
+                        }
+                        return;
+                    }
+                    const last = snapshot.lastProgressAt || snapshot.firstActivityAt;
+                    if (_staleMs > 0 && last && now - last > _staleMs) {
+                        try { _idleController.abort(new Error(`bridge task stale (${_staleMs}ms without stream/tool progress)`)); } catch { /* ignore */ }
+                    }
+                    return;
+                }
+                const last = _getLastProgressAt?.(session.id);
+                if (_staleMs > 0 && last && now - last > _staleMs) {
+                    try { _idleController.abort(new Error(`bridge task stale (${_staleMs}ms without progress)`)); } catch { /* ignore */ }
+                }
+            }, 1000)
+            : null;
+        if (_idleTimer && typeof _idleTimer.unref === 'function') _idleTimer.unref();
+        let terminalStatus = 'idle';
+        process.stderr.write(`[bridge-llm] role=${role} preset=${presetName} model=${preset.model} provider=${preset.provider} session=${session.id}\n`);
+        const _bridgeT0 = Date.now();
+        try {
+            const result = await askSession(session.id, finalPrompt, null, null, cwd);
+            process.stderr.write(`[bridge-llm] role=${role} session=${session.id} elapsed=${Date.now() - _bridgeT0}ms\n`);
+            const raw = result?.content || '';
+            // Brief cap. Bridge role answers (explore/recall/search)
+            // occasionally balloon to 8-10k token walls that then ride in the
+            // parent Lead's context for the rest of the turn. A 3000-token
+            // (~12 KB) ceiling trims the long tail while leaving the vast
+            // majority of answers untouched. Opt-out via `brief:false` when
+            // the caller explicitly wants the full synthesis.
+            if (opts.brief === false) {
+                try { closeSession(session.id, 'ephemeral-done'); } catch { /* ignore */ }
+                return raw;
+            }
+            const out = applyBriefCap(raw);
+            try { closeSession(session.id, 'ephemeral-done'); } catch { /* ignore */ }
+            return out;
+        } catch (err) {
+            terminalStatus = 'error';
+            try { closeSession(session.id, 'ephemeral-error'); } catch { /* ignore */ }
+            throw err;
+        } finally {
+            if (_idleTimer) {
+                try { clearInterval(_idleTimer); } catch { /* ignore */ }
+            }
+            // Always flip out of 'running' before returning so the sweep never
+            // leaves a stateless Pool C session stuck in 'running' when the
+            // try/catch falls through in unexpected ways.
+            try { await updateSessionStatus(session.id, terminalStatus); } catch { /* ignore */ }
+        }
+    };
+}