@event4u/agent-config 9.9.0 → 9.10.0

package/src/scripts/_lib/compile_time_toggles.ts

@@ -0,0 +1,79 @@
+/**
+ * Compile-time rule toggles — the single definition, shared by the router compiler
+ * and the projector.
+ *
+ * WHY THIS FILE EXISTS
+ * --------------------
+ * The map used to live only in `compile_router.ts`, which meant a disabled rule was
+ * dropped from `dist/router.json` while its **body still shipped** as a file in
+ * `dist/agent-src/rules/` (and through the `.claude/rules/` symlink). ADR
+ * `telegraph/0002` originally claimed that flipping the toggle gave "zero-cost
+ * dormancy". That was measured and found half wrong on 2026-07-29: the router entry
+ * governs *trigger-routing*; **file existence governs always-loaded injection**, and
+ * the host reads the file — a maintainer session's context listed the body verbatim
+ * as "project instructions", never having consulted the router.
+ *
+ * Two surfaces, one switch. Sharing the definition is what lets the projector honour
+ * it, so `speak: false` means what the ADR assumed instead of the ADR being weakened
+ * to match a partial implementation.
+ */
+
+/**
+ * HOW A RULE GETS HERE — the dormancy routing (road-to-cache-economy Phase 3)
+ * --------------------------------------------------------------------------
+ * A rule body is re-written on EVERY subagent spawn, so an always-loaded rule
+ * that is not earning its keep is paid per spawn, not once. That makes "should
+ * this rule be dormant?" a real question — and this map is the ONLY place the
+ * answer may land. The route, in order:
+ *
+ *   1. **Candidate** — `preamble_byte_census` ranks always-loaded rules by
+ *      per-spawn token cost (`--top`). A candidate is a number, never an
+ *      impression: telegraph-speak was ~982 tokens.
+ *   2. **Evidence** — the same bar telegraph-speak had to clear: an output-side
+ *      bench showing the rule does not pay for itself, judged against the
+ *      kill-criterion, BEFORE dormancy. A preference is not evidence, and
+ *      "it looks verbose" is not a measurement.
+ *   3. **Landing** — a new entry in the map below, keyed on a real setting the
+ *      consumer can flip back. Never a fifth toggle axis: this predicate already
+ *      has four consumers (the router compiler, the dist writer, `check_sync`,
+ *      and the per-tool symlink generator), and a rule wired into three of four
+ *      is how the last attempt blocked its own push.
+ *
+ * What is explicitly NOT this route: dropping a rule from the router while its
+ * body still ships (that was the measured half-truth this file exists to fix),
+ * and gating bodies behind triggers wholesale — that is thin projection, which
+ * failed a 48% quality floor at 36.2% and stays disabled.
+ */
+
+/** Loose settings shape — the toggles only ever read nested plain objects. */
+export type ToggleSettings = Record<string, unknown>;
+
+/** rule-id → predicate. A rule is emitted (router AND projection) only when its
+ * predicate returns true. A rule absent from this map is always emitted. */
+export const COMPILE_TIME_TOGGLES: Record<string, (s: ToggleSettings) => boolean> = {
+    // `speak` defaults FALSE (dormant) per docs/adrs/telegraph/0002 — the absent-key
+    // fallback used to be `true`, which silently contradicted ADR 0001 (accepted,
+    // "default off until bench"). Measured basis: median vs_terse −9.27% (API) /
+    // −5.47% (exact cl100k_base) — telegraph emits MORE than a plain "be terse".
+    // Opt back in with an explicit `telegraph.speak: true` once an output-side bench
+    // clears the kill-criterion bar. `enabled` keeps its true default: it is the
+    // family master switch, and flipping it would silence sibling telegraph settings
+    // that were never measured negative.
+    //
+    // This predicate deliberately does NOT read `speak_scope`. That key disables the
+    // rule's *behaviour* and never removed its token cost — the trap the measurement
+    // exposed.
+    'telegraph-speak': (s: ToggleSettings): boolean => {
+        const tg = (s['telegraph'] as ToggleSettings | undefined) ?? {};
+        const enabled = tg['enabled'] === undefined ? true : tg['enabled'];
+        const speak = tg['speak'] === undefined ? false : tg['speak'];
+        return Boolean(enabled) && Boolean(speak);
+    },
+};
+
+/** True when the rule may be emitted. Unknown ids are always emitted — the map is an
+ * opt-in list of gated rules, never an allowlist of permitted ones. */
+export function rule_is_compile_enabled(rule_id: string, settings: ToggleSettings): boolean {
+    const predicate = COMPILE_TIME_TOGGLES[rule_id];
+    return predicate === undefined ? true : predicate(settings);
+}

package/src/scripts/_lib/confusables.ts

@@ -0,0 +1,101 @@
+/**
+ * Visible mixed-script confusable signature — the ONE definition in the tree.
+ *
+ * Extracted from `lint_confusables.ts` so the authoring-time linter and the
+ * runtime encoding scanner share one table and one decision rule
+ * (road-to-runtime-encoding-hardening Phase 3). Two copies of a confusable set
+ * is exactly the drift this extraction prevents: a codepoint added to one and
+ * not the other means the two surfaces disagree about what a homoglyph is.
+ *
+ * The dependency direction matters. This module imports NOTHING — no `fs`, no
+ * lint framework — so the runtime retrieval path can use it without pulling the
+ * authoring-time lint infrastructure into a request.
+ */
+
+/** A token needs this many letters before the signature can fire. */
+export const MIN_LETTERS = 3;
+
+// Unicode-script classifiers via property escapes (requires the `u` flag).
+const _LATIN = /\p{Script=Latin}/u;
+const _CYRILLIC = /\p{Script=Cyrillic}/u;
+const _GREEK = /\p{Script=Greek}/u;
+const _LETTER = /\p{L}/u;
+
+/** A "token" is a maximal run of letters / combining marks / decimal digits. */
+export const TOKEN_RE = /[\p{L}\p{M}\p{Nd}]+/gu;
+
+/**
+ * Cyrillic + Greek codepoints that have a basic-Latin lookalike (Unicode TR39
+ * confusables, common subset). A foreign letter only counts toward the
+ * confusable signal when it is in this set — Greek math operators with no Latin
+ * twin (Δ Σ Π Ω Φ Θ Λ Ξ Ψ Γ δ π ω …) are deliberately excluded so legit
+ * notation does not false-positive.
+ */
+export const CONFUSABLE_FOREIGN: ReadonlySet<number> = new Set([
+    // Cyrillic lowercase ↔ Latin
+    0x0430 /*а→a*/, 0x0435 /*е→e*/, 0x043e /*о→o*/, 0x0440 /*р→p*/, 0x0441 /*с→c*/,
+    0x0443 /*у→y*/, 0x0445 /*х→x*/, 0x0455 /*ѕ→s*/, 0x0456 /*і→i*/, 0x0458 /*ј→j*/,
+    0x04bb /*һ→h*/, 0x0501 /*ԁ→d*/, 0x051b /*ԛ→q*/, 0x0577 /*no*/,
+    // Cyrillic uppercase ↔ Latin
+    0x0410 /*А→A*/, 0x0412 /*В→B*/, 0x0415 /*Е→E*/, 0x041a /*К→K*/, 0x041c /*М→M*/,
+    0x041d /*Н→H*/, 0x041e /*О→O*/, 0x0420 /*Р→P*/, 0x0421 /*С→C*/, 0x0422 /*Т→T*/,
+    0x0423 /*У→Y*/, 0x0425 /*Х→X*/, 0x0405 /*Ѕ→S*/, 0x0406 /*І→I*/, 0x0408 /*Ј→J*/,
+    // Greek lowercase ↔ Latin
+    0x03b1 /*α→a*/, 0x03b5 /*ε→e*/, 0x03bf /*ο→o*/, 0x03bd /*ν→v*/, 0x03c1 /*ρ→p*/,
+    0x03c5 /*υ→u*/, 0x03c7 /*χ→x*/, 0x03ba /*κ→k*/,
+    // Greek uppercase ↔ Latin (only those with a real Latin twin)
+    0x0391 /*Α→A*/, 0x0392 /*Β→B*/, 0x0395 /*Ε→E*/, 0x0396 /*Ζ→Z*/, 0x0397 /*Η→H*/,
+    0x0399 /*Ι→I*/, 0x039a /*Κ→K*/, 0x039c /*Μ→M*/, 0x039d /*Ν→N*/, 0x039f /*Ο→O*/,
+    0x03a1 /*Ρ→P*/, 0x03a4 /*Τ→T*/, 0x03a5 /*Υ→Y*/, 0x03a7 /*Χ→X*/, 0x0392 /*Β→B*/,
+]);
+
+type ScriptName = 'latin' | 'cyrillic' | 'greek' | 'other';
+
+function _script_of(ch: string): ScriptName {
+    if (_LATIN.test(ch)) return 'latin';
+    if (_CYRILLIC.test(ch)) return 'cyrillic';
+    if (_GREEK.test(ch)) return 'greek';
+    return 'other';
+}
+
+/**
+ * Classify a single token. Returns the offending mixed-script descriptor when
+ * the token matches the homoglyph signature, else null.
+ *
+ * The containment rules are the load-bearing part, and they are why this is one
+ * shared function rather than two similar ones: a Latin-majority token with at
+ * least one TR39-confusable foreign letter is the signal; a single-script token
+ * (a genuine Cyrillic or Greek word) is not; and a token whose foreign letters
+ * outnumber its Latin ones is a foreign word, not an attack.
+ */
+export function classifyToken(token: string): string | null {
+    let latin = 0;
+    let cyrillic = 0;
+    let greek = 0;
+    let letters = 0;
+    for (const ch of token) {
+        if (!_LETTER.test(ch)) continue; // skip combining marks / digits for script vote
+        letters += 1;
+        const script = _script_of(ch);
+        if (script === 'latin') {
+            latin += 1;
+        } else if (script === 'cyrillic' || script === 'greek') {
+            // Only confusable foreign letters (TR39) count — math operators with
+            // no Latin twin are ignored, so legit notation never trips.
+            if (CONFUSABLE_FOREIGN.has(ch.codePointAt(0) as number)) {
+                if (script === 'cyrillic') cyrillic += 1;
+                else greek += 1;
+            }
+        }
+    }
+    if (letters < MIN_LETTERS) return null;
+    const foreign = cyrillic + greek;
+    if (latin === 0 || foreign === 0) return null; // single-script (or no Latin) → legit
+    if (latin <= foreign) return null; // majority must be Latin (foreign word ≠ attack)
+    const which = cyrillic > 0 && greek > 0
+        ? 'cyrillic+greek'
+        : cyrillic > 0
+            ? 'cyrillic'
+            : 'greek';
+    return `latin+${which} (${latin} latin / ${foreign} foreign-confusable)`;
+}

package/src/scripts/_lib/duplicate_scope_census.ts

@@ -0,0 +1,77 @@
+/**
+ * Duplicate-scope rule census — the shared byte-comparison primitive behind
+ * both C-2 (`cache_realization_report.ts`'s `computeDuplicateScope`, which
+ * turns this into a share of subagent write volume) and the `doctor`
+ * `duplicate-scope-rules` health check (`_cli/cmd_doctor.ts`), so the two
+ * surfaces can never drift on what counts as "shared" or how a redundant
+ * copy's size is estimated.
+ *
+ * `road-to-cache-economy.md` Phase 3: the same 110 rule
+ * filenames observed at both `~/.claude/rules` (user scope) and
+ * `dist/agent-src/rules` (project scope) on this maintainer's own checkout —
+ * C-2 confirmed at 38.5% of subagent write volume. This module answers only
+ * "which filenames are shared, and how many redundant bytes do they cost" —
+ * the write-volume share and the doctor warning are each computed by their
+ * own caller from this raw census.
+ *
+ * Detection only. Never deletes, never rewrites a user's file — see
+ * `non-destructive-by-default`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+export interface DuplicateScopeCensus {
+    evaluable: boolean;
+    reason?: string | undefined;
+    /** `.md` basenames present in BOTH directories, sorted. */
+    shared_filenames: string[];
+    /** Σ min(userBytes, projectBytes) over shared filenames — the conservative
+     *  estimate of the redundant copy (the roadmap's byte census found the two
+     *  scopes near-identical in size, so the min/max choice rarely matters). */
+    duplicate_chars: number;
+}
+
+/**
+ * For every `.md` filename present in BOTH `userRulesDir` and
+ * `projectRulesDir`, the redundant copy is estimated as the SMALLER of the
+ * two files' byte sizes, summed across all shared filenames.
+ */
+export function censusDuplicateScope(userRulesDir: string, projectRulesDir: string): DuplicateScopeCensus {
+    if (!fs.existsSync(userRulesDir) || !fs.existsSync(projectRulesDir)) {
+        return {
+            evaluable: false,
+            reason: `one or both rule directories are missing (user: ${userRulesDir}, project: ${projectRulesDir})`,
+            shared_filenames: [],
+            duplicate_chars: 0,
+        };
+    }
+
+    const userFiles = new Set(fs.readdirSync(userRulesDir).filter((f) => f.endsWith('.md')));
+    const projectFiles = fs.readdirSync(projectRulesDir).filter((f) => f.endsWith('.md'));
+
+    const shared: string[] = [];
+    let duplicateChars = 0;
+    for (const f of projectFiles) {
+        if (!userFiles.has(f)) continue;
+        shared.push(f);
+        const a = fs.statSync(path.join(userRulesDir, f)).size;
+        const b = fs.statSync(path.join(projectRulesDir, f)).size;
+        duplicateChars += Math.min(a, b);
+    }
+    shared.sort();
+
+    if (shared.length === 0) {
+        return {
+            evaluable: false,
+            reason: 'no shared .md filenames between the two rule scopes — this checkout has no duplicate-scope install',
+            shared_filenames: [],
+            duplicate_chars: 0,
+        };
+    }
+
+    return {
+        evaluable: true,
+        shared_filenames: shared,
+        duplicate_chars: duplicateChars,
+    };
+}

package/src/scripts/_lib/managed_agents_folder.ts

@@ -0,0 +1,181 @@
+/**
+ * Detect whether a directory is a project whose `agents/` folder is managed
+ * by this package.
+ *
+ * `.agent-settings.yml` resolution and settings-cascade routing already have
+ * a project-root walker (`find_project_root_with_anchor` in
+ * `_lib/agent_settings.ts`), but that walker answers a different question —
+ * "where does the settings cascade start reading from" — and its `agents/`
+ * check exists only to pick a boundary anchor for that walk (its marker list
+ * mixes package-source-repo-only paths, e.g. `settings/.ai-council.yml`, with
+ * consumer-only paths). It also treats a bare `.git` anywhere in the ancestor
+ * chain as "a project was found", which is the right answer for "where do
+ * settings live" but the wrong answer for "is this THIS package's managed
+ * `agents/` folder" — a third-party repo with an unrelated `agents/`
+ * directory and its own `.git` would resolve to a root there too. No
+ * existing helper answers the narrower managed/unmanaged/not-a-project
+ * question this module exists for.
+ *
+ * Contract — pure, read-only, tolerant:
+ *
+ * - Never writes, never mutates, never touches the network.
+ * - Operates on the given `start` directory directly — it does not walk
+ *   ancestors looking for a project root (that is the caller's job, e.g.
+ *   via `find_project_root` when the caller only has a subdirectory).
+ *   Keeping this helper non-walking keeps it a distinct primitive from the
+ *   settings-root walker above rather than a second, subtly different copy
+ *   of the same walk.
+ * - Silently tolerant of a missing/unreadable `start` — every check falls
+ *   through to `false`, which resolves to `'not-a-project'`.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { SECTION_HEADER as _MANAGED_GITIGNORE_HEADER } from '../sync_gitignore.js';
+
+/**
+ * Three-state answer — never a boolean, because "no `agents/` folder" and
+ * "no project at all" route differently downstream (an unmanaged repo is a
+ * candidate for adoption; a bare directory outside any repo is not a
+ * project the P-routing question even applies to).
+ */
+export type ManagedAgentsFolderStatus = 'managed' | 'unmanaged' | 'not-a-project';
+
+/**
+ * Detection predicate — chosen after inspecting what the installer actually
+ * writes into a consumer project (verified against source, not invented):
+ *
+ *   is_project   := <start>/.git exists (file or directory — worktrees and
+ *                    submodules use a `.git` file, not a directory).
+ *   has_agents   := <start>/agents is a directory.
+ *   has_marker   := ANY of —
+ *     (a) <start>/.gitignore contains the managed-block header line
+ *         `# event4u/agent-config` (`SECTION_HEADER` in
+ *         `sync_gitignore.ts`) — installed by `refresh --project` /
+ *         `sync:gitignore`. Strongest signal: the literal package name, so
+ *         a third-party repo carries it only if it also runs this package.
+ *     (b) <start>/agents/overrides/ is a directory — scaffolded by
+ *         `install.ts` for every consumer project (the "guaranteed
+ *         minimal-consumer surface", ADR-020).
+ *     (c) a resolvable `.agent-settings.yml` exists — canonical
+ *         `<start>/agents/settings/.agent-settings.yml`, or the legacy
+ *         `<start>/.agent-settings.yml` fallback (see
+ *         `project_settings_path` in `_lib/agent_settings.ts`).
+ *
+ *   status := has_agents && has_marker  → 'managed'
+ *             is_project (else)         → 'unmanaged'
+ *             otherwise                 → 'not-a-project'
+ *
+ * Rejected alternatives:
+ *
+ *   - `agents/` existence alone (no marker). Rejected: this is exactly the
+ *     false positive the roadmap phase calls out — an unrelated multi-agent
+ *     framework repo, or any project that happens to name a directory
+ *     `agents/`, would read as managed with zero package-specific evidence.
+ *   - Reusing `find_project_root_with_anchor`'s `_AGENTS_DIR_MARKERS` list
+ *     verbatim (`roadmaps`, `settings/.ai-council.yml`,
+ *     `roadmaps-progress.md`, `overrides`). Rejected: two of those four
+ *     (`settings/.ai-council.yml`, `roadmaps-progress.md`) are `pkg`-scope
+ *     only per `docs/contracts/agents-layout.md`'s consumer-slim-profile
+ *     table — they never appear in an installed consumer project, so
+ *     requiring "any one" would under-detect nothing (they're just dead
+ *     weight for the consumer case) but reusing the *function* would also
+ *     inherit its `.git`-anchor and `.agent-settings.yml`-layer-fallback
+ *     semantics, which answer "where is the settings root" rather than
+ *     "is `agents/` managed" (see module docblock).
+ *   - `agents/roadmaps/` as a marker. Rejected: it is listed as "Optional"
+ *     even in the consumer-slim profile — a managed project with zero
+ *     roadmaps yet (the common case right after install) would false-
+ *     negative.
+ */
+function _existsAt(dir: string, ...segments: readonly string[]): boolean {
+    try {
+        fs.statSync(path.join(dir, ...segments));
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function _isDirAt(dir: string, ...segments: readonly string[]): boolean {
+    try {
+        return fs.statSync(path.join(dir, ...segments)).isDirectory();
+    } catch {
+        return false;
+    }
+}
+
+function _isFileAt(dir: string, ...segments: readonly string[]): boolean {
+    try {
+        return fs.statSync(path.join(dir, ...segments)).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/** `true` when `start` sits at the root of a git repository (or worktree). */
+function _isGitProject(start: string): boolean {
+    // `.git` is a directory in a normal clone, a file in a worktree or
+    // submodule checkout — `statSync` (not `lstatSync`) is deliberate so a
+    // broken symlink named `.git` does not count as present.
+    return _existsAt(start, '.git');
+}
+
+/** `true` when `<start>/.gitignore` carries the managed-block header line. */
+function _hasManagedGitignoreBlock(start: string): boolean {
+    if (!_isFileAt(start, '.gitignore')) {
+        return false;
+    }
+    let text: string;
+    try {
+        text = fs.readFileSync(path.join(start, '.gitignore'), 'utf-8');
+    } catch {
+        return false;
+    }
+    return text
+        .split(/\r\n|\r|\n/)
+        .some((line) => line.trim() === _MANAGED_GITIGNORE_HEADER);
+}
+
+/** `true` when `<start>/agents/overrides` exists as a directory. */
+function _hasOverridesDir(start: string): boolean {
+    return _isDirAt(start, 'agents', 'overrides');
+}
+
+/**
+ * `true` when a resolvable `.agent-settings.yml` exists — canonical
+ * `agents/settings/.agent-settings.yml`, or the legacy repo-root
+ * `.agent-settings.yml`.
+ */
+function _hasResolvableAgentSettings(start: string): boolean {
+    return (
+        _isFileAt(start, 'agents', 'settings', '.agent-settings.yml') ||
+        _isFileAt(start, '.agent-settings.yml')
+    );
+}
+
+/**
+ * Classify `start` as `'managed'` (an `agents/` folder this package
+ * installed and can safely write project facts into), `'unmanaged'` (a real
+ * project — has a `.git` — with no such folder, or an `agents/` folder this
+ * package did not install), or `'not-a-project'` (no `.git` at `start` at
+ * all — e.g. a bare directory outside any repo).
+ *
+ * Read-only. Does not walk ancestors — `start` is checked directly; pass a
+ * project root (e.g. from `find_project_root`) when the caller only has a
+ * subdirectory.
+ */
+export function detect_managed_agents_folder(start: string): ManagedAgentsFolderStatus {
+    if (!_isGitProject(start)) {
+        return 'not-a-project';
+    }
+    const hasAgentsDir = _isDirAt(start, 'agents');
+    const hasMarker =
+        _hasManagedGitignoreBlock(start) ||
+        _hasOverridesDir(start) ||
+        _hasResolvableAgentSettings(start);
+    if (hasAgentsDir && hasMarker) {
+        return 'managed';
+    }
+    return 'unmanaged';
+}

package/src/scripts/_lib/payload_hash_drift.ts

@@ -0,0 +1,126 @@
+/**
+ * Payload-hash × cache-hit drift aggregator (pure, no-I/O).
+ *
+ * `road-to-cache-economy.md` Phase 3, step 6: the
+ * `orchestration` object's `payload_hash` and `cache_hit` fields are both
+ * `null`-by-default and read by nothing (per the roadmap's own defect list).
+ * This module is the reader: it joins the two fields recorded on the SAME
+ * audit-log-v1 line — `payload_hash` names which spawn-payload shape a
+ * dispatch used, `cache_hit` is the provider-reported prompt-cache hit for
+ * that dispatch — so prefix-stability drift becomes visible.
+ *
+ * Cohort split (the roadmap's own verify criterion — "a cohort dispatched
+ * with a deliberately unstable payload shows a lower read share than a
+ * stable one"):
+ *
+ * - STABLE cohort: every occurrence of a `payload_hash` AFTER its first —
+ *   a hash that repeats means the same payload shape was dispatched again,
+ *   so a cache hit on the repeat is the signal a stable prefix predicts.
+ * - UNSTABLE cohort: every `payload_hash` that occurs exactly once in the
+ *   window — a payload that never repeats can never show a repeat-hit, so
+ *   its (necessarily first-call) `cache_hit` value is the unstable-payload
+ *   baseline.
+ *
+ * A hash's FIRST occurrence is excluded from the stable cohort — nothing
+ * exists yet for a first call to hit, so counting it would understate the
+ * stable cohort's hit rate for a reason that has nothing to do with prefix
+ * stability.
+ *
+ * Zero recorded lines is a VALID state (both fields are lean-init
+ * extensions with no caller wiring a real value yet) — the aggregator
+ * returns a report with empty cohorts rather than failing, and the CLI
+ * wrapper states that plainly rather than presenting empty input as a green
+ * result.
+ */
+
+export interface PayloadHashLine {
+    payload_hash: string | null;
+    cache_hit: boolean | null;
+}
+
+export interface HashGroupStat {
+    payload_hash: string;
+    occurrences: number;
+    hit_count: number;
+    hit_rate: number;
+}
+
+export interface CohortStat {
+    n: number;
+    hit_count: number;
+    hit_rate: number | null;
+}
+
+export interface PayloadHashDriftReport {
+    total_lines: number;
+    /** Lines carrying both a non-null `payload_hash` and a boolean `cache_hit`. */
+    lines_with_data: number;
+    /** Per-hash breakdown, most-occurrences first. */
+    groups: HashGroupStat[];
+    stable_cohort: CohortStat;
+    unstable_cohort: CohortStat;
+    /** True only when BOTH cohorts have data AND the stable cohort's hit rate is strictly higher. */
+    drift_visible: boolean;
+}
+
+function emptyCohort(): CohortStat {
+    return { n: 0, hit_count: 0, hit_rate: null };
+}
+
+/**
+ * Aggregates already-parsed audit-log-v1 orchestration lines. `lines` order
+ * matters — it is read as chronological (the CLI wrapper reads
+ * `agents/runtime/state/audit/*.jsonl` in filename-sorted order, matching
+ * `readAuditLines`), since "first occurrence of a hash" is the only signal
+ * that decides which cohort an occurrence falls into.
+ */
+export function aggregatePayloadHashDrift(lines: readonly PayloadHashLine[]): PayloadHashDriftReport {
+    const withData = lines.filter((l) => l.payload_hash !== null && l.cache_hit !== null);
+
+    const byHash = new Map<string, boolean[]>();
+    for (const l of withData) {
+        const hash = l.payload_hash as string;
+        const arr = byHash.get(hash) ?? [];
+        arr.push(l.cache_hit as boolean);
+        byHash.set(hash, arr);
+    }
+
+    const groups: HashGroupStat[] = [];
+    const stable = emptyCohort();
+    const unstable = emptyCohort();
+
+    for (const [hash, hits] of byHash) {
+        const hitCount = hits.filter(Boolean).length;
+        groups.push({
+            payload_hash: hash,
+            occurrences: hits.length,
+            hit_count: hitCount,
+            hit_rate: hitCount / hits.length,
+        });
+
+        if (hits.length === 1) {
+            unstable.n += 1;
+            if (hits[0] === true) unstable.hit_count += 1;
+        } else {
+            // Every occurrence AFTER the first (repeat dispatches of the same payload shape).
+            const repeats = hits.slice(1);
+            stable.n += repeats.length;
+            stable.hit_count += repeats.filter(Boolean).length;
+        }
+    }
+
+    groups.sort((a, b) => b.occurrences - a.occurrences || a.payload_hash.localeCompare(b.payload_hash));
+    stable.hit_rate = stable.n > 0 ? stable.hit_count / stable.n : null;
+    unstable.hit_rate = unstable.n > 0 ? unstable.hit_count / unstable.n : null;
+
+    const driftVisible = stable.hit_rate !== null && unstable.hit_rate !== null && stable.hit_rate > unstable.hit_rate;
+
+    return {
+        total_lines: lines.length,
+        lines_with_data: withData.length,
+        groups,
+        stable_cohort: stable,
+        unstable_cohort: unstable,
+        drift_visible: driftVisible,
+    };
+}