@cohortapp/agent-sdk 2.3.0

package/scripts/daemon/dispatcher.mjs

@@ -0,0 +1,1516 @@
+#!/usr/bin/env node
+// Dispatcher — manages concurrent claude --print sessions
+// Spawns child processes, manages queue, enforces concurrency cap
+
+import { spawn } from "child_process";
+import { appendFileSync, mkdirSync, writeFileSync, readFileSync, renameSync, existsSync, readdirSync, unlinkSync } from "fs";
+import { randomUUID } from "crypto";
+import { join, dirname } from "path";
+import { releaseLock, releaseThreadLock, releaseRequestClaim, claimItem, releaseItemClaim } from "./session-lock.mjs";
+import { promoteDeferred } from "./inbox-deferral.mjs";
+import { recordSession } from "./health.mjs";
+import { startTyping, stopTyping } from "./typing-registry.mjs";
+// Permission scoping (security CRITICAL / audit H1). sessionPermissionArgs()
+// returns ["--dangerously-skip-permissions"] by default (byte-for-byte the prior
+// hardcoded literal) OR a scoped ["--allowedTools", "<list>"] when the operator
+// sets MAESTRO_SCOPED_PERMISSIONS=1. Spawns route through it so opted-in scoping
+// is actually honoured instead of being bypassed on the user-facing path.
+import { sessionPermissionArgs } from "../../lib/session-permissions.mjs";
+
+// WS4 — resource governance + cross-session 429 breaker + daily budget cap.
+// Every spawn is gated on admission (ADMIT/QUEUE/DEFER) and the shared rate
+// breaker so the agent throttles instead of bricking and never exceeds the
+// host. All three are injectable (setGovernanceForTests) so the dispatcher
+// stays hermetically testable.
+import * as resourceGovernor from "../../lib/resource-governor.mjs";
+import * as rateGuardModule from "../../lib/rate-guard.mjs";
+import * as budgetGuardModule from "../../lib/budget-guard.mjs";
+
+let governor = resourceGovernor;
+let rateGuard = rateGuardModule;
+let budgetGuard = budgetGuardModule;
+const RATE_PROVIDER = process.env.MAESTRO_RATE_PROVIDER || "anthropic";
+
+/**
+ * Test seam: swap the governance modules for fakes. Each arg is optional;
+ * omitted modules keep the real implementation. Returns a restore fn.
+ */
+export function setGovernanceForTests({ governor: g, rateGuard: r, budgetGuard: b } = {}) {
+  const prev = { governor, rateGuard, budgetGuard };
+  if (g) governor = g;
+  if (r) rateGuard = r;
+  if (b) budgetGuard = b;
+  return () => { governor = prev.governor; rateGuard = prev.rateGuard; budgetGuard = prev.budgetGuard; };
+}
+
+// Indirection so a test can capture the EXACT argv handed to `claude` by the
+// real resume spawner (defaultSpawnResume) without launching a child process.
+// Production default is the imported `spawn`, so behaviour is unchanged.
+let _spawn = spawn;
+/** Test seam: replace child_process.spawn. Returns a restore fn. */
+export function setSpawnForTests(fn) {
+  const prev = _spawn;
+  _spawn = typeof fn === "function" ? fn : spawn;
+  return () => { _spawn = prev; };
+}
+
+/**
+ * Resolve the current admission decision for a (source) under live host load,
+ * folding in the daily-budget essential-only mode. Best-effort: any throw is
+ * treated as ADMIT (fail-open-for-work — Invariant: never drop/stall work on a
+ * governance bug).
+ */
+function admitFor(source, priority) {
+  try {
+    let mode = null;
+    try {
+      if (budgetGuard.dailyStatus({ agentRoot: AGENT_REPO_DIR }).essentialOnly) mode = "essential-only";
+    } catch { /* budget read best-effort */ }
+    return governor.admit({ source, priority, mode }, governor.defaultDeps({ agentRoot: AGENT_REPO_DIR }));
+  } catch {
+    return { decision: "ADMIT", reason: "governor-error-fail-open", snapshot: {} };
+  }
+}
+
+/** Is the shared 429 breaker currently open for our provider? */
+function rateBlocked() {
+  try {
+    const r = rateGuard.checkRateLimit(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR });
+    return r.allowed ? null : r;
+  } catch {
+    return null; // fail-open-for-work
+  }
+}
+
+const AGENT_REPO_DIR = process.env.AGENT_DIR || join(new URL(".", import.meta.url).pathname, "../..");
+// Resolve the claude binary against the agent's PATH (not launchd's bare
+// env). Without this, every daemon-spawned `claude --print` exits ENOENT.
+import { resolveClaudeBin, augmentedPath, daemonClaudeArgs } from "../../lib/claude-bin.mjs";
+const CLAUDE_BIN = resolveClaudeBin();
+
+// Model router — opt-in. When config/model-routing.yaml is present in the
+// agent repo, each spawn is routed to the cheapest backend that satisfies
+// the request's capability needs. When absent, the resolver returns null
+// and we preserve the current Claude-CLI-on-Max-subscription behaviour.
+//
+// Two routing paths now coexist (SPEC §3 — additive, byte-compatible):
+//   - v1 (legacy): resolveBackend → modelFlagFor → envForSpawn. Preserved
+//     verbatim for v1 configs (no schema_version) and as the safety net.
+//   - v2 (schema_version: 2): resolveChain → RouteDecision. The decision carries
+//     the chosen backend, the session-retarget env, the spawn knobs, the
+//     ordered failover chain, an estimated cost, and a decision_id that joins
+//     the ledger row ↔ resume marker ↔ routing audit. We build the argv + child
+//     env from the decision via the execution layer's pure builders
+//     (buildSpawnArgs / buildChildEnv from lib/model-router/spawn.mjs) so the
+//     §7.3 child-env scrubbing + argv contract match spawnRouted exactly.
+//
+// NOTE on spawnRouted: the daemon's spawnSession() must register the child
+// process SYNCHRONOUSLY (tests + getStatus() observe active_sessions right after
+// dispatch, and the child's close/error/timeout handlers own cooldowns, resume
+// markers, lock release, and the cost ledger). spawnRouted owns an ASYNC
+// fast-fail failover loop that resolves a Promise — incompatible with that
+// synchronous, externally-driven-close contract here without a rewrite that
+// risks regressions. We therefore reuse spawnRouted's pure argv/env BUILDERS at
+// this seam and keep the existing synchronous _spawn + handlers; the async
+// failover loop is the right fit for the scripted one-shot/cadence sites (which
+// already drive their own close). Cross-backend failover at the dispatcher is a
+// precise follow-up (see the spawn-site checklist in the WS summary).
+import {
+  loadRoutingConfig,
+  resolveBackend,
+  requestFromClassifierResult,
+  modelFlagFor,
+  resolveChain,
+} from "../../lib/model-router.mjs";
+import { buildSpawnArgs, buildChildEnv } from "../../lib/model-router/spawn.mjs";
+import { budgetLadder, spawnKnobsFor } from "../../lib/model-router/economics.mjs";
+// Observability spine (WS — diagnostics). The dispatcher emits `dispatched` at
+// spawn and `session_opened`/`session_closed` from the existing close hook,
+// attaching the interaction's trace_id (handed off explicitly on item.trace_id —
+// AsyncLocalStorage cannot cross the proc-event boundary) + the v2 decision_id.
+// emitEvent is fail-open (never throws), so this is purely additive telemetry.
+import { emitEvent, EVENT_TYPES } from "../../lib/diagnostics/events.mjs";
+// Lazy + cached so a misconfigured YAML doesn't break agents that didn't
+// opt in. The cache is invalidated only on daemon restart.
+let _routingConfigCache;
+function getRoutingConfig() {
+  if (_routingConfigCache === undefined) {
+    try {
+      _routingConfigCache = loadRoutingConfig(AGENT_REPO_DIR) || null;
+    } catch (err) {
+      console.warn(`[dispatcher] model-router config invalid, falling back to Anthropic CLI: ${err.message}`);
+      _routingConfigCache = null;
+    }
+  }
+  return _routingConfigCache;
+}
+const MAX_CONCURRENT = parseInt(process.env.DAEMON_MAX_CONCURRENT || "10", 10);
+const RESERVED_INBOX_SLOTS = 3;    // Always keep 3 slots free for real-time inbox items
+
+// Timeouts — tiered by model and source
+const SONNET_INBOX_TIMEOUT = 10 * 60 * 1000;          // 10 min (inbox — user expects a reply)
+const SONNET_BACKLOG_TIMEOUT = 30 * 60 * 1000;        // 30 min (backlog tasks need more time)
+const OPUS_INBOX_TIMEOUT = 45 * 60 * 1000;            // 45 min (complex inbox — CEO requests, research)
+const OPUS_BACKLOG_TIMEOUT = 12 * 60 * 60 * 1000;     // 12 hours (ultra-complex backlog — deep work)
+
+// Legacy aliases for compatibility
+const SONNET_TIMEOUT = SONNET_INBOX_TIMEOUT;
+const OPUS_TIMEOUT = OPUS_INBOX_TIMEOUT;
+
+const activeSessions = new Map();  // sessionId -> { process, item, startTime, model, source }
+const priorityQueue = [];          // critical/high items
+const normalQueue = [];            // normal items
+let sessionCounter = 0;
+
+// Tracks sessions whose proc.on("error") handler has already fired.
+// Prevents double-counting + double-cleanup when a spawn failure (ENOENT,
+// EACCES, ETIMEDOUT) triggers both "error" and a trailing "close" event.
+// See ib-20260416-daemon-etimedout-failed-event + cycle 135 memo.
+const spawnErrorHandled = new Set();
+
+// Backlog dedup: track which items have active sessions to prevent retry storms
+const activeBacklogKeys = new Set();  // backlog item key -> true (while session is running)
+const backlogRetryCount = new Map();  // backlog item key -> number of times dispatched
+const MAX_BACKLOG_RETRIES = 6;        // Max retries before skipping (was 3 — too aggressive)
+
+// Post-completion cooldown — once a session has run on a backlog item, don't
+// re-dispatch it until N hours later. Without this, every 2-min backlog
+// sweep re-dispatches the same items because the daemon has no signal
+// that the underlying work was actually completed (sessions exit 0 even
+// when they only "looked at" the item). 53 redundant spawns/day per item
+// was the observed rate before this fix.
+const SUCCESS_COOLDOWN_MS = 4 * 60 * 60 * 1000;  // 4h after exit 0
+const FAILURE_COOLDOWN_MS = 30 * 60 * 1000;      // 30m after non-zero exit
+const backlogCooldownUntil = new Map();           // key -> epoch ms
+const COOLDOWN_STATE_PATH = join(AGENT_REPO_DIR, "state/sessions/backlog-cooldowns.json");
+
+// Persist cooldown state across daemon restarts so a freshly-started
+// daemon doesn't immediately re-dispatch items it just completed.
+function loadCooldowns() {
+  try {
+    const body = readFileSync(COOLDOWN_STATE_PATH, "utf-8");
+    const data = JSON.parse(body);
+    const now = Date.now();
+    for (const [key, until] of Object.entries(data || {})) {
+      if (typeof until === "number" && until > now) {
+        backlogCooldownUntil.set(key, until);
+      }
+    }
+  } catch { /* file missing or malformed — start fresh */ }
+}
+function saveCooldowns() {
+  try {
+    const obj = {};
+    for (const [k, v] of backlogCooldownUntil) obj[k] = v;
+    mkdirSync(dirname(COOLDOWN_STATE_PATH), { recursive: true });
+    writeFileSync(COOLDOWN_STATE_PATH, JSON.stringify(obj, null, 2) + "\n");
+  } catch { /* best-effort */ }
+}
+loadCooldowns();
+
+/**
+ * Parse the `claude --print --output-format json` result object out of a
+ * captured stdout STRING (the dispatcher buffers stdout in memory) to recover
+ * the run's REAL token usage + authoritative cost for the ledger (recovery C1).
+ * Returns { ok, inputTokens, outputTokens, cacheReadTokens?, totalCostUsd?,
+ * model? } or { ok:false, reason } — never throws, never fabricates counts.
+ */
+export function parseUsageFromText(text) {
+  const trimmed = (text || "").trim();
+  if (!trimmed) return { ok: false, reason: "empty-stdout" };
+  let obj = null;
+  try { obj = JSON.parse(trimmed); }
+  catch {
+    // Tolerant path: a leading banner/log line can precede the JSON tail. The
+    // CLI's result object is the FIRST balanced top-level object, so slice from
+    // the first "{" to the last "}". (Using lastIndexOf("{") would wrongly grab
+    // a nested object's opening brace.)
+    const start = trimmed.indexOf("{");
+    const end = trimmed.lastIndexOf("}");
+    if (start !== -1 && end !== -1 && end > start) {
+      try { obj = JSON.parse(trimmed.slice(start, end + 1)); } catch { obj = null; }
+    }
+  }
+  if (!obj || typeof obj !== "object") return { ok: false, reason: "no-json-object" };
+  const usage = obj.usage && typeof obj.usage === "object" ? obj.usage : null;
+  if (!usage) return { ok: false, reason: "no-usage-field" };
+  const inputTokens = Number(usage.input_tokens);
+  const outputTokens = Number(usage.output_tokens);
+  if (!Number.isFinite(inputTokens) || !Number.isFinite(outputTokens)) {
+    return { ok: false, reason: "non-numeric-tokens" };
+  }
+  const out = { ok: true, inputTokens, outputTokens };
+  const cacheRead = Number(usage.cache_read_input_tokens);
+  if (Number.isFinite(cacheRead)) out.cacheReadTokens = cacheRead;
+  const totalCost = Number(obj.total_cost_usd);
+  if (Number.isFinite(totalCost) && totalCost >= 0) out.totalCostUsd = totalCost;
+  if (typeof obj.model === "string" && obj.model) {
+    out.model = /opus/i.test(obj.model) ? "opus" : /haiku/i.test(obj.model) ? "haiku" : "sonnet";
+  }
+  return out;
+}
+
+/**
+ * Append a TRUTHFUL cost-ledger row for a finished dispatcher session via
+ * scripts/cost/track-claude-usage.mjs (source "dispatcher"). Real token counts
+ * are parsed from the run's --output-format json stdout; on a parse failure we
+ * pass NO token flags (tracker records 0) rather than fabricate zeros, and the
+ * caller logs the gap. Best-effort + detached; never blocks the close path.
+ */
+function recordDispatcherCost({ stdout, model, durationMs, exitCode, decisionId }) {
+  const usage = parseUsageFromText(stdout);
+  try {
+    const trackerPath = join(AGENT_REPO_DIR, "scripts/cost/track-claude-usage.mjs");
+    if (!existsSync(trackerPath)) return usage;
+    const trackerArgs = [
+      trackerPath, "record",
+      "--cadence", "inbox",
+      "--source", "dispatcher",
+      "--model", usage.model || model || "sonnet",
+      "--duration-ms", String(durationMs),
+      "--exit", String(exitCode),
+    ];
+    // Carry the v2 RouteDecision id onto the ledger row so a spend row joins its
+    // routing decision + resume marker (SPEC §4.7). The tracker captures it as a
+    // generic flag; absent on the v1 / no-config paths.
+    if (decisionId) trackerArgs.push("--decision-id", String(decisionId));
+    if (usage.ok) {
+      trackerArgs.push("--input-tokens", String(usage.inputTokens));
+      trackerArgs.push("--output-tokens", String(usage.outputTokens));
+      if (usage.cacheReadTokens != null) trackerArgs.push("--cache-read-tokens", String(usage.cacheReadTokens));
+      if (usage.totalCostUsd != null) trackerArgs.push("--total-cost-usd", String(usage.totalCostUsd));
+    }
+    spawn(process.execPath, trackerArgs, {
+      stdio: "ignore",
+      env: { ...process.env, AGENT_ROOT: AGENT_REPO_DIR, AGENT_DIR: AGENT_REPO_DIR },
+    }).unref();
+  } catch { /* cost tracking is best-effort */ }
+  return usage;
+}
+
+function logDir() {
+  const dir = join(AGENT_REPO_DIR, "logs", "daemon");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function sessionLogDir() {
+  const dir = join(AGENT_REPO_DIR, "logs", "daemon", "sessions");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function today() {
+  return new Date().toISOString().split("T")[0];
+}
+
+function logSession(entry) {
+  const path = join(logDir(), `${today()}-sessions.jsonl`);
+  appendFileSync(path, JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + "\n");
+}
+
+const ACTIVE_PATH = join(AGENT_REPO_DIR, "state", "sessions", "active.json");
+
+// ---------------------------------------------------------------------------
+// WS4 — in-flight session resume markers
+// ---------------------------------------------------------------------------
+// A marker is written to state/sessions/resume-pending/<sessionId>.json right
+// after spawn and DELETED on a clean close. Its presence after a crash/reboot
+// means "this session was mid-flight" — resetActiveSessions() reconciles them
+// (re-dispatching `claude --print --session-id <claudeSessionId> <prompt>`,
+// the SAME continuation mechanism responder.mjs uses — NOT `--resume`) within a
+// freshness window, instead of blindly wiping the slate. 3 strikes → the queue
+// item is marked status:blocked. This is the "never brick / never drop work"
+// recovery path for the dispatcher.
+const RESUME_PENDING_DIR = join(AGENT_REPO_DIR, "state", "sessions", "resume-pending");
+// Sessions whose marker is older than this are too stale to resume meaningfully
+// (the work context has moved on); reconcile blocks them rather than re-running.
+const RESUME_FRESHNESS_MS = parseInt(process.env.MAESTRO_RESUME_FRESHNESS_MS || String(6 * 60 * 60 * 1000), 10);
+const RESUME_MAX_ATTEMPTS = 3;
+
+function resumePendingPath(sessionId) {
+  return join(RESUME_PENDING_DIR, `${sessionId}.json`);
+}
+
+/**
+ * Write the resume marker for a freshly-spawned session. Best-effort: a marker
+ * we can't write just means that session won't be auto-resumed after a crash
+ * (it still completes normally) — never throws into the spawn path.
+ */
+function writeResumePending(sessionId, entry, claudeSessionId, modelFlag, decisionId) {
+  try {
+    mkdirSync(RESUME_PENDING_DIR, { recursive: true });
+    const marker = {
+      sessionId,
+      claudeSessionId: claudeSessionId || null,
+      itemRef: entry.item?.raw_ref || entry.item?.id || entry.item?.title || null,
+      itemId: entry.item?.id || null,
+      sourceFile: entry.item?.source_file || null,
+      source: entry.source,
+      transcriptPath: entry.transcriptPath || null,
+      summary: entry.classResult?.summary || null,
+      model: entry.classResult?.model || "sonnet",
+      // The exact `--model` flag value the original spawn used (post model-
+      // router resolution). Persisted so a reboot-resume re-spawns against the
+      // SAME backend, not just the coarse sonnet/opus class. (H1)
+      modelFlag: modelFlag || entry.classResult?.model || "sonnet",
+      // The v2 RouteDecision id (when routed through resolveChain). Persisted so
+      // a reboot-resume can correlate the resumed run with the original routing
+      // decision + ledger row (SPEC §4.8). Null on the v1 / no-config paths.
+      decision_id: decisionId || null,
+      // The original prompt is what makes a true resume possible: the resume
+      // path re-spawns `claude --print --session-id <id> <prompt>` (NOT
+      // `--resume`), mirroring responder.mjs's blessed continuation pattern.
+      // Without it a resumed spawn would have no work to do and exit 0, which
+      // the close handler would mistake for "done". (H1)
+      prompt: typeof entry.prompt === "string" ? entry.prompt : null,
+      priority: entry.classResult?.priority || "normal",
+      startedAt: Date.now(),
+      recoveryAttempts: typeof entry.recoveryAttempts === "number" ? entry.recoveryAttempts : 0,
+    };
+    const tmp = resumePendingPath(sessionId) + ".tmp";
+    writeFileSync(tmp, JSON.stringify(marker, null, 2));
+    renameSync(tmp, resumePendingPath(sessionId));
+  } catch (err) {
+    console.warn(`[dispatcher] Failed to write resume-pending marker for ${sessionId}: ${err.message}`);
+  }
+}
+
+/** Delete the resume marker on a clean close. Best-effort. */
+function clearResumePending(sessionId) {
+  try { unlinkSync(resumePendingPath(sessionId)); } catch { /* already gone */ }
+}
+
+/**
+ * Mark a queue item blocked (after 3 failed resume attempts) so the backlog
+ * sweep stops re-dispatching it and an operator can see why. Edits the queue
+ * YAML in place by flipping the item's status to `blocked` and appending a
+ * reason comment. Best-effort + behavior-preserving: if we can't locate the
+ * item we no-op (the cooldown/retry caps still bound re-dispatch).
+ */
+function markItemBlocked(marker, reason) {
+  try {
+    if (!marker.itemId || !marker.sourceFile) return false;
+    const queuePath = join(AGENT_REPO_DIR, "state", "queues", marker.sourceFile);
+    if (!existsSync(queuePath)) return false;
+    let body = readFileSync(queuePath, "utf-8");
+    // Find the item's id line and flip the nearest status: within its block.
+    const idRe = new RegExp(`(^|\\n)(\\s*)(-?\\s*)"?id"?:\\s*["']?${marker.itemId.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}["']?`, "m");
+    const m = idRe.exec(body);
+    if (!m) return false;
+    // Replace the first status: line after the id with status: blocked.
+    const after = body.slice(m.index);
+    const replacedAfter = after.replace(/("?status"?:\s*)["']?(open|in_progress|pending)["']?/, `$1blocked  # WS4 recovery: ${reason}`);
+    if (replacedAfter === after) return false;
+    body = body.slice(0, m.index) + replacedAfter;
+    const tmp = queuePath + ".tmp";
+    writeFileSync(tmp, body);
+    renameSync(tmp, queuePath);
+    logSession({ event: "item_blocked_after_resume_strikes", item_id: marker.itemId, source_file: marker.sourceFile, reason });
+    return true;
+  } catch (err) {
+    console.warn(`[dispatcher] markItemBlocked failed: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * Reset active.json + (on startup) reconcile in-flight session resume markers.
+ *
+ * Previous daemon instances may have left stale active.json entries (killed
+ * sessions whose close handlers never fired). The in-memory session map starts
+ * empty, so active.json is always cleared.
+ *
+ * WS4 — instead of *also* blindly discarding any work that was mid-flight when
+ * the box rebooted/lost power, when `opts.reconcile` is set we walk
+ * state/sessions/resume-pending/ and, for each marker still inside the
+ * freshness window, re-spawn `claude --print --session-id <claudeSessionId>
+ * <prompt>` (the responder's continuation pattern — NOT `--resume`) so the work
+ * continues where it left off. After RESUME_MAX_ATTEMPTS (3) the item is marked
+ * status:blocked with a reason rather than retried forever.
+ *
+ * Graceful shutdown passes no opts (just clears active.json); only startup
+ * reconciles, so we never re-spawn work we're deliberately stopping.
+ *
+ * @param {object} [opts] { reconcile?: boolean, spawnResume?: fn (tests) }
+ */
+export function resetActiveSessions(opts = {}) {
+  try {
+    let staleCount = 0;
+    try {
+      const old = JSON.parse(readFileSync(ACTIVE_PATH, "utf-8"));
+      staleCount = Object.keys(old).length;
+    } catch {}
+    writeFileSync(ACTIVE_PATH, "{}");
+    if (staleCount > 0) {
+      console.log(`[dispatcher] Cleared ${staleCount} stale entries from active.json`);
+    }
+  } catch (err) {
+    console.warn(`[dispatcher] Failed to reset active.json: ${err.message}`);
+  }
+  if (opts.reconcile) {
+    try { return reconcileResumePending(opts); }
+    catch (err) { console.warn(`[dispatcher] resume reconcile failed: ${err.message}`); }
+  }
+}
+
+/**
+ * Walk resume-pending markers and re-dispatch / block each as appropriate.
+ * Exported so a test can drive it deterministically with an injected
+ * `spawnResume`. Returns a summary { resumed, blocked, expired, scanned }.
+ *
+ * @param {object} [opts] { spawnResume?: ({marker})=>void, now?: ()=>number }
+ */
+export function reconcileResumePending(opts = {}) {
+  const now = (typeof opts.now === "function" ? opts.now : Date.now)();
+  const stats = { scanned: 0, resumed: 0, blocked: 0, expired: 0 };
+  let files = [];
+  try {
+    if (!existsSync(RESUME_PENDING_DIR)) return stats;
+    files = readdirSync(RESUME_PENDING_DIR).filter((f) => f.endsWith(".json") && !f.endsWith(".tmp"));
+  } catch { return stats; }
+
+  for (const file of files) {
+    const path = join(RESUME_PENDING_DIR, file);
+    stats.scanned++;
+    let marker;
+    try { marker = JSON.parse(readFileSync(path, "utf-8")); }
+    catch { try { unlinkSync(path); } catch { /* */ } continue; }
+
+    const age = now - (marker.startedAt || 0);
+    const attempts = (marker.recoveryAttempts || 0);
+
+    // 3 strikes → block the item, drop the marker.
+    if (attempts >= RESUME_MAX_ATTEMPTS) {
+      markItemBlocked(marker, `exceeded ${RESUME_MAX_ATTEMPTS} resume attempts`);
+      logSession({ event: "resume_blocked", sessionId: marker.sessionId, item_id: marker.itemId, recovery_attempts: attempts });
+      try { unlinkSync(path); } catch { /* */ }
+      stats.blocked++;
+      continue;
+    }
+
+    // Too stale to resume meaningfully → block (work context has moved on).
+    if (age > RESUME_FRESHNESS_MS) {
+      markItemBlocked(marker, `resume marker stale (${Math.round(age / 60000)}m old)`);
+      logSession({ event: "resume_expired", sessionId: marker.sessionId, item_id: marker.itemId, age_min: Math.round(age / 60000) });
+      try { unlinkSync(path); } catch { /* */ }
+      stats.expired++;
+      continue;
+    }
+
+    // No claude session id to re-spawn against → can't continue; block.
+    if (!marker.claudeSessionId) {
+      logSession({ event: "resume_no_session_id", sessionId: marker.sessionId, item_id: marker.itemId });
+      try { unlinkSync(path); } catch { /* */ }
+      stats.expired++;
+      continue;
+    }
+
+    // No original prompt persisted → there's nothing to re-spawn with (the
+    // resume re-issues `--session-id <id> <prompt>`, NOT `--resume`). A marker
+    // without a prompt is either a legacy marker (pre-H1) or one whose write
+    // dropped the field; we can't truly resume it, so retire it rather than
+    // spawn a no-op that the close handler would mistake for "done". (H1)
+    if (typeof marker.prompt !== "string" || !marker.prompt) {
+      logSession({ event: "resume_no_prompt", sessionId: marker.sessionId, item_id: marker.itemId });
+      try { unlinkSync(path); } catch { /* */ }
+      stats.expired++;
+      continue;
+    }
+
+    // Bump the attempt count on the marker BEFORE re-dispatch so a crash mid-
+    // resume still advances toward the 3-strike cap (no infinite loop).
+    marker.recoveryAttempts = attempts + 1;
+    try {
+      const tmp = path + ".tmp";
+      writeFileSync(tmp, JSON.stringify(marker, null, 2));
+      renameSync(tmp, path);
+    } catch { /* best-effort */ }
+
+    const spawnResume = typeof opts.spawnResume === "function" ? opts.spawnResume : defaultSpawnResume;
+    try {
+      spawnResume({ marker });
+      logSession({ event: "resume_dispatched", sessionId: marker.sessionId, claudeSessionId: marker.claudeSessionId, item_id: marker.itemId, attempt: marker.recoveryAttempts });
+      stats.resumed++;
+    } catch (err) {
+      console.warn(`[dispatcher] resume spawn failed for ${marker.sessionId}: ${err.message}`);
+    }
+  }
+  if (stats.scanned > 0) {
+    console.log(`[dispatcher] resume reconcile: ${stats.resumed} resumed, ${stats.blocked} blocked, ${stats.expired} expired (of ${stats.scanned})`);
+  }
+  return stats;
+}
+
+/**
+ * Real resume spawner. Mirrors responder.mjs's blessed session-continuation
+ * pattern (see runClaudeCLI ~L116-122 + generateResponse ~L461-465): a
+ * continuation re-spawns `claude --print --session-id <sessionId> <prompt>`
+ * with the SAME model/flags the original used — it does NOT use `--resume`.
+ *
+ * Why NOT `--resume` (the previous bug): `--resume <id>` with no prompt and
+ * stdin ignored either (a) exits 0 having done nothing — the close handler
+ * then clears the marker and the interrupted work is silently lost — or (b)
+ * errors, force-`blocked`ing every in-flight item after a reboot. Pre-minting
+ * a stable session id and RE-SPAWNING against it with the original prompt is
+ * the actual resume mechanism in `--print` mode (per the b1 flag-verification
+ * report cited in responder.mjs). The CLI rehydrates the session-id's history
+ * and the fresh prompt continues the work.
+ *
+ * The resumed session inherits the same permission/env posture as a fresh
+ * spawn. Best-effort; failures are logged, the marker stays (next reconcile
+ * retries up to the strike cap). On a clean close the resumed session's own
+ * close handler clears the marker.
+ */
+function defaultSpawnResume({ marker }) {
+  const args = [
+    "--print",
+    ...sessionPermissionArgs({ source: "dispatcher-resume" }),
+    ...daemonClaudeArgs(),
+    "--session-id", marker.claudeSessionId,
+    "--model", marker.modelFlag || marker.model || "sonnet",
+    marker.prompt,
+  ];
+  const spawnEnv = {
+    ...process.env,
+    PATH: augmentedPath(),
+    ANTHROPIC_API_KEY: "",
+    ANTHROPIC_AUTH_TOKEN: "",
+  };
+  const proc = _spawn(CLAUDE_BIN, args, { cwd: AGENT_REPO_DIR, env: spawnEnv, stdio: ["ignore", "pipe", "pipe"] });
+  let stderr = "";
+  proc.stderr.on("data", (c) => { stderr += c.toString(); });
+  proc.on("close", (code) => {
+    if (code === 0) {
+      // Resume succeeded — the underlying work is done; clear the marker.
+      clearResumePending(marker.sessionId);
+      logSession({ event: "resume_completed", sessionId: marker.sessionId, item_id: marker.itemId });
+    } else {
+      // A 429 during resume must open the breaker so subsequent spawns gate.
+      if (rateGuard.classifyStderr(stderr)) {
+        try { rateGuard.recordRateLimit(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR }); } catch { /* */ }
+      }
+      logSession({ event: "resume_exit_nonzero", sessionId: marker.sessionId, item_id: marker.itemId, exit_code: code });
+    }
+  });
+  proc.on("error", (err) => {
+    logSession({ event: "resume_spawn_error", sessionId: marker.sessionId, error: err.code || err.message });
+  });
+}
+
+function writeActiveSession(sessionId, entry) {
+  try {
+    let active = {};
+    try { active = JSON.parse(readFileSync(ACTIVE_PATH, "utf-8")); } catch {}
+    active[sessionId] = {
+      sender: entry.item?.sender || null,
+      channel: entry.item?.channel || entry.item?.channel_id || null,
+      summary: entry.classResult?.summary || "unknown",
+      model: entry.classResult?.model || "sonnet",
+      startTime: Date.now(),
+      source: entry.source,
+    };
+    const tmpPath = ACTIVE_PATH + ".tmp";
+    writeFileSync(tmpPath, JSON.stringify(active, null, 2));
+    renameSync(tmpPath, ACTIVE_PATH);
+  } catch (err) {
+    console.warn(`[dispatcher] Failed to write active.json: ${err.message}`);
+  }
+}
+
+function removeActiveSession(sessionId) {
+  try {
+    let active = {};
+    try { active = JSON.parse(readFileSync(ACTIVE_PATH, "utf-8")); } catch {}
+    delete active[sessionId];
+    const tmpPath = ACTIVE_PATH + ".tmp";
+    writeFileSync(tmpPath, JSON.stringify(active, null, 2));
+    renameSync(tmpPath, ACTIVE_PATH);
+  } catch (err) {
+    console.warn(`[dispatcher] Failed to update active.json: ${err.message}`);
+  }
+}
+
+/**
+ * Count active sessions by source type.
+ */
+function countBySource(source) {
+  let count = 0;
+  for (const [, s] of activeSessions) {
+    if (s.source === source) count++;
+  }
+  return count;
+}
+
+/**
+ * Evict the lowest-priority, longest-running backlog session to make room
+ * for a high-priority inbox item. Returns true if a session was evicted.
+ */
+function evictForPriority() {
+  const priorityRank = { low: 0, normal: 1, high: 2, critical: 3 };
+  let worst = null;
+  let worstId = null;
+
+  for (const [id, s] of activeSessions) {
+    if (s.source !== "backlog") continue;
+    const rank = priorityRank[s.classResult.priority] || 1;
+    if (!worst) {
+      worst = s; worstId = id;
+      continue;
+    }
+    const worstRank = priorityRank[worst.classResult.priority] || 1;
+    // Prefer to evict lower priority; break ties by oldest session
+    if (rank < worstRank || (rank === worstRank && s.startTime < worst.startTime)) {
+      worst = s; worstId = id;
+    }
+  }
+
+  if (worst) {
+    console.log(`[dispatcher] PREEMPT: Evicting backlog session ${worstId} (${worst.classResult.summary}) for priority inbox item`);
+    logSession({ event: "evicted", sessionId: worstId, reason: "priority_preemption", summary: worst.classResult.summary });
+    // M2: clear the resume-pending marker BEFORE the SIGTERM. Eviction is a
+    // deliberate preemption, not a crash — the item stays on disk and the
+    // backlog sweep re-dispatches it normally (acquiring the item-claim).
+    // If we left the marker, a reboot's reconcileResumePending would re-spawn
+    // it WITHOUT the claim while sweepBacklog independently claim+dispatched
+    // the same item → two concurrent runs. The non-zero SIGTERM close would
+    // otherwise keep the marker, so we must retire it here.
+    clearResumePending(worstId);
+    worst.process.kill("SIGTERM");
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Generate a stable key for a backlog item to track in-flight status.
+ */
+function backlogKey(item) {
+  return item.id || item.title || item.summary || JSON.stringify(item).substring(0, 100);
+}
+
+/**
+ * Check if a backlog item already has an active session or has exceeded retry limit.
+ * Returns { allowed: boolean, reason?: string }
+ */
+export function canDispatchBacklog(item) {
+  const key = backlogKey(item);
+  if (activeBacklogKeys.has(key)) {
+    return { allowed: false, reason: "session_already_active" };
+  }
+  const retries = backlogRetryCount.get(key) || 0;
+  if (retries >= MAX_BACKLOG_RETRIES) {
+    return { allowed: false, reason: "max_retries_exceeded", retries };
+  }
+  // Post-completion cooldown — prevent every-2-min re-dispatch of items
+  // that completed (success or failure) within the recent window.
+  const cooldownUntil = backlogCooldownUntil.get(key) || 0;
+  if (cooldownUntil > Date.now()) {
+    const remaining_min = Math.ceil((cooldownUntil - Date.now()) / 60000);
+    return { allowed: false, reason: "post_completion_cooldown", remaining_min };
+  }
+  return { allowed: true };
+}
+
+/**
+ * Dispatch an item for processing.
+ *
+ * @param {string} prompt
+ * @param {object} item
+ * @param {object} classResult
+ * @param {string} source - "inbox" or "backlog"
+ * @param {object} [opts]
+ * @param {(result:{ok:boolean, sessionId:string|null, item:object, code:number|null, stdout:string})=>void} [opts.onClose]
+ *   Invoked EXACTLY ONCE when the spawned session reaches a terminal state
+ *   (clean close → ok:true; non-zero close OR spawn error → ok:false). Lets the
+ *   caller defer finalizing the inbox item (markProcessed) to spawn-close success
+ *   so a crash between dispatch and close leaves the item re-deliverable rather
+ *   than prematurely `.processed` (F1/H2 message-loss window). The callback
+ *   survives queueing (it's carried on the entry, so a QUEUE/DEFER'd item still
+ *   fires onClose once it is later drained and spawned). It does NOT fire on the
+ *   pre-spawn drop paths (backlog dedup / claim-denied / governor-DEFER backlog),
+ *   which leave the durable on-disk item untouched for the next sweep anyway.
+ */
+export function dispatch(prompt, item, classResult, source = "inbox", opts = {}) {
+  const entry = { prompt, item, classResult, source, onClose: typeof opts.onClose === "function" ? opts.onClose : null };
+  const priority = classResult.priority;
+  const isPriorityInbox = source === "inbox" && (priority === "critical" || priority === "high");
+
+  // Backlog items: check dedup and retry limits
+  if (source === "backlog") {
+    const check = canDispatchBacklog(item);
+    if (!check.allowed) {
+      logSession({ event: "skipped", reason: check.reason, summary: classResult.summary, retries: check.retries });
+      return;
+    }
+  }
+
+  // ── WS4 governance gate ──────────────────────────────────────────────────
+  // Consult the shared 429 breaker + the resource governor BEFORE claiming a
+  // backlog item, so a DEFER leaves the item untouched on disk (the 10-min
+  // sweep retries it — no work lost, no retry budget burned). For inbox, a
+  // non-ADMIT routes to the in-memory queue instead of spawning (the user's
+  // message is never dropped). Priority inbox can still preempt a backlog
+  // session below. `forceQueue` carries the decision to the spawn branch.
+  let forceQueue = false;
+  let queueReason = null;
+  let queueRetryAt = null; // M1: when the breaker says "retry after T", arm a re-drain then.
+  {
+    const rb = rateBlocked();
+    if (rb) {
+      if (source === "backlog") {
+        logSession({ event: "deferred", reason: "rate_limited", retry_at: rb.retryAt, summary: classResult.summary });
+        return; // leave on disk; sweep retries after the breaker closes
+      }
+      forceQueue = true; queueReason = "rate_limited"; queueRetryAt = rb.retryAt || null;
+    }
+    if (!forceQueue || source !== "inbox") {
+      const adm = admitFor(source, priority);
+      if (adm.decision !== "ADMIT") {
+        if (source === "backlog") {
+          // QUEUE and DEFER both mean "not now" for backlog — the item stays in
+          // its queue file (re-derivable, durable) and the sweep retries. We do
+          // NOT claim it and we do NOT burn retry budget.
+          logSession({ event: adm.decision === "DEFER" ? "deferred" : "queued_skip", reason: adm.reason, decision: adm.decision, source, summary: classResult.summary });
+          return;
+        }
+        // inbox: never drop — queue it (DEFER(inbox) → queue anyway).
+        forceQueue = true; queueReason = queueReason || adm.reason;
+      }
+    }
+  }
+
+  // Item-claim acquisition: file-based claim visible across daemon restarts
+  // and concurrent launchd triggers. Complements the in-memory activeBacklogKeys.
+  // (ib-20260407-001b: concurrent session coordination)
+  if (source === "backlog" && item.id) {
+    const sessionId = `s-${Date.now()}-${sessionCounter + 1}`;
+    const claim = claimItem(item.id, {
+      session_id: sessionId,
+      agent_description: classResult.summary || item.title || "",
+      ttl_minutes: classResult.model === "opus" ? 120 : 30,
+      source: "backlog",
+      queue_file: item.source_file || "",
+      pid: process.pid, // daemon PID; child PID not yet known
+    });
+    if (!claim.claimed) {
+      console.log(`[dispatcher] Item claim denied for ${item.id}: ${claim.reason} (holder: ${claim.holder || "unknown"})`);
+      logSession({ event: "skipped", reason: `item_claim_denied: ${claim.reason}`, summary: classResult.summary, holder: claim.holder });
+      return;
+    }
+  }
+
+  // Backlog items respect the reserved slot cap
+  if (source === "backlog") {
+    const backlogCount = countBySource("backlog");
+    const backlogCap = MAX_CONCURRENT - RESERVED_INBOX_SLOTS;
+    if (backlogCount >= backlogCap) {
+      // No room for more backlog — silently skip (don't queue indefinitely)
+      return;
+    }
+  }
+
+  // forceQueue (WS4): the governor/breaker said "not now" for this inbox item,
+  // OR all slots are full. Either way we don't spawn directly — but a priority
+  // inbox item may still preempt a running backlog session.
+  if (!forceQueue && activeSessions.size < MAX_CONCURRENT) {
+    spawnSession(entry);
+  } else if (isPriorityInbox) {
+    // Priority inbox item but no slots (or governor-gated) — try to evict a
+    // backlog session. (Eviction is only useful under capacity pressure; under
+    // a rate-limit/budget gate there may be nothing to evict, in which case it
+    // simply queues — still never dropped.)
+    if (evictForPriority()) {
+      // Session evicted; it will call drainQueue on close. Queue this item at front.
+      priorityQueue.unshift(entry);
+      logSession({ event: "queued_after_eviction", priority: classResult.priority, summary: classResult.summary, reason: queueReason });
+    } else {
+      // No backlog sessions to evict — queue normally
+      priorityQueue.push(entry);
+      logSession({ event: "queued", priority: classResult.priority, summary: classResult.summary, queue_position: priorityQueue.length, reason: queueReason });
+    }
+  } else if (classResult.priority === "critical" || classResult.priority === "high") {
+    priorityQueue.push(entry);
+    logSession({ event: "queued", priority: classResult.priority, summary: classResult.summary, queue_position: priorityQueue.length, reason: queueReason });
+  } else {
+    normalQueue.push(entry);
+    logSession({ event: "queued", priority: classResult.priority, summary: classResult.summary, queue_position: normalQueue.length, reason: queueReason });
+  }
+
+  // M1: a governor/budget/rate DEFER can now force-queue an inbox item while
+  // NO session is running (pre-WS4 an item was only ever queued behind a
+  // running session, whose close drains). With zero active sessions nothing
+  // wakes the queue until the next external dispatch — so the item could stall
+  // indefinitely. Arm a single debounced re-drain timer to self-heal. The
+  // 60s inbox re-scan can't double-dispatch this: the item-claim / sent-message
+  // dedupe already guards that, and drainQueue itself re-checks admission.
+  if (activeSessions.size === 0 && (priorityQueue.length > 0 || normalQueue.length > 0)) {
+    armReDrain(queueRetryAt);
+  }
+}
+
+// ── M1: re-drain timer (single, debounced) ──────────────────────────────────
+// Only ONE timer is ever pending. Arming again while one is live is a no-op
+// (we never stack timers). Cleared whenever a real drain runs.
+const RE_DRAIN_MIN_MS = 15_000;  // floor: don't busy-poll the governor
+const RE_DRAIN_MAX_MS = 30_000;  // ceiling: bound worst-case stall to 30s
+let reDrainTimer = null;
+
+/**
+ * Arm a one-shot re-drain. `retryAt` (epoch ms, optional) is the breaker's
+ * "safe to retry after" hint; we clamp the delay into [15s, 30s] so we neither
+ * hammer the governor nor leave an item parked too long. Debounced: a second
+ * call while a timer is pending does nothing.
+ */
+function armReDrain(retryAt) {
+  if (reDrainTimer) return; // already armed — debounce
+  let delay = RE_DRAIN_MAX_MS;
+  if (typeof retryAt === "number" && retryAt > 0) {
+    delay = Math.max(RE_DRAIN_MIN_MS, Math.min(RE_DRAIN_MAX_MS, retryAt - Date.now()));
+  }
+  reDrainTimer = setTimeout(() => {
+    reDrainTimer = null;
+    try { drainQueue(); } catch (err) { console.warn(`[dispatcher] re-drain failed: ${err.message}`); }
+  }, delay);
+  // Don't let this timer pin the event loop alive on its own (mirrors the
+  // socket-mode supervisor's unref pattern).
+  if (reDrainTimer && typeof reDrainTimer.unref === "function") reDrainTimer.unref();
+}
+
+/** Test seam: report whether a re-drain timer is currently armed. */
+export function _hasReDrainArmed() {
+  return reDrainTimer !== null;
+}
+
+/**
+ * Current budget band (0|75|90|100) from budget-guard's daily spend vs the
+ * config/recovery.yaml cap, mapped onto the economics ladder. Fed into
+ * resolveChain so a chain degrades (frontier→default→fast→cheap) as the day's
+ * spend climbs (SPEC §6.4). Best-effort: any read failure → band 0 (policy as
+ * written) so a budget-read bug never changes routing under us.
+ */
+function currentBudgetBand() {
+  try {
+    const st = budgetGuard.dailyStatus({ agentRoot: AGENT_REPO_DIR });
+    return budgetLadder(st.spentUSD, st.capUSD).band;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Resolve the spawn target through the v2 router (resolveChain) when the agent
+ * has opted into a `schema_version: 2` config, else fall back to the v1
+ * resolveBackend path (byte-compatible). Returns a normalised shape the spawn
+ * path consumes regardless of which router produced it:
+ *
+ *   { modelFlag, envForSpawn, decisionId, backend, model, transport,
+ *     maxTurns, effort, agentsJson, explain, decision }
+ *
+ * NEVER throws — any router error degrades to the v1 path (or null → stock CLI).
+ * The kill switch (MAESTRO_ROUTER_FORCE_ANTHROPIC) is honoured INSIDE both
+ * resolveChain and resolveBackend, so it short-circuits to stock Anthropic
+ * either way.
+ *
+ * @param {object} routingConfig  loaded config (v1 or v2) or null
+ * @param {object} routingRequest v1 AgentRequest (from requestFromClassifierResult)
+ * @param {object} classResult
+ * @param {string} source
+ * @param {string} fallbackModel  the coarse sonnet/opus class for the no-config path
+ */
+function resolveSpawnTarget(routingConfig, routingRequest, classResult, source, fallbackModel) {
+  // No config at all → stock Claude-CLI-on-Max behaviour (unchanged).
+  if (!routingConfig) {
+    return { modelFlag: fallbackModel, envForSpawn: {}, decisionId: null, backend: null, model: null, transport: "anthropic-cli", maxTurns: null, effort: null, agentsJson: null, explain: null, decision: null };
+  }
+
+  // v2 path — resolveChain produces a full RouteDecision.
+  if (routingConfig.schema_version === 2) {
+    try {
+      const taskClass = "session.responder";
+      const req = {
+        ...routingRequest,
+        task_class: taskClass,
+        // data_class is DERIVED from the channel/source, never model-chosen
+        // (SPEC §7.6): inbox traffic is sensitive; backlog is internal work.
+        data_class: source === "inbox" ? "sensitive" : "internal",
+        budget_band: currentBudgetBand(),
+        harness_hint: "session",
+      };
+      const decision = resolveChain(req, { config: routingConfig, agentRoot: AGENT_REPO_DIR });
+      if (decision && decision.chosen) {
+        // Spawn knobs default per task_class; a rule may have overridden them on
+        // the decision (decision.spawnArgs wins where present).
+        const knobs = spawnKnobsFor(taskClass);
+        const sa = decision.spawnArgs || {};
+        return {
+          modelFlag: sa.modelFlag || decision.chosen.model || fallbackModel,
+          envForSpawn: decision.envForSpawn || {},
+          decisionId: decision.decision_id || null,
+          backend: decision.chosen.provider || null,
+          model: decision.chosen.model || null,
+          transport: decision.chosen.transport || null,
+          maxTurns: sa.maxTurns != null ? sa.maxTurns : knobs.maxTurns,
+          effort: sa.effort != null ? sa.effort : knobs.effort,
+          agentsJson: sa.agentsJson != null ? sa.agentsJson : knobs.agentsJson,
+          explain: decision.explain || null,
+          decision,
+        };
+      }
+    } catch (err) {
+      console.warn(`[dispatcher] resolveChain failed, falling back to v1 resolver: ${err.message}`);
+    }
+    // resolveChain degraded — fall through to v1 below.
+  }
+
+  // v1 path — resolveBackend → modelFlagFor (preserved verbatim).
+  const resolved = resolveBackend(routingRequest, { config: routingConfig });
+  if (!resolved) {
+    return { modelFlag: fallbackModel, envForSpawn: {}, decisionId: null, backend: null, model: null, transport: "anthropic-cli", maxTurns: null, effort: null, agentsJson: null, explain: null, decision: null };
+  }
+  return {
+    modelFlag: modelFlagFor(resolved, routingRequest),
+    envForSpawn: resolved.envForSpawn || {},
+    decisionId: null,
+    backend: resolved.name || null,
+    model: resolved.model || null,
+    transport: resolved.transport || null,
+    maxTurns: null,
+    effort: null,
+    agentsJson: null,
+    explain: null,
+    decision: null,
+    _v1Resolved: resolved,
+  };
+}
+
+function spawnSession(entry) {
+  const { prompt, item, classResult, source } = entry;
+  const sessionId = `s-${Date.now()}-${++sessionCounter}`;
+
+  // F1/H2: notify the dispatch caller exactly once when this session reaches a
+  // terminal state, so it can finalize the inbox item on success and re-deliver
+  // on crash. Single-fire guard — both proc.on("close") (clean + non-zero) and
+  // proc.on("error") (spawn failure) route here, and the close handler can run
+  // after error on the ENOENT/ETIMEDOUT path; we must invoke onClose only once.
+  //
+  // The callback also receives the run's raw `stdout` (already buffered here for
+  // the cost ledger) so the caller can apply POST-SESSION OUTCOME DISCIPLINE —
+  // reading the turn's commitments off its final text and landing them through
+  // the org protocol (scripts/daemon/session-outcomes.mjs). Purely additive: the
+  // field is new, existing callers destructure what they already used.
+  let onCloseFired = false;
+  const fireOnClose = (ok, code, closeStdout = "") => {
+    if (onCloseFired || !entry.onClose) return;
+    onCloseFired = true;
+    try { entry.onClose({ ok, sessionId, item, code, stdout: closeStdout }); }
+    catch (err) { console.warn(`[dispatcher] onClose callback threw for ${sessionId}: ${err.message}`); }
+  };
+  const model = classResult.model || "sonnet";
+  const timeout = model === "opus"
+    ? (source === "backlog" ? OPUS_BACKLOG_TIMEOUT : OPUS_INBOX_TIMEOUT)
+    : (source === "backlog" ? SONNET_BACKLOG_TIMEOUT : SONNET_INBOX_TIMEOUT);
+
+  // Track backlog items to prevent retry storms
+  if (source === "backlog") {
+    const key = backlogKey(item);
+    activeBacklogKeys.add(key);
+    backlogRetryCount.set(key, (backlogRetryCount.get(key) || 0) + 1);
+  }
+
+  // Resolve the spawn target via the model router. v2 configs go through
+  // resolveChain (full RouteDecision: model + retarget env + spawn knobs +
+  // decision_id + estimated cost + failover chain); v1 configs keep the legacy
+  // resolveBackend path; no config preserves the historical Claude-CLI-on-Max
+  // default exactly. NEVER throws (resolveSpawnTarget degrades internally).
+  const routingConfig = getRoutingConfig();
+  const routingRequest = requestFromClassifierResult(classResult, { source, role: "responder" });
+  const target = resolveSpawnTarget(routingConfig, routingRequest, classResult, source, model);
+  const effectiveModelFlag = target.modelFlag || model;
+
+  // WS4: pre-mint a stable Claude session id so a crash/reboot mid-flight can
+  // be resumed deterministically with `claude --print --resume <id>`. (Same
+  // mechanism the responder already uses; safe in --print text mode.)
+  const claudeSessionId = randomUUID();
+
+  // The v2 router supplies spawn knobs (SPEC §4.4 / §6.5): --max-turns bounds
+  // the session, --effort tunes reasoning where supported, --agents attaches the
+  // cheap-subagent (Haiku-Explore) fan-out map — the sanctioned intra-session
+  // cost lever that keeps the main loop's cache intact. v1 / no-config spawns
+  // carry none of these (knobs are null), so this is purely additive.
+  const knobArgs = [];
+  if (target.maxTurns != null && Number.isFinite(Number(target.maxTurns))) {
+    knobArgs.push("--max-turns", String(target.maxTurns));
+  }
+  if (target.effort) knobArgs.push("--effort", String(target.effort));
+  if (target.agentsJson) {
+    knobArgs.push("--agents", typeof target.agentsJson === "string" ? target.agentsJson : JSON.stringify(target.agentsJson));
+  }
+
+  const args = [
+    "--print",
+    // --output-format json so this run's stdout carries the REAL token usage we
+    // record to the cost ledger (recovery C1). The dispatcher's stdout is only
+    // tee'd to a per-session log file — it's never streamed to the user (the
+    // session sends its own user-facing messages via the Slack/Gmail APIs), so
+    // switching the format does not affect any reply.
+    "--output-format", "json",
+    ...sessionPermissionArgs({ source: "dispatcher", priority: classResult?.priority }),
+    ...daemonClaudeArgs(),
+    ...knobArgs,
+    "--session-id", claudeSessionId,
+    "--model", effectiveModelFlag,
+    prompt,
+  ];
+
+  // Build the spawn env.
+  //   Default (no router): strip ANTHROPIC_API_KEY/ANTHROPIC_AUTH_TOKEN so
+  //   `claude` falls through to the keychain OAuth (Max subscription) per
+  //   CEO directive 2026-04-27.
+  //   Router active: merge the resolved target's envForSpawn — this points the
+  //   CLI at the chosen backend (Moonshot, OpenRouter, NIM, etc.) and sets
+  //   ANTHROPIC_API_KEY="" explicitly so Claude Code doesn't fall back to
+  //   OAuth against api.anthropic.com.
+  //
+  // For a v2 retarget (envForSpawn carries ANTHROPIC_BASE_URL), we build the
+  // child env through the execution layer's buildChildEnv so the §7.3 allowlist
+  // scrub applies (no foreign *_API_KEY / *_AUTH_TOKEN leaks into a third-party
+  // session). buildChildEnv already injects ANTHROPIC_API_KEY="" for a retarget.
+  // For the common Anthropic-session case (envForSpawn === {}) and the v1 path
+  // we keep the prior explicit empty-key env verbatim (byte-compatible).
+  const retargeting = !!(target.envForSpawn && target.envForSpawn.ANTHROPIC_BASE_URL);
+  const spawnEnv = retargeting
+    ? { ...buildChildEnv({ ...process.env, PATH: augmentedPath() }, target.envForSpawn), PATH: augmentedPath() }
+    : {
+        ...process.env,
+        PATH: augmentedPath(),
+        ANTHROPIC_API_KEY: "",
+        ANTHROPIC_AUTH_TOKEN: "",
+        ...(target.envForSpawn || {}),
+      };
+
+  const proc = _spawn(CLAUDE_BIN, args, {
+    cwd: AGENT_REPO_DIR,
+    env: spawnEnv,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  // Log the routing outcome whenever a backend was actually chosen (v1 or v2)
+  // and it isn't the stock Anthropic CLI no-op. The v2 path also carries the
+  // decision_id + the one-line explain so `maestro router why` can join this
+  // session to its routing-audit + ledger rows.
+  if (target.backend && target.transport !== "anthropic-cli") {
+    logSession({
+      event: "routed",
+      sessionId,
+      decision_id: target.decisionId,
+      backend: target.backend,
+      transport: target.transport,
+      model: target.model,
+      tried: target.decision ? target.decision.tried : target._v1Resolved?.tried,
+      fallback_reason: target.decision ? target.decision.audit?.fallback_reason : target._v1Resolved?.fallback_reason,
+      explain: target.explain,
+    });
+  }
+
+  let stdout = "";
+  let stderr = "";
+  const logFile = join(sessionLogDir(), `${sessionId}.log`);
+
+  proc.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+  proc.stderr.on("data", (chunk) => { stderr += chunk.toString(); });
+
+  const timer = setTimeout(() => {
+    console.error(`[dispatcher] Session ${sessionId} timed out (${timeout / 1000}s), killing`);
+    proc.kill("SIGTERM");
+    const killTimer = setTimeout(() => { if (!proc.killed) proc.kill("SIGKILL"); }, 5000);
+    if (killTimer && typeof killTimer.unref === "function") killTimer.unref();
+  }, timeout);
+  // A kill-watchdog must never be the sole handle pinning the event loop open
+  // (mirrors the re-drain timer above). It is cleared on every close path below;
+  // unref only ensures a leaked/never-closed session (e.g. a test fake-spawn that
+  // never emits "close") can't hold the process — otherwise the test suite would
+  // wait out the full session timeout before exiting.
+  if (timer && typeof timer.unref === "function") timer.unref();
+
+  const startTime = Date.now();
+  activeSessions.set(sessionId, { process: proc, item, classResult, startTime, model, source, claudeSessionId });
+  writeActiveSession(sessionId, entry);
+
+  // WS4: drop the in-flight resume marker. Present-after-crash = mid-flight, so
+  // a startup reconcile can re-dispatch `claude --print --resume`. Cleared on a
+  // clean close below. Inbox sessions are short and user-facing; backlog
+  // sessions are the ones that most benefit from surviving a reboot, but we mark
+  // both uniformly — the freshness window + 3-strike cap bound any churn.
+  writeResumePending(sessionId, { ...entry, recoveryAttempts: entry.recoveryAttempts }, claudeSessionId, effectiveModelFlag, target.decisionId);
+
+  // WS2: show a typing indicator on the originating channel while the session
+  // works (inbox items only — backlog work has no waiting human). Best-effort
+  // via the typing registry; channels without a live adapter no-op.
+  if (source === "inbox") {
+    try { startTyping(item); } catch { /* fail-open */ }
+  }
+
+  logSession({
+    event: "spawned",
+    sessionId,
+    model,
+    source,
+    priority: classResult.priority,
+    summary: classResult.summary,
+    active_count: activeSessions.size,
+  });
+
+  // Observability: the interaction's trace_id rode in on item.trace_id (set by
+  // the daemon at item_received); read it explicitly here because the close/error
+  // handlers below fire on a separate event-loop tick, outside any withTrace
+  // scope. `dispatched` marks the spawn decision; `session_opened` the sub-session
+  // start. Both carry trace_id + the v2 decision_id so the audit can join the
+  // routing decision ↔ ledger row ↔ diagnostic stream.
+  const traceId = (item && typeof item.trace_id === "string") ? item.trace_id : null;
+  emitEvent({
+    type: EVENT_TYPES.DISPATCHED,
+    trace_id: traceId,
+    attrs: { session_id: sessionId, source, model, decision_id: target.decisionId || null, priority: classResult.priority },
+  });
+  emitEvent({
+    type: EVENT_TYPES.SESSION_OPENED,
+    trace_id: traceId,
+    attrs: { session_id: sessionId, source, model, decision_id: target.decisionId || null },
+  });
+
+  console.log(`[dispatcher] Spawned ${sessionId} (${model}) — ${classResult.summary} [${activeSessions.size}/${MAX_CONCURRENT}]`);
+
+  proc.on("close", (code) => {
+    clearTimeout(timer);
+    // WS2: stop the typing heartbeat for this conversation (mirrors the
+    // promoteDeferred close-hook). Best-effort; fail-open.
+    if (source === "inbox") { try { stopTyping(item); } catch { /* */ } }
+    // If proc.on("error") already fired for this session (spawn failure path
+    // — ENOENT, EACCES, ETIMEDOUT), cleanup + metric + lock release already
+    // happened. Skip to avoid double-count and double-release.
+    if (spawnErrorHandled.has(sessionId)) {
+      spawnErrorHandled.delete(sessionId);
+      clearResumePending(sessionId); // error path already terminal — no resume
+      // The error handler already fired onClose(ok:false) AND emitted
+      // session_closed; the single-fire guard makes the onClose a no-op, and we
+      // do NOT re-emit session_closed here to keep it exactly-once per session.
+      fireOnClose(false, code);
+      drainQueue();
+      return;
+    }
+    activeSessions.delete(sessionId);
+    removeActiveSession(sessionId);
+    recordSession(true, code === 0);
+    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+
+    // WS4: a clean exit retires the resume marker (work finished — nothing to
+    // resume) and closes the shared 429 breaker. A non-zero exit whose stderr
+    // looks like a rate limit opens the breaker so ALL spawn sources back off
+    // together. The marker is deliberately LEFT in place on a non-zero exit so
+    // a subsequent reboot can still resume the work; the cooldown/strike caps
+    // bound re-dispatch.
+    if (code === 0) {
+      clearResumePending(sessionId);
+      try { rateGuard.recordSuccess(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR }); } catch { /* */ }
+    } else if (rateGuard.classifyStderr(stderr)) {
+      try {
+        const rec = rateGuard.recordRateLimit(RATE_PROVIDER, { agentRoot: AGENT_REPO_DIR });
+        logSession({ event: "rate_limit_recorded", sessionId, open_until: rec.openUntil, consecutive: rec.consecutive429 });
+      } catch { /* */ }
+    }
+
+    // Release item lock — MUST use same key order as acquireLock in daemon
+    // (raw_ref first, then id). Previously this used id || raw_ref, creating
+    // a different sanitised filename so the release silently missed the lock.
+    const itemId = item.raw_ref || item.id || item.title;
+    if (itemId) releaseLock(itemId);
+
+    // Release thread/channel lock so new messages in this thread/DM can
+    // be processed. We must release unconditionally when a channel is
+    // known — the previous `if (item.thread_id)` gate skipped DMs (which
+    // always have empty thread_id), so DM-channel locks never cleared
+    // until the 60min TTL fired. acquireThreadLock normalises DM
+    // channels to `dm-channel` internally; releaseThreadLock mirrors
+    // that normalisation, so calling it with an empty thread_id on a
+    // DM channel does the right thing.
+    {
+      const channel = item.channel_id || (item.raw_ref ? (item.raw_ref.match(/slack:([^:]+):/) || [])[1] : null) || item.channel;
+      if (channel) {
+        releaseThreadLock(channel, item.thread_id);
+        // Now that the lock is gone, promote any messages that were
+        // deferred behind it. Latest-wins: a burst of N messages
+        // collapses into ONE re-dispatch carrying the most recent
+        // message (its thread_context already includes the earlier
+        // ones), so the user gets a single coherent reply rather than
+        // N replies serialised over N session-durations.
+        const promo = promoteDeferred(channel, AGENT_REPO_DIR);
+        if (promo.promoted > 0) {
+          logSession({
+            event: "deferred_promoted",
+            channel,
+            promoted: promo.promoted,
+            bundled: promo.bundled,
+            service: promo.service,
+          });
+        }
+      }
+    }
+
+    // Release request claim so the same type of request can be processed again
+    if (classResult && classResult.summary) {
+      releaseRequestClaim({
+        recipient: item.channel_id || item.channel || item.sender || "unknown",
+        subject: classResult.summary || item.subject || "",
+        action_type: classResult.action || "respond",
+      });
+    }
+
+    // Release backlog tracking + item claim
+    if (source === "backlog") {
+      const key = backlogKey(item);
+      activeBacklogKeys.delete(key);
+      const retries = backlogRetryCount.get(key) || 0;
+
+      // Apply post-completion cooldown — different for success vs failure.
+      // This is the fix for the every-2-min re-dispatch loop: once a
+      // session has touched an item, we wait before touching it again.
+      const cooldownMs = code === 0 ? SUCCESS_COOLDOWN_MS : FAILURE_COOLDOWN_MS;
+      backlogCooldownUntil.set(key, Date.now() + cooldownMs);
+      saveCooldowns();
+      logSession({
+        event: "cooldown_set",
+        summary: classResult.summary,
+        exit_code: code,
+        cooldown_minutes: Math.round(cooldownMs / 60000),
+      });
+
+      // Release file-based item claim (ib-20260407-001b)
+      if (item.id) releaseItemClaim(item.id);
+
+      // If session timed out (143=SIGTERM) and hit retry limit, log it
+      if (code === 143 && retries >= MAX_BACKLOG_RETRIES) {
+        console.warn(`[dispatcher] Backlog item "${classResult.summary}" exhausted ${MAX_BACKLOG_RETRIES} retries — will not retry`);
+        logSession({ event: "retries_exhausted", summary: classResult.summary, retries });
+      }
+    }
+
+    // Write session log
+    writeFileSync(logFile, `# Session ${sessionId}\n# Model: ${model}\n# Duration: ${duration}s\n# Exit: ${code}\n\n## STDOUT\n${stdout}\n\n## STDERR\n${stderr}\n`);
+
+    // Record a TRUTHFUL cost-ledger row from this run's real token usage
+    // (recovery C1) — the dispatcher is the user-facing spawn source and was
+    // previously invisible to budget-guard. Parse failures are surfaced, not
+    // backfilled with fake zeros.
+    const costUsage = recordDispatcherCost({
+      stdout,
+      model: effectiveModelFlag,
+      durationMs: Date.now() - startTime,
+      exitCode: code,
+      decisionId: target.decisionId,
+    });
+    if (!costUsage.ok) {
+      logSession({ event: "cost_usage_parse_failed", sessionId, reason: costUsage.reason });
+    }
+
+    logSession({
+      event: "completed",
+      sessionId,
+      model,
+      source,
+      exit_code: code,
+      duration_s: parseFloat(duration),
+      summary: classResult.summary,
+      active_count: activeSessions.size,
+    });
+
+    // Observability: the sub-session ended. Carry the interaction's trace_id +
+    // decision_id so item_received → dispatched → session_opened → session_closed
+    // (→ sent, emitted by the daemon's onClose) all group by one id.
+    emitEvent({
+      type: EVENT_TYPES.SESSION_CLOSED,
+      trace_id: traceId,
+      attrs: { session_id: sessionId, source, exit_code: code, duration_s: parseFloat(duration), decision_id: target.decisionId || null },
+    });
+
+    console.log(`[dispatcher] Session ${sessionId} done (${duration}s, exit ${code}) [${activeSessions.size}/${MAX_CONCURRENT}]`);
+
+    // F1/H2: tell the caller this session reached a terminal state. A clean exit
+    // (code 0) finalizes the inbox item (markProcessed); any non-zero exit leaves
+    // it re-deliverable. Fired AFTER lock/claim release above so the caller's
+    // re-delivery path (which may release the per-item lock) doesn't race them.
+    fireOnClose(code === 0, code, stdout);
+
+    // Dispatch next queued item
+    drainQueue();
+  });
+
+  proc.on("error", (err) => {
+    clearTimeout(timer);
+    // WS2: stop the typing heartbeat (the session never really ran).
+    if (source === "inbox") { try { stopTyping(item); } catch { /* */ } }
+    // Mark so the trailing proc.on("close") doesn't double-process.
+    spawnErrorHandled.add(sessionId);
+    activeSessions.delete(sessionId);
+    removeActiveSession(sessionId);
+    // Spawn never ran — there is nothing to resume; retire the marker so the
+    // next startup reconcile doesn't try to --resume a session that never began.
+    clearResumePending(sessionId);
+    recordSession(true, false);
+    const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+    const errorCode = err.code || "unknown";
+
+    // Release item lock — mirror of close-handler logic.
+    const itemId = item.raw_ref || item.id || item.title;
+    if (itemId) releaseLock(itemId);
+
+    // Release thread/channel lock so new messages can be processed.
+    // Mirror of close-handler logic — unconditional when channel is
+    // known, since releaseThreadLock handles the DM normalization.
+    {
+      const channel = item.channel_id || (item.raw_ref ? (item.raw_ref.match(/slack:([^:]+):/) || [])[1] : null) || item.channel;
+      if (channel) {
+        releaseThreadLock(channel, item.thread_id);
+        const promo = promoteDeferred(channel, AGENT_REPO_DIR);
+        if (promo.promoted > 0) {
+          logSession({
+            event: "deferred_promoted_on_error",
+            channel,
+            promoted: promo.promoted,
+            bundled: promo.bundled,
+            service: promo.service,
+          });
+        }
+      }
+    }
+
+    // Release request claim + emit explicit claim_released event so
+    // reconciliation audits (cycle 124 Agent C pattern) can distinguish
+    // genuine in-flight sessions from silent-exit ETIMEDOUT failures
+    // without cross-referencing logs/daemon/responses.jsonl.
+    let claimReleased = false;
+    if (classResult && classResult.summary) {
+      releaseRequestClaim({
+        recipient: item.channel_id || item.channel || item.sender || "unknown",
+        subject: classResult.summary || item.subject || "",
+        action_type: classResult.action || "respond",
+      });
+      claimReleased = true;
+    }
+
+    // Release backlog tracking + item claim. Apply failure cooldown so the
+    // same item isn't re-spawned on the next backlog sweep.
+    if (source === "backlog") {
+      const key = backlogKey(item);
+      activeBacklogKeys.delete(key);
+      backlogCooldownUntil.set(key, Date.now() + FAILURE_COOLDOWN_MS);
+      saveCooldowns();
+      // Release file-based item claim (ib-20260407-001b)
+      if (item.id) releaseItemClaim(item.id);
+    }
+
+    console.error(`[dispatcher] Session ${sessionId} failed: ${errorCode} (${err.message})`);
+
+    // Rich "failed" event — see ib-20260416-daemon-etimedout-failed-event.
+    logSession({
+      event: "failed",
+      sessionId,
+      error: errorCode,
+      error_message: err.message,
+      model,
+      source,
+      priority: classResult?.priority,
+      summary: classResult?.summary,
+      duration_s: parseFloat(duration),
+      active_count: activeSessions.size,
+    });
+
+    if (claimReleased) {
+      logSession({
+        event: "claim_released",
+        sessionId,
+        reason: `spawn_failed_${errorCode}`,
+      });
+    }
+
+    // Observability: a spawn failure is a terminal close too. Emit session_closed
+    // (exit_code null, error code carried) so the audit sees every session reach a
+    // terminal hop. Exactly-once: the trailing proc.on("close") early-returns via
+    // the spawnErrorHandled guard WITHOUT re-emitting.
+    emitEvent({
+      type: EVENT_TYPES.SESSION_CLOSED,
+      trace_id: traceId,
+      attrs: { session_id: sessionId, source, exit_code: null, error: errorCode, decision_id: target.decisionId || null },
+    });
+
+    // F1/H2: a spawn failure is terminal and the work never ran — tell the caller
+    // (ok:false) so the inbox item is left re-deliverable, never `.processed`.
+    fireOnClose(false, null);
+
+    drainQueue();
+  });
+}
+
+function drainQueue() {
+  // A real drain supersedes any pending re-drain timer; clear it so we don't
+  // also fire a redundant one. If we bail out under pressure below with items
+  // still queued + no active session, we re-arm before returning (M1).
+  if (reDrainTimer) { clearTimeout(reDrainTimer); reDrainTimer = null; }
+
+  // WS4: the shared 429 breaker gates the whole drain — if it's open, leave
+  // everything queued (re-derivable; nothing dropped) and let a later close /
+  // drain retry once the breaker closes.
+  const rb = rateBlocked();
+  if (rb) {
+    // M1: with no session to drive a future close-drain, re-arm so the queued
+    // item isn't stranded until the next external dispatch.
+    if (activeSessions.size === 0 && (priorityQueue.length > 0 || normalQueue.length > 0)) {
+      armReDrain(rb.retryAt);
+    }
+    return;
+  }
+
+  while (activeSessions.size < MAX_CONCURRENT) {
+    // Peek the head without removing it so a governor QUEUE/DEFER leaves the
+    // item in place (never dropped).
+    const next = priorityQueue[0] || normalQueue[0];
+    if (!next) break;
+
+    const adm = admitFor(next.source, next.classResult?.priority);
+    if (adm.decision !== "ADMIT") {
+      // Under pressure: stop draining. Inbox items stay queued; the next close
+      // event (a freed slot) or the breaker closing will resume the drain.
+      logSession({ event: "drain_paused", reason: adm.reason, decision: adm.decision, source: next.source });
+      // M1: if nothing is running, no close event will re-drain — arm a timer.
+      if (activeSessions.size === 0) armReDrain(adm.retryAt);
+      break;
+    }
+
+    // Commit: remove from whichever queue it sat at the head of, then spawn.
+    if (priorityQueue[0] === next) priorityQueue.shift();
+    else normalQueue.shift();
+    spawnSession(next);
+  }
+}
+
+/** Get current status for health checks */
+export function getStatus() {
+  return {
+    active_sessions: activeSessions.size,
+    max_concurrent: MAX_CONCURRENT,
+    priority_queue_length: priorityQueue.length,
+    normal_queue_length: normalQueue.length,
+    sessions: Array.from(activeSessions.entries()).map(([id, s]) => ({
+      id,
+      model: s.model,
+      priority: s.classResult.priority,
+      summary: s.classResult.summary,
+      duration_s: ((Date.now() - s.startTime) / 1000).toFixed(0),
+    })),
+  };
+}
+
+/** Get available slots count */
+export function availableSlots() {
+  return MAX_CONCURRENT - activeSessions.size;
+}