@event4u/agent-config 14.2.0 → 14.5.0

package/src/scripts/hooks/session_eol_hook.ts

@@ -54,6 +54,8 @@ import {
     scanEolSlice,
     type EolCounters,
 } from '../_lib/session_eol.js';
+import { buildCheckpoint, writeCheckpoint } from '../_lib/run_checkpoint.js';
+import { read_claimed_slug } from '../session_register_hook.js';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
@@ -107,6 +109,23 @@ export function deriveSessionKey(envelope: JsonObject, payload: JsonObject): str
     );
 }
 
+/**
+ * The RAW session id, not the hashed key.
+ *
+ * `read_claimed_slug` keys the per-session claim file off the id the host
+ * exported, so handing it `deriveSessionKey`'s hash would look up a file that
+ * cannot exist and silently report "no contract" for every claimed run.
+ * Falls back to the envelope, which is where the dispatcher puts it, and
+ * deliberately does NOT fall back to the transcript path: that is a filename,
+ * not an identity, and `sessions:claim` never wrote a claim under one.
+ */
+export function payloadSessionId(payload: JsonObject, envelope: JsonObject): string {
+    return (
+        str(payload['session_id'] as JsonValue | undefined) ||
+        str(envelope['session_id'] as JsonValue | undefined)
+    ).trim();
+}
+
 /** Load prior per-session state; any read/shape error reads as "fresh session". */
 export function readState(file: string): SessionEolState {
     try {
@@ -337,6 +356,39 @@ export function main(): number {
 
     writeContextFill(workspaceRoot, tokens, threshold, now);
 
+    // ── UOTL Phase 6.1 — the deterministic half of the handoff ───────
+    //
+    // Above the threshold AND inside a running contract, leave a derived
+    // checkpoint behind. Two properties the advisory alone cannot give:
+    //
+    //   · It costs no judgement. Every field is recomputed from the
+    //     roadmap on disk, so a dying session produces it correctly even
+    //     when it has no context left to summarise anything.
+    //   · It is re-verifiable. A resumed run recomputes the same fields
+    //     and can name WHICH claim went stale rather than trusting the
+    //     record, which is the deliberate departure from resuming by
+    //     bookkeeping (Phase 3.2).
+    //
+    // "Inside a running contract" is the same carrier `run-continuation`
+    // uses — a `sessions:claim` for this session — and no second one is
+    // invented. Outside a contract this is silent: a checkpoint for a
+    // conversational session names work nobody is executing.
+    //
+    // Best-effort throughout. A checkpoint is a recovery aid, and a
+    // recovery aid that can fail a Stop is a liability.
+    const checkpointRunId = payloadSessionId(payload, envelope);
+    if (shouldAdvise && checkpointRunId !== '') {
+        try {
+            const slug = read_claimed_slug(workspaceRoot, checkpointRunId);
+            if (slug !== null) {
+                const cp = buildCheckpoint(workspaceRoot, eolSessionKey(checkpointRunId), slug);
+                if (cp !== null) writeCheckpoint(workspaceRoot, cp);
+            }
+        } catch {
+            // never block the Stop path
+        }
+    }
+
     if (shouldAdvise && threshold !== null && tokens !== null) {
         process.stdout.write(
             `${JSON.stringify({

package/src/scripts/hooks/telemetry_usage_hook.ts

@@ -0,0 +1,339 @@
+#!/usr/bin/env tsx
+/**
+ * Deterministic PostToolUse Class-A usage capture
+ * (road-to-org-telemetry Phase 1, step 1.2).
+ *
+ * Why a hook rather than the existing collector. `skill_usage_collect.ts`
+ * scans the maintainer's own transcript directory and derives its project
+ * slug from this repository, so a consumer session is invisible to it by
+ * construction — the roadmap's Context table records that as still true
+ * after 479 commits. Phase 0's third spike then measured the size of the
+ * gap on the set the collector DOES read: **0 of 89** invocations detected,
+ * against 163 of 164 across every worktree slug. The zero in the usage
+ * report is an instrumentation artefact, not an adoption measurement.
+ *
+ * Phase 0's first spike settled the event this concern binds to:
+ * `post_tool_use` with `tool_name === "Skill"`, the skill name at
+ * `tool_input.skill` — present in 164 of 164 real invocations across 14,171
+ * live records. The transcript-scan fallback the roadmap pre-registered does
+ * not fire.
+ *
+ * DEFAULT-OFF, AND THE SWITCH IS NOT `enabled`. `read_remote_settings`
+ * activates only when `enabled` is true AND the org pack supplied an
+ * endpoint, an org id, and a salt. An external clone of this repository
+ * carries the key names and no values, so copying the tree cannot reach the
+ * write path. When inactive this concern performs zero telemetry file
+ * operations — no log write, no directory creation — and zero network calls.
+ * (It does read `.agent-settings.yml`, once per process and memoised: the
+ * settings file is how it learns it is off, the same as the artefact-
+ * engagement surface it mirrors.)
+ *
+ * NO OUTBOUND CALL EXISTS HERE, DELIBERATELY. Transport is Phase 2 and is
+ * blocked on `sink-choice`; org-wide enablement is Phase 3 and is blocked on
+ * `dpo-signoff`. This concern appends to a local JSONL file and stops.
+ *
+ * Exit code is ALWAYS 0 — malformed envelope, unreadable settings, failed
+ * write, anything. A hook `warn` (exit 2) is read as a hard BLOCK on this
+ * host (recorded trap), and a telemetry concern has nothing to say to the
+ * model, so it never warns either.
+ */
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import * as fs from 'node:fs';
+
+import {
+    read_remote_settings,
+    type RemoteTelemetrySettings,
+} from '../../agent-src/templates/scripts/telemetry/settings.js';
+import {
+    append_class_a_record,
+    build_class_a_record,
+    profile_from_legacy_tier,
+} from '../../agent-src/templates/scripts/telemetry/remote.js';
+import { is_replay_mode } from './state_io.js';
+import { readHookStdin } from './hook_stdin.js';
+
+const EXIT_ALLOW = 0;
+
+/** The tool name Phase 0 spike 1 confirmed for a skill invocation. */
+export const SKILL_TOOL_NAME = 'Skill';
+
+const SETTINGS_FILENAME = '.agent-settings.yml';
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function isObject(v: unknown): v is JsonObject {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/** Unwrap the dispatcher envelope down to the platform-native payload. */
+export function unwrapPayload(envelope: JsonObject): JsonObject {
+    const inner = envelope['payload'];
+    return isObject(inner) ? inner : envelope;
+}
+
+/** Best-effort read of the tool name across host key variants. */
+export function extractToolName(payload: JsonObject): string | null {
+    const v = payload['tool_name'] ?? payload['toolName'] ?? payload['tool'];
+    return typeof v === 'string' && v ? v : null;
+}
+
+/**
+ * The invoked skill's name, off `tool_input.skill`.
+ *
+ * Spike 1 observed this key on 164 of 164 real invocations; the camelCase
+ * variant is accepted for the same reason `extractToolName` accepts one —
+ * host key casing has varied across versions in this tree before.
+ */
+export function extractSkillName(payload: JsonObject): string | null {
+    const input = payload['tool_input'] ?? payload['toolInput'];
+    if (!isObject(input)) return null;
+    const v = input['skill'] ?? input['skill_name'] ?? input['name'];
+    return typeof v === 'string' && v ? v : null;
+}
+
+/** Host id off the dispatcher envelope (`claude`, `augment`, …). */
+export function extractHost(envelope: JsonObject): string | null {
+    const v = envelope['platform'] ?? envelope['host'];
+    return typeof v === 'string' && v ? v : null;
+}
+
+/**
+ * The host session id. Hashed before it is recorded, never stored raw —
+ * it is a high-entropy opaque token that `check_secret_leak` reads as a
+ * candidate credential.
+ */
+export function extractSessionId(envelope: JsonObject, payload: JsonObject): string {
+    for (const source of [envelope, payload]) {
+        const v = source['session_id'] ?? source['sessionId'];
+        if (typeof v === 'string' && v) return v;
+    }
+    return '';
+}
+
+/**
+ * Read one top-level scalar out of the settings text.
+ *
+ * Deliberately a raw line scan rather than a YAML parse: this runs on the
+ * post-tool hot path, both values wanted here are top-level scalars from
+ * closed enums, and `build_class_a_record` rejects anything outside those
+ * enums — so a mis-parse produces a dropped field, never a wrong one.
+ *
+ * Accepts a trailing inline comment, which this file's own settings
+ * template uses heavily (`discipline_profile: essential  # ~3.3x kernel
+ * tokens`); rejecting it would have silently reported "not declared" for a
+ * perfectly ordinary line.
+ */
+function _scalar(settingsText: string, key: string): string | null {
+    const re = new RegExp(`^${key}:[ \\t]*([^#\\r\\n]+?)[ \\t]*(?:#.*)?$`, 'u');
+    for (const line of settingsText.split('\n')) {
+        const m = re.exec(line);
+        if (m && m[1]) {
+            const value = m[1].trim().replace(/^["']|["']$/gu, '');
+            if (!value) return null;
+            // The shipped template carries a placeholder until `install`
+            // fills it in; that is "not yet resolved", not a value.
+            if (value.startsWith('__')) return null;
+            return value;
+        }
+    }
+    return null;
+}
+
+/**
+ * The DECLARED discipline profile — the knob that actually decides which
+ * rule surfaces load.
+ *
+ * The first version of this function read `rule_loading_tier`, and that was
+ * wrong: the settings template calls that key a "legacy knob — superseded by
+ * discipline_profile above", and `resolve_discipline_profile` confirms the
+ * precedence — explicit `discipline_profile` wins outright and the legacy
+ * key is consulted only in its absence. So a default install would have had
+ * a knob recorded that does not decide the thing the field implies.
+ *
+ * The fallback mirrors the resolver's own legacy mapping, which needs no
+ * model id and is therefore safe to reproduce here. What is NOT reproduced
+ * is the resolver's both-absent default (`essential`): recording it would
+ * claim a declaration the install never made. Absent stays `null`, and a
+ * reader applies the documented default themselves.
+ */
+export function extractDisciplineProfile(settingsText: string): string | null {
+    const explicit = _scalar(settingsText, 'discipline_profile');
+    if (explicit !== null) return explicit;
+    return profile_from_legacy_tier(_scalar(settingsText, 'rule_loading_tier'));
+}
+
+/**
+ * Installed package version, from the env the installer sets. Never
+ * fabricated: an install that did not report one records `null`.
+ */
+export function extractPackageVersion(env: NodeJS.ProcessEnv): string | null {
+    const v = env['AGENT_CONFIG_PACKAGE_VERSION'];
+    return typeof v === 'string' && v.trim() ? v.trim() : null;
+}
+
+interface SettingsRead {
+    settings: RemoteTelemetrySettings;
+    text: string;
+    /**
+     * The directory the settings file was found in — the project root, and
+     * the base a relative `output.path` resolves against. NOT the session
+     * cwd: a session started in a subdirectory would otherwise scatter one
+     * log file per directory it happened to start in.
+     */
+    root: string;
+}
+
+/**
+ * Read + memoise the settings for one process. The in-process dispatcher
+ * runs every concern in one `node`, so without this the file would be read
+ * once per concern per tool call.
+ */
+const _settingsCache = new Map<string, SettingsRead>();
+
+/**
+ * Walk up from `start` to the first directory holding a settings file.
+ *
+ * A host may report a session `cwd` inside a subdirectory of the project,
+ * and reading only that directory made the concern silently inactive on a
+ * legitimately enabled install — a failure with no message, which is the
+ * worst shape for a default-off surface. Bounded by the filesystem root, so
+ * it terminates on every path; no hit returns `start` unchanged, and the
+ * settings read then fails closed exactly as before.
+ */
+export function resolveSettingsPath(start: string): string {
+    let dir = path.resolve(start);
+    for (;;) {
+        const candidate = path.join(dir, SETTINGS_FILENAME);
+        try {
+            if (fs.statSync(candidate).isFile()) return candidate;
+        } catch {
+            // Not here — keep walking.
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) return path.join(path.resolve(start), SETTINGS_FILENAME);
+        dir = parent;
+    }
+}
+
+export function readSettingsFor(consumerRoot: string): SettingsRead {
+    const p = resolveSettingsPath(consumerRoot);
+    const cached = _settingsCache.get(p);
+    if (cached !== undefined) return cached;
+
+    let text = '';
+    try {
+        text = fs.readFileSync(p, 'utf-8');
+    } catch {
+        text = '';
+    }
+    const read: SettingsRead = { settings: read_remote_settings(p), text, root: path.dirname(p) };
+    _settingsCache.set(p, read);
+    return read;
+}
+
+/** Test seam — the cache is process-global and tests write real files. */
+export function _resetSettingsCache(): void {
+    _settingsCache.clear();
+}
+
+function processEnvelope(envelope: JsonValue, consumer_root: string): number {
+    try {
+        if (!isObject(envelope)) return EXIT_ALLOW;
+
+        const payload = unwrapPayload(envelope);
+        if (extractToolName(payload) !== SKILL_TOOL_NAME) return EXIT_ALLOW;
+
+        const { settings, text, root } = readSettingsFor(consumer_root);
+        if (!settings.active) return EXIT_ALLOW;
+        if (is_replay_mode()) return EXIT_ALLOW;
+
+        const skill = extractSkillName(payload);
+        if (skill === null) return EXIT_ALLOW;
+
+        const record = build_class_a_record({
+            skill,
+            host: extractHost(envelope),
+            org_id: settings.org_id,
+            salt: settings.salt,
+            hostname: os.hostname(),
+            username: os.userInfo().username,
+            session_id: extractSessionId(envelope, payload),
+            package_version: extractPackageVersion(process.env),
+            discipline_profile: extractDisciplineProfile(text),
+        });
+
+        // Relative to the PROJECT root (the directory holding the settings
+        // file), never to the session cwd — otherwise a session started in a
+        // subdirectory writes its own stray log there.
+        const logPath = path.isAbsolute(settings.log_path)
+            ? settings.log_path
+            : path.join(root, settings.log_path);
+        // The growth budget travels from the settings the install actually
+        // declared, not from the appender's own defaults — a retention key
+        // the write path never reads would be a setting that decorates
+        // rather than decides.
+        append_class_a_record(logPath, record, {
+            max_age_days: settings.retention_max_age_days,
+            max_bytes: settings.retention_max_bytes,
+        });
+    } catch {
+        // Malformed payload, unreadable disk, a rejected id — never block
+        // the tool call, and never write a degraded record.
+        return EXIT_ALLOW;
+    }
+    return EXIT_ALLOW;
+}
+
+export function run(stdin_text: string, options: { consumer_root: string }): number {
+    let envelope: JsonValue;
+    try {
+        const raw = stdin_text.trim();
+        if (!raw) return EXIT_ALLOW;
+        envelope = JSON.parse(raw) as JsonValue;
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return processEnvelope(envelope, options.consumer_root);
+}
+
+export function _resolveRoot(envelope: JsonValue): string {
+    if (isObject(envelope)) {
+        const cwd = envelope['cwd'];
+        if (typeof cwd === 'string' && cwd) return cwd;
+        const pr = envelope['workspace_root'] ?? envelope['project_root'];
+        if (typeof pr === 'string' && pr) return pr;
+    }
+    return process.cwd();
+}
+
+export function main(): number {
+    const raw = readHookStdin();
+    let envelope: JsonValue = {};
+    try {
+        envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+    } catch {
+        return EXIT_ALLOW;
+    }
+    return processEnvelope(envelope, _resolveRoot(envelope));
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) return true;
+    try {
+        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) process.exit(main());

package/src/scripts/hooks/tool_result_bytes_hook.ts

@@ -38,6 +38,15 @@
  * The result is measured, never read: `_resultBytes` computes a length and
  * discards the value in the same expression.
  *
+ * payload-bodies-waiver: result — measured, never read. This concern
+ * deliberately declares NO `needs_payload_bodies` in `hook_manifest.yaml`: the
+ * dispatcher omits the body and passes its exact UTF-8 byte length in the stub,
+ * which is the only thing this file ever wanted. Declaring `result` here would
+ * silently restore the 2 MB payload for the one concern the omission was built
+ * for (`road-to-per-turn-hook-economy` step 2.2), and the census would look
+ * identical while the cost came back. The `RESULT_KEYS` literals below are the
+ * key NAMES this concern looks under, not a read of the body.
+ *
  * ── Always exit 0 ─────────────────────────────────────────────────────
  *
  * A `warn` (exit 2) is read as a hard BLOCK on this host, and this concern
@@ -62,6 +71,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
+import { stubbedBytes } from './payload_stub.js';
 
 const EXIT_ALLOW = 0;
 
@@ -98,11 +108,28 @@ const RESULT_KEYS = ['tool_response', 'toolResponse', 'tool_result', 'toolUseRes
  *
  * Bytes, not characters: a multibyte result costs what it costs on the
  * wire, and `String.length` would under-report it.
+ *
+ * ## The dispatcher may omit the body, and then it passes the length instead
+ *
+ * `road-to-per-turn-hook-economy` step 2.2. This concern declares no
+ * `needs_payload_bodies` in `hook_manifest.yaml` — its own header says the
+ * result is "measured, never read", and that is exactly the concern the
+ * payload opt-in exists for. So the dispatcher replaces the body with a stub
+ * carrying its UTF-8 byte length, computed the same way this function
+ * computes it, and this function reads it back.
+ *
+ * Without the stub branch the census would keep filling — with the ~120-byte
+ * length of the STUB, silently, forever. An instrument that reports a wrong
+ * number is worse than one that reports none, which is why the branch is
+ * first and why `stubbedBytes` distinguishes "omitted, this many bytes" from
+ * "present, measure it".
  */
 export function _resultBytes(payload: JsonObject): number | null {
     for (const key of RESULT_KEYS) {
         const v = payload[key];
         if (v === undefined || v === null) continue;
+        const omitted = stubbedBytes(v);
+        if (omitted !== undefined) return omitted;
         if (typeof v === 'string') return Buffer.byteLength(v, 'utf8');
         try {
             return Buffer.byteLength(JSON.stringify(v), 'utf8');

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -9,7 +9,7 @@
  * is deliberately not another reminder. It is a check at the point of
  * delivery that can say no.
  *
- * Three detectors ride on one guard, because building the unsafe part twice
+ * FOUR detectors ride on one guard, because building the unsafe part twice
  * is how a second detector becomes a second outage:
  *
  *   A — promissory closing  (FC-5, 20 measured occurrences)
@@ -20,6 +20,33 @@
  *                            prose, which is why `readTranscriptTail` collects
  *                            them: `_messageText` keeps `type === 'text'` blocks
  *                            only, so tool activity is invisible to A and B.)
+ *   D — completion claim    (a claim of done carrying no fresh evidence; landed
+ *                            under conformance round 7 § Phase 1.)
+ *
+ * TWO of the four are CONDITIONAL, and saying "unconditional" here would be the
+ * same stale-header defect this block corrects below. A and D are the
+ * completion-adjacent pair an open subagent dispatch excuses, so `main()` runs
+ * them only when `dispatchOpen` is false; B and C run on every turn-end. That
+ * narrowing is deliberate (Phase 3 Step 2, narrowed again by R2 round 2) and is
+ * the third allow path, alongside the two re-entrancy layers — see the
+ * per-detector list in `main()`.
+ *
+ * This block said "Three" and listed A/B/C until 2026-08-18, while `DetectorId`
+ * below has carried four since round 7. `DETECTOR_IDS` in
+ * `_lib/turn_end_refusals.ts` is read off that union rather than off this
+ * comment for exactly that reason, and the count is corrected here rather than
+ * left as a stale header the next reader has to disbelieve.
+ *
+ * ## Removal condition
+ *
+ * This is a BLOCKING concern, so it owes one — see
+ * `docs/contracts/turn-end-detector-demotion.md` for the pre-registered
+ * per-detector bars, their sample floors, and the reason a crossed bar
+ * authorises a staged study rather than a demotion. Two things that contract
+ * says about the guard below are worth meeting here: the re-entrancy layers cap
+ * a turn at ONE refusal, which makes a re-refusal share unobservable and the
+ * three-strikes non-termination valve unreachable. Both are properties of this
+ * design, not gaps in the counters.
  *
  * ## Re-entrancy — the shape, stated before registration
  *
@@ -997,10 +1024,18 @@ export function main(): number {
     );
     if (alreadyRefusedTurn(workspaceRoot, sessionKey, turnOrdinal)) return EXIT_ALLOW;
 
-    // Every detector runs on every turn-end. The gating is INSIDE each one —
-    // no promise, no pin mismatch, no unverified edit ⇒ no finding ⇒ the turn
-    // ends. That is the whole of "fires when it is warranted"; there is no
-    // second, configurable notion of warranted layered on top of it.
+    // B and C run on every turn-end; A and D run only when no dispatch is open
+    // (the ternaries below). For the detectors that DO run, the gating is INSIDE
+    // each one — no promise, no pin mismatch, no unverified edit, no unsettled
+    // completion claim ⇒ no finding ⇒ the turn ends. That is the whole of "fires
+    // when it is warranted"; there is no second, configurable notion of warranted
+    // layered on top of it.
+    //
+    // This said "Every detector runs on every turn-end" and enumerated three of
+    // four, three lines above the two `dispatchOpen` ternaries that refute it.
+    // Corrected 2026-08-19 with the header block at the top of this file: a reader
+    // arriving here met the false claim first, and the D comment below deferred to
+    // "the note at the top of this loop" — which was this sentence.
     const findings: Finding[] = [];
     for (const f of [
         // A and D are the completion-adjacent pair a pending dispatch excuses
@@ -1009,8 +1044,11 @@ export function main(): number {
         dispatchOpen ? null : detectPromissory(lastAssistant),
         detectLanguage(lastAssistant, readLanguagePin(workspaceRoot)),
         detectUnverifiedEdit(toolCalls),
-        // Round 7 § Phase 1 — detector D, in the same unconditional list as the
-        // other three. It shipped with its own settings flag one commit earlier
+        // Round 7 § Phase 1 — detector D. It is NOT unconditional, and this
+        // comment said it was while sitting one line above the `dispatchOpen`
+        // ternary that conditions it: A and D are both excused by an open
+        // dispatch, per the note at the top of this loop. Corrected 2026-08-18.
+        // It shipped with its own settings flag one commit earlier
         // and that flag is gone: `hooks.turn_end_gate.*` was deleted on
         // 2026-08-12 because a default-off safety gate is an absent one. Its
         // gating is where the comment above says gating belongs — inside the

package/src/scripts/hooks_doctor.ts

@@ -31,7 +31,10 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { read_dispatch_issues } from "./hooks/dispatch_issues.js";
+import {
+  POLICY_OUTCOME_ISSUES,
+  read_dispatch_issues,
+} from "./hooks/dispatch_issues.js";
 import { type JsonObject, type JsonValue, _load_yaml } from "./hooks/dispatch_hook.js";
 import * as hooks_status from "./hooks_status.js";
 import {
@@ -240,9 +243,20 @@ export function collect(
 
   // Phase 1 of road-to-hooks-actually-fire-in-consumers: surface
   // the dispatch-issues log so users see hooks that tried and failed.
+  //
+  // POLICY OUTCOMES ARE FILTERED OUT, and the filter is the point: this view
+  // means "a hook tried to fire and couldn't", and its CTA is a reinstall. The
+  // two emission-shaping codes mean the opposite — the concern ran correctly and
+  // the dispatcher chose not to emit it — so they are neither a failure nor
+  // fixable by reinstalling. They fire as a routine per-dispatch outcome, so
+  // leaving them in would let normal traffic push a real `script_not_found` out
+  // of the last-20 window. They stay in the log, which is where the "why did
+  // that advisory not appear" question is answered. (R2 review, 2026-08-19.)
   let issues: JsonObject[] = [];
   try {
-    issues = read_dispatch_issues(REPO_ROOT).slice(-20) as unknown as JsonObject[];
+    issues = read_dispatch_issues(REPO_ROOT)
+      .filter((e) => !POLICY_OUTCOME_ISSUES.has(String(e["issue"])))
+      .slice(-20) as unknown as JsonObject[];
   } catch {
     issues = [];
   }