mixdog 0.7.1

package/src/agent/orchestrator/ai-wrapped-dispatch.mjs

@@ -0,0 +1,1010 @@
+/**
+ * ai-wrapped-dispatch — dispatch hub for `recall` / `search` / `explore`.
+ *
+ * All three MCP tools flagged `aiWrapped: true` in tools.json route here
+ * instead of the direct module handler. Each query spawns its own Pool C
+ * agent session and runs concurrently via Promise.allSettled, so wall-clock
+ * latency is bound by the slowest query rather than the sum. A single query
+ * spawns a single agent, so the per-array cost scales linearly with query
+ * count. Shared Pool B/C cache shards mean only the first concurrent agent
+ * pays the cold-write; peers ride the warm prefix.
+ *
+ * Dispatch completion pushes into the caller's session via the existing
+ * `notifications/claude/channel` bridge. The notify meta carries
+ * `type: 'dispatch_result'` plus an `instruction` string so the Lead
+ * integrates the answer on its next turn automatically.
+ */
+
+import { homedir } from 'os'
+import { resolve as resolvePath, isAbsolute, join, relative, dirname } from 'path'
+import { createHash } from 'crypto'
+import { existsSync, mkdirSync, readFileSync, statSync, readdirSync, unlinkSync, writeFileSync } from 'fs'
+import { loadConfig, getPluginData } from './config.mjs'
+import { fileURLToPath } from 'url'
+import { getHiddenRole } from './internal-roles.mjs'
+import { writeJsonAtomicSync } from '../../shared/atomic-file.mjs'
+import { errText } from '../../shared/err-text.mjs'
+import { resolvePresetName } from './smart-bridge/bridge-llm.mjs'
+import { smartReadTruncate } from './tools/builtin.mjs'
+import { executeBuiltinTool } from './tools/builtin.mjs'
+import { addPending, removePending, setPendingResult } from './dispatch-persist.mjs'
+import { notifyActivity } from './activity-bus.mjs'
+import { stripSoftWarns } from './tool-loop-guard.mjs'
+import { stripAnsi, normalizeWhitespace, dedupRepeatedLines } from './tools/result-compression.mjs'
+import {
+  EXPLORE_OUTPUT_CHAR_CAP,
+  EXPLORE_PER_PIECE_CHAR_CAP,
+  EXPLORE_TRUNCATION_MARKER,
+} from './explore-validator.mjs'
+import { classifyResultKind } from './session/result-classification.mjs'
+import { isUncPath } from './tools/builtin/device-paths.mjs'
+
+// Plugin version — read once at module load from package.json so per-call cost
+// is zero. Included in the query-cache key so cached results are invalidated
+// when the plugin version changes (new prompt templates, tool definitions, etc.).
+// Intentionally retained: query-result disk cache was removed but this constant
+// stays so a future cache re-enable keeps stable invalidation semantics.
+const _PLUGIN_VERSION = (() => {
+  try {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '../../../package.json')
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
+    return String(pkg.version || 'unknown')
+  } catch (err) {
+    throw new Error(`[ai-wrapped-dispatch] package.json read failed: ${err.message}`)
+  }
+})()
+
+// Fan-out deadline — documented runtime envelope.
+// Default 240 s; override via env FANOUT_DEADLINE_S. 240 s balances
+// the slowest bridge role latency against session responsiveness.
+// Applied to both sync and background fan-out paths. After expiry, settled
+// subs are merged as partial; pending subs are aborted.
+const _FANOUT_DEADLINE_MS = (() => {
+  const v = parseInt(process.env.FANOUT_DEADLINE_S, 10)
+  return Number.isFinite(v) && v > 0 ? v * 1000 : 240_000
+})()
+
+// Hard errors that should trigger sibling abort + partial-error escalation.
+// SessionClosedError is excluded — it means the parent itself aborted, not
+// a sub failure.
+function isHardSubError(reason) {
+  if (!reason) return false
+  if (reason?.name === 'SessionClosedError') return false
+  return true
+}
+
+function _roleNameForTool(tool) {
+  const def = getHiddenRole('explorer')
+  if (def && def.invokedBy === tool) return 'explorer'
+  return null
+}
+
+const ROLE_BY_TOOL = Object.freeze({
+  explore: { role: _roleNameForTool('explore'), build: buildExplorerPrompt, label: _roleNameForTool('explore') || 'explorer' },
+})
+
+// Clamp a raw subagent body (or error string) to the per-piece cap
+// BEFORE it gets wrapped with header / separator. Returns the (possibly
+// truncated) string; truncation reuses the existing marker so callers
+// see a consistent signal.
+function clampPiece(raw) {
+  if (typeof raw !== 'string') return raw
+  if (raw.length <= EXPLORE_PER_PIECE_CHAR_CAP) return raw
+  return raw.slice(0, EXPLORE_PER_PIECE_CHAR_CAP) + EXPLORE_TRUNCATION_MARKER
+}
+
+// Build a merged answer with a hard cumulative-size cap. Mirrors the
+// per-mode shape used by the regular merge path (single query returns
+// the raw answer; multi-query prepends `### Query N:` headers and joins
+// with `---`) but stops appending once the running total crosses the
+// cap, then emits a single inline marker. Each piece is also pre-clamped
+// to EXPLORE_PER_PIECE_CHAR_CAP so a single oversized response can't
+// blow up before the running-total check fires.
+// partialInfo: { completed, total, deadlineSecs } | null — appends footer when set.
+function mergeExploreSettled(settled, queries, label, partialInfo) {
+  const isSingle = queries.length === 1
+  if (isSingle) {
+    const r = settled[0]
+    const raw = r.status === 'fulfilled'
+      ? (r.value || '(no response)')
+      : `[${label} error] ${errText(r.reason)}`
+    // Single-query path: per-piece cap == cumulative cap effectively, but
+    // still pre-clamp to keep the post-clamp slice bounded and cheap.
+    const clamped = clampPiece(raw)
+    if (typeof clamped === 'string' && clamped.length > EXPLORE_OUTPUT_CHAR_CAP) {
+      return clamped.slice(0, EXPLORE_OUTPUT_CHAR_CAP) + EXPLORE_TRUNCATION_MARKER
+    }
+    return _appendPartialFooter(clamped, partialInfo)
+  }
+  const parts = []
+  let total = 0
+  let truncated = false
+  let truncatedAtPiece = -1
+  const sep = '\n\n'
+  for (let i = 0; i < settled.length; i++) {
+    const r = settled[i]
+    const header = `## Q${i + 1}: ${String(queries[i] ?? '').replace(/\s+/g, ' ').slice(0, 60)}`
+    const rawBody = r.status === 'fulfilled'
+      ? (r.value || '(no response)')
+      : `[${label} error] ${errText(r.reason)}`
+    // Pre-clamp the body BEFORE template construction so a 400MB rogue
+    // response can't allocate a 400MB+ piece string just to be discarded.
+    const body = clampPiece(rawBody)
+    const piece = `${header}\n${body}`
+    const addLen = (parts.length === 0 ? 0 : sep.length) + piece.length
+    // Running-total guard: stop appending once the next piece would push
+    // us past the cumulative cap. Truncate the trailing piece to the
+    // remaining budget so we still emit something for the boundary query.
+    if (total + addLen > EXPLORE_OUTPUT_CHAR_CAP) {
+      const remaining = EXPLORE_OUTPUT_CHAR_CAP - total - (parts.length === 0 ? 0 : sep.length)
+      if (remaining > 0) {
+        parts.push(piece.slice(0, remaining))
+        total += (parts.length === 1 ? 0 : sep.length) + remaining
+      }
+      truncated = true
+      truncatedAtPiece = i + 1
+      break
+    }
+    parts.push(piece)
+    total += addLen
+  }
+  const merged = parts.join(sep)
+  if (!truncated) return _appendPartialFooter(merged, partialInfo)
+  const note = truncatedAtPiece > 0
+    ? `\n\n[explore: merge truncated at piece ${truncatedAtPiece}/${settled.length}]`
+    : ''
+  return _appendPartialFooter(merged + EXPLORE_TRUNCATION_MARKER + note, partialInfo)
+}
+
+// Append "(M/N ok, dl=Xs)" footer when partialInfo is truthy.
+function _appendPartialFooter(text, partialInfo) {
+  if (!partialInfo) return text
+  const { completed, total, deadlineSecs } = partialInfo
+  return `${text}\n\n(${completed}/${total} ok, dl=${deadlineSecs}s)`
+}
+
+// Preflight: reject explore cwd values that are structurally unbounded
+// roots — fs root, a bare drive root, the home dir, or ~/.claude. This is
+// a path-only gate by design: those roots are never a valid explore scope,
+// and on Windows a probe walk under `path:'/'` returns a misleading 0-entry
+// count, so a count-based check cannot catch them reliably — only the
+// structural path check does.
+//
+// Returns a non-empty error string when rejected, '' when acceptable.
+// Callers MUST abort with an MCP error when non-empty.
+//
+async function checkBroadCwdBlock(resolvedCwd, rawCwdInput) {
+  const display = (typeof rawCwdInput === 'string' && rawCwdInput.trim())
+    ? rawCwdInput.trim()
+    : (resolvedCwd || '')
+  if (!resolvedCwd) return ''
+  // Hard-block system roots and home directory: their glob is unbounded in
+  // practice (50k+ entries) and a probe walk under `path:'/'` on Windows
+  // can return a misleading 0-entry count when the glob handler cannot
+  // resolve the root, letting the spawn proceed. The invariant is
+  // structural: these paths are never a valid explore scope.
+  const norm = String(resolvedCwd).replace(/\\/g, '/').replace(/\/+$/, '')
+  const isUnixRoot = norm === ''
+  const isDriveRoot = /^[A-Za-z]:$/.test(norm)
+  const home = homedir().replace(/\\/g, '/').replace(/\/+$/, '')
+  const isHomeRoot = norm.length > 0 && norm === home
+  const claudeDir = home + '/.claude'
+  const isClaudeDir = norm === claudeDir
+  if (isUnixRoot || isDriveRoot || isHomeRoot || isClaudeDir) {
+    return `Error: explore root too broad: "${display}" is a system root or home directory. Narrow to a specific project subdirectory.`
+  }
+  return ''
+}
+
+// Background dispatch registry. Entries live in-memory for the plugin server
+// process lifetime — the merged answer is auto-pushed via the channel,
+// and the registry is kept around for observability only. Pruned
+// opportunistically to keep the map bounded.
+const _dispatchResults = new Map() // id → { status, role, tool, queries, createdAt, completedAt?, content?, error? }
+const DISPATCH_RESULT_MAX_ENTRIES = 200
+const DISPATCH_RESULT_TTL_MS = 30 * 60_000 // 30 minutes — enough for the Lead to loop back, short enough to not hoard memory
+// R15: hard caps to bound fan-out + background concurrency. Without these,
+// model/prompt-injection abuse can spawn an unbounded number of hidden-role
+// sub-sessions (one per query) or pile up background dispatches faster than
+// they complete, exhausting the plugin server's memory/file-handle budget.
+const MAX_FANOUT_QUERIES = 12
+const MAX_ACTIVE_BG_DISPATCHES = 8
+let _activeBgDispatches = 0
+// (explore query-result cache + disk persistence + inflight coalescing
+//  removed — each sub-query now fans out uncached, matching native Explore)
+
+
+
+
+/* explore cache key builder removed
+    .update(siblingList.map((s) => normalizeQueryForCache(s)).sort().join('\u0001'))
+   removed */
+
+
+
+
+
+
+/* explore inflight coalescing removed
+   removed */
+
+/* explore inflight join/settle removed
+   removed */
+
+// Shared fan-out controller/deadline/merge/error pipeline used by both
+// sync (in-turn merged answer) and background (handle-then-push) paths.
+// The two paths agree on every observable: parent-abort cascade, sub
+// controllers, hard-error escalation + sibling abort, deadline race, and
+// settled-rebuild. Per-path divergence is parameterized:
+//   - `isBackground` controls the deadline-rebuild shape: sync races the
+//     live promise against the immediate-reject ("late winner wins"),
+//     background uses the immediate-reject only (matches the original
+//     bg form byte-for-byte).
+//   - `onHardError()` fires once when the first hard sub-error escalates,
+//     letting the bg caller mutate the dispatch-registry entry to
+//     'partial-error' while the sync caller skips the mutation.
+// Sub-queries run uncached: each fans out to its own bridge role with no
+// result-cache or inflight-coalescing layer (matches native Explore).
+async function _runFanout({ queries, name, resolvedCwd, brief, spec, ctx, makeBridgeLlm, bridgeConfig, isBackground, onHardError }) {
+  // Parent abort → sub controllers link. Resolve parent signal first so an
+  // already-aborted parent cascades into freshly-created sub controllers in
+  // the same synchronous frame.
+  let parentSig = null
+  try {
+    if (ctx?.callerSessionId) {
+      const { getAbortSignalForSession } = await import('./session/abort-lookup.mjs')
+      parentSig = await getAbortSignalForSession(ctx.callerSessionId)
+    }
+  } catch (e) { try { process.stderr.write(`[ai-wrapped-dispatch] swallow: ${e?.message ?? e}\n`); } catch {} }
+
+  const subControllers = queries.map(() => { try { return new AbortController() } catch { return null } })
+
+  let _parentAbortHandler = null
+  if (parentSig) {
+    if (parentSig.aborted) {
+      subControllers.forEach(ac => { try { ac?.abort() } catch {} })
+    } else {
+      _parentAbortHandler = () => {
+        subControllers.forEach(ac => { try { ac?.abort() } catch {} })
+      }
+      parentSig.addEventListener('abort', _parentAbortHandler, { once: true })
+    }
+  }
+
+  // Per-request cancellation (ESC / MCP `notifications/cancelled`) → abort subs.
+  // ctx.requestSignal is the forwarded extra.signal from the CallTool handler.
+  // Unlike parentSig (session-level), it fires when the user cancels THIS
+  // specific tool request. Wiring it into the sub controllers makes ESC
+  // actually stop the explorer fan-out instead of letting it run to
+  // completion. Background path: the MCP request completes on handle return,
+  // so this signal never aborts there — harmless no-op.
+  const requestSig = ctx?.requestSignal || null
+  let _requestAbortHandler = null
+  if (requestSig && requestSig !== parentSig) {
+    if (requestSig.aborted) {
+      subControllers.forEach(ac => { try { ac?.abort() } catch {} })
+    } else {
+      _requestAbortHandler = () => {
+        subControllers.forEach(ac => { try { ac?.abort() } catch {} })
+      }
+      requestSig.addEventListener('abort', _requestAbortHandler, { once: true })
+    }
+  }
+
+  let hardErrorEscalated = false
+  const escapedSettled = []
+
+  const promises = queries.map((q, i) => {
+    const subSignal = subControllers[i]?.signal ?? null
+    // No result cache / inflight coalescing: each sub-query runs its own
+    // bridge role directly, driven by this sub-query's abort controller.
+    const p = (async () => {
+      const llm = makeBridgeLlm({
+        role: spec.role,
+        cwd: resolvedCwd,
+        brief,
+        parentSessionId: ctx?.callerSessionId || null,
+        clientHostPid: ctx?.clientHostPid,
+        parentSignal: subSignal,
+        config: bridgeConfig ?? null,
+      })
+      return llm({ prompt: spec.build(q, resolvedCwd) })
+    })()
+    p.then(
+      (val) => { escapedSettled[i] = { status: 'fulfilled', value: val } },
+      (err) => {
+        escapedSettled[i] = { status: 'rejected', reason: err }
+        if (!hardErrorEscalated && isHardSubError(err)) {
+          hardErrorEscalated = true
+          subControllers.forEach((ac, j) => { if (j !== i) try { ac?.abort() } catch {} })
+          if (typeof onHardError === 'function') onHardError()
+        }
+      },
+    )
+    return p
+  })
+
+  // Deadline timer — race against all subs.
+  let deadlineTimer = null
+  let deadlineFired = false
+  const deadlineMs = _FANOUT_DEADLINE_MS
+  const deadlinePromise = new Promise((resolve) => {
+    deadlineTimer = setTimeout(() => {
+      deadlineFired = true
+      subControllers.forEach(ac => { try { ac?.abort() } catch {} })
+      resolve('__deadline__')
+    }, deadlineMs)
+    if (typeof deadlineTimer?.unref === 'function') deadlineTimer.unref()
+  })
+
+  await Promise.race([Promise.allSettled(promises), deadlinePromise])
+  clearTimeout(deadlineTimer)
+
+  // Rebuild settled from what resolved so far. Background path uses the
+  // immediate-reject form; sync path races the live promise against the
+  // immediate-reject so a late winner can still land.
+  const settled = await Promise.allSettled(
+    promises.map((p, i) => {
+      if (escapedSettled[i] !== undefined) {
+        return escapedSettled[i].status === 'fulfilled'
+          ? Promise.resolve(escapedSettled[i].value)
+          : Promise.reject(escapedSettled[i].reason)
+      }
+      const timeoutP = Promise.resolve(undefined).then(() => Promise.reject(new Error('bridge role timed out (deadline)')))
+      return isBackground ? timeoutP : Promise.race([p, timeoutP])
+    }),
+  )
+
+  // Only genuinely fulfilled results count as 'ok' in the partial
+  // footer. Any rejection — timeout or otherwise — is not ok, since
+  // _appendPartialFooter renders completedCount as the "ok" tally.
+  const completedCount = settled.filter(r => r.status === 'fulfilled').length
+  const partialInfo = deadlineFired
+    ? { completed: completedCount, total: queries.length, deadlineSecs: Math.round(deadlineMs / 1000) }
+    : null
+
+  if (parentSig && _parentAbortHandler) {
+    try { parentSig.removeEventListener('abort', _parentAbortHandler) } catch {}
+  }
+  if (requestSig && _requestAbortHandler) {
+    try { requestSig.removeEventListener('abort', _requestAbortHandler) } catch {}
+  }
+
+  return { settled, partialInfo, hardErrorEscalated }
+}
+
+function _pruneDispatchResults() {
+  if (_dispatchResults.size < DISPATCH_RESULT_MAX_ENTRIES) return
+  const now = Date.now()
+  for (const [id, entry] of _dispatchResults) {
+    const age = now - (entry.completedAt || entry.createdAt || now)
+    if (entry.status !== 'running' && age > DISPATCH_RESULT_TTL_MS) _dispatchResults.delete(id)
+  }
+  if (_dispatchResults.size >= DISPATCH_RESULT_MAX_ENTRIES) {
+    // Still full — evict the oldest regardless of status.
+    const oldest = _dispatchResults.keys().next().value
+    if (oldest) _dispatchResults.delete(oldest)
+  }
+}
+
+export async function dispatchAiWrapped(name, args, ctx) {
+  let rawQuery = args.query
+  // MCP schema-less query field: some clients JSON-stringify arrays when the
+  // inputSchema does not declare an explicit `type`. Parse `'["a","b"]'` back
+  // into a real array so fan-out works whether the caller passed an array
+  // literal or a stringified one. Plain strings (no leading `[`) pass through.
+  if (typeof rawQuery === 'string') {
+    const trimmed = rawQuery.trim()
+    if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+      try {
+        const parsed = JSON.parse(trimmed)
+        if (Array.isArray(parsed)) rawQuery = parsed
+      } catch { /* not valid JSON array — keep as plain string */ }
+    }
+  }
+  if (rawQuery == null) return fail('query is required')
+  let queries = Array.isArray(rawQuery) ? rawQuery.slice() : [rawQuery]
+  if (queries.length === 0) return fail('query cannot be empty')
+  // R15: bound LLM-dispatch fan-out at the call boundary. Truncating here
+  // (before either sync or background path forks) guarantees one call cannot
+  // spawn more than MAX_FANOUT_QUERIES hidden-role sub-sessions via a
+  // hostile/poisoned `query:[...]`. The capped count is surfaced to the
+  // caller via the merged-answer notice below.
+  let _fanoutCapNotice = ''
+  if (queries.length > MAX_FANOUT_QUERIES) {
+    _fanoutCapNotice = `[capped ${queries.length}->${MAX_FANOUT_QUERIES} queries]`
+    queries = queries.slice(0, MAX_FANOUT_QUERIES)
+  }
+
+  const spec = ROLE_BY_TOOL[name]
+  if (!spec) throw new Error(`Unknown aiWrapped tool: ${name}`)
+
+  // recall / search are handled directly in server-main.mjs
+  // _dispatchToolImpl — they no longer reach this dispatcher at all.
+  // Only `explore` (LLM-routed hidden role) flows through here.
+
+  // Recursion break — the tool schema stays full across every session so
+  // that all roles share one cache shard. The counterweight lives here:
+  // when a hidden-role session (explorer / cycle1 / cycle2) calls back
+  // into an aiWrapped dispatcher, we reject the call at runtime. Without
+  // this, `explore` inside an explorer turn would spawn another explorer
+  // session and fan out forever.
+  if (ctx?.callerSessionId) {
+    try {
+      const { loadSession } = await import('./session/store.mjs')
+      const { isHiddenRole } = await import('./internal-roles.mjs')
+      const caller = loadSession(ctx.callerSessionId)
+      if (!caller) {
+        return fail(
+          `"${name}" blocked: caller session "${ctx.callerSessionId}" not found — recursion guard fails closed.`,
+        )
+      }
+      if (isHiddenRole(caller.role)) {
+        return fail(
+          `"${name}" is blocked inside the "${caller.role}" hidden role (recursion break). `
+          + `Use direct read / code_graph (mode:search for a symbol name) / grep / glob for your query.`,
+        )
+      }
+    } catch (e) {
+      return fail(
+        `"${name}" blocked: recursion guard introspection failed (${e?.message || e}). Fail-closed for safety.`,
+      )
+    }
+  }
+
+  const { makeBridgeLlm } = await import('./smart-bridge/bridge-llm.mjs')
+  const bridgeConfig = loadConfig()
+
+  // `brief` (default true) applies a ~3000-token cap to each bridge role
+  // answer before it rides back into the Lead context. Pass `brief:false`
+  // when the caller explicitly wants the uncapped synthesis. See
+  // bridge-llm.mjs::applyBriefCap for the cap shape.
+  const brief = args.brief !== false;
+  const hasExplicitCwdArg = typeof args.cwd === 'string' && args.cwd.trim()
+  const cwdInput = hasExplicitCwdArg
+    ? args.cwd
+    : ctx?.callerCwd
+  // Only `explore` reaches this dispatcher (ROLE_BY_TOOL registers it alone;
+  // any other tool name throws at the spec lookup above).
+  let resolvedCwd
+  try {
+    resolvedCwd = resolveExploreCwd(cwdInput, ctx?.callerCwd, Boolean(hasExplicitCwdArg))
+  } catch (e) {
+    // Fail-loud: explicit cwd resolved outside callerCwd and does not exist
+    // (no silent rebase to callerCwd). The sole call site can surface the
+    // mistake to Lead directly instead of running explore against the
+    // wrong tree.
+    return fail(errText(e))
+  }
+
+  // Hard-block broad cwds for explore before spawning any bridge roles.
+  // V8 string-limit risk: scanning home / ~/.claude / fs-root can blow the
+  // mcp server process. Fail fast here so neither the sync nor background
+  // path ever launches a bridge role against a dangerous root.
+  const _earlyBroadErr = await checkBroadCwdBlock(resolvedCwd, hasExplicitCwdArg ? args.cwd : '')
+  if (_earlyBroadErr) return fail(_earlyBroadErr)
+
+  // Sync by default — the merged bridge role answer lands in-turn as the MCP
+  // tool response, no channel round-trip, no turn fragmentation. Opt into
+  // background=true for heavy multi-angle queries that risk exceeding the
+  // 120s harness-owned MCP request ceiling (the harness severs the request at
+  // that fixed limit); in that case a handle is returned immediately and the
+  // merged answer is pushed via the channel bridge when ready.
+  const background = typeof args.background === 'boolean'
+    ? args.background
+    : false
+
+  if (!background) {
+    // Sync fan-out: shared controller/deadline/cache/merge pipeline runs the
+    // bridge roles; the merged answer lands in-turn.
+    //
+    // Crash-safety net: register a recoverable handle BEFORE running and persist
+    // the merged body on the completion path BEFORE removing the pending entry,
+    // so a transport tear-down landing between persist and remove can't silently
+    // lose a finished answer (recoverPending replays it on next boot). NOTE: a
+    // user cancellation (requestSignal abort, detected below) is the deliberate
+    // exception — it drops the pending entry WITHOUT replay, because a cancelled
+    // dispatch must not resurface later.
+    const _dataDir = process.env.CLAUDE_PLUGIN_DATA
+    const handle = `dispatch_${name}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+    try { addPending(_dataDir, handle, name, queries, ctx?.routingSessionId, ctx?.clientHostPid) } catch {}
+
+    // Cancellation detection. ctx.requestSignal is the forwarded extra.signal
+    // (server-main aiWrapped route) — it fires on an MCP `notifications/cancelled`
+    // for THIS request, i.e. the user pressing ESC (or a harness transport
+    // sever). _runFanout now wires this same signal into the explorer sub
+    // controllers, so when it fires the fan-out is actively aborted rather than
+    // run to completion. We also capture it here as `_severed` so the exits
+    // below drop the pending entry and return in-turn WITHOUT resurrecting a
+    // cancelled result through the dispatch_result channel. The abort may land
+    // mid-fan-out, so register a listener in addition to the synchronous check.
+    const _sig = ctx?.requestSignal
+    let _severed = false
+    const _onSeverAbort = () => { _severed = true }
+    if (_sig) {
+      if (_sig.aborted) _severed = true
+      else _sig.addEventListener('abort', _onSeverAbort, { once: true })
+    }
+
+    try {
+      const { settled, partialInfo, hardErrorEscalated: _hardErrorEscalated } = await _runFanout({
+        queries, name, resolvedCwd, brief, spec, ctx, makeBridgeLlm,
+        bridgeConfig,
+        isBackground: false,
+      })
+
+      // Cancellation exit (ESC / transport sever): requestSignal fired and
+      // _runFanout's requestSignal→subController link already aborted the
+      // explorer subs. A cancelled dispatch must NOT persist for replay or
+      // resurface later through the channel — drop the pending entry and return
+      // in-turn (the return is harmlessly discarded if the transport is dead).
+      if (_severed) {
+        try { removePending(_dataDir, handle) } catch {}
+        return ok('[explore cancelled by user]')
+      }
+
+      // Only `explore` reaches this dispatcher (ROLE_BY_TOOL registers it alone;
+      // any other tool name throws at the spec lookup above).
+      const merged = mergeExploreSettled(settled, queries, spec.label, partialInfo)
+
+      // All-failed detection: every entry rejected. Surface as MCP isError so
+      // caller doesn't merge the failures back into context as if they were
+      // normal results.
+      const allFailed = settled.every(r => r.status === 'rejected')
+
+      // Persist the finished body (success OR all-failed) BEFORE acking — mirror
+      // the background path's persist→ack→remove ordering. Await the disk tail so
+      // a tear-down between persist and remove cannot lose the body. Best-effort:
+      // a persist failure must not block the in-turn answer.
+      const _handleLine = `[explore handle: ${handle}]`
+      const _mergedWithHandle = `${_handleLine}\n${merged}`
+      // Align the PERSISTED body with the RETURNED body: fold in the fan-out cap
+      // notice when present so a restart replay through recoverPending carries
+      // the same `[capped N->M queries]` notice the in-turn return would have
+      // shown — not a silently truncated body.
+      const _syncMerged = _fanoutCapNotice ? `${_fanoutCapNotice}\n${_mergedWithHandle}` : _mergedWithHandle
+      const _syncMergedCapped = capDispatchRetrievalBody(_syncMerged).text
+      const _syncPersistTail = () => Promise.resolve(
+        setPendingResult(_dataDir, handle, name, queries, _syncMerged, !!allFailed, ctx?.routingSessionId, ctx?.clientHostPid),
+      ).catch((e) => { try { process.stderr.write(`[ai-wrapped-dispatch] sync persist failed: ${e?.message ?? e}\n`); } catch {} })
+      const _okCount = settled.filter(r => r.status === 'fulfilled').length
+      const _hardAllFailed = _hardErrorEscalated && !allFailed && _okCount === 0
+      const _awaitSyncPersist = allFailed || _hardAllFailed
+      if (_awaitSyncPersist) {
+        try { await _syncPersistTail() } catch (e) { try { process.stderr.write(`[ai-wrapped-dispatch] sync persist failed: ${e?.message ?? e}\n`); } catch {} }
+      } else {
+        _syncPersistTail()
+      }
+
+      // Hard-error escalation: any hard sub error and not all already covered.
+      if (_hardErrorEscalated && !allFailed) {
+        const hardFailed = settled.filter(r => r.status === 'rejected' && isHardSubError(r.reason)).length
+        if (_okCount === 0) {
+          // All-hard-error exit. A late cancellation (abort landing during the
+          // sync merge) is handled the same as a normal exit: drop the pending
+          // entry and return in-turn — never channel-push a cancelled result.
+          try { removePending(_dataDir, handle) } catch {}
+          return fail(_syncMergedCapped)
+        }
+        // Partial-error: some completed, annotate but don't fail the whole call.
+        process.stderr.write(`[ai-wrapped-dispatch] partial-error: ${hardFailed} hard errors, ${_okCount} ok — escalated\n`)
+      }
+      if (allFailed) {
+        // All-failed exit — drop the pending entry and return in-turn.
+        try { removePending(_dataDir, handle) } catch {}
+        return fail(_syncMergedCapped)
+      }
+      // Normal success exit — pop the finalized pending entry and return in-turn.
+      try { removePending(_dataDir, handle) } catch {}
+      return ok(_syncMergedCapped)
+    } finally {
+      if (_sig) {
+        try { _sig.removeEventListener('abort', _onSeverAbort) } catch {}
+      }
+    }
+  }
+
+  // Background dispatch path. The caller (Lead) gets an immediate handle;
+  // bridge roles stream in the background and the merged answer is pushed
+  // via the channel notification bridge.
+  //
+  // R15: bound background concurrency. Without this, a flood of background
+  // dispatches (one per `background:true` call) accumulates indefinitely —
+  // _pruneDispatchResults only evicts finished results, not admission. Reject
+  // new background dispatches when the in-flight count is at the cap so the
+  // model/caller cannot exhaust the plugin server via prompt-injection abuse.
+  if (_activeBgDispatches >= MAX_ACTIVE_BG_DISPATCHES) {
+    return fail(`dispatch capacity exceeded - retry shortly (active=${_activeBgDispatches}/${MAX_ACTIVE_BG_DISPATCHES})`)
+  }
+  _activeBgDispatches += 1
+  _pruneDispatchResults()
+  const id = `dispatch_${name}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+  _dispatchResults.set(id, {
+    status: 'running',
+    tool: name,
+    role: spec.role,
+    queries,
+    createdAt: Date.now(),
+  })
+  // Persist so a plugin restart mid-dispatch can emit a single Aborted
+  // notification on next bootstrap instead of silently orphaning the handle.
+  addPending(process.env.CLAUDE_PLUGIN_DATA, id, name, queries, ctx?.routingSessionId, ctx?.clientHostPid)
+  // Starting a bridge dispatch counts as session activity — keeps
+  // background tasks suppressed while long-running work is in flight.
+  notifyActivity()
+  // (start banner removed — notifyFn takes no opts so silent_to_agent is
+  //  not available; pushing "X started" to the channel is channel noise.
+  //  The merged result arrives later via pushDispatchResult.)
+  // Wire caller abort: when the caller session aborts (ESC, new prompt),
+  // mark the dispatch handle cancelled so a later result push doesn't echo
+  // a stale answer back to a session that already moved on. Best-effort:
+  // background bridge roles continue running on the bridge, but their result
+  // is suppressed at push time.
+  let _callerAborted = false;
+  try {
+    if (ctx?.callerSessionId) {
+      import('./session/abort-lookup.mjs').then(({ getAbortSignalForSession }) => {
+        Promise.resolve(getAbortSignalForSession(ctx.callerSessionId)).then((sig) => {
+          if (!sig) return;
+          if (sig.aborted) { _callerAborted = true; return; }
+          sig.addEventListener('abort', () => {
+            _callerAborted = true;
+            const entry = _dispatchResults.get(id);
+            if (entry && entry.status === 'running') {
+              entry.status = 'cancelled';
+              entry.completedAt = Date.now();
+            }
+          }, { once: true });
+        }).catch(() => {});
+      }).catch(() => {});
+    }
+  } catch {}
+  // Background fan-out with parent abort cascade + deadline.
+  ;(async () => {
+    // Shared fan-out pipeline. The bg-only hook flips the dispatch-registry
+    // entry to 'partial-error' on the first hard sub error.
+    const { settled, partialInfo: bgPartialInfo } = await _runFanout({
+      queries, name, resolvedCwd, brief, spec, ctx, makeBridgeLlm,
+      bridgeConfig,
+      isBackground: true,
+      onHardError: () => {
+        const bgEntry = _dispatchResults.get(id)
+        if (bgEntry && bgEntry.status === 'running') bgEntry.status = 'partial-error'
+      },
+    })
+
+    // Only `explore` reaches this dispatcher (ROLE_BY_TOOL registers it alone;
+    // any other tool name throws at the spec lookup above).
+    const merged = mergeExploreSettled(settled, queries, spec.label, bgPartialInfo)
+    _pruneDispatchResults()
+    const entry = _dispatchResults.get(id)
+    const allFailed = settled.every(r => r.status === 'rejected')
+    if (entry) {
+      // Preserve partial-error stamped by onHardError; completion must not
+      // overwrite that signal when at least one sub failed hard but others
+      // succeeded. allFailed still escalates to 'error'.
+      entry.status = allFailed
+        ? 'error'
+        : (entry.status === 'partial-error' ? 'partial-error' : 'done')
+      entry.isError = allFailed
+      entry.content = merged
+      entry.completedAt = Date.now()
+    }
+    _activeBgDispatches = Math.max(0, _activeBgDispatches - 1)
+    if (_callerAborted) {
+      // Caller already moved on; suppress notification but persist the
+      // completed body before removing so recoverPending on next boot
+      // re-delivers the actual answer rather than the Aborted boilerplate
+      // (matches the persist→notify→remove order used by pushDispatchResult).
+      const _dataDir = process.env.CLAUDE_PLUGIN_DATA
+      if (_dataDir) {
+        import('./dispatch-persist.mjs').then(({ setPendingResult, removePending: _rm }) =>
+          Promise.resolve(setPendingResult(_dataDir, id, name, queries, merged, !!allFailed, ctx?.routingSessionId, ctx?.clientHostPid))
+            .then(() => _rm(_dataDir, id)),
+        ).catch((e) => { try { process.stderr.write(`[ai-wrapped-dispatch] caller-aborted persist failed: ${e?.message ?? e}\n`); } catch {} })
+      }
+      return
+    }
+    const _bgMerged = _fanoutCapNotice ? `${_fanoutCapNotice}\n${merged}` : merged
+    // pushDispatchResult owns the persist→notify→remove sequence (see
+    // setPendingResult / removePending in dispatch-persist.mjs); do NOT
+    // pre-remove the pending entry here — that would race the persist and
+    // a crash between addPending and notify could lose the result.
+    pushDispatchResult(ctx, id, name, queries, _bgMerged, { error: allFailed })
+  })().catch((err) => {
+    const msg = errText(err)
+    _pruneDispatchResults()
+    const entry = _dispatchResults.get(id)
+    if (entry) {
+      entry.status = 'error'
+      entry.error = msg
+      entry.completedAt = Date.now()
+    }
+    _activeBgDispatches = Math.max(0, _activeBgDispatches - 1)
+    // Same persist+notify-before-remove invariant as the success path —
+    // pushDispatchResult drives removal after the error body is persisted
+    // and notified.
+    pushDispatchResult(ctx, id, name, queries, `[${spec.label} dispatch error] ${msg}`, { error: true })
+  })
+  const queryCount = queries.length === 1 ? `1 query` : `${queries.length} queries`
+  const _startNotice = _fanoutCapNotice ? `${_fanoutCapNotice} ` : ''
+  return ok(`${_startNotice}${name} started — ${queryCount}. Merged answer will be auto-pushed via the channel (handle ${id}).`)
+}
+
+
+function _escapeXml(str) {
+  return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+function buildExplorerPrompt(query, cwd) {
+  // Full isolation: each explorer receives ONLY its own <query>. Peer queries
+  // are never injected, so a weaker model cannot bleed into or re-answer sibling
+  // topics — it never sees them. The descriptive-only contract lives at
+  // system level (rules/bridge/30-explorer.md via collect.mjs): brief-level
+  // constraints alone proved insufficient — haiku still rendered verdicts on
+  // evaluative queries. The trailing one-liner is reinforcement only; small
+  // models weight the instruction after the query over the query body.
+  return `<query>${_escapeXml(query)}</query>\nReminder: describe with file:line evidence; no verdicts, ratings, or recommendations.`
+}
+
+/**
+ * Resolve user-provided cwd: expand `~`, resolve relatives against the
+ * launch workspace. Falls back to null so callers use process.cwd().
+ */
+function resolveCwd(input, baseCwd = process.cwd()) {
+  if (!input || typeof input !== 'string') return null
+  const trimmed = input.trim()
+  if (!trimmed) return null
+  const expanded = trimmed.startsWith('~')
+    ? trimmed.replace(/^~/, homedir())
+    : trimmed
+  const base = (typeof baseCwd === 'string' && baseCwd) ? baseCwd : process.cwd()
+  return isAbsolute(expanded) ? expanded : resolvePath(base, expanded)
+}
+
+function resolveExploreCwd(input, callerCwd, hasExplicitCwdArg = false) {
+  const base = resolveCwd(callerCwd, process.cwd())
+  const resolved = resolveCwd(input, base || process.cwd())
+  // UNC / SMB reject: exploring a network share root auto-authenticates to
+  // the remote host and leaks the current user's NTLM hash. Reject the
+  // resolved cwd before any bridge role can walk it. Mirrors the read/list
+  // path's UNC guard.
+  if (typeof isUncPath === 'function' && isUncPath(resolved)) {
+    throw new Error(
+      `explore cwd "${input}" resolves to a UNC / SMB path ("${resolved}") — network credential leak risk; pass a local absolute path`,
+    )
+  }
+  if (!hasExplicitCwdArg || !base || !resolved) return resolved
+  // Explicit cwd: must point to a real directory regardless of whether it
+  // sits under callerCwd. An under-callerCwd path that doesn't exist is
+  // still almost certainly a typo (e.g. cwd:'missing'); a path outside
+  // callerCwd that does exist is the deliberate redirect branch
+  // (Lead exploring a sibling tree, plugin source, etc.) — both are
+  // accepted only when the directory actually exists.
+  if (_cwdIsExistingDir(resolved)) return resolved
+  // Fail-loud rather than silently rebasing to callerCwd: a non-existent
+  // explicit cwd is almost always a typo and silent rebase would run the
+  // explore against the wrong tree without warning. The single caller in
+  // dispatchAiWrapped catches this and returns it through fail().
+  throw new Error(
+    `explore cwd "${input}" does not exist (resolved to "${resolved}") — pass a valid absolute path or omit cwd to use the launch workspace`,
+  )
+}
+
+function _cwdIsExistingDir(p) {
+  if (!p || typeof p !== 'string') return false
+  let st
+  try { st = statSync(p) } catch { return false }
+  return Boolean(st && st.isDirectory())
+}
+
+function isPathInside(baseCwd, targetCwd) {
+  if (!baseCwd || !targetCwd) return false
+  const rel = relative(resolvePath(baseCwd), resolvePath(targetCwd))
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))
+}
+
+/**
+ * Resolve a short model tag for the given hidden role, mirroring the
+ * `modelTag` format that bridge/worker lifecycle notifications use in
+ * src/agent/index.mjs (e.g. `3-5-sonnet`). Best-effort — returns an
+ * empty string when the preset / config can't be resolved so the header
+ * still renders (falls back to `[{tool}] Done.`).
+ */
+export function resolveAgentModelTag(role) {
+  try {
+    const presetName = resolvePresetName({ role })
+    if (!presetName) return ''
+    const config = loadConfig()
+    const preset = config?.presets?.find((p) => p.id === presetName || p.name === presetName)
+    const raw = preset?.model
+    if (!raw || typeof raw !== 'string') return ''
+    const stripped = raw.startsWith('claude-') ? raw.slice('claude-'.length) : raw
+    return stripped || ''
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * Build the `Done.` header that wraps async-result notifications, mirroring
+ * the Pool B worker completion shape emitted in src/agent/index.mjs:
+ *     [{model-tag}] [{role}] <content>
+ * Dispatch re-uses the same pattern so the user sees a consistent
+ * `Done.` header across bridge worker output and recall/search/explore
+ * dispatch result delivery.
+ *
+ * When the model tag can't be resolved, falls back to `[{tool}] Done.`.
+ * When the tool is empty (shouldn't happen), falls back to `Done.`.
+ */
+export function buildDispatchResultHeader(tool, modelTag) {
+  const toolPart = tool ? `[${tool}] ` : ''
+  const tagPart = modelTag ? `[${modelTag}] ` : ''
+  return `${tagPart}${toolPart}Done.`
+}
+
+function capDispatchRetrievalBody(body) {
+  let bodyStr = typeof body === 'string' ? body : String(body ?? '')
+  bodyStr = stripSoftWarns(bodyStr)
+  bodyStr = stripAnsi(bodyStr)
+  bodyStr = normalizeWhitespace(bodyStr)
+  bodyStr = dedupRepeatedLines(bodyStr)
+  const bodyBytes = Buffer.byteLength(bodyStr, 'utf8')
+  let bodyLines = bodyStr.length === 0 ? 0 : 1
+  for (let i = 0; i < bodyStr.length; i += 1) {
+    if (bodyStr.charCodeAt(i) === 10) bodyLines += 1
+  }
+  const { text, truncated } = smartReadTruncate(bodyStr, bodyLines, bodyBytes)
+  return { text, truncated }
+}
+
+// Spool the full, untruncated dispatch body to disk when the notify body was
+// smart-truncated, mirroring _saveLeadDirectFullOutput in server-main.mjs.
+// Best-effort: a spool failure must never break the notify path, so the caller
+// only appends the pointer line when this returns a path.
+function saveDispatchFullOutput(dataDir, id, rawBody) {
+  try {
+    const dir = resolvePath(dataDir, 'tool-results', 'dispatch')
+    mkdirSync(dir, { recursive: true })
+    const safeId = String(id || 'dispatch').replace(/[^A-Za-z0-9_-]+/g, '_').slice(0, 80) || 'dispatch'
+    const file = resolvePath(dir, `${safeId}.txt`)
+    writeFileSync(file, rawBody, 'utf8')
+    return file
+  } catch {
+    return null
+  }
+}
+
+// Age-based GC for non-per-session tool-results subdirs (`lead-direct/`,
+// `dispatch/`): these accumulate one file per output and are never reopened,
+// so an mtime TTL is the only reliable cleanup signal. Runs once per process
+// boot (see invocation below), mirroring the stale-log sweep in
+// src/channels/index.mjs. 7-day TTL keeps recent forensics while bounding leak.
+const _TOOL_RESULTS_TTL_MS = 7 * 24 * 60 * 60 * 1000
+function _gcToolResultsOnce() {
+  const dataDir = process.env.CLAUDE_PLUGIN_DATA
+  if (!dataDir) return
+  const now = Date.now()
+  for (const sub of ['lead-direct', 'dispatch']) {
+    try {
+      const dir = resolvePath(dataDir, 'tool-results', sub)
+      for (const f of readdirSync(dir)) {
+        const p = resolvePath(dir, f)
+        try { if (now - statSync(p).mtimeMs > _TOOL_RESULTS_TTL_MS) unlinkSync(p) } catch {}
+      }
+    } catch {}
+  }
+}
+try { _gcToolResultsOnce() } catch {}
+
+export function pushDispatchResult(ctx, id, tool, queries, body, flags = {}) {
+  const notify = ctx?.notifyFn
+  if (typeof notify !== 'function') {
+    // notifyFn absent means the background result has nowhere to go — the
+    // promise would silently vanish.  Write a visible stderr line so the
+    // operator can diagnose "auto-pushed" answers that never arrived, and
+    // return a structured marker so callers can detect the gap.
+    try {
+      process.stderr.write(`[ai-wrapped-dispatch] pushDispatchResult: no notifyFn — result lost tool=${tool} id=${id}\n`)
+    } catch {}
+    return { lost: true, tool, id, reason: 'no-notify-fn' }
+  }
+  const queryCount = queries.length === 1
+    ? `1 query`
+    : `${queries.length} queries`
+  const bodyHeader = flags.error
+    ? `${tool} failed`
+    : `${tool} — ${queryCount}`
+  // Smart truncation — large recall/search/explore merged bodies
+  // (multi-query fan-out) can blow past the 30 KB smart-read cap and waste
+  // Lead context. Apply the same head/tail summariser used by `read`
+  // (single + array form) so Lead still sees the interesting frames (first queries
+  // and final queries) without paying for the middle mass. Truncation acts
+  // on the body only — the `Done.` header is prepended AFTER, so it never
+  // gets cut.
+  const rawBody = typeof body === 'string' ? body : String(body ?? '')
+  const { text: cappedBody, truncated: bodyTruncated } = capDispatchRetrievalBody(body)
+  // When smart-truncation actually dropped content, spool the full raw body to
+  // tool-results/dispatch/<id>.txt and point the notify body at it so Lead can
+  // recover the complete output instead of reconstructing it by hand.
+  let notifyBody = `${bodyHeader}\n\n${cappedBody}`
+  if (bodyTruncated) {
+    const _dataDirSpool = process.env.CLAUDE_PLUGIN_DATA
+    if (_dataDirSpool && id) {
+      const _fullPath = saveDispatchFullOutput(_dataDirSpool, id, rawBody)
+      if (_fullPath) notifyBody += `\n[full output saved: ${_fullPath}]`
+    }
+  }
+  const persistBody = `${bodyHeader}\n\n${rawBody}`
+  // Prepend a `Done.` wrapper that mirrors the Pool B worker
+  // completion header in src/agent/index.mjs (`${modelTag}[${role}] ...`).
+  // When the model tag can't be resolved, the helper falls back to
+  // `[{tool}] Done.` — still better than no header.
+  const spec = ROLE_BY_TOOL[tool]
+  const modelTag = spec ? resolveAgentModelTag(spec.role) : ''
+  const doneHeader = flags.error
+    ? buildDispatchResultHeader(tool, modelTag).replace(/Done\.$/, 'Failed.')
+    : buildDispatchResultHeader(tool, modelTag)
+  const notifyContent = `${doneHeader}\n\n${notifyBody}`
+  const persistContent = `${doneHeader}\n\n${persistBody}`
+  // NOTE: duplicate notification on reconnect is acceptable — the goal is
+  // "no silent loss". Host-side dedup is not implemented; a reconnect-window
+  // duplicate surfaces the answer twice rather than not at all.
+  const _dataDir = process.env.CLAUDE_PLUGIN_DATA
+  const _qs = Array.isArray(queries) ? queries : [String(queries ?? '')]
+  // Persist the merged result BODY before notify so a torn-down transport
+  // can't lose the answer. recoverPending replays the persisted content on
+  // next boot instead of the generic Aborted boilerplate.
+  // setPendingResult enqueues a debounced/serialized write and returns the
+  // tail Promise that resolves AFTER the disk write completes. We must
+  // await that tail (not just the function return) before notify, so a
+  // crash between notify and disk-flush can't drop the answer — recoverPending
+  // replays from the persisted body, which has to actually be on disk first.
+  const _persistPromise = (_dataDir && id && tool)
+    ? import('./dispatch-persist.mjs').then(({ setPendingResult }) => {
+        const tail = setPendingResult(_dataDir, id, tool, _qs, persistContent, !!flags.error, ctx?.routingSessionId, ctx?.clientHostPid)
+        // Defensive: older builds returned void. Coerce to a Promise so the
+        // chain still awaits something rather than resolving immediately.
+        return tail && typeof tail.then === 'function' ? tail : Promise.resolve()
+      }).catch((e) => { try { process.stderr.write(`[ai-wrapped-dispatch] setPendingResult failed: ${e?.message ?? e}\n`); } catch {} })
+    : Promise.resolve()
+  try {
+    _persistPromise.then(() => {
+      return Promise.resolve(
+        notify(notifyContent, {
+          type: 'dispatch_result',
+          dispatch_id: id,
+          tool,
+          // Daemon routing: deliver this result to the dispatching terminal
+          // via caller_session_id (owner-only in daemon; no session → drop).
+          caller_session_id: ctx?.routingSessionId,
+          ...(typeof ctx?.clientHostPid === 'number' && ctx.clientHostPid > 0
+            ? { client_host_pid: String(ctx.clientHostPid) }
+            : {}),
+          instruction: `The ${tool} dispatch you started earlier (${id}) has returned — use this answer in your next step.`,
+        }),
+      )
+    }).then(() => {
+      // Notify resolved successfully — safe to remove the pending entry.
+      if (_dataDir && id) {
+        import('./dispatch-persist.mjs').then(({ removePending }) => removePending(_dataDir, id)).catch((e) => { try { process.stderr.write(`[ai-wrapped-dispatch] removePending failed: ${e?.message ?? e}\n`); } catch {} })
+      }
+    }).catch((err) => {
+      try {
+        process.stderr.write(`[ai-wrapped-dispatch] pushDispatchResult async failed: tool=${tool} id=${id} err=${err?.message ?? String(err)} — leaving in pending for recoverPending\n`)
+      } catch {}
+      // Leave the pending entry — recoverPending will retry on next boot.
+    })
+  } catch (err) {
+    try { process.stderr.write(`[ai-wrapped-dispatch] pushDispatchResult failed: tool=${tool} id=${id} err=${err?.message ?? String(err)}\n`); } catch {}
+    // Sync-throw safety net: _persistPromise already fired above (best-effort).
+  }
+}
+
+function ok(text) {
+  return { content: [{ type: 'text', text }] }
+}
+
+function fail(msg) {
+  return { content: [{ type: 'text', text: `[aiWrapped error] ${msg}` }], isError: true }
+}