@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/hooks/concern_timings.ts

@@ -0,0 +1,94 @@
+import fs from "node:fs";
+
+/**
+ * concern_timings — the per-concern latency sink the bench reads.
+ *
+ * Step 3.2 of `road-to-a-kernel-that-guards-its-plumbing`. The dispatcher has
+ * always timed each concern — `_run_concern` returns a duration and the
+ * feedback record carries it — but nothing could READ that distribution: the
+ * feedback dir keeps one file per concern and every dispatch OVERWRITES it, so
+ * the only survivor is the last run. A p95 needs every sample, and the bench
+ * harness that produces the samples runs with `AGENT_CONFIG_REPLAY=1`, where
+ * the feedback write returns before writing anything at all.
+ *
+ * So this sink is separate from the feedback dir on purpose, and deliberately
+ * not derived from it:
+ *
+ * - it APPENDS, so N runs leave N samples rather than one;
+ * - it is written in replay mode, because the measurement harness is the
+ *   caller that needs it;
+ * - it is off unless the variable is set, so the cost on a real dispatch is
+ *   one `process.env` lookup.
+ *
+ * It carries a concern name, an integer, an event and a platform. There is no
+ * field that can hold a payload, a path or a prompt — the same shape-level
+ * privacy floor `payload_stubs` keeps one row up.
+ *
+ * It lives in its own file rather than inside `dispatch_hook.ts` because that
+ * file sits against the 1,500-line source budget, and `check_source_size_budget`
+ * refused the inline version.
+ */
+
+/** Environment variable naming the JSONL sink. Registered in the kill-switch table. */
+export const TIMINGS_SINK_ENV = "AGENT_CONFIG_HOOK_TIMINGS";
+
+/**
+ * One measurement.
+ *
+ * MICROseconds, not milliseconds. The dispatcher's `duration_ms` is floored,
+ * and since the in-process fast path landed every registry concern finishes in
+ * well under a millisecond — so the floored field reads exactly `0` for all of
+ * them. That was invisible while nothing consumed the number and stops being
+ * invisible the moment a p95 is reported and a timeout derived from it.
+ */
+export interface ConcernTimingSample {
+  concern: string;
+  duration_us: number;
+}
+
+/**
+ * Append one JSONL row per concern, when the sink is armed.
+ *
+ * Never throws and never blocks the dispatch: a measurement sink that can fail
+ * a hook would be a new way for the plumbing to refuse, which is the opposite
+ * of what this roadmap is for.
+ */
+export function writeConcernTimings(
+  event: string,
+  platform: string,
+  samples: readonly ConcernTimingSample[],
+  sinkPath: string | undefined = process.env[TIMINGS_SINK_ENV],
+): void {
+  if (!sinkPath) {
+    return;
+  }
+  try {
+    const lines: string[] = [];
+    for (const sample of samples) {
+      // A concern the dispatcher never timed is OMITTED rather than recorded
+      // as 0. A zero here would read as "instantaneous" and would be
+      // indistinguishable from a real sub-millisecond run — the exact
+      // substitution the report's `not_measured` requirement forbids one layer
+      // up, reintroduced at the source instead of at the report.
+      if (!Number.isFinite(sample.duration_us)) {
+        continue;
+      }
+      lines.push(
+        JSON.stringify({
+          concern: sample.concern,
+          // Rounded HERE rather than at the call site: the caller holds a
+          // float millisecond reading and the sink is the one place that has
+          // to decide the recorded unit.
+          duration_us: Math.round(sample.duration_us),
+          event,
+          platform,
+        }),
+      );
+    }
+    if (lines.length > 0) {
+      fs.appendFileSync(sinkPath, lines.join("\n") + "\n", "utf-8");
+    }
+  } catch {
+    // Non-fatal by construction — see the header.
+  }
+}

package/src/scripts/hooks/delegation_nudge_hook.ts

@@ -102,15 +102,14 @@ import { classifyLadder, type LadderRung } from "../_lib/judgment_ladder.js";
 import { resolveSessionRole } from "../_lib/session_role.js";
 import { resolveSubagentRouting, type Tier } from "../_lib/subagent_routing.js";
 import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 // Severity is taken from the EXIT CODE, not from the `decision` field in the
 // stdout payload — mirrors `language_mirror_hook.ts`'s own note (found the
 // same way: by tracing delivery, not by re-reading the unit tests). A warn
 // verdict is reported at exit 2 so `host_semantics.emitFor` reduces it to
 // severity `"warn"` and forwards `additional_context`; see the file header
 // for why this exit code never actually blocks the turn.
-const EXIT_WARN = 2;
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
 type JsonObject = { [k: string]: JsonValue };

package/src/scripts/hooks/design_pass_hook.ts

@@ -57,12 +57,13 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { appendDischarge, stamp } from '../_lib/obligations.js';
+import { compareInputs } from '../_lib/probe_inputs.js';
+import { trigger_matches, type Trigger } from '../_lib/router_match.js';
 import { isUiPath, isUiTreePath } from '../_lib/ui_surface.js';
 import { loadDesignContext, scanFile } from '../lint_design_slop.js';
 import { readHookStdin } from './hook_stdin.js';
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
-const EXIT_WARN = 2;
 const SETTINGS_FILE = '.agent-settings.yml';
 const STATE_REL = path.join('agents', 'runtime', 'state', 'design-pass-hook.json');
 const AUDIT_REL = path.join('agents', 'runtime', 'state', 'ui-audit.json');
@@ -150,27 +151,94 @@ export interface ConformanceVerdict {
      * write is the noise that gets a carrier switched off — Risk 1 of the parent
      * roadmap. Absent is still reported honestly whenever the pass speaks for
      * another reason.
+     *
+     * The ONE exception is a turn that actually touched a provided design
+     * handover. There, the probe is the evidence the turn was supposed to
+     * produce, and its absence is the noteworthy kind.
      */
     noteworthy: boolean;
     line: string;
 }
 
-export function conformanceVerdict(root: string): ConformanceVerdict {
+export interface ConformanceOptions {
+    /**
+     * Whether a provided design handover was among the files this turn wrote.
+     * Decided by `handoverTouched` from the shipped routing triggers, never by a
+     * matcher invented here.
+     */
+    handoverDetected?: boolean;
+}
+
+/**
+ * The file-based half of `src/rules/design-fidelity.md`'s `triggers:` set — the
+ * shipped answer to "is this file a provided design handover?".
+ *
+ * COPIED AS A CONSTANT, MATCHED BY THE SHIPPED MATCHER. Reading and parsing the
+ * rule's frontmatter here would put a YAML load on `post_tool_use`, the hottest
+ * slot this concern binds, and would depend on a rule path that differs between
+ * this repository and an installed consumer. The drift that a constant invites
+ * is closed by a test instead: `design_pass.test.ts` asserts this list equals the
+ * rule's file-based triggers in BOTH directions, so a trigger added to the rule
+ * and not here fails CI.
+ *
+ * THE HONEST REACH. Only the two HTML patterns are reachable through this
+ * carrier. `.claude/design-system/` names JSON and token files, which
+ * `isUiSurface` does not admit, so `main` returns before the verdict is
+ * computed. Widening `isUiSurface` to admit them would change the UI-turn
+ * denominator that the consultation-rate measurement is defined against, which
+ * is a different decision than this one. The prefix stays for parity with the
+ * rule and is stated as unreachable rather than quietly dropped.
+ */
+export const HANDOVER_TRIGGERS: readonly Trigger[] = [
+    { file_pattern: '*design.html' },
+    { file_pattern: '*.dc.html' },
+    { path_prefix: '.claude/design-system/' },
+];
+
+/** True when any of the paths this turn wrote is a provided design handover. */
+export function handoverTouched(paths: readonly string[]): boolean {
+    if (!paths.length) return false;
+    return HANDOVER_TRIGGERS.some((t) => trigger_matches(t, '', paths, null));
+}
+
+export function conformanceVerdict(root: string, opts: ConformanceOptions = {}): ConformanceVerdict {
     let raw: string;
     try {
         raw = fs.readFileSync(path.join(root, CONFORMANCE_REL), 'utf-8');
     } catch {
-        return {
-            noteworthy: false,
-            line: 'ui-conformance: absent — no probe artefact for this change (run `ui_conformance_probe --target <file> --reference <file>`). Absent is not clean.',
-        };
+        const base =
+            'ui-conformance: absent — no probe artefact for this change (run `ui_conformance_probe --target <file> --reference <file>`). Absent is not clean.';
+        return opts.handoverDetected
+            ? {
+                  noteworthy: true,
+                  line: `${base} A provided design handover was touched this turn, so this is the absence worth naming.`,
+              }
+            : { noteworthy: false, line: base };
     }
     try {
         const a = JSON.parse(raw) as {
             structure_gate?: string;
+            inputs?: unknown;
             dimensions?: { dimension: string; status: string; findings: number | null; reason?: string }[];
-            findings?: unknown[];
+            findings?: { dimension?: string; probe_id?: string; expected?: string; observed?: string }[];
         };
+
+        // Before anything is counted. A finding count measured against inputs
+        // that have since moved is the misleading half of a stale artefact, so
+        // the count is withheld rather than printed beside a warning.
+        const inputs = compareInputs(a.inputs, (p) => (path.isAbsolute(p) ? p : path.join(root, p)));
+        if (inputs.verdict === 'moved') {
+            return {
+                noteworthy: true,
+                line: [
+                    `ui-conformance: stale — ${inputs.moved.join(', ')} changed since the probe ran, so its findings ` +
+                        'describe inputs that no longer exist. The count is withheld rather than reported against ' +
+                        'them; re-run `ui_conformance_probe --target <file> --reference <file>`.',
+                    '  (shadow verdict: reported, never enforced — this pass does not block on it)',
+                ].join('\n'),
+            };
+        }
+
         const rows = a.dimensions ?? [];
         const exercised = rows.filter((r) => r.status === 'exercised');
         const notApplicable = rows.filter((r) => r.status !== 'exercised');
@@ -188,6 +256,29 @@ export function conformanceVerdict(root: string): ConformanceVerdict {
         if (a.structure_gate === 'stopped') {
             parts.push('  · structure gate stopped on at least one node — style comparison was skipped for it');
         }
+        // The added-element half. This line already said "Absent is not clean"
+        // about a missing artefact; the probe's structure dimension could only
+        // ever show the omit half of "never omit or add an element", so this is
+        // the one number the verdict could not print. Derived from the findings
+        // the probe already writes — no new artefact field is read.
+        const addedElements = (a.findings ?? []).filter(
+            (f) => f.dimension === 'structure' && f.expected === 'absent' && f.observed === 'present',
+        );
+        if (addedElements.length) {
+            parts.push(
+                `  · ${addedElements.length} element(s) present in the target and absent from the reference: ` +
+                    `${addedElements.map((f) => f.probe_id ?? '?').join(', ')} — added, not ported`,
+            );
+        }
+        parts.push(
+            inputs.verdict === 'unchanged'
+                ? '  · inputs: unchanged since the probe ran'
+                : // Unknown is a version skew, not evidence of movement — and
+                  // equally not evidence of freshness. Saying so is the whole
+                  // point: an artefact from before the digests existed must read
+                  // neither stale nor fresh.
+                  `  · inputs: unknown — ${inputs.reason}`,
+        );
         parts.push('  (shadow verdict: reported, never enforced — this pass does not block on it)');
         return {
             noteworthy: (a.findings ?? []).length > 0 || a.structure_gate === 'stopped' || notApplicable.length > 0,
@@ -456,7 +547,7 @@ function main(): number {
     // be silent — a behavioural finding is exactly the thing no static scan can
     // see — but it cannot make it refuse. `result.blocked` above is computed
     // without it and the exit code below is unchanged.
-    const conformance = conformanceVerdict(root);
+    const conformance = conformanceVerdict(root, { handoverDetected: handoverTouched(targets) });
 
     if (
         !result.findings.length &&

package/src/scripts/hooks/design_slop_hook.ts

@@ -26,10 +26,9 @@ import { type DesignContext } from "../design_slop_rules.js";
 import { UI_EXT } from "../_lib/ui_surface.js";
 import { loadDesignContext, scanFile } from "../lint_design_slop.js";
 import { readHookStdin } from "./hook_stdin.js";
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
 const SETTINGS_FILE = ".agent-settings.yml";
-const EXIT_ALLOW = 0;
-const EXIT_WARN = 2;
 const DEGRADE_AFTER = 3; // surfaces of the same file::rule signature before going silent
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };

package/src/scripts/hooks/dispatch_hook.ts

@@ -12,7 +12,7 @@
  * Per `docs/contracts/hook-architecture-v1.md`. Reads `src/scripts/hook_manifest.yaml`,
  * resolves which concerns fire on the given (platform, event) tuple, and runs each
  * sequentially with the stdin envelope contract. Reduces concern exit codes per the
- * spec (0=allow, 1=block, 2=warn, ≥3=error → fail-open unless concern is fail_closed).
+ * spec (0=allow, 1=block, 2=warn, ≥3=error → resolved by declared `severity`).
  *
  * Invocation:
  *
@@ -34,6 +34,10 @@ import * as tty from "node:tty";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 
+import { runBundleIntegrityGate } from "./bundle_integrity.js";
+import { writeConcernTimings, type ConcernTimingSample } from "./concern_timings.js";
+import { tableFingerprint } from "./table_fingerprint.js";
+
 import { hardenedSpawnEnv } from "../_lib/spawn_env.js";
 import {
   atomic_write_json,
@@ -55,10 +59,19 @@ import { _concern_body_classes, planPayloadShapes } from "./payload_stub.js";
 import { resolveSessionRole, type SessionRole } from "../_lib/session_role.js";
 import { stdinReadFailure, denyOnStdinFailure } from './stdin_failure_policy.js';
 export { stdinReadFailure, denyOnStdinFailure, _is_fail_closed_blocking } from './stdin_failure_policy.js';
+// Severity policy — what a declaration means when the concern said nothing.
+// Re-exported so the move out of this file left every importer unaffected.
+import {
+  _is_advisory, _is_blocking, _resolve_execution_failure,
+  classifySpawnResult, noVerdictRefusalNotice, SPAWN_TIMEOUT_MS,
+} from './concern_failure_policy.js';
+export { _is_advisory, _is_blocking, _resolve_execution_failure };
 import { _py_json_dumps } from './py_json_dumps.js';
 import { _fallback_yaml } from './fallback_yaml.js';
 import { detectSurface } from '../_lib/surface.js';
 import { recordCapture, recordOpportunity } from "../_lib/collector_denominator.js";
+import { EXIT_ALLOW, EXIT_BLOCK, EXIT_WARN, EXIT_USAGE } from './exit_codes.js';
+export { EXIT_ALLOW, EXIT_BLOCK, EXIT_WARN };
 export { _fallback_yaml } from './fallback_yaml.js';
 
 // Free-form JSON values flow through every helper here; a documented
@@ -84,10 +97,6 @@ const REPO_ROOT = path.resolve(
 );
 const MANIFEST_PATH = path.join(REPO_ROOT, "src", "scripts", "hook_manifest.yaml");
 
-export const EXIT_ALLOW = 0;
-export const EXIT_BLOCK = 1;
-export const EXIT_WARN = 2;
-
 // Per Council Round 2 (Q3): `agent_error` covers agent-level crashes
 // that are not concern-triggered, so chat-history can checkpoint
 // partial sessions on abnormal exit.
@@ -126,18 +135,6 @@ export function _severity_for(rc: number): string {
   return _SEVERITY_BY_EXIT[rc] ?? "error";
 }
 
-/**
- * P0.2 (road-to-rule-coherence) — is this concern declared advisory?
- *
- * An advisory concern MUST never produce a BLOCK verdict on any host. Four
- * PreToolUse concerns document themselves as advisory in prose
- * (`design_slop_hook`: "FLAGS, NEVER A BLOCK") while the transport happily
- * turned their WARN into a host-level deny. Prose is not enforcement: the
- * manifest now declares severity and the dispatcher enforces the ceiling.
- */
-export function _is_advisory(concern: JsonObject): boolean {
-  return String(concern["severity"] ?? "").trim().toLowerCase() === "advisory";
-}
 
 function _now_iso(): string {
   // Python: datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ").
@@ -196,37 +193,25 @@ export function _parse_concern_stdout(stdout_text: string): JsonObject {
  * path (`yaml.safe_load(text) or {}`); version 1.1 matches PyYAML.safe_load.
  */
 /**
- * Cheap content fingerprint of a manifest source — FNV-1a 32-bit plus the byte
- * length, hex.
+ * Content fingerprint of a manifest source — delegated to `tableFingerprint`,
+ * which owns the algorithm and the measurement.
  *
- * Deliberately NOT a crypto hash: `require('node:crypto')` costs 8 ms of
- * process start, which is most of what the precompiled manifest exists to
- * save. This runs in about 0.2 ms over 61 kB and only has to detect an edited
- * source, not resist an adversary — a wrong answer costs the slow path, never
- * correctness.
+ * road-to-blocking-severities 3.1: this comment used to argue against a crypto
+ * hash for a function that already used one. The retired argument and the
+ * numbers that retired it live there now.
  */
 export function _manifest_fingerprint(text: string): string {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < text.length; i += 1) {
-    h ^= text.charCodeAt(i);
-    h = Math.imul(h, 0x01000193) >>> 0;
-  }
-  return `${h.toString(16)}:${String(text.length)}`;
+  return tableFingerprint(text);
 }
 
 export function _load_yaml(p: string): JsonObject {
-  // Precompiled fast path. The manifest is ~61 kB of YAML and is parsed on
-  // EVERY dispatch, which measured 12 ms of a ~103 ms dispatch (plus 8 ms to
-  // load the `yaml` module itself). The sibling `.json` is the same data with
-  // comments stripped — 14.7 kB — and JSON.parse of it is sub-millisecond.
+  // Precompiled fast path. The manifest is ~61 kB of YAML parsed on EVERY
+  // dispatch — 12 ms of a ~103 ms dispatch, plus 8 ms to load the `yaml` module
+  // itself. The sibling `.json` is the same data with comments stripped,
+  // 14.7 kB, and JSON.parse of it is sub-millisecond.
   //
-  // Freshness is decided by the SOURCE CONTENT, not by mtime. The first version
-  // of this compared mtimes and that was a measured defect, not a theoretical
-  // one: on a fresh `actions/checkout` both files get the checkout timestamp in
-  // whatever order git wrote them, so whether the optimisation applied at all
-  // was a coin flip. It won on the PR (p95 129 ms) and lost on the trunk
-  // (p95 186 ms) for the same commit. A fingerprint is deterministic wherever
-  // the tree came from.
+  // Freshness is SOURCE CONTENT, never mtime — the measured defect behind that
+  // is in `table_fingerprint.ts`, told once rather than in all three readers.
   //
   // Reading the YAML unconditionally costs ~0 ms (it is the PARSE that is
   // expensive), so the fast path still skips ~20 ms.
@@ -238,7 +223,14 @@ export function _load_yaml(p: string): JsonObject {
       if (
         _isObject(raw) &&
         raw["fingerprint"] === _manifest_fingerprint(text) &&
-        _isObject(raw["manifest"])
+        _isObject(raw["manifest"]) &&
+        // road-to-blocking-severities 2.3, the manifest twin of the check in
+        // `host_lowering.resolveTable`, which carries the full reasoning. In
+        // one line: the label above binds this file to the YAML SOURCE and says
+        // nothing about the body underneath, so an edited `manifest` body with
+        // an untouched label was served — on the table that decides which
+        // concern runs on which slot at all. Absent field → fall through.
+        raw["body_fingerprint"] === _manifest_fingerprint(JSON.stringify(raw["manifest"]))
       ) {
         return raw["manifest"];
       }
@@ -251,12 +243,10 @@ export function _load_yaml(p: string): JsonObject {
   return _isObject(data) ? data : {};
 }
 
-
 interface ConcernDef extends JsonObject {
   name: string;
 }
 
-
 /**
  * Per-concern tool filter — the `tools:` key.
  *
@@ -424,7 +414,6 @@ export function _resolve_concerns(
   return out;
 }
 
-
 /**
  * Write the raw stdin payload to a capture directory when
  * `AGENT_HOOK_CAPTURE_DIR` is set. Fail-silent: any IO / JSON error must
@@ -506,6 +495,7 @@ interface RunResult {
   rc: number;
   stderr: string;
   stdout: string;
+  /** Elapsed ms, NOT floored — floored where STORED. See `concern_timings.ts`. */
   duration_ms: number;
 }
 
@@ -570,10 +560,10 @@ function _resolve_tsx_invocation(
  * Escape hatch: AGENT_CONFIG_HOOKS_ISOLATED=1 forces the historical
  * spawn-per-concern path (also used by the bench harness for A/B numbers).
  *
- * Known trade-off vs the spawn path: the 30 s kill-timeout cannot preempt
- * in-process synchronous code. Concerns are repo-owned, budget-capped and
- * fail-open; the latency budget gate (hook-latency-budget.json) is the
- * standing regression net.
+ * Known trade-off vs the spawn path: a kill-timeout cannot preempt in-process
+ * synchronous code, so a slow concern is bounded on neither route — see
+ * `SPAWN_TIMEOUT_MS`. A CRASH is caught here, surfaces as rc 3, and the caller
+ * resolves it by declared severity.
  */
 /**
  * ## Why this still re-serialises the envelope per concern (step 1.1, MEASURED NULL)
@@ -680,10 +670,10 @@ function _run_concern_inproc(
     }
     clearHookStdinOverride();
   }
-  const elapsed = Math.floor(performance.now() - started);
-  return { rc, stderr: err, stdout: out, duration_ms: elapsed };
+  return { rc, stderr: err, stdout: out, duration_ms: performance.now() - started };
 }
 
+
 function _run_concern(concern: ConcernDef, envelope: JsonObject): RunResult {
   // In-process fast path — the default whenever the concern is in the
   // static registry (all manifest concerns; parity is CI-enforced).
@@ -734,31 +724,31 @@ function _run_concern(concern: ConcernDef, envelope: JsonObject): RunResult {
     encoding: "utf-8",
     cwd: workspace,
     env: concern_env,
-    timeout: 30000,
+    timeout: SPAWN_TIMEOUT_MS, // historical bound; `SPAWN_TIMEOUT_MS` says why
   });
-  const elapsed = Math.floor(performance.now() - started);
-  if (proc.error) {
-    // OSError / timeout equivalent — log execution-failed so the
-    // never-block contract keeps a trace.
-    const err = proc.error as NodeJS.ErrnoException;
-    const typeName =
-      err.code === "ETIMEDOUT" ? "TimeoutExpired" : err.name || "OSError";
+  const elapsed = performance.now() - started;
+  // Three ways a spawn produces no verdict; `classifySpawnResult` owns the
+  // reading, this writes the record and carries the code.
+  const outcome = classifySpawnResult(proc.error, proc.status, proc.signal);
+  if (outcome.issueDetail !== null) {
     log_dispatch_issue(
       workspace,
       String(concern["name"] || "unknown"),
       "execution_failed",
-      `${typeName}: ${err.message}`,
+      outcome.issueDetail,
       fix_hint(),
     );
+  }
+  if (outcome.noVerdict) {
     return {
-      rc: 3,
-      stderr: `${String(concern["name"])}: ${err.message}`,
+      rc: outcome.rc,
+      stderr: `${String(concern["name"])}: ${String(outcome.stderrNote)}\n${proc.stderr || ""}`,
       stdout: "",
       duration_ms: elapsed,
     };
   }
   return {
-    rc: proc.status ?? 0,
+    rc: outcome.rc,
     stderr: proc.stderr || "",
     stdout: proc.stdout || "",
     duration_ms: elapsed,
@@ -796,6 +786,7 @@ interface FeedbackEntry extends JsonObject {
   concern: string;
 }
 
+
 /**
  * Write per-concern feedback files + summary rollup.
  *
@@ -1064,7 +1055,7 @@ function _parse_args(argv: string[]): Args {
     process.stderr.write(
       `dispatch_hook: the following arguments are required: ${missing.join(", ")}\n`,
     );
-    process.exit(2);
+    process.exit(EXIT_USAGE);
   }
   return args;
 }
@@ -1251,6 +1242,15 @@ export function main(argv?: string[]): number {
     }
   }
 
+  // Step 3.1 — the bundle we execute must be the bundle the build produced.
+  // Beside `denyOnStdinFailure` for its reason: the verdict needs the resolved
+  // concern list. Rules: `bundle_integrity.ts`.
+  if (_IN_BUNDLE) {
+    const stop = runBundleIntegrityGate(fileURLToPath(import.meta.url), args.platform,
+      args.event, concerns.some((c) => !_is_advisory(c)));
+    if (stop !== null) return stop;
+  }
+
   const envelope = _build_envelope(args, payload_text);
   const session_id = _resolve_session_id(envelope);
   const started_at = _now_iso();
@@ -1286,6 +1286,7 @@ export function main(argv?: string[]): number {
   // classes are present, which any concern loses, the single measurement pass,
   // and the at-most-four envelope shapes — so the loop below reads a shape
   // rather than re-deriving one. Rationale and cost model: payload_stub.ts.
+  const timing_samples: ConcernTimingSample[] = [];
   const keep_by_concern = concerns.map(
     (c) => [c, _concern_body_classes(c)] as const,
   );
@@ -1308,17 +1309,22 @@ export function main(argv?: string[]): number {
     const concern_started = _now_iso();
     const { rc: rawRcResult, stderr: stderr_text, stdout: stdout_text, duration_ms } =
       _run_concern(concern, concern_envelope);
+    timing_samples.push({ concern: String(concern["name"]), duration_us: duration_ms * 1000 });
     let rc = rawRcResult;
     const raw_rc = rc;
     if (rc >= 3) {
-      if (!concern["fail_closed"]) {
-        rc = EXIT_ALLOW; // fail-open
-      } else {
-        rc = EXIT_BLOCK;
-      }
+      // Resolved by DECLARED SEVERITY, no longer by `fail_closed:`. Every
+      // crash path has already written an `execution_failed` row, so a refusal
+      // here is traceable to a named failure. See `_resolve_execution_failure`.
+      rc = _resolve_execution_failure(concern, refusal_retry);
       if (stderr_text) {
         process.stderr.write(stderr_text);
       }
+      // The escape, printed only where a denial can repeat — `stop` is bounded
+      // by the one-retry clause above. Reasoning: `noVerdictRefusalNotice`.
+      if (rc === EXIT_BLOCK && !refusal_retry) {
+        process.stderr.write(noVerdictRefusalNotice(String(concern["name"])));
+      }
     }
     // P0.2 severity ceiling: an advisory concern can never block, on any host.
     // This covers BOTH the concern emitting EXIT_BLOCK directly and the
@@ -1376,7 +1382,7 @@ export function main(argv?: string[]): number {
       severity: _severity_for(rc),
       decision: (reply["decision"] || _severity_for(rc)) as JsonValue,
       reason: (reply["reason"] ?? null) as JsonValue,
-      duration_ms,
+      duration_ms: Math.floor(duration_ms),
       started_at: concern_started,
       completed_at: _now_iso(),
       fail_closed: Boolean(concern["fail_closed"]),
@@ -1392,6 +1398,7 @@ export function main(argv?: string[]): number {
     });
   }
   const final_rc = _reduce(rcs);
+  writeConcernTimings(String(envelope["event"] ?? ""), String(envelope["platform"] ?? ""), timing_samples);
   _write_feedback(envelope, session_id, feedback_entries, final_rc, started_at);
   _record_rule_trips(envelope, feedback_entries);
   if (context_blocks.length > 0 && final_rc === EXIT_ALLOW) {
@@ -1459,7 +1466,6 @@ function _sortedRepr(s: ReadonlySet<string>): string {
  */
 let _stdin_read_failed: string | null = null;
 
-
 // Bundle-safety: never auto-run when inlined into an esbuild bundle, where
 // every module shares the bundle's `import.meta.url` (declare at top of file).
 function _isCliEntry(): boolean {

package/src/scripts/hooks/edit_shape_hook.ts

@@ -86,11 +86,10 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { unwrap, type JsonObject, type JsonValue } from './envelope.js';
 import { readHookStdin } from './hook_stdin.js';
 import { atomic_write_json } from './state_io.js';
+import { EXIT_ALLOW, EXIT_WARN } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 // Severity is taken from the EXIT CODE, not from the `decision` field in the
 // stdout payload — see the file header for why this never blocks on `claude`.
-const EXIT_WARN = 2;
 
 /** Committed threshold (roadmap 5.1): minimum current line count of the
  *  replaced file before this concern has anything to say. */

package/src/scripts/hooks/end_review_nudge_hook.ts

@@ -253,6 +253,7 @@ import {
 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';
+import { EXIT_WARN } from './exit_codes.js';
 
 /** Default fire threshold — the council's high-risk shape (roadmap 5.1). */
 export const MUTATION_LINE_THRESHOLD = 50;
@@ -319,7 +320,6 @@ export function isSafeTranscriptPath(
 // reported at exit 2 so `host_semantics.emitFor` reduces it to severity
 // `"warn"` and forwards `additional_context`; see the file header for why
 // this exit code never actually blocks the turn on `claude`.
-const EXIT_WARN = 2;
 
 /** One `git diff --numstat` row: added/deleted line counts + the path. */
 export interface NumstatRow {

package/src/scripts/hooks/evidence_independence.ts

@@ -52,8 +52,8 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { atomic_write_json } from "./state_io.js";
 import { readHookStdin } from "./hook_stdin.js";
 import { isCodePath, isTestPath } from "../_lib/test_delta.js";
+import { EXIT_ALLOW, EXIT_BLOCK } from './exit_codes.js';
 
-const EXIT_ALLOW = 0;
 // MUST equal dispatch_hook.EXIT_BLOCK. The dispatcher's internal ladder is
 // 0 allow / 1 block / 2 warn — NOT the 2-means-block shape a PreToolUse guard
 // reads naturally from Claude's own native contract. This constant was 2 when
@@ -61,7 +61,6 @@ const EXIT_ALLOW = 0;
 // and the gate emitted advisory context while the operation went through.
 // Pinned against the dispatcher's export by
 // tests/hooks/concern_block_exit_parity.test.ts.
-const EXIT_BLOCK = 1;
 
 export const STATE_FILE = path.join("agents", "state", "evidence-dispatch.json");