@event4u/agent-config 14.2.0 → 14.4.0

package/src/scripts/interruption_report.ts

@@ -49,6 +49,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { SESSION_ID_LEN, derive_session_tag } from './chat_history.js';
+
 export const DEFAULT_WINDOW = 30;
 
 export interface LedgerRow {
@@ -70,25 +72,79 @@ export interface HistoryTurn {
 export interface RunReport {
     run_id: string;
     roadmap: string | null;
-    asks: number;
-    handbacks: number;
-    contacts: number;
-    halts: number;
+    /**
+     * Contact counts, or `null` when this run has NO interruption-ledger
+     * entry — a session predating the ledger, or one whose stop hook never
+     * fired.
+     *
+     * R2 round 6, finding 8. These were built unconditionally from the ledger
+     * rows, so an absent run emitted `asks: 0, contacts: 0, halts: 0` — while
+     * this report's own note tells the reader such a run is "reported with the
+     * missing axis null". The aggregate median already excluded them; the ROWS
+     * did not, and a reader consuming rows would score an unmeasured run as
+     * zero contacts. That is precisely the arithmetic falsification criterion
+     * (3) of the pre-registered `user-out-of-loop-baseline` claim forbids —
+     * "scoring an unmeasured run as zero contacts is the arithmetic that would
+     * manufacture the result".
+     */
+    asks: number | null;
+    handbacks: number | null;
+    contacts: number | null;
+    halts: number | null;
     elapsed_minutes: number | null;
     waiting_minutes: number | null;
     working_minutes: number | null;
+    /** `engage` events for this run in `run-continuation.jsonl`. */
+    reengagements: number;
+    /** `halt-stall` events — the anti-stall rung firing, not the loop working. */
+    stall_halts: number;
+    /** Relaunches the supervisor has spent on this run. */
+    relaunches: number;
+    /** Decision memos this run wrote instead of contacting the user. */
+    memos: number;
 }
 
+/**
+ * Runs required before either pre-registered claim may be compared.
+ *
+ * Fixed BEFORE any data by `user-out-of-loop-baseline` and
+ * `roadmap-wall-clock-baseline` in `docs/CLAIMS.md`, both falsification
+ * criterion (3): "≥ 20 recorded runs before any comparison, else
+ * UNDERPOWERED". Named here so the report states the floor it is judging
+ * itself against rather than leaving a reader to look it up.
+ */
+export const POWER_FLOOR_RUNS = 20;
+
 export interface Report {
     window_requested: number;
     sessions_found: number;
     window_short: boolean;
     synthetic_user_turns_excluded: number;
+    /** Runs carrying a contact count — the CONTACT axis's own denominator. */
+    contact_axis_runs: number;
+    /** Runs carrying timing — the WALL-CLOCK axis's own, much smaller, denominator. */
+    wall_clock_axis_runs: number;
+    /**
+     * Agent→user turnarounds behind `median_user_wait_minutes`.
+     *
+     * A THIRD denominator, and it is neither axis's: one run contributes as
+     * many waits as it had turnarounds, so this count is in gaps where the two
+     * above are in runs. Kept separate rather than folded into either.
+     */
+    user_wait_gaps: number;
+    /** The pre-registered floor both claims fix before any comparison. */
+    power_floor_runs: number;
     runs: RunReport[];
     median_contacts_per_run: number | null;
     median_user_wait_minutes: number | null;
     median_elapsed_minutes: number | null;
     median_working_minutes: number | null;
+    /** Phase 5.0 — the autonomy axis. */
+    median_reengagements_per_run: number | null;
+    /** Share of runs whose loop hit the stall rung. `null` with no runs. */
+    stall_halt_rate: number | null;
+    median_relaunches_per_run: number | null;
+    median_memos_per_run: number | null;
     notes: string[];
 }
 
@@ -107,6 +163,140 @@ export function isSyntheticUserText(text: string): boolean {
     return SYNTHETIC_MARKERS.some((m) => text.includes(m));
 }
 
+/**
+ * Look one run's value up in a source keyed differently from the ledger.
+ *
+ * R2 review, finding 2. Three producers write three key spaces for the same
+ * run and the report joined them with exact lookups, so `reengagements`,
+ * `stall_halts`, `stall_halt_rate` and `relaunches` read 0 / 0 % for every
+ * real run while the data sat on disk:
+ *
+ *   - the interruption ledger  `derive_session_tag(id)`  = 16 hex
+ *   - run-continuation.jsonl   `deriveSessionKey(id)`    = 32 hex
+ *   - supervise-relaunches     the RAW `session_id`
+ *
+ * A zero meaning "no instrument" and a zero meaning "the key did not match"
+ * are indistinguishable in the output, and this report prints an explicit
+ * NO INSTRUMENT for two other axes precisely to avoid the first — so a silent
+ * second kind was the worse failure.
+ *
+ * Resolution is EXACT-FIRST and lives here rather than in the readers: a
+ * reader that rewrote its own keys would have to guess what an unrecognised
+ * string means, and guessing "hash it" turns a would-have-matched key into a
+ * guaranteed miss. The readers keep reporting what is on disk; the join owns
+ * the reconciliation, because only the join knows the ledger id it is
+ * looking for.
+ *
+ * The 32-hex key is a prefix-extension of the 16-hex tag ONLY because a
+ * session id carries no whitespace for `fingerprint` to normalise away.
+ * `interruption_report.test.ts` pins that equivalence rather than assuming it.
+ */
+export function lookupByRunId<T>(
+    source: ReadonlyMap<string, T> | Readonly<Record<string, T>>,
+    runId: string,
+): T | undefined {
+    const get = (k: string): T | undefined =>
+        source instanceof Map ? source.get(k) : (source as Record<string, T>)[k];
+    // 1. The key as the ledger spells it. Covers a source that already agrees,
+    //    and every fixture that writes one id everywhere.
+    const exact = get(runId);
+    if (exact !== undefined) return exact;
+    // 2. A 32-hex continuation key whose first SESSION_ID_LEN chars are this tag.
+    const keys: string[] = source instanceof Map ? [...source.keys()] : Object.keys(source);
+    for (const k of keys) {
+        if (k.length === 32 && /^[0-9a-f]+$/.test(k) && k.slice(0, SESSION_ID_LEN) === runId) {
+            return get(k);
+        }
+    }
+    // 3. A raw session id that hashes to this tag.
+    for (const k of keys) {
+        if (derive_session_tag(k) === runId) return get(k);
+    }
+    return undefined;
+}
+
+/**
+ * Phase 5.0 — the autonomy axis, from three runtime sources.
+ *
+ * Each reader is best-effort and returns an empty map on any failure. That is
+ * correct rather than lenient: a run that predates the mechanism genuinely had
+ * zero re-engagements, and refusing to report the other axes because one
+ * source is absent would make the whole report unavailable on a fresh install.
+ */
+export function readContinuationEvents(
+    root: string,
+): Map<string, { engage: number; stall: number }> {
+    const out = new Map<string, { engage: number; stall: number }>();
+    let text: string;
+    try {
+        text = fs.readFileSync(
+            path.join(root, 'agents', 'runtime', 'state', 'run-continuation.jsonl'),
+            'utf-8',
+        );
+    } catch {
+        return out;
+    }
+    for (const line of text.split('\n')) {
+        if (line.trim() === '') continue;
+        let rec: unknown;
+        try {
+            rec = JSON.parse(line);
+        } catch {
+            continue;
+        }
+        if (rec === null || typeof rec !== 'object' || Array.isArray(rec)) continue;
+        const o = rec as Record<string, unknown>;
+        const id = o['run_id'];
+        const ev = o['event'];
+        if (typeof id !== 'string' || typeof ev !== 'string') continue;
+        const cur = out.get(id) ?? { engage: 0, stall: 0 };
+        if (ev === 'engage') cur.engage += 1;
+        else if (ev === 'halt-stall') cur.stall += 1;
+        out.set(id, cur);
+    }
+    return out;
+}
+
+export function readRelaunchLedger(root: string): Record<string, number> {
+    try {
+        const raw: unknown = JSON.parse(
+            fs.readFileSync(
+                path.join(root, 'agents', 'runtime', 'state', 'supervise-relaunches.json'),
+                'utf-8',
+            ),
+        );
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) return {};
+        const out: Record<string, number> = {};
+        for (const [k, v] of Object.entries(raw as Record<string, unknown>)) {
+            if (typeof v === 'number' && Number.isFinite(v) && v >= 0) out[k] = v;
+        }
+        return out;
+    } catch {
+        return {};
+    }
+}
+
+export function readMemoCounts(root: string): Record<string, number> {
+    const base = path.join(root, 'agents', 'runtime', 'state', 'decisions');
+    const out: Record<string, number> = {};
+    let runs: string[];
+    try {
+        runs = fs.readdirSync(base);
+    } catch {
+        return out;
+    }
+    for (const run of runs) {
+        try {
+            out[run] = fs
+                .readdirSync(path.join(base, run))
+                .filter((n) => /^\d{3}\.md$/.test(n)).length;
+        } catch {
+            // a file where a directory was expected — not a run
+        }
+    }
+    return out;
+}
+
 export function median(values: readonly number[]): number | null {
     if (values.length === 0) return null;
     const sorted = [...values].sort((a, b) => a - b);
@@ -237,6 +427,13 @@ export function buildReport(root: string, windowRequested: number): Report {
     // null wall clock rather than disappearing from the denominator.
     for (const id of ledgerRuns) if (!windowedIds.has(id)) runIds.add(id);
 
+    // Phase 5.0 sources. All three are gitignored runtime state, all three are
+    // read best-effort, and an absent one yields zeros rather than an error —
+    // a run predating the mechanism genuinely had zero re-engagements.
+    const continuation = readContinuationEvents(root);
+    const relaunches = readRelaunchLedger(root);
+    const memosByRun = readMemoCounts(root);
+
     const allGaps: number[] = [];
     const runs: RunReport[] = [];
 
@@ -265,16 +462,31 @@ export function buildReport(root: string, windowRequested: number): Report {
             if (elapsed !== null) working = Math.max(0, elapsed - waiting);
         }
 
+        const cont = lookupByRunId(continuation, runId) ?? { engage: 0, stall: 0 };
+        const inLedger = ledgerRuns.has(runId);
         runs.push({
             run_id: runId,
             roadmap: rows.find((r) => r.roadmap !== null)?.roadmap ?? null,
-            asks,
-            handbacks,
-            contacts: contacts.length,
-            halts,
+            // `null`, not 0, when this run is absent from the ledger — see
+            // the field docs above and falsification criterion (3).
+            asks: inLedger ? asks : null,
+            handbacks: inLedger ? handbacks : null,
+            contacts: inLedger ? contacts.length : null,
+            halts: inLedger ? halts : null,
             elapsed_minutes: elapsed,
             waiting_minutes: waiting,
             working_minutes: working,
+            reengagements: cont.engage,
+            stall_halts: cont.stall,
+            // By ROADMAP, not by run id: the relaunch ledger is keyed on the
+            // roadmap slug so its per-run cap survives the new session id a
+            // relaunch produces (see `run_supervise.RelaunchLedger`). Joining
+            // it on the run id would read 0 for every run — the same
+            // permanent-zero shape finding 2 fixed one source over.
+            relaunches: (rows.find((r) => r.roadmap !== null)?.roadmap ?? null) === null
+                ? 0
+                : (relaunches[rows.find((r) => r.roadmap !== null)?.roadmap as string] ?? 0),
+            memos: lookupByRunId(memosByRun, runId) ?? 0,
         });
     }
 
@@ -303,10 +515,40 @@ export function buildReport(root: string, windowRequested: number): Report {
         sessions_found: bySession.size,
         window_short: bySession.size < windowRequested,
         synthetic_user_turns_excluded: synthetic,
+        // Per-axis N against the pre-registered ≥ 20-run floor. The two axes
+        // read DIFFERENT sources — the ledger is a committed append-only file,
+        // the chat history is a rolling buffer — so their effective N diverges
+        // hard, and one banner over both cannot say which is underpowered.
+        //
+        // Measured 2026-08-19: **19** runs carried contacts and 4 carried
+        // timing, out of 21 runs in the window. NEITHER axis cleared the
+        // floor. The two runs in the gap carry timing and no ledger entry, so
+        // they raise the total and not the contact axis — which is the whole
+        // reason the total may not be read as either axis's N.
+        //
+        // R2 round 1, finding 1: this comment first said "21 runs carried
+        // contacts … the contact axis had cleared its own floor", i.e. it
+        // shipped the exact misreading this field exists to prevent, as a
+        // fact, inside the fix for it. The roadmap and CLAIMS.md in the same
+        // change said 19 and "it had not". Worth leaving on the record: the
+        // number is easy to get wrong even while writing the guard against
+        // getting it wrong, which is the argument for reading it off the
+        // field rather than off the total.
+        //
+        // `runsWithLedger` is reused rather than re-filtered (finding 4):
+        // `r.contacts` is null exactly when the run is absent from
+        // `ledgerRuns`, so a second predicate is a second thing to keep true.
+        contact_axis_runs: runsWithLedger,
+        wall_clock_axis_runs: runs.filter((r) => r.elapsed_minutes !== null).length,
+        user_wait_gaps: allGaps.length,
+        power_floor_runs: POWER_FLOOR_RUNS,
         runs,
         notes,
         median_contacts_per_run: median(
-            runs.filter((r) => ledgerRuns.has(r.run_id)).map((r) => r.contacts),
+            runs
+                .filter((r) => ledgerRuns.has(r.run_id))
+                .map((r) => r.contacts)
+                .filter((v): v is number => v !== null),
         ),
         median_user_wait_minutes: median(allGaps),
         median_elapsed_minutes: median(
@@ -315,6 +557,14 @@ export function buildReport(root: string, windowRequested: number): Report {
         median_working_minutes: median(
             runs.map((r) => r.working_minutes).filter((v): v is number => v !== null),
         ),
+        median_reengagements_per_run: median(runs.map((r) => r.reengagements)),
+        // A RATE, not a count: the question is what share of runs hit the
+        // anti-stall rung, and a raw count would rise with the window size and
+        // read as a regression when nothing changed.
+        stall_halt_rate:
+            runs.length === 0 ? null : runs.filter((r) => r.stall_halts > 0).length / runs.length,
+        median_relaunches_per_run: median(runs.map((r) => r.relaunches)),
+        median_memos_per_run: median(runs.map((r) => r.memos)),
     };
 }
 
@@ -322,6 +572,20 @@ function fmt(v: number | null, unit = ''): string {
     return v === null ? 'n/a' : `${Math.round(v * 10) / 10}${unit}`;
 }
 
+/**
+ * The power verdict for ONE axis, printed on that axis's own header.
+ *
+ * `UNDERPOWERED` is the word the claims themselves use, so the reader meets
+ * the same term the falsification criterion is written in. The count is always
+ * shown, including when the floor is cleared — a bare "OK" would leave a
+ * reader unable to tell 20 from 200.
+ */
+function power(n: number, floor: number): string {
+    return n >= floor
+        ? `  ·  n=${n} runs (≥ ${floor} floor cleared)`
+        : `  ·  n=${n} runs — ⚠️  UNDERPOWERED, floor is ${floor}`;
+}
+
 export function renderText(report: Report): string {
     const lines: string[] = [];
     lines.push('interruption_report — road-to-user-out-of-the-loop Phase 0');
@@ -332,19 +596,72 @@ export function renderText(report: Report): string {
     );
     lines.push(`synthetic user turns excluded: ${report.synthetic_user_turns_excluded}`);
     lines.push('');
-    lines.push('CONTACT AXIS');
+    lines.push(`CONTACT AXIS${power(report.contact_axis_runs, report.power_floor_runs)}`);
     lines.push(`  median contacts per run:   ${fmt(report.median_contacts_per_run)}`);
-    lines.push(`  median user wait:          ${fmt(report.median_user_wait_minutes, ' min')}`);
     lines.push('');
-    lines.push('WALL-CLOCK AXIS');
+    lines.push(`WALL-CLOCK AXIS${power(report.wall_clock_axis_runs, report.power_floor_runs)}`);
     lines.push(`  median elapsed per run:    ${fmt(report.median_elapsed_minutes, ' min')}`);
     lines.push(`  median agent working time: ${fmt(report.median_working_minutes, ' min')}`);
+    // `user wait` sits HERE and not under the contact axis, and it carries a
+    // third denominator of its own.
+    //
+    // R2 round 2, finding 1. It used to print under CONTACT AXIS, directly
+    // beneath that axis's ledger-sourced n — so the per-axis fix reproduced
+    // the very conflation it was written to remove, one line further down.
+    // `roadmap-wall-clock-baseline` settles which axis owns it: WAITING is
+    // named as that claim's own instrument, derived from chat-history
+    // timestamps, i.e. the source whose N is the small one.
+    //
+    // And the unit is gaps, not runs: one run contributes as many waits as it
+    // had agent→user turnarounds. Printing a run-count next to it would be the
+    // second half of the same error, so it carries its own count.
+    lines.push(
+        `  median user wait:          ${fmt(report.median_user_wait_minutes, ' min')}` +
+            `  ·  n=${report.user_wait_gaps} gap(s), not runs`,
+    );
     lines.push('');
-    lines.push(`runs: ${report.runs.length}`);
+    lines.push('AUTONOMY AXIS (Phase 5.0)');
+    lines.push(`  median re-engagements:     ${fmt(report.median_reengagements_per_run)}`);
+    lines.push(
+        `  stall-halt rate:           ${
+            report.stall_halt_rate === null
+                ? 'n/a'
+                : `${Math.round(report.stall_halt_rate * 1000) / 10}%`
+        }`,
+    );
+    lines.push(`  median relaunches per run: ${fmt(report.median_relaunches_per_run)}`);
+    lines.push(`  median memos per run:      ${fmt(report.median_memos_per_run)}`);
+    // Two axes the roadmap names and this instrument CANNOT report. Stated as
+    // no-instrument rather than printed as 0, because a zero here would read
+    // as "measured, and it is zero" — the exact confusion between an absent
+    // record and an absent event that this suite records elsewhere.
+    // "cannot run YET" and "pre-registered" were both true when written and
+    // are both false now: the spawn is a published refusal
+    // (road-to-long-horizon-execution 4.0) and `unattended-demotion-gate` took
+    // its honest-null path in the same change-set that refused it. R2 round 2,
+    // finding 2 — `run_supervise.ts` had its identical wording rewritten and
+    // this sibling site in the same diff was missed, which is what the
+    // defect-pattern sweep exists to catch and did not.
+    lines.push('  unattended-vs-attended rework: NO INSTRUMENT, and permanently so — the');
+    lines.push('    unattended lane will not run: the spawn is a published REFUSAL, not an');
+    lines.push('    unbuilt feature (road-to-long-horizon-execution 4.0). `unattended-demotion-gate`');
+    lines.push('    took its honest-null path and is CLOSED — do not read it as a live threshold.');
+    lines.push('  memo revisit rate:            NO INSTRUMENT — a memo carries no revisit marker,');
+    lines.push('    so a revisited decision is indistinguishable from one nobody reopened.');
+    lines.push('');
+    // The total carries its caveat inline, because the roadmap blames THIS
+    // line for the live misreading and round 1 left it untouched (R2 round 2,
+    // finding 11): a per-axis n printed thirty lines earlier does not reach a
+    // reader who scrolled to the number that looks like the sample size.
+    lines.push(
+        `runs: ${report.runs.length}  ·  NOT either axis's N — see the per-axis n above ` +
+            `(contact ${report.contact_axis_runs}, wall-clock ${report.wall_clock_axis_runs})`,
+    );
     for (const run of report.runs) {
         lines.push(
             `  ${run.run_id}  asks=${run.asks} handbacks=${run.handbacks} halts=${run.halts}` +
                 `  elapsed=${fmt(run.elapsed_minutes)} working=${fmt(run.working_minutes)}` +
+                `  re=${run.reengagements} stall=${run.stall_halts} relaunch=${run.relaunches} memo=${run.memos}` +
                 `  roadmap=${run.roadmap ?? '-'}`,
         );
     }

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);