@event4u/agent-config 12.1.0 → 14.0.0

package/src/scripts/hooks/ship_diff_volume_hook.ts

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * `ship-diff-volume` — a shipping-intent gate on diff VOLUME.
+ *
+ * Complementary to `minimal-safe-diff`, not a duplicate of it, and the
+ * distinction is the reason this exists: that concern counts unique FILES
+ * TOUCHED PER TURN, which is a within-session shape signal. This one measures
+ * total changed LINES on the branch AT A SHIP VERB — the moment the change
+ * leaves for review. A twelve-turn change of four files each time trips
+ * neither; a single-turn 3,000-line change trips only this one.
+ *
+ * THE THRESHOLD IS DERIVED FROM THIS REPOSITORY'S OWN HISTORY, never copied
+ * from the reference that suggested the gate. Replay of the 40 most recently
+ * merged PRs (agents/evidence/eval-findings/metric-loop-s04.md) put the
+ * corrected p90 at 1,695 lines.
+ *
+ * THE EXCLUSION SET IS PART OF THE DEFINITION, NOT A TUNING PARAMETER. The
+ * same replay found the naive metric double-counting: four of the five largest
+ * PRs were dominated by `*.review-input/diff.patch` — a committed copy of the
+ * very diff being measured — and the fifth by a generated index. Precision at
+ * the raw p90 was 2/5, below the pre-registered 0.50 floor; excluding the
+ * repository's own bookkeeping moved it to 5/5. Removing an input that was
+ * never shipping volume is a correction. Growing this set until a firing goes
+ * away would be tuning, and the kill criterion applies to that.
+ *
+ * WARN-LEVEL FIRST. It never blocks; escalation waits for one release of
+ * recorded firings, per the phase. Exit code is always 0 on the advisory path;
+ * 2 is the warn-in-context channel this estate's dispatcher reads.
+ */
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { readHookStdin } from './hook_stdin.js';
+import { atomic_write_json } from './state_io.js';
+
+export const STATE_FILE = path.join('agents', 'state', 'ship-diff-volume.json');
+
+/** Derived: corrected p90 over the last 40 merged PRs (spike s04). */
+export const DEFAULT_THRESHOLD = 1695;
+
+/**
+ * Paths excluded from the volume because they are not shipping volume.
+ *
+ * Each entry is a category of artefact the change did not author: a snapshot of
+ * the diff itself, a generated index, or a projection tree regenerated from
+ * source. None is a threshold in disguise.
+ */
+export const EXCLUDED = [
+    '.review-input/', // a committed copy of the diff being measured
+    'agents/roadmaps/archive/index.json', // generated index
+    'dist/', // projection of src/
+    '.augment/',
+    '.claude/',
+    '.cursor/',
+    '.clinerules/',
+] as const;
+
+/** Ship verbs — the moment a change leaves for review. */
+const SHIP_PATTERNS = [/\bgit\s+push\b/, /\bgh\s+pr\s+create\b/] as const;
+
+export function isShipCommand(cmd: string): boolean {
+    return SHIP_PATTERNS.some((re) => re.test(cmd));
+}
+
+export function isExcluded(p: string): boolean {
+    return EXCLUDED.some((e) => (e.endsWith('/') ? p.startsWith(e) || p.includes(e) : p === e));
+}
+
+/** `git diff --numstat` output → corrected volume plus what was excluded. */
+export function correctedVolume(numstat: string): { volume: number; excluded: number; files: number } {
+    let volume = 0;
+    let excluded = 0;
+    let files = 0;
+    for (const line of numstat.split('\n')) {
+        const m = line.match(/^(\d+|-)\t(\d+|-)\t(.+)$/);
+        if (m === null) continue;
+        const add = m[1] === '-' ? 0 : Number(m[1]);
+        const del = m[2] === '-' ? 0 : Number(m[2]);
+        const p = m[3]!;
+        if (isExcluded(p)) {
+            excluded += add + del;
+            continue;
+        }
+        volume += add + del;
+        files += 1;
+    }
+    return { volume, excluded, files };
+}
+
+function extractCommand(envelope: Record<string, unknown>): string {
+    const ti = envelope['tool_input'];
+    if (ti !== null && typeof ti === 'object') {
+        const c = (ti as Record<string, unknown>)['command'];
+        if (typeof c === 'string') return c;
+    }
+    const c = envelope['command'];
+    return typeof c === 'string' ? c : '';
+}
+
+export function main(argv?: string[]): number {
+    const args = argv ?? process.argv.slice(2);
+    const idx = args.indexOf('--command');
+    let cmd = idx >= 0 && args[idx + 1] !== undefined ? args[idx + 1]! : '';
+    if (!cmd) {
+        const raw = readHookStdin();
+        let envelope: Record<string, unknown> = {};
+        if (raw.trim()) {
+            try {
+                envelope = JSON.parse(raw) as Record<string, unknown>;
+            } catch {
+                envelope = {};
+            }
+        }
+        cmd = extractCommand(envelope);
+    }
+    if (!isShipCommand(cmd)) return 0;
+
+    let numstat: string;
+    let base: string;
+    try {
+        base = execFileSync('git', ['merge-base', 'HEAD', 'origin/main'], { encoding: 'utf-8' }).trim();
+        numstat = execFileSync('git', ['diff', '--numstat', `${base}...HEAD`], {
+            encoding: 'utf-8',
+            maxBuffer: 64 * 1024 * 1024,
+        });
+    } catch {
+        // No merge base, no origin, a detached probe — nothing to say. An
+        // advisory concern that guesses on missing input is worse than silent.
+        return 0;
+    }
+
+    const { volume, excluded, files } = correctedVolume(numstat);
+    const over = volume >= DEFAULT_THRESHOLD;
+
+    try {
+        fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+        atomic_write_json(STATE_FILE, {
+            schema_version: 1,
+            base,
+            corrected_volume: volume,
+            excluded_volume: excluded,
+            files_counted: files,
+            threshold: DEFAULT_THRESHOLD,
+            warning: over,
+            checked_at: new Date().toISOString(),
+        });
+    } catch {
+        // State is observability, never the gate. A read-only tree must not
+        // turn an advisory warning into a failed ship.
+    }
+
+    if (!over) return 0;
+
+    process.stderr.write(
+        `ship-diff-volume: ${String(volume)} changed lines against ${DEFAULT_THRESHOLD} ` +
+            `(${String(files)} file(s); ${String(excluded)} line(s) excluded as bookkeeping).\n` +
+            `Every PR above this line in the last 40 named two or more concerns in its own title. ` +
+            `Splitting is a suggestion, not a requirement — this warns and never blocks.\n`,
+    );
+    return 2; // warn-in-context; advisory severity means the dispatcher does not block
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) 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/skill_route_hook.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Skill route — `user_prompt_submit` concern
+ * (road-to-inbox-harvest-2026-08-d-runtime-skill-routing Phase 2).
+ *
+ * THE DEFECT THIS CLOSES. A deterministic task→skill ranker has shipped in
+ * this tree for months and is bound to nothing: `score_skill_relevance.rank`
+ * and its `suggest_skill_for_task` wrapper have no production caller, and
+ * `hook_manifest.yaml` had no concern that reached either. A capability that
+ * ships and never runs is indistinguishable from one that was never built —
+ * the same shape `delegation-nudge` was created to end for `classifyTask`, and
+ * this concern is deliberately its twin rather than a new mechanism.
+ *
+ * POINTERS, NEVER BODIES. The injected line names at most three skill IDs and
+ * their scores. It does not carry descriptions, excerpts, or file contents, and
+ * it never instructs the agent to load anything. The reason is the risk this
+ * roadmap's own register ranks first: a pointer line the agent trusts is worse
+ * than no line when the ranking is poor, so what is injected is the cheapest
+ * thing that can still be acted on — and the cheapest thing to ignore.
+ *
+ * SILENCE IS THE DEFAULT, AND BOTH FLOORS ARE MEASURED, NOT GUESSED. `rank`
+ * already drops every zero-scoring skill, but on real prompts it almost always
+ * returns SOMETHING, so "non-empty" is not a usable trigger. Measured over the
+ * routing-matrix corpus (496 prompt lines, `tests/eval/routing-matrix/*.yaml`,
+ * 2026-08-16): top-score median 18, p75 28, p90 30, max 70, and only 4 prompts
+ * score nothing at all.
+ *
+ * TWO floors are needed, because the score alone cannot express the failure at
+ * the short end. `MIN_TOP_SCORE` gates confidence; `MIN_TASK_TERMS` gates the
+ * denominator that confidence is computed over — the scorer divides by the task
+ * term count, so a one-term prompt scores 70/100 against whatever shares that
+ * term. Together they fire on 9.1 % of the corpus. A score floor at the median
+ * with no term floor would fire on half of all turns AND still hand 70/100 to
+ * `"fix it"` — the per-turn-reminder shape this estate has already measured
+ * failing at a 24/29 miss rate. Each constant carries its own derivation below.
+ *
+ * COST, MEASURED RATHER THAN ASSUMED. Ranking re-reads the skill catalogue per
+ * prompt, uncached. Measured 2026-08-16 on this tree: **12.3 ms warm** for a
+ * prompt that reaches the ranker, against the slot's 250 ms p95 budget — about
+ * 5 % of it. A prompt below `MIN_TASK_TERMS` costs **0 ms**, because the term
+ * floor is checked BEFORE the catalogue read; that ordering is deliberate and
+ * is what keeps conversational turns free. No cache is added: a cache would
+ * need an invalidation story for a tree that changes under the session, and
+ * 12.3 ms does not buy one.
+ *
+ * NO ADOPTION THRESHOLD IS COMMITTED HERE. Whether the line changes behaviour
+ * is a question for data, not for this header: `skill_route_pointer_rate` is
+ * registered in `hook-token-budget.json` under the same owner/review discipline
+ * as its sibling advisories, with the same kill standard — a nudge whose
+ * verdicts are measurably ignored gets its trigger tightened or its line
+ * removed. The score floor above is a TRIGGER calibration and is measured; the
+ * adoption threshold is an OUTCOME claim and is deliberately absent.
+ *
+ * DELIVERY PATH — the verified one, copied rather than re-derived. A
+ * `user_prompt_submit` concern returning `{decision:"allow", context:…}` at
+ * exit 0 produces zero stdout: `host_semantics.emitFor` drops the field for
+ * severity `"allow"`. The only shape that survives to
+ * `hookSpecificOutput.additionalContext` is `{decision:"warn", reason,
+ * additional_context}` at exit 2, which `emitFor` reduces to a real process
+ * exit of 0 — it never blocks the turn. `delegation_nudge_hook.ts` carries the
+ * full proof of that mechanism and this concern follows it exactly.
+ *
+ * PLATFORM SCOPE — `claude` only, for the same reason its twin gives:
+ * `host_semantics.VERIFIED_PLATFORMS` covers only `claude`, `cowork`'s
+ * trampoline discards dispatcher stdout unconditionally, and the other
+ * trampolines were never inspected for that property. Extending an exit-2
+ * delivery to an unverified propagation path is the speculative mapping
+ * `host_semantics.ts` exists to prevent.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { readHookStdin } from "./hook_stdin.js";
+import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
+import { resolveSkillsRoot } from "../_lib/skill_catalogue.js";
+import { _tokenize, rank, type RankRow } from "../skill_tools/score_skill_relevance.js";
+
+const EXIT_ALLOW = 0;
+/** See the header: reduced to a real exit of 0 by `emitFor`'s warn branch. */
+const EXIT_WARN = 2;
+
+/**
+ * Minimum top-1 ranker score before this concern speaks.
+ *
+ * **31, not the measured p90 of 30, and the extra point is load-bearing.** The
+ * scorer is `overlap * 70 + personaHit * 30`, so a skill whose PERSONA slug
+ * appears in the prompt scores exactly 30 with zero keyword overlap. A floor of
+ * 30 with a `>=` test therefore admits a pure persona coincidence as if it were
+ * a ranked match. 31 is the smallest floor strictly above that value; it moves
+ * the corpus fire rate from 13.9 % to 9.1 %.
+ */
+export const MIN_TOP_SCORE = 31;
+
+/**
+ * Minimum distinct task terms before the score is trusted at all.
+ *
+ * The scorer divides by `|task_terms|`, so the score is inversely proportional
+ * to prompt length and degenerates at the short end: `"fix it"` tokenizes to
+ * ONE term and hands 70/100 to whichever skills happen to share it, which on
+ * this catalogue means the alphabetically first three. `MIN_TOP_SCORE` cannot
+ * fix that — the number is not too low, the denominator is too small.
+ *
+ * **3 is the routing-matrix corpus's own minimum**, so this floor excludes
+ * ZERO of the 496 prompt lines the score calibration rests on while removing
+ * every degenerate short prompt measured (`"fix it"` 1, `"mach das"` 2,
+ * `"was denkst du dazu"` 2, `"weiter"` 1). A floor of 4 would have cost 10 real
+ * corpus prompts for one tenth of a percentage point.
+ */
+export const MIN_TASK_TERMS = 3;
+
+/** Pointers per line. Three is the ranker's own default `--top`. */
+export const TOP_K = 3;
+
+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);
+}
+
+/**
+ * Rank a prompt and return the pointers worth injecting, or `[]` for silence.
+ *
+ * Total by construction: a missing root, an unreadable catalogue, or a ranker
+ * error all resolve to `[]`. A routing advisory that can crash a turn is worse
+ * than one that says nothing.
+ */
+export function routePointers(prompt: string, skillsDir: string | null): RankRow[] {
+  if (skillsDir === null) return [];
+  // Denominator floor BEFORE the catalogue read: a prompt too short to score
+  // meaningfully cannot produce a pointer worth 337 file reads either.
+  try {
+    if (_tokenize(prompt).size < MIN_TASK_TERMS) return [];
+  } catch {
+    return [];
+  }
+  let rows: RankRow[];
+  try {
+    rows = rank(prompt, skillsDir);
+  } catch {
+    return [];
+  }
+  const top = rows[0];
+  if (top === undefined || top[1] < MIN_TOP_SCORE) return [];
+  return rows.slice(0, TOP_K);
+}
+
+/**
+ * The injected line. Names the floor it cleared, so a reader can tell a
+ * confident pointer from a lucky one without opening this file.
+ */
+export function buildRouteLine(rows: readonly RankRow[]): string {
+  const pointers = rows.map(([name, score]) => `${name} (${score})`).join(", ");
+  return (
+    `<skill-route>ranked skill pointers for this prompt: ${pointers}. ` +
+    `Deterministic keyword ranker, top-1 at or above ${MIN_TOP_SCORE}/100 — ` +
+    `pointers only, no bodies loaded. Open one if it fits; ignore the line if it does not.</skill-route>`
+  );
+}
+
+function _extractPrompt(payload: JsonObject): string {
+  for (const key of ["prompt", "userPrompt", "user_prompt", "message", "text"]) {
+    const v = payload[key];
+    if (typeof v === "string" && v.trim()) return v;
+  }
+  return "";
+}
+
+function _workspaceRoot(envelope: JsonObject): string {
+  const v = envelope["workspace_root"];
+  return typeof v === "string" && v ? v : process.cwd();
+}
+
+export function main(): number {
+  let envelope: JsonValue = {};
+  try {
+    const raw = readHookStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    return EXIT_ALLOW; // malformed envelope — never block
+  }
+  const env: JsonObject = _isObject(envelope) ? envelope : {};
+
+  const event = env["event"];
+  const slot = typeof event === "string" && event !== "" ? event : "user_prompt_submit";
+  if (slot !== "user_prompt_submit") return EXIT_ALLOW;
+
+  const payload = _isObject(env["payload"]) ? (env["payload"] as JsonObject) : env;
+  const prompt = _extractPrompt(payload);
+  if (!prompt) return EXIT_ALLOW;
+  if (isSyntheticPrompt(prompt)) return EXIT_ALLOW; // harness turn, not a task
+
+  const rows = routePointers(prompt, resolveSkillsRoot(_workspaceRoot(env)));
+  if (rows.length === 0) return EXIT_ALLOW; // silence is the default
+
+  process.stdout.write(
+    `${JSON.stringify({
+      decision: "warn",
+      reason: `skill-route: ${rows.length} pointer(s), top ${rows[0]![1]}/100`,
+      additional_context: buildRouteLine(rows),
+    })}\n`,
+  );
+  return EXIT_WARN;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+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 {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv = fs.realpathSync(path.resolve(process.argv[1]));
+    return here === argv;
+  } catch {
+    return false;
+  }
+}
+
+if (_isCliEntry()) {
+  process.exit(main());
+}

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -47,9 +47,11 @@
  *      non-sidechain user entries — is distinct for every real turn whatever
  *      the user typed, and stable across harness injections.
  *
- *      Still true and still worth stating: per-session files are bounded per
- *      session but not pruned, so a long-lived workspace accumulates one small
- *      file per session. No TTL ships here.
+ *      No longer true, and corrected here rather than left as a stale admission:
+ *      the files ARE pruned. `road-to-stop-gate-honesty` step 1.2 added a
+ *      90-day retention (`pruneAgedRefusalState`), run at `session_start` by the
+ *      session-register concern. The record also COUNTS now instead of
+ *      overwriting itself — see `markRefusedTurn`.
  *
  * The failure this ordering prevents is not a loop but a wedge: a turn that
  * can never end. Layer 2 also covers the host that does not send
@@ -111,7 +113,6 @@
  * not an advisory, so there is no advisory path here to put on the wrong code.
  * Probed, not assumed.
  */
-import * as crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
@@ -130,6 +131,14 @@ 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 { openRecordStats } from './subagent_ledger_hook.js';
+import {
+    deriveSessionKey,
+    foldRefusal,
+    parseRecord,
+    readInstallBoundary,
+    sessionRefusalFile,
+    type RefusalRecord,
+} from '../_lib/turn_end_refusals.js';
 
 /** Dispatcher-internal block code. Pinned to 1 by `concern_block_exit_parity`. */
 const EXIT_BLOCK = 1;
@@ -294,8 +303,12 @@ const PROMISSORY = [
  * A legitimate hand-back is the opposite speech act: it gives the decision
  * to the user and ends the turn on purpose. `scope-control` requires
  * exactly this shape, so refusing it would put two rules in direct conflict.
+ *
+ * EXPORTED because `interruption_ledger_hook` classifies the same shape as a
+ * synchronous contact. Narrowing this list therefore changes a measurement as
+ * well as a refusal — check that hook before you touch it.
  */
-const HANDBACK = [
+export const HANDBACK = [
     /\bdas entscheidest (du|Du)\b/i,
     /\bdeine Entscheidung\b/i,
     /\bich fasse .{0,40}nicht ungefragt an\b/i,
@@ -527,9 +540,49 @@ const _EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
  * detection when a project verifies by some command not listed here, and that is
  * the safe direction for a gate that can refuse a turn: a false negative costs
  * one unguarded turn, a false positive teaches the user to switch the gate off.
+ *
+ * ## Audited 2026-08-17 — `road-to-stop-gate-honesty` step 2.2
+ *
+ * 52 commands this project's own surface actually produces (its `package.json`
+ * scripts, its `Taskfile` targets, `./scripts-run`, `./agent-config`, and the
+ * PHP / Python / Go / Rust toolchains) were run through
+ * `isVerificationCommand`. The table of every one, with its verdict, is
+ * `turn_end_verify_allowlist.test.ts`; that file is the fixture step 2.2
+ * requires, and every addition below has its own row in it.
+ *
+ * The draft that opened the roadmap expected to add `phpunit` and `pest`. Claim
+ * 4 had already overtaken that — both matched before this audit, as did
+ * `composer test` and `php artisan test` — so what the audit actually found was
+ * two different gaps:
+ *
+ *   · `phpstan` — a static analyser of exactly the class already listed
+ *     (`mypy`, `pyright`, `clippy`). Added.
+ *   · `lint` followed by a WORD character — `lint_persistence`,
+ *     `lint_provenance`, and every other `lint_*` script in `src/scripts/`
+ *     missed, because `\blint\b` needs a boundary and `_` is a word character.
+ *     `lint[-_:a-z]*` is the exact mirror of the `check[-_:a-z]*` this list
+ *     already carried, which is why it is the narrow fix rather than a new idea.
+ *
+ * Four further misses were found and deliberately NOT added, because Risk 2 of
+ * that roadmap is that every addition is a way to satisfy the gate without
+ * verifying anything:
+ *
+ *   · `npm run prepack` — a lifecycle hook whose content is per-project. Here it
+ *     validates; elsewhere it copies files. Recognising it would clear an
+ *     unverified edit in any repo whose prepack is a build step.
+ *   · `task sync` / `task generate-tools` / `agent-config roadmap:progress` —
+ *     GENERATORS. They rewrite the tree; they check nothing. A generator that
+ *     cleared the gate would be the rubber stamp in its purest form.
+ *   · `agent-config gates --all` — enumerates gates, runs none.
+ *   · `vendor/bin/rector process --dry-run` — a refactoring tool. Its dry run
+ *     prints a diff; it does not assert anything holds.
+ *
+ * `psalm` is the obvious sibling of `phpstan` and is also NOT added: nothing in
+ * the audited surface runs it, and "the team actually runs" is the step's own
+ * standard. It is named here so the next audit does not re-derive the question.
  */
 const _VERIFY_RE =
-    /\b(test|tests|vitest|jest|pytest|phpunit|pest|tsc|eslint|ruff|mypy|pyright|clippy|typecheck|lint|build|ci|preflight|smoke[-_:a-z]*|check[-_:a-z]*|validate[-_:a-z]*)\b|\b(task|npm|pnpm|yarn|composer|cargo|go|make|php artisan|bun)\s+(run\s+)?\S*(test|check|lint|build|ci|typecheck)/i;
+    /\b(test|tests|vitest|jest|pytest|phpunit|pest|tsc|eslint|ruff|mypy|pyright|clippy|phpstan|typecheck|lint[-_:a-z]*|build|ci|preflight|smoke[-_:a-z]*|check[-_:a-z]*|validate[-_:a-z]*)\b|\b(task|npm|pnpm|yarn|composer|cargo|go|make|php artisan|bun)\s+(run\s+)?\S*(test|check|lint|build|ci|typecheck)/i;
 
 export function isVerificationCommand(command: string): boolean {
     return _VERIFY_RE.test(command);
@@ -579,29 +632,30 @@ export function detectUnverifiedEdit(toolCalls: readonly ToolCall[]): Finding |
 // Re-entrancy — the guard, keyed on the turn, not on the reply
 // ---------------------------------------------------------------------------
 
-function stateDir(workspaceRoot: string): string {
-    return path.join(workspaceRoot, 'agents', 'runtime', 'state', 'turn-end-gate');
-}
-
 /**
  * ONE file per session, not one per refused turn. R2 round 1, finding 17:
  * per-turn files accumulated without bound and without a TTL, because "re-arms
  * itself with no cleanup" described the key rotating, not the files being
  * removed.
  *
- * HALF of that is fixed and half is not, stated rather than implied (R2 round 2,
- * finding 12): the per-turn MULTIPLICITY is gone, so a session no longer leaves
- * one file per refused turn. There is still no TTL and no pruning, so a
- * long-lived workspace accumulates one small file per session that ever had a
- * turn refused. Adding expiry is new behaviour and belongs with its own test.
+ * Both halves are now closed. The per-turn MULTIPLICITY went first; the missing
+ * TTL was the other half and `road-to-stop-gate-honesty` step 1.2 shipped it as
+ * `pruneAgedRefusalState`, run at `session_start` by the session-register
+ * concern — the one slot that already prunes and therefore adds no spawn. The
+ * path and the retention constant live with the reader
+ * (`_lib/turn_end_refusals.ts`), because a pruner in one module and a writer in
+ * another must not each own their own idea of where the files are.
  */
 function sessionStateFile(workspaceRoot: string, sessionKey: string): string {
-    return path.join(stateDir(workspaceRoot), `${sessionKey}.json`);
+    return sessionRefusalFile(workspaceRoot, sessionKey);
 }
 
-export function deriveSessionKey(sessionId: string): string {
-    return crypto.createHash('sha256').update(sessionId).digest('hex').slice(0, 32);
-}
+/**
+ * Re-exported, not re-derived: the session register reads this session's own
+ * refusal record back for live per-session visibility, so the stem has two
+ * consumers and exactly one definition (`_lib/turn_end_refusals.ts`).
+ */
+export { deriveSessionKey };
 
 /**
  * A turn's identity is its ORDINAL — how many genuine user prompts the
@@ -641,19 +695,53 @@ export function alreadyRefusedTurn(
     return false;
 }
 
+/**
+ * Write the re-entrancy marker AND count the refusal.
+ *
+ * The marker half is unchanged: `refused_turn` is what `alreadyRefusedTurn`
+ * reads, and nothing about the counting can alter whether a turn is refused
+ * twice. The counting half is `road-to-stop-gate-honesty` step 1.1 — the old
+ * record overwrote itself, so a session refused nine times looked exactly like a
+ * session refused once, and D-2's "refusal frequency is invisible" was true of
+ * the state file as much as of the absent reader.
+ *
+ * EVERY finding's detector is counted, not just the first. The first still lands
+ * in `detector` for compatibility with the 36 field records written before this,
+ * but a turn that trips B and C at once is two observations, and pooling them
+ * into one is what step 1.1 forbids in the reader — doing it in the writer would
+ * put the same defect somewhere the reader cannot fix.
+ */
 function markRefusedTurn(
     workspaceRoot: string,
     sessionKey: string,
     turnOrdinal: number,
-    detector: DetectorId,
+    detectors: readonly DetectorId[],
 ): void {
     if (is_replay_mode()) return;
+    const file = sessionStateFile(workspaceRoot, sessionKey);
+    let prev: RefusalRecord | null = null;
+    try {
+        prev = parseRecord(fs.readFileSync(file, 'utf-8'));
+    } catch {
+        // Absent or unreadable prior state starts a fresh count. Never a reason
+        // to skip the marker — the marker is the wedge guard.
+    }
+    let version: string | undefined;
+    try {
+        version = readInstallBoundary().version ?? undefined;
+    } catch {
+        version = undefined;
+    }
     try {
-        atomic_write_json(sessionStateFile(workspaceRoot, sessionKey), {
-            refused_at: new Date().toISOString(),
-            refused_turn: turnOrdinal,
-            detector,
-        });
+        atomic_write_json(
+            file,
+            foldRefusal(prev, {
+                detectors,
+                turnOrdinal,
+                at: new Date().toISOString(),
+                version,
+            }) as unknown as Record<string, unknown>,
+        );
     } catch {
         // A state-write failure must never wedge the turn. Losing the marker
         // costs at most one extra refusal; failing closed here would cost the
@@ -934,7 +1022,12 @@ export function main(): number {
     }
     if (findings.length === 0) return EXIT_ALLOW;
 
-    markRefusedTurn(workspaceRoot, sessionKey, turnOrdinal, findings[0]!.detector);
+    markRefusedTurn(
+        workspaceRoot,
+        sessionKey,
+        turnOrdinal,
+        findings.map((f) => f.detector),
+    );
 
     const lines = findings.map(
         (f) => `  · ${f.detector}: ${f.reason}\n    evidence: ${JSON.stringify(f.evidence)}`,

package/src/scripts/hooks/ui_route_nudge_hook.ts

@@ -30,9 +30,12 @@
  * degradation valve `design_slop_hook` carries, for the same reason: an agent
  * that has decided to proceed must not be re-prompted into a loop.
  *
- * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `pre_tool_use` exists on three
- * hosts. Everywhere else this concern has nowhere to bind and the obligation
- * stays model-carried, exactly as the two rules already declare. Run
+ * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `pre_tool_use` is BOUND on three
+ * hosts. Everywhere else the obligation stays model-carried, exactly as the two
+ * rules already declare. Corrected 2026-08-17: this comment said the concern has
+ * "nowhere to bind" elsewhere, which the manifest's own `native_event_aliases`
+ * table refutes for cursor, cline and gemini — unbound, not unbindable. See
+ * `docs/contracts/hook-architecture-v1.md` § Which hosts carry pre_tool_use. Run
  * `agent-config hooks:status` for the host you are actually on.
  *
  * Default-OFF: no-ops unless `hooks.ui_route_nudge.enabled: true`.