@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/_lib/turn_end_refusals.ts

@@ -7,14 +7,24 @@
  * none, and a gate that blocks unobserved is the shape that discipline exists to
  * prevent.
  *
- * This module is the reader. It owns three things and deliberately not a fourth:
+ * This module is the reader. It owns five things and deliberately not a sixth:
  *
  *   1. the on-disk record shape, extended so a session's refusals are COUNTED
  *      rather than overwritten (§ Phase 1 step 1.1);
  *   2. a TTL prune, which the gate's own header admits is missing (step 1.2);
  *   3. the split by recorded package version, so claim 10's prediction — that
  *      refusals correlate with the local 12.1 install — is TESTED rather than
- *      assumed (step 1.3).
+ *      assumed (step 1.3);
+ *   4. the SHADOW record — what a retry would have been refused for, written on
+ *      an allow path (`road-to-a-stop-that-holds` step 2.1);
+ *   5. the rollup over those records (step 2.2). Read `ShadowLayerStats` before
+ *      quoting anything it produces: the share it computes is NOT the Q1 the
+ *      demotion contract registers bars against, and the difference is named
+ *      there rather than left to a reader of the number.
+ *
+ * (This list read "three things and deliberately not a fourth" until 2026-10-01.
+ * It was accurate when written and silently false for the two steps after it —
+ * an independent review caught it. Items 4 and 5 are the two that landed.)
  *
  * The fourth thing it does not own is a **rate over all sessions**, and the
  * reason is structural rather than an omission. A record is written only when a
@@ -335,6 +345,243 @@ export function readInstallBoundary(): InstallBoundary {
     }
 }
 
+// ---------------------------------------------------------------------------
+// The shadow read — road-to-a-stop-that-holds step 2.1
+// ---------------------------------------------------------------------------
+
+/**
+ * One observation of "this retry would still have been refused".
+ *
+ * `turn-end-detector-demotion.md` § Q1 asks what share of the turns the gate
+ * allows on a re-entrancy layer would have been refused again. Both layers
+ * return `EXIT_ALLOW` unconditionally, so that share is not derivable from the
+ * refusal record: a retry leaves no trace at all, and a detector that fired
+ * twice is indistinguishable from one that was satisfied on the second pass.
+ * This row is that trace.
+ *
+ * `layer` is which allow path produced it, because the two are not the same
+ * measurement. `stop_hook_active` is the HOST's answer and is set on any stop
+ * hook's block, including another concern's; `refused_turn` is this gate's own
+ * marker and therefore always follows a refusal by this gate. Pooling them
+ * would let another concern's retries inflate Q1's numerator against a
+ * denominator that only counts this gate's refusals.
+ */
+export interface WouldRefuseAgainRow {
+    detector: RefusalDetectorId;
+    /** The turn ordinal the shadow ran on — joins to `refused_turn`. */
+    turn: number;
+    at: string;
+    layer: ShadowLayer;
+}
+
+/**
+ * The two allow paths a shadow read can run on, in the order `main()` reaches
+ * them.
+ *
+ * A LIST rather than a bare union, and the counter below is derived from it,
+ * for the reason `emptyCounts` gives one screen up: a hand-written counter
+ * object satisfied `Record<Union, number>` on the day it was typed and read
+ * back `undefined` the moment a member was added, so every `+=` over it
+ * produced `NaN` and the whole rollup went quiet. Adding a third layer here
+ * cannot repeat that.
+ */
+export const SHADOW_LAYERS = ['stop_hook_active', 'refused_turn'] as const;
+
+export type ShadowLayer = (typeof SHADOW_LAYERS)[number];
+
+/** A zeroed retry counter per layer, DERIVED from `SHADOW_LAYERS`. */
+export function emptyRetryCounts(): Record<ShadowLayer, number> {
+    const out = {} as Record<ShadowLayer, number>;
+    for (const l of SHADOW_LAYERS) out[l] = 0;
+    return out;
+}
+
+/**
+ * Per-session shadow state, in its own file beside the refusal record.
+ *
+ * SEPARATE FILE, deliberately, and this is the one design decision in the step
+ * worth defending. The plan says "into the session state" and the refusal
+ * record is the obvious place — but `refused_turn` in that record is the
+ * re-entrancy wedge guard, `parseRecord` rejects any record lacking it, and a
+ * Layer-1 retry can occur with no refusal by this gate at all (another stop
+ * concern blocked). Writing a shadow row there would mean either synthesising
+ * a `refused_turn` this gate never wrote — corrupting the one field a wedge
+ * depends on — or loosening the parser that protects it. A sibling file costs
+ * one more path and touches neither.
+ *
+ * It lives in this module rather than in the gate for the reason the header
+ * already gives about the pruner: a directory with two writers each holding
+ * their own idea of where the files are is how a reader and a writer end up
+ * disagreeing.
+ *
+ * Two limits bound what a reading of this record may claim.
+ *
+ * **It counts retries with a READABLE TRANSCRIPT, not all retries.** A retry
+ * whose transcript is absent, over `TRANSCRIPT_READ_MAX_BYTES`, or carries no
+ * assistant text records nothing at all — the gate's input assembly returns
+ * null and there is no detector verdict to shadow. The numerator is unaffected
+ * and the denominator shrinks, so the bias is UPWARD: a Q1 read off this
+ * record is an upper bound, never a point estimate.
+ *
+ * **On a host that sends no `session_id` it pools across sessions.** The key
+ * is `deriveSessionKey(rawSessionId || 'unknown-session')`, so every such
+ * session shares one file and one counter. The gate documents the same
+ * collision for the re-entrancy marker and argues it degrades safely, toward
+ * under-refusing. That argument does NOT transfer here: a merged measurement
+ * does not under-report, it reports one number for several sessions and a
+ * reader takes it for one. Named rather than inherited, because the two
+ * failures are opposite in kind.
+ */
+export interface ShadowRecord {
+    /** Newest last. Bounded by `SHADOW_MAX_ROWS`. */
+    would_refuse_again: WouldRefuseAgainRow[];
+    /**
+     * Retries observed on an allow path in this session, refusing or NOT,
+     * SPLIT BY LAYER.
+     *
+     * Kept because a shadow row array alone cannot distinguish "no retry
+     * happened" from "every retry came back clean", and those are opposite
+     * readings of the same empty list.
+     *
+     * Split because pooling it made a per-layer Q1 uncomputable, which the
+     * first version shipped and an independent review caught before any row
+     * accumulated. `layer` is on every ROW for a stated reason — a
+     * `stop_hook_active` retry follows ANY stop concern's block, not only this
+     * gate's — so a pooled numerator would read another concern's retries
+     * against this gate's refusals. A pooled DENOMINATOR has the same defect
+     * one level down, and worse: a CLEAN retry adds no row at all, so it left
+     * no layer trace anywhere. The numerator could be split and the
+     * denominator could not, which is not a sanity check on anything.
+     *
+     * Keyed rather than two fields so a third layer, if one is ever added,
+     * cannot silently land in neither bucket.
+     */
+    retries_observed: Record<ShadowLayer, number>;
+    /** Rows dropped to the cap. A non-zero value makes the array a sample. */
+    dropped: number;
+    first_at: string;
+    last_at: string;
+}
+
+/**
+ * Row cap per session.
+ *
+ * A stated bound, not a measured optimum. A row is ~90 bytes and a session
+ * with 200 retries is already pathological, so the cap exists to keep an
+ * unbounded write off the Stop path rather than to fit a distribution. Oldest
+ * rows are dropped first: Q1 is a rate, and the most recent observations are
+ * the ones a reader is deciding on. A non-zero `dropped` on a real session is
+ * the signal that the number was chosen too low.
+ */
+export const SHADOW_MAX_ROWS = 200;
+
+/**
+ * The shadow file's suffix, named rather than inlined because TWO readers need
+ * to agree on it: the writer below and `pruneAgedRefusalState`, which scans the
+ * same directory for `*.json` and would otherwise keep every shadow record
+ * forever.
+ */
+export const SHADOW_SUFFIX = '.shadow.json';
+
+export function sessionShadowFile(workspaceRoot: string, sessionKey: string): string {
+    return path.join(refusalStateDir(workspaceRoot), `${sessionKey}${SHADOW_SUFFIX}`);
+}
+
+/**
+ * Parse one shadow record. `null` for anything unreadable — same fail-open
+ * contract as `parseRecord`, and for the same reason: this is the Stop path.
+ */
+export function parseShadowRecord(raw: string): ShadowRecord | null {
+    let decoded: unknown;
+    try {
+        decoded = JSON.parse(raw);
+    } catch {
+        return null;
+    }
+    if (typeof decoded !== 'object' || decoded === null || Array.isArray(decoded)) return null;
+    const o = decoded as Record<string, unknown>;
+    const rowsRaw = o['would_refuse_again'];
+    if (!Array.isArray(rowsRaw)) return null;
+    const rows: WouldRefuseAgainRow[] = [];
+    for (const r of rowsRaw) {
+        if (typeof r !== 'object' || r === null || Array.isArray(r)) continue;
+        const ro = r as Record<string, unknown>;
+        const det = ro['detector'];
+        const turn = ro['turn'];
+        const at = ro['at'];
+        const layer = ro['layer'];
+        if (!isDetector(det)) continue;
+        if (typeof turn !== 'number' || !Number.isFinite(turn)) continue;
+        if (typeof at !== 'string') continue;
+        if (layer !== 'stop_hook_active' && layer !== 'refused_turn') continue;
+        rows.push({ detector: det, turn, at, layer });
+    }
+    const num = (v: unknown): number =>
+        typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0;
+    const observed = o['retries_observed'];
+    const byLayer = emptyRetryCounts();
+    if (typeof observed === 'object' && observed !== null && !Array.isArray(observed)) {
+        for (const l of SHADOW_LAYERS) {
+            byLayer[l] = num((observed as Record<string, unknown>)[l]);
+        }
+    }
+    return {
+        would_refuse_again: rows,
+        retries_observed: byLayer,
+        dropped: num(o['dropped']),
+        first_at: typeof o['first_at'] === 'string' ? o['first_at'] : '',
+        last_at: typeof o['last_at'] === 'string' ? o['last_at'] : '',
+    };
+}
+
+/**
+ * Fold one retry observation into a shadow record. Pure — the caller writes.
+ *
+ * `detectors` EMPTY is a real and load-bearing input: a retry whose detectors
+ * all came back silent raises `retries_observed` for its layer and adds no
+ * row, which is the only way Q1 can ever read below 1.
+ */
+export function foldShadow(
+    prev: ShadowRecord | null,
+    input: {
+        detectors: readonly RefusalDetectorId[];
+        turnOrdinal: number;
+        at: string;
+        layer: ShadowLayer;
+    },
+): ShadowRecord {
+    const rows = [...(prev?.would_refuse_again ?? [])];
+    for (const d of input.detectors) {
+        rows.push({ detector: d, turn: input.turnOrdinal, at: input.at, layer: input.layer });
+    }
+    let dropped = prev?.dropped ?? 0;
+    if (rows.length > SHADOW_MAX_ROWS) {
+        dropped += rows.length - SHADOW_MAX_ROWS;
+        rows.splice(0, rows.length - SHADOW_MAX_ROWS);
+    }
+    const retries = emptyRetryCounts();
+    for (const l of SHADOW_LAYERS) retries[l] = prev?.retries_observed[l] ?? 0;
+    retries[input.layer] += 1;
+    return {
+        would_refuse_again: rows,
+        retries_observed: retries,
+        dropped,
+        first_at: prev?.first_at !== undefined && prev.first_at !== '' ? prev.first_at : input.at,
+        last_at: input.at,
+    };
+}
+
+/** This session's shadow record, or `null` when it has never retried. */
+export function readShadowRecord(workspaceRoot: string, sessionKey: string): ShadowRecord | null {
+    try {
+        return parseShadowRecord(
+            fs.readFileSync(sessionShadowFile(workspaceRoot, sessionKey), 'utf-8'),
+        );
+    } catch {
+        return null;
+    }
+}
+
 // ---------------------------------------------------------------------------
 // TTL — step 1.2
 // ---------------------------------------------------------------------------
@@ -350,8 +597,9 @@ export function readInstallBoundary(): InstallBoundary {
  * LIVENESS and this bounds EVIDENCE — pruning evidence on a liveness clock would
  * delete the corpus this roadmap exists to read.
  *
- * *Revisit-if:* a rollup window longer than 90 days is needed to read a rate, or
- * the directory's file count becomes a measured cost rather than a projected one.
+ * Two things would show 90 is the wrong number: a rollup window longer than it
+ * being needed to read a rate, or the directory's file count becoming a
+ * measured cost rather than a projected one.
  */
 export const REFUSAL_STATE_MAX_AGE_DAYS = 90;
 
@@ -389,6 +637,53 @@ export function pruneAgedRefusalState(
         if (!name.endsWith('.json')) continue;
         result.scanned += 1;
         const file = path.join(dir, name);
+        // A shadow record is a sibling in the same directory whose name also
+        // ends `.json`, and `parseRecord` rejects it for lacking `refused_at`.
+        // Left to the branch below it would land in `kept` FOREVER — the
+        // unbounded growth this pruner exists to stop, reintroduced by the
+        // instrument step 2.1 added. Its own clock is `last_at`.
+        if (name.endsWith(SHADOW_SUFFIX)) {
+            let shadow: ShadowRecord | null = null;
+            try {
+                shadow = parseShadowRecord(fs.readFileSync(file, 'utf-8'));
+            } catch {
+                shadow = null;
+            }
+            const shadowAt = shadow === null ? NaN : Date.parse(shadow.last_at);
+            // KEEP-ON-UNPARSEABLE IS NOT INHERITED, and the asymmetry with the
+            // branch below is the point. A refusal record that will not parse
+            // may still carry the wedge marker, so deleting it is the one
+            // irreversible move available and it is refused. A shadow record
+            // is pure measurement with nothing to protect — keeping one whose
+            // `last_at` cannot be read means it never ages out at all, which
+            // is the unbounded growth this pruner exists to stop, surviving
+            // for exactly the subset nobody can read. An unreadable one is
+            // pruned on the filesystem mtime, which is the weaker clock this
+            // function refuses for refusal records precisely because they are
+            // evidence; for a corrupt measurement it is the only clock left.
+            if (!Number.isFinite(shadowAt)) {
+                let mtime = NaN;
+                try {
+                    mtime = fs.statSync(file).mtimeMs;
+                } catch {
+                    mtime = NaN;
+                }
+                if (!Number.isFinite(mtime) || mtime >= cutoffMs) {
+                    result.kept += 1;
+                    continue;
+                }
+            } else if (shadowAt >= cutoffMs) {
+                result.kept += 1;
+                continue;
+            }
+            try {
+                fs.unlinkSync(file);
+                result.pruned += 1;
+            } catch {
+                result.kept += 1;
+            }
+            continue;
+        }
         let rec: RefusalRecord | null = null;
         try {
             rec = parseRecord(fs.readFileSync(file, 'utf-8'));
@@ -492,6 +787,12 @@ export function collectRefusalStats(workspaceRoot: string): RefusalStats {
     const versions = new Map<string, VersionBucket>();
     for (const name of entries) {
         if (!name.endsWith('.json')) continue;
+        // Shadow records share the directory and the extension. `parseRecord`
+        // would reject each one anyway, so this line changes no number — it is
+        // here because relying on another function's strictness for a
+        // correctness property is how the property disappears when that
+        // function is loosened.
+        if (name.endsWith(SHADOW_SUFFIX)) continue;
         let rec: RefusalRecord | null = null;
         try {
             rec = parseRecord(fs.readFileSync(path.join(dir, name), 'utf-8'));
@@ -535,3 +836,223 @@ export function collectRefusalStats(workspaceRoot: string): RefusalStats {
     stats.byVersion = [...versions.values()].sort((a, b) => (a.version < b.version ? 1 : -1));
     return stats;
 }
+
+// ---------------------------------------------------------------------------
+// Q1 — the shadow rollup (step 2.2)
+// ---------------------------------------------------------------------------
+
+/**
+ * One layer's Q1 inputs, kept as counts so the ratio is computed where it is
+ * read rather than stored.
+ *
+ * SPLIT BY LAYER BEFORE DETECTOR, and that order is the shape's whole point
+ * rather than a presentation choice. A `stop_hook_active` retry follows ANY
+ * stop concern's block — not only this gate's — so pooling the two layers
+ * divides another concern's retries into this gate's refusals and calls the
+ * result a re-refusal share. `ShadowRecord.retries_observed` is keyed the same
+ * way so the denominator splits with the numerator; an independent review
+ * found the first version pooling the denominator, which left the per-layer
+ * ratio uncomputable even though every row already carried its `layer`.
+ */
+export interface ShadowLayerStats {
+    layer: ShadowLayer;
+    /**
+     * Retries observed on this layer across every readable record — the
+     * denominator, counting retries that came back CLEAN as well as refusing
+     * ones. A clean retry writes no row, so without this a zero numerator and
+     * "no retry happened" are the same empty list.
+     */
+    retries: number;
+    /** Shadow rows on this layer, by detector — the numerators. */
+    byDetector: DetectorCounts;
+    /**
+     * Rows on this layer, summed.
+     *
+     * MAY EXCEED `retries`, legitimately: one retry that would have been
+     * refused by two detectors writes two rows, and the demotion contract's
+     * attribution rule counts it once for each. A per-detector ratio stays
+     * within [0, 1]; this total is not a share and is printed as a count.
+     */
+    rows: number;
+}
+
+/**
+ * Rollup over every session's shadow record under a workspace.
+ *
+ * Two bounds travel with every number this carries. Both are properties of the
+ * instrument rather than of a particular reading, both are stated on
+ * `ShadowRecord`, and both are repeated here because a consumer reads this
+ * type and not that comment:
+ *
+ *   - A retry whose transcript is unreadable or oversized records NOTHING —
+ *     no row and no retry. The denominator shrinks with the numerator, so a
+ *     Q1 read off this is an UPPER bound rather than a point estimate.
+ *   - On a host that sends no `session_id`, every session shares one record
+ *     and one counter. `files` below then counts FILES and not sessions, and
+ *     a reader taking one for the other over-states the sample.
+ */
+export interface ShadowStats {
+    /**
+     * Shadow FILES parsed. Deliberately not named `sessions`: one file is one
+     * session only on a host that sends a `session_id`.
+     */
+    files: number;
+    /** Files present but unparseable. A non-zero value makes every rate a floor. */
+    unreadable: number;
+    /**
+     * Rows dropped to `SHADOW_MAX_ROWS`, summed. Non-zero means the row arrays
+     * are samples of their own sessions and every numerator is a floor.
+     */
+    dropped: number;
+    byLayer: ShadowLayerStats[];
+    earliest: string | null;
+    latest: string | null;
+}
+
+/** A zeroed rollup, DERIVED from `SHADOW_LAYERS` for the reason `emptyCounts` gives. */
+export function emptyShadowStats(): ShadowStats {
+    return {
+        files: 0,
+        unreadable: 0,
+        dropped: 0,
+        byLayer: SHADOW_LAYERS.map((layer) => ({
+            layer,
+            retries: 0,
+            byDetector: emptyCounts(),
+            rows: 0,
+        })),
+        earliest: null,
+        latest: null,
+    };
+}
+
+/**
+ * Aggregate every shadow record under a workspace.
+ *
+ * Reads through `parseShadowRecord`, never by hand: the gate writes these
+ * files, and a reader carrying its own idea of their shape is how a producer
+ * and a consumer drift apart — the exact seam the 2026-09-30 review round
+ * found uncrossed between the verification recorder and its classifier.
+ */
+export function collectShadowStats(workspaceRoot: string): ShadowStats {
+    const dir = refusalStateDir(workspaceRoot);
+    const stats = emptyShadowStats();
+    const byLayer = new Map(stats.byLayer.map((b) => [b.layer, b]));
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return stats;
+    }
+    for (const name of entries) {
+        if (!name.endsWith(SHADOW_SUFFIX)) continue;
+        let rec: ShadowRecord | null = null;
+        try {
+            rec = parseShadowRecord(fs.readFileSync(path.join(dir, name), 'utf-8'));
+        } catch {
+            rec = null;
+        }
+        if (rec === null) {
+            stats.unreadable += 1;
+            continue;
+        }
+        stats.files += 1;
+        stats.dropped += rec.dropped;
+        for (const layer of SHADOW_LAYERS) {
+            const bucket = byLayer.get(layer);
+            if (bucket !== undefined) bucket.retries += rec.retries_observed[layer] ?? 0;
+        }
+        for (const row of rec.would_refuse_again) {
+            const bucket = byLayer.get(row.layer);
+            if (bucket === undefined) continue;
+            bucket.byDetector[row.detector] += 1;
+            bucket.rows += 1;
+        }
+        // EMPTY STRINGS ARE SKIPPED, NOT COMPARED. `parseShadowRecord` coerces a
+        // missing `first_at` to `''`, and `'' < <any ISO stamp>` is true, so a
+        // record lacking the field would win the earliest comparison and the
+        // report would print an empty window start beside a real end. An absent
+        // timestamp is not an earlier one.
+        if (rec.first_at !== '' && (stats.earliest === null || rec.first_at < stats.earliest)) {
+            stats.earliest = rec.first_at;
+        }
+        if (rec.last_at !== '' && (stats.latest === null || rec.last_at > stats.latest)) {
+            stats.latest = rec.last_at;
+        }
+    }
+    return stats;
+}
+
+/**
+ * Detectors whose share may NOT be reported off a shadow rollup, because the
+ * record cannot tell a dispatch-suppressed retry from a clean one.
+ *
+ * `runDetectors` in `turn_end_gate_hook.ts` skips A, D and F when a subagent
+ * dispatch is open — they did not run, so the turn is not an observation of
+ * them staying silent. `recordShadow` then increments `retries_observed`
+ * unconditionally and writes no dispatch flag, so every dispatch-suppressed
+ * retry lands in those three denominators as a "would not have refused" that
+ * nobody observed. In a suite whose delegation policy dispatches by default
+ * that is not a rare branch.
+ *
+ * The demotion contract already forbids publishing it: *"A rollup that cannot
+ * tell a dispatch-suppressed turn from a clean one may not report Q2 for A or
+ * D at all."* This set is that clause applied to the shadow rollup, extended to
+ * F — the contract's attribution paragraph names only A and D because it
+ * predates F, while its own § The six detectors table and the gate both gate
+ * all three. The wider set is the safe reading of a censoring rule.
+ *
+ * Closing this needs a `dispatch_open` flag on the shadow row, which is a
+ * PRODUCER change. Until then these three are censored rather than estimated.
+ */
+export const DISPATCH_CENSORED_DETECTORS: ReadonlySet<RefusalDetectorId> =
+    new Set<RefusalDetectorId>(['promissory', 'completion', 'untested']);
+
+/**
+ * The **retry-conditioned re-refusal share** for one detector on one layer, or
+ * `null` when the layer observed no retry.
+ *
+ * ```
+ * THIS IS NOT THE Q1 `turn-end-detector-demotion.md` REGISTERS BARS AGAINST.
+ * NEVER COMPARE IT TO A BAR IN THAT TABLE.
+ * ```
+ *
+ * The contract defines Q1 as *"of **a detector's** eligible initial refusals,
+ * the share whose immediate retry is refused again by the same detector"*. Both
+ * halves of that are conditioned on the detector. This function conditions
+ * NEITHER: the denominator is every retry observed on the layer, whatever
+ * refusal produced it, and the numerator is every row where this detector would
+ * have fired, whatever refusal produced the retry.
+ *
+ * **They disagree in direction, so this is not a bound either.** Take ten
+ * retries on a layer, nine following `verification` refusals and one following
+ * a `language` refusal, with one `language` row. The contract's Q1 for B is
+ * 1/1 = 100 % — bar crossed, a demotion study authorised. This function returns
+ * 1/10 = 10 % — bar not crossed. Opposite verdicts on identical evidence. The
+ * numerator can also run the other way, since a `language` row on a retry that
+ * followed a `verification` refusal counts here and does not count there.
+ *
+ * **Why it is shaped this way, which is a producer limit rather than a choice.**
+ * `ShadowRecord` carries no originating detector: `retries_observed` is keyed by
+ * layer alone and a row records only what WOULD fire, never what did. The
+ * session's `RefusalRecord` holds per-detector COUNTS for the whole session and
+ * `refused_turn` for the last refused turn, so the per-turn origin needed to
+ * condition this denominator is not on disk anywhere. Computing the registered
+ * Q1 needs the producer to record it; that is named as the open residue on
+ * `road-to-a-stop-that-holds` step 2.2 rather than papered over here.
+ *
+ * `null` RATHER THAN ZERO on an empty denominator, and that distinction is why
+ * `retries_observed` exists at all: zero means "retries happened and this
+ * detector would not have refused any of them", a finding about the detector,
+ * while null means "nothing was observed", a finding about the sample.
+ * Collapsing them publishes the second as the first.
+ */
+export function retryConditionedShare(
+    stats: ShadowStats,
+    layer: ShadowLayer,
+    detector: RefusalDetectorId,
+): number | null {
+    const bucket = stats.byLayer.find((b) => b.layer === layer);
+    if (bucket === undefined || bucket.retries === 0) return null;
+    return bucket.byDetector[detector] / bucket.retries;
+}