@event4u/agent-config 16.1.0 → 16.3.0

package/src/scripts/before_complete_hook.ts

@@ -62,8 +62,19 @@ import {
   prune_stale_session_states,
   session_state_file,
   update_json_under_lock,
+  owns_session_state,
 } from "./hooks/state_io.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
+import { hookSectionValue } from "./_lib/hook_settings.js";
+import { isVerificationCommand, mightBeVerification } from "./_lib/verification_command.js";
+import {
+  advisoryLine,
+  runTouchedFileQuality,
+  touchedFilesAtStop,
+  type QualityRun,
+} from "./_lib/touched_file_quality.js";
+import { runnerOf } from "./_lib/verification_evidence.js";
+import { resolve_toolchain } from "../agent-src/templates/scripts/work_engine/stack/runner.js";
 
 // NOTE: the Python docstring says `agents/runtime/state/`, but the code
 // constant is `agents/state/`. Replicated verbatim — latent docstring/code
@@ -144,28 +155,6 @@ export const COMMAND_TOOLS: ReadonlySet<string> = new Set([
   "RunShellCommand", // Cursor
 ]);
 
-// Permissive verification-command pattern. Observability — false positives
-// are cheaper than false negatives. Word-boundary anchored on common
-// shell separators so chained commands (`task sync && task ci`) match.
-//
-// Python re flags: IGNORECASE. The pattern uses no Python-specific syntax;
-// it ports verbatim. The leading `(?:^|[\s;&|`(])` class includes backtick.
-const _VERIFICATION_RE = new RegExp(
-  "(?:^|[\\s;&|`(])(" +
-    "task\\s+(?:ci|test|tests|lint|check|qa|phpstan|rector|ecs|pest|pytest)" +
-    "|(?:\\./|\\.venv/bin/|vendor/bin/)?(?:pest|phpunit|phpstan|psalm|rector|ecs)\\b" +
-    "|(?:python3?|\\.venv/bin/python3?)\\s+-m\\s+pytest" +
-    "|pytest\\b" +
-    "|(?:npm|pnpm|yarn|bun)\\s+(?:run\\s+)?(?:test|check|lint|typecheck|tsc)" +
-    "|cargo\\s+(?:test|check|clippy)" +
-    "|go\\s+test" +
-    "|make\\s+(?:test|check|lint)" +
-    "|composer\\s+(?:test|check|lint|phpstan)" +
-    "|(?:php\\s+)?artisan\\s+test" +
-    ")",
-  "i",
-);
-
 type StateDict = Record<string, unknown>;
 
 /** Python datetime.now(timezone.utc).isoformat(timespec="seconds"). */
@@ -193,10 +182,92 @@ function _empty_state(): StateDict {
     // has to survive it: the measured failure is a completion claim in a LATER
     // turn than the poll it rests on.
     ci_last: null,
+    // Round 8 — see `_reset_turn`. Present in the empty state so a freshly
+    // created file has the same shape as one that has seen a turn boundary;
+    // a reader must never have to distinguish "no runs yet" from "key absent".
+    verification_runs: [],
+    edits_this_turn: 0,
+    // NOTE — `quality_runs` and `quality_files_source` are deliberately ABSENT
+    // here, against the convention `verification_runs` above follows.
+    //
+    // That convention ("present in the empty state so a reader never has to tell
+    // 'no runs yet' from 'key absent'") is the right default and it loses to a
+    // stronger one: the roadmap's first acceptance criterion is that with
+    // `touched_file_quality: off` the record is BYTE-IDENTICAL to the base ref.
+    // Seeding two keys would break that for every install that never opted in,
+    // and "the default-off feature changed my state file" is exactly the kind of
+    // silent shape drift a consumer cannot audit. The convention's cost here is
+    // zero, because the only reader of these keys is 2.1's analysis, which counts
+    // stops — and a stop with no key is a stop where the pass did not run, which
+    // is a distinction it needs rather than one it must not make.
     checked_at: _now(),
   };
 }
 
+/** The three values `hooks.verify_before_complete.touched_file_quality` may take. */
+export type TouchedFileQualityMode = "off" | "shadow" | "warn";
+
+/**
+ * The configured mode, defaulting to `off`.
+ *
+ * FAIL-CLOSED ON THE FLAG, FAIL-OPEN ON THE READ, exactly as
+ * `hookSectionEnabled` does: an unreadable settings file, a missing key, or a
+ * value outside the enum all resolve to `off`. A typo must never turn a pass
+ * ON — `warn` emits a line the operator did not ask for, and `shadow` spawns
+ * processes, so an unrecognised string is the one case where guessing is
+ * strictly worse than doing nothing.
+ */
+export function readTouchedFileQualityMode(consumer_root: string): TouchedFileQualityMode {
+  const raw = hookSectionValue(consumer_root, "verify_before_complete", "touched_file_quality");
+  return raw === "shadow" || raw === "warn" ? raw : "off";
+}
+
+/**
+ * Run the shadow quality pass for this stop, or return nothing.
+ *
+ * Kept OUTSIDE the state lock on purpose. `update_json_under_lock` holds a lock
+ * around its mutator, and a mutator that spawns `tsc` would hold it for the
+ * whole typecheck — every concurrent concern writing this session's state would
+ * block behind a linter. The pass runs first, the result is handed to `_update`
+ * as data, and the lock stays as short as it was.
+ */
+export function collectTouchedFileQuality(
+  consumer_root: string,
+  session_id: string,
+): { runs: QualityRun[]; source: string } | null {
+  let touched: { files: readonly string[]; source: string };
+  try {
+    touched = touchedFilesAtStop(consumer_root, session_id);
+  } catch {
+    return null;
+  }
+  if (touched.files.length === 0) {
+    // Nothing to measure. Recorded as an empty run list with its source, not as
+    // silence: 2.1 counts "stops with edits" against "stops with at least one
+    // entry", and a stop that produced no entry has to be distinguishable from
+    // a stop where the pass never ran.
+    return { runs: [], source: touched.source };
+  }
+  let commands: readonly string[] = [];
+  try {
+    commands = resolve_toolchain(consumer_root).quality;
+  } catch {
+    commands = [];
+  }
+  try {
+    return {
+      runs: runTouchedFileQuality({
+        root: consumer_root,
+        commands,
+        files: touched.files,
+      }),
+      source: touched.source,
+    };
+  } catch {
+    return null;
+  }
+}
+
 
 /** Return [tool_name, command_text] from a tool-event payload. */
 function _extract_command(payload: StateDict): [string | null, string | null] {
@@ -230,7 +301,7 @@ function _is_verification(command: string): boolean {
   // settle is genuine, which is what the FC-3b guard below decides. Before this
   // change a CI poll counted for nothing at all, so nothing observed the
   // difference between "settled" and "never started".
-  return _VERIFICATION_RE.test(command) || isCiPoll(command);
+  return isVerificationCommand(command) || isCiPoll(command);
 }
 
 /**
@@ -334,11 +405,303 @@ function _extract_output(payload: StateDict): string | null {
   return null;
 }
 
+/**
+ * Tool names that CHANGE the tree, across the platforms this concern sees.
+ *
+ * The first four mirror `_EDIT_TOOLS` in the turn-end gate exactly; the rest are
+ * the same three tools under the names Augment, Cline and Cursor give them. The
+ * gate reads a Claude transcript and can afford four names; this recorder runs
+ * on every platform the manifest binds `post_tool_use` on, so it needs all of
+ * them — a missed edit name means `edits_this_turn` undercounts and a
+ * verification run looks LATER in the sequence than it was, which is the one
+ * direction that could clear an unverified edit.
+ */
+const EDIT_TOOLS: ReadonlySet<string> = new Set([
+  "Edit",
+  "Write",
+  "MultiEdit",
+  "NotebookEdit",
+  "str-replace-editor",
+  "save-file",
+  "str_replace_editor",
+  "create_file",
+  "write_to_file",
+  "replace_in_file",
+  "apply_diff",
+  "edit_file",
+]);
+
+/**
+ * How many run records one turn may keep.
+ *
+ * The state file is read by a stop-slot hook on every turn, so it is on the
+ * latency path and cannot grow without a ceiling. The NEWEST are kept because
+ * the only question asked of them is whether a passing run follows the LAST
+ * edit, which is always answered by the tail.
+ */
+export const MAX_VERIFICATION_RUNS_PER_TURN = 24;
+
+/**
+ * Characters of tool output retained per stream per record.
+ *
+ * CHARACTERS, not bytes, and the name is kept for its existing importers: the
+ * slice is applied to a JS string. Multibyte output can therefore exceed this
+ * many bytes, which is a bound on the state file rather than a promise about
+ * it, and 4,096 characters is far more than any runner's summary needs.
+ */
+export const RUN_OUTPUT_TAIL_BYTES = 4096;
+
+/**
+ * Apply the per-turn cap, keeping the newest AND the earliest failing record.
+ *
+ * Two detectors read this array and they ask opposite-ended questions. Detector
+ * C asks whether a pass follows the last edit — always answered by the tail.
+ * Detector F asks whether a red preceded the green — answered by the head. A
+ * plain `slice(-N)` serves the first and can silently drop the evidence the
+ * second needs, turning a turn that did honest red-green work into a
+ * `no_red_evidence` refusal once the run count passes the cap.
+ */
+function _cap_runs(runs: unknown[]): unknown[] {
+  if (runs.length <= MAX_VERIFICATION_RUNS_PER_TURN) return runs;
+  const tail = runs.slice(-(MAX_VERIFICATION_RUNS_PER_TURN - 1));
+  const head = runs.find((r) => {
+    if (r === null || typeof r !== "object" || Array.isArray(r)) return false;
+    const rec = r as StateDict;
+    const code = rec["exit_code"];
+    return typeof code === "number" && code !== 0;
+  });
+  if (head === undefined || tail.includes(head)) {
+    return runs.slice(-MAX_VERIFICATION_RUNS_PER_TURN);
+  }
+  return [head, ...tail];
+}
+
+/**
+ * The prefix a host puts on a FAILED shell result when it carries no exit field.
+ *
+ * Claude Code's Bash tool does exactly this: a failing call's whole tool
+ * response is the string `Error: Exit code 1\n<output>`. Measured over 1,077
+ * object-shaped and 11 string-shaped tool results in this machine's own
+ * transcripts (2026-09-29): every string-shaped result carried this prefix, and
+ * no shape of either kind carried any of the numeric field names below.
+ */
+const _ERROR_EXIT_PREFIX = /^Error:\s*Exit code\s*(\d+)/i;
+
+/**
+ * The same statement without the `Error:` word, which is how the host words it
+ * on its FAILURE event.
+ *
+ * Measured 2026-10-01 on Claude Code 2.1.286: a failing `Bash` call fires
+ * `PostToolUseFailure`, whose envelope carries NO `tool_response` at all. The
+ * exit status is a top-level `error` string whose first line reads
+ * `Exit code N`, with the command's own diagnostics on the lines after it. The
+ * prefix above never matches that, so for as long as only the success event was
+ * bound this recorder could not have written a non-zero exit even once — which
+ * is exactly what 24 consecutive all-zero records on this host turned out to
+ * mean.
+ */
+const _BARE_EXIT_PREFIX = /^\s*Exit code\s*(\d+)/i;
+
+/** The status a post-tool payload actually reports, and HOW it reported it. */
+interface ExitReading {
+  readonly code: number | null;
+  /** Provenance, recorded so a reader can tell an observed code from a derived one. */
+  readonly source: "field" | "error_prefix" | "response_shape" | null;
+  /** The host said the call was interrupted — a kill, not a verdict on the work. */
+  readonly interrupted: boolean;
+}
+
+const _NO_EXIT: ExitReading = { code: null, source: null, interrupted: false };
+
+function _numeric_exit_field(obj: StateDict): number | null {
+  for (const key of ["exit_code", "exitCode", "returncode", "returnCode", "status_code"]) {
+    const v = obj[key];
+    if (typeof v === "number" && Number.isFinite(v)) return Math.trunc(v);
+    if (typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v))) {
+      return Math.trunc(Number(v));
+    }
+  }
+  return null;
+}
+
+/**
+ * What the host said about how the command ended.
+ *
+ * `null` is a REAL value and is never normalised to 0: several hosts surface no
+ * exit status at all, and writing 0 for "the host said nothing" would
+ * manufacture the strongest possible evidence out of silence. The classifier's
+ * `exit_code_unavailable` verdict exists so that gap stays visible.
+ *
+ * THREE SOURCES, in descending directness, and the third is the one that took a
+ * measurement rather than a guess.
+ *
+ *   · `field` — a numeric exit field, wherever a host provides one.
+ *   · `error_prefix` — the `Error: Exit code N` string form above. This is a
+ *     real non-zero code, stated by the host in the only place it states it.
+ *   · `response_shape` — an OBJECT response carrying `interrupted: false`
+ *     alongside a `stdout` or `stderr` key. On Claude Code that is the success
+ *     form, and the discriminator is deliberately the PRESENCE of
+ *     `interrupted: false` rather than the ABSENCE of an error prefix: a
+ *     positive signal from the host, not an inference from silence. A shape
+ *     that carries neither reads as `null` and stays an instrument gap.
+ *
+ * Without the second and third readings this recorder wrote `exit_code: null`
+ * for every command on the one host that binds the turn-end gate, so the whole
+ * record path was inert — found by an independent review of the branch that
+ * introduced it, against 1,077 real tool results.
+ */
+/**
+ * Did the HOST say this call failed, independently of anything in its text?
+ *
+ * Read from the native event name, which the host writes in two places and the
+ * agent in neither: `hook_event_name` inside the payload, and `native_event` on
+ * the dispatcher envelope. Either is authoritative; both are checked because a
+ * raw-payload invocation carries only the first and a synthesised envelope only
+ * the second.
+ *
+ * An explicit set of OBSERVED names, with a suffix match behind it as a declared
+ * fallback rather than as the primary rule. A reviewer called the suffix-only
+ * form a maintenance trap and was right about the direction: the set is what a
+ * reader checks against the manifest, and `PostToolUseFailure` is the one
+ * spelling this package has actually seen a host send.
+ *
+ * The fallback is kept, and keeping it is the deliberate half. A host whose
+ * failure event this tree has never observed is exactly the case where guessing
+ * wrong is cheapest in one direction and expensive in the other: a false
+ * positive costs a refusal to record a zero, a false negative costs a
+ * manufactured pass on a red run. So the set is the rule and the suffix is the
+ * safe default for a name nobody here has met yet.
+ */
+export const FAILURE_EVENT_NAMES: ReadonlySet<string> = new Set(["PostToolUseFailure"]);
+
+function _is_failure_event(payload: StateDict, envelope: StateDict): boolean {
+  for (const v of [payload["hook_event_name"], envelope["native_event"]]) {
+    if (typeof v !== "string" || v === "") continue;
+    if (FAILURE_EVENT_NAMES.has(v)) return true;
+    if (/failure$/i.test(v)) return true;
+  }
+  return false;
+}
+
+function _extract_exit_reading(payload: StateDict, failure_event = false): ExitReading {
+  // On an event the host itself named a FAILURE, a zero is never recorded —
+  // from any of the three readings. The host has already stated the call did not
+  // succeed, so a `0` arrived at by parsing its text would contradict the only
+  // authoritative thing in the envelope, and it would do so in the single most
+  // dangerous direction: manufacturing the strongest possible pass evidence out
+  // of a red run. `null` instead, which the classifier already treats as an
+  // instrument gap and never as a pass.
+  //
+  // Raised by an independent reviewer who asked what happens when a command's
+  // own error text begins `Exit code 0`. Nothing observed produces that, which
+  // is exactly why it is worth closing before something does.
+  const seal = (r: ExitReading): ExitReading =>
+    failure_event && r.code === 0 ? { code: null, source: null, interrupted: r.interrupted } : r;
+
+  const direct = _numeric_exit_field(payload);
+  if (direct !== null) return seal({ code: direct, source: "field", interrupted: false });
+
+  // The FAILURE envelope, read before the success keys because it carries none
+  // of them: no `tool_response`, the status in a top-level `error` string, and
+  // the interrupt flag spelled `is_interrupt` rather than the nested
+  // `interrupted` below. Interruption is checked FIRST — a killed call is a
+  // statement about the kill and not a verdict on the work, so a host that
+  // sends both must not have its kill read as a failing exit.
+  const interrupted_top = payload["is_interrupt"] === true;
+  const err = payload["error"];
+  if (typeof err === "string") {
+    if (interrupted_top) return { code: null, source: null, interrupted: true };
+    const bare = _BARE_EXIT_PREFIX.exec(err) ?? _ERROR_EXIT_PREFIX.exec(err);
+    if (bare?.[1] !== undefined) {
+      return seal({ code: Number(bare[1]), source: "error_prefix", interrupted: false });
+    }
+  }
+  if (interrupted_top) return { code: null, source: null, interrupted: true };
+
+  for (const key of ["tool_response", "toolResponse", "result", "output"]) {
+    const v = payload[key];
+    if (typeof v === "string") {
+      const m = _ERROR_EXIT_PREFIX.exec(v);
+      if (m?.[1] !== undefined) {
+        return seal({ code: Number(m[1]), source: "error_prefix", interrupted: false });
+      }
+      continue;
+    }
+    if (v === null || typeof v !== "object" || Array.isArray(v)) continue;
+    const obj = v as StateDict;
+    const nested = _numeric_exit_field(obj);
+    if (nested !== null) return seal({ code: nested, source: "field", interrupted: false });
+    if (obj["interrupted"] === true) return { code: null, source: null, interrupted: true };
+    const hasStream = typeof obj["stdout"] === "string" || typeof obj["stderr"] === "string";
+    if (obj["interrupted"] === false && hasStream) {
+      return seal({ code: 0, source: "response_shape", interrupted: false });
+    }
+  }
+  return _NO_EXIT;
+}
+
+/**
+ * The command's stdout and stderr as REAL strings, never as a stringified blob.
+ *
+ * Separate from `_extract_output` above, which feeds the pre-existing `vacuous`
+ * counters and whose behavior must not move: that one returns
+ * `JSON.stringify(v)` for an object response, and every parser in
+ * `verification_evidence.ts` is line-anchored (`/^[ \t]*Tests:?.../m` and
+ * friends). JSON escapes a newline as the two characters `\` and `n`, so a
+ * stringified response can never match any of them — the classifier was blind
+ * to every summary on the host's success shape. Found by the same review.
+ */
+function _extract_run_streams(payload: StateDict): { stdout: string; stderr: string } {
+  for (const key of ["tool_response", "toolResponse", "result", "output"]) {
+    const v = payload[key];
+    if (typeof v === "string") return { stdout: v, stderr: "" };
+    if (v === null || typeof v !== "object" || Array.isArray(v)) continue;
+    const obj = v as StateDict;
+    const out = obj["stdout"] ?? obj["output"];
+    const err = obj["stderr"];
+    if (typeof out === "string" || typeof err === "string") {
+      return {
+        stdout: typeof out === "string" ? out : "",
+        stderr: typeof err === "string" ? err : "",
+      };
+    }
+  }
+  const topOut = payload["stdout"] ?? payload["output"];
+  const topErr = payload["stderr"];
+  if (typeof topOut === "string" || typeof topErr === "string") {
+    return {
+      stdout: typeof topOut === "string" ? topOut : "",
+      stderr: typeof topErr === "string" ? topErr : "",
+    };
+  }
+  // The failure envelope's one text field. Recorded as `stdout` because the
+  // host collapses both streams into it and says nothing about which was
+  // which — a recorder that split them would be inventing a fact — and because
+  // every parser in `verification_evidence` is line-anchored over stdout. The
+  // alternative, dropping it, would leave a red run recorded with its exit code
+  // and no reason, which is the half the reader actually needs.
+  const errText = payload["error"];
+  if (typeof errText === "string") return { stdout: errText, stderr: "" };
+  return { stdout: "", stderr: "" };
+}
+
 function _reset_turn(state: StateDict, session_id: string): StateDict {
   state["session_id"] = session_id || state["session_id"] || "";
   state["turn_started_at"] = _now();
   state["verifications_this_turn"] = 0;
   state["verified_this_turn"] = false;
+  // Round 8 — the run records the stop gate reads instead of the command text,
+  // and the edit counter that places them in the turn's sequence. Both are
+  // TURN-scoped: a run from the previous turn demonstrably did not exercise this
+  // turn's edits, which is the freshness argument `verify-before-complete` makes.
+  state["verification_runs"] = [];
+  state["edits_this_turn"] = 0;
+  // TURN-scoped for the same reason as its neighbour: a quality verdict from
+  // the previous turn describes files this turn may already have changed, and a
+  // stale PASS is the direction that misleads. DELETED rather than emptied, so
+  // that a turn boundary restores the base-ref shape — see `_empty_state`.
+  delete state["quality_runs"];
+  delete state["quality_files_source"];
   // FC-3b turn-scoped counters: a CI settle must be witnessed within the same
   // turn that claims it, so the in-flight observation does not survive a turn.
   state["ci_saw_pending"] = false;
@@ -357,7 +720,19 @@ function _asInt(v: unknown): number {
   return Number.isFinite(n) ? Math.trunc(n) : 0;
 }
 
-function _update(state: StateDict, event: string, envelope: StateDict): StateDict {
+/**
+ * Apply one event to the state.
+ *
+ * `quality` is the shadow pass's already-computed result, handed in rather than
+ * fetched: this function runs INSIDE the state lock, and a spawn in here would
+ * hold that lock for the duration of a typecheck.
+ */
+function _update(
+  state: StateDict,
+  event: string,
+  envelope: StateDict,
+  quality: { runs: QualityRun[]; source: string } | null = null,
+): StateDict {
   const session_id = (envelope["session_id"] || state["session_id"] || "") as string;
   if (session_id && session_id !== state["session_id"]) {
     // Session boundary — reset session-scoped counters.
@@ -376,6 +751,16 @@ function _update(state: StateDict, event: string, envelope: StateDict): StateDic
     state = _reset_turn(state, session_id);
   }
 
+  // The host that wrote this file. Recorded because the instrument-gap reading
+  // is a PER-HOST question and the witness carried no answer to it: every
+  // coverage number had to be attributed by hand, and a file from an unknown
+  // host is indistinguishable from a host with nothing to report. Written on
+  // every update rather than once, so a file predating this field acquires it
+  // the first time the host touches it; until then a reader sees it absent,
+  // which is the honest reading and not a default.
+  const platform = envelope["platform"];
+  if (typeof platform === "string" && platform) state["platform"] = platform;
+
   let payload = envelope["payload"];
   if (!(typeof payload === "object" && payload !== null && !Array.isArray(payload))) {
     payload = {};
@@ -386,6 +771,11 @@ function _update(state: StateDict, event: string, envelope: StateDict): StateDic
     state = _reset_turn(state, session_id);
   } else if (event === "post_tool_use") {
     const [tool, cmd] = _extract_command(pl);
+    // Counted BEFORE the verification branch, so a run recorded in this same
+    // event is placed after the edits that preceded it and never after itself.
+    if (tool !== null && EDIT_TOOLS.has(tool)) {
+      state["edits_this_turn"] = _asInt(state["edits_this_turn"]) + 1;
+    }
     if (cmd && _is_verification(cmd)) {
       const output = _extract_output(pl);
       // No readable output → the guard has nothing to judge, so behaviour is
@@ -439,6 +829,7 @@ function _update(state: StateDict, event: string, envelope: StateDict): StateDic
         vacuous,
         counted: counts,
       };
+
       if (counts) {
         state["verifications_this_turn"] = _asInt(state["verifications_this_turn"]) + 1;
         state["verifications_this_session"] =
@@ -448,8 +839,73 @@ function _update(state: StateDict, event: string, envelope: StateDict): StateDic
         state["nonevidence_this_turn"] = _asInt(state["nonevidence_this_turn"]) + 1;
       }
     }
+
+    // The RUN record, written beside `last_verification` and gated on a
+    // DIFFERENT, wider selector — the one the turn-end gate's detector C uses.
+    //
+    // Two selectors is a smell, so here is why it is not one — and the reason
+    // was rewritten 2026-09-30, because the version standing here was half
+    // wrong. It claimed the narrow selector protected `verifications_this_turn`
+    // AND the FC-3b `ci_last` discrimination. `ci_last` is written inside the
+    // nested `isCiPoll` branch above, reached through the second disjunct of
+    // `_is_verification` whatever the first one says, so no widening of the
+    // first could ever have moved it; and nothing branches on the counter.
+    // Both are now pinned by tests rather than asserted in a comment.
+    //
+    // What survives is a real distinction, and it is about ERROR COST, not
+    // about two spellings of one idea. `isVerificationCommand` answers *did
+    // this verify* — a false positive there clears an unverified edit, so it is
+    // head-anchored. `mightBeVerification` answers *is this worth writing down*
+    // — and the run record decides nothing by itself, since `classifyRun` is
+    // what judges it. So the record path wants every command the gate might
+    // read, including the ones the classifier will then reject —
+    // `not_a_verification_command` is a verdict the gate needs to SEE, and a
+    // recorder that filtered those out would leave the gate unable to tell "the
+    // turn ran `echo test`" from "the turn ran nothing at all".
+    //
+    // `after_edits` is the edit counter as it stood when the command ran. The
+    // reader compares it against the number of edits the turn made in total:
+    // equal or greater means nothing was edited afterwards. That is an ORDINAL
+    // comparison needing no clock, so it survives a host whose timestamps are
+    // coarse or absent, and it degrades toward under-refusing when the reader's
+    // own count is short.
+    if (cmd && mightBeVerification(cmd)) {
+      const streams = _extract_run_streams(pl);
+      const exit = _extract_exit_reading(pl, _is_failure_event(pl, envelope));
+      const runs = Array.isArray(state["verification_runs"])
+        ? [...(state["verification_runs"] as unknown[])]
+        : [];
+      runs.push({
+        command: cmd.slice(0, 512),
+        tool,
+        exit_code: exit.code,
+        // Provenance, not decoration: `response_shape` is a code this recorder
+        // DERIVED from the host's success form, and a reader disputing a verdict
+        // needs to know which of the three readings produced it.
+        exit_source: exit.source,
+        interrupted: exit.interrupted,
+        stdout_tail: streams.stdout.slice(-RUN_OUTPUT_TAIL_BYTES),
+        // Written, and previously not: `RunRecord.stderr_tail` was declared and
+        // read by the classifier's `output()` while nothing populated it, so
+        // stderr reached a parser only by accident inside a stringified blob.
+        stderr_tail: streams.stderr.slice(-RUN_OUTPUT_TAIL_BYTES),
+        runner: runnerOf(cmd),
+        after_edits: _asInt(state["edits_this_turn"]),
+        at: _now(),
+      });
+      // The NEWEST are kept for detector C, which asks whether a pass follows
+      // the last edit. Detector F asks a question the head answers — was there a
+      // red before the green — so the cap keeps the FIRST failing record too,
+      // ahead of the tail, rather than letting a chatty turn drop the red half
+      // of its own red-then-green pair.
+      state["verification_runs"] = _cap_runs(runs);
+    }
   } else if (event === "stop") {
     state["last_stop_at"] = _now();
+    if (quality !== null) {
+      state["quality_runs"] = quality.runs;
+      state["quality_files_source"] = quality.source;
+    }
   }
 
   state["checked_at"] = _now();
@@ -511,6 +967,15 @@ export function run(
 
   const target = path.join(consumer_root, statePathFor(session_id));
 
+  // The shadow quality pass, computed BEFORE the lock (see `_update`'s header)
+  // and only at `stop`. `off` is the template default and the resolved value of
+  // every unreadable or unrecognised setting, so an install that never opted in
+  // spawns nothing, reads no manifest and writes no new field — the acceptance
+  // criterion is that its record is byte-identical to the base ref.
+  const quality_mode = event === "stop" ? readTouchedFileQualityMode(consumer_root) : "off";
+  const quality =
+    quality_mode === "off" ? null : collectTouchedFileQuality(consumer_root, session_id);
+
   // LOAD → UPDATE → PUBLISH under ONE lock, not three separate steps.
   //
   // This was `_load_state` / `_update` / `atomic_write_json`, which makes the
@@ -541,7 +1006,7 @@ export function run(
     // treats a missing counter as 0 and the `=== true` guards treat a missing
     // flag as false, so every assertion would still pass while `schema_version`
     // and an explicit `ci_last: null` vanished from a freshly created file.
-    state = _update({ ..._empty_state(), ...loaded } as StateDict, event, envelope);
+    state = _update({ ..._empty_state(), ...loaded } as StateDict, event, envelope, quality);
     return state;
   });
   if (outcome === "failed") {
@@ -562,6 +1027,21 @@ export function run(
     );
   }
 
+  // `warn` — ONE advisory line, and the exit code does not move.
+  //
+  // In this tree a warn is conventionally an exit of 2, and on the one host that
+  // honours a deny that reads as a BLOCK. D3 of the roadmap settles it the other
+  // way for this field: shadow → warn only, never a block, on the strength of
+  // this hook's own contract ("the hook itself never blocks — it is
+  // observability infra, not control flow"). So the line goes to stderr and the
+  // function returns 0 on this path exactly as on every other.
+  if (quality_mode === "warn" && quality !== null) {
+    const line = advisoryLine(quality.runs);
+    if (line !== null) {
+      process.stderr.write(`${line}\n`);
+    }
+  }
+
   if (verbose) {
     process.stderr.write(
       `verify-before-complete-hook: event=${event} ` +
@@ -613,6 +1093,74 @@ export function main(argv?: string[]): number {
   return run(_readStdin(), { consumer_root: process.cwd(), verbose: args.verbose });
 }
 
+// ---------------------------------------------------------------------------
+// The consumer side of `verification_runs`, living with its producer
+// ---------------------------------------------------------------------------
+
+/**
+ * Why the turn-end gate's reader sits HERE and not in the gate.
+ *
+ * The shape of `verification_runs` and `edits_this_turn` is this file's; the
+ * reader is the only consumer of that shape, and the gate already imported this
+ * module's path BUILDER rather than a path constant for exactly the reason that
+ * applies here too — "the consumer cannot read a path the producer does not
+ * write" is only true while the two agree, and separating them made the
+ * agreement invisible when the layout moved. Keeping the reader beside the
+ * writer makes a shape change a type error in one file instead of a silent
+ * disagreement across two.
+ *
+ * It also keeps the gate under its source-size ceiling without deleting
+ * anything, which is the move the ratchet asks for rather than a trim.
+ */
+export interface TurnRunState {
+  readonly runs: readonly unknown[];
+  readonly edits_this_turn: number;
+}
+
+/**
+ * The turn's recorded verification runs, or `null` when the recorder is not live.
+ *
+ * WHY THE LIVENESS TEST IS `edits_this_turn >= 1` AND NOT "the file exists".
+ * The obvious predicate — a state file with a `verification_runs` key — is
+ * wrong in a way that would refuse honest work on entire platforms. That key is
+ * present in the recorder's EMPTY state, so a host whose `post_tool_use` slot
+ * the manifest does not bind still has a file carrying `[]`, written by the
+ * prompt and stop events alone. Reading that as "this turn ran nothing" would
+ * refuse every editing turn on such a host, whatever the operator actually ran.
+ *
+ * `edits_this_turn` is the one field only a `post_tool_use` event can raise. The
+ * detector reaches here having already found an edit in the transcript, so a
+ * recorder that saw none of this turn's tool events is exactly the case this
+ * returns `null` for — and `null` means the transcript path answers, which is
+ * the behavior that predates the record path.
+ *
+ * The ownership check is the same one detector D applies to `ci_last`, for the
+ * same reason: a FOREIGN file's passing record would vouch for a run this
+ * session never made.
+ */
+export function readTurnRunState(
+    workspaceRoot: string,
+    session_id: string,
+): TurnRunState | null {
+    if (!has_stable_session_id(session_id)) return null;
+    try {
+        const raw = fs.readFileSync(path.join(workspaceRoot, statePathFor(session_id)), 'utf-8');
+        const decoded: unknown = JSON.parse(raw);
+        if (!owns_session_state(decoded, session_id)) return null;
+        if (typeof decoded !== 'object' || decoded === null || Array.isArray(decoded)) return null;
+        const state = decoded as Record<string, unknown>;
+        const runs = state['verification_runs'];
+        const edits = state['edits_this_turn'];
+        if (!Array.isArray(runs)) return null;
+        if (typeof edits !== 'number' || !Number.isFinite(edits) || edits < 1) return null;
+        return { runs: runs as readonly unknown[], edits_this_turn: edits };
+    } catch {
+        // Absent, unreadable or malformed — the recorder said nothing, so the
+        // transcript answers. Never a refusal of its own.
+        return null;
+    }
+}
+
 // 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;