@event4u/agent-config 14.1.0 → 14.4.0

package/src/scripts/lint_hook_manifest.ts

@@ -179,11 +179,177 @@ function _check_concerns(manifest: YamlObject, errors: string[]): Set<string> {
         }
       }
     }
+    // `needs_payload_bodies:` — the payload opt-in
+    // (`road-to-per-turn-hook-economy` step 2.1). Validated for the same
+    // reason `tools:` is, with the polarity reversed: the dispatcher ignores
+    // anything it does not recognise, so `true`, `"input"`, or a misspelled
+    // `[inputs]` all resolve to "keep nothing" and the concern silently
+    // receives stubs it was meant to opt out of. A concern that reads a body
+    // and gets a stub does not crash — it reads `undefined` and reports
+    // nothing, which is the failure this check exists to keep a YAML typo from
+    // introducing. The runtime deliberately does NOT widen on a malformed
+    // value; that would make this check unenforceable.
+    if ("needs_payload_bodies" in spec) {
+      const raw = spec["needs_payload_bodies"];
+      if (!Array.isArray(raw)) {
+        errors.push(
+          `concerns.${name}: 'needs_payload_bodies' must be a list of body ` +
+            `classes (got ${pyTypeName(raw)}) — use [input], [result], or ` +
+            `[input, result]; omit the key to receive stubs, which is the default`,
+        );
+      } else if (raw.length === 0) {
+        errors.push(
+          `concerns.${name}: 'needs_payload_bodies' is an empty list — omit ` +
+            `the key rather than declaring a need for nothing`,
+        );
+      } else {
+        for (const cls of raw) {
+          if (cls !== "input" && cls !== "result") {
+            errors.push(
+              `concerns.${name}: 'needs_payload_bodies' entries must be ` +
+                `'input' or 'result', got ${JSON.stringify(cls)}`,
+            );
+          }
+        }
+      }
+    }
     names.add(name);
   }
   return names;
 }
 
+/** The two slots whose payload carries a stubbable tool body. */
+const TOOL_BODY_EVENTS: ReadonlySet<string> = new Set([
+  "pre_tool_use",
+  "post_tool_use",
+]);
+
+/**
+ * Payload keys per body class, mirroring `hooks/payload_stub.ts::BODY_KEYS`.
+ *
+ * Duplicated deliberately rather than imported: this gate must keep working if
+ * the dispatcher module moves, and the pair is pinned by a test that asserts
+ * the two lists agree. A silent divergence would make the gate scan for keys
+ * the dispatcher no longer stubs.
+ */
+const BODY_KEY_LITERALS: Readonly<Record<'input' | 'result', readonly string[]>> = {
+  input: ["tool_input", "toolInput"],
+  result: ["tool_response", "toolResponse", "tool_result", "toolUseResult"],
+};
+
+/** `// payload-bodies-waiver: <class> — <reason>` in a concern's own source. */
+const WAIVER_RE = /payload-bodies-waiver:\s*(input|result)\s*[—:-]\s*(.+)/g;
+
+/**
+ * A concern that READS a payload body must declare it
+ * (`road-to-per-turn-hook-economy` step 2.1).
+ *
+ * ## Why this is derived from source rather than from trust
+ *
+ * The first version of this check covered guards only, and the R2 review named
+ * the gap precisely: the failure mode the change itself introduces — a NEW
+ * advisory `post_tool_use` concern that reads `tool_response` and forgets the
+ * declaration — passed the lint, passed every test, and then read `undefined`
+ * in silence. Runtime cannot catch it either: the dispatcher's stub counter is
+ * a function of the declaration and the payload shape, so it says how often a
+ * concern ran without a body and never whether it wanted one.
+ *
+ * Authoring time is where the question is decidable, so the requirement is
+ * computed from the concern's own script: if it mentions a body key, it
+ * declares that class or says in the file why it does not.
+ *
+ * ## Over-detection is the safe direction, on purpose
+ *
+ * The scan is a literal match on the key name in quotes or after a dot, so a
+ * COMMENT mentioning `tool_response` also trips it. That is deliberate: a false
+ * positive costs one concern receiving a body it does not need, which is
+ * exactly the status quo before this phase; a false negative costs silence. The
+ * escape hatch is a `payload-bodies-waiver:` line naming the class and a
+ * reason, which keeps the claim next to the code that makes it instead of in a
+ * manifest a concern author may never open.
+ *
+ * ## The guard floor stays, and is stricter than the source scan
+ *
+ * `fail_closed` / `severity: blocking` on a tool slot requires `input`
+ * regardless of what the source scan finds, and a waiver cannot lift it: a
+ * guard served a stub has nothing to match and exits ALLOW. The dispatcher
+ * enforces the same floor independently (`_concern_body_classes` returns every
+ * class for a guard) and does not depend on this lint having run.
+ *
+ * Scoped to the two tool slots deliberately. `turn-end-gate` is blocking and
+ * binds `stop`, whose payload carries no tool body at all — requiring a
+ * declaration there would put a "give me the bodies" line on a concern that
+ * can never receive one, which documents nothing and misleads the next reader.
+ */
+function _check_guard_payload_bodies(
+  manifest: YamlObject,
+  errors: string[],
+): void {
+  const concernsRaw = manifest["concerns"];
+  const platformsRaw = manifest["platforms"];
+  if (!isObject(concernsRaw) || !isObject(platformsRaw)) return;
+  const onToolSlot = new Set<string>();
+  for (const block of Object.values(platformsRaw)) {
+    if (!isObject(block)) continue;
+    for (const [event, names] of Object.entries(block)) {
+      if (!TOOL_BODY_EVENTS.has(event) || !Array.isArray(names)) continue;
+      for (const n of names) {
+        if (typeof n === "string") onToolSlot.add(n);
+      }
+    }
+  }
+  for (const [name, spec] of Object.entries(concernsRaw)) {
+    if (!isObject(spec) || !onToolSlot.has(name)) continue;
+    const isGuard = spec["fail_closed"] === true || spec["severity"] === "blocking";
+    const declared = spec["needs_payload_bodies"];
+    const declaredSet = new Set(
+      Array.isArray(declared)
+        ? declared.filter((c): c is string => typeof c === "string")
+        : [],
+    );
+    if (isGuard && !declaredSet.has("input")) {
+      errors.push(
+        `concerns.${name}: bound on a tool slot and fail_closed / ` +
+          `severity: blocking, so it must declare 'needs_payload_bodies' ` +
+          `including 'input' — a guard served a payload stub has nothing to ` +
+          `match and exits ALLOW`,
+      );
+    }
+    const script = spec["script"];
+    if (typeof script !== "string") continue;
+    let source = "";
+    try {
+      source = fs.readFileSync(path.join(REPO_ROOT, script), "utf8");
+    } catch {
+      continue; // missing script is already reported by _check_concerns
+    }
+    const waived = new Map<string, string>();
+    for (const m of source.matchAll(WAIVER_RE)) {
+      const cls = m[1];
+      const reason = (m[2] ?? "").trim();
+      if (cls !== undefined && reason) waived.set(cls, reason);
+    }
+    for (const [cls, keys] of Object.entries(BODY_KEY_LITERALS)) {
+      if (declaredSet.has(cls)) continue;
+      const hit = keys.find(
+        (k) =>
+          source.includes(`'${k}'`) ||
+          source.includes(`"${k}"`) ||
+          source.includes(`.${k}`),
+      );
+      if (hit === undefined) continue;
+      if (waived.has(cls)) continue;
+      errors.push(
+        `concerns.${name}: ${script} references '${hit}' but does not declare ` +
+          `'${cls}' in needs_payload_bodies — it would receive a stub and read ` +
+          `undefined in silence. Declare the class, or put ` +
+          `\`payload-bodies-waiver: ${cls} — <reason>\` in the script saying ` +
+          `why the body is not needed`,
+      );
+    }
+  }
+}
+
 function _check_platforms(
   manifest: YamlObject,
   concernNames: Set<string>,
@@ -425,6 +591,7 @@ export function lint(manifestPath: string, strict: boolean): number {
   const warnings: string[] = [];
   const concernNames = _check_concerns(manifest, errors);
   const bound = _check_platforms(manifest, concernNames, errors, warnings);
+  _check_guard_payload_bodies(manifest, errors);
   _check_roles(manifest, concernNames, errors);
   _check_aliases(manifest, errors);
   _check_orphan_trampolines(manifest, errors);

package/src/scripts/roadmap_progress_hook.ts

@@ -34,6 +34,7 @@
  */
 
 import { spawnSync } from "node:child_process";
+import * as crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -41,9 +42,146 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { hardenedSpawnEnv } from "./_lib/spawn_env.js";
 import { log_dispatch_issue } from "./hooks/dispatch_issues.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
+import { atomic_write_json } from "./hooks/state_io.js";
 
 export const REPLAY_ENV_VAR = "AGENT_CONFIG_REPLAY";
 
+/**
+ * Debounce ledger (road-to-per-turn-hook-economy step 3.1 / D-3).
+ *
+ * The hook used to re-shell the regenerator through tsx on EVERY roadmap write.
+ * A cold tsx start per write, in the roadmap-heavy workflow this repo runs, is
+ * the second of the two spawns that escape the in-process concern table.
+ *
+ * It now records the touched repo roots and regenerates ONCE at turn end.
+ * Two properties make that safe rather than merely cheaper:
+ *
+ * - **The ledger lives under `consumer_root`, not under the target root.** A
+ *   touched root may be a sibling worktree, and at `stop` the payload carries no
+ *   roadmap path — so a marker written beside the edited file would be
+ *   unfindable at flush time. `--project-dir` is the same value on both events,
+ *   which makes one ledger per consumer the only shape that closes.
+ * - **A ledger write that fails regenerates immediately instead.** Losing the
+ *   dashboard-stays-in-sync guarantee silently is worse than paying the spawn,
+ *   so the debounce degrades to the old behaviour rather than to a no-op.
+ *
+ * Flushed by `stop` AND `session_end`, so the worst case is a regeneration
+ * deferred to turn end (risk 4) and never a dropped one. The per-write guarantee
+ * was never a stated contract; session granularity is.
+ */
+export const DIRTY_LEDGER_REL = path.join(
+  "agents",
+  "runtime",
+  "state",
+  "roadmap-progress",
+  "dirty",
+);
+
+/** Events that flush the ledger rather than appending to it. */
+export const FLUSH_EVENTS: ReadonlySet<string> = new Set([
+  "stop",
+  "session_end",
+  // The dispatcher envelope carries the agent-config event id; a bare host
+  // payload carries the native name, and the hook accepts either shape on the
+  // write path already.
+  "Stop",
+  "SessionEnd",
+  "sessionEnd",
+  // Native aliases `hook_manifest.yaml` maps onto those two events. Missing them
+  // was a real gap rather than a completeness nit: the write path keys on
+  // `tool_name`, not on the event, so a host whose turn end arrives under one of
+  // these names accumulated dirty roots that nothing ever flushed. Found by the
+  // R2 review of the commit that introduced this ledger.
+  "TaskComplete",
+  "TaskCancel",
+  "AfterAgent",
+]);
+
+function _ledger_dir(consumer_root: string): string {
+  return path.join(consumer_root, DIRTY_LEDGER_REL);
+}
+
+/**
+ * One entry file per root, named from a hash of the root path.
+ *
+ * **This shape is the concurrency fix, not a style choice.** The first version
+ * kept a single JSON array and did a read-modify-write on it, which is a
+ * lost-update: two `post_tool_use` dispatches from parallel tool calls in one
+ * turn both read `[]`, the second write drops the first root, and `mark_dirty`
+ * still returns `true` — so the inline-regeneration fallback never fires and the
+ * dashboard goes silently stale, which is exactly what the debounce exists to
+ * prevent. Found by the R2 review of the commit that introduced it.
+ *
+ * Independent per-root files remove the race by construction rather than by
+ * holding a lock across a read and a write: concurrent dispatches touch
+ * different paths, and the same root twice is the same path — so N writes to one
+ * repo still leave ONE entry.
+ */
+function _entry_path(consumer_root: string, root: string): string {
+  const digest = crypto.createHash("sha256").update(root).digest("hex").slice(0, 16);
+  return path.join(_ledger_dir(consumer_root), `${digest}.json`);
+}
+
+/** Read the ledger; a missing directory or an unparseable entry reads as empty. */
+export function read_dirty_roots(consumer_root: string): string[] {
+  let names: string[];
+  try {
+    names = fs.readdirSync(_ledger_dir(consumer_root));
+  } catch {
+    return [];
+  }
+  const roots: string[] = [];
+  for (const name of names.sort()) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const raw = fs.readFileSync(path.join(_ledger_dir(consumer_root), name), "utf8");
+      const parsed = JSON.parse(raw) as unknown;
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) continue;
+      const root = (parsed as { root?: unknown }).root;
+      if (typeof root === "string" && root.trim() !== "") roots.push(root);
+    } catch {
+      // A torn or hand-edited entry is dropped, never fatal.
+    }
+  }
+  return Array.from(new Set(roots)).sort();
+}
+
+/**
+ * Record each root as its own entry. Returns false when any write failed — the
+ * caller then regenerates inline, so a broken state directory costs latency
+ * rather than a silently stale dashboard.
+ *
+ * Writes go through `atomic_write_json` (tmp → rename under the dispatcher
+ * lock), which `hook-architecture-v1` requires for everything written under
+ * `agents/runtime/state/`. That call is a no-op under `AGENT_CONFIG_REPLAY=1`,
+ * which is why the replay guard stays in the caller rather than relying on it.
+ */
+export function mark_dirty(consumer_root: string, roots: readonly string[]): boolean {
+  if (roots.length === 0) return true;
+  let wrote = 0;
+  for (const root of roots) {
+    try {
+      atomic_write_json(_entry_path(consumer_root, root), {
+        root,
+        marked_at: new Date().toISOString(),
+      });
+      wrote += 1;
+    } catch {
+      // A partial write still needs the caller's inline fallback.
+    }
+  }
+  return wrote === roots.length;
+}
+
+/** Drop every entry. A missing directory is success — flush is idempotent. */
+export function clear_dirty(consumer_root: string): void {
+  try {
+    fs.rmSync(_ledger_dir(consumer_root), { recursive: true, force: true });
+  } catch {
+    // observability never breaks the hook
+  }
+}
+
 // Tools whose successful execution can write to a roadmap file. We keep
 // the list explicit so an unknown tool name (e.g. a new MCP tool that
 // happens to mention a roadmap path in its input) does not trigger a
@@ -322,6 +460,59 @@ function _resolve_tsx_invocation(scriptPath: string): { command: string; args: s
   return { command: "npx", args: ["tsx", scriptPath] };
 }
 
+/**
+ * Run the regenerator once per root. Extracted by step 3.1 so the write path
+ * and the flush path share ONE implementation — a debounce whose flush
+ * regenerated differently from the per-write path would be a second code path
+ * nobody compares.
+ */
+function _regenerate(roots: Iterable<string>, verbose: boolean): void {
+  for (const root of roots) {
+    const script = _resolve_regenerator(root);
+    if (script === null) {
+      // Phase 1 of road-to-hooks-actually-fire-in-consumers: log dispatch
+      // issue directly (this hook runs as a subprocess from the universal
+      // dispatcher; routing through the dispatcher would add latency for
+      // no benefit).
+      try {
+        log_dispatch_issue(
+          root,
+          "roadmap-progress",
+          "prerequisite_missing",
+          "update_roadmap_progress.ts not found at any of: " +
+            ".augment/scripts/, dist/agent-src/scripts/, " +
+            "src/agent-src/scripts/",
+          "./agent-config hooks:install --regen " + "(or ./agent-config init)",
+        );
+      } catch {
+        // observability never breaks the hook
+      }
+      if (verbose) {
+        process.stderr.write(
+          `roadmap-progress-hook: regenerator not found for ${root}, skipping\n`,
+        );
+      }
+      continue;
+    }
+
+    try {
+      // The regenerator is a `.ts` script; run it through tsx (resolved from
+      // a node_modules/.bin found by walking up from the regenerator's dir,
+      // falling back to `npx tsx`), mirroring the dispatcher's `.ts` concerns.
+      // `--repo-root` + cwd pin the regeneration to the edited file's own repo.
+      const inv = _resolve_tsx_invocation(script);
+      spawnSync(inv.command, [...inv.args, "--repo-root", root], {
+        cwd: root,
+        stdio: ["ignore", "ignore", "ignore"],
+        timeout: 30000,
+        env: hardenedSpawnEnv(),
+      });
+    } catch {
+      // never propagate regenerator failures into the agent loop
+    }
+  }
+}
+
 export function run(
   stdin_text: string,
   options: { consumer_root: string; verbose?: boolean },
@@ -341,8 +532,18 @@ export function run(
     }
   }
 
-  // Unwrap dispatcher envelope (Phase 7.3, hook-architecture-v1.md).
+  // Unwrap dispatcher envelope (Phase 7.3, hook-architecture-v1.md). The
+  // envelope's `event` is read BEFORE the unwrap and kept: step 3.1 needs it to
+  // tell a write (append to the ledger) from a turn end (flush it), and the
+  // inner payload does not carry it.
+  let envelope_event = "";
+  const raw_native = payload["hook_event_name"];
+  if (typeof raw_native === "string") {
+    envelope_event = raw_native;
+  }
   if (["schema_version", "platform", "event", "payload"].every((k) => k in payload)) {
+    const raw_event = payload["event"];
+    envelope_event = typeof raw_event === "string" ? raw_event : envelope_event;
     const inner = payload["payload"];
     payload =
       typeof inner === "object" && inner !== null && !Array.isArray(inner)
@@ -350,6 +551,38 @@ export function run(
         : {};
   }
 
+  const replay = (process.env[REPLAY_ENV_VAR] ?? "").trim() === "1";
+
+  // Flush path (step 3.1): `stop` / `session_end` carry no roadmap path, so the
+  // roots come from the ledger the write path appended to. Nothing dirty → a
+  // read of one small file and exit, which is what makes this cheap enough to
+  // bind on a slot that already carries ten concerns.
+  if (FLUSH_EVENTS.has(envelope_event)) {
+    if (replay) {
+      if (verbose) {
+        process.stderr.write("roadmap-progress-hook: replay mode, skipping flush\n");
+      }
+      return 0;
+    }
+    const dirty = read_dirty_roots(consumer_root);
+    if (dirty.length === 0) {
+      return 0;
+    }
+    // Clear FIRST: a regenerator that hangs or throws must not leave a ledger
+    // that replays the same roots on every subsequent turn end. `_regenerate`
+    // already swallows its own failures, so a cleared ledger plus a failed
+    // regeneration degrades to "stale until the next roadmap write", which is
+    // the same worst case the debounce already accepts.
+    clear_dirty(consumer_root);
+    _regenerate(dirty, verbose);
+    if (verbose) {
+      process.stderr.write(
+        `roadmap-progress-hook: flushed ${dirty.length} dirty root(s) at ${envelope_event}\n`,
+      );
+    }
+    return 0;
+  }
+
   const tool = payload["tool_name"] || payload["toolName"] || payload["tool"];
   if (!(typeof tool === "string" && WRITE_TOOLS.has(tool))) {
     return 0;
@@ -369,59 +602,34 @@ export function run(
     return 0;
   }
 
-  // Replay mode (`AGENT_CONFIG_REPLAY=1`) skips the regenerator subprocess
-  // so fixture dispatches never rewrite agents/roadmaps-progress.md.
-  if ((process.env[REPLAY_ENV_VAR] ?? "").trim() === "1") {
+  // Replay mode (`AGENT_CONFIG_REPLAY=1`) skips both the ledger write and the
+  // regenerator subprocess, so fixture dispatches leave no state and never
+  // rewrite agents/roadmaps-progress.md.
+  if (replay) {
     if (verbose) {
       process.stderr.write("roadmap-progress-hook: replay mode, skipping regenerator\n");
     }
     return 0;
   }
 
-  for (const root of targetRoots) {
-    const script = _resolve_regenerator(root);
-    if (script === null) {
-      // Phase 1 of road-to-hooks-actually-fire-in-consumers: log dispatch
-      // issue directly (this hook runs as a subprocess from the universal
-      // dispatcher; routing through the dispatcher would add latency for
-      // no benefit).
-      try {
-        log_dispatch_issue(
-          root,
-          "roadmap-progress",
-          "prerequisite_missing",
-          "update_roadmap_progress.ts not found at any of: " +
-            ".augment/scripts/, dist/agent-src/scripts/, " +
-            "src/agent-src/scripts/",
-          "./agent-config hooks:install --regen " + "(or ./agent-config init)",
-        );
-      } catch {
-        // observability never breaks the hook
-      }
-      if (verbose) {
-        process.stderr.write(
-          `roadmap-progress-hook: regenerator not found for ${root}, skipping\n`,
-        );
-      }
-      continue;
-    }
-
-    try {
-      // The regenerator is a `.ts` script; run it through tsx (resolved from
-      // a node_modules/.bin found by walking up from the regenerator's dir,
-      // falling back to `npx tsx`), mirroring the dispatcher's `.ts` concerns.
-      // `--repo-root` + cwd pin the regeneration to the edited file's own repo.
-      const inv = _resolve_tsx_invocation(script);
-      spawnSync(inv.command, [...inv.args, "--repo-root", root], {
-        cwd: root,
-        stdio: ["ignore", "ignore", "ignore"],
-        timeout: 30000,
-        env: hardenedSpawnEnv(),
-      });
-    } catch {
-      // never propagate regenerator failures into the agent loop
+  // Write path (step 3.1): record and return. The spawn this used to pay per
+  // write now happens once, at turn end. A ledger that cannot be written falls
+  // back to regenerating inline — the debounce is an optimisation and must never
+  // be the reason a dashboard silently stops updating.
+  if (mark_dirty(consumer_root, Array.from(targetRoots))) {
+    if (verbose) {
+      process.stderr.write(
+        `roadmap-progress-hook: marked ${targetRoots.size} root(s) dirty for tool=${tool}\n`,
+      );
     }
+    return 0;
+  }
+  if (verbose) {
+    process.stderr.write(
+      "roadmap-progress-hook: ledger unwritable, regenerating inline\n",
+    );
   }
+  _regenerate(targetRoots, verbose);
 
   if (verbose) {
     process.stderr.write(`roadmap-progress-hook: regenerated for tool=${tool}\n`);