@event4u/agent-config 14.19.0 → 14.20.0

package/src/scripts/handoff_context_hook.ts

@@ -37,10 +37,12 @@ import { fileURLToPath } from 'node:url';
 import { collectRepoAnchor, describeDrift } from './_lib/envelope_grounding.js';
 import { readHookStdin } from './hooks/hook_stdin.js';
 import {
-    RECYCLE_CONSUMED_REL,
-    RECYCLE_ENVELOPE_REL,
     RECYCLE_MAX_AGE_HOURS,
+    predecessorTracePresent,
+    recycle_consumed_rel,
+    resolveContinuityRecord,
 } from './_lib/recycle_envelope_paths.js';
+import { env_session_id } from './sessions_cli.js';
 import {
     hasBoundaryMarker,
     scanEnvelopeDirectives,
@@ -153,8 +155,33 @@ export function consume_handoff_context(root: string, now: Date = new Date()): C
  *   - focus (Phase 3.4): `AGENT_RESUME_FOCUS` narrows what the successor
  *     attacks first — the consumer-side mirror of `next_task`.
  */
-export function consume_recycle_envelope(root: string, now: Date = new Date()): ConsumeDecision {
-    const target = process.env.AGENT_RECYCLE_ENVELOPE_FILE || path.join(root, RECYCLE_ENVELOPE_REL);
+export function consume_recycle_envelope(
+    root: string,
+    now: Date = new Date(),
+    session_id: string | null | undefined = undefined,
+): ConsumeDecision {
+    // Phase 2.1: which record belongs to THIS session is a resolution, not a
+    // path constant. `resolveContinuityRecord` returns `null` with a reason
+    // when it cannot tell — the reader then starts clean and says the reason
+    // out loud rather than resuming from whichever file is newest.
+    //
+    // The id is a PARAMETER with an env fallback, not an env read. The
+    // dispatcher already carries `session_id` in the envelope, and reading the
+    // ambient variable instead means any process that inherits a host's
+    // `CLAUDE_CODE_SESSION_ID` — a test runner in an agent session, most
+    // obviously — resolves a foreign identity and reports the record absent.
+    const sessionId = session_id === undefined ? env_session_id() : session_id;
+    const override = process.env.AGENT_RECYCLE_ENVELOPE_FILE;
+    let target: string;
+    if (override !== undefined && override !== '') {
+        target = override;
+    } else {
+        const resolved = resolveContinuityRecord(root, sessionId);
+        if (resolved.file === null) {
+            return { action: 'absent', reason: resolved.reason };
+        }
+        target = resolved.file;
+    }
     let text: string;
     try {
         text = fs.readFileSync(target, 'utf-8');
@@ -164,7 +191,10 @@ export function consume_recycle_envelope(root: string, now: Date = new Date()):
 
     const consume = (): void => {
         try {
-            fs.renameSync(target, path.join(path.dirname(target), path.basename(RECYCLE_CONSUMED_REL)));
+            fs.renameSync(
+                target,
+                path.join(path.dirname(target), path.basename(recycle_consumed_rel(sessionId))),
+            );
         } catch {
             try {
                 fs.unlinkSync(target); // fallback — never let it survive
@@ -212,6 +242,19 @@ export function consume_recycle_envelope(root: string, now: Date = new Date()):
         return { action: 'discard', reason: 'recycle envelope workspace does not resolve' };
     }
 
+    // Lineage (Phase 2.3): a record that NAMES a predecessor is claiming a
+    // chain. If nothing in this workspace corroborates that session, the claim
+    // is unverifiable and the record is refused — never resolved to whatever
+    // else is lying about.
+    const predecessor = String(envelope['predecessor'] ?? '').trim();
+    if (predecessor !== '' && !predecessorTracePresent(root, predecessor)) {
+        consume();
+        return {
+            action: 'discard',
+            reason: `recycle envelope names predecessor "${predecessor}", which has no trace in this workspace`,
+        };
+    }
+
     // Drift first: a stale resume against the wrong tree is the failure the
     // reader must see before anything else in the block.
     const drift = describeDrift(envelope, collectRepoAnchor(root));
@@ -221,7 +264,7 @@ export function consume_recycle_envelope(root: string, now: Date = new Date()):
     const focus = (process.env.AGENT_RESUME_FOCUS ?? '').trim();
     const block = wrapAsPriorSessionData(JSON.stringify(envelope, null, 2), {
         kind: 'recycle-envelope',
-        source: RECYCLE_ENVELOPE_REL,
+        source: path.relative(root, target) || path.basename(target),
         warnings: [
             ...drift,
             ...(focus ? [`FOCUS: attack "${focus}" first — the rest of this envelope is context.`] : []),
@@ -265,7 +308,11 @@ export function main(): number {
         }
         if (event === 'session_start') {
             const handoff = consume_handoff_context(root);
-            const recycle = consume_recycle_envelope(root);
+            const recycle = consume_recycle_envelope(
+                root,
+                new Date(),
+                String(envelope['session_id'] ?? '').trim() || env_session_id(),
+            );
             const blocks: string[] = [];
             const reasons: string[] = [];
             // Recycle envelope first — it is the task-state restore the

package/src/scripts/hooks/session_eol_hook.ts

@@ -45,7 +45,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import recycleThresholdConfig from '../../config/recycle-threshold-budget.json';
 
-import { RECYCLE_ENVELOPE_REL } from '../_lib/recycle_envelope_paths.js';
+import { recycle_envelope_rel } from '../_lib/recycle_envelope_paths.js';
 import {
     emptyCounters,
     eolSessionKey,
@@ -180,8 +180,16 @@ export function readState(file: string): SessionEolState {
  * session's state — a wrong resume instead of an empty one. An envelope whose
  * `written_at` predates the advisory is not this session's.
  */
-export function envelopeExists(workspaceRoot: string, since: string | null = null): boolean {
-    const target = path.join(workspaceRoot, RECYCLE_ENVELOPE_REL);
+export function envelopeExists(
+    workspaceRoot: string,
+    since: string | null = null,
+    sessionId: string | null = null,
+): boolean {
+    // Phase 2.1: the record is keyed by session, so the counter-check must look
+    // at THIS session's path. Checking the shared name would read a peer's
+    // record as proof that this session wrote one — the same cross-session
+    // confusion the key exists to remove, re-created in the checker.
+    const target = path.join(workspaceRoot, recycle_envelope_rel(sessionId));
     let raw: string;
     try {
         raw = fs.readFileSync(target, 'utf-8');
@@ -212,10 +220,10 @@ export function envelopeExists(workspaceRoot: string, since: string | null = nul
  * the next action the advisory recommended is the one that destroys the
  * session.
  */
-export function buildMissingEnvelopeLine(workspaceRoot: string): string {
+export function buildMissingEnvelopeLine(workspaceRoot: string, sessionId: string | null = null): string {
     return (
         `recycle advised earlier, but no envelope exists at ` +
-        `${path.join(workspaceRoot, RECYCLE_ENVELOPE_REL)} — /clear now starts the successor ` +
+        `${path.join(workspaceRoot, recycle_envelope_rel(sessionId))} — /clear now starts the successor ` +
         `from nothing. Re-run \`agent-config session:recycle\` and check that it prints the ` +
         `absolute path it wrote before clearing.`
     );
@@ -334,11 +342,14 @@ export function main(): number {
     // `AGENT_RECYCLE_THRESHOLD_TOKENS=0` is documented as the emergency switch
     // for the whole advisory lane, and a lane that keeps one more warn after
     // being switched off is not off.
+    // Raw id, not `sessionKey`: the record path is built from the id the host
+    // exported (`safe_stem`), never from the hashed state-file key.
+    const rawSessionId = payloadSessionId(payload, envelope) || null;
     const shouldWarnMissing =
         threshold !== null &&
         state.advisory_fired_at !== null &&
         (state.missing_envelope_warned_at ?? null) === null &&
-        !envelopeExists(workspaceRoot, state.advisory_fired_at);
+        !envelopeExists(workspaceRoot, state.advisory_fired_at, rawSessionId);
 
     const nextState: SessionEolState = {
         schema_version: 1,
@@ -415,7 +426,7 @@ export function main(): number {
             `${JSON.stringify({
                 decision: 'warn',
                 reason: 'session-eol: recycle advised, no envelope written',
-                additional_context: buildMissingEnvelopeLine(workspaceRoot),
+                additional_context: buildMissingEnvelopeLine(workspaceRoot, rawSessionId),
             })}\n`,
         );
         return EXIT_WARN;

package/src/scripts/install.ts

@@ -75,6 +75,7 @@ import { build_merge_entries } from './_lib/json_pointers.js';
 import { is_claude_builtin_name } from './_lib/claude_builtin_names.js';
 import * as installed_lock from './_lib/installed_lock.js';
 import * as mcp_bridge from './_lib/mcp_bridge.js';
+import * as mcp_consent from './_lib/mcp_consent_residual.js';
 import * as scoped_projection from './_lib/scoped_projection.js';
 import * as surface_tiers from './_lib/surface_tiers.js';
 import * as global_deploy_inventory from './_lib/global_deploy_inventory.js';
@@ -5121,11 +5122,9 @@ function _main_project_install(
             ...ensure_augment_bridge(project_root, opts.force),
         ];
         if (_is_tool_enabled(tools, 'claude-code')) {
-            merged_keys_by_tool['claude-code'] = [
-                ...ensure_claude_bridge(project_root, opts.force),
-                ...ensure_mcp_bridge(project_root, opts.force),
-            ];
+            merged_keys_by_tool['claude-code'] = ensure_claude_bridge(project_root, opts.force);
         }
+        mcp_bridge.registerMcpHosts(merge_json_file, project_root, opts.force, package_root, tools, merged_keys_by_tool);
         if (_is_tool_enabled(tools, 'cursor')) {
             merged_keys_by_tool['cursor'] = ensure_cursor_bridge(project_root, opts.force);
         }
@@ -5226,6 +5225,7 @@ function _main_project_install(
             );
             process.stdout.write('\n');
         }
+        mcp_consent.printResiduals(tools, state.QUIET);
         if (_is_tool_enabled(tools, 'claude-code')) {
             const team_hint = _team_setup_hint_line(project_root);
             if (team_hint !== null) {

package/src/scripts/lint_agent_security.ts

@@ -26,8 +26,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { runCountedProbe } from "./_lib/counted_probe.js";
-import { assertWatchlistResolves, DeadScopeError } from "./_lib/scan_scope.js";
+import { runCountedProbe, type ProbeResult } from "./_lib/counted_probe.js";
+import { assertWatchlistResolves, DeadScopeError, reportScanned } from "./_lib/scan_scope.js";
+import { runGateCli, runSelfTest } from "./_lib/gate_self_test.js";
+import os from "node:os";
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 
@@ -50,26 +52,162 @@ const LINTERS: ReadonlyArray<[string, string]> = [
   ["dangerous-frontmatter", "lint_skill_frontmatter_safety.ts"],
 ];
 
-function _run(script: string): [number, Finding[]] {
-  // Spawn the child linter's `.ts` twin via the repo-local tsx binary
-  // (capture_output=True, text=True equivalent). Mirrors the retired Python implementation's
-  // `subprocess.run([sys.executable, HERE/<child>.py, "--json"])`, now that the
-  // children are TypeScript and the `.py` originals are deleted.
-  // Bounded read: a truncated `--json` payload would fail to parse and be
-  // swallowed as zero findings — a security aggregate reporting clean because
-  // it lost the answer. `runCountedProbe` throws on overflow instead.
-  const proc = runCountedProbe(tsxBin, [path.join(_HERE, script), "--json"]);
-  let findings: Finding[];
+/**
+ * How one child linter is executed.
+ *
+ * A seam, not a policy: the production runner is `_spawnChild` below and is the
+ * default everywhere. It exists so the failure corpus can drive each way a
+ * child can fail to ANSWER — non-zero with empty stdout, zero with unparsable
+ * stdout, and a spawn that never happened — without planting a broken linter in
+ * the tree. The four ways are not reproducible any other way: a real child that
+ * crashes on demand is a child that has to be able to crash in production.
+ */
+export type ChildRunResult = ProbeResult | { readonly skipped: SkipReason };
+export type ChildRunner = (script: string) => ChildRunResult;
+
+// Spawn the child linter's `.ts` twin via the repo-local tsx binary
+// (capture_output=True, text=True equivalent). Mirrors the retired Python implementation's
+// `subprocess.run([sys.executable, HERE/<child>.py, "--json"])`, now that the
+// children are TypeScript and the `.py` originals are deleted.
+// Bounded read: a truncated `--json` payload would fail to parse and be
+// swallowed as zero findings — a security aggregate reporting clean because
+// it lost the answer. `runCountedProbe` throws on overflow instead.
+function _spawnChild(root: string | null): ChildRunner {
+  return (script) =>
+    runCountedProbe(tsxBin, [
+      path.join(_HERE, script),
+      "--json",
+      ...(root === null ? [] : ["--root", root]),
+    ]);
+}
+
+/**
+ * The closed set of terminal outcomes a child run can have.
+ *
+ * Closed is the whole point. Before this, a child had one outcome — "here are
+ * its findings" — and every way of not answering collapsed into an empty
+ * findings array indistinguishable from a clean run. Three states make the
+ * distinction expressible, and `failed` is the one that blocks.
+ */
+export type ChildOutcome =
+  | {
+      readonly kind: "completed";
+      readonly findings: Finding[];
+      readonly exitCode: number;
+      /** Artifacts this child reported inspecting. See `CHILD_SCANNED` below. */
+      readonly scanned: number;
+    }
+  | { readonly kind: "failed"; readonly detail: string; readonly exitCode: number | null }
+  | { readonly kind: "skipped"; readonly reason: SkipReason };
+
+/**
+ * Skip reasons, as a RUNNER CONSTANT rather than configuration.
+ *
+ * A configurable skip list is a fail-open switch with a settings file in front
+ * of it: whoever can add a reason can silence a child. Keeping the set here
+ * means adding one is a reviewed code change in the gate itself.
+ *
+ * NO CHILD PRODUCES A SKIP TODAY, and that is stated rather than implied — all
+ * five apply on every platform this suite runs on. The state exists because the
+ * alternative to having it is the pressure this repair creates: once a
+ * non-completing child blocks, a genuinely non-applicable child would have to
+ * be expressed as `failed`, and the fix for that would be to weaken `failed`.
+ * A legal non-failing terminal state is what stops that. It is exercised
+ * through the runner seam in the failure corpus, so the branch is not dead.
+ */
+export const SKIP_REASONS = {
+  PLATFORM_NOT_APPLICABLE: "not applicable on this platform",
+} as const;
+export type SkipReason = (typeof SKIP_REASONS)[keyof typeof SKIP_REASONS];
+
+/**
+ * The child `--json` contract, stated so a violation of it is nameable:
+ *
+ *   exit 0  — ran, here is the findings array (possibly empty)
+ *   exit 1  — ran, here is the findings array (non-empty)
+ *   anything else, or a non-array payload, or unparsable stdout, or no run at
+ *   all — the child did not answer.
+ *
+ * Exit 1 with an EMPTY array is a violation and not a nit: every child returns
+ * its dead-scope code (1 or 2) with nothing on stdout, which is precisely the
+ * "the corpus moved and I read nothing" case that used to score as clean.
+ */
+function _classify(res: ChildRunResult): ChildOutcome {
+  // The execution layer decides WHETHER a child applies here; the reason it may
+  // give comes from `SKIP_REASONS` above, so a new reason is a reviewed code
+  // change in this file rather than a value someone can supply.
+  if ("skipped" in res) {
+    return { kind: "skipped", reason: res.skipped };
+  }
+  const proc = res;
+  // spawnSync reports null when the process was signalled or never spawned.
+  if (proc.status === null) {
+    return {
+      kind: "failed",
+      exitCode: null,
+      detail: `the child never ran (${proc.failure ?? "no exit status reported"})`,
+    };
+  }
+  let parsed: unknown;
   try {
-    const parsed: unknown = JSON.parse((proc.stdout ?? "") || "[]");
-    findings = Array.isArray(parsed) ? (parsed as Finding[]) : [];
+    parsed = JSON.parse((proc.stdout ?? "") || "[]");
   } catch {
-    findings = [];
+    return {
+      kind: "failed",
+      exitCode: proc.status,
+      detail:
+        `exited ${String(proc.status)} and its stdout was not JSON — a crashed child that ` +
+        "printed a diagnostic used to be read as zero findings",
+    };
+  }
+  if (!Array.isArray(parsed)) {
+    return {
+      kind: "failed",
+      exitCode: proc.status,
+      detail:
+        `exited ${String(proc.status)} and its stdout parsed but was not a findings array — ` +
+        "a JSON error object used to be read as zero findings",
+    };
+  }
+  const findings = parsed as Finding[];
+  if (proc.status !== 0 && !(proc.status === 1 && findings.length > 0)) {
+    return {
+      kind: "failed",
+      exitCode: proc.status,
+      detail:
+        `exited ${String(proc.status)} with ${String(findings.length)} finding(s), which is outside ` +
+        "the --json contract (0 = clean, 1 = findings; every other code means it could not run)",
+    };
+  }
+  // A child that ran but did not say what it read leaves the aggregate unable to
+  // publish a real corpus size — the same class of unknown as a crashed child,
+  // so it gets the same verdict rather than a silent zero.
+  const scanned = _childScanned(proc.stderr ?? "");
+  if (scanned === null) {
+    return {
+      kind: "failed",
+      exitCode: proc.status,
+      detail:
+        `exited ${String(proc.status)} without reporting what it inspected — an aggregate ` +
+        "corpus size cannot be published from a child that did not state one",
+    };
+  }
+  return { kind: "completed", findings, exitCode: proc.status, scanned };
+}
+
+/** Read a child's `scanned: <N>` line off its stderr. `null` = it printed none. */
+function _childScanned(stderr: string): number | null {
+  for (const line of stderr.split("\n")) {
+    const m = /^scanned: (\d+)$/.exec(line.trim());
+    if (m) {
+      return Number.parseInt(m[1] as string, 10);
+    }
   }
-  // Python returncode of a normally-exited process is its exit code; spawnSync
-  // reports null when the process was signalled / failed to spawn.
-  const returncode = proc.status ?? 1;
-  return [returncode, findings];
+  return null;
+}
+
+function _run(script: string, runChild: ChildRunner): ChildOutcome {
+  return _classify(runChild(script));
 }
 
 function _is_fail(f: Finding): boolean {
@@ -84,7 +222,7 @@ interface SarifReport {
   runs: unknown[];
 }
 
-function _sarif(all_findings: Finding[]): SarifReport {
+function _sarif(all_findings: Finding[], outcomes: ReadonlyArray<[string, string, ChildOutcome]>): SarifReport {
   const results: unknown[] = [];
   for (const f of all_findings) {
     const lineRaw = f["line"];
@@ -109,6 +247,21 @@ function _sarif(all_findings: Finding[]): SarifReport {
       ],
     });
   }
+  // Execution state rides in SARIF's OWN `invocations` array — the schema
+  // already models "did this tool run and with what exit code", so a parallel
+  // metadata block beside it would be a second, unread copy of the same fact.
+  // One invocation per child, in the order the children ran.
+  //
+  // `executionSuccessful` is the field a SARIF consumer reads to decide whether
+  // an empty `results` array means "clean" or "never looked". That is exactly
+  // the question this whole repair is about, so it is the field that carries it.
+  const invocations = outcomes.map(([, script, outcome]) => ({
+    commandLine: `${script} --json`,
+    executionSuccessful: outcome.kind === "completed",
+    ...(outcome.kind === "skipped" || outcome.exitCode === null
+      ? {}
+      : { exitCode: outcome.exitCode }),
+  }));
   return {
     $schema: "https://json.schemastore.org/sarif-2.1.0.json",
     version: "2.1.0",
@@ -121,6 +274,7 @@ function _sarif(all_findings: Finding[]): SarifReport {
             rules: LINTERS.map(([cid]) => ({ id: cid })),
           },
         },
+        invocations,
         results,
       },
     ],
@@ -149,10 +303,13 @@ function _pyJsonDumpsIndent2(obj: unknown): string {
 interface ParsedArgs {
   sarif: string | null;
   quiet: boolean;
+  /** Bounded scan base, forwarded verbatim to every child. Null = the package root. */
+  root: string | null;
+  selfTest: boolean;
 }
 
 function parse_args(argv: string[]): ParsedArgs {
-  const out: ParsedArgs = { sarif: null, quiet: false };
+  const out: ParsedArgs = { sarif: null, quiet: false, root: null, selfTest: false };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i] as string;
     if (a === "--sarif" || a.startsWith("--sarif=")) {
@@ -170,11 +327,28 @@ function parse_args(argv: string[]): ParsedArgs {
         i += 1;
         out.sarif = next;
       }
+    } else if (a === "--root" || a.startsWith("--root=")) {
+      const eq = a.indexOf("=");
+      if (eq !== -1) {
+        out.root = a.slice(eq + 1);
+      } else {
+        const next = argv[i + 1];
+        if (next === undefined) {
+          process.stderr.write(
+            "lint_agent_security: error: argument --root: expected one argument\n",
+          );
+          process.exit(2);
+        }
+        i += 1;
+        out.root = next;
+      }
+    } else if (a === "--self-test") {
+      out.selfTest = true;
     } else if (a === "--quiet") {
       out.quiet = true;
     } else if (a === "-h" || a === "--help") {
       process.stdout.write(
-        "usage: lint_agent_security [-h] [--sarif PATH] [--quiet]\n",
+        "usage: lint_agent_security [-h] [--sarif PATH] [--quiet] [--root DIR] [--self-test]\n",
       );
       process.exit(0);
     }
@@ -182,8 +356,17 @@ function parse_args(argv: string[]): ParsedArgs {
   return out;
 }
 
-export function main(argv: string[] | null = null): number {
+export interface MainOptions {
+  /** Override how child linters are executed. Test seam; production uses `_spawnChild`. */
+  readonly runChild?: ChildRunner;
+}
+
+export function main(argv: string[] | null = null, opts: MainOptions = {}): number {
   const args = parse_args(argv ?? process.argv.slice(2));
+  if (args.selfTest) {
+    return _selfTest();
+  }
+  const runChild = opts.runChild ?? _spawnChild(args.root);
 
   // This runner owns no corpus of its own — it guards five named child linters,
   // so its scope is that watch list. `_run` swallows an unparseable child
@@ -204,9 +387,26 @@ export function main(argv: string[] | null = null): number {
   }
 
   const all_findings: Finding[] = [];
+  const outcomes: Array<[string, string, ChildOutcome]> = [];
+  const notCompleted: string[] = [];
   let blocking = 0;
+  let totalScanned = 0;
   for (const [check, script] of LINTERS) {
-    const [, findings] = _run(script);
+    const outcome = _run(script, runChild);
+    outcomes.push([check, script, outcome]);
+    if (outcome.kind === "failed") {
+      // Named on the line, because "one child failed" sends a reader to five
+      // linters. The exit code stays on the line for the same reason.
+      notCompleted.push(check);
+      process.stdout.write(`  ❌ ${check}: did not complete — ${outcome.detail}\n`);
+      continue;
+    }
+    if (outcome.kind === "skipped") {
+      process.stdout.write(`  ⏭️ ${check}: skipped — ${outcome.reason}\n`);
+      continue;
+    }
+    const findings = outcome.findings;
+    totalScanned += outcome.scanned;
     all_findings.push(...findings);
     const fails = findings.filter((f) => _is_fail(f)).length;
     const warns = findings.length - fails;
@@ -218,11 +418,50 @@ export function main(argv: string[] | null = null): number {
   if (args.sarif) {
     const out = args.sarif;
     fs.mkdirSync(path.dirname(out), { recursive: true });
-    fs.writeFileSync(out, _pyJsonDumpsIndent2(_sarif(all_findings)), "utf-8");
+    fs.writeFileSync(out, _pyJsonDumpsIndent2(_sarif(all_findings, outcomes)), "utf-8");
     process.stdout.write(`  SARIF → ${args.sarif}\n`);
   }
 
+  // Publish what the scan actually read, on EVERY path including the red one.
+  // The umbrella owns no corpus of its own — this number is the SUM of the five
+  // children's own reported counts, so it is artifact INSPECTIONS rather than
+  // distinct artifacts (a file two children read counts twice). That is the
+  // stronger collapse detector: a distinct-union figure would stay high while
+  // one child's corpus went missing, which is the failure this line exists to
+  // make visible. `src/config/gate-coverage.yml` carries the floor.
+  reportScanned({
+    gate: "lint_agent_security",
+    scanned: totalScanned,
+    units: "artifact inspection(s) across the five child linters",
+    roots: LINTERS.map(([cid]) => cid),
+    ...(notCompleted.length > 0
+      ? {
+          allowEmpty:
+            "WATCHLIST_DRIVEN: a child that did not complete reports no count. Zero here means " +
+            "every child failed, which this run is already exiting 1 for and naming — the scope " +
+            "is not dead, the children are.",
+        }
+      : {}),
+  });
+
   process.stdout.write("\n");
+  // A child that did not answer is reported BEFORE findings and fails on its
+  // own. The two are independent verdicts: findings say the corpus is dirty,
+  // a non-completing child says the verdict is unknown, and an unknown verdict
+  // is not a pass. Both can hold at once, and both print.
+  if (notCompleted.length > 0) {
+    process.stdout.write(
+      `❌  agent-security: ${notCompleted.length} of ${LINTERS.length} child linter(s) did not complete ` +
+        `(${notCompleted.join(", ")}). A child that did not answer is not a clean scan — ` +
+        "run it directly for its own diagnostic.\n",
+    );
+    if (blocking) {
+      process.stdout.write(
+        `❌  agent-security: ${blocking} blocking finding(s) from the children that did complete.\n`,
+      );
+    }
+    return 1;
+  }
   if (blocking) {
     process.stdout.write(
       `❌  agent-security: ${blocking} blocking finding(s). ` +
@@ -237,6 +476,58 @@ export function main(argv: string[] | null = null): number {
   return 0;
 }
 
+/**
+ * `--self-test` — prove, on demand, that the shipped binary still rejects.
+ *
+ * The two rejecting cases are the two ways this gate is supposed to go red, and
+ * they are different failures rather than one failure twice:
+ *
+ *  - EMPTY SCOPE. Every child asserts its own corpus is non-empty, so an empty
+ *    root makes all five exit non-zero with nothing on stdout — which, since the
+ *    fail-closed repair, is a run failure the umbrella names. This is also the
+ *    negative control the coverage floor owes: the run publishes `scanned: 0`,
+ *    and 0 is below any floor above zero, so `check_gate_coverage` reds on it.
+ *  - A PLANTED PAYLOAD. A zero-width joiner inside a `.md` file under an
+ *    otherwise clean root, which a child must flag as a blocking finding.
+ *
+ * The accepting case is the same root without the payload. Without it, a gate
+ * that returned non-zero unconditionally would score two rejections and look
+ * healthy.
+ */
+function _selfTest(): number {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "lint-agent-security-selftest-"));
+  const mk = (name: string, body: string): string => {
+    const dir = path.join(tmp, name, "src", "skills", "candidate");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "SKILL.md"), body, "utf-8");
+    return path.join(tmp, name);
+  };
+  const cleanRoot = mk("clean", "---\ntitle: candidate\n---\n\nOrdinary prose with nothing hidden in it.\n");
+  // U+200D ZERO WIDTH JOINER between two words — invisible, and exactly the
+  // hidden-instruction carrier class this umbrella exists to catch.
+  const payloadRoot = mk("payload", "---\ntitle: candidate\n---\n\nOrdinary\u200dprose with something hidden in it.\n");
+  const emptyRoot = path.join(tmp, "empty");
+  fs.mkdirSync(emptyRoot, { recursive: true });
+
+  const run = (root: string): number =>
+    runGateCli(REPO_ROOT, "src/scripts/lint_agent_security.ts", ["--root", root], REPO_ROOT);
+
+  try {
+    return runSelfTest({
+      gate: "lint_agent_security",
+      minCases: 3,
+      minRejectCases: 2,
+      cases: [
+        { name: "empty scope — every child reads nothing and the aggregate refuses", expect: "reject", run: () => run(emptyRoot) },
+        { name: "planted zero-width joiner — a child flags it and the aggregate blocks", expect: "reject", run: () => run(payloadRoot) },
+        { name: "clean root — the same scope without the payload still passes", expect: "accept", run: () => run(cleanRoot) },
+      ],
+    });
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;