mixdog 0.7.1

package/src/agent/orchestrator/dispatch-persist.mjs

@@ -0,0 +1,549 @@
+/**
+ * dispatch-persist — crash / restart recovery for async dispatch handles.
+ *
+ * Plugin MCP server can be restarted by Claude Code at any time (idle timeout,
+ * user reload, etc.). Any in-flight dispatch whose merge callback had not yet
+ * run would otherwise be orphaned silently — handle issued, no result, no
+ * abort notification.
+ *
+ * This module persists the minimum needed to recover:
+ *   - handle   (`dispatch_<tool>_...`)
+ *   - tool     (`recall` / `search` / `explore`)
+ *   - queries  (for the abort message)
+ *   - createdAt
+ *
+ * On add: write through to disk. On complete/error: remove entry.
+ * On bootstrap: read file, emit one abort Noti per surviving entry, clear.
+ *
+ * Best-effort everywhere — never let persist IO break the caller.
+ */
+
+import fs from 'fs';
+import path, { join } from 'path';
+import { writeJsonAtomicSync } from '../../shared/atomic-file.mjs';
+
+const TTL_MS = 30 * 60_000;
+const FILE_NAME = 'pending-dispatches.json';
+// Per-entry persisted result body cap. pushDispatchResult already
+// smart-truncates to ~30KB; this is a defense-in-depth ceiling so the
+// pending file cannot balloon if a future caller skips truncation.
+const PERSIST_RESULT_MAX_BYTES = 64 * 1024;
+
+// File mode for the on-disk pending-dispatches.json. Matches config/snapshot
+// data-at-rest posture: owner-only read/write. The replayed body may contain
+// tool output bytes (recall/search/explore) that, despite redaction below,
+// should not be world-readable.
+const PERSIST_FILE_MODE = 0o600;
+
+// High-confidence secret patterns redacted before the result body is written
+// to pending-dispatches.json. recoverPending replays entry.content verbatim
+// into model context, so an async explore/search/recall result that happened
+// to surface a credential would otherwise duplicate it into this JSON.
+//
+// Conservative on purpose — false negatives are acceptable (already-known
+// truncation defense remains), false positives just redact a token-shaped
+// substring in a transcript. Patterns:
+//   - `sk-...` bearer-style API keys (OpenAI / Anthropic family prefix)
+//   - `Bearer <token>` Authorization header values
+//   - `*_API_KEY` / `*_TOKEN` / `*_SECRET` assignments (env / json / yaml)
+//   - JWTs (`eyJ` header + two more base64url segments)
+//   - PEM private-key blocks (GCP service-account / RSA)
+//   - `"private_key_id": "<40 hex>"` JSON fields (GCP service-account)
+const _SECRET_PATTERNS = [
+  // sk-<16+ token chars>
+  /\bsk-[A-Za-z0-9_\-]{16,}\b/g,
+  // Bearer <token>
+  /\bBearer\s+[A-Za-z0-9._\-]{16,}\b/gi,
+  // FOO_API_KEY = "..." | FOO_TOKEN: '...' | FOO_SECRET=...
+  // Captures the assignment prefix in group 1 so the key name survives.
+  /\b([A-Z][A-Z0-9_]*_(?:API_KEY|TOKEN|SECRET|PASSWORD))\s*[:=]\s*["']?([A-Za-z0-9_./+\-]{8,})["']?/g,
+  // JWT: three dot-separated base64url segments; header starts `eyJ`
+  // (base64 of `{"`). High-precision — the `eyJ` anchor + two segments
+  // avoids matching generic base64.
+  /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+  // PEM private-key block — any common label (PKCS#8 plain, RSA, EC, DSA,
+  // OPENSSH, ENCRYPTED). Non-greedy so a body with multiple keys redacts
+  // each block independently.
+  /-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----/g,
+  // GCP service-account `"private_key_id": "<40 lowercase hex>"`.
+  // Captures the field prefix (g1) and closing quote (g2) so the JSON key
+  // and structure survive.
+  /("private_key_id"\s*:\s*")[a-f0-9]{40}(")/g,
+];
+
+function redactSecrets(body) {
+  if (typeof body !== 'string' || body.length === 0) return body;
+  try {
+    let out = body;
+    out = out.replace(_SECRET_PATTERNS[0], '[REDACTED:sk-key]');
+    out = out.replace(_SECRET_PATTERNS[1], 'Bearer [REDACTED]');
+    out = out.replace(_SECRET_PATTERNS[2], (_m, k) => `${k}=[REDACTED]`);
+    out = out.replace(_SECRET_PATTERNS[3], '[REDACTED:jwt]');
+    out = out.replace(_SECRET_PATTERNS[4], '[REDACTED:private-key]');
+    out = out.replace(_SECRET_PATTERNS[5], (_m, k, q) => `${k}[REDACTED]${q}`);
+    return out;
+  } catch {
+    // Fail closed: a redaction failure must NEVER leak the raw/partial body.
+    return '[REDACTED: secret-redaction failed]';
+  }
+}
+
+// Per-dataDir Promise tails — different dataDirs run in parallel.
+// Keyed by normalized absolute dataDir path (path.resolve); value is the
+// current tail Promise.  Normalization ensures '/data/x/' and '/data/x' route
+// to the same tail entry.
+const _writeTails = new Map();
+
+// Last successfully written payload per dataDir for exit-drain sync flush.
+const _lastPayload = new Map();
+
+// In-progress desired state captured at writeAll entry (before the async write
+// completes).  exitDrain prefers this over _lastPayload because it is newer —
+// it reflects mutations that queued after the last completed writeAll but
+// before process exit.  Cleared once writeAll succeeds.
+const _pendingPayload = new Map();
+
+function getTail(dataDir) {
+  return _writeTails.get(path.resolve(dataDir)) ?? Promise.resolve();
+}
+
+function setTail(dataDir, p) {
+  _writeTails.set(path.resolve(dataDir), p);
+}
+
+// ── Exit drain: sync-flush in-flight tails on process exit ─────────────────
+// Cannot await on exit; use sync writeFileSync to flush the last known payload.
+//
+// Risk (KEEP): this sync flush bypasses the async cross-process file lock.
+// A concurrent writer from another process may race on the same file during
+// the drain window.  The window is bounded (process is exiting) and eliminating
+// it requires a fundamentally different design (e.g. a dedicated lock-owner
+// process).  Best-effort is the correct trade-off here.
+export function drainDispatchPersist() {
+  // Prefer _pendingPayload (desired state captured at writeAll entry) over
+  // _lastPayload (last successfully written state).  Pending is strictly
+  // newer when a writeAll is still in-flight or queued at process exit.
+  const dirs = new Set([..._pendingPayload.keys(), ..._lastPayload.keys()]);
+  for (const dataDir of dirs) {
+    const payload = _pendingPayload.get(dataDir) ?? _lastPayload.get(dataDir);
+    if (!payload) continue;
+    try {
+      const p = pathFor(dataDir);
+      // fsync:false — see writeAll. This file is a best-effort restart-recovery
+      // spool; the page cache survives a plugin process restart (the only
+      // failure it guards), so we skip the synchronous disk-flush stall. KEEP
+      // lock:true: the exit-drain window can still race other processes.
+      writeJsonAtomicSync(p, payload, { compact: true, lock: true, mode: PERSIST_FILE_MODE, fsync: false });
+    } catch { /* best-effort */ }
+  }
+}
+
+// SIGTERM/SIGINT drain runs through drain-registry.mjs (single signal
+// handler for the whole orchestrator); the bare 'exit' hook stays as an
+// idempotent backup for cases where the registry already ran.
+process.once('exit', drainDispatchPersist);
+
+// ── Cross-process file lock ─────────────────────────────────────────────────
+// Uses O_EXCL (wx flag) on a sibling .lock file so concurrent writers from
+// different processes serialize around the same R/M/W on pending-dispatches.json.
+// Wait briefly with jittered polling; stale lock files are cleared so a crashed
+// writer cannot make every later dispatch persist best-effort-only.
+const LOCK_FILE_NAME = 'pending-dispatches.json.lock';
+const LOCK_WAIT_MS  = 8_000;
+const LOCK_POLL_MS  = 50;
+const LOCK_STALE_MS = 30_000;
+const LOCK_WAIT_CODES = new Set(['EEXIST', 'EPERM', 'EACCES', 'EBUSY']);
+
+function lockPath(dataDir) {
+  return join(dataDir, LOCK_FILE_NAME);
+}
+
+/**
+ * Acquire a cross-process file lock. Returns the lock-file path on success
+ * so the caller can pass it to releaseFileLock. Returns null if the lock
+ * could not be acquired within the timeout; callers then skip this
+ * best-effort persist rather than writing unlocked over another process.
+ */
+async function acquireFileLock(dataDir) {
+  const lp = lockPath(dataDir);
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  while (true) {
+    try {
+      // O_EXCL guarantees atomic create; fails with EEXIST if lock is held.
+      const fd = fs.openSync(lp, 'wx');
+      try { fs.writeSync(fd, `${process.pid} ${Date.now()}\n`, 0, 'utf8'); } catch { /* best-effort */ }
+      fs.closeSync(fd);
+      return lp;
+    } catch (err) {
+      if (!LOCK_WAIT_CODES.has(err?.code)) {
+        process.stderr.write(`[dispatch-persist] lock open error: ${err?.code || err?.message}\n`);
+        return null;
+      }
+      try {
+        const st = fs.statSync(lp);
+        if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+          try { fs.unlinkSync(lp); } catch { /* another process won */ }
+          continue;
+        }
+      } catch { /* stat race; retry */ }
+      if (Date.now() >= deadline) {
+        process.stderr.write(`[dispatch-persist] lock timeout after ${LOCK_WAIT_MS}ms — skipping this best-effort persist\n`);
+        return null;
+      }
+      await new Promise(r => setTimeout(r, LOCK_POLL_MS + Math.floor(Math.random() * LOCK_POLL_MS)));
+    }
+  }
+}
+
+function releaseFileLock(lp) {
+  if (!lp) return;
+  try { fs.unlinkSync(lp); } catch { /* best-effort */ }
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+
+function pathFor(dataDir) {
+  return join(dataDir, FILE_NAME);
+}
+
+async function readAll(dataDir) {
+  try {
+    const p = pathFor(dataDir);
+    try {
+      await fs.promises.access(p);
+    } catch {
+      return {};
+    }
+    const raw = await fs.promises.readFile(p, 'utf8');
+    if (!raw.trim()) return {};
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object') ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function readAllSync(dataDir) {
+  try {
+    const p = pathFor(dataDir);
+    try {
+      fs.accessSync(p);
+    } catch {
+      return {};
+    }
+    const raw = fs.readFileSync(p, 'utf8');
+    if (!raw.trim()) return {};
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object') ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+async function writeAll(dataDir, map) {
+  try {
+    const p = pathFor(dataDir);
+    // Capture desired state BEFORE the async write so exitDrain can sync-flush
+    // it even if this writeAll is still in-flight at process exit.
+    _pendingPayload.set(dataDir, map);
+    // fsync:false — pending-dispatches.json is a BEST-EFFORT restart-recovery
+    // spool, not durable data. The only event it must survive is a plugin MCP
+    // server restart, and the OS page cache already survives that (the bytes
+    // are visible to the next process without an fsync). The fsync only buys
+    // durability across an OS crash / power loss, which recovery does not rely
+    // on — so we skip the synchronous fsyncSync stall on the dispatch hot path.
+    // Atomic write-temp + rename ordering is unchanged; only the durability
+    // barrier is dropped. Default fsync behaviour is untouched for every other
+    // writeJsonAtomicSync caller (session saves, secrets, snapshots).
+    writeJsonAtomicSync(p, map, { compact: true, mode: PERSIST_FILE_MODE, fsync: false });
+    // Write completed — promote to last-written and clear pending (redundant now).
+    _lastPayload.set(dataDir, map);
+    _pendingPayload.delete(dataDir);
+  } catch { /* best-effort */ }
+}
+
+/**
+ * Prune expired entries. Returns `{ map, changed }` so callers can decide
+ * whether to write the pruned state back to disk. `changed === true` iff
+ * at least one entry was deleted (or was present but falsy). addPending
+ * always writes regardless, so it does not need the flag; hasPending /
+ * recoverPending / removePending use it to persist the pruned map instead
+ * of letting expired entries accumulate in pending-dispatches.json across
+ * restarts.
+ */
+function gc(map) {
+  const now = Date.now();
+  let changed = false;
+  for (const [k, v] of Object.entries(map)) {
+    if (!v || (now - (v.createdAt || 0)) > TTL_MS) {
+      delete map[k];
+      changed = true;
+    }
+  }
+  return { map, changed };
+}
+
+function normalizeClientHostPid(v) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export function addPending(dataDir, handle, tool, queries, callerSessionId, clientHostPid) {
+  if (!dataDir || !handle) return;
+  const tail = getTail(dataDir).then(async () => {
+    try {
+      const lp = await acquireFileLock(dataDir);
+      if (!lp) return;
+      try {
+        const { map } = gc(await readAll(dataDir));
+        // Preserve any prior fields (e.g. content from setPendingResult) so a
+        // re-add by pushDispatchResult does not erase the persisted body.
+        const prior = map[handle] && typeof map[handle] === 'object' ? map[handle] : {};
+        const sid = callerSessionId != null && String(callerSessionId)
+          ? String(callerSessionId)
+          : prior.callerSessionId;
+        const hostPid = normalizeClientHostPid(clientHostPid) ?? normalizeClientHostPid(prior.clientHostPid);
+        map[handle] = {
+          ...prior,
+          tool,
+          queries: Array.isArray(queries) ? queries : [String(queries)],
+          createdAt: prior.createdAt || Date.now(),
+          ...(sid ? { callerSessionId: sid } : {}),
+          ...(hostPid ? { clientHostPid: hostPid } : {}),
+        };
+        await writeAll(dataDir, map);
+        try {
+          process.stderr.write(`[dispatch-persist] persist handle=${handle} tool=${tool} entries=${Object.keys(map).length}\n`);
+        } catch { /* best-effort */ }
+      } finally {
+        releaseFileLock(lp);
+      }
+    } catch { /* best-effort */ }
+  });
+  setTail(dataDir, tail);
+}
+
+/**
+ * Attach the merged dispatch result body to an existing pending entry. Called
+ * BEFORE notify so a torn-down transport / mid-push restart can replay the
+ * actual answer via recoverPending instead of the generic Aborted boilerplate.
+ *
+ * Body is truncated to PERSIST_RESULT_MAX_BYTES so a future skipped-truncation
+ * caller cannot balloon the pending file. Truncation marker is appended verbatim
+ * — the body is already a finished user-facing answer when this runs.
+ */
+export function setPendingResult(dataDir, handle, tool, queries, content, isError, callerSessionId, clientHostPid) {
+  if (!dataDir || !handle) return Promise.resolve();
+  const tail = getTail(dataDir).then(async () => {
+    try {
+      const lp = await acquireFileLock(dataDir);
+      if (!lp) return;
+      try {
+        const { map } = gc(await readAll(dataDir));
+        const prior = map[handle] && typeof map[handle] === 'object' ? map[handle] : {};
+        const sid = callerSessionId != null && String(callerSessionId)
+          ? String(callerSessionId)
+          : prior.callerSessionId;
+        const hostPid = normalizeClientHostPid(clientHostPid) ?? normalizeClientHostPid(prior.clientHostPid);
+        let body = typeof content === 'string' ? content : String(content ?? '');
+        // Redact high-confidence secret patterns BEFORE truncation so a key
+        // that lands near the truncation boundary cannot be sliced into the
+        // persisted prefix unredacted.
+        body = redactSecrets(body);
+        if (Buffer.byteLength(body, 'utf8') > PERSIST_RESULT_MAX_BYTES) {
+          body = body.slice(0, PERSIST_RESULT_MAX_BYTES) + '\n…[persist-truncated]';
+        }
+        map[handle] = {
+          ...prior,
+          tool: tool || prior.tool,
+          queries: Array.isArray(queries) ? queries : (prior.queries || []),
+          createdAt: prior.createdAt || Date.now(),
+          content: body,
+          isError: !!isError,
+          ...(sid ? { callerSessionId: sid } : {}),
+          ...(hostPid ? { clientHostPid: hostPid } : {}),
+        };
+        await writeAll(dataDir, map);
+        try {
+          process.stderr.write(`[dispatch-persist] persist-result handle=${handle} tool=${tool} bytes=${Buffer.byteLength(body, 'utf8')}\n`);
+        } catch { /* best-effort */ }
+      } finally {
+        releaseFileLock(lp);
+      }
+    } catch { /* best-effort */ }
+  });
+  setTail(dataDir, tail);
+  // Return the tail Promise so callers (pushDispatchResult) can actually
+  // await the disk flush before notifying. Previously this returned void,
+  // letting notify race the debounced write — a crash between the two
+  // would lose the persisted body recoverPending depends on.
+  return tail;
+}
+
+/**
+ * Best-effort check: is there at least one non-expired in-flight dispatch
+ * recorded for this dataDir? Used by the scheduler's idle-state probe so
+ * background tasks stay suppressed while a bridge dispatch is still
+ * running. Never throws.
+ */
+export function hasPending(dataDir) {
+  if (!dataDir) return false;
+  try {
+    // hasPending is a synchronous probe on the hot path; read without lock is
+    // acceptable (observation only). If gc pruned entries, flush asynchronously
+    // via per-dataDir tail so the write is still cross-process serialized.
+    const p = pathFor(dataDir);
+    let raw = '';
+    try { raw = fs.readFileSync(p, 'utf8'); } catch { /* missing = empty */ }
+    let parsed = {};
+    try { if (raw.trim()) parsed = JSON.parse(raw); } catch { /* best-effort */ }
+    if (!parsed || typeof parsed !== 'object') parsed = {};
+    const { map, changed } = gc(parsed);
+    if (changed) {
+      const tail = getTail(dataDir).then(async () => {
+        const lp = await acquireFileLock(dataDir);
+        if (!lp) return;
+        try { await writeAll(dataDir, map); } finally { releaseFileLock(lp); }
+      });
+      setTail(dataDir, tail);
+    }
+    return Object.keys(map).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export function removePending(dataDir, handle) {
+  if (!dataDir || !handle) return;
+  const tail = getTail(dataDir).then(async () => {
+    try {
+      const lp = await acquireFileLock(dataDir);
+      if (!lp) return;
+      try {
+        const { map, changed } = gc(await readAll(dataDir));
+        let mutated = changed;
+        if (handle in map) {
+          delete map[handle];
+          mutated = true;
+          try {
+            process.stderr.write(`[dispatch-persist] ack-pop handle=${handle} entries=${Object.keys(map).length}\n`);
+          } catch { /* best-effort */ }
+        }
+        if (mutated) await writeAll(dataDir, map);
+      } finally {
+        releaseFileLock(lp);
+      }
+    } catch { /* best-effort */ }
+  });
+  setTail(dataDir, tail);
+}
+
+/**
+ * Called once at plugin bootstrap after the MCP transport is connected.
+ * For every pending entry remaining from the previous process lifetime,
+ * emit a single Aborted notification with `type: 'dispatch_result'` so the
+ * Lead can close the loop on its next turn. Then clear the file.
+ *
+ * Recovery is chained onto the per-dataDir tail so it serializes with any
+ * in-flight addPending / removePending mutations for the same dataDir.
+ * Notifications fire asynchronously; the return value is the number of
+ * handles queued for recovery (callers use it as bootstrap telemetry).
+ */
+export function recoverPending(dataDir, notifyFn, { sessionId, priorSessionId, clientHostPid } = {}) {
+  if (!dataDir || typeof notifyFn !== 'function') return 0;
+  const { map: snapshot } = gc(readAllSync(dataDir));
+  const filterSid = sessionId != null && String(sessionId) ? String(sessionId) : null;
+  const priorSid = priorSessionId != null && String(priorSessionId) ? String(priorSessionId) : null;
+  const filterHostPid = normalizeClientHostPid(clientHostPid);
+  const matchesScope = (entry) => {
+    if (!filterSid && !filterHostPid) return true;
+    const callerSessionId = entry?.callerSessionId;
+    const cid = callerSessionId != null && String(callerSessionId) ? String(callerSessionId) : null;
+    if (cid && (cid === filterSid || (priorSid != null && cid === priorSid))) return true;
+    const entryHostPid = normalizeClientHostPid(entry?.clientHostPid);
+    return filterHostPid != null && entryHostPid === filterHostPid;
+  };
+  const scoped = filterSid || filterHostPid;
+  const queued = scoped
+    ? Object.keys(snapshot).filter((h) => matchesScope(snapshot[h])).length
+    : Object.keys(snapshot).length;
+  const tail = getTail(dataDir).then(async () => {
+    const lp = await acquireFileLock(dataDir);
+    if (!lp) return;
+    try {
+      const { map, changed } = gc(await readAll(dataDir));
+      const handles = Object.keys(map).filter((handle) => {
+        return matchesScope(map[handle]);
+      });
+      if (handles.length === 0) {
+        // No handles to recover for this scope. A gc() pass may still have
+        // pruned expired entries — persist the pruned `map` (NOT `{}`): under a
+        // session-scoped recovery `handles` is only the reconnecting session's
+        // subset, so other sessions' still-live pending entries remain in `map`
+        // and must survive. (Unscoped recovery reaches here only when `map` is
+        // already empty, so writing `map` is equivalent to writing `{}` there.)
+        if (changed) await writeAll(dataDir, map);
+        return;
+      }
+      for (const handle of handles) {
+        const entry = map[handle] || {};
+        const tool = entry.tool || 'dispatch';
+        const queries = Array.isArray(entry.queries) ? entry.queries : [];
+        // Two recovery modes:
+        //   1. Persisted result body present → re-deliver the actual answer.
+        //      The result was computed but the channel push didn't ack before
+        //      the plugin died. setPendingResult wrote it pre-notify.
+        //   2. No body → the worker hadn't returned yet at restart; emit the
+        //      Aborted boilerplate so the Lead can retry.
+        let content;
+        let isError;
+        let kind;
+        if (typeof entry.content === 'string' && entry.content.length > 0) {
+          content = entry.content;
+          isError = !!entry.isError;
+          kind = 'replay';
+        } else {
+          const qSuffix = queries.length === 1 ? '1 query' : `${queries.length} queries`;
+          content = `[${tool}] Aborted — plugin restart interrupted dispatch (${qSuffix}). Retry if still needed.`;
+          isError = true;
+          kind = 'abort';
+        }
+        const meta = {
+          type: 'dispatch_result',
+          dispatch_id: handle,
+          tool,
+          error: String(isError),
+          ...(filterSid
+            ? { caller_session_id: filterSid }
+            : (entry.callerSessionId ? { caller_session_id: entry.callerSessionId } : {})),
+          ...(filterHostPid > 0
+            ? { client_host_pid: String(filterHostPid) }
+            : (entry.clientHostPid > 0 ? { client_host_pid: String(entry.clientHostPid) } : {})),
+          instruction: kind === 'replay'
+            ? `Earlier ${tool} dispatch (${handle}) result was queued before plugin restart — here it is.`
+            : `Earlier ${tool} dispatch (${handle}) was aborted by a plugin restart. Retry if the answer is still needed.`,
+        };
+        try { process.stderr.write(`[dispatch-persist] recover handle=${handle} tool=${tool} kind=${kind}\n`); } catch { /* best-effort */ }
+        // Entry remains on disk until notifyFn resolves.  A crash between
+        // fire and ack is safe: the entry survives and recoverPending re-fires
+        // it on the next restart.  Only clear AFTER ack to prevent silent loss.
+        try {
+          Promise.resolve(notifyFn(content, meta)).then(() => {
+            removePending(dataDir, handle);
+          }).catch(() => { /* best-effort — entry stays for next recoverPending */ });
+        } catch { /* best-effort */ }
+      }
+      // Do NOT bulk-clear here.  Each handle is removed individually above,
+      // only after its notifyFn acks.  If gc() pruned expired entries, write
+      // back the pruned map (without expired keys) — live handles remain on
+      // disk until their per-handle removePending calls land.
+      if (changed) await writeAll(dataDir, map);
+      try {
+        process.stderr.write(`[dispatch-persist] recoverPending recovered=${handles.length} entries queued\n`);
+      } catch { /* best-effort */ }
+    } catch { /* best-effort */ }
+    finally { releaseFileLock(lp); }
+  });
+  setTail(dataDir, tail);
+  return queued;
+}

package/src/agent/orchestrator/drain-registry.mjs

@@ -0,0 +1,50 @@
+/**
+ * Exit-time drain registry for the cli.mjs process. Single SIGTERM/SIGINT
+ * owner — modules must NOT self-install signal handlers (avoids import-order
+ * race where the first handler's process.exit suppressed the rest).
+ * runAllDrains walks _drainBuckets in priority order; drains are best-effort
+ * by contract (never throw). Bucket order/membership pinned by tests.
+ */
+
+import { drainSessionStore } from './session/store.mjs';
+import { drainCodeGraphCache } from './tools/code-graph.mjs';
+import { drainCacheStats } from './session/cache/scoped-cache.mjs';
+import { drainBridgeTrace } from './bridge-trace.mjs';
+import { drainDispatchPersist } from './dispatch-persist.mjs';
+import { drainJobs } from './jobs.mjs';
+import { drainBashSessions } from './tools/bash-session.mjs';
+import { drainShellSnapshots } from './tools/shell-snapshot.mjs';
+import { drainMcpClients } from './mcp/client.mjs';
+import { drainOpenaiWsPool } from './providers/openai-oauth-ws.mjs';
+
+const _drainBuckets = [
+    { name: 'data-integrity',    drains: [drainSessionStore, drainDispatchPersist, drainJobs] },
+    { name: 'external-resource', drains: [drainBashSessions, drainShellSnapshots, drainMcpClients, drainOpenaiWsPool] },
+    { name: 'recoverable-cache', drains: [drainCodeGraphCache, drainCacheStats] },
+    { name: 'telemetry',         drains: [drainBridgeTrace] },
+];
+
+// Atomic single-execution: concurrent callers share the same Promise so
+// each drain fires exactly once across process lifetime.
+let _runningDrain = null;
+export function runAllDrains() {
+    if (_runningDrain) return _runningDrain;
+    _runningDrain = (async () => {
+        for (const bucket of _drainBuckets) {
+            for (const fn of bucket.drains) await fn();
+        }
+    })();
+    return _runningDrain;
+}
+
+// Test-facing snapshot — tests pin priority order and bucket membership.
+export const _internals = { _drainBuckets };
+
+// Side-effect signal handlers — drain on SIGINT/SIGTERM same as normal exit.
+// Exit code 128 + signal (SIGINT=2 → 130, SIGTERM=15 → 143).
+async function _signalDrainExit(code) {
+    await runAllDrains();
+    process.exit(code);
+}
+process.on('SIGINT', () => { _signalDrainExit(130); });
+process.on('SIGTERM', () => { _signalDrainExit(143); });

package/src/agent/orchestrator/explore-validator.mjs

@@ -0,0 +1,8 @@
+// Runtime envelope limits for explore output. These are not classifier
+// heuristics — they cap raw string allocation to stay clear of V8's
+// max-string-length (~512 MB) when concatenating subagent responses across
+// a broad cwd (e.g. the whole ~/.claude tree). Lowering these would silently
+// truncate legitimate output; raising them risks OOM crashes in the MCP server.
+export const EXPLORE_OUTPUT_CHAR_CAP = 50_000_000
+export const EXPLORE_PER_PIECE_CHAR_CAP = 5_000_000
+export const EXPLORE_TRUNCATION_MARKER = '\n\n[explore: output truncated at 50MB cap; narrow cwd or split queries to see more]'