@ijfw/memory-server 1.4.4 → 1.5.1

package/src/orchestrator/checkpoint-contract.md

@@ -0,0 +1,140 @@
+# Subagent Checkpoint Contract — v1.5.0 S1
+
+**Status:** Frozen. Wave 11-A1 wire-up.
+
+## Why this exists
+
+Across IJFW v1.4.4 Wave 10 + v1.5.0 research dispatch, **8 of 13 subagents (62%) truncated mid-flow** at the Claude Code harness cap (~20 tool uses or ~60s wall, whichever first). Truncation manifested as silent stop without a Status: report — orchestrator had to read partial worktree state and finish by hand. The checkpoint contract closes this gap by giving the orchestrator a structured record of "what the agent was doing when it died" so it can resume from the last known good state instead of redispatching from scratch.
+
+## The CLI
+
+```bash
+ijfw checkpoint <waveId> <subId> <jsonPayload>
+```
+
+- `<waveId>` and `<subId>` MUST match `[A-Za-z0-9_-]{1,64}` (no path traversal).
+- `<jsonPayload>` is a JSON object string. Wrapping fields (`schema_version`, `wave_id`, `sub_id`, `ts`) are added by the CLI; do not include them yourself.
+- The CLI atomically writes via `withFsLock` to `.ijfw/wave-<waveId>/subagent-<subId>.checkpoint.json`. Concurrent calls from the same subId serialise.
+
+## What to put in the payload
+
+Recommended fields (free-form — the schema accepts arbitrary keys, but these are what the orchestrator looks for on resume):
+
+| Field | Type | Purpose |
+|---|---|---|
+| `tool_use_count` | integer | How many tool calls the agent has made. Helps the orchestrator estimate cap proximity. |
+| `last_action` | string ≤200 chars | Human-readable description of what the agent just finished. |
+| `files_created` | string[] | Paths the agent has created so far (relative to project root). |
+| `files_modified` | string[] | Paths the agent has modified so far. |
+| `commits_made` | string[] | SHA list of commits the agent has landed. |
+| `next_step` | string ≤200 chars | What the agent intends to do next. **The orchestrator's resume protocol picks up here.** |
+| `blockers` | string (optional) | Set only if the agent paused due to ambiguity or environment issue. Triggers `NEEDS_CONTEXT` handling. |
+
+## Cadence
+
+**Checkpoint every substantive tool use OR every 30 seconds, whichever first.** Do not checkpoint after pure read-only tool calls — that just burns your tool budget. Examples of "substantive":
+
+- After a Write that produced a non-trivial file.
+- After an Edit that changed code semantics.
+- After a Bash that ran tests, built artifacts, or made commits.
+- After a substantive piece of analysis you don't want to repeat.
+
+Examples of "not substantive" (skip the checkpoint):
+
+- Read of a small file you already had context for.
+- Glob/Grep that returned nothing surprising.
+
+## Size cap
+
+Serialised payload (after the CLI adds wrapping fields) must be ≤ **4 KB**. The CLI rejects larger payloads with a clear error. Keep `last_action` and `next_step` under 200 chars each; trim file lists if they grow past ~20 entries.
+
+## How orchestrator detects + resumes truncation
+
+1. After the agent returns, the orchestrator inspects its message for a `Status: <VALUE>` line per the v1.4.4 status protocol.
+2. If no Status line, the orchestrator treats the agent as truncated.
+3. It calls `listOrphanedSubagents(waveId, projectRoot)` to find subagents with a checkpoint file but no completion marker in STATE.md.
+4. For each orphan, it calls `readLastCheckpoint(waveId, subId, projectRoot)`.
+5. It re-dispatches the subagent with a prepended context block:
+
+   ```
+   PRIOR CHECKPOINT (from your last truncated run):
+   - Tool uses: <tool_use_count>
+   - Last action: <last_action>
+   - Files created: <files_created>
+   - Files modified: <files_modified>
+   - Commits made: <commits_made>
+   - Intended next step: <next_step>
+   - Blockers (if any): <blockers>
+
+   RESUME FROM `next_step`. Do NOT restart from scratch. Re-verify your prior commits are intact, then continue.
+   ```
+
+6. The resumed agent verifies its prior commits + continues. The orchestrator confirms by checking that the next commit touches files in the checkpoint's modified list (or the agent must explain divergence in the commit message).
+
+## Backward compatibility
+
+Subagents that don't call `ijfw checkpoint` still work — they just have the same truncation-recovery cost as v1.4.4 (orchestrator-side hand-finishing). The contract is opt-in for the implementer; opt-in for the orchestrator's resume protocol.
+
+## Real-world evidence
+
+| Dispatch | Cap hit at | Outcome |
+|---|---|---|
+| v1.4.4 W10-A2 | 19 tool uses / 3:00 | Orchestrator finished in-place |
+| v1.4.4 W10-A3 | 28 / 3:30 | Orchestrator finished in-place |
+| v1.4.4 W10-B2 | 10 / 0:42 | Orchestrator finished in-place |
+| v1.5.0 R1 (research) | 25 / 43s | Lost work — no commit |
+| v1.5.0 R2-first | 33 / 587s | Lost work — empty branch |
+| v1.5.0 R4-first | 55 / 167s | Lost work — partial file recovered |
+| v1.5.0 R1-redo | 19 / 58s | Lost work — even with anti-truncation prompt |
+| v1.5.0 R4-redo | 17 / 49s | Lost work — even with anti-truncation prompt |
+| v1.5.0 W11-A0 | 14 / 69s | Files written but commit failed |
+| v1.5.0 W11-A1 | 14 / 80s | First commit landed, last two lost |
+
+**8 of 13 dispatches = 62% truncation rate.** v1.5.0 S1 is the load-bearing fix for this class of failure.
+
+## Worktree isolation drain protocol — v1.5.0-major S01
+
+The v1.5.0 S1 checkpoint contract above assumes the subagent's `projectRoot` matches the orchestrator's `projectRoot`. That assumption **does not hold** for canonical dispatch in `isolation: 'worktree'` mode: the Claude Code harness spawns the subagent with `cwd` set to a disposable worktree (e.g. `.claude/worktrees/agent-<id>/`), so `process.cwd()` resolves to the worktree — not the parent project. Checkpoints written under the worktree's `.ijfw/` directory vanish the moment `git worktree remove` runs, taking truncation forensics with them.
+
+**This was R3's #1 honest finding for v1.5.0:** without the fix below, S1 is shelfware in the canonical dispatch mode where it matters most.
+
+### How the fix works
+
+Two complementary mechanisms:
+
+1. **Env-var passthrough (primary).** When the orchestrator/dispatcher spawns a worktree subagent, it MUST set:
+
+   ```
+   IJFW_PARENT_PROJECT_ROOT=<absolute path to the parent projectRoot>
+   ```
+
+   `orchestrator/subagent-telemetry.js` (`recordCheckpoint`, `readLastCheckpoint`, `listOrphanedSubagents`) and `dispatch/checkpoint-cli.js` consult this env var first and fall back to the passed `projectRoot` when absent. Net effect: a worktree subagent's `ijfw checkpoint` write lands in the **parent** project's `.ijfw/wave-<id>/` directory automatically — visible to the orchestrator before and after worktree cleanup, no drain step required.
+
+   The `ijfw checkpoint` CLI also logs the resolved root to stderr (`ijfw checkpoint: writing to <root>/.ijfw/wave-<id>/`) so operators can see at a glance whether the env var was honored.
+
+2. **Belt-and-suspenders drain (fallback).** When the dispatcher cannot set env vars (older Claude Code harness builds, manual `claude` invocation inside a worktree, third-party orchestrators), the subagent's checkpoint still lands in the worktree's `.ijfw/`. To prevent loss, the orchestrator MUST run the drain CLI **BEFORE** `git worktree remove`:
+
+   ```
+   ijfw worktree-drain <waveId> <worktreePath>
+   ```
+
+   This copies every `<worktreePath>/.ijfw/wave-<waveId>/subagent-*.checkpoint.json` into the parent's `.ijfw/wave-<waveId>/`. Idempotent (safe to re-run). Returns `{ok:true, drained: N}` (or `{ok:true, drained: 0}` if the worktree has no checkpoints).
+
+### Orchestrator scanning across active worktrees
+
+`listOrphanedSubagents(waveId, projectRoot, additionalRoots)` accepts an optional `additionalRoots: string[]` argument — pass the list of active worktree paths (typically from `git worktree list --porcelain`) so the orchestrator sees in-flight checkpoints from worktree subagents that have NOT yet drained. Returned subId list is deduplicated across all scanned roots.
+
+### Backward compatibility
+
+- **Subagents without the env var set** continue to write to the passed `projectRoot` (which for legacy non-worktree dispatch is already correct).
+- **Subagents in a worktree without the env var set** write to the worktree's own `.ijfw/` — the orchestrator's `ijfw worktree-drain` pre-cleanup step recovers them.
+- **`listOrphanedSubagents` called without `additionalRoots`** preserves v1.5.0-S1 behavior (single-root scan).
+
+### Why both mechanisms
+
+Env passthrough is the right primary because it makes checkpoints visible **continuously**, not just at cleanup time (matters for live `wave-status` queries and mid-flight resume). The drain step exists because env passthrough requires harness cooperation that may not exist in every dispatch path; the drain ensures checkpoints survive even when the env var doesn't propagate.
+
+### Wiring status
+
+- `subagent-telemetry.js`, `checkpoint-cli.js`, `wave-cli.js` (`worktree-drain`) — wired in v1.5.0 W12-A0 S01.
+- Dispatcher env passthrough — **TODO marker** in `dispatch/extension.js`; depends on Claude Code harness exposing an env-passthrough hook on `Agent({ isolation: 'worktree' })` spawn. Until that lands, orchestrators MUST rely on the drain step.

package/src/orchestrator/debug-trident-trigger.js

@@ -0,0 +1,374 @@
+/**
+ * debug-trident-trigger.js — v1.5.1: the LIVE production trigger for the
+ * Trident-powered debug loop (T29, debug-trident.js).
+ *
+ * --------------------------------------------------------------------------
+ * WHY THIS MODULE EXISTS
+ * --------------------------------------------------------------------------
+ *
+ * debug-trident.js (`runDebugCampaign`) is the cross-AI debug pillar — when a
+ * single-lens hypothesis tree stalls, it dispatches codex + gemini lenses in
+ * parallel to generate competing hypotheses. v1.5.1 W2.C wired it into
+ * `runPostDone` (post-done-runner.js) — but `runPostDone` is itself NOT on the
+ * live subagent-completion path. The live path is the `subagent.post-done`
+ * verb in state-sdk.js, which calls `runSelfCheck`, never `runPostDone`. So
+ * T29 was "tested but never firing in production".
+ *
+ * This module is the genuine wiring. It exposes ONE entrypoint —
+ * `maybeFireDebugTrident` — designed to be called fire-and-forget from the
+ * live gate-failure branch of the `subagent.post-done` verb. It mirrors the
+ * A-Mem auto-linking precedent in memory/fts5.js exactly:
+ *
+ *   - The caller does NOT await it. The verb's return value and timing are
+ *     unchanged — STATE-SDK-CONTRACT §8 classes `subagent.post-done` as a
+ *     fast read verb; an inline blocking multi-lens AI call would violate
+ *     that contract. The campaign runs in the background.
+ *   - Env-gated. `IJFW_DEBUG_TRIDENT=1` enables it; default is OFF. (A-Mem's
+ *     auto-linker is default-ON with an `IJFW_AUTOLINK_OFF` kill switch;
+ *     debug-trident spawns EXTERNAL codex/gemini processes, so the safe
+ *     default for an unattended gate-failure path is opt-in — but the
+ *     env-gate + silent-no-op shape is identical.)
+ *   - Silent no-op on missing deps. No codex/gemini CLI reachable, no
+ *     dispatcher, a thrown import — every failure mode resolves to a quiet
+ *     skip. It NEVER throws into the caller.
+ *   - Result persistence. The competing-hypotheses output is written to an
+ *     append-only JSONL receipt under `.ijfw/receipts/debug-campaigns.jsonl`
+ *     so the dashboard / next phase can read it. (mirrors receipts.js).
+ *
+ * --------------------------------------------------------------------------
+ * THE DISPATCHER
+ * --------------------------------------------------------------------------
+ *
+ * runDebugCampaign needs a `tridentDispatch({ lens, evidencePack,
+ * currentHypotheses }) => { lens, hypotheses }`. IJFW's production multi-lens
+ * dispatcher is `defaultConvergeDispatch` in cross-orchestrator.js (the same
+ * one runPhaseEConverge + ijfw_cross_audit_converge use to spawn real
+ * codex/gemini). We obtain it via a DYNAMIC import() — static import would
+ * create a require cycle (cross-orchestrator.js → state-sdk.js telemetry →
+ * back here), and truncation.js was wired the same way (state-sdk.js:1246,
+ * commit 75e5894). The adapter wraps `defaultConvergeDispatch` (an audit
+ * dispatcher returning `{ verdict, findings }`) into the hypothesis-gen shape
+ * runDebugCampaign expects: each audit finding becomes one competing
+ * hypothesis row.
+ *
+ * Zero new prod deps. ESM. Node ≥18. No emoji.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { runDebugCampaign } from './debug-trident.js';
+
+/**
+ * Env gate. `IJFW_DEBUG_TRIDENT=1` (or `true`/`on`) turns the live trigger
+ * on. Default OFF — the campaign spawns external codex/gemini processes, so
+ * an unattended gate-failure path stays opt-in. Read on every call so a test
+ * harness can flip it without re-importing.
+ */
+export function debugTridentEnabled() {
+  const v = String(process.env.IJFW_DEBUG_TRIDENT || '').trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'on' || v === 'yes';
+}
+
+/**
+ * Receipt path — append-only JSONL, sibling of the cross-run receipts file.
+ */
+export function debugCampaignReceiptPath(projectRoot) {
+  return path.join(projectRoot, '.ijfw', 'receipts', 'debug-campaigns.jsonl');
+}
+
+// Cap on receipt entries — same MAX_RECEIPTS posture as receipts.js so the
+// file never grows unbounded under a flapping gate.
+const MAX_DEBUG_RECEIPTS = 100;
+
+/**
+ * Append one debug-campaign record to the JSONL receipt. Best-effort: a
+ * write failure is swallowed (the campaign verdict is never altered by a
+ * diagnostic-write failure — mirrors fts5.js graph-errors.jsonl discipline).
+ */
+function writeDebugCampaignReceipt(projectRoot, record) {
+  try {
+    const dest = debugCampaignReceiptPath(projectRoot);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.appendFileSync(dest, JSON.stringify(record) + '\n');
+    // Prune to the last MAX_DEBUG_RECEIPTS lines.
+    try {
+      const raw = fs.readFileSync(dest, 'utf8');
+      const lines = raw.split('\n').filter((l) => l.trim());
+      if (lines.length > MAX_DEBUG_RECEIPTS) {
+        fs.writeFileSync(dest, lines.slice(-MAX_DEBUG_RECEIPTS).join('\n') + '\n');
+      }
+    } catch { /* prune is best-effort */ }
+  } catch { /* receipt write must never throw into the caller */ }
+}
+
+/**
+ * Read all debug-campaign receipts for a project. Skips corrupt lines.
+ * Used by the integration test + (future) the dashboard.
+ */
+export function readDebugCampaignReceipts(projectRoot) {
+  const file = debugCampaignReceiptPath(projectRoot);
+  if (!fs.existsSync(file)) return [];
+  const out = [];
+  try {
+    const raw = fs.readFileSync(file, 'utf8');
+    for (const line of raw.split('\n')) {
+      if (!line.trim()) continue;
+      try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+    }
+  } catch { /* unreadable -> empty */ }
+  return out;
+}
+
+/**
+ * Build the production `tridentDispatch` function runDebugCampaign needs.
+ *
+ * `defaultConvergeDispatch` (cross-orchestrator.js) is an AUDIT dispatcher:
+ * it spawns a lens CLI with an audit prompt and returns
+ * `{ lens, verdict, findings:[...] }`. runDebugCampaign instead wants a
+ * hypothesis generator returning `{ lens, hypotheses:[{hypothesis,rationale}] }`.
+ * The adapter bridges the two: the evidence pack is handed to the lens as the
+ * audit target, and each returned finding is mapped to one competing
+ * hypothesis (finding text → hypothesis, severity/category → rationale).
+ *
+ * A lens that is unreachable returns verdict UNREACHABLE / zero findings,
+ * which the adapter passes through as zero hypotheses — runDebugCampaign
+ * already treats that as a non-contributing lens (no crash).
+ *
+ * Returns `null` when the dispatcher cannot be loaded at all (missing
+ * module) — the caller treats that as a silent no-op.
+ */
+export async function buildTridentDispatch() {
+  let defaultConvergeDispatch;
+  try {
+    // DYNAMIC import — avoids a static require cycle through
+    // cross-orchestrator.js -> receipts/telemetry -> state-sdk.js.
+    ({ defaultConvergeDispatch } = await import('../cross-orchestrator.js'));
+  } catch {
+    return null;
+  }
+  if (typeof defaultConvergeDispatch !== 'function') return null;
+
+  return async function tridentDispatch({ lens, evidencePack, currentHypotheses, signal } = {}) {
+    // Embed the already-tried hypotheses so the lens avoids re-proposing
+    // refuted theory (runDebugCampaign also dedups, this just saves tokens).
+    const triedBlock = Array.isArray(currentHypotheses) && currentHypotheses.length > 0
+      ? '\n\n## Hypotheses already considered (propose DIFFERENT ones)\n'
+        + currentHypotheses
+          .map((h) => `- ${h && h.hypothesis ? h.hypothesis : ''} `
+            + `[${h && h.status ? h.status : 'open'}]`)
+          .join('\n')
+      : '';
+    const target = `## Stalled debug investigation — generate competing root-cause hypotheses\n\n`
+      + `${typeof evidencePack === 'string' ? evidencePack : ''}${triedBlock}`;
+    let raw;
+    try {
+      raw = await defaultConvergeDispatch({
+        lens,
+        commitRange: target,
+        iteration: 1,
+        cycleSummary: null,
+        signal: signal || null,
+      });
+    } catch (err) {
+      return { lens, hypotheses: [], ok: false, reason: err && err.message ? err.message : String(err) };
+    }
+    const findings = raw && Array.isArray(raw.findings) ? raw.findings : [];
+    const hypotheses = findings
+      .map((f) => {
+        if (!f || typeof f !== 'object') return null;
+        const text = typeof f.finding === 'string' && f.finding.trim()
+          ? f.finding.trim()
+          : (typeof f.title === 'string' ? f.title.trim() : '');
+        if (!text) return null;
+        const rationaleParts = [];
+        if (f.severity) rationaleParts.push(`severity:${f.severity}`);
+        if (f.category) rationaleParts.push(`category:${f.category}`);
+        if (typeof f.rationale === 'string' && f.rationale.trim()) {
+          rationaleParts.push(f.rationale.trim());
+        }
+        return { hypothesis: text, rationale: rationaleParts.join(' ') };
+      })
+      .filter(Boolean);
+    return { lens, hypotheses };
+  };
+}
+
+/**
+ * Fire-and-forget entrypoint — call this from the LIVE `subagent.post-done`
+ * gate-failure branch. It returns IMMEDIATELY; the actual campaign runs in a
+ * detached promise. The verb's return value and timing are unchanged.
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot   project root (where `.ijfw/` lives)
+ * @param {string} [opts.subagentId]  the subagent whose gate failed
+ * @param {string} [opts.reason]      the gate-failure reason string
+ * @param {string} [opts.reportText]  the subagent's DONE report (evidence)
+ * @param {object} [opts.selfCheck]   the failed self-check result (evidence)
+ * @returns {void}                    nothing — never throws
+ *
+ * Diagnostic hook: `maybeFireDebugTrident.__lastCampaignPromise` holds the
+ * most recent background promise so integration tests can `await` it before
+ * asserting on the receipt (mirrors `indexEntry.__lastAutoLinkPromise` in
+ * memory/fts5.js). Production callers do NOT read this.
+ */
+export function maybeFireDebugTrident(opts = {}) {
+  // Gate 1 — env opt-in. Disabled => true no-op. No promise, no receipt.
+  if (!debugTridentEnabled()) {
+    maybeFireDebugTrident.__lastCampaignPromise = null;
+    return;
+  }
+  const projectRoot = typeof opts.projectRoot === 'string' && opts.projectRoot
+    ? opts.projectRoot : null;
+  if (!projectRoot) {
+    maybeFireDebugTrident.__lastCampaignPromise = null;
+    return;
+  }
+
+  const subagentId = typeof opts.subagentId === 'string' && opts.subagentId
+    ? opts.subagentId : 'unknown';
+  const reason = typeof opts.reason === 'string' ? opts.reason : 'gate-failure';
+  const reportText = typeof opts.reportText === 'string' ? opts.reportText : '';
+  const selfCheck = opts.selfCheck && typeof opts.selfCheck === 'object'
+    ? opts.selfCheck : null;
+  // A test-supplied dispatcher (stub) short-circuits the dynamic import —
+  // lets the integration test prove the wiring fires WITHOUT spawning real
+  // codex/gemini. Production callers never pass this.
+  const injectedDispatch = typeof opts.tridentDispatch === 'function'
+    ? opts.tridentDispatch : null;
+
+  // Compose the evidence pack from the gate-failure context. This is what
+  // the codex/gemini lenses reason over.
+  const evidenceLines = [
+    `Subagent ${subagentId} failed its post-done self-check gate.`,
+    `Gate-failure reason: ${reason}`,
+  ];
+  if (selfCheck) {
+    if (Array.isArray(selfCheck.files_missing) && selfCheck.files_missing.length) {
+      evidenceLines.push(`Missing claimed files: ${selfCheck.files_missing.join(', ')}`);
+    }
+    if (Array.isArray(selfCheck.commits_missing) && selfCheck.commits_missing.length) {
+      evidenceLines.push(`Missing claimed commits: ${selfCheck.commits_missing.join(', ')}`);
+    }
+  }
+  if (reportText) {
+    evidenceLines.push('', '--- Subagent DONE report ---', reportText.slice(0, 4000));
+  }
+  const evidencePack = evidenceLines.join('\n');
+
+  // The seed hypothesis — the single-lens reading that "stalled" (the gate
+  // failed). Trident dispatches codex+gemini for competing alternatives.
+  const seedHypotheses = [
+    {
+      id: 'H1',
+      hypothesis: `Subagent ${subagentId} reported DONE but did not produce the claimed artifacts (${reason}).`,
+      status: 'open',
+      evidence: reason,
+      refuted_by: '',
+    },
+  ];
+
+  // Fire-and-forget — NOT awaited. Any failure resolves to a quiet skip.
+  const campaignPromise = (async () => {
+    let tridentDispatch = injectedDispatch;
+    if (!tridentDispatch) {
+      tridentDispatch = await buildTridentDispatch();
+    }
+    if (typeof tridentDispatch !== 'function') {
+      // No dispatcher (missing module / missing CLIs) — silent no-op.
+      writeDebugCampaignReceipt(projectRoot, {
+        ts: new Date().toISOString(),
+        subagentId,
+        reason,
+        outcome: 'skipped',
+        skipReason: 'no-trident-dispatcher',
+      });
+      return { skipped: true, skipReason: 'no-trident-dispatcher' };
+    }
+
+    // The per-cycle `dispatch` for the live trigger: cycle 1 reports the
+    // single-lens stall (INVESTIGATION_INCONCLUSIVE) so the campaign
+    // immediately escalates to Trident; cycle 2 reports inconclusive again
+    // so the campaign terminates cleanly once competing hypotheses exist.
+    // The point of the LIVE trigger is to GENERATE the competing-hypotheses
+    // set off a real gate failure, not to auto-resolve the bug — resolution
+    // is the ijfw-debugger agent's job, this just seeds it.
+    let stallCycles = 0;
+    const dispatch = async () => {
+      stallCycles += 1;
+      return { terminator: 'INVESTIGATION_INCONCLUSIVE' };
+    };
+
+    let campaign;
+    try {
+      campaign = await runDebugCampaign({
+        sessionId: `gate-failure-${subagentId}`,
+        symptoms: `post-done self-check FAILED for ${subagentId} — ${reason}`,
+        hypotheses: seedHypotheses,
+        dispatch,
+        tridentDispatch,
+        tridentLenses: ['codex', 'gemini'],
+        maxCycles: 2,
+        evidencePack,
+        projectRoot,
+        // recordTelemetry stays on (default) — the campaign also writes a
+        // telemetry.record via the state-SDK, same as the unit-tested path.
+      });
+    } catch (err) {
+      writeDebugCampaignReceipt(projectRoot, {
+        ts: new Date().toISOString(),
+        subagentId,
+        reason,
+        outcome: 'failed',
+        error: err && err.message ? err.message : String(err),
+      });
+      return { skipped: false, error: err && err.message ? err.message : String(err) };
+    }
+    void stallCycles;
+
+    // Persist the competing-hypotheses output. This is the receipt the
+    // dashboard / next phase reads — the campaign output is NOT lost.
+    const competing = Array.isArray(campaign.hypothesesFinal)
+      ? campaign.hypothesesFinal.filter(
+        (h) => h && typeof h.from === 'string' && h.from.startsWith('trident:'),
+      )
+      : [];
+    writeDebugCampaignReceipt(projectRoot, {
+      ts: new Date().toISOString(),
+      subagentId,
+      reason,
+      outcome: campaign.outcome,
+      sessionId: campaign.sessionId,
+      cycles: campaign.cycles,
+      stalls: campaign.stalls,
+      tridentInvocations: campaign.tridentInvocations,
+      hypothesesAdded: campaign.hypothesesAdded,
+      competingHypotheses: competing.map((h) => ({
+        id: h.id,
+        from: h.from,
+        hypothesis: h.hypothesis,
+        rationale: h.rationale || '',
+      })),
+      durationMs: campaign.duration_ms,
+    });
+    return { skipped: false, campaign };
+  })().catch((err) => {
+    // Last-resort guard — the background promise must NEVER surface an
+    // unhandled rejection. Best-effort receipt, then swallow.
+    try {
+      writeDebugCampaignReceipt(projectRoot, {
+        ts: new Date().toISOString(),
+        subagentId,
+        reason,
+        outcome: 'failed',
+        error: err && err.message ? err.message : String(err),
+      });
+    } catch { /* nothing more we can do */ }
+    return { skipped: false, error: err && err.message ? err.message : String(err) };
+  });
+
+  // Expose for deterministic test awaiting only.
+  maybeFireDebugTrident.__lastCampaignPromise = campaignPromise;
+}
+
+maybeFireDebugTrident.__lastCampaignPromise = null;