@event4u/agent-config 14.7.0 → 14.8.0

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/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/injection_scan_hook.ts

@@ -141,10 +141,114 @@ function _enabled(root: string): boolean {
   return false;
 }
 
-/** Best-effort extraction of the tool-output text from the envelope. */
+/**
+ * ── The output-envelope contract ─────────────────────────────────────────────
+ *
+ * `b-injection-scan-unwrap-security`, option (a), council 2026-08-20 (2/2
+ * quorum): "specify the envelope contract and its fixtures BEFORE narrowing the
+ * scanner input". This block is that contract; the fixtures are in
+ * `tests/hooks/injection_scan_output_contract.test.ts`, and they are the
+ * deliverable — the code change below is one descent and one deletion.
+ *
+ * WHAT THIS CONCERN READS, exhaustively:
+ *
+ *  1. **The tool output, and only the tool output.** `injection-scan` is bound
+ *     to `post_tool_use` on every platform that carries it, so a payload
+ *     reaching here is expected to hold a tool result.
+ *  2. **Where it lives.** Under a dispatcher envelope the host-shaped fields are
+ *     nested under `payload` (`dispatch_hook._build_envelope`); under a bare-host
+ *     or direct invocation they sit at the root. Both are supported.
+ *  3. **Which keys.** {@link OUTPUT_KEYS}, in order. The first four mirror
+ *     `payload_stub.BODY_KEYS.result` — the set the dispatcher stubs, and
+ *     therefore the set it knows how to serve whole. `output` and `result` are
+ *     the two generic spellings this concern has accepted since it shipped and
+ *     are kept: dropping them would narrow coverage on the same change that
+ *     narrows the fallback, and only one of those is decided here.
+ *  4. **How a value is read.** A string is scanned verbatim. An object or array
+ *     is scanned as its compact JSON serialisation — unchanged, deliberately,
+ *     including the consequence that a hidden codepoint inside a nested string
+ *     becomes the literal text `\u200b` and does NOT trip `_HIDDEN`. That is a
+ *     detection property of the serialiser, not of this contract, and changing
+ *     it is a separate question.
+ *  5. **Missing output → nothing to scan → allow.** THIS IS THE NARROWING. The
+ *     previous code fell through to serialising the WHOLE envelope, so what it
+ *     actually scanned in production was everything: the tool input echo, the
+ *     cwd, the session id, the settings block. It worked by accident and nothing
+ *     tested the accident.
+ *  6. **Malformed envelope → allow.** Non-JSON, a list, a scalar: unchanged.
+ *  7. **A stubbed result body → allow, LOUDLY.** The manifest declares
+ *     `needs_payload_bodies: [input, result]`, which is what keeps the result
+ *     served whole. If that declaration is ever dropped the body arrives as a
+ *     `PayloadStub` and a plain read finds no string — indistinguishable from
+ *     "clean output", which is a scanner that silently stops scanning. Say so on
+ *     stderr instead. Same second-silent-death route `ship-diff-volume` closes.
+ *
+ * BOTH DIRECTIONS OF THE COST, stated because the narrowing is on a security
+ * surface and only one direction is an improvement:
+ *
+ *  - **Removed false positives.** The old fallback could raise a hit on text
+ *    that is not tool output at all — a `cwd` under a path containing an exfil
+ *    signature, an injection phrase echoed in the tool INPUT the user typed.
+ *  - **Accepted false-negative risk.** A host that puts its tool output under a
+ *    key not in {@link OUTPUT_KEYS} is now unscanned where the fallback would
+ *    have caught it. This is mitigated, not dismissed: an unrecognised payload
+ *    shape emits one stderr line naming the payload's top-level KEY NAMES (never
+ *    values), so a new host spelling surfaces on first contact instead of going
+ *    dark. The list is one exported constant; adding a spelling is one line.
+ *
+ * The descent below is LOCAL and is deliberately NOT `envelope.ts`'s shared
+ * `unwrap`, which descends only when all four `ENVELOPE_KEYS` are present: a
+ * producer emitting a partial envelope would leave this concern reading the root
+ * again with every test still green. `ship-diff-volume`, `design-slop` and
+ * `ui-route-nudge` each carry their own descent for the same reason.
+ */
+export const OUTPUT_KEYS: readonly string[] = [
+  // payload_stub.BODY_KEYS.result — the spellings the dispatcher serves.
+  "tool_response",
+  "toolResponse",
+  "tool_result",
+  "toolUseResult",
+  // Generic spellings accepted since this concern shipped.
+  "output",
+  "result",
+];
+
+/** The dispatcher's stub marker (payload_stub.STUB_MARKER), inlined so this
+ * concern keeps its no-hard-import-dependency property in a consumer repo. */
+const STUB_MARKER = "_agent_config_body_omitted";
+
+function _isStub(v: unknown): boolean {
+  return _isObject(v as JsonValue) && (v as JsonObject)[STUB_MARKER] === true;
+}
+
+/**
+ * Descend to the platform payload. See the contract block above, point 2.
+ */
+function _payload_of(root: JsonObject): JsonObject {
+  const inner = root["payload"];
+  return _isObject(inner) ? inner : root;
+}
+
+/**
+ * The tool-output text, per the contract above. `''` means "nothing to scan",
+ * which is a real answer and not a failure.
+ */
 function _tool_output(envelope: JsonObject): string {
-  for (const key of ["tool_response", "tool_result", "toolResponse", "output", "result"]) {
-    const v = envelope[key];
+  const payload = _payload_of(envelope);
+  for (const key of OUTPUT_KEYS) {
+    const v = payload[key];
+    if (v === undefined || v === null) {
+      continue;
+    }
+    if (_isStub(v)) {
+      // Contract point 7: the declaration that serves this body was dropped.
+      process.stderr.write(
+        `injection-scan: ${key} arrived stubbed; the concern declares ` +
+          "needs_payload_bodies: [input, result] and cannot scan tool output " +
+          "without it. Nothing was scanned on this event.\n",
+      );
+      return "";
+    }
     if (typeof v === "string") {
       return v;
     }
@@ -152,8 +256,36 @@ function _tool_output(envelope: JsonObject): string {
       return _pyJsonDumpsCompact(v);
     }
   }
-  // fall back to the whole payload (minus obvious input echoes)
-  return _pyJsonDumpsCompact(envelope);
+  // Contract point 5 + the accepted false-negative risk. Key NAMES only — a
+  // value here could be tool output, which is exactly what must not be logged.
+  const names = Object.keys(payload);
+  if (names.length > 0) {
+    process.stderr.write(
+      "injection-scan: no recognised tool-output key in this payload; nothing " +
+        `scanned. Present keys: ${names.sort().join(", ")}. Expected one of: ` +
+        `${OUTPUT_KEYS.join(", ")}.\n`,
+    );
+  }
+  return "";
+}
+
+/**
+ * The stdin boundary: raw concern stdin → the text this concern scans.
+ *
+ * Exported so the regression drives the BOUNDARY rather than the extractor —
+ * both council seats required that, and it is what stops a hand-written fixture
+ * from drifting into agreeing with the bug. Never throws.
+ */
+export function toolOutputFromStdin(raw: string): string {
+  if (!raw.trim()) return "";
+  let root: unknown;
+  try {
+    root = JSON.parse(raw);
+  } catch {
+    return "";
+  }
+  if (!_isObject(root as JsonValue)) return "";
+  return _tool_output(root as JsonObject);
 }
 
 function _scan(text: string): string[] {

package/src/scripts/lint_hook_manifest.ts

@@ -135,6 +135,7 @@ function _check_concerns(manifest: YamlObject, errors: string[]): Set<string> {
     return new Set();
   }
   const names = new Set<string>();
+  const nudgeRanks = new Map<number, string[]>();
   for (const [name, spec] of Object.entries(concernsRaw)) {
     if (!isObject(spec)) {
       errors.push(
@@ -213,8 +214,56 @@ function _check_concerns(manifest: YamlObject, errors: string[]): Set<string> {
         }
       }
     }
+    // `nudge_rank:` — the nudge-exclusivity ordering `injection_budget`
+    // arbitrates on. Validated here because `injection_budget._selectNudge`
+    // says so in as many words: "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". This is that check.
+    //
+    // A tie is not a crash. `_selectNudge` keeps the lowest rank and breaks
+    // ties on concern name, so a collision resolves stably and arbitrarily:
+    // one nudge silently wins forever, and the author who added the second one
+    // gets no signal that their concern can never emit. That is the failure
+    // mode — silent, not loud.
+    if ("nudge_rank" in spec) {
+      const rank = spec["nudge_rank"];
+      if (typeof rank !== "number" || !Number.isInteger(rank) || rank < 1) {
+        errors.push(
+          `concerns.${name}: 'nudge_rank' must be a positive integer ` +
+            `(got ${pyTypeName(rank)}) — the dispatcher keeps the LOWEST rank, ` +
+            `so a malformed value reads as "never wins" rather than as an error`,
+        );
+      } else {
+        const seen = nudgeRanks.get(rank);
+        if (seen) {
+          seen.push(name);
+        } else {
+          nudgeRanks.set(rank, [name]);
+        }
+      }
+    }
     names.add(name);
   }
+  // Uniqueness is enforced GLOBALLY, not per event, and that is a deliberate
+  // choice rather than an accident of what is easy to compute. `_selectNudge`
+  // compares candidates within one dispatch, so two concerns bound to disjoint
+  // events could share a rank harmlessly and the accurate invariant is
+  // per-event. Global uniqueness is the strictly-safe superset: it costs
+  // nothing at today's two declared ranks, and an author reusing a rank across
+  // events is exactly the confusion worth refusing. If a legitimate design
+  // ever needs the same rank on two events, NARROW this to concerns sharing at
+  // least one bound event — do not delete it.
+  for (const [rank, holders] of nudgeRanks) {
+    if (holders.length > 1) {
+      errors.push(
+        `concerns: nudge_rank ${rank} is declared by ${holders.length} concerns ` +
+          `(${holders.slice().sort().join(", ")}) — ranks must be unique, because ` +
+          `the dispatcher breaks a tie on concern name and the loser can then ` +
+          `never emit`,
+      );
+    }
+  }
   return names;
 }