@ijfw/memory-server 1.4.4 → 1.5.0

package/src/cross-orchestrator.js

@@ -23,20 +23,105 @@ import { buildRequest, parseResponse, mergeResponses, checkBudget } from './cros
 import { writeReceipt, readReceipts } from './receipts.js';
 import { runViaApi } from './api-client.js';
 import { RELEASE_BLOCKER_GATES, DegradedTridentError } from './trident/dispatch.js';
+// v1.5.0 wire-W1.B — Anthropic ephemeral-cache TTL heartbeat for long
+// convergence waves. Opt-in via IJFW_CACHE_KEEPALIVE_MS env (1s..5min).
+import { startKeepaliveFromEnv } from './lib/cache-keepalive.js';
+// v1.5.0 T21 (W4) — convergence telemetry via state-SDK telemetry.record verb.
+// Writes `.ijfw/telemetry/convergence.json` with cycles-to-converge, false-
+// positive rate, and cost. Routed through the SDK so the append is journaled,
+// dedup'd, and tap-emitted on the standard observability surface.
+import { query as _stateQuery } from './orchestrator/state-sdk.js';
 
 // ---------------------------------------------------------------------------
 // Per-provider timeout defaults (ms). Codex cold-start can take 120s+ (U2).
+// r17.1 — bumped gemini 45s → 90s. The 45s budget was tuned for Gemini 2.x
+// which routinely returned in 10-20s; Gemini 3.x cold starts + larger context
+// windows mean a single audit on a 10KB target can exceed 45s end-to-end
+// (verified in cross-audit r16 on this codebase). 90s gives realistic
+// headroom without making a hung process feel hung.
 // ---------------------------------------------------------------------------
 const PROVIDER_TIMEOUT_MS = {
   codex:       120_000,
-  gemini:       45_000,
+  gemini:       90_000,
   anthropic:    60_000,
   'api-mode':   30_000,
 };
 const DEFAULT_TIMEOUT_MS = 90_000;
 
+// r17.1 — retry budget for transient timeouts. Gemini's API frequently returns
+// transient 502s and TCP hangs that resolve on a second attempt; codex more
+// often has a real cold-start problem that needs the longer first timeout
+// rather than a retry. Default: 1 retry, only for the gemini family. Per-
+// auditor `retryOnTimeout: true|false` in audit-roster.js overrides.
+// r17-L1 closure: also keyed by `family` so any future google-family auditor
+// (e.g. a "gemini-fast" id) inherits the family retry policy without us
+// having to add every id explicitly.
+const PROVIDER_RETRY_ON_TIMEOUT = {
+  gemini: true,
+};
+const FAMILY_RETRY_ON_TIMEOUT = {
+  google: true,
+};
+
+// v1.5.0 audit-MED-trident-M7 — per-(provider, path) retry matrix.
+// CLI cold-start failure modes (process startup, codex/gemini binary auth) are
+// different from API failure modes (transient 502s, network blips). A blanket
+// "no retry for codex" was wrong: codex CLI shouldn't retry (cold-start hits
+// the same wall), but codex *API* path absolutely should retry on transient
+// network noise. Resolves a finding where the api-fallback path inherited the
+// CLI's no-retry policy and gave up after one HTTP 502.
+//
+// Lookup precedence (most → least specific):
+//   1. pick.retryMatrix[path]  -- explicit per-auditor override
+//   2. PROVIDER_RETRY_PATH[id][path]
+//   3. FAMILY_RETRY_PATH[family][path]
+//   4. PROVIDER_RETRY_ON_TIMEOUT[id] / FAMILY_RETRY_ON_TIMEOUT[family]
+//      (legacy single-axis policy, kept for back-compat)
+//   5. default: false (CLI), true (API)
+const PROVIDER_RETRY_PATH = {
+  // codex CLI cold-start is real work; API is HTTP and benefits from retry.
+  codex:  { cli: false, api: true  },
+  gemini: { cli: true,  api: true  },
+};
+const FAMILY_RETRY_PATH = {
+  openai:    { cli: false, api: true },
+  google:    { cli: true,  api: true },
+  anthropic: { cli: false, api: true },
+};
+
+// shouldRetryOnTimeout(pick, path) -- path is 'cli' | 'api'.
+function shouldRetryOnTimeout(pick, path) {
+  // Explicit pick-level override.
+  if (pick && pick.retryMatrix && pick.retryMatrix[path] !== undefined) {
+    return pick.retryMatrix[path] === true;
+  }
+  // Per-provider, per-path.
+  const provider = pick && pick.id;
+  if (provider && PROVIDER_RETRY_PATH[provider] && PROVIDER_RETRY_PATH[provider][path] !== undefined) {
+    return PROVIDER_RETRY_PATH[provider][path] === true;
+  }
+  // Per-family, per-path.
+  const family = pick && pick.family;
+  if (family && FAMILY_RETRY_PATH[family] && FAMILY_RETRY_PATH[family][path] !== undefined) {
+    return FAMILY_RETRY_PATH[family][path] === true;
+  }
+  // Legacy single-axis fallback (preserves r17.1 behavior for non-matrixed picks).
+  if (pick && pick.retryOnTimeout === true)  return true;
+  if (pick && pick.retryOnTimeout === false) return false;
+  if (provider && PROVIDER_RETRY_ON_TIMEOUT[provider] === true) return true;
+  if (family   && FAMILY_RETRY_ON_TIMEOUT[family]    === true) return true;
+  // Default: API path retries on timeout; CLI does not.
+  return path === 'api';
+}
+
+// Exported for tests.
+export const _shouldRetryOnTimeout = shouldRetryOnTimeout;
+
 function timeoutForPick(pick, resolvedTimeoutSec) {
   if (resolvedTimeoutSec) return resolvedTimeoutSec * 1000;
+  // v1.5.0 S7: roster-level override takes precedence over family default.
+  // Codex needs 8min for review work vs 90s default; see audit-roster.js.
+  if (pick.timeoutMs) return pick.timeoutMs;
   return PROVIDER_TIMEOUT_MS[pick.id] ?? DEFAULT_TIMEOUT_MS;
 }
 
@@ -121,11 +206,72 @@ function angleFor(mode, id) {
 // silently pick up an unrelated gcloud project (cloudaicompanion.googleapis.com
 // billing collisions). Reproduced by Kat in issue #9.
 //
-// Precedence we enforce when GEMINI_API_KEY is set:
+// v1.5.0 audit-MED-trident-M2 (F-SEC-1): per-pick API-key allowlist.
+// Previously every cross-fired auditor inherited the FULL parent env --
+// codex saw GEMINI_API_KEY + DEEPSEEK_API_KEY + ANTHROPIC_API_KEY, gemini saw
+// OPENAI_API_KEY, etc. A prompt-injected auditor could egress every key the
+// host has loaded. We now whitelist the keys each auditor legitimately needs
+// (its own auth + minimal POSIX baseline) and drop everything else from the
+// inherited env. Non-secret config vars (PATH, HOME, LANG, IJFW_*, CODEX_*)
+// pass through; vendor API keys are filtered.
+//
+// Precedence we still enforce when GEMINI_API_KEY is set:
 //   GEMINI_API_KEY (kept) > GOOGLE_APPLICATION_CREDENTIALS (dropped)
 //                         > gcloud active-project env (dropped)
+
+// Vendor API-key env-vars that MUST NOT leak across auditor boundaries.
+// Any key matching this list is dropped unless explicitly re-added by the
+// per-pick allowlist below.
+const VENDOR_API_KEY_VARS = new Set([
+  'OPENAI_API_KEY',
+  'ANTHROPIC_API_KEY',
+  'GEMINI_API_KEY',
+  'GOOGLE_API_KEY',
+  'DEEPSEEK_API_KEY',
+  'DASHSCOPE_API_KEY',     // qwen / Alibaba
+  'MOONSHOT_API_KEY',      // kimi
+  'GROQ_API_KEY',
+  'XAI_API_KEY',           // grok
+  'MISTRAL_API_KEY',
+  'COHERE_API_KEY',
+  'PERPLEXITY_API_KEY',
+  'TOGETHER_API_KEY',
+  'OPENROUTER_API_KEY',
+  'AZURE_OPENAI_API_KEY',
+  'GH_COPILOT_TOKEN',
+  'GITHUB_TOKEN',
+]);
+
+// Per-pick API-key allowlist. Each auditor sees ONLY the keys it needs.
+// Unrecognized picks fall through to a conservative "no vendor keys" default
+// (still inherits PATH/HOME/LANG/etc via the broader env, just no API keys).
+const PER_PICK_API_KEY_ALLOWLIST = {
+  codex:    ['OPENAI_API_KEY'],
+  copilot:  ['OPENAI_API_KEY', 'GH_COPILOT_TOKEN', 'GITHUB_TOKEN'],
+  gemini:   ['GEMINI_API_KEY', 'GOOGLE_API_KEY'],
+  claude:   ['ANTHROPIC_API_KEY'],
+  deepseek: ['DEEPSEEK_API_KEY'],
+  qwen:     ['DASHSCOPE_API_KEY'],
+  kimi:     ['MOONSHOT_API_KEY'],
+  opencode: [],
+  aider:    ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY'], // aider routes to either
+};
+
 export function buildSpawnEnv(pick, baseEnv) {
   const env = { ...baseEnv };
+
+  // M2: strip every vendor API key, then re-inject only the ones this pick
+  // is on the allowlist for. The allowlist is keyed by pick.id; unknown ids
+  // get an empty allowlist (still safe — drops all vendor keys).
+  const pickId = pick && pick.id;
+  const allowed = PER_PICK_API_KEY_ALLOWLIST[pickId] || [];
+  const allowedSet = new Set(allowed);
+  for (const key of VENDOR_API_KEY_VARS) {
+    if (!allowedSet.has(key)) delete env[key];
+  }
+
+  // Issue #9-A guard remains: if gemini is the pick AND its own key is set,
+  // also scrub gcloud project env vars so they don't silently override.
   if (pick && pick.id === 'gemini' && env.GEMINI_API_KEY) {
     delete env.GOOGLE_APPLICATION_CREDENTIALS;
     delete env.GOOGLE_CLOUD_PROJECT;
@@ -255,23 +401,150 @@ async function fireExternal(pick, request, timeoutMs, env = process.env, signal
     return { stdout: '', stderr: apiResult.error, exitCode: null, status: 'failed', source: 'none', elapsedMs: elapsed() };
   }
 
-  const raw = await spawnCli(pick, request, timeoutMs, signal, env);
+  let raw = await spawnCli(pick, request, timeoutMs, signal, env);
 
   // Aborted by runAc
   if (raw && raw.aborted) {
     return { stdout: '', stderr: 'aborted', exitCode: null, status: 'aborted', source: 'none', elapsedMs: elapsed() };
   }
 
-  // Explicit timeout -- attempt API fallback before giving up.
-  if (raw && raw.timedOut) {
-    if (pick.apiFallback && isReachable(pick.id, env).api) {
+  // v1.5.0 audit-MED-tok-M8 + audit-MED-trident-M7 — Parallel retry-vs-fallback
+  // race, gated by the path-aware retry matrix.
+  //
+  // The retry policy is per-(provider,path) — CLI cold-start (path='cli') and
+  // API transient errors (path='api') are distinct failure modes with distinct
+  // retry profiles. shouldRetryOnTimeout() consults the matrix; an explicit
+  // `pick.retryMatrix[path] === false` or `pick.retryOnTimeout === false`
+  // always wins for caller opt-out.
+  //
+  // When BOTH a CLI retry AND an api-fallback are eligible, we RACE them
+  // concurrently and take the first productive result, capping the timeout-
+  // recovery budget at max(retry-timeout, api-mode-timeout) instead of the
+  // sequential sum (~25% wall-clock improvement on the gemini unhappy path).
+  // When only one channel is eligible, we fall back to sequential behaviour
+  // so the change is purely additive — same outcome whenever exactly one
+  // recovery channel exists.
+  if (raw && raw.timedOut && !signal?.aborted) {
+    const canRetry    = shouldRetryOnTimeout(pick, 'cli');
+    const canFallback = Boolean(pick.apiFallback) && isReachable(pick.id, env).api;
+
+    if (canRetry && canFallback) {
+      // Race retry against api-fallback. Each path runs with its own abort
+      // controller; the loser is aborted as soon as we have a winner.
+      const retryAc    = new AbortController();
+      const fallbackAc = new AbortController();
+      // Honour the parent runAc abort by cascading into both.
+      const onParentAbort = () => { retryAc.abort(); fallbackAc.abort(); };
+      if (signal) {
+        if (signal.aborted) onParentAbort();
+        else signal.addEventListener('abort', onParentAbort, { once: true });
+      }
+
+      const retryPromise = spawnCli(pick, request, timeoutMs, retryAc.signal, env)
+        .then(r => ({ kind: 'retry', raw: r }));
+
       const { mode, angle, target } = extractApiParams();
-      const apiResult = await runViaApi(pick, mode, angle, target, env, PROVIDER_TIMEOUT_MS['api-mode'], signal);
+      // M7: api-path retry on transient timeout (separate from CLI policy).
+      // Wrapped in an async IIFE so the per-path retry happens inside the
+      // single racing promise.
+      const fallbackPromise = (async () => {
+        let api = await runViaApi(pick, mode, angle, target, env, PROVIDER_TIMEOUT_MS['api-mode'], fallbackAc.signal);
+        if (api.status !== 'ok' && shouldRetryOnTimeout(pick, 'api') && !fallbackAc.signal.aborted) {
+          api = await runViaApi(pick, mode, angle, target, env, PROVIDER_TIMEOUT_MS['api-mode'], fallbackAc.signal);
+        }
+        return { kind: 'fallback', api };
+      })();
+
+      // We want the FIRST PRODUCTIVE result. Promise.race() returns whichever
+      // settles first regardless of productivity, so we iterate manually:
+      // if the first to resolve is "unproductive" (retry timed out, fallback
+      // errored), we await the other.
+      const settled = { retry: null, fallback: null };
+      let winner = null;
+
+      // Helper: did this kind produce a usable result?
+      const isProductive = (kind) => {
+        if (kind === 'retry') {
+          const r = settled.retry;
+          return Boolean(r && !r.aborted && !r.timedOut && r.exitCode === 0);
+        }
+        if (kind === 'fallback') {
+          return settled.fallback && settled.fallback.status === 'ok';
+        }
+        return false;
+      };
+
+      // Resolve as soon as ONE side returns a productive result, OR both have settled.
+      await new Promise((resolve) => {
+        let pending = 2;
+        let done = false;
+        const finish = (kind) => {
+          if (done) return;
+          if (isProductive(kind)) {
+            done = true;
+            winner = kind;
+            // Abort the loser so it stops consuming budget.
+            if (kind === 'retry') fallbackAc.abort();
+            else retryAc.abort();
+            resolve();
+            return;
+          }
+          if (--pending === 0) {
+            done = true;
+            resolve();
+          }
+        };
+        retryPromise.then(({ raw: r }) => { settled.retry = r; finish('retry'); })
+                    .catch(() => { settled.retry = null;       finish('retry'); });
+        fallbackPromise.then(({ api: a }) => { settled.fallback = a; finish('fallback'); })
+                       .catch(() => { settled.fallback = null;       finish('fallback'); });
+      });
+
+      // Detach parent-abort listener if it didn't already fire.
+      if (signal) {
+        try { signal.removeEventListener('abort', onParentAbort); } catch {}
+      }
+
+      // Decision matrix on the raced outcome.
+      if (winner === 'fallback' && settled.fallback && settled.fallback.status === 'ok') {
+        return { stdout: settled.fallback.raw, stderr: '', exitCode: 0, status: 'fallback-used', source: 'api', elapsedMs: elapsed() };
+      }
+      if (winner === 'retry' && settled.retry && settled.retry.exitCode === 0) {
+        // CLI second attempt landed -- use it as if it were the original.
+        raw = settled.retry;
+      } else {
+        // Neither path produced a productive result. Prefer the most-informative
+        // failure status: an explicit fallback error beats a bare timeout.
+        if (settled.fallback && settled.fallback.status !== 'ok' && settled.fallback.error) {
+          return { stdout: '', stderr: 'timeout-and-fallback-failed', exitCode: null, status: 'timeout', source: 'none', elapsedMs: elapsed() };
+        }
+        return { stdout: '', stderr: 'timeout', exitCode: null, status: 'timeout', source: 'none', elapsedMs: elapsed() };
+      }
+    } else if (canRetry) {
+      // Retry-only path (no api-fallback eligible): single sequential CLI retry.
+      raw = await spawnCli(pick, request, timeoutMs, signal, env);
+      if (raw && raw.aborted) {
+        return { stdout: '', stderr: 'aborted-after-retry', exitCode: null, status: 'aborted', source: 'none', elapsedMs: elapsed() };
+      }
+      if (raw && raw.timedOut) {
+        return { stdout: '', stderr: 'timeout', exitCode: null, status: 'timeout', source: 'none', elapsedMs: elapsed() };
+      }
+    } else if (canFallback) {
+      // Fallback-only path (no CLI retry eligible): API fallback with M7
+      // path-aware retry on transient API timeout.
+      const { mode, angle, target } = extractApiParams();
+      let apiResult = await runViaApi(pick, mode, angle, target, env, PROVIDER_TIMEOUT_MS['api-mode'], signal);
+      if (apiResult.status !== 'ok' && shouldRetryOnTimeout(pick, 'api') && !signal?.aborted) {
+        apiResult = await runViaApi(pick, mode, angle, target, env, PROVIDER_TIMEOUT_MS['api-mode'], signal);
+      }
       if (apiResult.status === 'ok') {
         return { stdout: apiResult.raw, stderr: '', exitCode: 0, status: 'fallback-used', source: 'api', elapsedMs: elapsed() };
       }
+      return { stdout: '', stderr: 'timeout', exitCode: null, status: 'timeout', source: 'none', elapsedMs: elapsed() };
+    } else {
+      // Neither retry nor fallback eligible: nothing more we can do.
+      return { stdout: '', stderr: 'timeout', exitCode: null, status: 'timeout', source: 'none', elapsedMs: elapsed() };
     }
-    return { stdout: '', stderr: 'timeout', exitCode: null, status: 'timeout', source: 'none', elapsedMs: elapsed() };
   }
 
   // CLI failed -- try API fallback
@@ -486,25 +759,31 @@ async function runPhaseEAuto({ projectDir, phase, target, env, quiet }) {
   const auditorResults = rawResults.map((raw, i) => {
     const pick = picks[i];
     if (raw === null) {
-      return { status: 'failed', parsed: { items: [], prose: `[${pick.id}: spawn failed]` } };
+      return { status: 'failed', counted: false, parsed: { items: [], prose: `[${pick.id}: spawn failed]` } };
     }
     const { stdout, exitCode, status: rawStatus } = raw;
-    if (rawStatus === 'timeout') return { status: 'timeout', parsed: { items: [], prose: `[${pick.id}: timeout]` } };
-    if (rawStatus === 'failed') return { status: 'failed', parsed: { items: [], prose: `[${pick.id}: failed]` } };
-    if (rawStatus === 'aborted') return { status: 'aborted', parsed: { items: [], prose: `[${pick.id}: aborted]` } };
+    // v1.5.0 S7: non-productive results MUST NOT count toward synthesis verdict.
+    // A hung CLI returning zero items would silently produce a PASS under the
+    // old logic (classifyVerdict([]) === 'PASS'). counted:false isolates them.
+    if (rawStatus === 'timeout') return { status: 'timeout', counted: false, parsed: { items: [], prose: `[${pick.id}: timeout]` } };
+    if (rawStatus === 'failed') return { status: 'failed', counted: false, parsed: { items: [], prose: `[${pick.id}: failed]` } };
+    if (rawStatus === 'aborted') return { status: 'aborted', counted: false, parsed: { items: [], prose: `[${pick.id}: aborted]` } };
     if (rawStatus === 'fallback-used') {
       const p = parseResponse('audit', stdout);
-      return { status: 'fallback-used', parsed: p };
+      return { status: 'fallback-used', counted: true, parsed: p };
     }
-    if (exitCode !== 0) return { status: 'failed', parsed: { items: [], prose: `[${pick.id}: exited ${exitCode}]` } };
+    if (exitCode !== 0) return { status: 'failed', counted: false, parsed: { items: [], prose: `[${pick.id}: exited ${exitCode}]` } };
     const p = parseResponse('audit', stdout);
-    return { status: 'ok', parsed: p };
+    return { status: 'ok', counted: true, parsed: p };
   });
 
-  const parsed = auditorResults.map(r => r.parsed);
+  const productive = auditorResults.filter(r => r.counted);
+  const parsed = productive.map(r => r.parsed);
   const merged = mergeResponses('audit', parsed);
   const items = Array.isArray(merged) ? merged : [];
-  const verdict = classifyVerdict(items);
+  // v1.5.0 S7: when zero auditors return productive output, the verdict is
+  // INCONCLUSIVE — refuses to grant PASS from a hung-CLI floor.
+  const verdict = productive.length === 0 ? 'INCONCLUSIVE' : classifyVerdict(items);
 
   // Write synthesis to .planning/<phase>/CROSS-AUDIT-r<N>.md
   const outputPath = resolveAuditOutputPath(projectDir, phase);
@@ -766,3 +1045,723 @@ export async function runCrossOp({
     accept_degraded: !!accept_degraded,
   };
 }
+
+// ---------------------------------------------------------------------------
+// v1.5.0 W12-C N01+N03 — runPhaseEConverge
+// ---------------------------------------------------------------------------
+//
+// Multi-lens consensus convergence (lock-in #47 — canonical Phase E).
+// Single-shot Phase E is the FALLBACK. Default behavior is a convergence
+// loop with divergence detection.
+//
+// Per-iteration flow:
+//   1. Dispatch all lenses in parallel.
+//   2. Collect verdicts (PASS / CONDITIONAL / FAIL) + finding lists.
+//   3. If all PASS → done.
+//   4. If verdicts diverge, build a CYCLE_SUMMARY (prior verdicts +
+//      areas of disagreement) and re-dispatch with it injected.
+//   5. Cap at `maxIterations` (default 3). If still divergent at the cap,
+//      emit `consensus_failed` and surface divergence.
+//   6. Stall breaker: if iter N produces byte-identical findings to
+//      iter N-1, halt with `stalled: true` rather than burn tokens.
+//
+// Dispatcher contract (for test/DI):
+//   dispatch({ lens, commitRange, iteration, cycleSummary }) →
+//     { lens, verdict: 'PASS'|'CONDITIONAL'|'FAIL'|'UNREACHABLE',
+//       findings: Array<{severity?, text?, ...}> }
+//
+// Tests inject a synthetic dispatcher; production passes a real one
+// that wraps `fireExternal` / `parseResponse` / `classifyVerdict` (or
+// reuses runCrossOp for each iteration).
+// ---------------------------------------------------------------------------
+
+const VERDICT_PASS          = 'PASS';
+const VERDICT_CONDITIONAL   = 'CONDITIONAL';
+const VERDICT_FAIL          = 'FAIL';
+const VERDICT_UNREACHABLE   = 'UNREACHABLE';
+const VERDICT_CONSENSUS_FAIL = 'consensus_failed';
+const DEFAULT_LENSES        = ['codex', 'gemini', 'claude'];
+
+// v1.5.0 audit-H4.1 — hard upper bound on convergence iterations. A caller
+// asking for 100 rounds would burn 100 rounds of full Trident dispatch (~3
+// auditors × ~90s = ~4.5h per cycle on cold start). 10 is well above the
+// observed empirical ceiling — the convergence loop almost always settles in
+// 2-3 iters; >5 is a smell, >10 is a misuse. Anything above the cap is
+// silently clamped to MAX_CONVERGE_ITERATIONS + emits a single dedup'd warning.
+export const MAX_CONVERGE_ITERATIONS = 10;
+
+// Module-level dedup set for max-iterations clamp warnings. One stderr line
+// per unique requested value per process lifetime (same pattern as
+// cross-project-search SKIP_LOG).
+const _MAX_ITER_WARN_LOG = new Set();
+
+/** Reset the max-iter warn-log dedup set. Test-only. */
+export function _resetMaxIterWarnLog() {
+  _MAX_ITER_WARN_LOG.clear();
+}
+
+// Stable serialization for stall comparison.
+function stableFindingsKey(perLensFindings) {
+  // perLensFindings: { lens → Array<finding> }
+  // Use lens-sorted keys, and within each lens stringify findings (sorted by
+  // a stable text representation) so semantically-identical iterations match.
+  const lenses = Object.keys(perLensFindings).sort();
+  const parts = [];
+  for (const lens of lenses) {
+    const findings = Array.isArray(perLensFindings[lens]) ? perLensFindings[lens] : [];
+    const serialized = findings
+      .map(f => JSON.stringify(f, Object.keys(f || {}).sort()))
+      .sort();
+    parts.push(`${lens}:[${serialized.join(',')}]`);
+  }
+  return parts.join('|');
+}
+
+// Detect whether lens verdicts diverge.
+// All-PASS (with no UNREACHABLE) → false. Anything else with mixed verdicts → true.
+// All-FAIL across reachable lenses → still divergent only if findings differ;
+// pure consensus FAIL is not divergence (everyone agrees the change is bad).
+function detectDivergence(lensResults) {
+  const reachable = lensResults.filter(r => r.verdict !== VERDICT_UNREACHABLE);
+  if (reachable.length === 0) return { divergent: false, axes: [] };
+  const verdicts = new Set(reachable.map(r => r.verdict));
+  if (verdicts.size === 1) {
+    // All reachable lenses agree on the verdict. Findings can still differ
+    // (one lens may report extra MEDIUM findings), but verdict consensus is
+    // sufficient — convergence is verdict-level, not finding-level.
+    return { divergent: false, axes: [] };
+  }
+  // Verdicts diverge: compute axes (which lens differs from the majority).
+  const counts = {};
+  for (const r of reachable) counts[r.verdict] = (counts[r.verdict] || 0) + 1;
+  let majority = reachable[0].verdict;
+  let max = 0;
+  for (const v of Object.keys(counts)) {
+    if (counts[v] > max) { max = counts[v]; majority = v; }
+  }
+  const axes = reachable
+    .filter(r => r.verdict !== majority)
+    .map(r => ({ lens: r.lens, verdict: r.verdict, majority }));
+  return { divergent: true, axes };
+}
+
+// Build a CYCLE_SUMMARY string injected into the next iteration's lens brief.
+function buildCycleSummary(iteration, prior) {
+  const lines = [
+    `# CYCLE_SUMMARY (iteration ${iteration})`,
+    '',
+    'Previous round verdicts:',
+  ];
+  for (const r of prior.lensResults) {
+    lines.push(`- ${r.lens}: ${r.verdict} (${(r.findings || []).length} findings)`);
+  }
+  if (prior.divergence && prior.divergence.axes && prior.divergence.axes.length > 0) {
+    lines.push('');
+    lines.push('Areas of disagreement (lens vs majority):');
+    for (const a of prior.divergence.axes) {
+      lines.push(`- ${a.lens} said ${a.verdict}; majority said ${a.majority}`);
+    }
+  }
+  lines.push('');
+  lines.push('Re-evaluate. If your prior verdict was correct, restate it with explicit reasoning. If the other lenses changed your mind, update accordingly.');
+  return lines.join('\n');
+}
+
+// Public convergence entrypoint.
+// Inputs:
+//   commitRange    string (e.g. 'HEAD~1..HEAD')
+//   lenses         array of lens ids (default ['codex','gemini','claude'])
+//   maxIterations  number (default 3; lock-in #43/#44 style)
+//   dispatch       async function (DI hook for tests/production)
+//   projectRoot    string (passed through to dispatch)
+//   totalTimeoutMs v1.5.0 audit-MED-trident-M6 — cumulative wall-clock cap.
+//                  When set, an AbortController fires at the deadline and
+//                  cancels remaining iterations. 3 iters × 3 lenses × 90s =
+//                  270s worst case without a cap; this lets a caller say
+//                  "no more than 4 minutes for the whole convergence".
+//                  Defaults to env IJFW_AUDIT_CONVERGE_TOTAL_TIMEOUT_SEC.
+//   perLensBudgetUsd  v1.5.0 audit-MED-trident-M5 — per-lens USD cap across
+//                     this convergence cycle. Aborts a lens once its
+//                     cumulative cost in this run exceeds the cap. Defaults
+//                     to env IJFW_AUDIT_BUDGET_USD_PER_LENS.
+// Returns:
+//   { verdict, iterations, findings, divergence?, stalled?, perIteration,
+//     timedOutTotal?, lensesOverBudget?, lensCosts }
+export async function runPhaseEConverge({
+  commitRange,
+  lenses = DEFAULT_LENSES,
+  maxIterations = 3,
+  dispatch,
+  projectRoot,
+  projectDir,         // v1.5.0 audit-H4.5 — receipts destination (defaults to projectRoot)
+  runStamp,           // v1.5.0 audit-H4.5 — caller-supplied stamp; auto if absent
+  totalTimeoutMs,     // v1.5.0 audit-MED-trident-M6 — cumulative timeout
+  perLensBudgetUsd,   // v1.5.0 audit-MED-trident-M5 — per-lens USD cap
+  keepaliveOnTick,    // v1.5.0 wire-W1.B — caller-supplied keepalive heartbeat
+  env = process.env,
+} = {}) {
+  if (typeof dispatch !== 'function') {
+    throw new Error('runPhaseEConverge: dispatch function is required');
+  }
+  if (!Array.isArray(lenses) || lenses.length === 0) {
+    throw new Error('runPhaseEConverge: lenses must be a non-empty array');
+  }
+  // v1.5.0 audit-H4.1 — clamp to [1, MAX_CONVERGE_ITERATIONS]. Anything above
+  // the cap is silently coerced; one-line stderr warning per unique requested
+  // value (Set dedup) so a caller running the same misconfigured tool 100
+  // times doesn't spam the log.
+  const requested = Math.max(1, Math.floor(maxIterations));
+  const cap = Math.min(requested, MAX_CONVERGE_ITERATIONS);
+  if (requested > MAX_CONVERGE_ITERATIONS) {
+    const key = String(requested);
+    if (!_MAX_ITER_WARN_LOG.has(key)) {
+      _MAX_ITER_WARN_LOG.add(key);
+      process.stderr.write(
+        `runPhaseEConverge: maxIterations=${requested} clamped to MAX_CONVERGE_ITERATIONS=${MAX_CONVERGE_ITERATIONS}.\n`
+      );
+    }
+  }
+
+  // v1.5.0 audit-H4.5 — receipts wiring. The flagship converge tool was
+  // previously invisible to `ijfw status` and the dashboard because no receipt
+  // was written. Capture start time + per-cycle finding counts here, write
+  // ONE summary receipt before each return path (writeReceiptIfPossible).
+  const _startMs = Date.now();
+  const _receiptCycles = [];          // [{ iteration, findingCount, lensVerdicts: {lens:verdict} }]
+  let _totalInvocations = 0;          // dispatch calls across all iterations
+
+  const _resolvedProjectDir = projectDir ?? projectRoot ?? process.cwd();
+  const _resolvedRunStamp = runStamp ?? new Date().toISOString();
+
+  // v1.5.0 T21 — telemetry accumulators for the three metrics published via
+  // the state-SDK `telemetry.record` verb at finalize time.
+  //   * _telemetryAlarms — count of (lens, cycle) observations whose verdict
+  //     was FAIL or CONDITIONAL (i.e. "raised an alarm"). The false-positive
+  //     rate compares this against the final consensus verdict.
+  //   * _telemetryReachableObs — count of reachable (lens, cycle) observations
+  //     (excludes UNREACHABLE/budget-capped) — the denominator for the rate.
+  // Cost is read off `_lensCosts` (already accumulated) at finalize.
+  let _telemetryAlarms = 0;
+  let _telemetryReachableObs = 0;
+
+  // v1.5.0 audit-MED-trident-M6 — cumulative-timeout AbortController.
+  // Either an arg-supplied totalTimeoutMs or env var; >0 enables. The signal
+  // is checked between iterations + passed to dispatch (dispatchers that
+  // honor `signal` will tear down in-flight lens calls).
+  const _envTotalSec = env && env.IJFW_AUDIT_CONVERGE_TOTAL_TIMEOUT_SEC;
+  const _resolvedTotalMs = (typeof totalTimeoutMs === 'number' && totalTimeoutMs > 0)
+    ? totalTimeoutMs
+    : (Number.isFinite(Number(_envTotalSec)) && Number(_envTotalSec) > 0
+      ? Math.floor(Number(_envTotalSec) * 1000)
+      : null);
+  const _cycleAc = new AbortController();
+  let _totalTimedOut = false;
+  let _totalTimer = null;
+  if (_resolvedTotalMs) {
+    _totalTimer = setTimeout(() => {
+      _totalTimedOut = true;
+      try { _cycleAc.abort(); } catch { /* ignore */ }
+    }, _resolvedTotalMs);
+    // Don't keep the event loop alive purely for this timer.
+    if (typeof _totalTimer.unref === 'function') _totalTimer.unref();
+  }
+
+  // v1.5.0 wire-W1.B — Anthropic ephemeral-cache keepalive heartbeat.
+  // Production wiring for `mcp-server/src/lib/cache-keepalive.js`. A long
+  // Trident convergence (5+ minutes of sequential lens calls separated by
+  // CLI / API latency) can lose cache hits mid-wave because the 5-min TTL
+  // expires between calls even though every call re-sends the same cache-
+  // eligible prefix. The lib provides an opt-in heartbeat that fires a
+  // no-op on a configurable interval to keep the cache warm.
+  //
+  // Default OFF (intervalMs=0 when IJFW_CACHE_KEEPALIVE_MS env is unset).
+  // When the env var is set in the [1000, 300000] range, the heartbeat
+  // fires every N ms until convergence completes or the cumulative-timeout
+  // signal aborts (signal is passed through so the cap cascades into
+  // keepalive too).
+  //
+  // Every tick increments a counter (surfaced on the return value + receipt
+  // for observability). Production callers can additionally supply their own
+  // onTick via `keepaliveOnTick` arg (e.g. to ping an API endpoint that
+  // re-warms the cache prefix); it runs alongside the counter, not instead.
+  let _keepaliveTicks = 0;
+  const _keepalive = startKeepaliveFromEnv({
+    // r21-LOW: count every tick regardless of whether a custom onTick is
+    // supplied. Previously the counter only ran on the default path, so
+    // runs that passed keepaliveOnTick under-reported as zero ticks.
+    onTick: () => {
+      _keepaliveTicks += 1;
+      if (typeof keepaliveOnTick === 'function') {
+        try { keepaliveOnTick(); } catch { /* keepalive errors must never crash the wave */ }
+      }
+    },
+    onError: () => { /* keepalive errors must never crash the wave */ },
+    signal: _cycleAc.signal,
+    env,
+  });
+
+  // v1.5.0 audit-MED-trident-M5 — per-lens budget. Tracks cumulative cost
+  // attributed to each lens across this converge cycle; abort that lens once
+  // its accumulated cost > cap. Cost source priority on dispatch return:
+  //   1. result.cost_usd
+  //   2. result.usage?.cost_usd
+  //   3. 0 (unknown — counted as 0, can still hit cap via N iterations)
+  const _envPerLensCap = env && env.IJFW_AUDIT_BUDGET_USD_PER_LENS;
+  const _resolvedPerLensCap = (typeof perLensBudgetUsd === 'number' && perLensBudgetUsd > 0)
+    ? perLensBudgetUsd
+    : (Number.isFinite(Number(_envPerLensCap)) && Number(_envPerLensCap) > 0
+      ? Number(_envPerLensCap)
+      : null);
+  const _lensCosts = Object.create(null);
+  const _lensOverBudget = new Set();
+  for (const lens of lenses) _lensCosts[lens] = 0;
+
+  async function _finalize(returnVal) {
+    // Clear cumulative-timeout timer so the process can exit cleanly.
+    if (_totalTimer) {
+      clearTimeout(_totalTimer);
+      _totalTimer = null;
+    }
+    // v1.5.0 wire-W1.B — sample the active flag BEFORE cancel. isActive()
+    // returns false once cancelled, so reading it after teardown (r21-MED)
+    // would under-report a heartbeat that was wired and running this wave.
+    const _keepaliveActive = _keepalive.isActive();
+    // Cancel keepalive (idempotent; no-op when never started).
+    try { _keepalive.cancel(); } catch { /* never throws */ }
+    // M5/M6: surface lens-budget + total-timeout posture on the return value
+    // so callers can branch on partial-completion. lensCosts is always
+    // present (even when no cap was set) so observability is consistent.
+    const enriched = {
+      ...returnVal,
+      lensCosts: { ..._lensCosts },
+      ...(_lensOverBudget.size > 0 ? { lensesOverBudget: [..._lensOverBudget] } : {}),
+      ...(_totalTimedOut ? { timedOutTotal: true } : {}),
+      // wire-W1.B observability: tick count + whether the heartbeat was wired
+      // at all for this run (proves the lib is live, not just imported).
+      keepaliveTicks: _keepaliveTicks,
+      keepaliveWired: _keepaliveActive || _keepaliveTicks > 0,
+    };
+    // Build + write the converge receipt. Failure to write must NOT clobber
+    // the orchestrator return value (defensive — receipts are observability,
+    // not correctness).
+    try {
+      const record = {
+        v: 1,
+        timestamp: new Date().toISOString(),
+        run_stamp: _resolvedRunStamp,
+        mode: 'converge',
+        target: commitRange,
+        // Receipt-compatible auditor list (renderReceipt reads .id from each).
+        auditors: lenses.map(id => ({ id })),
+        // findings shape matches renderReceipt's array branch.
+        findings: { items: Array.isArray(enriched.findings) ? enriched.findings : [] },
+        duration_ms: Date.now() - _startMs,
+        // Converge-specific fields (new — minimal addition; renderReceipt
+        // ignores unknown keys, so existing receipt renderers keep working).
+        converge: {
+          iterations: enriched.iterations,
+          verdict: enriched.verdict,
+          stalled: !!enriched.stalled,
+          divergent: Array.isArray(enriched.divergence) && enriched.divergence.length > 0,
+          total_invocations: _totalInvocations,
+          cycles: _receiptCycles,
+          requested_max_iterations: requested,
+          effective_max_iterations: cap,
+          // M5/M6 observability.
+          total_timeout_ms: _resolvedTotalMs,
+          timed_out_total: _totalTimedOut,
+          per_lens_budget_usd: _resolvedPerLensCap,
+          lens_costs: _lensCosts,
+          lenses_over_budget: [..._lensOverBudget],
+          // wire-W1.B observability: how many keepalive heartbeats fired
+          // during this convergence; 0 means the lib was wired but the env
+          // opt-in was off, >0 proves the heartbeat ran in production.
+          keepalive_ticks: _keepaliveTicks,
+        },
+      };
+      writeReceipt(_resolvedProjectDir, record);
+    } catch {
+      // Receipts are observability; never fail the converge run on a write error.
+    }
+
+    // v1.5.0 T21 (W4) — convergence telemetry via state-SDK `telemetry.record`.
+    //
+    // NOTE — this `_finalize` IIFE inside an async function chain: the
+    // telemetry recorder needs to publish BEFORE the function returns so
+    // callers (and tests) can read `.ijfw/telemetry/convergence.json`
+    // synchronously after `await runPhaseEConverge(...)`. We therefore
+    // shape `_finalize` to be async and await the telemetry write here.
+    // The await is inside a try/catch that swallows everything — failure
+    // to write telemetry never changes the convergence verdict.
+    //
+    // The three metrics are computed here AFTER the final verdict is known so
+    // the false-positive rate has a stable consensus reference point. Failure
+    // to record telemetry MUST NOT corrupt or override the convergence verdict:
+    // wrapped in try/catch with full swallow per the off-the-critical-path
+    // discipline. The convergence return value (`enriched`) is unchanged.
+    //
+    // Metric definitions (locked here so downstream dashboards and the
+    // STATE-SDK contract §7 telemetry.record consumers can rely on them):
+    //
+    //   1. cyclesToConverge (integer ≥ 1, ≤ MAX_CONVERGE_ITERATIONS):
+    //        The iteration count at which the loop terminated. Equals
+    //        `enriched.iterations` — i.e. the number of dispatch rounds
+    //        actually executed before a stop condition (PASS consensus,
+    //        non-PASS consensus short-circuit, byte-identical stall,
+    //        cap reached, total-timeout, or all-budget-capped) was met.
+    //        A single-cycle PASS reports 1; a 3-iter stalemate that ends
+    //        in `consensus_failed` reports 3.
+    //
+    //   2. falsePositiveRate (decimal in [0, 1]):
+    //        Numerator: (lens, cycle) observations where a lens raised an
+    //          alarm (verdict FAIL or CONDITIONAL) but the FINAL consensus
+    //          verdict was PASS. UNREACHABLE observations are excluded.
+    //        Denominator: total reachable (lens, cycle) observations across
+    //          all cycles in this run.
+    //        Rationale: a "false positive" is a lens that cried wolf — it
+    //          said "this change is broken" against a run the swarm
+    //          ultimately blessed. When the final verdict is NOT PASS (FAIL,
+    //          CONDITIONAL, consensus_failed, UNREACHABLE), no alarm can be
+    //          retro-classified as false — the numerator is 0 and the rate
+    //          collapses to 0. When the denominator is 0 (no reachable
+    //          observations ever fired — all lenses budget-capped or all
+    //          dispatch threw), the rate is reported as 0 (no signal to
+    //          divide by). 0 ≤ rate ≤ 1 by construction.
+    //
+    //   3. costUsd (decimal ≥ 0):
+    //        Sum across all lenses of cumulative cost attributed to this
+    //        convergence run. Source: `_lensCosts[lens]`, which is fed from
+    //        `dispatch().cost_usd` (or `dispatch().usage.cost_usd`) on every
+    //        per-cycle settlement. Lenses that never returned a cost field
+    //        contribute 0 (their wall-clock time isn't a "USD" cost — that's
+    //        already captured in the receipt's `duration_ms` field). When
+    //        no lens reports cost, costUsd is 0.0; this is the truthful
+    //        signal that the swarm ran on CLI credentials with no per-call
+    //        billing surface, not a missing-data sentinel.
+    try {
+      const finalVerdict = enriched.verdict;
+      const finalIsPass = finalVerdict === VERDICT_PASS;
+      // Numerator: alarms only count as FALSE positives when consensus PASS'd.
+      const _falsePositives = finalIsPass ? _telemetryAlarms : 0;
+      const falsePositiveRate = _telemetryReachableObs > 0
+        ? _falsePositives / _telemetryReachableObs
+        : 0;
+      let _summedCost = 0;
+      for (const v of Object.values(_lensCosts)) {
+        if (typeof v === 'number' && Number.isFinite(v)) _summedCost += v;
+      }
+      const metrics = {
+        cyclesToConverge: enriched.iterations,
+        falsePositiveRate,
+        costUsd: _summedCost,
+        // Diagnostics — not part of the locked three but useful to readers
+        // of `.ijfw/telemetry/convergence.json`. The SDK verb stores the
+        // metrics object opaquely so extra keys are non-breaking.
+        verdict: finalVerdict,
+        commitRange: typeof commitRange === 'string' ? commitRange : null,
+        lensCount: lenses.length,
+        reachableObservations: _telemetryReachableObs,
+        alarmObservations: _telemetryAlarms,
+        durationMs: Date.now() - _startMs,
+      };
+      // Stable, run-scoped dedup key. The verb's append-idempotency (§4)
+      // requires a string; the runStamp is the canonical per-run identity
+      // and the commitRange disambiguates concurrent runs against different
+      // targets. Same (stamp, range) → same key → second record is dedup'd
+      // by the verb (deterministic for tests + safe under double-fire).
+      const dedupKey = `convergence:${_resolvedRunStamp}:${typeof commitRange === 'string' ? commitRange : 'nocommitrange'}`;
+      // Off the critical path: the await is wrapped + swallowed. The verdict
+      // has already been computed; this is observability only.
+      await _stateQuery('telemetry.record', {
+        kind: 'convergence',
+        metrics,
+        dedupKey,
+      }, {
+        projectRoot: _resolvedProjectDir,
+      }).catch(() => {
+        // Telemetry failures must NEVER affect the convergence verdict.
+        // (e.g. read-only FS, missing .ijfw/, lock contention) — swallow.
+      });
+    } catch {
+      // Defensive — should never throw before the `.catch` chain, but the
+      // metric computation itself (e.g. exotic NaN in _lensCosts) must not
+      // break the orchestrator return value.
+    }
+
+    return enriched;
+  }
+
+  let cycleSummary = null;
+  let prior = null;
+  let priorFindingsKey = null;
+  const perIteration = [];
+
+  for (let iter = 1; iter <= cap; iter++) {
+    // M6: stop the loop if the cumulative wall-clock budget has elapsed.
+    if (_totalTimedOut || _cycleAc.signal.aborted) {
+      return _finalize({
+        verdict: VERDICT_CONSENSUS_FAIL,
+        iterations: Math.max(1, iter - 1),
+        findings: [],
+        perIteration,
+      });
+    }
+
+    // M5: filter out lenses that have exceeded the per-lens USD cap.
+    const activeLenses = lenses.filter(l => !_lensOverBudget.has(l));
+    if (activeLenses.length === 0) {
+      // All lenses budget-capped — return what we have with consensus_failed.
+      return _finalize({
+        verdict: VERDICT_CONSENSUS_FAIL,
+        iterations: Math.max(1, iter - 1),
+        findings: [],
+        perIteration,
+      });
+    }
+
+    // Fire all (still-active) lenses in parallel.
+    _totalInvocations += activeLenses.length;
+    const settlements = await Promise.all(activeLenses.map(lens =>
+      Promise.resolve()
+        .then(() => dispatch({
+          lens,
+          commitRange,
+          iteration: iter,
+          cycleSummary,
+          projectRoot,
+          // M6: pass the cumulative AbortController signal to dispatchers
+          // that honor it. Existing tests inject a dispatcher that ignores
+          // `signal`; production dispatchers should pass it through to
+          // fireExternal so in-flight CLI/API calls tear down on deadline.
+          signal: _cycleAc.signal,
+        }))
+        .catch(err => ({
+          lens,
+          verdict: VERDICT_UNREACHABLE,
+          findings: [],
+          error: err && err.message ? err.message : String(err),
+        }))
+    ));
+
+    // M5: accrue per-lens cost + flag over-budget lenses for the next iter.
+    if (_resolvedPerLensCap) {
+      for (const s of settlements) {
+        if (!s || !s.lens) continue;
+        const cost = (typeof s.cost_usd === 'number' && Number.isFinite(s.cost_usd))
+          ? s.cost_usd
+          : (s.usage && typeof s.usage.cost_usd === 'number' ? s.usage.cost_usd : 0);
+        _lensCosts[s.lens] = (_lensCosts[s.lens] || 0) + cost;
+        if (_lensCosts[s.lens] > _resolvedPerLensCap) {
+          _lensOverBudget.add(s.lens);
+        }
+      }
+    } else {
+      // Even without a cap, still track cumulative cost for observability.
+      for (const s of settlements) {
+        if (!s || !s.lens) continue;
+        const cost = (typeof s.cost_usd === 'number' && Number.isFinite(s.cost_usd))
+          ? s.cost_usd
+          : (s.usage && typeof s.usage.cost_usd === 'number' ? s.usage.cost_usd : 0);
+        _lensCosts[s.lens] = (_lensCosts[s.lens] || 0) + cost;
+      }
+    }
+
+    // Map back to the full lens list: lenses we filtered out (budget-capped)
+    // synthesize a stub UNREACHABLE result so downstream divergence/stall
+    // detection sees the same lens set every iteration.
+    const settlementByLens = new Map();
+    for (let i = 0; i < settlements.length; i++) {
+      const r = settlements[i];
+      const lensId = r && r.lens ? r.lens : activeLenses[i];
+      settlementByLens.set(lensId, r);
+    }
+    const lensResults = lenses.map(lensId => {
+      const r = settlementByLens.get(lensId);
+      if (!r) {
+        // M5: budget-capped lens — present as UNREACHABLE with explanatory error.
+        return {
+          lens: lensId,
+          verdict: VERDICT_UNREACHABLE,
+          findings: [],
+          error: 'over per-lens budget',
+        };
+      }
+      return {
+        lens: r.lens || lensId,
+        verdict: r.verdict ? r.verdict : VERDICT_UNREACHABLE,
+        findings: Array.isArray(r.findings) ? r.findings : [],
+        ...(r.error ? { error: r.error } : {}),
+      };
+    });
+
+    // Build per-lens findings map for stall detection.
+    const perLensFindings = {};
+    for (const r of lensResults) perLensFindings[r.lens] = r.findings;
+    const findingsKey = stableFindingsKey(perLensFindings);
+
+    const reachable = lensResults.filter(r => r.verdict !== VERDICT_UNREACHABLE);
+    const divergence = detectDivergence(lensResults);
+
+    perIteration.push({
+      iteration: iter,
+      lensResults,
+      divergent: divergence.divergent,
+    });
+
+    const mergedFindings = lensResults.flatMap(r => r.findings.map(f => ({ ...f, _lens: r.lens })));
+
+    // Receipt cycle metadata — per-cycle finding count + verdict map.
+    const lensVerdicts = {};
+    for (const r of lensResults) lensVerdicts[r.lens] = r.verdict;
+    _receiptCycles.push({
+      iteration: iter,
+      findingCount: mergedFindings.length,
+      lensVerdicts,
+    });
+
+    // T21 — false-positive accounting. Every reachable lens observation is
+    // a denominator tick; every FAIL/CONDITIONAL vote is a numerator tick
+    // (it "raised an alarm"). Whether each alarm was a true or false positive
+    // is decided at finalize against the final consensus verdict (see
+    // `_finalize`). UNREACHABLE lenses are excluded from both numerator and
+    // denominator — a CLI that never replied is neither a true nor false
+    // positive, it's a no-data point.
+    for (const r of lensResults) {
+      if (r.verdict === VERDICT_UNREACHABLE) continue;
+      _telemetryReachableObs += 1;
+      if (r.verdict === VERDICT_FAIL || r.verdict === VERDICT_CONDITIONAL) {
+        _telemetryAlarms += 1;
+      }
+    }
+
+    // Stop conditions, in priority order.
+
+    // 1. maxIterations === 1 — cap the loop after first iter no matter what.
+    if (cap === 1) {
+      const verdict = reachable.length === 0
+        ? VERDICT_UNREACHABLE
+        : (divergence.divergent ? VERDICT_CONSENSUS_FAIL : reachable[0].verdict);
+      return _finalize({
+        verdict,
+        iterations: 1,
+        findings: mergedFindings,
+        ...(divergence.divergent ? { divergence: divergence.axes } : {}),
+        perIteration,
+      });
+    }
+
+    // 2. All reachable lenses PASS → done.
+    if (reachable.length > 0 && !divergence.divergent && reachable[0].verdict === VERDICT_PASS) {
+      return _finalize({
+        verdict: VERDICT_PASS,
+        iterations: iter,
+        findings: mergedFindings,
+        perIteration,
+      });
+    }
+
+    // 3. Consensus on non-PASS (e.g. all FAIL) — short-circuit, no point looping.
+    if (reachable.length > 0 && !divergence.divergent) {
+      return _finalize({
+        verdict: reachable[0].verdict,
+        iterations: iter,
+        findings: mergedFindings,
+        perIteration,
+      });
+    }
+
+    // 4. Stall breaker: byte-identical findings to prior iter → halt.
+    if (priorFindingsKey !== null && findingsKey === priorFindingsKey) {
+      return _finalize({
+        verdict: VERDICT_CONSENSUS_FAIL,
+        iterations: iter,
+        findings: mergedFindings,
+        divergence: divergence.axes,
+        stalled: true,
+        perIteration,
+      });
+    }
+
+    // 5. Cap hit while still divergent → consensus_failed.
+    if (iter === cap) {
+      return _finalize({
+        verdict: VERDICT_CONSENSUS_FAIL,
+        iterations: iter,
+        findings: mergedFindings,
+        divergence: divergence.axes,
+        perIteration,
+      });
+    }
+
+    // Otherwise: stage next iteration with cycle summary.
+    prior = { lensResults, divergence };
+    cycleSummary = buildCycleSummary(iter + 1, prior);
+    priorFindingsKey = findingsKey;
+  }
+
+  // Unreachable; loop must exit via one of the return paths above.
+  /* c8 ignore next */
+  return _finalize({ verdict: VERDICT_CONSENSUS_FAIL, iterations: cap, findings: [], perIteration });
+}
+
+// Default production dispatcher.  Wraps the existing single-lens spawn path
+// (audit-roster pick → buildRequest → fireExternal → parseResponse →
+// classifyVerdict).  Tests pass their own dispatcher; production callers can
+// either pass this one or supply a customized wrapper.
+//
+// One quirk: this dispatcher embeds the cycleSummary into the audit target
+// string (prefixed) so the lens sees prior-round context in its prompt.
+// Lens stdout shape: same as parseResponse('audit', stdout).
+export async function defaultConvergeDispatch({ lens, commitRange, iteration, cycleSummary, projectRoot, signal } = {}) {
+  const env = process.env;
+  const entry = ROSTER.find(e => e.id === lens);
+  if (!entry) {
+    return { lens, verdict: VERDICT_UNREACHABLE, findings: [], error: `lens "${lens}" not in roster` };
+  }
+  // v1.5.0 wire-W1.F — honor a pre-aborted cumulative-timeout signal before
+  // any CLI/API spawn so runPhaseEConverge's totalTimeoutMs cap actually
+  // bounds wall-clock time when the deadline expired between iterations.
+  if (signal && signal.aborted) {
+    return { lens, verdict: VERDICT_UNREACHABLE, findings: [], error: 'aborted' };
+  }
+  const reach = isReachable(lens, env);
+  if (!reach.any) {
+    return { lens, verdict: VERDICT_UNREACHABLE, findings: [], error: `lens "${lens}" CLI missing and no apiFallback` };
+  }
+  const pick = (!reach.cli && reach.api) ? { ...entry, preferredSource: 'api' } : { ...entry };
+
+  // v1.5.0 audit-H4.2 — cycleSummary MUST come AFTER any cache_control-eligible
+  // block. Cached content (the stable commitRange/target) goes FIRST so user-
+  // message cache_control (planned for v1.5.0 ADJUDICATION-1 cap-layer work)
+  // hits the same prefix on every iteration; the iteration-varying summary
+  // goes LAST so it never busts the cache. The previous prefix layout would
+  // invalidate the cache on every iteration ≥ 2. See ADJUDICATIONS.md
+  // DISPUTED-1 (cache_control ordering invariant).
+  const target = (iteration > 1 && cycleSummary)
+    ? `${commitRange}\n\n---\n\n${cycleSummary}`
+    : commitRange;
+
+  const request = buildRequest('audit', target, pick.id, 'general', null);
+  const timeoutMs = timeoutForPick(pick, null);
+  try {
+    // v1.5.0 wire-W1.F — forward cumulative-timeout signal so in-flight CLI
+    // spawn + API fallback both cascade their AbortControllers on deadline.
+    const raw = await fireExternal(pick, request, timeoutMs, env, signal || null);
+    if (!raw || raw.status === 'timeout' || raw.status === 'failed' || raw.status === 'aborted') {
+      return { lens, verdict: VERDICT_UNREACHABLE, findings: [], error: (raw && raw.stderr) || 'no output' };
+    }
+    if (raw.exitCode !== 0 && raw.status !== 'fallback-used') {
+      return { lens, verdict: VERDICT_UNREACHABLE, findings: [], error: `exit ${raw.exitCode}` };
+    }
+    const parsed = parseResponse('audit', raw.stdout);
+    const items = Array.isArray(parsed.items) ? parsed.items : [];
+    const verdict = classifyVerdict(items);
+    return { lens, verdict, findings: items };
+  } catch (err) {
+    return { lens, verdict: VERDICT_UNREACHABLE, findings: [], error: err && err.message ? err.message : String(err) };
+  }
+  /* projectRoot reserved for future per-project dispatcher overrides */
+  // eslint-disable-next-line no-unreachable
+  void projectRoot;
+}
+