@event4u/agent-config 14.1.0 → 14.4.0

package/src/scripts/hooks/dispatch_hook.ts

@@ -32,6 +32,7 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import * as tty from "node:tty";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parse as parseYaml } from "yaml";
 
@@ -42,12 +43,15 @@ import {
   is_replay_mode,
 } from "./state_io.js";
 import { log_dispatch_issue, fix_hint } from "./dispatch_issues.js";
+import { shapeAndRecord, type ConcernMessage } from "./injection_budget.js";
 import { CONCERN_REGISTRY, type ConcernMain } from "./concern_registry.js";
 import {
   setHookStdinOverride,
   clearHookStdinOverride,
+  readFd0ToEnd,
 } from "./hook_stdin.js";
 import { emitFor, type Severity } from "./host_semantics.js";
+import { _concern_body_classes, planPayloadShapes } from "./payload_stub.js";
 import { resolveSessionRole, type SessionRole } from "../_lib/session_role.js";
 
 // Free-form JSON values flow through every helper here; a documented
@@ -174,8 +178,58 @@ export function _parse_concern_stdout(stdout_text: string): JsonObject {
  * always ships the `yaml` package, so this mirrors the PyYAML-present
  * 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.
+ *
+ * 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.
+ */
+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)}`;
+}
+
 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.
+  //
+  // 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.
+  //
+  // Reading the YAML unconditionally costs ~0 ms (it is the PARSE that is
+  // expensive), so the fast path still skips ~20 ms.
   const text = fs.readFileSync(p, "utf-8");
+  const compiled = p.replace(/\.ya?ml$/u, ".json");
+  if (compiled !== p) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(compiled, "utf-8")) as JsonValue;
+      if (
+        _isObject(raw) &&
+        raw["fingerprint"] === _manifest_fingerprint(text) &&
+        _isObject(raw["manifest"])
+      ) {
+        return raw["manifest"];
+      }
+    } catch {
+      // Missing, unreadable or malformed → fall through to the YAML source.
+      // Never fail the dispatch on the optimisation.
+    }
+  }
   const data = parseYaml(text, { version: "1.1" }) as JsonValue;
   return _isObject(data) ? data : {};
 }
@@ -665,6 +719,31 @@ function _resolve_tsx_invocation(
  * fail-open; the latency budget gate (hook-latency-budget.json) is the
  * standing regression net.
  */
+/**
+ * ## Why this still re-serialises the envelope per concern (step 1.1, MEASURED NULL)
+ *
+ * `setHookStdinOverride` takes text, so every concern re-stringifies the whole
+ * envelope — tool result included. On `post_tool_use` with the claude chain
+ * bound that is eleven serialisations of the same payload per tool call, which
+ * `road-to-per-turn-hook-economy` D-2 named as a cost worth removing.
+ *
+ * It was removed, measured against a pre-registered bar, and **put back**. Two
+ * A/B runs on one machine, 2 MB payload, bundle arm, `post_tool_use` p50:
+ * 166 → 135 ms (−18.7 %) at n=15, then 139 → 143 ms (**+2.9 %**) at n=25. The
+ * runs disagree in SIGN, and the within-arm spread (p95 190–228 ms on the same
+ * arm) is larger than the effect. That is the pre-registration's kill outcome:
+ * under 5 %, publish the null and stop the phase.
+ *
+ * So the hoist is not here, deliberately, and this comment is the reason —
+ * without it the next reader re-derives an "obvious" optimisation that has
+ * already been tried and did not pay.
+ *
+ * One property to preserve if anyone re-attempts it: share the **serialised
+ * string**, never a parsed object. The per-concern re-serialisation is
+ * accidentally an isolation boundary (risk 1), and a string cannot be mutated by
+ * one concern for the next. Pinned by
+ * `tests/scripts/hooks/dispatch_envelope_isolation.test.ts`.
+ */
 function _run_concern_inproc(
   main_fn: ConcernMain,
   concern: ConcernDef,
@@ -911,10 +990,18 @@ function _write_feedback(
     "decision",
     "reason",
     "duration_ms",
+    "payload_bodies",
+    "payload_stubs",
   ]);
   const summary: JsonObject = {
     schema_version: 1,
     session_id,
+    // Run-level roll-up of step 2.1's counter: how many payload bodies this
+    // dispatch omitted across the whole chain. A number, never a body.
+    payload_stubs_served: entries.reduce(
+      (n, e) => n + (typeof e["payload_stubs"] === "number" ? e["payload_stubs"] : 0),
+      0,
+    ),
     platform: (envelope["platform"] ?? null) as JsonValue,
     event: (envelope["event"] ?? null) as JsonValue,
     native_event: (envelope["native_event"] || "") as JsonValue,
@@ -1116,7 +1203,34 @@ export function main(argv?: string[]): number {
     }
   }
 
-  const payload_text = process.stdin.isTTY ? "" : _readStdin();
+  // `tty.isatty(0)`, NOT `process.stdin.isTTY`: reading the latter constructs
+  // the stdin stream and puts fd 0 into non-blocking mode, after which the read
+  // below throws EAGAIN on any payload above the pipe buffer and silently
+  // yields an EMPTY envelope. That is a measured guard bypass, not a theory —
+  // see readFd0ToEnd's header in hooks/hook_stdin.ts.
+  const payload_text = tty.isatty(0) ? "" : _readStdin();
+  if (_stdin_read_failed !== null) {
+    // NEVER silent: an empty envelope reached from a failed read means every
+    // guard on this event evaluated nothing. The exit code is unchanged (see
+    // `_stdin_read_failed`), so this line and the dispatch issue are the only
+    // signal that the chain ran blind.
+    process.stderr.write(
+      `dispatch_hook: STDIN READ FAILED (${_stdin_read_failed}) — the concern ` +
+        `chain for '${args.event}' ran against an EMPTY payload and could not ` +
+        `evaluate anything. This is not an empty stdin.\n`,
+    );
+    try {
+      log_dispatch_issue(
+        process.cwd(),
+        "dispatcher",
+        "execution_failed",
+        `stdin read failed on ${args.event}: ${_stdin_read_failed} — chain ran with an empty payload`,
+        fix_hint(),
+      );
+    } catch {
+      // observability never breaks the hook
+    }
+  }
   _maybe_capture_payload(args, payload_text);
   const session_role = resolveSessionRole(process.env);
   const refusal_retry = _is_refusal_retry(args.event, payload_text);
@@ -1156,17 +1270,42 @@ export function main(argv?: string[]): number {
   // feedback_entries on purpose: that record is written to disk with a
   // fixed-field schema (PII-exclusion-by-construction), and a concern's raw
   // stderr is free-form content. This array is in-memory only.
-  const concern_messages: Array<{ rc: number; text: string }> = [];
+  const concern_messages: ConcernMessage[] = [];
   // Per-concern `tools:` filter (see _concern_matches_tool). Applied here so it
   // is one place, after the envelope exists and before any concern is spawned.
   const tool_name = _payload_tool_name(envelope);
-  for (const concern of concerns) {
+  // Payload opt-in (step 2.1). There are at most FOUR distinct envelope shapes
+  // per dispatch (keep neither / input / result / both), so they are memoised
+  // by keep-set: concerns sharing a declaration share one clone, and building
+  // one per concern would re-pay the allocation the stub exists to avoid.
+  // `present` is the set of body classes this event actually carries — empty on
+  // every non-tool event, which is why those pay nothing at all.
+  // Payload opt-in (step 2.1). One planner owns the whole decision — which
+  // 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 keep_by_concern = concerns.map(
+    (c) => [c, _concern_body_classes(c)] as const,
+  );
+  const shapes = planPayloadShapes(
+    envelope,
+    keep_by_concern.map(([, keep]) => keep),
+  );
+  for (const [concern, keep_classes] of keep_by_concern) {
     if (!_concern_matches_tool(concern, tool_name)) {
       continue;
     }
+    const concern_envelope = shapes.shapeFor(keep_classes);
+    const stubs_served = shapes.stubsFor(keep_classes);
+    // What was actually SERVED, not what was declared. Recording the
+    // declaration made the record wrong in both directions on a body-less
+    // event: a blocking `stop` concern read "input,result" for bodies it can
+    // never receive, and an advisory one read "none" while the full envelope
+    // went to it untouched.
+    const served_classes = shapes.servedBy(keep_classes);
     const concern_started = _now_iso();
     const { rc: rawRcResult, stderr: stderr_text, stdout: stdout_text, duration_ms } =
-      _run_concern(concern, envelope);
+      _run_concern(concern, concern_envelope);
     let rc = rawRcResult;
     const raw_rc = rc;
     if (rc >= 3) {
@@ -1217,7 +1356,7 @@ export function main(argv?: string[]): number {
         : "";
     const message = [stated, extra].filter(Boolean).join("\n\n");
     if (message) {
-      concern_messages.push({ rc, text: message });
+      concern_messages.push({ rc, text: message, def: concern });
     }
     if (
       args.event === "session_start" &&
@@ -1238,6 +1377,15 @@ export function main(argv?: string[]): number {
       started_at: concern_started,
       completed_at: _now_iso(),
       fail_closed: Boolean(concern["fail_closed"]),
+      // Step 2.1's counter — an EXPOSURE denominator, not a detector, and the
+      // review was right to refuse the stronger reading: these numbers are a
+      // function of the declaration and the payload shape, so they say how
+      // often a concern ran without a body, never whether it wanted one. The
+      // detector for the wanting-one case is the source-derived check in
+      // `lint_hook_manifest`, at authoring time, where it is decidable.
+      // A sorted class list and an integer — nothing that can hold a body.
+      payload_bodies: served_classes.join(",") || "none",
+      payload_stubs: stubs_served,
     });
   }
   const final_rc = _reduce(rcs);
@@ -1253,9 +1401,13 @@ export function main(argv?: string[]): number {
   // disagree: on Claude Code exit 1 does not block and exit 2 does, which
   // inverted every verdict (see host_semantics.ts for the documented mapping).
   // Unverified platforms keep the legacy pass-through byte-for-byte.
-  const decidingReasons = concern_messages
-    .filter((m) => m.rc === final_rc)
-    .map((m) => m.text);
+  // Emission shaping (nudge exclusivity + per-turn byte ceiling) also owns the
+  // deciding-severity filter this line used to apply. See injection_budget.ts.
+  const decidingReasons = shapeAndRecord(
+    { packageRoot: REPO_ROOT, envelope, platform: args.platform, event: args.event },
+    concern_messages,
+    final_rc,
+  );
   const emission = emitFor(
     args.platform,
     args.event,
@@ -1285,10 +1437,31 @@ function _sortedRepr(s: ReadonlySet<string>): string {
   return `[${items.map((x) => `'${x}'`).join(", ")}]`;
 }
 
+/**
+ * Set when the stdin read FAILED, as distinct from stdin being genuinely empty.
+ *
+ * The two were indistinguishable, and that was the second half of the bypass
+ * F-1 records: removing the EAGAIN *trigger* still left `catch { return "" }`
+ * converting any residual failure — an exhausted retry budget, `EIO`, `EBADF` —
+ * into "no input", after which the whole chain runs with no `tool_name` and the
+ * dispatcher exits 0. For a `fail_closed: true`, `severity: blocking` guard that
+ * is an allow, emitted silently. Found by the R2 review.
+ *
+ * The failure is now LOUD (stderr + a dispatch issue) while the allow/deny
+ * decision is unchanged. Turning a failed read into a DENY is a policy change on
+ * a security surface, so it is filed as `b-stdin-read-failure-policy` rather than
+ * improvised here: an unreadable payload on a block-capable event arguably must
+ * refuse, and that call is the maintainer's.
+ */
+let _stdin_read_failed: string | null = null;
+
 function _readStdin(): string {
   try {
-    return fs.readFileSync(0, "utf-8");
-  } catch {
+    // Reads to EOF and retries on EAGAIN rather than treating it as empty
+    // input; shared with the concern-side reader so both paths cannot drift.
+    return readFd0ToEnd();
+  } catch (exc) {
+    _stdin_read_failed = exc instanceof Error ? exc.message : String(exc);
     return "";
   }
 }

package/src/scripts/hooks/dispatch_issues.ts

@@ -42,6 +42,32 @@ export const VALID_ISSUE: ReadonlySet<string> = new Set([
   "script_not_found",
   "permission_denied",
   "execution_failed",
+  // road-to-standing-context-40k Phase 4. The four codes above all mean "a
+  // concern tried to run and could not". These two mean the opposite — the
+  // concern ran, produced its line, and the DISPATCHER decided not to emit it.
+  // They share this log because it is already the place a reader looks to find
+  // out why an expected hook effect never appeared, and a suppressed advisory
+  // is exactly that question. The distinct codes keep the two classes
+  // separable: `hooks_doctor` surfaces the whole log, and a budget drop must
+  // not read as a broken hook.
+  "injection_budget_drop",
+  "nudge_interference_drop",
+]);
+
+/**
+ * The subset of `VALID_ISSUE` that records a POLICY OUTCOME rather than a
+ * concern failure — the concern ran correctly and the dispatcher chose not to
+ * emit it.
+ *
+ * Exported so the diagnostic consumers can tell the two classes apart instead of
+ * inferring it from a name. `hooks_doctor` filters these out of its
+ * "hooks tried to fire but couldn't" view: that view's CTA is a reinstall, which
+ * fixes nothing here, and these fire as routine per-dispatch traffic that would
+ * otherwise push a real failure out of the last-20 window.
+ */
+export const POLICY_OUTCOME_ISSUES: ReadonlySet<string> = new Set([
+  "injection_budget_drop",
+  "nudge_interference_drop",
 ]);
 
 export interface DispatchIssueEntry {

package/src/scripts/hooks/end_review_nudge_hook.ts

@@ -25,8 +25,8 @@
  *
  * `git diff --numstat HEAD` at `workspace_root`: the working tree vs the
  * last commit, TRACKED files only, PLUS every untracked non-doc file
- * (`git ls-files --others --exclude-standard`, one `git diff --numstat
- * --no-index /dev/null <file>` per file — see "Untracked files" below;
+ * (`git ls-files --others --exclude-standard`, each one READ from the
+ * filesystem rather than diffed in a subprocess — see "Untracked files" below;
  * fixes a review finding, F6, that a brand-new file was previously invisible
  * to this count entirely). Chosen over a session-start SHA/timestamp
  * baseline because no such baseline exists anywhere a `stop` concern can
@@ -52,10 +52,15 @@
  * that authored a brand-new 300-line module was previously measured as a
  * 0-line mutation. `untrackedNonDocFiles` lists the candidates
  * (`git ls-files --others --exclude-standard`, filtered by the same
- * `isDocPath` carve-out); `untrackedFileLineCount` sizes each one via
- * `git diff --no-index /dev/null <file>` (the only way to diff a path git's
- * index has never seen). Past `UNTRACKED_FILE_CAP` untracked non-doc files
- * this hook refuses to spawn one subprocess per file — an unbounded loop is
+ * `isDocPath` carve-out); `untrackedFileLineCount` sizes each one by READING
+ * IT — an untracked file's diff against nothing is its own content, so the
+ * count needs no git. It used to spawn `git diff --no-index /dev/null <file>`
+ * per file, on the Stop slot; step 3.2 of `road-to-per-turn-hook-economy`
+ * removed that process and preserved both edges that could otherwise move a
+ * threshold decision silently (a binary file counts 0, an unterminated last
+ * line still counts). The CAP is unchanged and still the outer bound: past
+ * `UNTRACKED_FILE_CAP` untracked non-doc files
+ * this hook refuses to read them all — an unbounded loop is
  * worse than an imprecise answer — and instead reports a line count
  * GUARANTEED to be over `MUTATION_LINE_THRESHOLD`: "many new files this
  * session" is itself sufficient signal to fire without the exact count.
@@ -224,10 +229,14 @@ import { atomic_write_json, is_replay_mode } from './state_io.js';
 export const MUTATION_LINE_THRESHOLD = 50;
 
 /**
- * Untracked non-doc files past which this hook refuses to spawn one
- * `git diff --no-index` subprocess per file and instead reports the
- * mutation as certainly over threshold (F6, review — see the file header's
- * "Untracked files" section).
+ * Untracked non-doc files past which this hook refuses to size them at all and
+ * instead reports the mutation as certainly over threshold (F6, review — see the
+ * file header's "Untracked files" section).
+ *
+ * It bounds the file COUNT. The per-file byte bound is separate and lives in
+ * `untrackedFileLineCount`: since step 3.2 replaced the per-file subprocess with
+ * a read, an unbounded read would move an arbitrarily large file INTO this
+ * process, which the subprocess never did.
  */
 export const UNTRACKED_FILE_CAP = 20;
 
@@ -366,21 +375,84 @@ export function untrackedNonDocFiles(cwd: string): string[] {
 }
 
 /**
- * Added+deleted line count for ONE untracked file, via
- * `git diff --numstat --no-index /dev/null <relPath>` — the only way to
- * diff a path git's index has never seen. `--no-index` exits `1` whenever a
- * diff exists (by design, unlike `gitNumstatRows`'s tracked-diff contract,
- * where a nonzero status means failure) — only the parsed numstat rows
- * matter here, never the exit code. Fails closed to `0`, never throws.
+ * Leading bytes probed for a NUL when deciding whether an untracked file is
+ * binary. git uses its own leading-block heuristic for the same call; the point
+ * of matching the size is that both agree on which files count as binary, not
+ * that either is exhaustive.
+ */
+export const BINARY_PROBE_BYTES = 8000;
+
+/**
+ * Per-file read ceiling for the untracked-file line count.
+ *
+ * `UNTRACKED_FILE_CAP` bounds how MANY files are sized; nothing bounded how
+ * LARGE one of them may be, and that gap arrived with step 3.2: the
+ * `git diff --no-index` subprocess it replaced never materialised file content in
+ * the hook process, while a `readFileSync` does. One untracked-but-not-ignored
+ * dataset or media file would then cost a full allocation plus an O(n) byte scan
+ * at every turn end, and past ~2 GiB the read throws and silently counts 0.
+ * Found by the R2 review.
+ *
+ * 8 MiB is far above any hand-written source file and far below a size worth
+ * allocating on the Stop path. A file over it is counted as
+ * `MUTATION_LINE_THRESHOLD + 1` rather than 0: "a huge new file appeared" is a
+ * mutation, and the old code's answer for an unreadable file — zero — is the
+ * direction that hides one.
+ */
+export const UNTRACKED_FILE_READ_CAP_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Added line count for ONE untracked file, read from the filesystem.
+ *
+ * **No subprocess (road-to-per-turn-hook-economy step 3.2 / D-3).** This used to
+ * run `git diff --numstat --no-index /dev/null <relPath>`, one spawn per
+ * untracked non-doc file, on the Stop slot — so a workspace with nineteen new
+ * files paid nineteen `git` process starts at every turn end. An untracked
+ * file's diff against nothing is just its own content, so the count needs no
+ * git at all.
+ *
+ * Behaviour is preserved rather than improved, in both directions that could
+ * silently change a threshold decision: a binary file still counts 0 (numstat
+ * printed a dash per side and `parseNumstat` mapped that to 0), and a file whose
+ * last line lacks a trailing newline still counts that line.
+ *
+ * The remaining bound is unchanged and lives one level up:
+ * `totalNonDocMutatedLinesWithMeasure` still refuses to read more than
+ * `UNTRACKED_FILE_CAP` files and returns a labelled `capped_approximation`
+ * instead — "many new files this session" is signal enough without an exact
+ * count. What 3.2 removes is the per-file *process*, not the cap.
+ *
+ * Fails closed to `0` and never throws, exactly as the spawn version did.
  */
 export function untrackedFileLineCount(cwd: string, relPath: string): number {
     try {
-        const r = spawnSync('git', ['diff', '--numstat', '--no-index', '/dev/null', relPath], {
-            cwd,
-            encoding: 'utf8',
-            maxBuffer: 16 * 1024 * 1024,
-        });
-        return parseNumstat(r.stdout ?? '').reduce((sum, row) => sum + row.added + row.deleted, 0);
+        const abs = path.resolve(cwd, relPath);
+        // Size before read: the point of the cap is not to allocate the file.
+        const size = fs.statSync(abs).size;
+        if (size === 0) return 0;
+        if (size > UNTRACKED_FILE_READ_CAP_BYTES) {
+            return MUTATION_LINE_THRESHOLD + 1;
+        }
+        const buf = fs.readFileSync(abs);
+        if (buf.length === 0) return 0;
+        // Binary detection, matching what this function replaced rather than
+        // improving on it: numstat prints a dash for each side of a binary file
+        // and `parseNumstat` maps a dash to 0, so a binary file contributed 0
+        // lines before and must contribute 0 now. Counting newline bytes in
+        // binary content would invent mutation volume out of image data. git's
+        // own heuristic is a NUL byte in the leading block, so the same block
+        // size is used here and the two agree on the same files.
+        const probe = buf.subarray(0, Math.min(buf.length, BINARY_PROBE_BYTES));
+        if (probe.includes(0)) return 0;
+        // The replaced spawn reported every line of the file as added, INCLUDING
+        // a final line with no trailing newline. Counting newline bytes alone
+        // would be one short on exactly the files an editor leaves unterminated.
+        let lines = 0;
+        for (const byte of buf) {
+            if (byte === 0x0a) lines += 1;
+        }
+        if (buf[buf.length - 1] !== 0x0a) lines += 1;
+        return lines;
     } catch {
         return 0;
     }
@@ -399,8 +471,9 @@ export interface MutationMeasurement {
  * HEAD`) and untracked (`git ls-files --others --exclude-standard`) files —
  * see the file header's "Untracked files (F6)" section for why both sources
  * are required. Past `UNTRACKED_FILE_CAP` untracked non-doc files this
- * function refuses to spawn one `git diff --no-index` subprocess per file
- * (an unbounded loop) and instead returns a value GUARANTEED to be over
+ * function refuses to size them individually at all (what used to be an
+ * unbounded spawn loop, and is now an unbounded read loop) and instead returns a
+ * value GUARANTEED to be over
  * `MUTATION_LINE_THRESHOLD` — "many new files this session" is itself
  * sufficient signal, no exact count needed. `measure` records WHICH of
  * those two shapes the returned `lines` value is, so a consumer (the

package/src/scripts/hooks/hook_stdin.ts

@@ -12,13 +12,17 @@
  * Contract:
  *   - Standalone invocation (a concern run directly as its own process —
  *     the historical path, still supported): no override is set, and
- *     `readHookStdin()` falls through to `fs.readFileSync(0, 'utf-8')`.
+ *     `readHookStdin()` falls through to a retrying fd-0 read (see
+ *     `readFd0ToEnd` — a plain `fs.readFileSync(0)` here was a measured guard
+ *     bypass on large payloads).
  *   - In-process invocation: the dispatcher calls
  *     `setHookStdinOverride(raw)` before the concern's `main()` and
  *     `clearHookStdinOverride()` after. Nesting is not supported (concerns
  *     never dispatch concerns).
  */
-import * as fs from 'node:fs';
+import * as tty from 'node:tty';
+
+import { readStdinText } from '../_lib/stdin.js';
 
 let _override: string | null = null;
 
@@ -30,12 +34,114 @@ export function clearHookStdinOverride(): void {
     _override = null;
 }
 
-/** TTY-safe stdin read: injected override first, else fd 0, else "". */
+/**
+ * Read fd 0 to EOF, correctly, for a payload of any size.
+ *
+ * Delegates to `_lib/stdin.readStdinText`, which already carries this exact
+ * defect's history (EAGAIN on a pipe larger than its buffer, measured 2026-08-04
+ * on a CI diff), a bounded retry budget, and the contract that matters here:
+ * **it never substitutes an empty string for a failed read.** A second
+ * implementation in this file would have been a worse copy of an audited one.
+ *
+ * ## The hook-side half of the defect (measured 2026-08-18)
+ *
+ * Knowing the read is fragile was not enough, because the *trigger* lived
+ * somewhere else. `dispatch_hook` guarded the read with `process.stdin.isTTY`,
+ * and merely READING that property lazily constructs the stdin stream, which
+ * puts fd 0 into non-blocking mode. So the guard is what made its own read fail:
+ *
+ * 1. `process.stdin.isTTY` → fd 0 becomes non-blocking.
+ * 2. `fs.readFileSync(0)` → `EAGAIN` once the payload exceeds the pipe buffer.
+ * 3. `catch { return '' }` → "no input", and the dispatcher proceeds against an
+ *    EMPTY envelope and exits 0.
+ *
+ * Reproduced on the shipped bundle: a `PreToolUse` payload carrying
+ * `git commit --no-verify` was DENIED small and ALLOWED once padded to 300 KB,
+ * because `block-no-verify` never saw a command. Padding is not exotic — a
+ * `PostToolUse` `tool_response` holding a large file read reaches these sizes
+ * routinely.
+ *
+ * Hence both halves, since either alone is a single point of failure:
+ * **`tty.isatty(0)`** answers the TTY question without constructing the stream,
+ * and **the retrying reader** holds even if something else in the process touched
+ * `process.stdin` first. Pinned by
+ * `tests/scripts/hooks/dispatch_large_payload_guard.test.ts`, which fails on the
+ * pre-fix bundle.
+ */
+/**
+ * Wait for the FIRST byte, in ms, before concluding fd 0 is idle. See
+ * {@link readFd0ToEnd} for why an idle fd 0 must be cheap and a busy one must
+ * not be truncated.
+ */
+export const HOOK_FIRST_BYTE_TIMEOUT_MS = 25;
+
+/**
+ * Read fd 0 to EOF for a payload of any size, without stalling when there is no
+ * payload at all.
+ *
+ * ## Two coupled properties, and it took three attempts to see that they were coupled
+ *
+ * 1. **A large payload must not truncate.** `fs.readFileSync(0)` returned `''`
+ *    once the payload exceeded the pipe buffer, and the caller's
+ *    `catch { return '' }` made that indistinguishable from empty input. That is
+ *    the guard bypass F-1 records: a `PreToolUse` payload carrying
+ *    `git commit --no-verify` was DENIED small and ALLOWED once padded to 300 KB.
+ * 2. **An idle fd 0 must be cheap.** A concern also runs with fd 0 simply open
+ *    and never written — a child that inherits stdin, or a test that calls
+ *    `main()` in-process under vitest. A read that blocks there hangs the caller
+ *    outright.
+ *
+ * The old code satisfied (2) **by accident, through the very bug that broke (1)**:
+ * reading `process.stdin.isTTY` constructs the stdin stream, which puts fd 0 into
+ * non-blocking mode, so the following `readFileSync` failed fast with EAGAIN on an
+ * idle fd — and equally on a large one. Removing the probe fixed (1) and broke (2)
+ * in the worst way: `fs.readSync` on a blocking, open, unwritten fd does not
+ * return EAGAIN, it BLOCKS, so no retry budget can bound it. Measured: a whole
+ * test file that calls a concern in-process never finished, and three CI shards
+ * hung for over an hour.
+ *
+ * So the non-blocking mode is now **deliberate** rather than a side effect, and
+ * the retry loop is what makes it safe:
+ *
+ * - Touch `process.stdin` on purpose to put fd 0 in non-blocking mode, so a read
+ *   can never block. This is the one place in the tree that wants that effect;
+ *   everywhere else it is the hazard `dispatch_hook` documents.
+ * - Read through `_lib/stdin.readStdinText`, which retries on EAGAIN instead of
+ *   reporting it as empty input — that is what fixes (1).
+ * - Cap the wait for the FIRST byte, and cap it SHORT. The host writes the
+ *   payload before the child can run, so the first read either returns data or
+ *   means nothing is coming; the 25 ms exists only to absorb a scheduling race
+ *   between the parent's first write and the child's first read, not to wait for
+ *   a slow writer. It was 500 ms for one iteration and that was already too
+ *   expensive — 7 in-process concern calls in one test file paid 3.5 s of pure
+ *   waiting. Once any byte HAS arrived the full ~10 s budget applies, so a
+ *   multi-megabyte payload is unaffected.
+ *
+ * Both directions are pinned by
+ * `tests/scripts/hooks/dispatch_large_payload_guard.test.ts`, which fails on the
+ * pre-fix bundle for (1) and times out for (2) — fixing either alone reintroduces
+ * the other.
+ */
+export function readFd0ToEnd(): string {
+    // Deliberate: constructing the stream sets O_NONBLOCK on fd 0, which is the
+    // only portable way to guarantee the reads below cannot block. Node exposes
+    // no direct O_NONBLOCK call for an existing descriptor.
+    void process.stdin;
+    return readStdinText(0, { firstByteTimeoutMs: HOOK_FIRST_BYTE_TIMEOUT_MS });
+}
+
+/**
+ * TTY-safe stdin read: injected override first, else fd 0, else "".
+ *
+ * `tty.isatty(0)` rather than `process.stdin.isTTY`, and `readFd0ToEnd` rather
+ * than `fs.readFileSync(0)` — see `readFd0ToEnd`'s header for the silent
+ * large-payload truncation both halves prevent.
+ */
 export function readHookStdin(): string {
     if (_override !== null) return _override;
     try {
-        if (process.stdin.isTTY) return '';
-        return fs.readFileSync(0, 'utf-8');
+        if (tty.isatty(0)) return '';
+        return readFd0ToEnd();
     } catch {
         return '';
     }