@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/hooks/state_io.ts

@@ -6,10 +6,14 @@
  * Python module exactly (snake_case kept deliberately — fidelity over
  * TS idiom).
  *
- * Per `docs/contracts/hook-architecture-v1.md` § Concurrency, every concern
- * that writes under `agents/runtime/state/` MUST:
- *
- * 1. Acquire an exclusive lock on `agents/runtime/state/.dispatcher.lock`.
+ * Per `docs/contracts/hook-architecture-v1.md`, Concurrency, every concern
+ * that writes a state file under `agents/` MUST:
+ *
+ * 1. Acquire an exclusive lock on `<state_dir>/.dispatcher.lock` — the SAME
+ *    directory the target file lives in, derived from the target's own
+ *    path (`path.dirname`), never a single fixed location: one concern's
+ *    target under `agents/runtime/state/` locks there, another's target
+ *    under `agents/state/` locks there instead.
  * 2. Write to a sibling `<dest>.tmp.<pid>` file in the same directory.
  * 3. Rename(2) (atomic on the same filesystem) tmp → dest.
  * 4. Release the lock.

package/src/scripts/hooks/table_fingerprint.ts

@@ -9,6 +9,27 @@ import { createHash } from 'node:crypto';
  * dispatcher: `dispatch_hook` → `host_semantics` → `host_lowering` is a live
  * import chain, so the reverse edge would be a cycle.
  *
+ * THE RETIRED ARGUMENT, kept because both callers point here for it rather
+ * than restating it. `dispatch_hook._manifest_fingerprint` argued AGAINST a
+ * cryptographic hash on two grounds, and by the time road-to-blocking-
+ * severities 3.1 read that header the body had already been delegating here for
+ * a release — so a reader checking whether the dispatcher resists a CRAFTED
+ * sibling met a disclaimer the code had stopped making. Both grounds were
+ * re-measured when this module was extracted, and both were stale:
+ *
+ *   - "`require('node:crypto')` costs 8 ms of process start, which is most of
+ *     what the precompiled manifest exists to save." The module is already
+ *     loaded: `dist/hooks/dispatch.js` carries 23 top-level
+ *     `import … from "node:crypto"` statements from other parts of the graph,
+ *     so the cost is paid whether this function uses it or not.
+ *   - "An FNV-1a loop runs in about 0.2 ms and is the right trade." SHA-256
+ *     measured FASTER — 0.106 ms against 0.113 ms over the 99,792-byte
+ *     manifest — because Node's digest is native and the loop was that many
+ *     interpreted `charCodeAt` calls.
+ *
+ * Both readers now point here instead of restating it, so the argument and the
+ * numbers that retired it cannot part company again.
+ *
  * DELIBERATELY CONTENT-DERIVED, NOT MTIME. The first version of the manifest
  * fast path compared mtimes and that was a measured defect, not a theoretical
  * one: on a fresh `actions/checkout` both files carry the checkout timestamp in

package/src/scripts/hooks/telemetry_usage_hook.ts

@@ -22,12 +22,19 @@
  * activates only when `enabled` is true AND the org pack supplied an
  * endpoint, an org id, and a salt. An external clone of this repository
  * carries the key names and no values, so copying the tree cannot reach the
- * write path. When inactive this concern performs zero telemetry file
- * operations — no log write, no directory creation — and zero network calls.
+ * write path. When inactive this concern performs zero TELEMETRY file
+ * operations — no log write, no spool, no directory under the configured
+ * output path — and zero network calls.
  * (It does read `.agent-settings.yml`, once per process and memoised: the
  * settings file is how it learns it is off, the same as the artefact-
  * engagement surface it mirrors.)
  *
+ * The foreign-MCP tool-name recorder that once branched here lives in its own
+ * concern, `mcp-usage-observation` (road-to-neighbours-that-pull-their-weight
+ * D12): this concern's `tools: [Skill]` filter meant the dispatcher never
+ * called that branch, and default-on local collection does not belong under an
+ * opt-in telemetry name.
+ *
  * NO OUTBOUND CALL EXISTS HERE, DELIBERATELY. Transport is Phase 2 and is
  * blocked on `sink-choice`; org-wide enablement is Phase 3 and is blocked on
  * `dpo-signoff`. This concern appends to a local JSONL file and stops.
@@ -247,7 +254,8 @@ function processEnvelope(envelope: JsonValue, consumer_root: string): number {
         if (!isObject(envelope)) return EXIT_ALLOW;
 
         const payload = unwrapPayload(envelope);
-        if (extractToolName(payload) !== SKILL_TOOL_NAME) return EXIT_ALLOW;
+        const tool = extractToolName(payload);
+        if (tool !== SKILL_TOOL_NAME) return EXIT_ALLOW;
 
         const { settings, text, root } = readSettingsFor(consumer_root);
         if (!settings.active) return EXIT_ALLOW;
@@ -339,11 +347,18 @@ export function main(): number {
 
 // Bundle-safety: never auto-run when inlined into an esbuild bundle, where
 // every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+//
+// The bundle test is at the CALL SITE rather than at the top of
+// `_isCliEntry`, and that placement is the whole point. Inside the function
+// esbuild folds the condition to `if (true) return false` and then emits the
+// nine unreachable lines below it anyway — measured at 475 bytes of dead code
+// in a bundle `check_hook_bundle_composition` caps. Guarding the call instead
+// makes the whole statement `if (false)`, which esbuild drops, taking the now
+// unreferenced function with it. Behavior outside the bundle is unchanged:
+// `__AGENT_CONFIG_BUNDLE__` is undeclared there, the first operand is true,
+// and `!__AGENT_CONFIG_BUNDLE__` is never evaluated — so no ReferenceError.
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
 function _isCliEntry(): boolean {
-    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
-        return false;
-    }
     if (process.argv[1] === undefined) return false;
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) return true;
@@ -353,4 +368,6 @@ function _isCliEntry(): boolean {
         return false;
     }
 }
-if (_isCliEntry()) process.exit(main());
+if (typeof __AGENT_CONFIG_BUNDLE__ === 'undefined' || !__AGENT_CONFIG_BUNDLE__) {
+    if (_isCliEntry()) process.exit(main());
+}

package/src/scripts/hooks/turn_end_gate_hook.ts

@@ -186,6 +186,17 @@ export { readTurnRunState };
 // Detector E, extracted to `_lib` where its prose costs no ratchet debt.
 // Re-exported so every existing importer of this module is unchanged.
 import { detectDroppedDecision } from '../_lib/dropped_decision.js';
+// Step 3.2 of `road-to-a-graph-that-feeds-the-gate` — the shadow feeder. It
+// lives in `_lib` for the reason every other extraction here does: this file
+// sits against a 1,500-line shrink-only source budget, and the module it would
+// otherwise grow into is one a recall reading has to be able to open on its own.
+import {
+    appendFeederRow,
+    buildFeederRow,
+    type FeederLayer,
+    graphUntestedVerdict,
+} from '../_lib/graph_feeder_record.js';
+import { type GraphState, graphState } from '../code_graph/detect.js';
 import { isVerificationCommand } from '../_lib/verification_command.js';
 // Round 8 — the record path detector C prefers over its own regex. The regex
 // reads a command's TEXT and `echo test` matches it; these read what the run
@@ -215,6 +226,7 @@ import {
     readInstallBoundary,
     sessionRefusalFile,
     sessionShadowFile,
+    shadowSetBy,
     type RefusalRecord,
     type ShadowLayer,
     type ShadowRecord,
@@ -1276,6 +1288,66 @@ function runDetectors(inputs: DetectorInputs): Finding[] {
     return findings;
 }
 
+/**
+ * Write the graph feeder row for ONE stop (step 3.2).
+ *
+ * Called from both stop paths with the findings that path already computed, so
+ * the F verdict in the row is the SAME verdict the gate acted on — never a
+ * second evaluation written beside it, which is the shape
+ * `obligation_settle_hook.ts` names as measuring nothing.
+ *
+ * It changes no exit code, and the whole body is wrapped: a stop that crashed on
+ * its own instrument would be a new failure mode on a path that is supposed to
+ * cost nothing. The graph half is skipped outright unless the state is `fresh`
+ * or `edited` — an answer from an index that predates the change is not evidence
+ * about the change.
+ */
+function recordGraphFeeder(
+    inputs: DetectorInputs,
+    findings: readonly Finding[],
+    layer: FeederLayer,
+): void {
+    if (is_replay_mode()) return;
+    try {
+        let state: GraphState;
+        try {
+            state = graphState(inputs.workspaceRoot);
+        } catch {
+            return;
+        }
+        // No graph at all is the silent case, exactly as it is for the context
+        // hook: a consumer who never builds one never grows this file.
+        if (state === 'absent') return;
+        // The SAME path set detector F reads, filtered by the SAME predicate.
+        // A completion review found the two arms running over different inputs:
+        // the feeder passed every edit path while F filters to production
+        // source, so the graph arm would have fired on precisely the turns F is
+        // silent for — a recall comparison between two detectors answering
+        // different questions, which is worse than no comparison.
+        const paths = inputs.toolCalls
+            .filter((c) => _EDIT_TOOLS.has(c.name) && c.path !== undefined)
+            .map((c) => c.path as string)
+            .filter(_isProductionSource);
+        const f = findings.find((x) => x.detector === 'untested');
+        appendFeederRow(
+            inputs.workspaceRoot,
+            inputs.sessionKey,
+            buildFeederRow({
+                root: inputs.workspaceRoot,
+                turn: inputs.turnOrdinal,
+                layer,
+                state,
+                fFired: f !== undefined,
+                fMode: f?.mode ?? null,
+                paths,
+                graph: graphUntestedVerdict(inputs.workspaceRoot, state, paths),
+            }),
+        );
+    } catch {
+        // An instrument is never a reason to change what the gate does.
+    }
+}
+
 /**
  * Record what this retry WOULD have been refused for, then let it end.
  *
@@ -1289,6 +1361,14 @@ function recordShadow(inputs: DetectorInputs, layer: ShadowLayer): void {
     if (is_replay_mode()) return;
     try {
         const findings = runDetectors(inputs);
+        // On `refused_turn` the answer is `ours` by construction — that marker
+        // is this gate's own and nothing else writes it. On `stop_hook_active`
+        // the host sets the flag for ANY stop hook's block, so it has to be
+        // read from our own refusal record rather than assumed.
+        const setBy = layer === 'refused_turn'
+            ? 'ours'
+            : shadowSetBy(inputs.workspaceRoot, inputs.sessionKey);
+        recordGraphFeeder(inputs, findings, layer);
         const file = sessionShadowFile(inputs.workspaceRoot, inputs.sessionKey);
         let prev: ShadowRecord | null = null;
         try {
@@ -1303,6 +1383,7 @@ function recordShadow(inputs: DetectorInputs, layer: ShadowLayer): void {
                 turnOrdinal: inputs.turnOrdinal,
                 at: new Date().toISOString(),
                 layer,
+                setBy,
             }) as unknown as Record<string, unknown>,
         );
     } catch {
@@ -1361,6 +1442,10 @@ export function main(): number {
     // warranted"; there is no second, configurable notion of warranted layered
     // on top of it.
     const findings = runDetectors(inputs);
+    // The live verdict's own row. It is written BEFORE the branch below, so a
+    // turn the gate allows and a turn it refuses are both in the record — a
+    // recall reading needs the allowed turns as its negative arm.
+    recordGraphFeeder(inputs, findings, 'live');
     if (findings.length === 0) return EXIT_ALLOW;
 
     markRefusedTurn(

package/src/scripts/hooks_status.ts

@@ -23,11 +23,14 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+import { enforcementFor } from "./check_enforcement_matrix.js";
 import {
   type JsonObject,
   type JsonValue,
   _load_yaml,
 } from "./hooks/dispatch_hook.js";
+import { loadHostLowering } from "./hooks/host_lowering.js";
+import { type SlotReading, readSlots } from "./report_enforcement_drift.js";
 
 // src/scripts/hooks_status.ts → parents[1] is the repo root (.../parents[2]
 // in the Python which lives one level deeper relative computation).
@@ -90,6 +93,18 @@ export interface PlatformRow {
    */
   ask: AskShape;
   bindings: Record<string, string[]>;
+  /**
+   * For each slot that binds at least one `blocking` concern, what that host's
+   * slot can actually carry — `refusal`, `warning-only`, `unverified` or
+   * `proof-expired` (road-to-blocking-severities 1.2).
+   *
+   * Slots with no blocking concern are ABSENT rather than present with a
+   * value, so a reader cannot mistake "nothing here claims to refuse" for a
+   * capability reading. Derived from `host_lowering.yaml`, never from the
+   * manifest: the manifest declares intent and only the lowering table records
+   * whether a refusal can land.
+   */
+  blocking_enforcement: Record<string, string>;
   hint: string | null;
 }
 
@@ -123,10 +138,79 @@ function _bridge_status(project_root: string, rel_path: string): string {
   return stat && stat.isFile() ? "installed" : "missing";
 }
 
+/**
+ * `severity` per concern, read off the manifest this report already loaded.
+ *
+ * `(undeclared)` is folded into "not blocking": this report publishes the
+ * enforcement of concerns that CLAIM to refuse, and a concern that claims
+ * nothing has nothing to reconcile. `lint_hook_manifest` is what refuses an
+ * undeclared severity; duplicating that judgement here would put two answers
+ * in the tree.
+ */
+function _severities(manifest: JsonObject): Map<string, string> {
+  const out = new Map<string, string>();
+  const concerns = manifest["concerns"];
+  if (!_isObject(concerns)) {
+    return out;
+  }
+  for (const [name, spec] of Object.entries(concerns)) {
+    const sev = _isObject(spec) ? spec["severity"] : undefined;
+    if (typeof sev === "string") {
+      out.set(name, sev);
+    }
+  }
+  return out;
+}
+
+/**
+ * What each slot carrying a `blocking` concern can actually do on this host.
+ *
+ * road-to-blocking-severities 1.2, the third surface. The decision and the
+ * vocabulary live in `check_enforcement_matrix`; this reads them rather than
+ * restating them, so the published document and this report cannot drift into
+ * two different answers to one question.
+ *
+ * Failure is SILENT and the field is simply absent. This is a read-only status
+ * report that the post-install smoke probe runs, and a malformed or missing
+ * lowering table must degrade it, never abort it — the gate is where a broken
+ * lowering table is supposed to fail.
+ */
+function _blocking_enforcement(
+  platform: string,
+  bindings: Record<string, string[]>,
+  severities: Map<string, string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  let slots: SlotReading[];
+  try {
+    slots = readSlots(loadHostLowering(), platform).slots;
+  } catch {
+    return out;
+  }
+  const bySlot = new Map(slots.map((s) => [s.slot, s]));
+  for (const [event, concerns] of Object.entries(bindings)) {
+    if (!concerns.some((c) => severities.get(c) === "blocking")) {
+      continue;
+    }
+    const row = bySlot.get(event);
+    out[event] = enforcementFor(
+      row === undefined
+        ? "unlowerable"
+        : row.literal === null
+          ? "null-block"
+          : row.effective === null
+            ? "stale-proof"
+            : null,
+    );
+  }
+  return out;
+}
+
 /** Build the runtime matrix as a plain object — JSON-serialisable. */
 export function collect(project_root: string, manifest: JsonObject): StatusMatrix {
   const platformsRaw = manifest["platforms"];
   const platforms = _isObject(platformsRaw) ? platformsRaw : {};
+  const severities = _severities(manifest);
   const rows: PlatformRow[] = [];
   for (const platform of Object.keys(PLATFORM_BRIDGES)) {
     const [rel, hint] = PLATFORM_BRIDGES[platform] as [string, string];
@@ -148,6 +232,7 @@ export function collect(project_root: string, manifest: JsonObject): StatusMatri
     rows.push({
       platform,
       status,
+      blocking_enforcement: _blocking_enforcement(platform, bindings, severities),
       bridge_path: rel || null,
       fallback_only,
       ask,
@@ -160,6 +245,23 @@ export function collect(project_root: string, manifest: JsonObject): StatusMatri
   return { schema_version: 1, platforms: rows };
 }
 
+/**
+ * One short line per enforcement value, for the table.
+ *
+ * `unverified` says what is MISSING, never what the host cannot do — the same
+ * wording discipline `docs/enforcement-by-host.md` carries, and the reason this
+ * report distinguishes the two values at all.
+ */
+const _ENFORCEMENT_NOTE: Record<string, string> = {
+  refusal: "the slot denies, so a blocking verdict stops the call",
+  "proof-expired":
+    "the slot can deny; this package's `verified` citation has lapsed",
+  "warning-only":
+    "`block_exit` is null here — they run and warn, they cannot refuse",
+  unverified:
+    "no lowering row for this slot — nothing bound natively, nothing established",
+};
+
 const _STATUS_MARKER: Record<string, string> = {
   installed: "✅ ",
   missing: "❌ ",
@@ -199,6 +301,16 @@ export function _render_table(matrix: StatusMatrix): string {
     for (const event of Object.keys(row.bindings).sort()) {
       const concerns = row.bindings[event]?.join(", ") || "—";
       lines.push(`    ${event.padEnd(22)} → ${concerns}`);
+      // road-to-blocking-severities 1.2 — printed only where a concern on this
+      // slot DECLARES `blocking`, and worded so `unverified` never reads as a
+      // claim about the host.
+      const enforcement = row.blocking_enforcement[event];
+      if (enforcement !== undefined) {
+        lines.push(
+          `    ${" ".repeat(22)}   blocking concerns here: ${enforcement} — ` +
+            `${_ENFORCEMENT_NOTE[enforcement] ?? "see docs/enforcement-by-host.md"}`,
+        );
+      }
     }
     if (row.hint) {
       lines.push(`    hint: ${row.hint}`);

package/src/scripts/injection_scan_hook.ts

@@ -214,6 +214,13 @@ export const OUTPUT_KEYS: readonly string[] = [
   "toolResponse",
   "tool_result",
   "toolUseResult",
+  // The failure event's result body. A FAILING command on claude carries its
+  // stdout and stderr here and carries no `tool_response` at all, so without
+  // this line a failed `curl` of a hostile page would reach the model with
+  // nothing scanned — the one direction where the output is most likely to be
+  // attacker-shaped. Caught by this concern's own coverage test, which pins
+  // OUTPUT_KEYS as a superset of what the dispatcher serves.
+  "error",
   // Generic spellings accepted since this concern shipped.
   "output",
   "result",

package/src/scripts/install-hooks.sh

@@ -70,9 +70,13 @@ cat > "$HOOKS_DIR/pre-push" << 'EOF'
 # belongs here; resolution belongs to a step run with the result in front of
 # you. When this hook refuses for staleness, the thing that fixes it is
 #
-#     task push-ready          # fetch -> integrate the base SET -> regenerate
-#                              # -> verify -> re-check freshness -> push
-#     task push-ready DRY=1    # the same six steps, read-only
+#     task push-ready BASE=<base>          # fetch -> integrate the base SET -> regenerate
+#                                          # -> verify -> re-check freshness -> push
+#     task push-ready DRY=1 BASE=<base>    # the same six steps, read-only
+#
+# `<base>` is the base the refusal names. Without BASE the base comes from the
+# open pull request (gh pr view), and is the default branch only when there is
+# no open pull request or no gh.
 #
 # The base is a SET: a branch targeting a release line or a stacked parent may
 # also have to integrate the default branch, per the branch-convergence policy
@@ -141,23 +145,47 @@ fail=0
 # no useful second finding to collect from a tree that is about to move.
 #
 # It never merges. `check_branch_freshness` asks the REMOTE (one `ls-remote`,
-# measured 4.5s) and returns 1 only on a VERIFIED behind state; offline, in CI,
-# on a detached HEAD, or standing on the base itself it returns 0 and says so.
-# So an unreachable network cannot block a push, and a stale local tracking ref
-# cannot fake a green.
+# measured 4.5s) and returns 1 on a VERIFIED behind state, or when the remote
+# answered without the base at all (a misspelled or deleted base); offline, in
+# CI, on a detached HEAD, or standing on the base itself it returns 0 and says
+# so. So an unreachable network cannot block a push, and a stale local tracking
+# ref cannot fake a green. The refusal below names which of the two it was, read
+# from the gate's own lines, so a typo is never reported as staleness.
 echo "🔍 Base freshness — is this branch behind the base it will merge into?"
 if [ "${AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS:-}" = "1" ]; then
     echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1"
 elif [ ! -x ./scripts-run ]; then
     echo "⚠️  ./scripts-run not found — skipping the freshness check for this push."
-elif ! ./scripts-run src/scripts/check_branch_freshness --quiet; then
-    echo ""
-    echo "   Push blocked — the branch is behind its base, and the gates you just"
-    echo "   passed were answered against a base that no longer exists."
+else
+    fresh_rc=0
+    fresh_out=$(./scripts-run src/scripts/check_branch_freshness --quiet 2>&1) || fresh_rc=$?
+    [ -z "$fresh_out" ] || printf '%s\n' "$fresh_out"
+fi
+if [ "${fresh_rc:-0}" -ne 0 ]; then
+    # The gate prints the base in the spelling `task push-ready` accepts.
+    base=$(printf '%s\n' "$fresh_out" | sed -n 's/^ *task push-ready BASE=\([^ ]*\).*/\1/p' | head -n 1)
+    absent=$(printf '%s\n' "$fresh_out" | sed -n 's/.*base `\([^`]*\)` does not exist on \([^ ]*\) .*/\2\/\1/p' | head -n 1)
     echo ""
-    echo "     task push-ready         # fetch → integrate the base SET → regenerate"
-    echo "                             # → verify → re-check freshness, then push"
-    echo "     task push-ready DRY=1   # the same steps, read-only"
+    if [ -n "$base" ]; then
+        echo "   Push blocked — the branch is behind its base, and the gates you just"
+        echo "   passed were answered against a base that no longer exists."
+        echo ""
+        echo "     task push-ready BASE=$base         # fetch → integrate the base SET"
+        echo "                                         # → regenerate → verify → re-check"
+        echo "     task push-ready DRY=1 BASE=$base   # the same steps, read-only"
+    elif printf '%s\n' "$fresh_out" | grep -q 'branch is BEHIND'; then
+        # A strategy that does not merge gets no push-ready line; its remedy
+        # is printed by the gate itself.
+        echo "   Push blocked — the branch is behind its base. The remedy for this"
+        echo "   project's update strategy is printed above."
+    elif [ -n "$absent" ]; then
+        echo "   Push blocked — the base $absent does not exist on the remote: a"
+        echo "   misspelled or deleted base, not a stale branch. Name a branch the"
+        echo "   remote has (--base main and --base origin/main are the same branch)."
+    else
+        echo "   Push blocked — the freshness gate refused without a verdict line;"
+        echo "   its output is above."
+    fi
     echo ""
     echo "   This hook refuses; it never merges. Bypass a genuine WIP push with"
     echo "   AGENT_CONFIG_SKIP_PREPUSH_FRESHNESS=1."