@dzhechkov/harness-core 0.5.0 → 0.5.1

package/src/loop-run-semantics.ts

@@ -0,0 +1,278 @@
+/**
+ * `loop-run-semantics` — the ONE home of loop-designer's ENACTMENT DECISIONS (feature
+ * dz-workflow-run, ADR-001 W4).
+ *
+ * Before this module these semantics existed ONLY as template strings inside
+ * `loop-render.ts:renderRuntime` — readable by the generated Claude-host script and by nobody
+ * else. A second enactor (`dz workflow run`) would have had to COPY them, and two copies of a
+ * gate-verdict grammar is exactly how a runner comes to synthesize a pass the render would have
+ * refused. So the decisions move here once and are consumed twice:
+ *   • the generated script gets them as a BLOB (`scripts/gen-loop-blobs.mjs`, blob `loop-semantics`,
+ *     always on — the base runtime references errText/classifyFailure in every script);
+ *   • the dz runner imports them directly.
+ * "Imported, not copied" stops being an intention and becomes a fact a test can check.
+ *
+ * SCOPE, honestly (ADR-001 names it): what moves is DECISION semantics. `__drainAll`,
+ * `runStep` and `__settleStep` do NOT move — they are HOST-STRUCTURAL (they wrap the sandbox's
+ * `parallel()`/`agent()` and its settle discipline); the runner has its own structured concurrency
+ * and its own settle path.
+ *
+ * BLOB-SOURCE DISCIPLINE (same rule as `loop-trace.ts`): this module has NO RUNTIME IMPORT — its
+ * single `import type` is erased at compile time, so the generator can slice declarations out of it
+ * with no import to resolve. The generator's INV-12 output ban (fs / clock / randomness / process)
+ * holds here by construction: every function below is pure.
+ *
+ * One consequence of that discipline is visible in the signatures: the six BLOB-EXPORTED functions
+ * may not mention an IMPORTED type by bare name (the slicer would see an unresolvable cross-file
+ * reference and fail closed), so `classifyFailure` spells its return type as the inline import type
+ * `import('./loop-plan.js').FailureClass`. It is the SAME closed enum — one domain, not a restated
+ * copy — written in the one form the slicer can carry.
+ */
+
+import type { Deliverable, LoopPlan } from './loop-plan.js';
+
+/** Blob version stamp read by scripts/gen-loop-blobs.mjs. */
+export const LOOP_RUN_SEMANTICS_BLOB_VERSION = '1.0.0';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// BLOB EXPORTS — sliced verbatim into every rendered script AND imported by the runner.
+// Byte-semantics preserved from the template originals (loop-render.ts, pre-extraction):
+//   errText ← __errText · causeChain ← __causeChain · errSnap ← __errSnap
+//   classifyFailure ← __classifyFailure · gateVerdict ← __gateVerdict · joinRegion ← joinRegion
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ErrSnapLink {
+  code: string | null;
+  name: string | null;
+  text: string;
+}
+
+/**
+ * TOTAL error-to-text (the ha-consilium 5b totality lesson): the writer's own settle event must
+ * survive a hostile error object. `String(err)` throws on a null-prototype object and a throwing
+ * `.message` getter throws on access — both are caught here, so rendering a message can never
+ * replace the original failure or lose the settle. `.message` is read ONCE into a local (a one-shot
+ * getter answered the `typeof` probe and vanished on the value read — snapshot-once defeats it).
+ */
+export function errText(err: unknown): string {
+  try {
+    if (err !== null && typeof err === 'object') {
+      const m = (err as { message?: unknown }).message;
+      if (typeof m === 'string') return m;
+    }
+    return String(err);
+  } catch (_e) {
+    try {
+      return Object.prototype.toString.call(err);
+    } catch (_e2) {
+      return '[unrenderable error]';
+    }
+  }
+}
+
+/**
+ * The `err.cause` chain, bounded (depth 5), cycle-safe and getter-safe. The standard Node fetch
+ * shape `TypeError('fetch failed', { cause: { code: 'ECONNRESET' } })` hides its real class one
+ * link down, so classification must see the whole chain, not the outermost error.
+ */
+export function causeChain(err: unknown): unknown[] {
+  const chain: unknown[] = [];
+  let cur: unknown = err;
+  for (let d = 0; d < 5; d++) {
+    if (cur === null || cur === undefined) break;
+    if (chain.indexOf(cur) !== -1) break; // cycle-safe
+    chain.push(cur);
+    try {
+      cur = typeof cur === 'object' ? (cur as { cause?: unknown }).cause : undefined;
+    } catch (_e) {
+      cur = undefined; // getter-safe
+    }
+  }
+  return chain.length > 0 ? chain : [err];
+}
+
+/**
+ * ONE snapshot PER FAILURE. The earlier shape snapshotted `.message` once per `errText` CALL, not
+ * once per failure — so logging read it, classification read it AGAIN, and a one-shot `.message`
+ * getter answered the log and defeated the classifier (2 getter reads, 1 attempt, MEASURED). The
+ * catch site builds this snapshot once; the log line and the classifier both consume the SNAPSHOT,
+ * so `.code` / `.name` / `.message` are each read exactly once per failure, over the whole chain.
+ */
+export function errSnap(err: unknown): ErrSnapLink[] {
+  const chain = causeChain(err);
+  const snap: ErrSnapLink[] = [];
+  for (let ci = 0; ci < chain.length; ci++) {
+    let code: string | null = null;
+    try {
+      const c = chain[ci] !== null && typeof chain[ci] === 'object' ? (chain[ci] as { code?: unknown }).code : null;
+      code = typeof c === 'string' ? c.toUpperCase() : null;
+    } catch (_e) {
+      code = null;
+    }
+    let name: string | null = null;
+    try {
+      const n = chain[ci] !== null && typeof chain[ci] === 'object' ? (chain[ci] as { name?: unknown }).name : null;
+      name = typeof n === 'string' ? n : null;
+    } catch (_e) {
+      name = null;
+    }
+    snap.push({ code: code, name: name, text: errText(chain[ci]) });
+  }
+  return snap;
+}
+
+/**
+ * The CLOSED failure classification of `loop-plan/1` (timeout | transport | malformed-output |
+ * policy-refusal). THREE TIERS over the whole cause chain, strongest first:
+ *   1. error CODE — works on non-Error shapes like `{code:'ECONNRESET'}`, never message-dependent
+ *      (`ETIMEDOUT` is a TRANSPORT code; an earlier message regex captured it as 'timeout' first);
+ *   2. error NAME — `SyntaxError` = parsing the model's output failed → malformed-output;
+ *   3. message patterns, DISJOINT by precedence transport > policy-refusal > malformed-output >
+ *      timeout, every alternative WORD-BOUNDED (an unbounded `rate.?limit` matched
+ *      'delibeRATE LIMITation' — a substring must never smuggle a class).
+ * `outcome: 'null'` (a dead/empty agent) is a delivery failure ⇒ `transport`, retryable ONLY under
+ * `retryOn: ['transport']`. An UNCLASSIFIABLE failure returns null and is NEVER retried.
+ */
+export function classifyFailure(
+  outcome: 'null' | 'error',
+  snap: ErrSnapLink[],
+): import('./loop-plan.js').FailureClass | null {
+  if (outcome === 'null') return 'transport';
+  const links = Array.isArray(snap) ? snap : [];
+  for (let ci = 0; ci < links.length; ci++) {
+    const code = (links[ci] as ErrSnapLink).code;
+    if (code === 'ETIMEDOUT' || code === 'ECONNRESET' || code === 'ECONNREFUSED' || code === 'ENOTFOUND' || code === 'EPIPE' || code === 'ECONNABORTED' || code === 'EAI_AGAIN') return 'transport';
+  }
+  for (let ci = 0; ci < links.length; ci++) {
+    if ((links[ci] as ErrSnapLink).name === 'SyntaxError') return 'malformed-output';
+  }
+  let msg = '';
+  for (let ci = 0; ci < links.length; ci++) msg += (ci > 0 ? '\n' : '') + (links[ci] as ErrSnapLink).text;
+  msg = msg.toLowerCase();
+  // rate[ -]?limit(ed|ing|s)? is RIGHT-BOUNDED: the open 'rate.?limit' matched
+  // 'rate limitation: invalid JSON' as transport — a malformed-output failure smuggled a class.
+  if (/\btransport\b|\beconnreset\b|\beconnrefused\b|\benotfound\b|\bepipe\b|\betimedout\b|\bsocket hang up\b|\bnetwork error\b|\brate[ -]?limit(ed|ing|s)?\b|\boverloaded\b|\bhttp 5[0-9][0-9]\b/.test(msg)) return 'transport';
+  if (/\bpolicy\b|\brefus(e|ed|es|al|ing)\b|\bdeclin(e|ed|es|ing)\b|\bcontent filter\b|\bsafety block\b/.test(msg)) return 'policy-refusal';
+  if (/\bmalformed\b|\bunparseable\b|\bparse error\b|\binvalid json\b|\bunexpected token\b|\bunexpected end of json\b|\bschema mismatch\b/.test(msg)) return 'malformed-output';
+  if (/\btimeout\b|\btimed out\b/.test(msg)) return 'timeout';
+  return null;
+}
+
+export type GateVerdict = 'pass' | 'fail' | 'invalid';
+
+/**
+ * Gate verdict parsing — parse-NEVER-synthesize, with the EXACTLY-ONE-ENDING-LINE protocol
+ * enforced: the verdict must be an ANCHORED line ("GATE: PASS" or "GATE: FAIL" alone on its line),
+ * it must be the LAST non-empty line of the reply, and it must be the ONLY anchored verdict line.
+ * Embedded mid-reply "GATE: PASS" text never counts, "GATE: PASS" followed by trailing prose is
+ * invalid, and "GATE: FAIL … GATE: PASS" is an INVALID verdict (never a success) — routed like a
+ * failure (redo / fail route), never a pass.
+ */
+export function gateVerdict(reply: unknown): GateVerdict {
+  if (typeof reply !== 'string') return 'invalid';
+  const vLines = reply.split('\n');
+  const vRe = /^\s*GATE:\s*(PASS|FAIL)\s*$/;
+  let vCount = 0;
+  let vLast = '';
+  for (let i = 0; i < vLines.length; i++) {
+    if (vRe.test(vLines[i] as string)) vCount++;
+    if ((vLines[i] as string).trim() !== '') vLast = vLines[i] as string;
+  }
+  const vEnd = vRe.exec(vLast);
+  if (vCount !== 1 || vEnd === null) return 'invalid';
+  return vEnd[1] === 'PASS' ? 'pass' : 'fail';
+}
+
+export interface JoinOutcome {
+  ok: true;
+  values: unknown[];
+  failures: number[];
+}
+
+/**
+ * The join decision — explicit policy from the closed set; a dispatched branch is never skippable.
+ * `any` fails only when EVERY branch failed; `quorum:<n>` needs n non-failing branches; every other
+ * policy (the `all-*` family) fails on the first failing branch. Throws with a NAMED message, which
+ * the caller settles through its own single terminal exit.
+ */
+export function joinRegion(results: unknown[], o: { policy: string; onInvalid: string; region: string }): JoinOutcome {
+  const policy = o && o.policy ? o.policy : 'all-activated';
+  const failures: number[] = [];
+  for (let i = 0; i < results.length; i++) {
+    if (results[i] === null || results[i] === undefined) failures.push(i);
+  }
+  if (policy === 'any') {
+    if (failures.length === results.length) throw new Error('join ' + o.region + ': every branch failed (policy any)');
+    return { ok: true, values: results, failures: failures };
+  }
+  const quorum = /^quorum:([1-9][0-9]*)$/.exec(policy);
+  if (quorum) {
+    const okN = results.length - failures.length;
+    if (okN < Number(quorum[1])) throw new Error('join ' + o.region + ': quorum ' + quorum[1] + ' not met (' + okN + ' ok)');
+    return { ok: true, values: results, failures: failures };
+  }
+  if (failures.length > 0) throw new Error('join ' + o.region + ': ' + failures.length + ' dispatched branch(es) failed under policy ' + policy + ' — a dispatched branch is never skippable');
+  return { ok: true, values: results, failures: [] };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// NON-BLOB EXPORTS — shared by loop-render.ts and workflow-run.ts, never injected into a script
+// (the rendered script receives the RESULT of these as literal text / a literal number).
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ContractInputs {
+  reads: string[];
+  writes: string[];
+  deliverable: Deliverable;
+  tools: string[];
+  gate: { kind: string } | null;
+}
+
+/**
+ * THE agent-visible contract TEXT lines (ADR-001 Confirmation-5) — byte-for-byte the strings the
+ * render splices after a step's USER prompt, minus the JS quoting. Both enactors assemble a step's
+ * prompt from the SAME function, so a dz-hosted step and a Claude-hosted step communicate the plan's
+ * declarations identically; a value-pinned wiring test compares the rendered USER-region contract
+ * lines against the runner-assembled ones.
+ *
+ * The tools line's second sentence is not decoration — it is the honesty clause the whole feature
+ * rests on: a declaration is not enforcement.
+ */
+export function stepContractLines(c: ContractInputs): string[] {
+  const lines: string[] = [];
+  const reads = c.reads ?? [];
+  const writes = c.writes ?? [];
+  const tools = c.tools ?? [];
+  if (reads.length > 0) lines.push('declared inputs (plan artifacts.reads): ' + reads.join(', '));
+  if (writes.length > 0) {
+    const fileNote = (c.deliverable ?? 'return-value') === 'file' ? '; your deliverable is the written file(s), not your reply' : '';
+    lines.push('declared outputs (plan artifacts.writes): ' + writes.join(', ') + ' — write them' + fileNote + '. The loop verifies they land.');
+  }
+  if (tools.length > 0) {
+    lines.push('declared MCP tool allowlist (plan tools): ' + tools.join(', ') + ' — use NOTHING outside it. In this environment every one of these is a labeled STUB, not a live integration; enforcement lives at the MCP server, not here.');
+  }
+  if (c.gate !== null && c.gate !== undefined) {
+    lines.push('GATE PROTOCOL (kind: ' + (c.gate.kind ?? 'gate') + '): end your reply with exactly one line "GATE: PASS" or "GATE: FAIL" — the loop PARSES this verdict and never synthesizes one.');
+  }
+  return lines;
+}
+
+/**
+ * THE budget ceiling formula (ADR-004 Confirmation-2): declared per-step budgets PLUS the declared
+ * gate-redo allowance — a plan-declared redo must be AFFORDABLE (an undeclared one still hits the
+ * guard loudly). A gate whose failRoute is a `terminal:` route reserves nothing: a terminal route
+ * ends the run, it does not re-run anything.
+ *
+ * This is the number the rendered script carries as `const __budget = { left: N }`; the runner reads
+ * it from HERE, so the two enactors cannot drift into two ceilings.
+ */
+export function computeBudgetTotal(plan: LoopPlan): number {
+  const stepBudget = plan.steps.reduce((n, s) => n + (s.budget?.maxAgents ?? 1), 0);
+  const byId = new Map(plan.steps.map((s) => [s.stepId, s]));
+  const gateRedoBudget = (plan.gates ?? []).reduce((n, g) => {
+    const redos = typeof g.maxRedos === 'number' && Number.isFinite(g.maxRedos) && g.maxRedos > 0 ? Math.floor(g.maxRedos) : 0;
+    if (redos === 0 || typeof g.failRoute !== 'string' || g.failRoute.startsWith('terminal:')) return n;
+    return n + redos * ((byId.get(g.failRoute)?.budget?.maxAgents ?? 1) + (byId.get(g.stepId)?.budget?.maxAgents ?? 1));
+  }, 0);
+  return stepBudget + gateRedoBudget;
+}

package/src/loop-trace.ts

@@ -211,6 +211,19 @@ export function traceFlushCmd(state: TraceState, traceFileAbs: string): string |
   return 'mkdir -p ' + dir + ' && ' + printfs;
 }
 
+/**
+ * Drain the buffered, already-VALIDATED lines — the runner's flush primitive (W17/T0.1). The
+ * fs-less Claude host turns the same buffer into a shell command (`traceFlushCmd`); a host that
+ * HAS fs (the `dz workflow run` scheduler) appends exactly these lines itself. One buffer, two
+ * drains, zero second line-shape: a line this returns has already passed `traceValidateEvent`,
+ * because nothing else can enter the buffer. Empty buffer ⇒ `[]` (never a repeat of the last
+ * batch).
+ */
+export function traceDrain(state: TraceState): string[] {
+  if (state.buffer.length === 0) return [];
+  return state.buffer.splice(0, state.buffer.length);
+}
+
 /**
  * Build the feature-ADR live-panel telemetry leg. Totality comes from the caller's grouped splice:
  * returning the bare command lets that splice preserve the trace flush's exit status while
@@ -303,12 +316,31 @@ export interface TraceRun {
   parseErrors: string[];
 }
 
-/** Parse a trace.jsonl text. Tolerant of a missing run.closed (incomplete: true); a DUPLICATE
- * settle for one invocation is a PARSE ERROR, never a silent merge (INV-15). */
+/**
+ * Parse a trace.jsonl text. Tolerant of a missing run.closed (incomplete: true); a DUPLICATE
+ * settle for one invocation is a PARSE ERROR, never a silent merge (INV-15).
+ *
+ * W17 / AM-12 — `run.events` is CANONICALIZED by ascending `seq` after the line scan. The host's
+ * batched racing flush agents legitimately append out of seq order (MEASURED on the committed
+ * `pkg-audit-1` run: lines 1-2 are settles seq 7 and 6, ahead of `run.opened` seq 1), and the
+ * reader used to inherit that file order — so `invocations()` DROPPED every settle that preceded
+ * its own dispatch in the file, and a complete, successful run read as three FAIL verdicts. seq is
+ * the authoritative order (it is allocated synchronously at the lifecycle transition); file order
+ * is a durability artifact the flush design already blesses, and it stays recoverable only from the
+ * raw text.
+ *
+ * Order of the two bookkeeping passes is load-bearing:
+ *   • LINE-SHAPE errors (unparseable / invalid event) are recorded in FILE order — they describe
+ *     the bytes, and quoting them in file order is what lets a human find the line.
+ *   • The duplicate-dispatch and duplicate-settle checks run AFTER canonicalization, so "which
+ *     settle is the duplicate" is decided by seq, not by which flush batch happened to land first
+ *     (before this, reversing the flush order changed WHICH event INV-15 refused).
+ * The sort is stable, so two events sharing one seq keep their file order relative to each other —
+ * the only ordering the file can still testify to. INV-14 fails such a trace on uniqueness anyway.
+ */
 export function parseTrace(text: string): TraceRun {
   const run: TraceRun = { runId: null, planDigest: null, execFp: null, events: [], incomplete: true, parseErrors: [] };
-  const settledSeen = new Set<string>();
-  const dispatchSeen = new Set<string>();
+  const scanned: TraceEvent[] = [];
   for (const line of String(text ?? '').split('\n')) {
     const t = line.trim();
     if (t === '') continue;
@@ -324,7 +356,13 @@ export function parseTrace(text: string): TraceRun {
       run.parseErrors.push('invalid event (' + err + '): ' + t.slice(0, 120));
       continue;
     }
-    const ev = e as TraceEvent;
+    scanned.push(e as TraceEvent);
+  }
+  // CANONICALIZATION (the W17 fix): ascending seq, stable.
+  scanned.sort((a, b) => a.seq - b.seq);
+  const settledSeen = new Set<string>();
+  const dispatchSeen = new Set<string>();
+  for (const ev of scanned) {
     if (ev.event === 'run.opened') {
       run.runId = ev.runId;
       run.planDigest = ev.planDigest;
@@ -395,13 +433,49 @@ export function runInvariants(projection: TraceProjection, run: TraceRun): Invar
   const out: InvariantVerdict[] = [];
   const invs = invocations(run);
 
-  // INV-14: seq unique + strictly increasing in event order.
+  // INV-14 (RESTATED, W17/AM-12 — verdict id UNCHANGED: `seq-monotonic` is the consumer contract,
+  // keyed on by the fitness suite and every `dz workflow-trace` reader, so only the SEMANTICS and
+  // the message restate). `parseTrace` now canonicalizes by seq, so "strictly increasing in event
+  // order" became tautological — it tested the reader's own sort. The property that still has
+  // teeth is the SINGLE-ALLOCATOR witness:
+  //   • seq values are UNIQUE (two writers, or one writer allocating twice, collide) — always;
+  //   • on a COMPLETE trace they are exactly contiguous 1..maxSeq (a closed run that skips a
+  //     number lost an event or had a second allocator);
+  //   • on an INCOMPLETE trace a gap is INCONCLUSIVE, never a pass — the window is truncated, so
+  //     a missing number is indistinguishable from an unflushed one.
+  // Residue accepted and named in AM-12: a writer allocating unique + contiguous seq in a
+  // non-monotonic ORDER is no longer detectable. Allocation order was only ever observable through
+  // the racy append that this fix (correctly) stopped trusting.
   {
     const seqs = run.events.map((e) => e.seq);
-    const dup = seqs.some((s, i) => seqs.indexOf(s) !== i);
-    const decreasing = seqs.some((s, i) => i > 0 && s <= (seqs[i - 1] as number));
-    if (dup || decreasing) out.push({ id: 'seq-monotonic', status: 'fail', message: 'seq is not unique/strictly-increasing — the single serialized writer property is broken' });
-    else out.push({ id: 'seq-monotonic', status: 'pass', message: 'seq unique and strictly increasing (' + seqs.length + ' events)' });
+    const dupes = [...new Set(seqs.filter((s, i) => seqs.indexOf(s) !== i))].sort((a, b) => a - b);
+    if (dupes.length > 0) {
+      out.push({
+        id: 'seq-monotonic',
+        status: 'fail',
+        message: 'duplicate seq value(s) ' + dupes.join(', ') + ' — the single-ALLOCATOR property is broken (seq must be unique across the whole run)',
+      });
+    } else {
+      const maxSeq = seqs.length === 0 ? 0 : Math.max(...seqs);
+      const missing: number[] = [];
+      const present = new Set(seqs);
+      for (let s = 1; s <= maxSeq && missing.length < 8; s++) if (!present.has(s)) missing.push(s);
+      if (missing.length === 0) {
+        out.push({ id: 'seq-monotonic', status: 'pass', message: 'seq unique and contiguous 1..' + maxSeq + ' (' + seqs.length + ' events)' });
+      } else if (run.incomplete) {
+        out.push({
+          id: 'seq-monotonic',
+          status: 'inconclusive',
+          message: 'seq unique but NOT contiguous (missing ' + missing.join(', ') + ' of 1..' + maxSeq + ') on an INCOMPLETE trace — a truncated window is indistinguishable from a lost event',
+        });
+      } else {
+        out.push({
+          id: 'seq-monotonic',
+          status: 'fail',
+          message: 'seq is not contiguous 1..' + maxSeq + ' on a COMPLETE trace — missing ' + missing.join(', ') + ' (a closed run that skips a number lost an event or had a second allocator)',
+        });
+      }
+    }
   }
 
   // INV-15: pairing (a dangling dispatch is only conclusive on a complete trace).

package/src/managed-hooks.ts

@@ -65,6 +65,16 @@ export interface MergeManagedHookOptions {
   readonly looksLikeOurs?: (entry: ManagedHookEntry, event: string) => boolean;
   /** True ⇒ this OURS entry was in a legacy shape/vintage (Claude path only). */
   readonly isLegacy?: (entry: ManagedHookEntry, event: string) => boolean;
+  /**
+   * Per-HANDLER salvage for an entry `isManaged` claimed. Given an OWNED entry, return it rebuilt
+   * from only the handlers that are NOT ours, or `null` when every handler was ours.
+   *
+   * Optional, and absent means the historical whole-entry behaviour — the Claude path passes
+   * nothing and is byte-identical to before (AM-3). The Codex path passes it because attribution at
+   * matcher-group granularity deleted a foreign handler that merely shared a group with dz's
+   * (independent review, finding 6).
+   */
+  readonly retainForeign?: (entry: ManagedHookEntry, event: string) => ManagedHookEntry | null;
   /** e.g. `'agentdb'` → `merged agentdb hooks (user hooks preserved)`. */
   readonly reportLabel?: string;
   /** Report text when nothing changed. */
@@ -98,7 +108,12 @@ export function mergeManagedHookEntries(
   for (const [event, entries] of Object.entries(source)) {
     if (!Array.isArray(entries)) continue;
     for (const entry of entries) {
-      if (options.isManaged(entry, event)) continue;
+      if (options.isManaged(entry, event)) {
+        // A mixed group counts as a preserved foreign entry when something of the user's survives
+        // in it — the census must not report zero for a handler the merge actually keeps.
+        if (options.retainForeign?.(entry, event) != null) foreignPreserved += 1;
+        continue;
+      }
       foreignPreserved += 1;
       if (options.looksLikeOurs?.(entry, event) === true) unattributable += 1;
     }
@@ -108,11 +123,17 @@ export function mergeManagedHookEntries(
   let replacedLegacy = false;
   for (const event of Object.keys(managed)) {
     const current = Array.isArray(hooks[event]) ? (hooks[event] as ManagedHookEntry[]) : [];
-    const kept = current.filter((entry) => {
+    const kept: ManagedHookEntry[] = [];
+    for (const entry of current) {
       const ours = options.isManaged(entry, event);
-      if (ours && options.isLegacy?.(entry, event) === true) replacedLegacy = true;
-      return !ours;
-    });
+      if (!ours) {
+        kept.push(entry);
+        continue;
+      }
+      if (options.isLegacy?.(entry, event) === true) replacedLegacy = true;
+      const salvaged = options.retainForeign?.(entry, event) ?? null;
+      if (salvaged !== null) kept.push(salvaged);
+    }
     const next = [...kept, ...(managed[event] ?? [])];
     if (JSON.stringify(next) !== JSON.stringify(current)) changed = true;
     hooks[event] = next;