@event4u/agent-config 14.7.0 → 14.9.0

package/src/scripts/hooks/host_semantics.ts

@@ -78,6 +78,27 @@ const CLAUDE_BLOCK_CAPABLE_EVENTS: ReadonlySet<string> = new Set([
     "stop",
 ]);
 
+/**
+ * Does this (platform, event) pair let a hook actually REFUSE the action?
+ *
+ * Exported because a second consumer now needs the same fact and must not
+ * re-derive it: `dispatch_hook`'s stdin-read-failure policy denies only where a
+ * deny is honoured (`b-stdin-read-failure-policy`, option (c)). A copy of
+ * `CLAUDE_BLOCK_CAPABLE_EVENTS` one module away is a copy that drifts, and the
+ * drift direction here is the dangerous one: a stale copy would deny on a slot
+ * where the deny is discarded, refusing nothing while looking like enforcement.
+ *
+ * An unverified platform is NOT block-capable by this predicate, and that is
+ * deliberate rather than incidental: `emitFor` hands such a platform its legacy
+ * exit code verbatim, so this tree has no evidence its host honours a deny at
+ * all. Claiming capability without evidence is the over-claim the hook-coverage
+ * corrections in this estate exist to remove.
+ */
+export function isBlockCapable(platform: string, event: string): boolean {
+    if (!VERIFIED_PLATFORMS.has(platform)) return false;
+    return CLAUDE_BLOCK_CAPABLE_EVENTS.has(event);
+}
+
 function _joinReasons(reasons: readonly string[]): string {
     return reasons.map((r) => r.trim()).filter((r) => r.length > 0).join(" · ");
 }

package/src/scripts/hooks/injection_budget.ts

@@ -196,9 +196,19 @@ export function evictionOrder(
  * Nudge exclusivity: keep the lowest `nudge_rank`, drop every other nudge.
  *
  * Ties break on concern name so the winner is stable; a tie is a manifest
- * defect rather than a runtime one, and `lint_hook_manifest` is where it should
- * eventually be caught — that check does not exist yet and this comment is the
- * honest statement of the gap, not a claim that it is covered.
+ * defect rather than a runtime one, and `lint_hook_manifest` is where it is
+ * caught — `_check_concerns` rejects a repeated non-null `nudge_rank`, naming
+ * the rank and every concern declaring it, and rejects a non-positive-integer
+ * value rather than coercing it (road-to-wiring-truth-corrections Phase 3;
+ * cases in `tests/scripts/lint_hook_manifest.test.ts`). The tie-break below
+ * therefore stays as the runtime's stable fallback for a manifest that got
+ * past the lint, not as the only thing standing between a collision and a
+ * silently non-emitting concern.
+ *
+ * The lint enforces uniqueness GLOBALLY while this selector compares within
+ * one dispatch, so the lint is deliberately the stricter of the two — see its
+ * own note for why, and narrow it rather than delete it if a design ever needs
+ * one rank on two disjoint events.
  */
 function _selectNudge(
     candidates: readonly EmissionCandidate[],

package/src/scripts/hooks/py_json_dumps.ts

@@ -0,0 +1,103 @@
+/**
+ * `json.dumps(obj, indent=n)` byte-for-byte, extracted from `dispatch_hook.ts`.
+ *
+ * Pure and self-contained: it recurses into itself and calls nothing else, which
+ * is what made it safe to move out of a dispatcher that runs on every tool call.
+ * Extracted because dispatch_hook.ts sits at the 1500-line source ceiling.
+ *
+ * For anyone tempted to share it: mcp_telemetry_store, mcp_telemetry_query and
+ * mcp_telemetry_health each define their OWN `_py_json_dumps`. They were left
+ * alone — unifying four copies is a change with its own risk, not a merge-time
+ * side effect.
+ */
+// Python json.dumps(record, indent=2) byte-for-byte (ensure_ascii=True).
+export function _py_json_dumps(value: unknown, indent: number): string {
+  const pad = " ".repeat(indent);
+  const escapeString = (s: string): string => {
+    let out = '"';
+    for (const ch of s) {
+      const code = ch.codePointAt(0) as number;
+      switch (ch) {
+        case '"':
+          out += '\\"';
+          break;
+        case "\\":
+          out += "\\\\";
+          break;
+        case "\n":
+          out += "\\n";
+          break;
+        case "\r":
+          out += "\\r";
+          break;
+        case "\t":
+          out += "\\t";
+          break;
+        case "\b":
+          out += "\\b";
+          break;
+        case "\f":
+          out += "\\f";
+          break;
+        default:
+          if (code < 0x20 || code > 0x7e) {
+            if (code > 0xffff) {
+              const c = code - 0x10000;
+              const hi = 0xd800 + (c >> 10);
+              const lo = 0xdc00 + (c & 0x3ff);
+              out +=
+                "\\u" +
+                hi.toString(16).padStart(4, "0") +
+                "\\u" +
+                lo.toString(16).padStart(4, "0");
+            } else {
+              out += "\\u" + code.toString(16).padStart(4, "0");
+            }
+          } else {
+            out += ch;
+          }
+      }
+    }
+    return out + '"';
+  };
+  const render = (v: unknown, depth: number): string => {
+    if (v === null || v === undefined) return "null";
+    if (typeof v === "boolean") return v ? "true" : "false";
+    if (typeof v === "number") {
+      if (!Number.isFinite(v)) {
+        if (Number.isNaN(v)) return "NaN";
+        return v > 0 ? "Infinity" : "-Infinity";
+      }
+      return String(v);
+    }
+    if (typeof v === "string") return escapeString(v);
+    const curPad = pad.repeat(depth + 1);
+    const closePad = pad.repeat(depth);
+    if (Array.isArray(v)) {
+      if (v.length === 0) return "[]";
+      return (
+        "[\n" +
+        v.map((item) => curPad + render(item, depth + 1)).join(",\n") +
+        "\n" +
+        closePad +
+        "]"
+      );
+    }
+    if (typeof v === "object") {
+      const obj = v as Record<string, unknown>;
+      const keys = Object.keys(obj);
+      if (keys.length === 0) return "{}";
+      return (
+        "{\n" +
+        keys
+          .map((k) => curPad + escapeString(k) + ": " + render(obj[k], depth + 1))
+          .join(",\n") +
+        "\n" +
+        closePad +
+        "}"
+      );
+    }
+    throw new TypeError(`Object of type ${typeof v} is not JSON serializable`);
+  };
+  return render(value, 0);
+}

package/src/scripts/hooks/run_continuation_hook.ts

@@ -129,6 +129,7 @@
  */
 
 import * as fs from 'node:fs';
+import { revokeBillingGrant } from '../_lib/billing_grant.js';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
@@ -599,12 +600,13 @@ function writeState(file: string, state: RunState): boolean {
  * stamp with it. Adoption is a fact this read already established; it is passed in
  * rather than re-derived from a condition that cannot express it.
  */
-function clearRunState(
+export function clearRunState(
     workspaceRoot: string,
     runId: string,
     keyedFile: string,
     adoptedLegacy: boolean,
 ): void {
+    revokeBillingGrant(workspaceRoot, runId); // the run IS the grant's TTL
     try {
         fs.rmSync(keyedFile, { force: true });
     } catch {

package/src/scripts/hooks/state_io.ts

@@ -540,7 +540,9 @@ function _atomic_write_text(target: string, text: string): void {
  * Layout:
  *     <state_root>/.dispatcher/<session_id>/
  *         <concern>.json     — one per concern that ran
- *         summary.json       — rollup written by the dispatcher
+ *         summary.json       — capped list of per-invocation rollups
+ *                              (schema 2; see hook-architecture-v1 for why
+ *                              a single rollup object lost one per overlap)
  *
  * Per Council Round 2 (2026-05-04): exit-code reduction collapses
  * multiple concern signals into a single platform-native code; the
@@ -1003,6 +1005,91 @@ export function owns_session_state(state: unknown, session_id: string): boolean
  * sites at the time of the change and both were converted; a new caller must
  * compare against a member of the union, never coerce to a boolean.
  */
+/**
+ * Read a TEXT file, transform it, and write it back — the WHOLE sequence under
+ * one lock.
+ *
+ * The text sibling of {@link update_json_under_lock}, added for P3 of
+ * `b-stop-async-split-prerequisites` (council 2026-08-20, option (a),
+ * "P3 before anything else"). The concrete case is
+ * `agents/runtime/state/dispatch-issues.jsonl`, which had NO lock and NO
+ * tmp+rename: `log_dispatch_issue` read the whole capped log, appended a line,
+ * and `writeFileSync`'d the target directly.
+ *
+ * That is corruption-capable rather than merely lossy, and the distinction is
+ * why this needed its own primitive instead of a comment. `writeFileSync`
+ * truncates and then writes, so a concurrent reader can observe a half-written
+ * log and a concurrent writer can interleave into one — and the file is written
+ * precisely when something has ALREADY gone wrong, so the evidence destroyed is
+ * the evidence of the failure being reported. Two concurrent dispatchers in one
+ * workspace is a supported configuration (two platforms installed side by side),
+ * and a host that runs tool calls in parallel produces it without any second
+ * platform at all.
+ *
+ * `transform` receives the file's content as read INSIDE the lock — `null` when
+ * the file does not exist, so a caller can tell "absent" from "empty" — and
+ * returns what to write. Returning `null` writes nothing and still counts as
+ * success.
+ *
+ * Returns `written` / `skipped` / `failed`, the same three-state contract
+ * `update_json_under_lock` carries since `bcbb0380b` — a boolean could not tell
+ * a deliberate decline from a failure, and every member of the union is a truthy
+ * string, so `if (!result)` is a silent no-op rather than a compile error. Under
+ * `AGENT_CONFIG_REPLAY=1` this reports `failed` without touching the tree.
+ */
+export function update_text_under_lock(
+  target: string,
+  transform: (loaded: string | null) => string | null,
+  options: { blocking?: boolean } = {},
+): LockedUpdateResult {
+  if (is_replay_mode()) return "failed";
+  const targetPath = path.resolve(target);
+  const state_dir = path.dirname(targetPath);
+  try {
+    fs.mkdirSync(state_dir, { recursive: true });
+  } catch {
+    return "failed";
+  }
+  // FILE-keyed, matching `update_json_under_lock` rather than
+  // `_atomic_write_text`. Converged onto the sibling deliberately after
+  // `bcbb0380b` landed the measured argument: a read-modify-write needs mutual
+  // exclusion against writers of THIS file and nothing else, and the shared
+  // directory lock was measured paying the full cost of exclusion for writes
+  // that require none (8 workers: slowest 138-267 ms shared vs 83-95 ms
+  // unshared). This function was written against the directory-keyed primitive
+  // one commit earlier; leaving it there would have made
+  // `dispatch-issues.jsonl` serialise against every unrelated
+  // `atomic_write_text` in the state dir.
+  const lock_path = _target_lock_path(targetPath);
+  let fd: number | null;
+  try {
+    fd = _acquire_lock(lock_path, { blocking: options.blocking ?? true });
+  } catch {
+    return "failed";
+  }
+  // FAIL CLOSED, for the same reason the JSON sibling does: an append without
+  // exclusion is the truncating write this function exists to prevent.
+  if (fd === null) return "failed";
+  try {
+    let loaded: string | null = null;
+    try {
+      loaded = fs.readFileSync(targetPath, "utf-8");
+    } catch {
+      // Absent or unreadable. `null` lets the transform distinguish the two
+      // from an empty file, which matters for an append-only log: an
+      // unreadable existing log must not be silently replaced by one line.
+    }
+    const next = transform(loaded);
+    if (next === null) return "skipped"; // deliberate no-write, not a failure
+    _publish_text_locked(targetPath, next);
+    return "written";
+  } catch {
+    return "failed";
+  } finally {
+    _release_lock(fd, lock_path);
+  }
+}
+
 export function update_json_under_lock<T>(
   target: string,
   mutate: (loaded: Partial<T>) => T | null,

package/src/scripts/hooks/stdin_failure_policy.ts

@@ -0,0 +1,96 @@
+/**
+ * The stdin-read-failure policy, extracted from `dispatch_hook.ts`.
+ *
+ * These functions are pure with respect to dispatch_hook's own state: they take
+ * what they need as parameters and return a verdict. They do call two imported
+ * helpers (`readFd0ToEnd`, `isBlockCapable`), which move with them as imports. The module-level flag they feed, `_stdin_read_failed`, stays in
+ * dispatch_hook.ts, written at exactly one call site and read at three. That
+ * asymmetry is what makes moving the functions safe and the state untouched.
+ *
+ * Extracted because dispatch_hook.ts sits at the 1500-line source ceiling.
+ */
+import type { JsonObject } from './dispatch_hook.js';
+import { readFd0ToEnd } from './hook_stdin.js';
+import { isBlockCapable } from './host_semantics.js';
+
+/**
+ * The seam where a FAILED read becomes an empty string — isolated so the three
+ * failure classes the policy names can be driven with real errno values.
+ *
+ * Returns the failure message, or `null` when the read succeeded. The read
+ * itself is injectable for exactly one reason: `EAGAIN` exhaustion, `EIO` and
+ * `EBADF` cannot be staged against a live fd 0 portably, and a policy whose
+ * trigger is untestable is a policy nobody can show works. What the injection
+ * does NOT buy is proof that the production path reaches here — that is the
+ * wiring, pinned separately by driving `main()`.
+ */
+export function stdinReadFailure(read: () => string = readFd0ToEnd): {
+  text: string;
+  failure: string | null;
+} {
+  try {
+    // 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 { text: read(), failure: null };
+  } catch (exc) {
+    return { text: "", failure: exc instanceof Error ? exc.message : String(exc) };
+  }
+}
+
+/**
+ * Is this concern one whose verdict a failed read silently converted into an
+ * allow?
+ *
+ * Both halves are required and neither is redundant. `fail_closed: true` is the
+ * manifest's declaration that this concern's own crash must not become a pass;
+ * `severity: blocking` is the declaration that it can refuse at all. An
+ * advisory concern that happens to be `fail_closed` has no verdict to lose, and
+ * a blocking concern that is not `fail_closed` has already declared the opposite
+ * intent.
+ */
+export function _is_fail_closed_blocking(concern: JsonObject): boolean {
+  const severity = String(concern["severity"] ?? "").trim().toLowerCase();
+  return concern["fail_closed"] === true && severity === "blocking";
+}
+
+/**
+ * `b-stdin-read-failure-policy`, option (c) — deny a failed read ONLY where a
+ * deny is honoured AND something was actually silenced.
+ *
+ * Decided by council 2026-08-20, 2/2 quorum, both seats on option (c):
+ * "on a read failure, deny only when the slot is block-capable and at least one
+ * selected concern is both blocking and `fail_closed: true`".
+ *
+ * The two rejected options are worth keeping visible, because each is the
+ * obvious move. Denying on EVERY slot (option (a)) refuses nothing on
+ * `post_tool_use` — the tool already ran — and on `stop` it breaks a turn end
+ * to protect a guard that was never there; it buys availability risk for no
+ * enforcement. Keeping the allow (option (b), the status quo) leaves a
+ * documented allow-on-failure on a security path: F-1 measured a
+ * `git commit --no-verify` DENIED at small payload size and ALLOWED at 300 KB,
+ * and the loud stderr line that now ships makes that visible without making it
+ * stop.
+ *
+ * The cost is stated rather than hidden: a transient I/O error on
+ * `pre_tool_use` now refuses a tool call the user must retry. The retry budget
+ * already survived ~10 s of `EAGAIN` before this point, so the class of error
+ * that reaches here is not "the writer was slow".
+ *
+ * Returns `null` when the dispatch proceeds normally.
+ */
+export function denyOnStdinFailure(
+  platform: string,
+  event: string,
+  concerns: readonly JsonObject[],
+  failure: string,
+): { reason: string } | null {
+  if (!isBlockCapable(platform, event)) return null;
+  const silenced = concerns.filter(_is_fail_closed_blocking).map((c) => String(c["name"]));
+  if (silenced.length === 0) return null;
+  return {
+    reason:
+      `agent-config: refusing this action — the hook payload could not be read ` +
+      `(${failure}), so ${silenced.join(", ")} evaluated nothing. ` +
+      `A fail-closed guard on a block-capable slot must not pass by default. Retry.`,
+  };
+}

package/src/scripts/hooks/subagent_ledger_hook.ts

@@ -112,7 +112,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { validateResponse } from '../_lib/subagent_response.js';
+import { countContractFields, validateResponse } from '../_lib/subagent_response.js';
 import { atomic_write_json, is_replay_mode } from './state_io.js';
 import { readHookStdin } from './hook_stdin.js';
 
@@ -197,7 +197,7 @@ function extractParentId(payload: JsonObject, ownId: string | null): string | nu
     return null;
 }
 
-export type EnvelopeParse = 'ok' | 'fail' | 'no_message' | 'no_envelope';
+export type EnvelopeParse = 'ok' | 'fail' | 'foreign_object' | 'no_message' | 'no_envelope';
 
 /**
  * The retired fifth value. Records written before 2026-08-20 carry `absent`,
@@ -212,16 +212,49 @@ export type EnvelopeParse = 'ok' | 'fail' | 'no_message' | 'no_envelope';
  */
 export const RETIRED_ENVELOPE_PARSE = 'absent';
 
+/**
+ * READING THE HISTORICAL WINDOW — the caveat, not a version field.
+ *
+ * A verdict records conformance to the shape that was canonical **when the row
+ * was written**, and that shape was reconciled on 2026-08-22
+ * (`subagent-response-contract.md` § The canonical shape). Before that date one
+ * contract existed in three mutually inconsistent states: the spawn contract's
+ * rule (f), a narrower JSON injected by `team_dispatch.ts:297`, and the
+ * validator's five required fields. Nothing recorded which one a given row was
+ * judged against, because until the reconciliation there was no single answer.
+ *
+ * So a row from the 2026-08 window must NOT be read as conforming — or as
+ * failing to conform — to the reconciled shape. What it says is narrower: the
+ * classifier at the time either found a `validateResponse`-passing object or did
+ * not. As it happens the two agree for every row in that window, because the
+ * count is **0 of 1,845** and a rate of zero is the same number under either
+ * reading — but that is a property of this particular window, not of the
+ * comparison, and the next window will not have it.
+ *
+ * Deliberately a comment and not a `contract_version` field. Adding one would
+ * be honest going forward and would still say nothing about the rows already on
+ * disk, which are the rows this caveat exists for. A council seat asked for the
+ * field; it is the right next step and it is not this one, because a field
+ * stamped from today cannot retro-tag yesterday.
+ */
+
 export interface ParseVerdict {
     verdict: EnvelopeParse;
     /** Count of validator errors. A COUNT — the messages never leave this function. */
     error_count: number;
+    /**
+     * How many of the five REQUIRED contract fields the judged candidate
+     * carried. Recorded beside the error count so the `fail` / `foreign_object`
+     * boundary is auditable from the row itself rather than re-derived from a
+     * probe — which is how the split's own premise had to be established.
+     */
+    field_hits: number;
 }
 
 /**
  * Classify a subagent's final message against the response-envelope contract.
  *
- * Four outcomes, and every boundary between them separates two defects with
+ * Five outcomes, and every boundary between them separates two defects with
  * two different fixes:
  *
  *   - `no_message` — the host delivered no `last_assistant_message` at all
@@ -232,9 +265,22 @@ export interface ParseVerdict {
  *     the overwhelmingly common case: subagents answer in prose. It is not a
  *     channel failure, and a fallback keyed on it would fire on nearly every
  *     dispatch.
- *   - `fail` — an object arrived and did not satisfy `validateResponse`.
+ *   - `fail` — an object arrived, carried at least one required contract
+ *     field, and did not satisfy `validateResponse`. A near-miss: someone
+ *     aimed at the envelope and got it wrong.
+ *   - `foreign_object` — an object arrived and carried NONE of the required
+ *     fields. A fenced tool call, or a prose-embedded JSON blob: it never
+ *     aimed at the envelope at all.
  *   - `ok` — an object arrived and validated.
  *
+ * The last two used to be one value, `fail`, and the collapse had the same
+ * shape as the `absent` one below it. Re-derived over the live month ledger
+ * (7,282 rows, 6,315 stops) the all-time `fail` histogram was `{5: 27}` —
+ * every recorded `fail` carried `error_count: 5`, which is exactly "zero
+ * required fields present". So the bucket a threshold would be read off held
+ * no contract attempts at all, and could neither rise nor fall for the reason
+ * its name suggests.
+ *
  * The first two used to be one value, `absent`. Over the first measured window
  * that collapse read 25 of 25 `absent` — including the #58109 control arm that
  * returned a complete report — so a rate computed off it measured the answer
@@ -244,21 +290,37 @@ export interface ParseVerdict {
  * column, and Phase 2's fallback condition, expressible at all.
  */
 export function classifyEnvelope(message: string | null): ParseVerdict {
-    if (message === null || !message.trim()) return { verdict: 'no_message', error_count: 0 };
+    if (message === null || !message.trim()) {
+        return { verdict: 'no_message', error_count: 0, field_hits: 0 };
+    }
 
     const candidates = _jsonObjectCandidates(message);
-    if (candidates.length === 0) return { verdict: 'no_envelope', error_count: 0 };
+    if (candidates.length === 0) return { verdict: 'no_envelope', error_count: 0, field_hits: 0 };
 
     // A message may carry several object-shaped spans. The envelope is the one
-    // that validates, so a `fail` is only reported once every candidate has
-    // been tried — otherwise a stray leading `{}` would mask a valid envelope.
+    // that validates, so a failure verdict is only reported once every
+    // candidate has been tried — otherwise a stray leading `{}` would mask a
+    // valid envelope.
+    //
+    // Among failures the MOST contract-shaped candidate wins, not the first
+    // one met. First-match was safe while every failure was one bucket; with
+    // the near-miss split it is not, because a leading `{"note":1}` would
+    // report `foreign_object` for a message that also carried a real attempt —
+    // the same masking defect one register down.
     let best: ParseVerdict | null = null;
     for (const candidate of candidates) {
         const result = validateResponse(candidate);
-        if (result.valid) return { verdict: 'ok', error_count: 0 };
-        if (best === null) best = { verdict: 'fail', error_count: result.errors.length };
+        const fieldHits = countContractFields(candidate);
+        if (result.valid) return { verdict: 'ok', error_count: 0, field_hits: fieldHits };
+        if (best === null || fieldHits > best.field_hits) {
+            best = {
+                verdict: fieldHits === 0 ? 'foreign_object' : 'fail',
+                error_count: result.errors.length,
+                field_hits: fieldHits,
+            };
+        }
     }
-    return best ?? { verdict: 'no_envelope', error_count: 0 };
+    return best ?? { verdict: 'no_envelope', error_count: 0, field_hits: 0 };
 }
 
 /**
@@ -685,6 +747,9 @@ function handleStop(root: string, payload: JsonObject, nowIso: string, sessionId
         start_seen: rec !== null,
         envelope_parse: parse.verdict,
         envelope_error_count: parse.error_count,
+        // Beside the count, never instead of it: the count says how wrong the
+        // candidate was, this says whether it was aimed at the envelope.
+        envelope_field_hits: parse.field_hits,
         concurrent_open: countOpen(root),
     });
 }