@event4u/agent-config 16.0.0 → 16.2.0

package/src/scripts/_lib/authority_path.ts

@@ -0,0 +1,102 @@
+/**
+ * The strictest path, reserved for authority —
+ * `road-to-adversarial-verification-and-long-runs` 11.1.
+ *
+ * An authority-expanding change takes four independent passes — an independent
+ * TEST author, an independent GOVERNANCE reviewer, a COUNCIL pass, and a
+ * PROVIDER-DIVERSE reviewer — plus the ratification artefact. Until the artefact
+ * carries `verdict: ratified`, the new authority is **inert**.
+ *
+ * ```
+ * NEW AUTHORITY IS INERT UNTIL RATIFIED. AN AGENT MAY AUTHOR THE CHANGE
+ * AND MAY NEVER RATIFY ITS OWN INCREASE IN POWER (ADR-268 § 4).
+ * FOUR PASSES, ALL FOUR, AND THEY MAY NOT BE THE SAME REVIEWER TWICE.
+ * ```
+ *
+ * **Inert-until-ratified is the property that makes the rest safe.** Without it
+ * the four passes are a process an author could complete and then merge; with it
+ * the change can land, be read, and still do nothing — so the ratification is a
+ * separate act on a separate turn by a party that is not the author.
+ *
+ * Pure.
+ */
+
+/** The four passes. All four, and the list is closed. */
+export const REQUIRED_PASSES = [
+    'independent-test-author',
+    'independent-governance-reviewer',
+    'council',
+    'provider-diverse-reviewer',
+] as const;
+export type Pass = (typeof REQUIRED_PASSES)[number];
+
+export interface PassRecord {
+    readonly pass: Pass;
+    /** Who performed it. Two passes by the same identity is not two passes. */
+    readonly by: string;
+    /** The provider, so provider-diversity is checkable rather than asserted. */
+    readonly provider: string;
+}
+
+export interface RatificationArtefact {
+    /** Anything other than `ratified` leaves the authority inert. */
+    readonly verdict: string;
+    readonly passes: readonly PassRecord[];
+    /** The author of the change under ratification. */
+    readonly author: string;
+}
+
+export type AuthorityState = 'inert' | 'active';
+
+export interface AuthorityVerdict {
+    readonly state: AuthorityState;
+    readonly blockers: readonly string[];
+}
+
+/**
+ * Is the new authority active yet?
+ *
+ * Returns EVERY blocker rather than the first: the artefact is a checklist a
+ * human completes, and handing them one item at a time turns four passes into
+ * four round trips.
+ */
+export function authorityState(a: RatificationArtefact | null): AuthorityVerdict {
+    if (a === null) {
+        return { state: 'inert', blockers: ['no ratification artefact exists'] };
+    }
+    const blockers: string[] = [];
+
+    for (const required of REQUIRED_PASSES) {
+        if (!a.passes.some((p) => p.pass === required)) {
+            blockers.push(`missing pass: ${required}`);
+        }
+    }
+
+    // The author may perform NONE of the four. This is the ADR-268 § 4 clause
+    // and the one a process can satisfy on paper while violating in substance.
+    for (const p of a.passes) {
+        if (p.by === a.author) {
+            blockers.push(`${p.pass} was performed by the author (${p.by}) — an agent may not ratify its own increase in power`);
+        }
+    }
+
+    // Provider diversity is a property of the SET, so it is checked over the set
+    // rather than trusted from the pass that carries the name.
+    const providers = new Set(a.passes.map((p) => p.provider));
+    if (a.passes.length > 1 && providers.size < 2) {
+        blockers.push(
+            `every pass ran on one provider (${[...providers].join(', ')}) — provider-diverse means at least two`,
+        );
+    }
+
+    if (a.verdict !== 'ratified') {
+        blockers.push(`verdict is "${a.verdict}", not "ratified"`);
+    }
+
+    return { state: blockers.length === 0 ? 'active' : 'inert', blockers };
+}
+
+/** `true` only for an artefact that clears everything. */
+export function isRatified(a: RatificationArtefact | null): boolean {
+    return authorityState(a).state === 'active';
+}

package/src/scripts/_lib/body_portable.ts

@@ -0,0 +1,102 @@
+/**
+ * `body-portable` — does a skill's declared frontmatter survive the MCP-lite
+ * carrier whole?
+ *
+ * road-to-semantic-parity-before-off-menu, Phase 2.1.
+ *
+ * WHAT THIS DECIDES, AND WHAT IT DOES NOT
+ *
+ * It decides ELIGIBILITY only. It marks nothing, excludes nothing, and is not a
+ * verdict about which skills matter. A committed list of skills this returns
+ * false for is one step from a menu-exclusion discharged by citing it, which is
+ * precisely the laundering the parked menu-economy roadmap's Risk 1 names — a
+ * measurement of carrier coverage reused as a judgement about worth. Nothing in
+ * the tree consumes this as an exclusion trigger, and building the half that
+ * could is a separate decision that has not been taken.
+ *
+ * THE RULE
+ *
+ * A skill is body-portable when every key it declares is one the carrier
+ * transports whole. Three ways to fail, and they are deliberately not
+ * distinguished in the boolean:
+ *
+ *   - a DROPPED key — the carrier never reads it, so the semantic stays on disk.
+ *   - a PARTIAL key — the carrier reads it and transports part of the value.
+ *     `triggers` is the only one: `keyword` and `phrase` travel, while
+ *     `file_pattern`, `path_prefix`, `command` and `reason` do not. Counting it
+ *     as portable would make a path-triggered skill look complete when the very
+ *     routing that selects it never leaves the disk.
+ *   - an UNKNOWN key — one the schema does not declare at all. It fails CLOSED.
+ *     The alternative is to ignore what you cannot classify, and an unknown key
+ *     is exactly the case where the carrier's behaviour is unestablished, so
+ *     returning true there would assert portability from ignorance.
+ *
+ * SCOPE: one carrier, `ContentEntry` in `src/cli/mcp/content.ts`. A second
+ * delivery path drops a different set and needs its own predicate rather than a
+ * widened reading of this one.
+ */
+
+import { INDEXED_TRIGGER_KEYS } from '../../shared/skillRanking.js';
+
+/**
+ * Frontmatter keys `buildEntry` reads and transports whole
+ * (`src/cli/mcp/content.ts` — `fm.name`, `fm.description`, `fm.source`,
+ * `fm.personas`).
+ *
+ * Derived from the carrier source, never from the schema: a schema property the
+ * carrier does not read is dropped no matter what the schema says about it.
+ */
+export const CARRIED_KEYS: readonly string[] = ['name', 'description', 'source', 'personas'];
+
+/**
+ * Keys the carrier reads but truncates, with the sub-keys that actually travel.
+ *
+ * The sub-key list is IMPORTED from `INDEXED_TRIGGER_KEYS` rather than restated.
+ * Restating it was the first version of this file and it is a silent-lie shape:
+ * add a third indexed key and a hand-copied literal keeps reporting the old two
+ * while the carrier transports three, so the census `travels` column would be
+ * wrong with every test still green.
+ */
+export const PARTIAL_KEYS: Readonly<Record<string, readonly string[]>> = {
+    triggers: INDEXED_TRIGGER_KEYS,
+};
+
+/** Why a skill is not body-portable. Empty when it is. */
+export interface PortabilityReasons {
+    /** Declared keys the carrier transports only in part. */
+    readonly partial: readonly string[];
+    /** Declared keys the carrier does not read, including keys the schema does not declare. */
+    readonly dropped: readonly string[];
+}
+
+export interface PortabilityVerdict extends PortabilityReasons {
+    readonly portable: boolean;
+}
+
+/**
+ * Classify one skill's declared frontmatter keys.
+ *
+ * Pure: it reads nothing and depends only on its argument and the two constants
+ * above.
+ */
+export function classifyPortability(frontmatter: Readonly<Record<string, unknown>>): PortabilityVerdict {
+    const partial: string[] = [];
+    const dropped: string[] = [];
+
+    for (const key of Object.keys(frontmatter).sort()) {
+        if (CARRIED_KEYS.includes(key)) continue;
+        if (Object.hasOwn(PARTIAL_KEYS, key)) {
+            partial.push(key);
+            continue;
+        }
+        // Dropped, and an unknown key lands here too — failing closed.
+        dropped.push(key);
+    }
+
+    return { portable: partial.length === 0 && dropped.length === 0, partial, dropped };
+}
+
+/** The predicate itself. `true` only when nothing the skill declares is lost. */
+export function isBodyPortable(frontmatter: Readonly<Record<string, unknown>>): boolean {
+    return classifyPortability(frontmatter).portable;
+}

package/src/scripts/_lib/cascade_base.ts

@@ -0,0 +1,94 @@
+/**
+ * The cascade base — `road-to-adversarial-verification-and-long-runs` 5.1.
+ *
+ * `check_branch_freshness` asks whether a branch is behind THE BASE ITS PR
+ * TARGETS. That is one hop, and it is the right question for the common case
+ * where the base is the trunk. On a stacked PR it is only half of it: a branch
+ * targeting `feat/parent` can be perfectly current with `feat/parent` while
+ * `feat/parent` itself is fifty commits behind `main`, so the branch is stale
+ * against the tree it will eventually land in and every gate reports green.
+ *
+ * The cascade is the ordered list of refs a branch must be current with, nearest
+ * first. Merging in that order is not arbitrary: taking the trunk first would
+ * pull trunk commits past the parent and make the stack's own diff unreadable,
+ * which is the thing a stack exists to avoid.
+ *
+ * **Depth is bounded and the bound is deliberate.** A cascade is a chain of
+ * bases, and a chain can cycle — a branch whose PR targets a branch that targets
+ * it. `MAX_HOPS` stops the walk and the result says it was truncated, because
+ * a hop list silently cut short is indistinguishable from a short one.
+ *
+ * Pure: the caller supplies the base-of lookup, so the whole thing is testable
+ * without a forge.
+ */
+
+/** How many bases a cascade may chain through before the walk stops. */
+export const MAX_HOPS = 8;
+
+export interface Cascade {
+    /** Refs to merge in, nearest base first, trunk last. Never includes `branch`. */
+    readonly hops: readonly string[];
+    /** True when the walk stopped on a cycle rather than on the trunk. */
+    readonly cycle: boolean;
+    /** True when the walk stopped on {@link MAX_HOPS}. */
+    readonly truncated: boolean;
+}
+
+/** `null` when the ref has no PR base — i.e. it is a trunk or is unknown. */
+export type BaseOf = (ref: string) => string | null;
+
+/**
+ * Walk from `branch` to `trunk`, collecting every base on the way.
+ *
+ * A branch whose base IS the trunk yields one hop — identical to the single-hop
+ * behaviour that existed before, which is the compatibility property that
+ * matters: this widens the check, it does not change the common case.
+ */
+export function cascadeBase(branch: string, trunk: string, baseOf: BaseOf): Cascade {
+    const hops: string[] = [];
+    const seen = new Set<string>([branch]);
+    let current = branch;
+
+    for (let i = 0; i < MAX_HOPS; i += 1) {
+        const base = baseOf(current);
+        if (base === null || base === '') {
+            // No PR base. The trunk is still owed unless we are already on it.
+            if (current !== trunk && !hops.includes(trunk)) hops.push(trunk);
+            return { hops, cycle: false, truncated: false };
+        }
+        if (seen.has(base)) {
+            return { hops, cycle: true, truncated: false };
+        }
+        seen.add(base);
+        hops.push(base);
+        if (base === trunk) {
+            return { hops, cycle: false, truncated: false };
+        }
+        current = base;
+    }
+    return { hops, cycle: false, truncated: true };
+}
+
+/** One ref's freshness, as the caller measured it. */
+export interface HopReading {
+    readonly ref: string;
+    /** `true` behind · `false` current · `null` not measured. */
+    readonly behind: boolean | null;
+}
+
+/**
+ * Which hops still need merging, in order.
+ *
+ * An UNMEASURED hop is returned alongside the behind ones rather than skipped:
+ * "we could not tell" and "it is current" are different states, and treating the
+ * first as the second is how a single-hop check reported green on a stale stack
+ * in the first place.
+ */
+export function hopsNeedingMerge(readings: readonly HopReading[]): HopReading[] {
+    return readings.filter((r) => r.behind !== false);
+}
+
+/** True only when every hop was measured and every hop is current. */
+export function cascadeCurrent(readings: readonly HopReading[]): boolean {
+    return readings.length > 0 && readings.every((r) => r.behind === false);
+}

package/src/scripts/_lib/cc_transcript.ts

@@ -82,6 +82,16 @@ export interface TranscriptRecord {
     /** Raw `timestamp` field from the record, or null when absent. */
     timestamp: string | null;
     usage: TokenCounts;
+    /**
+     * UTF-8 byte length of this record's own `message.content`, or `null` when
+     * the scan did not ask for it ({@link ScanOptions.measureBytes}) or the
+     * record carries no serialisable content.
+     *
+     * `null` is NOT zero. A record whose content was never measured and a
+     * record whose content is empty are different facts, and a ratio built
+     * over the first would divide by a denominator it never observed.
+     */
+    content_bytes: number | null;
 }
 
 export interface ScanOptions {
@@ -98,6 +108,17 @@ export interface ScanOptions {
     maxAgeDays?: number;
     /** Clock used to evaluate `maxAgeDays` — injectable for tests. */
     now?: Date;
+    /**
+     * Also measure each record's `message.content` byte length
+     * ({@link TranscriptRecord.content_bytes}).
+     *
+     * OPT-IN, because it costs a second serialisation of content the scan
+     * otherwise never touches, and the existing callers — `cost_summary`,
+     * `preamble_byte_census`, the bench harness — want token sums only. A
+     * caller that does not ask gets `content_bytes: null` on every record and
+     * pays nothing.
+     */
+    measureBytes?: boolean;
 }
 
 export interface ScanResult {
@@ -161,7 +182,7 @@ interface RawUsage {
 
 interface RawAssistantRecord {
     type?: unknown;
-    message?: { id?: unknown; model?: unknown; usage?: RawUsage };
+    message?: { id?: unknown; model?: unknown; usage?: RawUsage; content?: unknown };
     requestId?: unknown;
     agentId?: unknown;
     isSidechain?: unknown;
@@ -180,6 +201,29 @@ function toTokenCounts(raw: RawUsage | undefined): TokenCounts {
     };
 }
 
+/**
+ * UTF-8 byte length of one record's `message.content`, or `null` when there is
+ * nothing serialisable to measure.
+ *
+ * Bytes, never characters: a multibyte block costs what it costs, and
+ * `String.length` would under-report it. Content is what this reader can
+ * actually SEE — the request's system prompt, tool definitions and prior turns
+ * are not in the transcript at all (`preamble_byte_census` records the same
+ * limitation), so a ratio built from this is a ratio over assistant output and
+ * is labelled as such wherever it surfaces.
+ */
+export function measureContentBytes(raw: RawAssistantRecord): number | null {
+    const content = raw.message?.content;
+    if (content === undefined || content === null) return null;
+    if (typeof content === 'string') return Buffer.byteLength(content, 'utf8');
+    try {
+        return Buffer.byteLength(JSON.stringify(content), 'utf8');
+    } catch {
+        // Circular or otherwise unserialisable — unmeasurable, not zero.
+        return null;
+    }
+}
+
 /** Subagent iff a non-empty top-level `agentId` OR `isSidechain === true` — see module doc comment. */
 function classifyBucket(raw: RawAssistantRecord): TranscriptBucket {
     const hasAgentId = typeof raw.agentId === 'string' && raw.agentId.length > 0;
@@ -285,6 +329,7 @@ export function scanTranscripts(opts: ScanOptions = {}): ScanResult {
                 model: typeof raw.message.model === 'string' ? raw.message.model : 'unknown',
                 timestamp: typeof raw.timestamp === 'string' ? raw.timestamp : null,
                 usage: toTokenCounts(raw.message.usage),
+                content_bytes: opts.measureBytes === true ? measureContentBytes(raw) : null,
             });
         }
     }
@@ -298,6 +343,92 @@ export function scanTranscripts(opts: ScanOptions = {}): ScanResult {
     };
 }
 
+/* -------------------------------------------------------------------------- */
+/* Bytes — measured on the corpus, never assumed                               */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * A bytes-per-token ratio, together with the two sums it was divided from and
+ * the population it was measured over.
+ *
+ * The sums travel WITH the ratio on purpose. A bare ratio is the shape that
+ * becomes a constant: somebody copies the number, it outlives the corpus that
+ * produced it, and the next reader cannot tell what it measured. Carrying
+ * `content_bytes` and `output_tokens` means the division is re-derivable from
+ * the record itself.
+ */
+export interface BytesPerToken {
+    /** Always `'measured'` — this value is a division of two counted sums. */
+    basis: 'measured';
+    /** Summed `content_bytes` over the records that carried one. */
+    content_bytes: number;
+    /** Summed `output_tokens` over those same records. */
+    output_tokens: number;
+    /** `content_bytes / output_tokens`. */
+    bytes_per_token: number;
+    /** Records that contributed — `content_bytes !== null` and `output_tokens > 0`. */
+    records: number;
+}
+
+/**
+ * Measure a bytes-per-token ratio ON THE GIVEN RECORDS. Returns `null` when
+ * nothing in the corpus can supply one.
+ *
+ * `null` is the honest outcome and callers must render it as such rather than
+ * substituting a default: a ratio invented where none was measured is exactly
+ * the constant this function exists to make unnecessary. There is deliberately
+ * no fallback value anywhere in this module — the factor is a property of the
+ * corpus, and a corpus that cannot supply one has not supplied one.
+ */
+export function measureBytesPerToken(records: readonly TranscriptRecord[]): BytesPerToken | null {
+    let bytes = 0;
+    let tokens = 0;
+    let n = 0;
+    for (const rec of records) {
+        if (rec.content_bytes === null || rec.usage.output_tokens <= 0) continue;
+        bytes += rec.content_bytes;
+        tokens += rec.usage.output_tokens;
+        n += 1;
+    }
+    if (n === 0 || tokens <= 0) return null;
+    return {
+        basis: 'measured',
+        content_bytes: bytes,
+        output_tokens: tokens,
+        bytes_per_token: bytes / tokens,
+        records: n,
+    };
+}
+
+/** A byte figure obtained by multiplying a token count by a measured ratio. */
+export interface DerivedBytes {
+    /** Always `'derived'`. Never `'measured'` — nothing counted these bytes. */
+    basis: 'derived';
+    /** The token count that was multiplied. */
+    tokens: number;
+    /** The ratio used, carried so the arithmetic sits beside its result. */
+    factor: BytesPerToken;
+    /** `tokens * factor.bytes_per_token`, rounded to a whole byte. */
+    bytes: number;
+}
+
+/**
+ * Multiply a token count by a ratio measured on the same corpus.
+ *
+ * The result carries `basis: 'derived'` and the factor that produced it, so a
+ * derived figure and a counted one can never be read as the same number — the
+ * failure this whole path is shaped to prevent. `null` factor in, `null` out.
+ */
+export function derivedBytes(tokens: number, factor: BytesPerToken | null): DerivedBytes | null {
+    if (factor === null) return null;
+    return {
+        basis: 'derived',
+        tokens,
+        factor,
+        bytes: Math.round(tokens * factor.bytes_per_token),
+    };
+}
+
 function emptyAggregate(bucket: TranscriptBucket): BucketAggregate {
     return {
         bucket,

package/src/scripts/_lib/changelog_eras.ts

@@ -231,8 +231,13 @@ export function archive_file_header(boundary: string): string {
         '> `tests/test_changelog_eras.py`.\n' +
         '>\n' +
         '> **Read-only.** New entries land in `CHANGELOG.md`. Entries\n' +
-        '> here are not amended — git tags remain the canonical source\n' +
-        '> for what shipped.\n' +
+        '> here are not rewritten — git tags remain the canonical source\n' +
+        '> for what shipped. The one amendment an archive permits is a\n' +
+        '> **correction that adds**: where a published entry says something\n' +
+        '> the shipped tree contradicts, the correction is appended beside\n' +
+        '> it and names the commit that decided the matter. Nothing is\n' +
+        '> deleted, so both the original claim and its correction stay\n' +
+        '> readable.\n' +
         '>\n' +
         '> Entry shape follows\n' +
         '> [`../contracts/CHANGELOG-conventions.md`](../contracts/CHANGELOG-conventions.md).\n' +

package/src/scripts/_lib/concern_sla_window.ts

@@ -0,0 +1,200 @@
+/**
+ * Per-concern SLA measurement and the warn-only window's reporting.
+ *
+ * Extracted from `bench_hook_latency.ts` on 2026-10-01, not for tidiness: the
+ * additions that made `one-question-per-ask` measurable and gave the warn-only
+ * window a reader pushed that file from 1,361 lines to 1,583, i.e. 83 lines
+ * past the 1,500-line source ceiling, and `check_source_size_budget`'s ratchet
+ * asked for exactly this by name. Raising the baseline was the other option
+ * and is the one the ratchet exists to make visible rather than easy — a MOVE
+ * gives the budget back instead of spending it, which is the doctrine every
+ * entry in `gate-violation-baselines.json` records.
+ *
+ * It is also the better boundary on its own terms. Everything here answers one
+ * question — which blocking concern is bounded, by how much, and did this run
+ * cross it — and none of it is about measuring a hook SLOT, which is what the
+ * bench itself does.
+ *
+ * NOTHING HERE GATES. The bound these functions read is not armed anywhere:
+ * step 3.3 of `road-to-a-kernel-that-guards-its-plumbing` is its only consumer
+ * and is blocked on the window these functions report. A measurement that can
+ * red a build before its bar is validated is Risk 1 of that roadmap.
+ */
+import * as fs from 'node:fs';
+
+/**
+ * The subset of a per-concern row the window needs: a measurement and a bound.
+ *
+ * Declared here rather than imported so the dependency runs one way only —
+ * `bench_hook_latency.ts` imports this module and this module imports nothing
+ * back. `ConcernLatencyRow` satisfies it structurally, so the caller passes its
+ * own rows unchanged and no adapter exists to drift.
+ */
+export interface BoundedConcern {
+    readonly concern: string;
+    /** p95 of the concern's own durations in microseconds, or null when untimed. */
+    readonly p95_us: number | null;
+    /** The registered SLA in milliseconds, or null when none is registered. */
+    readonly sla_ms: number | null;
+    /** The budget carried a value for this concern that is not a number. */
+    readonly sla_malformed: boolean;
+}
+
+/**
+ * An alternate tool shape for the synthetic payload.
+ *
+ * The default payload names `Read`, which is the right default for every gated
+ * number: it is the common non-matching case consumers pay on every tool call.
+ * But a concern filtered by the manifest's per-concern `tools:` key is SKIPPED
+ * in-process on a payload naming a tool it does not claim, so it never produces
+ * a sample and the per-concern report prints `not_measured` for it — correctly,
+ * and uselessly for a step that needs a bound.
+ *
+ * `one-question-per-ask` is the live instance: `severity: blocking`, filtered to
+ * `AskUserQuestion` and five aliases. It is the only blocking concern the
+ * default payload cannot reach, and the owning roadmap's Phase-3 blocker names
+ * the choice explicitly — "either a payload shaped to trigger it or an explicit
+ * decision that an unmeasured blocking concern keeps the current 30 s timeout".
+ * This is the first branch: measure it, so the decision is not forced by the
+ * harness.
+ *
+ * Measurement-only, like `--bundle` and `--payload-bytes`. It is reachable only
+ * from `concernSlaPass`, which gates nothing and writes no budget row — a probe
+ * payload must never produce a gated slot number, because the slot caps were
+ * derived against the `Read` shape and a different shape runs a different
+ * concern chain.
+ */
+export interface ToolShape {
+    readonly tool_name: string;
+    readonly tool_input: Record<string, unknown>;
+}
+
+/**
+ * The probe that reaches `one-question-per-ask`.
+ *
+ * ONE question, not two: a single question is the ALLOW path, and the allow
+ * path is what an ordinary call costs. Two questions would measure the deny
+ * path — the rarer branch, and the one that builds a message — so a bound taken
+ * from it would describe the exception rather than the rule. Both run
+ * `countStructuredAskQuestions`, which is the concern's actual work.
+ */
+export const ASK_PROBE: ToolShape = {
+    tool_name: 'AskUserQuestion',
+    tool_input: { questions: [{ question: 'bench probe' }] },
+};
+
+/**
+ * The one concern the ask probe exists to measure.
+ *
+ * Named rather than inferred from the `tools:` filter: a future concern added
+ * with an overlapping filter would be measured under a payload chosen for THIS
+ * one, and silently adopting it is the contamination above wearing a different
+ * shape.
+ */
+export const PROBE_TARGET = 'one-question-per-ask';
+
+/**
+ * Append only `target`'s samples from the probe sink onto the main sink.
+ *
+ * The probe sink is read and then left in place; it is a temp-dir file the
+ * caller owns. A read failure is not fatal — the probe is an observation, and
+ * a bench that dies because one auxiliary sink was unreadable converts a
+ * measurement into an outage, which is the posture `readConcernTimings`
+ * already takes one level down.
+ */
+export function mergeProbeSamples(probeSink: string, sinkPath: string, target: string): void {
+    let text: string;
+    try {
+        text = fs.readFileSync(probeSink, 'utf-8');
+    } catch {
+        return;
+    }
+    const keep: string[] = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '') continue;
+        let row: { concern?: unknown };
+        try {
+            row = JSON.parse(trimmed) as typeof row;
+        } catch {
+            continue;
+        }
+        if (row.concern === target) keep.push(trimmed);
+    }
+    if (keep.length === 0) return;
+    try {
+        fs.appendFileSync(sinkPath, `${keep.join('\n')}\n`, 'utf-8');
+    } catch {
+        /* the sink is an observation aid; losing it must not fail the bench */
+    }
+}
+
+/**
+ * The warn-only window, made legible — observe-only, gating nothing.
+ *
+ * Step 3.3 derives a per-concern timeout of `sla_ms x 3` and its own text says
+ * "warn-only for the first measured window, then deny". A window nothing
+ * observes is not a window: with `sla_ms` registered and no reader, the flip
+ * would be taken on the absence of a complaint rather than on a reading.
+ *
+ * So this is the instrument. Every bench run — local or CI, gated or not —
+ * prints each blocking concern's measured p95 beside its registered bound and
+ * names any concern that crossed it. The window is then a span of runs a human
+ * can read, and the flip has an evidence base that exists before it is taken.
+ *
+ * It lives in the measurement harness and NOT in the dispatcher deliberately.
+ * A runtime warn would be a dispatcher change shipped as part of a step that is
+ * blocked on the very readings it would produce, and Risk 1 of the owning
+ * roadmap is precisely about acting on a bound before it is validated.
+ *
+ * A concern with no registered SLA, or no measurement, is NOT an overrun — it
+ * is an unknown, and the two must not collapse. Returning it as "fine" would
+ * let an unregistered concern read as a clean window.
+ */
+export interface SlaOverrun {
+    concern: string;
+    p95_us: number;
+    /** `sla_ms x 3`, in microseconds — the bound step 3.3 would apply. */
+    bound_us: number;
+}
+
+/**
+ * What a run can actually say about the window — three counts, never one.
+ *
+ * `registered` is how many concerns carry a bound. `usable` is how many of
+ * those this run could compare against it. The gap is what an earlier version
+ * of the summary line silently dropped: it printed "none over" off `registered`,
+ * so a run that measured none of its bounded concerns read exactly like a run
+ * that measured all of them and found nothing. That is the same
+ * unknown-collapsed-into-fine failure `slaOverruns` refuses per row, one level
+ * up at the summary.
+ */
+export interface WindowState {
+    registered: number;
+    usable: number;
+    /** Registered but not comparable this run — unmeasured or malformed. */
+    unusable: number;
+}
+
+export function windowState(rows: readonly BoundedConcern[]): WindowState {
+    let registered = 0;
+    let usable = 0;
+    for (const row of rows) {
+        if (row.sla_ms === null && !row.sla_malformed) continue;
+        registered += 1;
+        if (!row.sla_malformed && row.sla_ms !== null && row.p95_us !== null) usable += 1;
+    }
+    return { registered, usable, unusable: registered - usable };
+}
+
+export function slaOverruns(rows: readonly BoundedConcern[]): SlaOverrun[] {
+    const out: SlaOverrun[] = [];
+    for (const row of rows) {
+        if (row.sla_ms === null || row.sla_malformed || row.p95_us === null) continue;
+        const bound_us = row.sla_ms * 3 * 1000;
+        if (row.p95_us > bound_us) {
+            out.push({ concern: row.concern, p95_us: row.p95_us, bound_us });
+        }
+    }
+    return out;
+}