@event4u/agent-config 13.0.0 → 14.0.0

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_doctor.ts

@@ -34,6 +34,13 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { read_dispatch_issues } from "./hooks/dispatch_issues.js";
 import { type JsonObject, type JsonValue, _load_yaml } from "./hooks/dispatch_hook.js";
 import * as hooks_status from "./hooks_status.js";
+import {
+  DETECTOR_IDS,
+  collectRefusalStats,
+  readInstallBoundary,
+  type InstallBoundary,
+  type RefusalStats,
+} from "./_lib/turn_end_refusals.js";
 
 // src/scripts/hooks_doctor.ts → parents[2] (../../..) is the repo root,
 // mirroring the Python `Path(__file__).resolve().parents[2]`.
@@ -171,6 +178,17 @@ export interface DoctorPayload {
   concerns: ConcernRow[];
   trampolines: TrampolineRow[];
   dispatch_issues: JsonObject[];
+  /**
+   * Turn-end refusals, per detector, from this workspace's own records.
+   *
+   * `road-to-stop-gate-honesty` § D-2: every advisory concern in this estate
+   * carries a registered kill standard and the one BLOCKING concern carries
+   * none, because nobody could see how often it fires. The doctor is where a
+   * concern's health is already read, so this is where the number belongs.
+   */
+  turn_end_refusals: RefusalStats;
+  /** The machine's install stamp, for reading the version split below it. */
+  install_boundary: InstallBoundary;
 }
 
 /** Build the doctor payload — JSON-serialisable. */
@@ -229,12 +247,31 @@ export function collect(
     issues = [];
   }
 
+  let turn_end_refusals: RefusalStats;
+  try {
+    turn_end_refusals = collectRefusalStats(project_root);
+  } catch {
+    turn_end_refusals = {
+      sessionsWithRefusals: 0,
+      total: 0,
+      byDetector: { promissory: 0, language: 0, verification: 0, completion: 0 },
+      byPeriod: [],
+      legacyRecords: 0,
+      unversionedRecords: 0,
+      byVersion: [],
+      earliest: null,
+      latest: null,
+    };
+  }
+
   return {
     schema_version: 1,
     platforms: matrix.platforms,
     concerns,
     trampolines,
     dispatch_issues: issues,
+    turn_end_refusals,
+    install_boundary: readInstallBoundary(),
   };
 }
 
@@ -242,6 +279,79 @@ function _strVal(v: JsonValue | undefined): string {
   return v === undefined || v === null ? "undefined" : String(v);
 }
 
+/**
+ * The turn-end-gate's own number.
+ *
+ * Reports what the records can support and refuses the number they cannot: the
+ * denominator is *sessions that had at least one refusal*, never all sessions,
+ * because a session that was never refused writes no record. Labelling a
+ * per-refused-session figure as a per-session rate would be the same
+ * denominator inflation this estate's measurement discipline exists to stop.
+ */
+export function _render_refusals(payload: DoctorPayload): string[] {
+  const s = payload.turn_end_refusals;
+  const lines: string[] = [];
+  lines.push("Turn-end refusals");
+  lines.push("-".repeat(60));
+  if (s.sessionsWithRefusals === 0) {
+    lines.push("·  no refusal records under agents/runtime/state/turn-end-gate/");
+    return lines;
+  }
+  const perSession = (s.total / s.sessionsWithRefusals).toFixed(2);
+  lines.push(
+    `   ${s.total} refusal(s) across ${s.sessionsWithRefusals} session(s) ` +
+      `that were refused at least once — ${perSession} per such session.`,
+  );
+  lines.push(
+    "   NOT a per-session rate: sessions with no refusal write no record, so " +
+      "the wider denominator is unavailable here by construction.",
+  );
+  if (s.earliest && s.latest) {
+    lines.push(`   window: ${s.earliest.slice(0, 10)} … ${s.latest.slice(0, 10)}`);
+  }
+  for (const id of DETECTOR_IDS) {
+    const n = s.byDetector[id];
+    const share = s.total > 0 ? Math.round((n / s.total) * 100) : 0;
+    lines.push(`   ${id.padEnd(14)} ${String(n).padStart(4)}  ${share}%`);
+  }
+  if (s.legacyRecords > 0) {
+    lines.push(
+      `   ${s.legacyRecords} record(s) predate per-detector counting and ` +
+        "contribute one refusal each — the total is a FLOOR, not an exact count.",
+    );
+  }
+  const boundary = payload.install_boundary;
+  if (boundary.version || boundary.installed_at) {
+    lines.push(
+      `   installed: ${boundary.version ?? "(unknown version)"} at ` +
+        `${boundary.installed_at ?? "(unknown date)"}`,
+    );
+  }
+  if (s.byVersion.length > 0) {
+    lines.push("   by recorded version:");
+    for (const v of s.byVersion) {
+      lines.push(`     ${v.version.padEnd(16)} ${String(v.total).padStart(4)}`);
+    }
+    if (s.unversionedRecords > 0) {
+      lines.push(
+        "     (unrecorded) rows predate version stamping — they cannot test " +
+          "the install-date prediction in either direction.",
+      );
+    }
+  }
+  const recent = s.byPeriod.slice(0, 7);
+  if (recent.length > 0) {
+    lines.push("   most recent days:");
+    for (const p of recent) {
+      lines.push(
+        `     ${p.period}  ${String(p.total).padStart(3)} refusal(s) / ` +
+          `${p.sessions} session(s)`,
+      );
+    }
+  }
+  return lines;
+}
+
 export function _render_table(payload: DoctorPayload): string {
   const lines: string[] = [];
   // Phase 1 CTA — surfaces at the TOP when issues exist, so a user
@@ -286,6 +396,8 @@ export function _render_table(payload: DoctorPayload): string {
     const suffix = t.required ? "" : "  (not required)";
     lines.push(`${marker}${t.platform.padEnd(9)} ${t.expected}${suffix}`);
   }
+  lines.push("");
+  lines.push(..._render_refusals(payload));
   // Dispatch-issues detail — last 20 grouped by concern.
   if (payload.dispatch_issues.length > 0) {
     lines.push("");