mixdog 0.7.1

package/src/agent/index.mjs

@@ -0,0 +1,2138 @@
+import { initProviders, refreshProviderCatalogsOnStartup, refreshCatalogs } from './orchestrator/providers/registry.mjs';
+import { runWithCwdOverride, pwd } from '../shared/user-cwd.mjs';
+import { askSession, listSessions, closeSession, updateSessionStatus, updateSessionStage, getSessionRuntime, SessionClosedError, setSmartBridge, forEachSessionRuntime, hideSessionFromList, getSession, enqueuePendingMessage } from './orchestrator/session/manager.mjs';
+import { publishHeartbeat as publishSessionHeartbeat } from './orchestrator/session/store.mjs';
+import { StreamStalledAbortError, startWatchdog as startStreamWatchdog } from './orchestrator/session/stream-watchdog.mjs';
+import { startBridgeStallWatchdog } from './bridge-stall-watchdog.mjs';
+import { loadConfig, getPluginData, listPresets, getDefaultPreset, resolveRuntimeSpec } from './orchestrator/config.mjs';
+import { connectMcpServers, disconnectAll } from './orchestrator/mcp/client.mjs';
+import { setInternalToolsProvider, awaitBootReady } from './orchestrator/internal-tools.mjs';
+import { listWorkflows, getWorkflow, seedDefaults } from './orchestrator/workflow-store.mjs';
+import { prepareBridgeSession } from './orchestrator/smart-bridge/session-builder.mjs';
+import { normalizeInputPath } from './orchestrator/tools/builtin.mjs';
+import { prewarmCodeGraph, prewarmCodeGraphSymbols } from './orchestrator/tools/code-graph.mjs';
+import { runWithDispatchRetry } from './orchestrator/bridge-retry.mjs';
+import { ensureDataSeeds } from '../shared/seed.mjs';
+import { errText } from '../shared/err-text.mjs';
+import { isCurrentDaemonDoomed } from '../shared/daemon-recycle.mjs';
+import { writeFileSync, readFileSync, existsSync, watch, watchFile, unwatchFile } from 'fs';
+import { readFile } from 'fs/promises';
+import { execFileSync } from 'child_process';
+import { addPending, removePending, setPendingResult } from './orchestrator/dispatch-persist.mjs';
+import { join, resolve, isAbsolute } from 'path';
+
+// --- user-workflow.json loader ---
+// The plugin already persists user role -> preset mapping in
+//   <plugin-data>/user-workflow.json
+// Smart Bridge consumes this directly instead of introducing a duplicate
+// config key. fs.watch keeps Smart Bridge in sync when the user edits roles.
+
+/**
+ * @typedef {Object} RoleConfig
+ * @property {string}      name        - unique role identifier
+ * @property {string}      preset      - preset name from agent-config presets
+ * @property {'read'|'read-write'|'mcp'|'full'} permission - tool permission category
+ * @property {string|null} desc_path   - relative to CLAUDE_PLUGIN_ROOT
+ */
+
+const VALID_PERMISSIONS = new Set(['read', 'read-write', 'mcp', 'full']);
+const SILENT_BRIDGE_CANCEL_REASONS = new Set([
+  'manual',
+  'request-abort',
+  'request-aborted',
+  'retry-replaced',
+  'idle-sweep',
+]);
+
+function shouldEmitBridgeCancellation(reason) {
+  if (!reason) return true;
+  return !SILENT_BRIDGE_CANCEL_REASONS.has(String(reason));
+}
+
+// Sanitize cwd before passing it to a child-process spawn. On Windows,
+// node:child_process spawn() with a non-ASCII cwd often fails with ENOENT
+// because of code-page / UTF-8 mismatches in the inherited environment
+// (worker invocations with non-ASCII OneDrive paths such as a localized
+// Desktop directory saw zero tool activity
+// before this guard). Falls back to process.cwd() when the cwd contains
+// non-ASCII; the caller (case 'bridge') is expected to surface the
+// originally-requested path inside the prompt body so absolute paths in
+// tool calls still hit the right tree.
+function _safeCwdForSpawn(rawCwd) {
+  if (!rawCwd) return rawCwd;
+  if (process.platform === 'win32' && /[^\x20-\x7e]/.test(String(rawCwd))) {
+    try { return process.cwd(); } catch { return rawCwd; }
+  }
+  return rawCwd;
+}
+
+function applyRoleDefaults(raw) {
+  const permission = raw.permission ?? 'full';
+  const desc_path = typeof raw.desc_path === 'string' ? raw.desc_path : null;
+
+  return {
+    name: raw.name,
+    preset: raw.preset,
+    permission,
+    desc_path,
+  };
+}
+
+function validateRoleConfig(role) {
+  if (!role.name || typeof role.name !== 'string')
+    throw new Error(`[user-workflow] role entry missing "name"`);
+  if (!role.preset || typeof role.preset !== 'string')
+    throw new Error(`[user-workflow] role "${role.name}" missing "preset"`);
+  if (!VALID_PERMISSIONS.has(role.permission))
+    throw new Error(`[user-workflow] role "${role.name}": invalid permission "${role.permission}" (expected: ${[...VALID_PERMISSIONS].join(", ")})`);
+}
+
+/** @type {Map<string, RoleConfig>} */
+let _roleConfigCache = new Map();
+
+function loadResolvedRoles() {
+  const path = join(getPluginData(), 'user-workflow.json');
+  const map = new Map();
+  if (!existsSync(path)) return map;
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    if (Array.isArray(data?.roles)) {
+      for (const raw of data.roles) {
+        if (!raw?.name || !raw?.preset) continue;
+        const resolved = applyRoleDefaults(raw);
+        validateRoleConfig(resolved);
+        map.set(resolved.name, resolved);
+      }
+    }
+  } catch (e) {
+    process.stderr.write(`[user-workflow] load error: ${e.message}\n`);
+  }
+  return map;
+}
+
+function loadUserWorkflowRoles() {
+  _roleConfigCache = loadResolvedRoles();
+  const out = {};
+  for (const [name, cfg] of _roleConfigCache) out[name] = cfg.preset;
+  return out;
+}
+
+/**
+ * Get the fully-resolved RoleConfig for a given role name.
+ * @param {string} roleName
+ * @returns {RoleConfig|null}
+ */
+export function getRoleConfig(roleName) {
+  return _roleConfigCache.get(roleName) ?? null;
+}
+
+let _userWorkflowWatcher = null;
+function watchUserWorkflow(onChange) {
+  if (_userWorkflowWatcher) return;
+  const dir = getPluginData();
+  if (process.platform === 'linux') {
+    // linux/WSL: fs.watch on a directory is unreliable/unsupported.
+    // Use fs.watchFile polling on the specific file instead.
+    try {
+      const fp = join(dir, 'user-workflow.json');
+      watchFile(fp, { persistent: false, interval: 2000 }, () => {
+        try { onChange(loadUserWorkflowRoles()); } catch {}
+      });
+      _userWorkflowWatcher = { close: () => unwatchFile(fp) };
+    } catch (e) {
+      process.stderr.write(`[user-workflow-watch] watchFile failed on ${dir}: ${e?.message}\n`);
+    }
+  } else {
+    // win32: reliable; darwin: flat watch on single dir is fine.
+    try {
+      _userWorkflowWatcher = watch(dir, { persistent: false }, (_event, filename) => {
+        if (filename === 'user-workflow.json') {
+          try { onChange(loadUserWorkflowRoles()); } catch {}
+        }
+      });
+    } catch (e) {
+      // fs.watch can fail on some platforms — log and continue; watcher is non-critical.
+      process.stderr.write(`[user-workflow-watch] fs.watch failed on ${dir}: ${e?.message}\n`);
+    }
+  }
+}
+
+let _agentConfigWatcher = null;
+let _agentConfigReloadTimer = null;
+let _agentConfigReloadRunning = false;
+let _agentConfigReloadQueued = false;
+let _lastExternalServersKey = '';
+
+function stableJson(value) {
+  if (!value || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  const entries = Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`);
+  return `{${entries.join(',')}}`;
+}
+
+function externalMcpServersFromConfig(config) {
+  const rawServers = (config?.mcpServers && typeof config.mcpServers === 'object') ? config.mcpServers : {};
+  const externalServers = {};
+  for (const [name, cfg] of Object.entries(rawServers)) {
+    if (name === 'mixdog' || name === 'trib-plugin') continue;
+    externalServers[name] = cfg;
+  }
+  return externalServers;
+}
+
+function scheduleAgentConfigReload(reason = 'change') {
+  clearTimeout(_agentConfigReloadTimer);
+  _agentConfigReloadTimer = setTimeout(() => {
+    reloadAgentConfig(reason).catch((err) => {
+      process.stderr.write(`[agent-config-watch] reload failed: ${err?.message || String(err)}\n`);
+    });
+  }, 250);
+  _agentConfigReloadTimer.unref?.();
+}
+
+async function reloadAgentConfig(reason = 'change') {
+  if (_agentConfigReloadRunning) {
+    _agentConfigReloadQueued = true;
+    return;
+  }
+  _agentConfigReloadRunning = true;
+  try {
+    const config = loadConfig();
+    await initProviders(config.providers);
+
+    try {
+      const { getSmartBridge } = await import('./orchestrator/smart-bridge/index.mjs');
+      getSmartBridge().updatePresets(config.presets || []);
+    } catch {}
+
+    const externalServers = externalMcpServersFromConfig(config);
+    const externalKey = stableJson(externalServers);
+    if (_lastExternalServersKey !== externalKey) {
+      try {
+        await disconnectAll();
+        if (Object.keys(externalServers).length > 0) await connectMcpServers(externalServers);
+        process.stderr.write(`[agent-config-watch] external MCP servers refreshed (${Object.keys(externalServers).length})\n`);
+      } catch (err) {
+        process.stderr.write(`[agent-config-watch] external MCP refresh failed: ${err?.message || String(err)}\n`);
+      } finally {
+        _lastExternalServersKey = externalKey;
+      }
+    }
+
+    refreshCatalogs();
+    process.stderr.write(`[agent-config-watch] runtime refreshed (${reason})\n`);
+  } finally {
+    _agentConfigReloadRunning = false;
+    if (_agentConfigReloadQueued) {
+      _agentConfigReloadQueued = false;
+      scheduleAgentConfigReload('queued');
+    }
+  }
+}
+
+function watchAgentConfig() {
+  if (_agentConfigWatcher) return;
+  const dir = getPluginData();
+  const file = join(dir, 'mixdog-config.json');
+  if (process.platform === 'linux') {
+    try {
+      watchFile(file, { persistent: false, interval: 2000 }, () => scheduleAgentConfigReload('mixdog-config.json'));
+      _agentConfigWatcher = { close: () => unwatchFile(file) };
+    } catch (e) {
+      process.stderr.write(`[agent-config-watch] watchFile failed on ${file}: ${e?.message}\n`);
+    }
+  } else {
+    try {
+      _agentConfigWatcher = watch(dir, { persistent: false }, (_event, filename) => {
+        if (filename === 'mixdog-config.json') scheduleAgentConfigReload('mixdog-config.json');
+      });
+    } catch (e) {
+      process.stderr.write(`[agent-config-watch] fs.watch failed on ${dir}: ${e?.message}\n`);
+    }
+  }
+}
+
+function buildInstructions() {
+  const lines = [];
+
+  try {
+    const workflows = listWorkflows();
+    lines.push('');
+    if (workflows.length > 0) {
+      lines.push('Available workflows:');
+      for (const w of workflows) {
+        lines.push(`- ${w.name}: ${w.description}`);
+      }
+    } else {
+      lines.push('No custom workflows configured.');
+    }
+  } catch {
+    lines.push('');
+    lines.push('No custom workflows configured.');
+  }
+
+  return lines.join('\n');
+}
+
+// Seed default workflows into user data dir if none exist yet.
+seedDefaults();
+
+// jobId → current activeSession.id registry. Populated by detached bridge
+// workers so bridge type=close can reach the *latest* session after a retry
+// replaced the original. Also maintains a reverse map (sessionId → jobId)
+// so bridge type=close can resolve any session id — original or replacement —
+// back to the job and close its current active session. Both maps are
+// cleared when the job finishes (finally block).
+// Map<jobId, sessionId> + Map<sessionId, jobId>
+const _jobSessionRegistry = new Map();
+const _sessionJobRegistry = new Map(); // reverse: sessionId → jobId
+
+// tag → sessionId registry for the unified `bridge` tool. A `tag` is a stable,
+// human-named handle for a detached worker session so the Lead can `bridge
+// type=send|close tag=<tag>` without tracking the raw sess_ id. Unlike the
+// job registries (which are torn down in the worker finally block to free
+// memory), tag entries persist until the session is explicitly closed OR a
+// completed/errored session is reaped from listSessions — this is what makes
+// detached workers RESUMABLE: askSession replays session.messages from the
+// {id}.json transcript on disk, so a `send` to a still-live (idle) session
+// continues the conversation. On retry the worker swaps activeSession.id; the
+// spawn handler updates this map in lockstep with _jobSessionRegistry so the
+// tag keeps pointing at the live replacement (history of the prior attempt is
+// not carried — see retry-swap note in the bridge spawn branch).
+// Map<tag, sessionId>
+const _tagSessionRegistry = new Map();
+// Map<tag, role> — in-memory, EXPLICIT caller tags only (omitted tag → auto
+// ${role}${n} is NOT recorded). Set at bind-time after session creation succeeds;
+// survives terminal reap (tag→session binding is dropped on reap; role mapping
+// stays so a cold `bridge type=send` can respawn without passing role). Cleared
+// on `bridge type=close` (live session or cold tag with only a role mapping).
+const _tagRoleRegistry = new Map();
+// Map<tag, cwd> — the resolved workerCwd captured at spawn-bind time, kept
+// alongside the tag→role map so a COLD `bridge type=send` respawn restores the
+// original spawn's working directory. Without it a cold respawn falls back to
+// the daemon's launch dir (the plugin cache), and the worker's relative-path
+// reads resolve to the deployed copy instead of the live working tree.
+const _tagCwdRegistry = new Map();
+// Per-role auto-tag counter for spawns that omit an explicit tag.
+// Map<role, number>
+const _roleTagCounters = new Map();
+
+// Per-session terminal-reap timer handle. A completed/errored bridge worker
+// schedules a 1h reap (hide-from-list + close/tombstone + tag reclaim) in its finally block;
+// the handle is stored here keyed by sessionId so a later `bridge type=send`
+// resume can CANCEL or RESCHEDULE it (see _cancelBridgeReap /
+// _scheduleBridgeReap). Without this, a send to a just-completed session could
+// be reaped mid-resume — hidden and its tag deleted — leaving the resumed
+// session unaddressable by tag.
+// Map<sessionId, ReturnType<typeof setTimeout>>
+const _sessionReapTimers = new Map();
+
+// Resolve a tag (or a raw sess_ id) to a live sessionId. Returns null when the
+// tag is unknown OR maps to a session that no longer exists / was closed.
+function _resolveBridgeTag(tagOrId) {
+  if (typeof tagOrId !== 'string' || !tagOrId) return null;
+  // Raw session id passes through (still validated against the store below).
+  let sessionId = _tagSessionRegistry.get(tagOrId) || (tagOrId.startsWith('sess_') ? tagOrId : null);
+  if (!sessionId) return null;
+  let session = null;
+  try { session = getSession(sessionId); } catch { session = null; }
+  if (!session || session.closed === true) return null;
+  return sessionId;
+}
+
+// Allocate a unique tag for a spawn. Explicit tag must not already map to a
+// LIVE session (no silent overwrite); a stale tag (closed/missing session) is
+// reclaimed. Returns { tag } or { error }.
+function _allocateBridgeTag(requestedTag, role) {
+  if (typeof requestedTag === 'string' && requestedTag.trim()) {
+    const tag = requestedTag.trim();
+    if (_resolveBridgeTag(tag)) {
+      return { error: `tag "${tag}" already maps to a live session — close it first or use a different tag` };
+    }
+    return { tag };
+  }
+  // Auto-tag: ${role}${n} per-role counter, skipping any live collisions.
+  let n = (_roleTagCounters.get(role) || 0) + 1;
+  let tag = `${role}${n}`;
+  while (_resolveBridgeTag(tag)) {
+    n += 1;
+    tag = `${role}${n}`;
+  }
+  _roleTagCounters.set(role, n);
+  return { tag };
+}
+
+// Reverse-lookup the tag bound to a sessionId (for list output). Linear scan;
+// the registry is small (one live worker per entry).
+function _tagForSessionId(sessionId) {
+  for (const [tag, sid] of _tagSessionRegistry.entries()) {
+    if (sid === sessionId) return tag;
+  }
+  return null;
+}
+
+// Validate that a raw `sess_...` id maps to a LIVE (on-disk, non-tombstoned)
+// session. A reaped/closed session leaves a tombstone (closed===true) or is
+// gone entirely; treating such an id as resolved would launch an async
+// askSession against a dead session (#5). Used to gate the raw-sess_ fallback
+// in both the cold-respawn precheck and the send branch.
+function _isLiveSession(sessionId) {
+  if (!sessionId) return false;
+  try {
+    const s = getSession(sessionId);
+    return !!(s && s.closed !== true);
+  } catch { return false; }
+}
+
+// Schedule the 1h (3600s) terminal reap for a completed/errored session: hide
+// it from listSessions() and reclaim its tag. The 1h window keeps a finished
+// bridge worker resumable for same-task reuse — a follow-up `bridge type=send`
+// to the same tag continues the SAME session (transcript preserved, no
+// from-scratch re-discovery) and lands within the 1h prompt-cache window of
+// every provider we use, so the resume is cheap. The timer handle is recorded in
+// _sessionReapTimers so a resume (`bridge type=send`) can cancel it. Any
+// previously-pending reap for the same session is cancelled first so the
+// window is not double-scheduled. `.unref()` keeps the timer from holding the
+// process open (mirrors a detached lifecycle hook).
+function _scheduleBridgeReap(sessionId) {
+  if (!sessionId) return;
+  _cancelBridgeReap(sessionId);
+  const handle = setTimeout(() => {
+    _sessionReapTimers.delete(sessionId);
+    try { hideSessionFromList(sessionId); } catch { /* ignore */ }
+    // #3: also CLOSE/tombstone the persisted session JSON. hideSessionFromList
+    // only flips an in-memory listHidden flag (lost on restart) and the
+    // statusline aggregator reads the on-disk JSON directly — it treats any
+    // non-closed bridge worker as an idle worker and keeps rendering the
+    // reaped session until the 24h store sweep. Closing plants closed===true
+    // (status='closed') so the aggregator's `s.closed === true` filter drops
+    // it immediately. This is the terminal reap, so the worker is no longer
+    // resumable — closing is the correct lifecycle end.
+    try { closeSession(sessionId, 'terminal-reap'); } catch { /* ignore */ }
+    // Reclaim the tag once the terminal session is reaped from the list — the
+    // worker is no longer resumable, so free the name.
+    try {
+      const _t = _tagForSessionId(sessionId);
+      if (_t) _tagSessionRegistry.delete(_t);
+    } catch { /* ignore */ }
+  }, 3_600_000);
+  try { handle.unref?.(); } catch { /* ignore */ }
+  _sessionReapTimers.set(sessionId, handle);
+}
+
+// Cancel a pending terminal reap for a session (called on resume so an
+// in-flight/just-resumed worker is not hidden + tag-reclaimed mid-use).
+// Returns true if a timer was actually cleared.
+function _cancelBridgeReap(sessionId) {
+  if (!sessionId) return false;
+  const handle = _sessionReapTimers.get(sessionId);
+  if (!handle) return false;
+  try { clearTimeout(handle); } catch { /* ignore */ }
+  _sessionReapTimers.delete(sessionId);
+  return true;
+}
+
+// --- Shared session-control helpers (folded from the removed standalone
+// list / close session handlers (now bridge type=list / bridge type=close);
+// the unified `bridge` handler calls these so the runtime stage/staleness
+// derivation stays single-sourced).
+
+// Build the list-sessions view with runtime stage + staleness. Optional
+// role/status filters and a brief flag mirror the legacy tool's shape, plus a
+// `tag` field resolved from the tag registry.
+function _bridgeListSessions(opts = {}) {
+  const sessions = listSessions();
+  if (sessions.length === 0) return 'No active sessions.';
+  const now = Date.now();
+  const brief = opts.brief !== false;
+  const includeClosed = opts.includeClosed === true;
+  const roleFilter = typeof opts.role === 'string' && opts.role ? opts.role : null;
+  const statusFilter = typeof opts.status === 'string' && opts.status ? opts.status : null;
+  let filtered = includeClosed ? sessions : sessions.filter((s) => s.closed !== true);
+  if (filtered.length === 0) return 'No active sessions.';
+  const rows = filtered.map((s) => {
+    const runtime = getSessionRuntime(s.id);
+    // No runtime entry → session has no in-flight work; stage derives from
+    // persisted status ('running' is only set by long-running callers; idle
+    // otherwise). Single derivation, no legacy fallback path.
+    const persistedStatus = s.status || 'idle';
+    // Tombstones override status/stage. The persisted `status` field may still
+    // be 'running' because close aborts rather than touches it; `closed: true`
+    // is the authoritative signal.
+    const isClosed = s.closed === true;
+    const status = isClosed ? 'closed' : persistedStatus;
+    // Persisted status is the authoritative terminal signal — runtime stage may
+    // linger as 'streaming'/'tool_running' if the runtime entry missed the
+    // terminal transition. Trust persistedStatus when terminal; only use
+    // runtime stage while status is still 'running'.
+    const persistedTerminal = persistedStatus === 'idle' || persistedStatus === 'error';
+    const stage = isClosed
+      ? 'closed'
+      : (persistedTerminal ? persistedStatus : (runtime?.stage || 'connecting'));
+    const lastStreamDeltaAt = runtime?.lastStreamDeltaAt
+      ? new Date(runtime.lastStreamDeltaAt).toISOString()
+      : null;
+    const staleSeconds = runtime?.lastStreamDeltaAt
+      ? Math.floor((now - runtime.lastStreamDeltaAt) / 1000)
+      : null;
+    // windowTokens: provider-normalized context footprint at the most-recent
+    // call — the prompt tokens the model actually saw last turn, comparable
+    // across providers. Anthropic's input_tokens excludes cache, so
+    // lastContextTokens folds cache_read back in; openai/grok/gemini already
+    // include it. Far more honest than the lifetime-cumulative totalInputTokens
+    // (which mixes per-provider cache conventions). Falls back to
+    // lastInputTokens for sessions persisted before lastContextTokens existed.
+    const windowTokens = Number(s.lastContextTokens ?? s.lastInputTokens) || 0;
+    const base = {
+      id: s.id,
+      tag: _tagForSessionId(s.id),
+      role: s.role || null,
+      provider: s.provider,
+      model: s.model,
+      messages: s.messages.length,
+      tools: s.tools.length,
+      windowTokens,
+      windowCap: Number(s.contextWindow) || null,
+      cumulativeInputTokens: s.totalInputTokens,
+      cumulativeOutputTokens: s.totalOutputTokens,
+      scope: s.scopeKey || null,
+      status,
+      lastStatus: persistedStatus,
+      createdAt: new Date(s.createdAt).toISOString(),
+      updatedAt: s.updatedAt ? new Date(s.updatedAt).toISOString() : null,
+      stage,
+      lastStreamDeltaAt,
+      staleSeconds,
+      lastToolCall: runtime?.lastToolCall || null,
+    };
+    if (!brief) {
+      base.toolNames = Array.isArray(s.tools) ? s.tools.map((t) => t?.name).filter(Boolean) : [];
+    }
+    return base;
+  });
+  const out = rows.filter((r) =>
+    (!roleFilter || r.role === roleFilter) &&
+    (!statusFilter || r.status === statusFilter));
+  if (out.length === 0) return 'No active sessions.';
+  if (brief) {
+    // Brief (default): one compact line per session for token efficiency.
+    // Null/empty fields are omitted; callers needing full detail pass
+    // brief:false to get the unchanged JSON object array below.
+    return out.map((r) => {
+      const label = r.tag || String(r.id).split('_').pop();
+      const parts = [label];
+      if (r.role) parts.push(`role=${r.role}`);
+      if (r.model) parts.push(`model=${r.model}`);
+      if (r.status) parts.push(`status=${r.status}`);
+      if (r.stage) parts.push(`stage=${r.stage}`);
+      if (r.staleSeconds) parts.push(`stale=${r.staleSeconds}s`);
+      parts.push(`msgs=${r.messages}`);
+      const windowK = Math.round(r.windowTokens / 1000);
+      if (windowK) parts.push(`window=${windowK}k`);
+      if (r.lastToolCall) parts.push(`lastTool=${r.lastToolCall}`);
+      return parts.join(' ');
+    }).join('\n');
+  }
+  return out;
+}
+
+// Close a session by raw id (fire-and-forget). Resolves any retry-replacement
+// session via the job registries and plants a cancellation tombstone. Returns
+// the close ack shape. Folded verbatim from the removed standalone close
+// handler (now bridge type=close).
+function _bridgeCloseSession(sessionId) {
+  // Fire-and-forget: plant tombstone, abort in-flight controller, defer
+  // cleanup. We don't wait for the abort to unwind — callers get an immediate
+  // ack and unknown IDs return the same shape for simplicity.
+  //
+  // Retry-session forwarding: if the supplied sessionId was the initial session
+  // for a detached bridge job since replaced by a retry, the registry maps
+  // jobId→currentSessionId. We close the current (possibly newer) replacement
+  // too so the worker is actually stopped. If no retry replacement exists the
+  // current==requested and both closeSession calls are idempotent no-ops.
+  closeSession(sessionId, 'manual');
+  const owningJobId = _sessionJobRegistry.get(sessionId);
+  if (owningJobId != null) {
+    // Plant a job-level cancellation tombstone so the dispatch-retry loop stops
+    // between attempts. closeSession() only kills the currently-active session;
+    // without this flag, a manual close landing during STALL_RETRY_BACKOFF_MS
+    // would still let the retry path create a fresh activeSession after backoff.
+    _jobCancelledTombstones.add(owningJobId);
+    const currentId = _jobSessionRegistry.get(owningJobId);
+    if (currentId && currentId !== sessionId) {
+      try { closeSession(currentId, 'manual'); } catch {}
+    }
+  }
+  return { ok: true, sessionId };
+}
+
+// Job-level cancellation tombstones. bridge type=close plants the owning jobId so
+// the dispatch-retry path stops between attempts even when the manual close
+// races the stall-retry backoff (the OLD session is closed, but runWithDispatchRetry
+// is still asleep on STALL_RETRY_BACKOFF_MS and would otherwise unconditionally
+// spin a fresh activeSession on the next attempt). Cleared by the worker's
+// finally / .catch block when the job tears down.
+const _jobCancelledTombstones = new Set();
+
+// Seed plugin-owned scaffolding files (memory-config.json, etc.) so
+// first-time installs land with the Pool B surface populated and the Config
+// UI has real paths to edit.
+ensureDataSeeds(getPluginData());
+
+const INSTRUCTIONS = buildInstructions();
+
+// --- Prompt store (file-backed, shared with bin/bridge CLI) ---
+const _promptStorePath = join(getPluginData(), 'prompt-store.json');
+let _promptSeq = 0;
+
+function _psLoad() {
+  try {
+    return JSON.parse(readFileSync(_promptStorePath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function _psSave(store) {
+  writeFileSync(_promptStorePath, JSON.stringify(store) + '\n', 'utf-8');
+}
+
+const _promptStore = {
+  get(key) {
+    return _psLoad()[key] ?? null;
+  },
+  set(key, val) {
+    const store = _psLoad();
+    store[key] = val;
+    _psSave(store);
+  },
+  delete(key) {
+    const store = _psLoad();
+    delete store[key];
+    _psSave(store);
+  },
+};
+
+// --- Helpers ---
+
+// Worker reply protocol: every bridge response is wrapped in
+// <final-answer>...</final-answer> by instruction (rules/bridge/00-common.md).
+// Extract the wrapped content; if the tag is missing return raw text.
+function extractFinalAnswer(text) {
+  if (typeof text !== 'string' || !text) return text;
+  const m = text.match(/<final-answer>([\s\S]*?)<\/final-answer>/);
+  if (m) return m[1].trim();
+  return text;
+}
+
+function ok(data) {
+  return { content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }] };
+}
+
+function fail(err) {
+  const msg = errText(err);
+  return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+}
+
+// Format token counts in Claude Code style: <1000 as-is, >=1000 as "9.9k".
+function fmtTokens(n) {
+  if (typeof n !== 'number') return String(n ?? '?');
+  if (n < 1000) return String(n);
+  return `${(n / 1000).toFixed(1)}k`;
+}
+
+// --- bridge case helpers ---
+// These are ordered helpers extracted from the `case 'bridge'` handler.
+// They are side-effecting (emit notifications, mutate registries, wire
+// abort listeners, call into the session manager) but take all collaborators
+// as arguments — so call-site behavior is byte-identical to the inlined form.
+
+// Input resolution: prompt | file | ref → { prompt } or { error }.
+// `bridgeCwd` is the bridge worker's resolved working directory
+// (args.cwd > callerCwd). When supplied, a relative `args.file` is
+// resolved against it rather than the agent process cwd — previously
+// `readFile(args.file)` would silently read from the agent's process
+// cwd, producing the wrong contents (or ENOENT) for bridge callers
+// whose effective workspace differs from the host process.
+async function _resolveBridgePrompt(args, bridgeCwd = null) {
+  let prompt = args.prompt;
+  // Invariant: each input slot counts only when it carries
+  // non-whitespace content. filter(Boolean) historically accepted
+  // trim-empty strings ("\n", "   "), producing a downstream
+  // "# Task\n<whitespace>" block and silent empty-<final-answer>
+  // responses from the worker.
+  const _isMeaningful = (x) => typeof x === 'string' ? x.trim().length > 0 : Boolean(x);
+  const _inputCount = [args.prompt, args.file, args.ref].filter(_isMeaningful).length;
+  if (_inputCount > 1) return { error: 'bridge: provide exactly one of prompt|ref|file' };
+  if (!_isMeaningful(prompt) && _isMeaningful(args.file)) {
+    try {
+      const _filePath = (bridgeCwd && !isAbsolute(args.file))
+        ? resolve(bridgeCwd, args.file)
+        : args.file;
+      prompt = await readFile(_filePath, 'utf-8');
+    } catch (e) {
+      return { error: `Cannot read file: ${e.message}` };
+    }
+  }
+  if (!_isMeaningful(prompt) && _isMeaningful(args.ref)) {
+    prompt = _promptStore.get(args.ref);
+    if (!prompt) return { error: `ref "${args.ref}" not found in prompt store` };
+    _promptStore.delete(args.ref);
+  }
+  if (!_isMeaningful(prompt)) return { error: 'prompt must contain non-whitespace content (or provide a non-empty file/ref)' };
+  return { prompt };
+}
+
+// Role/preset lookup: bench escape hatch (provider+model) OR
+// user-workflow.json role→preset mapping.
+function _resolveBridgePreset(args, config) {
+  if (args.provider && args.model) {
+    const preset = {
+      id: '__bench__',
+      name: '__BENCH__',
+      type: 'bridge',
+      provider: String(args.provider),
+      model: String(args.model),
+      effort: args.effort ? String(args.effort) : undefined,
+      fast: args.fast === true,
+      tools: args.tools ? String(args.tools) : 'full',
+    };
+    const promptPrefix = args.systemPrompt ? String(args.systemPrompt) + '\n\n' : null;
+    return { preset, presetName: preset.name, _roleConfig: null, promptPrefix };
+  }
+  // Bench escape hatch, model-only form: a model override with no provider.
+  // Resolve the provider from the loaded config presets by exact model match
+  // so the override is honored instead of silently falling through to the
+  // role default. Errors out (rather than guessing) when no preset matches.
+  if (args.model && !args.provider) {
+    const _matches = config.presets?.filter((x) => x.model === String(args.model)) ?? [];
+    if (_matches.length === 0) {
+      return { error: `model "${args.model}" did not match any preset in mixdog-config.json — pass provider explicitly or use a preset` };
+    }
+    const _providers = [...new Set(_matches.map((x) => String(x.provider)))];
+    if (_providers.length > 1) {
+      return { error: `model "${args.model}" is ambiguous — it maps to multiple providers (${_providers.join(', ')}) in mixdog-config.json; pass provider explicitly` };
+    }
+    const _matched = _matches[0];
+    const preset = {
+      id: '__bench__',
+      name: '__BENCH__',
+      type: 'bridge',
+      provider: String(_matched.provider),
+      model: String(args.model),
+      effort: args.effort ? String(args.effort) : undefined,
+      fast: args.fast === true,
+      tools: args.tools ? String(args.tools) : 'full',
+    };
+    const promptPrefix = args.systemPrompt ? String(args.systemPrompt) + '\n\n' : null;
+    return { preset, presetName: preset.name, _roleConfig: null, promptPrefix };
+  }
+  // Load role→preset mapping from user-workflow.json. Role primitives only —
+  // no suffix variants, exact match required.
+  // Route through loadUserWorkflowRoles() so validateRoleConfig runs on
+  // every entry and _roleConfigCache is populated with full RoleConfig objects
+  // (including permission). getRoleConfig() then returns the validated record.
+  loadUserWorkflowRoles();
+  const _roleConfig = getRoleConfig(args.role);
+  const presetName = args.preset || _roleConfig?.preset;
+  if (!presetName) return { error: `role "${args.role}" not found in user-workflow.json (and no preset override given)` };
+  const preset = config.presets?.find((x) => x.id === presetName || x.name === presetName);
+  if (!preset) return { error: `preset "${presetName}" (mapped from role "${args.role}") not found in mixdog-config.json` };
+  return { preset, presetName, _roleConfig, promptPrefix: null };
+}
+
+// cwd resolution: explicit args.cwd > callerCwd > null; then spawn-safe variant.
+function _buildBridgeCwds(args, callerCwd) {
+  const _rawBridgeCwd = args.cwd ? normalizeInputPath(args.cwd) : (callerCwd || null);
+  const _safeBridgeCwd = _safeCwdForSpawn(_rawBridgeCwd);
+  return { _rawBridgeCwd, _safeBridgeCwd };
+}
+
+// cwd rewrite: prepend authoritative-cwd note (when silent-swapped) and the
+// invariant [effective-cwd] header. Idempotent against retry paths.
+function _applyBridgeCwdHeaders(prompt, rawCwd, safeCwd) {
+  if (rawCwd && safeCwd !== rawCwd) {
+    prompt = `# Working directory note\nThe authoritative working directory is \`${rawCwd}\`. Use absolute paths starting with this prefix in every tool call. The host process is running from \`${safeCwd}\` because the original cwd contains characters that node's child_process spawn cannot reliably handle on this platform.\n\n${prompt}`;
+  }
+  // Invariant header: tell the worker its effective cwd as data so that
+  // bare `~` in brief text cannot be re-expanded against a container HOME.
+  // Omit entirely when cwd is null (no workspace context).
+  // Idempotent: skip if the brief already carries the header (retry paths).
+  if (rawCwd && !String(prompt).startsWith('[effective-cwd]')) {
+    prompt = `[effective-cwd] ${rawCwd}\n\n${prompt}`;
+  }
+  return prompt;
+}
+
+// R3 Gap 3: clamp forwarded permissionMode against the parent Lead session
+// so a bridge worker can never become MORE permissive than its caller.
+// Rank: plan(0) < default(1) < acceptEdits(2) < bypassPermissions(3).
+// Unknown/missing parent ⇒ treat as 'default'. Unknown requested ⇒ pass
+// through unranked (validator already enums the accepted set upstream).
+function _clampBridgePermissionMode(requested, parentPermissionMode, role) {
+  const _permRank = { plan: 0, default: 1, acceptEdits: 2, bypassPermissions: 3 };
+  const _parentRanked = Object.prototype.hasOwnProperty.call(_permRank, parentPermissionMode);
+  const _parentRank = _parentRanked ? _permRank[parentPermissionMode] : _permRank.default;
+  let _permissionMode = requested;
+  if (requested && Object.prototype.hasOwnProperty.call(_permRank, requested)) {
+    const _reqRank = _permRank[requested];
+    if (_reqRank > _parentRank) {
+      const _clampedTo = _parentRanked ? parentPermissionMode : 'default';
+      process.stderr.write(
+        `[bridge-perm-clamp] role=${role} requested=${requested} parent=${parentPermissionMode || 'default'} clamped=${_clampedTo}\n`
+      );
+      _permissionMode = _clampedTo;
+    }
+  }
+  return _permissionMode;
+}
+
+// Fire-and-forget code-graph prewarm so the first find_symbol in this
+// bridge dispatch hits a warm cache (cold _buildCodeGraph is the 90s
+// outlier in PG bridge_calls telemetry). Same pattern as warmupCatalogs.
+// Prewarm only when prefetch signals symbol-graph use. files-only
+// prefetch embeds file bodies in the prompt and never fires
+// find_symbol — prewarming the graph for that path is wasted CPU.
+// callers / references are the true graph-touch signals.
+function _runBridgePrewarm(workerCwd, prefetch) {
+  const _prewarmCallers = Array.isArray(prefetch?.callers) ? prefetch.callers : [];
+  const _prewarmRefs = Array.isArray(prefetch?.references) ? prefetch.references : [];
+  const _prewarmSymbols = [..._prewarmCallers, ..._prewarmRefs].filter(Boolean);
+  if (_prewarmSymbols.length > 0) {
+    // Symbol-aware prewarm populates lazy per-symbol candidate cache
+    // so the worker's first find_symbol on these names skips the
+    // O(N) node scan in addition to skipping the graph cold build.
+    try { prewarmCodeGraphSymbols(workerCwd, _prewarmSymbols); }
+    catch (e) { process.stderr.write(`[bridge] prewarmCodeGraphSymbols failed: ${e?.message}\n`); }
+  } else if (prefetch && (prefetch.callers || prefetch.references)) {
+    // Only fall back to a full graph prewarm when prefetch signals
+    // symbol-graph use (callers/references fields present). Files-only
+    // or otherwise empty prefetch never fires find_symbol, so skip.
+    try { prewarmCodeGraph(workerCwd); }
+    catch (e) { process.stderr.write(`[bridge] prewarmCodeGraph failed: ${e?.message}\n`); }
+  }
+}
+
+// --- opt-in git-worktree isolation for bridge workers ---
+// When a spawn passes isolation:'worktree' and the resolved workerCwd lives
+// inside a git repo, the worker runs in a dedicated `git worktree` + branch so
+// parallel workers can edit the same files without stepping on each other's
+// working tree. On any git failure we fall back to the plain workerCwd (a warn
+// to stderr) so isolation is strictly best-effort and never blocks a spawn.
+
+// Sanitize a tag/jobId fragment into a shell-safe, git-ref-safe token. Only
+// [A-Za-z0-9_-] survive; everything else is dropped. Empty result → null so
+// callers fall back to the jobId. Never interpolated into a shell (execFile),
+// but sanitized anyway to keep the branch ref well-formed.
+function _sanitizeWorktreeName(raw) {
+  if (raw == null) return null;
+  const cleaned = String(raw).replace(/[^A-Za-z0-9_-]/g, '');
+  return cleaned.length > 0 ? cleaned : null;
+}
+
+// Resolve the git repo root for a cwd (null when not a git repo / git absent).
+function _gitRepoRoot(cwd) {
+  try {
+    const out = execFileSync('git', ['-C', cwd, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      // Bound a hung git so it can't block the daemon event loop for ALL
+      // sessions; on timeout execFileSync throws and the catch falls back.
+      timeout: 10000,
+      maxBuffer: 8 * 1024 * 1024,
+      windowsHide: true,
+    });
+    const root = String(out).trim();
+    return root.length > 0 ? root : null;
+  } catch {
+    return null;
+  }
+}
+
+// Attempt to create an isolated worktree for a worker. Returns the new worktree
+// path on success, or null to signal "use plain workerCwd". Best-effort: any
+// failure warns to stderr and returns null.
+// Returns { worktreePath, branch } on success; null on fallback.
+function _setupWorkerWorktree({ workerCwd, jobId, tag }) {
+  const repoRoot = _gitRepoRoot(workerCwd);
+  if (!repoRoot) {
+    try { process.stderr.write(`[bridge] isolation=worktree requested but ${workerCwd} is not in a git repo — using plain cwd\n`); } catch {}
+    return null;
+  }
+  const safeName = _sanitizeWorktreeName(tag) || _sanitizeWorktreeName(jobId) || _sanitizeWorktreeName(`job_${Date.now()}`);
+  const pluginData = process.env.CLAUDE_PLUGIN_DATA || getPluginData();
+  const worktreePath = join(pluginData, 'worktrees', _sanitizeWorktreeName(jobId) || safeName);
+  const branch = `bridge/${safeName}`;
+  try {
+    execFileSync('git', ['-C', repoRoot, 'worktree', 'add', worktreePath, '-b', branch], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // Bound a hung git so it can't block the daemon event loop for ALL
+      // sessions; on timeout execFileSync throws and the catch falls back.
+      timeout: 10000,
+      maxBuffer: 8 * 1024 * 1024,
+      windowsHide: true,
+    });
+    return { worktreePath, branch, repoRoot };
+  } catch (e) {
+    try { process.stderr.write(`[bridge] git worktree add failed (job=${jobId}) — falling back to plain cwd: ${e?.message ?? e}\n`); } catch {}
+    return null;
+  }
+}
+
+// Tear down a worker's isolated worktree in the IIFE finally block. If the
+// worktree is clean it is removed and its branch deleted. If dirty, it is kept
+// (no auto-merge) and { kept:true, path, changedFiles } is returned so the
+// completion emit can surface the leftover path + changed-file count.
+function _teardownWorkerWorktree({ worktreePath, branch, repoRoot }) {
+  let dirty = false;
+  let changedFiles = 0;
+  try {
+    const out = execFileSync('git', ['-C', worktreePath, 'status', '--porcelain'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      // Bound a hung git so it can't block the daemon event loop for ALL
+      // sessions; on timeout execFileSync throws and the catch falls back.
+      timeout: 10000,
+      maxBuffer: 8 * 1024 * 1024,
+      windowsHide: true,
+    });
+    const lines = String(out).split('\n').filter((l) => l.trim().length > 0);
+    changedFiles = lines.length;
+    dirty = changedFiles > 0;
+  } catch (e) {
+    // If status can't be read, treat as dirty (keep) — never destroy unknown state.
+    try { process.stderr.write(`[bridge] worktree status failed (${worktreePath}) — keeping worktree: ${e?.message ?? e}\n`); } catch {}
+    return { kept: true, path: worktreePath, changedFiles: 0 };
+  }
+  if (dirty) {
+    return { kept: true, path: worktreePath, changedFiles };
+  }
+  // Clean — remove the worktree and delete its branch.
+  try {
+    execFileSync('git', ['-C', repoRoot, 'worktree', 'remove', '--force', worktreePath], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // Bound a hung git so it can't block the daemon event loop for ALL
+      // sessions; on timeout execFileSync throws and the catch falls back.
+      timeout: 10000,
+      maxBuffer: 8 * 1024 * 1024,
+      windowsHide: true,
+    });
+  } catch (e) {
+    try { process.stderr.write(`[bridge] worktree remove failed (${worktreePath}): ${e?.message ?? e}\n`); } catch {}
+  }
+  try {
+    execFileSync('git', ['-C', repoRoot, 'branch', '-D', branch], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // Bound a hung git so it can't block the daemon event loop for ALL
+      // sessions; on timeout execFileSync throws and the catch falls back.
+      timeout: 10000,
+      maxBuffer: 8 * 1024 * 1024,
+      windowsHide: true,
+    });
+  } catch (e) {
+    try { process.stderr.write(`[bridge] branch delete failed (${branch}): ${e?.message ?? e}\n`); } catch {}
+  }
+  return { kept: false, path: worktreePath, changedFiles: 0 };
+}
+
+// Short model tag for bridge worker lifecycle notifications.
+// Strip the redundant `claude-` vendor prefix; other providers
+// (gpt-*, etc.) pass through unchanged. Falls back to empty on
+// missing model so callers never throw.
+function _bridgeModelTag(preset) {
+  try {
+    const raw = preset.model;
+    if (!raw || typeof raw !== 'string') return '';
+    const stripped = raw.startsWith('claude-') ? raw.slice('claude-'.length) : raw;
+    return stripped ? `[${stripped}] ` : '';
+  } catch { return ''; }
+}
+
+// Brief size soft-warn helper: cap is ≤150 words per rules/lead/00-tool-lead.md.
+function _bridgeBriefWordCount(prompt) {
+  return prompt ? String(prompt).trim().split(/\s+/).filter(Boolean).length : 0;
+}
+
+// Logging-only listener so operators can correlate the MCP request
+// abort with a still-running detached worker. Returns the detach fn so the
+// IIFE finally block can remove it on normal completion (previously
+// leaked until GC). Detached bridge workers do NOT close the session on
+// MCP request abort — by contract they outlive the originating request.
+function _wireRequestAbortLog(requestSignal, { sessionId, role, jobId }) {
+  if (!requestSignal) return () => {};
+  const onRequestAbort = () => {
+    try {
+      process.stderr.write(
+        `[bridge] MCP request aborted — detached worker continues: session=${sessionId} role=${role} job=${jobId}\n`,
+      );
+      // Intentionally NOT calling closeSession() here — detached bridge
+      // workers survive the MCP request lifecycle.
+    } catch (e) { process.stderr.write(`[bridge] onRequestAbort write failed: ${e?.message}\n`); }
+  };
+  if (requestSignal.aborted) {
+    queueMicrotask(onRequestAbort);
+    return () => {};
+  }
+  try {
+    requestSignal.addEventListener('abort', onRequestAbort, { once: true });
+    return () => {
+      try { requestSignal.removeEventListener('abort', onRequestAbort); } catch { /* ignore */ }
+    };
+  } catch (e) {
+    process.stderr.write(`[bridge] addEventListener abort failed: ${e?.message}\n`);
+    return () => {};
+  }
+}
+
+// Render: empty-content diagnostic. Builds the telemetry shape, emits the
+// stderr breadcrumb, and returns the user-facing diagnostic string. Pure
+// w.r.t. the dispatch loop: only stderr side-effect, no state mutation.
+function _renderEmptyContentDiagnostic(result, activeSession) {
+  // Telemetry: why did the bridge result lack content?
+  const shape = {
+    resultType: typeof result,
+    contentType: typeof result?.content,
+    contentLen: typeof result?.content === 'string' ? result.content.length : null,
+    hasToolCalls: Array.isArray(result?.toolCalls) ? result.toolCalls.length : null,
+    stopReason: result?.stopReason ?? result?.stop_reason ?? null,
+    midstreamRetries: result?.__midstreamRetries ?? null,
+    toolCallsTotal: typeof result?.toolCallsTotal === 'number' ? result.toolCallsTotal : null,
+    outputTokens: typeof result?.lastUsage?.outputTokens === 'number'
+        ? result.lastUsage.outputTokens
+        : (typeof result?.usage?.outputTokens === 'number' ? result.usage.outputTokens : null),
+    model: activeSession?.model ?? null,
+    // Provider content-block classification (anthropic*.mjs):
+    // distinguishes thinking-only stalls (reasoning emitted, no
+    // text/tool_use) from true silent empty turns. null when
+    // the provider doesn't expose these fields.
+    hasThinkingContent: typeof result?.hasThinkingContent === 'boolean'
+        ? result.hasThinkingContent
+        : null,
+    contentBlockTypes: Array.isArray(result?.contentBlockTypes)
+        ? result.contentBlockTypes.slice()
+        : null,
+    keys: result && typeof result === 'object' ? Object.keys(result) : null,
+  };
+  try { process.stderr.write(`[bridge] empty-content fallback for sessionId=${activeSession?.id ?? 'unknown'} shape=${JSON.stringify(shape)}\n`); } catch {}
+  // Empty-content protocol guard: emit diagnostic instead of
+  // silent empty so Lead always sees actionable signal.
+  // Reports iterations + cumulative toolCallsTotal (not just
+  // final-turn toolCalls which is 0 when synthesis stalls) +
+  // stopReason. Work landed via tool calls survives even when
+  // the final synthesis turn returned empty content; this
+  // message helps Lead distinguish "work landed, synthesis
+  // missing" from "nothing happened".
+  const _emptyIterations = result?.iterations ?? 0;
+  const _emptyToolCallsTotal = result?.toolCallsTotal ?? shape.hasToolCalls ?? 0;
+  const _emptyFinalToolCalls = shape.hasToolCalls ?? 0;
+  const _emptyStopReason = shape.stopReason ?? 'unknown';
+  const _emptyOutTokens = shape.outputTokens;
+  const _emptyModel = shape.model ?? 'unknown';
+  const _outTokPart = typeof _emptyOutTokens === 'number'
+      ? `${_emptyOutTokens} output token(s)`
+      : 'output tokens unknown';
+  // Thinking-only stall vs. true empty disambiguator: when the
+  // provider classifies content blocks (anthropic*.mjs) we can
+  // tell Lead whether the model spent the turn on reasoning
+  // (hasThinkingContent=true, blockTypes contains 'thinking')
+  // versus producing nothing at all. Older providers leave
+  // these null — fall back to "unknown" so Lead still knows
+  // the classification wasn't available.
+  const _emptyHasThinking = shape.hasThinkingContent;
+  const _emptyBlockTypes = shape.contentBlockTypes;
+  const _thinkingPart = _emptyHasThinking === null
+      ? 'hasThinkingContent=unknown'
+      : `hasThinkingContent=${_emptyHasThinking}`;
+  const _blockTypesPart = _emptyBlockTypes === null
+      ? 'contentBlockTypes=unknown'
+      : `contentBlockTypes=[${_emptyBlockTypes.join(',') || 'none'}]`;
+  const _classifyHint = _emptyHasThinking === true
+      ? ' — thinking-only stall (model emitted reasoning but no text/tool_use); likely max_tokens or budget cutoff mid-synthesis'
+      : (_emptyHasThinking === false && Array.isArray(_emptyBlockTypes) && _emptyBlockTypes.length === 0
+          ? ' — true empty turn (no content blocks emitted at all)'
+          : '');
+  return `(empty final synthesis: bridge worker [model=${_emptyModel}] completed ${_emptyIterations} iteration(s) with ${_emptyToolCallsTotal} cumulative tool call(s); final turn had ${_emptyFinalToolCalls} tool call(s), 0 content, ${_outTokPart}. stopReason=${_emptyStopReason}. ${_thinkingPart} ${_blockTypesPart}${_classifyHint}. Tool-side work (read/edit/write/apply_patch) may have landed — if toolCallsTotal>0 check git diff or trace store; if toolCallsTotal=0 and outputTokens=0 nothing happened. Possible causes: provider returned text-empty terminal turn (thinking-only block, pause_turn, max_tokens), worker skipped <final-answer> tag emission, or contract-nudge cap reached. Re-dispatch or inspect landed work.)`;
+}
+
+// Empty <final-answer> guard: extractFinalAnswer returns '' when the
+// model emitted `<final-answer></final-answer>` (or wrapped only
+// whitespace). Lead would otherwise receive a bare `[role]` header
+// and have no signal about what the worker produced. Surface the
+// raw content (truncated) with an explicit warning so the Lead can
+// see the actual model output and decide next steps.
+function _resolveFinalAnswer(content) {
+  let _extractedAnswer = extractFinalAnswer(content);
+  if (typeof _extractedAnswer === 'string' && _extractedAnswer.trim().length === 0) {
+    const _rawSample = typeof content === 'string' ? content.slice(0, 500) : '';
+    _extractedAnswer = _rawSample
+      ? `(warning: empty <final-answer> tag; raw response: ${_rawSample})`
+      : '(warning: worker produced no content)';
+  }
+  return _extractedAnswer;
+}
+
+// Unified emit-with-delivery-flag helper for the bridge dispatch IIFE.
+// Matches the original four-site pattern: `emit → set delivered → catch
+// emit error → log to stderr (best-effort)`. Returns true on emit success,
+// false on failure; callers OR-in the result so an earlier success cannot
+// be flipped to false by a later branch's emit failure (the original code
+// only ever set `_delivered = true`, never back to false).
+function _bridgeDispatchMeta(jobId, { error = false, instruction } = {}) {
+  return {
+    type: 'dispatch_result',
+    dispatch_id: jobId,
+    tool: 'bridge',
+    error: String(!!error),
+    instruction: instruction || `The bridge dispatch you started earlier (${jobId}) has returned — use this answer in your next step.`,
+  };
+}
+
+async function _bridgeEmitDelivered(emit, message, { pathLabel, jobId, sessionId, role, meta }) {
+  try {
+    await Promise.resolve(emit(message, meta || _bridgeDispatchMeta(jobId)));
+    return true;
+  } catch (emitErr) {
+    try {
+      process.stderr.write(`[bridge] emit failed (${pathLabel}): job=${jobId} session=${sessionId} role=${role} ${emitErr instanceof Error ? emitErr.message : String(emitErr)}\n`);
+    } catch {}
+    return false;
+  }
+}
+
+// --- Tool definitions ---
+//
+// Tool array lives in ./tool-defs.mjs (pure data, zero side effects) so
+// it can be imported without dragging the full agent module graph.
+// Re-aliased here as `TOOLS` to keep existing references and the
+// `TOOL_DEFS` export below resolving unchanged.
+import { TOOL_DEFS as TOOLS } from './tool-defs.mjs';
+
+// ── Module exports (for unified server) ──────────────────────────────
+
+export { TOOLS as TOOL_DEFS };
+export { INSTRUCTIONS as instructions };
+
+export async function init() {
+  const config = loadConfig();
+  // External MCP servers only. Plugin's own tools are injected in-process
+  // via the context from server.mjs; a self-ref entry would self-spawn or
+  // partially loop back through HTTP, so strip on ingress.
+  const externalServers = externalMcpServersFromConfig(config);
+  // Run independent init steps in parallel: provider registry + external
+  // MCP server connections. Both are network-bound and have no shared
+  // dependency, so serialising them was wasted boot latency.
+  await Promise.all([
+    initProviders(config.providers),
+    Object.keys(externalServers).length > 0 ? connectMcpServers(externalServers) : Promise.resolve(),
+  ]);
+  _lastExternalServersKey = stableJson(externalServers);
+  // Force-refresh each provider's /models catalog in the background so models
+  // released since the last run are picked up on every MCP start (the old
+  // warmupCatalogs respected the 24h provider TTL and no-op'd on a fresh
+  // cache). LiteLLM pricing/context metadata is intentionally left on its own
+  // 24h TTL — not force-refreshed here.
+  setImmediate(() => refreshProviderCatalogsOnStartup());
+  seedDefaults();
+  startStreamWatchdog(forEachSessionRuntime);
+  // Smart Bridge — unified router + cache strategy + profile system.
+  // User-role preset mapping comes from user-workflow.json (existing source
+  // of truth). Preset catalog (provider/model/effort) comes from config.presets.
+  try {
+    const { initSmartBridge, getSmartBridge, setRoleResolver } = await import('./orchestrator/smart-bridge/index.mjs');
+    const userRoles = loadUserWorkflowRoles();
+    const presets = config.presets || [];
+    // Inject the role resolver so SmartBridge.resolveSync() can read role
+    // configs without lazy-importing this module (avoids the circular
+    // require that the old router.mjs had).
+    setRoleResolver(getRoleConfig);
+    const sb = initSmartBridge({ userRoles, presets });
+    // Inject into session manager so createSession() can resolve profiles
+    // synchronously (no lazy-import race).
+    setSmartBridge(sb);
+    // Keep Smart Bridge in sync with user-workflow.json edits.
+    watchUserWorkflow((nextRoles) => {
+      try { getSmartBridge().updateUserRoles(nextRoles); } catch {}
+    });
+  } catch (e) {
+    process.stderr.write(`[smart-bridge] init skipped: ${e.message}\n`);
+  }
+  watchAgentConfig();
+}
+
+/**
+ * Handle a tool call from the unified server.
+ * @param {string} name - tool name
+ * @param {object} args - tool arguments
+ * @param {{ notifyFn?: (text: string) => void, elicitFn?: (opts: object) => Promise<object> }} [opts]
+ */
+export async function handleToolCall(name, args, opts = {}) {
+  const _baseNotifyFn = typeof opts.notifyFn === 'function' ? opts.notifyFn : null;
+  // Daemon routing: tag every bridge notification with the dispatching MCP
+  // session id so the daemon router delivers detached-worker results back to
+  // THIS terminal instead of the Lead connection. No-op outside the daemon
+  // (routingSessionId undefined → meta unchanged → router falls back to Lead).
+  const _routingSessionId = typeof opts.routingSessionId === 'string' && opts.routingSessionId ? opts.routingSessionId : null;
+  const _clientHostPid = Number(opts.clientHostPid) || null;
+  const notifyFn = _baseNotifyFn
+    ? (text, extraMeta) => {
+        const patch = {};
+        if (_routingSessionId) patch.caller_session_id = _routingSessionId;
+        if (_clientHostPid > 0) patch.client_host_pid = String(_clientHostPid);
+        const merged = { ...(extraMeta || {}), ...patch };
+        // CC channel schema requires meta to be Record<string,string> (channelNotification.ts);
+        // coerce every value so a non-string (boolean/number) can't fail zod and silently drop the notify.
+        const meta = {};
+        for (const [k, v] of Object.entries(merged)) {
+          if (v === undefined || v === null) continue;
+          // silent_to_agent is an internal routing flag the daemon router and
+          // agentNotify consume (=== true) BEFORE the CC zod boundary; keep it
+          // boolean so those checks fire. It never reaches CC — silent notifies
+          // are dropped or Discord-forwarded pre-CC.
+          meta[k] = k === 'silent_to_agent' ? (v === true || v === 'true') : String(v);
+        }
+        return _baseNotifyFn(text, Object.keys(meta).length ? meta : undefined);
+      }
+    : null;
+  const requestSignal = opts.requestSignal instanceof AbortSignal ? opts.requestSignal : null;
+  const callerSessionId = typeof opts.callerSessionId === 'string' && opts.callerSessionId ? opts.callerSessionId : null;
+  const callerCwd = typeof opts.callerCwd === 'string' && opts.callerCwd ? opts.callerCwd : null;
+  await awaitBootReady(2000);
+  // Idempotent fallback — server.mjs populates the registry at boot via
+  // loadModule('agent').then(...), but if eager init failed (missing deps,
+  // file error), the first tool call still restores it here. Re-registration
+  // is safe: setInternalToolsProvider replaces the executor/tools refs.
+  if (typeof opts.toolExecutor === 'function' && Array.isArray(opts.internalTools)) {
+    setInternalToolsProvider({
+      executor: opts.toolExecutor,
+      tools: opts.internalTools,
+    });
+  }
+
+  try {
+    switch (name) {
+      case 'list_models': {
+        const cfg = loadConfig();
+        const presets = listPresets(cfg);
+        const current = getDefaultPreset(cfg);
+        if (presets.length === 0) return ok('No presets configured.');
+        const currentLabel = current ? `${current.model}${current.effort ? ' · ' + current.effort : ''}${current.fast ? ' · fast' : ''}` : 'none';
+        // list_models is read-only; default-preset changes go through
+        // mixdog-config.json or the config UI, not interactive elicit.
+        const lines = presets.map((p, i) => {
+          const parts = [p.name, p.model];
+          if (p.effort) parts.push(p.effort);
+          if (p.fast) parts.push('fast');
+          const mark = current && p.name === current.name ? '  ← active' : '';
+          return `[${i}] ${parts.join(' · ')}${mark}`;
+        });
+        return ok({ current: currentLabel, presets: lines });
+      }
+
+      case 'get_workflows': {
+        const workflows = listWorkflows();
+        return ok({ workflows });
+      }
+
+      case 'get_workflow': {
+        if (!args.name) return fail('name is required');
+        const workflow = getWorkflow(args.name);
+        if (!workflow) return fail('workflow not found');
+        return ok(workflow);
+      }
+
+      case 'set_prompt': {
+        let content = args.content;
+        if (!content && args.file) {
+          try {
+            content = await readFile(args.file, 'utf-8');
+          } catch (e) {
+            return fail(`Cannot read file: ${e.message}`);
+          }
+        }
+        if (!content) return fail('content or file is required');
+        const key = args.key || `p${++_promptSeq}`;
+        _promptStore.set(key, content);
+        return ok(`Stored as '${key}' (${content.length} chars)`);
+      }
+
+      case 'bridge': {
+        // Unified worker session control. `type` selects the action; default
+        // 'spawn' preserves the legacy detached-dispatch behavior so callers
+        // that pass only role+prompt (channels/index.mjs, webhook.mjs) keep
+        // working unchanged.
+        let bridgeType = typeof args.type === 'string' && args.type ? args.type : 'spawn';
+        // True when a cold `send` was flipped to `spawn` (fresh session, no
+        // transcript carry-over). Surfaced as `respawned: true` on the spawn
+        // immediate-return payload; live `send` resumes use `respawned: false`.
+        let _bridgeColdRespawn = false;
+
+        // Cold-tag respawn: a `type=send` whose tag no longer resolves to a
+        // live session (reaped after the 1h window, or never spawned) but
+        // whose role is known (args.role or the session-scoped tag→role map)
+        // should respawn FRESH rather than error — the prompt cache is cold
+        // anyway, so a new session is the correct outcome. Flip to the spawn
+        // path (which re-allocates args.tag + args.role and folds args.message
+        // into the prompt) and carry the requested tag forward so the new
+        // session registers under the same name. Without a recoverable role we
+        // leave bridgeType as 'send' and let the send handler emit its clear
+        // "include a role to respawn" error.
+        if (bridgeType === 'send') {
+          const _sendTarget = args.tag || args.sessionId;
+          const _sendTagKey = (typeof args.tag === 'string' && args.tag.trim())
+            ? args.tag.trim()
+            : (typeof _sendTarget === 'string' && !_sendTarget.startsWith('sess_') ? _sendTarget.trim() : null);
+          const _recoveredRole = args.role
+            || (_sendTagKey ? _tagRoleRegistry.get(_sendTagKey) : null)
+            || null;
+          // A raw `sess_...` id only counts as resolved when it maps to a LIVE
+          // session — a reaped/closed id must fall through to the respawn
+          // branch (role recoverable) rather than being launched against a dead
+          // session (#5).
+          const _resolved = _sendTarget
+            ? (_resolveBridgeTag(_sendTarget) || (typeof _sendTarget === 'string' && _sendTarget.startsWith('sess_') && _isLiveSession(_sendTarget) ? _sendTarget : null))
+            : null;
+          if (_sendTarget && !_resolved && _recoveredRole) {
+            if (args.tag == null && typeof _sendTarget === 'string' && !_sendTarget.startsWith('sess_')) {
+              args = { ...args, tag: _sendTarget };
+            }
+            if (!args.role) args = { ...args, role: _recoveredRole };
+            // Restore the original spawn's cwd so a cold respawn does NOT fall
+            // back to the daemon launch dir (plugin cache). Explicit args.cwd
+            // still wins; this only fills the gap a reaped session left behind.
+            if (args.cwd == null && _sendTagKey) {
+              const _recoveredCwd = _tagCwdRegistry.get(_sendTagKey);
+              if (_recoveredCwd) args = { ...args, cwd: _recoveredCwd };
+            }
+            bridgeType = 'spawn';
+            _bridgeColdRespawn = true;
+          }
+        }
+
+        if (bridgeType === 'list') {
+          return ok(_bridgeListSessions({
+            role: args.role,
+            status: args.status,
+            brief: args.brief,
+            includeClosed: args.includeClosed,
+          }));
+        }
+
+        if (bridgeType === 'close') {
+          const target = args.tag || args.sessionId;
+          if (!target) return fail('bridge close: tag (or sess_ id) is required');
+          const sessionId = _resolveBridgeTag(target) || (target.startsWith('sess_') ? target : null);
+          if (!sessionId) {
+            const _coldTag = (typeof args.tag === 'string' && args.tag.trim())
+              ? args.tag.trim()
+              : (typeof target === 'string' && !target.startsWith('sess_') ? String(target).trim() : null);
+            if (_coldTag && _tagRoleRegistry.has(_coldTag)) {
+              try { _tagSessionRegistry.delete(_coldTag); } catch {}
+              try { _tagRoleRegistry.delete(_coldTag); } catch {}
+              try { _tagCwdRegistry.delete(_coldTag); } catch {}
+              return ok({ closed: true, forgotten: true, tag: _coldTag, sessionId: null });
+            }
+            return fail(`bridge close: tag "${target}" does not map to a live session`);
+          }
+          const res = _bridgeCloseSession(sessionId);
+          // Cancel any pending terminal reap — the session is being closed
+          // explicitly now, so the deferred hide/tag-reclaim timer is moot.
+          _cancelBridgeReap(sessionId);
+          // Drop the tag binding so the name can be reused for a fresh spawn.
+          const tag = _tagForSessionId(sessionId) || (args.tag && _tagSessionRegistry.get(args.tag) === sessionId ? args.tag : null);
+          if (tag) {
+            try { _tagSessionRegistry.delete(tag); } catch {}
+            try { _tagRoleRegistry.delete(tag); } catch {}
+            try { _tagCwdRegistry.delete(tag); } catch {}
+          }
+          return ok({ ...res, tag: tag || null });
+        }
+
+        if (bridgeType === 'send') {
+          const target = args.tag || args.sessionId;
+          if (!target) return fail('bridge send: tag (or sess_ id) is required');
+          const message = args.message || args.prompt;
+          if (!message) return fail('bridge send: message is required');
+          // A raw `sess_...` id resolves only if it points at a LIVE session;
+          // a reaped/closed id is treated as unresolved so it cannot launch an
+          // async askSession against a dead session (#5). With no role to
+          // respawn (the role case was already flipped to spawn above), this
+          // falls into the clear "include a role to respawn" error below.
+          const sessionId = _resolveBridgeTag(target) || (target.startsWith('sess_') && _isLiveSession(target) ? target : null);
+          // A cold tag carrying a role was already flipped to the spawn path
+          // above, so reaching here means no role was supplied — guide the
+          // caller to respawn fresh.
+          if (!sessionId) return fail(`bridge send: tag "${target}" not found (may have been reaped after 1h idle) — include a role to respawn fresh`);
+          // Busy worker → QUEUE, don't reject (Claude Code pendingMessages
+          // pattern). The tag is published BEFORE the worker enters askSession
+          // (spawn) and re-published on each retry rebind, so a `send` can land
+          // while the startup / retry turn is still in flight. Rather than
+          // making it the first user message (jumping ahead of the original
+          // prompt) or rejecting it, enqueue it onto the per-session pending
+          // queue; askSession drains the queue after the in-flight turn and
+          // runs queued messages — in order — as follow-up turns. This both
+          // removes the startup race (queued send runs AFTER the original
+          // prompt) and lets a mid-turn send land without a retry. We treat a
+          // live, un-aborted controller OR a non-terminal status as "busy".
+          {
+            const _rt = getSessionRuntime(sessionId);
+            const _inFlight = !!(_rt && _rt.controller && _rt.controller.signal && !_rt.controller.signal.aborted);
+            let _sess = null;
+            try { _sess = getSession(sessionId); } catch { _sess = null; }
+            const _activeStates = new Set(['connecting', 'requesting', 'streaming', 'tool_running', 'running', 'cancelling']);
+            // #2 race close: prefer the RUNTIME terminal stage over a stale
+            // persisted 'running'. Spawn keeps persisted status 'running' until
+            // AFTER the completion emit (updateSessionStatus(idle) runs only
+            // after the await _bridgeEmitDelivered, OUTSIDE askSession). A send
+            // landing in that post-askSession / pre-idle gap would see persisted
+            // 'running' and wrongly ENQUEUE onto a queue nothing drains (the
+            // turn already returned past askSession's drain point) — stranded.
+            // The runtime stage flips to a terminal value (done/idle/error) the
+            // instant the turn completes (markSessionDone), so when a runtime
+            // entry exists it is authoritative for in-flight detection: enqueue
+            // ONLY when the runtime stage is genuinely active. Fall back to the
+            // persisted status only when there is no runtime entry at all (a
+            // truly live ask always creates one via markSessionAskStart).
+            const _runtimeStage = _rt?.stage || null;
+            let _busy;
+            if (_inFlight) {
+              _busy = true;
+            } else if (_runtimeStage) {
+              _busy = _activeStates.has(_runtimeStage);
+            } else {
+              const _status = _sess?.status || null;
+              _busy = !!(_status && _activeStates.has(_status));
+            }
+            if (_busy) {
+              const _depth = enqueuePendingMessage(sessionId, message);
+              return ok({
+                queued: true,
+                tag: _tagForSessionId(sessionId) || (typeof args.tag === 'string' ? args.tag : null) || null,
+                sessionId,
+                queueDepth: _depth,
+                respawned: false,
+              });
+            }
+          }
+          // Resume the conversation — askSession replays session.messages from
+          // the {id}.json transcript, so a follow-up continues where the
+          // detached worker left off. Like spawn, a detached resume does NOT
+          // bail on an already-aborted request signal — it runs to completion and
+          // delivers via notifyFn (abort is logging-only, wired below).
+          // Cancel the pending 1h terminal reap (scheduled when the spawn's
+          // initial turn completed) so this just-resumed / in-flight session is
+          // not hidden + tag-reclaimed mid-resume. Re-armed after the resumed
+          // turn settles below.
+          _cancelBridgeReap(sessionId);
+          // Keep the tag bound to the live session across the resume — if the
+          // reap had already raced ahead and dropped the binding, restore it so
+          // the session stays addressable by tag afterward.
+          const _liveTag = (typeof args.tag === 'string' && args.tag.trim()) ? args.tag.trim() : _tagForSessionId(sessionId);
+          if (_liveTag) { try { _tagSessionRegistry.set(_liveTag, sessionId); } catch {} }
+          // Detached resume — mirror the spawn dispatch path. The guard, the
+          // reap-cancel and the tag rebind above all run synchronously BEFORE
+          // we hand off; from here we generate a jobId and return IMMEDIATELY
+          // ({ jobId, sessionId, tag, detached:true }) without blocking on
+          // askSession. The resume runs inside the async IIFE below and its
+          // reply is delivered via notifyFn using the SAME shape spawn's
+          // completion emit uses (`${modelTag}[${role}] ${answer}`), so the
+          // Lead + channel see it like a SPAWN-OK dispatch result instead of a
+          // synchronous return value.
+          const sendJobId = `bridge_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+          const _sendSession = (() => { try { return getSession(sessionId); } catch { return null; } })();
+          const sendRole = _sendSession?.role || 'worker';
+          // Prefer the live bridge tag for completion labels; fall back through
+          // the persisted session tag, then role only if the tag is missing.
+          const sendTag = _liveTag || _tagForSessionId(sessionId) || _sendSession?.bridgeTag || sendRole;
+          const sendModelTag = _bridgeModelTag({ model: _sendSession?.model });
+          const emit = notifyFn || (() => {});
+          addPending(process.env.CLAUDE_PLUGIN_DATA, sendJobId, 'bridge', [sendTag || sendRole], _routingSessionId, _clientHostPid);
+          // Detached resume MUST outlive the originating MCP request — mirror
+          // the spawn dispatch contract: do NOT close/kill the session on
+          // request abort (#1). A request-abort that tore down the resumed
+          // session here used to flip a long resume to silently-dropped /
+          // cancelled the moment the MCP request lifecycle ended. Only a
+          // logging listener is installed; operators stop the work explicitly
+          // via bridge type=close.
+          const _detachSendAbortLog = _wireRequestAbortLog(requestSignal, {
+            sessionId,
+            role: sendRole,
+            jobId: sendJobId,
+          });
+          (async () => {
+            let _delivered = false;
+            try {
+              const result = await askSession(sessionId, message, args.context || null);
+              let content;
+              if (result && typeof result.content === 'string' && result.content.length > 0) {
+                content = result.content;
+              } else {
+                content = _renderEmptyContentDiagnostic(result, _sendSession);
+              }
+              const _extractedAnswer = _resolveFinalAnswer(content);
+              try {
+                const _tail = setPendingResult(process.env.CLAUDE_PLUGIN_DATA, sendJobId, 'bridge', [sendTag || sendRole], content, false, _routingSessionId, _clientHostPid);
+                if (_tail && typeof _tail.then === 'function') await _tail;
+              } catch (e) { try { process.stderr.write(`[bridge] setPendingResult (send success) failed: job=${sendJobId} role=${sendRole} ${e?.message ?? e}\n`); } catch {} }
+              _delivered = (await _bridgeEmitDelivered(
+                emit,
+                `${sendModelTag}[${sendTag}] ${_extractedAnswer}`,
+                { pathLabel: 'send success path', jobId: sendJobId, sessionId, role: sendRole },
+              )) || _delivered;
+            } catch (err) {
+              if (err instanceof SessionClosedError) {
+                // Preserve SessionClosedError handling — emit a cancellation
+                // notice only for reasons that warrant one (mirrors spawn).
+                // Label by tag (bridgeTag||role), matching the spawn cancel
+                // path (#4).
+                let reason = err.reason || null;
+                if (!reason && typeof err.message === 'string') {
+                  const m = err.message.match(/reason=([\w-]+)/);
+                  if (m) reason = m[1];
+                }
+                if (shouldEmitBridgeCancellation(reason)) {
+                  _delivered = (await _bridgeEmitDelivered(
+                    emit,
+                    reason ? `${sendTag} cancelled (reason=${reason})` : `${sendTag} cancelled`,
+                    { pathLabel: 'send cancel path', jobId: sendJobId, sessionId, role: sendRole, meta: _bridgeDispatchMeta(sendJobId, { error: true }) },
+                  )) || _delivered;
+                } else {
+                  _delivered = true;
+                }
+              } else {
+                const _errBody = `${sendTag} error: ${errText(err)}`;
+                try {
+                  const _tail = setPendingResult(process.env.CLAUDE_PLUGIN_DATA, sendJobId, 'bridge', [sendTag || sendRole], _errBody, true, _routingSessionId, _clientHostPid);
+                  if (_tail && typeof _tail.then === 'function') await _tail;
+                } catch (e) { try { process.stderr.write(`[bridge] setPendingResult (send error) failed: job=${sendJobId} role=${sendRole} ${e?.message ?? e}\n`); } catch {} }
+                // Error label by tag (bridgeTag||role) to match the spawn error
+                // path (#4).
+                _delivered = (await _bridgeEmitDelivered(
+                  emit,
+                  _errBody,
+                  { pathLabel: 'send error path', jobId: sendJobId, sessionId, role: sendRole, meta: _bridgeDispatchMeta(sendJobId, { error: true }) },
+                )) || _delivered;
+              }
+            } finally {
+              try { _detachSendAbortLog(); } catch { /* ignore */ }
+              if (_delivered) {
+                try { removePending(process.env.CLAUDE_PLUGIN_DATA, sendJobId); } catch {}
+              } else {
+                try { process.stderr.write(`[bridge] keeping pending record (send emit not delivered): job=${sendJobId} session=${sessionId} role=${sendRole}\n`); } catch {}
+              }
+              // Re-arm the deferred reap on BOTH success and failure (#2 fix):
+              // send() cancelled the pending reap before resuming, so a failed
+              // resumed turn would otherwise leave the idle/error session never
+              // terminally reaped. _scheduleBridgeReap cancels any prior timer
+              // so this is idempotent. Keep the tag bound across the resume.
+              // The detached resume outlives the request (no close-on-abort),
+              // so always re-arm.
+              {
+                if (_liveTag) { try { _tagSessionRegistry.set(_liveTag, sessionId); } catch {} }
+                try { _scheduleBridgeReap(sessionId); } catch { /* ignore */ }
+              }
+            }
+          })().catch(async (err) => {
+            try { process.stderr.write(`[bridge] detached send runner unhandled: session=${sessionId} role=${sendRole} job=${sendJobId} ${err instanceof Error ? (err.stack || err.message) : String(err)}\n`); } catch {}
+            const _crashDelivered = await _bridgeEmitDelivered(
+              emit,
+              `${sendTag} crash: ${errText(err)}`,
+              { pathLabel: 'send crash path', jobId: sendJobId, sessionId, role: sendRole, meta: _bridgeDispatchMeta(sendJobId, { error: true }) },
+            );
+            if (_crashDelivered) {
+              try { removePending(process.env.CLAUDE_PLUGIN_DATA, sendJobId); } catch {}
+            } else {
+              try { process.stderr.write(`[bridge] keeping pending record (send crash emit not delivered): job=${sendJobId} session=${sessionId} role=${sendRole}\n`); } catch {}
+            }
+          });
+
+          return ok({
+            jobId: sendJobId,
+            sessionId,
+            tag: _tagForSessionId(sessionId) || _liveTag || null,
+            detached: true,
+            respawned: false,
+          });
+        }
+
+        if (bridgeType !== 'spawn') {
+          return fail(`bridge: unknown type "${bridgeType}" (expected spawn|send|close|list)`);
+        }
+
+        // --- spawn (default): dispatch a detached worker ---
+        // Enforce exactly-one-of: prompt | file | ref. Schema is the first
+        // gate; _resolveBridgePrompt is the second defence for clients that
+        // bypass JSON Schema validation. `message` is the unified alias for
+        // `prompt` on spawn — fold it in before resolution. Resolve the bridge
+        // worker's cwd BEFORE reading args.file so a relative path is resolved
+        // against the worker's effective workspace (args.cwd > callerCwd), not
+        // the agent host process cwd.
+        if (!args.role) return fail('role is required');
+        // dev-sync recycle barrier: if dev-sync has flagged THIS daemon
+        // (server_pid) for a forced restart, the in-band kill is delayed and
+        // the daemon keeps serving for the kill-delay + respawn window.
+        // Spawning here would bind the worker to about-to-die, stale
+        // code/schema daemon (the stale-schema-after-restart incident).
+        // Fail fast with a retryable message so the caller's next call
+        // reconnects to the fresh daemon instead.
+        if (isCurrentDaemonDoomed()) {
+          return fail('bridge spawn deferred: this daemon (server_pid) is being recycled by dev-sync — retry; the next call reconnects to the fresh daemon');
+        }
+        if (args.message != null && args.prompt == null) args = { ...args, prompt: args.message };
+        // Allocate the tag up front so a duplicate-live-tag request fails fast
+        // before any session is created.
+        const _tagAlloc = _allocateBridgeTag(args.tag, args.role);
+        if (_tagAlloc.error) return fail(_tagAlloc.error);
+        const bridgeTag = _tagAlloc.tag;
+        const { _rawBridgeCwd, _safeBridgeCwd } = _buildBridgeCwds(args, callerCwd);
+        const _promptResolution = await _resolveBridgePrompt(args, _rawBridgeCwd);
+        if (_promptResolution.error) return fail(_promptResolution.error);
+        let prompt = _promptResolution.prompt;
+
+        // Bench escape hatch — when both provider and model are supplied,
+        // build an ad-hoc preset on the fly and bypass mixdog-config.json.
+        // Role still drives BP2 catalog scoping (unknown role names fall back
+        // to the legacy all-in-one catalog inside loadScopedRoleCatalog).
+        // systemPrompt is appended as a prefix to prompt so the same dispatch
+        // path can carry caller-injected guidance without changing the
+        // session-builder schema.
+        const config = loadConfig();
+        const _presetResolution = _resolveBridgePreset(args, config);
+        if (_presetResolution.error) return fail(_presetResolution.error);
+        const preset = _presetResolution.preset;
+        const presetName = _presetResolution.presetName;
+        const _roleConfig = _presetResolution._roleConfig;
+        if (_presetResolution.promptPrefix) {
+          prompt = _presetResolution.promptPrefix + prompt;
+        }
+
+        const role = args.role;
+        const effectiveLane = 'bridge';
+        const runtimeSpec = resolveRuntimeSpec(preset, {
+          lane: effectiveLane,
+          agentId: role,
+        });
+
+        // Stateless ephemeral session — created fresh per call (v0.6.97+).
+        // No pool, no resume, no reset. Provider-level prefix cache still
+        // hits because cache is content-keyed, not session-keyed. Shared
+        // with the Smart Bridge path via session-builder so role/preset
+        // telemetry stays bit-identical in bridge-trace.jsonl.
+        // P1 fix: cwd silent-swap surfacing. When _safeCwdForSpawn substitutes
+        // process.cwd() for a non-ASCII Windows cwd, the agent has no way to
+        // know the authoritative working directory and may resolve relative
+        // paths into the wrong tree. Inject a header into the prompt so the
+        // worker uses absolute paths under the originally-requested cwd.
+        // R3 Gap 3: clamp forwarded permissionMode against the parent Lead session
+        // so a bridge worker can never become MORE permissive than its caller.
+        const _requestedPermissionMode = args.permission_mode || args.permissionMode || undefined;
+        let _parentPermissionMode = null;
+        if (callerSessionId) {
+          try { _parentPermissionMode = getSession(callerSessionId)?.permissionMode || null; }
+          catch (e) {
+            // Fail closed: an unreadable parent must clamp the worker to the most
+            // restrictive mode ('plan'), not silently pass as a default parent.
+            try { process.stderr.write(`[bridge] parent permission lookup failed for ${callerSessionId}: ${e?.message ?? e}\n`); } catch {}
+            _parentPermissionMode = 'plan';
+          }
+        }
+        const _permissionMode = _clampBridgePermissionMode(_requestedPermissionMode, _parentPermissionMode, args.role);
+        prompt = _applyBridgeCwdHeaders(prompt, _rawBridgeCwd, _safeBridgeCwd);
+        const { session, effectiveCwd } = prepareBridgeSession({
+          role,
+          presetName,
+          preset,
+          runtimeSpec,
+          cwd: _safeBridgeCwd,
+          sourceType: 'lead',
+          sourceName: role,
+          parentSessionId: callerSessionId,
+          permissionMode: _permissionMode,
+          cacheKeyOverride: args.cacheKey || undefined,
+          permission: _roleConfig?.permission || undefined,
+          // Persist the bridge tag on the session JSON (sync save inside
+          // createSession lands it BEFORE the heartbeat publish below) so the
+          // forked statusline process + aggregator can read s.bridgeTag.
+          bridgeTag,
+          clientHostPid: _clientHostPid || undefined,
+        });
+
+        // workerCwd precedence: explicit Lead intent (effectiveCwd) > the
+        // dispatching session's cwd (callerCwd) > the ambient override/user cwd
+        // (pwd()). callerCwd sits ahead of pwd() so a worker never silently
+        // inherits the daemon launch dir (plugin cache) when no explicit cwd was
+        // given — pwd() in the daemon resolves to process.cwd() == plugin root.
+        let workerCwd = effectiveCwd || callerCwd || pwd();
+
+        const jobId = `bridge_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+        // Opt-in git-worktree isolation (args.isolation === 'worktree'): run the
+        // worker in a dedicated worktree + branch so parallel workers can edit
+        // the same files without clobbering each other's working tree. Resolved
+        // BEFORE prewarm so the code-graph cache warms against the worktree path.
+        // Best-effort — any git failure falls back to the plain workerCwd. The
+        // handle is captured for teardown in the IIFE finally block.
+        // Pre-isolation cwd: the real workerCwd before any worktree swap. The
+        // worktree path is per-jobId ephemeral and deleted on clean teardown,
+        // so a cold tag-respawn must restore THIS (the real repo cwd), not the
+        // swapped worktree dir which would no longer exist.
+        const _preIsolationWorkerCwd = workerCwd;
+        let _workerWorktree = null;
+        if (args.isolation === 'worktree') {
+          _workerWorktree = _setupWorkerWorktree({ workerCwd, jobId, tag: bridgeTag });
+          if (_workerWorktree) workerCwd = _workerWorktree.worktreePath;
+        }
+        _runBridgePrewarm(workerCwd, args.prefetch);
+        // Brief size soft-warn: cap is ≤150 words per subsystem per rules/lead/00-tool-lead.md.
+        const _briefWordCount = _bridgeBriefWordCount(prompt);
+        if (_briefWordCount > 150) {
+          process.stderr.write(
+            `[brief-size-warn] brief is ${_briefWordCount} words (cap=150) — split into multiple roles\n`
+          );
+        }
+        const modelLabel = preset.model || preset.name;
+        const emit = notifyFn || (() => {});
+        // Persist the in-flight bridge job so a child crash/restart can surface
+        // a loss notification via recoverPending() on next bootstrap instead of
+        // leaving the session permanently stuck at 'running'.
+        addPending(process.env.CLAUDE_PLUGIN_DATA, jobId, 'bridge', [role], _routingSessionId, _clientHostPid);
+        // Synchronous .hb write at dispatch entry (BEFORE the async IIFE) so
+        // the status aggregator surfaces this session immediately. Without
+        // this, the first heartbeat had to wait for the IIFE to spawn and the
+        // first stream delta to land — short / cached bridge-worker calls
+        // (recall / search / explore via dispatchAiWrapped) often completed
+        // before any .hb existed, making them invisible on the statusline.
+        // publishHeartbeat is atomic (tmp + rename) and ≤5s self-throttled,
+        // so the IIFE's own first markSessionStreamDelta naturally collapses
+        // into the same throttle window — no double-write.
+        try { publishSessionHeartbeat(session.id); } catch (e) { process.stderr.write(`[bridge] publishSessionHeartbeat failed: ${e?.message}\n`); }
+        // Public `bridge` is intentionally detached: we return immediately and
+        // keep the session alive until it completes (or is explicitly closed).
+        // Tying requestSignal to session lifetime caused long reviewer runs to
+        // flip to `role cancelled` when the MCP request lifecycle ended before
+        // the detached worker finished. Detached mode therefore does NOT wire
+        // request abort into closeSession(); operators can still stop the work
+        // explicitly through bridge type=close.
+        //
+        // Logging-only listener so operators can correlate the MCP request
+        // abort with a still-running detached worker. Tracked locally so the
+        // IIFE finally block can detach it on normal completion (previously
+        // leaked until GC).
+        const _detachRequestAbortLog = _wireRequestAbortLog(requestSignal, {
+          sessionId: session.id,
+          role,
+          jobId,
+        });
+        const modelTag = _bridgeModelTag(preset);
+
+        // Detached bridge workers do NOT close the session on MCP request
+        // abort — by contract they outlive the originating request. The
+        // logging listener installed above is the only request-lifecycle
+        // tie-in; no closeSession-on-abort wire-up is installed here.
+
+        // Track the active session id across retry attempts (may be replaced
+        // on each retry by a fresh session — the outer `session` binding is
+        // the first attempt; activeSession is updated per attempt and hoisted
+        // outside the IIFE so the .catch() handler can reference it).
+        let activeSession = session;
+        // Track all session IDs created across retry attempts so the finally
+        // block can clean up every _sessionJobRegistry entry, not just the last.
+        const _allRetrySessionIds = new Set([session.id]);
+        // Register initial mapping so bridge type=close can resolve the job's current
+        // session before the IIFE has had a chance to update it.
+        _jobSessionRegistry.set(jobId, activeSession.id);
+        _sessionJobRegistry.set(activeSession.id, jobId);
+        // Bind the tag → current sessionId so `bridge type=send|close tag=<tag>`
+        // can reach this worker. Kept in lockstep with _jobSessionRegistry on
+        // retry-swap (below) so the tag stays stable across retry attempts.
+        _tagSessionRegistry.set(bridgeTag, activeSession.id);
+        if (typeof args.tag === 'string' && args.tag.trim()) {
+          try { _tagRoleRegistry.set(bridgeTag, role); } catch { /* ignore */ }
+          // Capture the resolved cwd so a later cold respawn restores it. Use
+          // the PRE-isolation cwd: a worktree path is per-jobId ephemeral and
+          // removed on clean teardown, so a tag-respawn must start from the
+          // real repo cwd, not a dir that may no longer exist.
+          try { if (_preIsolationWorkerCwd) _tagCwdRegistry.set(bridgeTag, _preIsolationWorkerCwd); } catch { /* ignore */ }
+        }
+        // Close the send busy-guard's startup race: the tag is now resolvable
+        // but the session status is not written 'running' until inside the async
+        // IIFE below (and the runtime entry isn't created until askSession). A
+        // `send` landing in that gap would otherwise see no controller + no
+        // active status and wrongly become the first askSession turn. Mark the
+        // runtime stage 'connecting' synchronously so the guard's active-status
+        // set already catches this window. (in-memory + immediate, unlike the
+        // worker-thread-deferred updateSessionStatus disk write).
+        try { updateSessionStage(activeSession.id, 'connecting'); } catch { /* ignore */ }
+        // Wrap the detached async IIFE in runWithCwdOverride so all builtin tool
+        // calls inside this worker's async context resolve paths against workerCwd
+        // via pwd() — no manual callerCwd propagation through nested calls needed.
+        (async () => runWithCwdOverride(workerCwd, async () => {
+          const t0 = Date.now();
+          let errorMessage = null;
+          let result = null;
+          let lastIteration = 0;
+          let stallWatch = { stop() {}, fired() { return false; } };
+          let _delivered = false;
+          // Worktree-isolation teardown result, computed once on the success
+          // path (so a dirty leftover can be appended to the completion emit)
+          // and otherwise in the finally block. Guarded so it only runs once.
+          let _worktreeTornDown = false;
+          let _worktreeTeardown = null;
+          const _runWorktreeTeardown = () => {
+            if (_worktreeTornDown || !_workerWorktree) return _worktreeTeardown;
+            _worktreeTornDown = true;
+            try { _worktreeTeardown = _teardownWorkerWorktree(_workerWorktree); }
+            catch (e) { try { process.stderr.write(`[bridge] worktree teardown failed: job=${jobId} ${e?.message ?? e}\n`); } catch {} }
+            return _worktreeTeardown;
+          };
+          try {
+            await updateSessionStatus(activeSession.id, 'running');
+            // Bridge Start — silent_to_agent so the "started" lifecycle ping
+            // surfaces on Discord / user terminal but does NOT land in the Lead
+            // agent's context (redundant since Lead already knows it just
+            // dispatched). Done / Error emissions below stay non-silent so the
+            // Lead receives the result / failure.
+            // Best-effort: a synchronous notifyFn throw on this non-critical
+            // lifecycle ping must not abort the bridge work (matches the
+            // completion / error emit pattern wrapped via _bridgeEmitDelivered).
+            try { emit(`${modelTag}${role} started`, { silent_to_agent: true }); } catch (emitErr) {
+              try { process.stderr.write(`[bridge] emit failed (started path): job=${jobId} session=${activeSession.id} role=${role} ${emitErr instanceof Error ? emitErr.message : String(emitErr)}\n`); } catch {}
+            }
+            // Per-session stall watchdog — complements the orchestrator's
+            // stream-watchdog (which fires at 300s/600s on raw stream silence).
+            // This one catches the bridge-specific case where the lead is
+            // waiting on a `worker finished` notification that never arrives:
+            // if the SSE stream is quiet beyond STALL_TIMEOUT_S (default 600s)
+            // and the session isn't in `tool_running`, emit via notifyFn and
+            // abort so the outer catch renders a normal error footer.
+            //
+            // The watchdog is one-shot (self-stops after firing). For
+            // stall-class auto-retry we re-arm a fresh watchdog on each
+            // attempt below, and expose the *current* watchdog to the
+            // retry wrapper via `isStallAbort` so the race-rejector path
+            // (SessionClosedError 'aborted during call' with no closeReason)
+            // is still classified as a stall.
+            const _startStallWatch = () => startBridgeStallWatchdog({
+              sessionId: activeSession.id,
+              // Retry replaces activeSession; the watchdog's flush/hide path
+              // must target the *current* session id, not the original one
+              // captured at construction.
+              getSessionId: () => activeSession.id,
+              getRuntime: () => getSessionRuntime(activeSession.id),
+              getIteration: () => lastIteration,
+              abort: (reason) => {
+                const rt = getSessionRuntime(activeSession.id);
+                rt?.controller?.abort?.(reason);
+                try { closeSession(activeSession.id, String(reason?.message || reason || 'stall-watchdog')); } catch {}
+              },
+              notify: emit,
+              modelTag,
+              role,
+            });
+            stallWatch = _startStallWatch();
+            ({ result } = await runWithDispatchRetry({
+              role,
+              jobId,
+              startAttempt: 0,
+              // Detached bridge worker survives the MCP request lifecycle by
+              // contract; passing requestSignal would let the retry wrapper
+              // abort at attempt boundaries when the originating request ends.
+              externalSignal: null,
+              // Race-rejector path in manager.mjs:1232 surfaces a generic
+              // SessionClosedError('aborted during call', reason=null) — the
+              // structured BridgeStallAbortError marker is lost. Expose the
+              // current watchdog's fired() so runWithDispatchRetry can still
+              // classify that surface as a retryable stall.
+              isStallAbort: () => { try { return stallWatch.fired(); } catch { return false; } },
+              runFn: async (attempt) => {
+                if (attempt > 0) {
+                  // Job-level cancellation tombstone check — bridge type=close
+                  // may have planted this while runWithDispatchRetry was
+                  // sleeping on STALL_RETRY_BACKOFF_MS. If set, surface a
+                  // SessionClosedError(reason=manual) so the outer catch
+                  // takes the silent-cancel path instead of spinning a
+                  // fresh retry session against a job the user already
+                  // killed.
+                  if (_jobCancelledTombstones.has(jobId)) {
+                    throw new SessionClosedError(activeSession.id, 'cancelled before retry (reason=manual)', 'manual');
+                  }
+                  // Fresh session for retry — no message-history carry-over.
+                  try { closeSession(activeSession.id, 'retry-replaced'); } catch {}
+                  const retryBuilt = prepareBridgeSession({
+                    role,
+                    presetName,
+                    preset,
+                    runtimeSpec,
+                    cwd: _safeBridgeCwd,
+                    sourceType: 'lead',
+                    sourceName: role,
+                    parentSessionId: callerSessionId,
+                    permissionMode: _permissionMode,
+                    cacheKeyOverride: args.cacheKey || undefined,
+                    permission: _roleConfig?.permission || undefined,
+                    // Carry the stable bridge tag onto the replacement session
+                    // JSON so statusline/aggregator keep reading it post-swap.
+                    bridgeTag,
+                    clientHostPid: _clientHostPid || undefined,
+                  });
+                  activeSession = retryBuilt.session;
+                  _allRetrySessionIds.add(activeSession.id);
+                  // Keep jobId→sessionId registry current so bridge type=close
+                  // (called by the Lead with the original sessionId, which
+                  // bridge type=close resolves via _sessionJobRegistry) can
+                  // forward the close to the replacement worker.
+                  _jobSessionRegistry.set(jobId, activeSession.id);
+                  _sessionJobRegistry.set(activeSession.id, jobId);
+                  // Keep the tag pointing at the live replacement so a
+                  // concurrent `bridge type=send tag=<tag>` resumes the current
+                  // retry session, not the discarded one. The tag is stable
+                  // across the swap; only the underlying sessionId changes.
+                  _tagSessionRegistry.set(bridgeTag, activeSession.id);
+                  // Same startup-race guard as the initial bind: the rebound
+                  // tag now resolves to the fresh retry session, but its status
+                  // isn't 'running' until the updateSessionStatus below. Mark
+                  // the runtime stage 'connecting' synchronously so a `send`
+                  // arriving in this rebind→running gap is rejected by the
+                  // busy-guard instead of becoming the first askSession turn.
+                  try { updateSessionStage(activeSession.id, 'connecting'); } catch { /* ignore */ }
+                  await updateSessionStatus(activeSession.id, 'running');
+                  // Best-effort: a synchronous notifyFn throw on this non-critical
+                  // retry-attempt ping must not abort the bridge work (matches the
+                  // completion / error emit pattern wrapped via _bridgeEmitDelivered).
+                  try { emit(`${modelTag}${role} retry attempt=${attempt}`, { silent_to_agent: true }); } catch (emitErr) {
+                    try { process.stderr.write(`[bridge] emit failed (retry path): job=${jobId} session=${activeSession.id} role=${role} attempt=${attempt} ${emitErr instanceof Error ? emitErr.message : String(emitErr)}\n`); } catch {}
+                  }
+                  // Re-arm the stall watchdog for the retry attempt. The
+                  // previous watchdog is one-shot — it cleared its interval
+                  // when it fired (or stopped via _api_call_with_interrupt's
+                  // abort), and stays in the fired() state forever. Without
+                  // re-arming, a second stall on the retry attempt would go
+                  // undetected and the retry would hang against the bare
+                  // provider timeout instead of being aborted again.
+                  try { stallWatch.stop(); } catch { /* ignore */ }
+                  stallWatch = _startStallWatch();
+                  // Reset the iteration tracker so stall messages on this
+                  // retry attempt report the current attempt's progress.
+                  // Otherwise the askSession callback (iteration >
+                  // lastIteration) would silently skip early iterations
+                  // whose number is <= the previous attempt's final value.
+                  lastIteration = 0;
+                }
+                return askSession(activeSession.id, prompt, args.context || null, (iteration, _calls) => {
+                  if (typeof iteration === 'number' && iteration > lastIteration) lastIteration = iteration;
+                }, workerCwd, (args.prefetch && typeof args.prefetch === 'object') ? args.prefetch : undefined);
+              },
+            }));
+            // Footer (model/ctx/cache/out/loops/elapsed) dropped per user spec
+            // — caller (Lead) wants core content only. Per-turn usage stats are
+            // still available via session telemetry / bridge type=list.
+            let content;
+            if (result && typeof result.content === 'string' && result.content.length > 0) {
+              content = result.content;
+            } else {
+              content = _renderEmptyContentDiagnostic(result, activeSession);
+            }
+            const _extractedAnswer = _resolveFinalAnswer(content);
+            // Persist the full result BODY before emit so a torn-down
+            // transport / exit-255 between emit and disk-flush can't drop the
+            // answer — recoverPending replays this content instead of the
+            // generic Aborted boilerplate. Await the disk-flush tail; a
+            // persist failure is best-effort and must NOT block the emit.
+            try {
+              const _tail = setPendingResult(process.env.CLAUDE_PLUGIN_DATA, jobId, 'bridge', [role], content, false, _routingSessionId, _clientHostPid);
+              if (_tail && typeof _tail.then === 'function') await _tail;
+            } catch (e) { try { process.stderr.write(`[bridge] setPendingResult (success) failed: job=${jobId} role=${role} ${e?.message ?? e}\n`); } catch {} }
+            // Tear down the isolation worktree before the completion emit so a
+            // dirty (un-merged) leftover can be surfaced to the Lead. No
+            // auto-merge: a dirty worktree is kept and its path + changed-file
+            // count appended to the emit.
+            const _wtResult = _runWorktreeTeardown();
+            const _wtNote = (_wtResult && _wtResult.kept)
+              ? `\n\n⚠ isolation worktree kept (dirty, ${_wtResult.changedFiles} changed file${_wtResult.changedFiles === 1 ? '' : 's'}): ${_wtResult.path} — no auto-merge`
+              : '';
+            _delivered = (await _bridgeEmitDelivered(
+              emit,
+              `${modelTag}[${bridgeTag || role}] ${_extractedAnswer}${_wtNote}`,
+              { pathLabel: 'success path', jobId, sessionId: activeSession.id, role },
+            )) || _delivered;
+            await updateSessionStatus(activeSession.id, 'idle');
+          } catch (err) {
+            errorMessage = errText(err);
+            if (stallWatch.fired()) {
+              // The stall watchdog already attempted a user-facing message
+              // before aborting; whatever error bubbled up here (likely a
+              // SessionClosedError or provider-side abort surface) is just
+              // the unwind. Mark the session as errored and fall through.
+              // Only treat the pending record as delivered when the
+              // watchdog's notify actually landed (delivered()) — an async
+              // notify rejection routes to the fallback addPending and the
+              // pending record must stay replayable on next boot. Older
+              // builds shipping a watchdog without delivered() degrade
+              // safely: treat absence as "delivered" so behaviour matches
+              // the prior contract.
+              const _watchdogDelivered = typeof stallWatch.delivered === 'function'
+                ? (() => { try { return !!stallWatch.delivered(); } catch { return true; } })()
+                : true;
+              if (_watchdogDelivered) _delivered = true;
+              await updateSessionStatus(activeSession.id, 'error');
+            } else if (err instanceof SessionClosedError) {
+              // Prefer the structured enum on the error; fall back to
+              // regex-parsing the message for older call paths that might
+              // have constructed the error without the third arg.
+              let reason = err.reason || null;
+              if (!reason && typeof err.message === 'string') {
+                const m = err.message.match(/reason=([\w-]+)/);
+                if (m) reason = m[1];
+              }
+              if (shouldEmitBridgeCancellation(reason)) {
+                _delivered = (await _bridgeEmitDelivered(
+                  emit,
+                  reason ? `${bridgeTag || role} cancelled (reason=${reason})` : `${bridgeTag || role} cancelled`,
+                  { pathLabel: 'cancel path', jobId, sessionId: activeSession.id, role, meta: _bridgeDispatchMeta(jobId, { error: true }) },
+                )) || _delivered;
+              } else {
+                // Intentionally-silent cancel (manual / request-abort /
+                // retry-replaced / idle-sweep): no notification by design.
+                // Mark delivered so the finally block clears the pending
+                // record — otherwise the next bootstrap would resurface a
+                // bogus "loss notification" for a user-requested cancel.
+                _delivered = true;
+              }
+              // Stop stall watchdog synchronously on close so the timer can't
+              // fire a spurious notify after the session is already closed.
+              try { stallWatch.stop(); } catch { /* ignore */ }
+              // Cancellation isn't an error; flip to idle so the next sweep
+              // pass can reclaim the file instead of leaving a 'running'
+              // zombie until the 24h tombstone window expires.
+              await updateSessionStatus(activeSession.id, 'idle');
+            } else if (err instanceof StreamStalledAbortError) {
+              const info = err.info || {};
+              const header = `⚠ stream stalled — ${info.staleSeconds}s no delta (stage: ${info.stage || 'unknown'})`;
+              // Persist the rendered error BODY before emit so a crash after
+              // the error is computed replays the real error, not boilerplate.
+              try {
+                const _tail = setPendingResult(process.env.CLAUDE_PLUGIN_DATA, jobId, 'bridge', [role], `${role} error: ${header}`, true, _routingSessionId, _clientHostPid);
+                if (_tail && typeof _tail.then === 'function') await _tail;
+              } catch (e) { try { process.stderr.write(`[bridge] setPendingResult (stall) failed: job=${jobId} role=${role} ${e?.message ?? e}\n`); } catch {} }
+              _delivered = (await _bridgeEmitDelivered(
+                emit,
+                `${bridgeTag || role} error: ${header}`,
+                { pathLabel: 'stall path', jobId, sessionId: activeSession.id, role, meta: _bridgeDispatchMeta(jobId, { error: true }) },
+              )) || _delivered;
+              await updateSessionStatus(activeSession.id, 'error');
+            } else {
+              // Persist the error BODY before emit so a crash after the error
+              // is computed replays the real error, not Aborted boilerplate.
+              try {
+                const _tail = setPendingResult(process.env.CLAUDE_PLUGIN_DATA, jobId, 'bridge', [role], `${role} error: ${errorMessage}`, true, _routingSessionId, _clientHostPid);
+                if (_tail && typeof _tail.then === 'function') await _tail;
+              } catch (e) { try { process.stderr.write(`[bridge] setPendingResult (error) failed: job=${jobId} role=${role} ${e?.message ?? e}\n`); } catch {} }
+              _delivered = (await _bridgeEmitDelivered(
+                emit,
+                `${bridgeTag || role} error: ${errorMessage}`,
+                { pathLabel: 'error path', jobId, sessionId: activeSession.id, role, meta: _bridgeDispatchMeta(jobId, { error: true }) },
+              )) || _delivered;
+              await updateSessionStatus(activeSession.id, 'error');
+            }
+          } finally {
+            // Ensure the isolation worktree is torn down on every exit path
+            // (error / cancel / stall). Idempotent: a no-op when the success
+            // path already ran it. A dirty worktree is kept (logged in the
+            // teardown helper); only a clean one is removed + branch deleted.
+            try { _runWorktreeTeardown(); } catch { /* ignore */ }
+            // Do NOT stop stallWatch here unconditionally — stopping it before
+            // the 1h terminal-reap window prevents terminal-stale sessions
+            // from ever being hidden. Instead, schedule a deferred hide so
+            // listSessions() stops returning the completed bridge session after
+            // 1h. stallWatch.stop() is kept for the explicit close path only
+            // (handled inside the watchdog itself on abort).
+            // Schedule via _scheduleBridgeReap so the timer handle is recorded
+            // per-session in _sessionReapTimers — a later `bridge type=send`
+            // resume can then cancel/reschedule it (see send branch) instead of
+            // being reaped (hidden + tag-deleted) mid-resume.
+            try { _scheduleBridgeReap(activeSession.id); } catch { /* ignore */ }
+            // Detach request-abort logging listener — IIFE has settled, the
+            // MCP request has nothing left to log against. Harmless if abort
+            // already fired (listener was registered { once: true }).
+            try { _detachRequestAbortLog(); } catch { /* ignore */ }
+            // Remove persist record only after emit confirmed delivered.
+            // If emit failed (channel down, owner restart), leave the pending
+            // record intact so the supervisor can resurface or retry the job.
+            if (_delivered) {
+              try { removePending(process.env.CLAUDE_PLUGIN_DATA, jobId); } catch {}
+            } else {
+              try { process.stderr.write(`[bridge] keeping pending record (emit not delivered): job=${jobId} session=${activeSession.id} role=${role}\n`); } catch {}
+            }
+            try { _jobSessionRegistry.delete(jobId); } catch {}
+            // Clean up all session IDs registered across retry attempts.
+            try { for (const sid of _allRetrySessionIds) _sessionJobRegistry.delete(sid); } catch {}
+            try { _jobCancelledTombstones.delete(jobId); } catch {}
+          }
+        }))().catch(async (err) => {
+          // Order: emit FIRST, then remove pending only if emit succeeded.
+          // Previously this handler removed the pending record before
+          // attempting the crash emit — if the emit then failed (channel
+          // down, owner restart) the loss notification was silently
+          // dropped and the next bootstrap had no record to resurface.
+          // Keep genuine emit-failure replayable by keeping the pending
+          // record intact when emit throws.
+          const msg = err instanceof Error ? (err.stack || err.message) : String(err);
+          const crashSessionId = activeSession?.id ?? session.id;
+          try {
+            process.stderr.write(`[bridge] detached runner unhandled: session=${crashSessionId} role=${role} job=${jobId} ${msg}\n`);
+          } catch {}
+          // Best-effort isolation-worktree teardown for the crash path (the
+          // inner finally may not have run if the override wrapper threw).
+          // Idempotent at the git level: removing an already-removed worktree
+          // fails harmlessly and is logged by the helper.
+          try { if (_workerWorktree) _teardownWorkerWorktree(_workerWorktree); } catch { /* ignore */ }
+          // Notify via emit so the crash surfaces to the Lead / channel instead
+          // of silently disappearing. Uses the same channel as normal error
+          // emissions so the Lead can act on it.
+          const _crashDelivered = await _bridgeEmitDelivered(
+            emit,
+            `${bridgeTag || role} crash: ${errText(err)}`,
+            { pathLabel: 'crash path', jobId, sessionId: crashSessionId, role, meta: _bridgeDispatchMeta(jobId, { error: true }) },
+          );
+          if (_crashDelivered) {
+            try { removePending(process.env.CLAUDE_PLUGIN_DATA, jobId); } catch {}
+          } else {
+            try { process.stderr.write(`[bridge] keeping pending record (crash emit not delivered): job=${jobId} session=${crashSessionId} role=${role}\n`); } catch {}
+          }
+          try { _jobSessionRegistry.delete(jobId); } catch {}
+          try { for (const sid of _allRetrySessionIds) _sessionJobRegistry.delete(sid); } catch {}
+          try { _tagSessionRegistry.delete(bridgeTag); } catch {}
+          try { for (const sid of _allRetrySessionIds) _cancelBridgeReap(sid); } catch {}
+          try { _jobCancelledTombstones.delete(jobId); } catch {}
+          try { await updateSessionStatus(crashSessionId, 'error'); } catch {}
+          try { closeSession(crashSessionId, 'runner-crash'); } catch {}
+        });
+
+        return ok({
+          jobId,
+          sessionId: activeSession.id,
+          tag: bridgeTag,
+          role,
+          model: modelLabel,
+          detached: true,
+          respawned: !!_bridgeColdRespawn,
+          // Surface brief size to dispatcher (Lead) so over-cap briefs are
+          // visible without needing to inspect bridge stderr.
+          ...(_briefWordCount > 0 ? { briefWords: _briefWordCount } : {}),
+          ...(_briefWordCount > 150
+            ? { briefWarning: `brief is ${_briefWordCount} words (cap=150)` }
+            : {}),
+        });
+      }
+
+      default:
+        return fail(`Unknown tool: ${name}`);
+    }
+  } catch (err) {
+    return fail(err);
+  }
+}
+
+export async function start() { /* noop — standalone mode uses main() */ }
+export async function stop() { await disconnectAll(); }