@event4u/agent-config 9.33.0 → 9.35.0

package/src/agent-src/templates/scripts/work_engine/hooks/builtin/staged_confirmation_store.ts

@@ -0,0 +1,307 @@
+/**
+ * Staged-confirmation store — the I/O half, and the half that makes
+ * exactly-once real.
+ *
+ * `staged_confirmation.ts` decides what a confirmation attempt MEANS. It cannot
+ * make the transition happen only once: two processes that both read a
+ * `pending` record and both conclude `execute` is a check-then-act race, and no
+ * pure function closes it. So the claim is a **directory rename**, which the
+ * filesystem performs atomically — the first caller moves
+ * `pending/<token>.json` to `resolved/`, every later caller gets `ENOENT` and
+ * learns the stage is already taken.
+ *
+ * That is also why the state lives in the path and not only in a field: a
+ * read-modify-write of a `state:` key would reopen exactly the window the
+ * rename closes.
+ *
+ * Records live under `agents/runtime/staged-confirmations/`, which the repo
+ * `.gitignore` already covers via the `/agents/runtime/` catch-all — a staged
+ * action is machine-generated local state, never a tracked artefact. The store
+ * mirrors `_lib/self_repair_store.ts`: one file per identity, every read
+ * tolerant of a malformed file, and no throw on a missing directory.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import {
+    confirmOnce,
+    declineStage,
+    type ConfirmOutcome,
+    type StageState,
+    type StagedAction,
+    stageStatus,
+} from './staged_confirmation.js';
+
+export const STORE_REL = path.join('agents', 'runtime', 'staged-confirmations');
+
+export function storeDir(root: string): string {
+    return path.join(root, STORE_REL);
+}
+
+function pendingDir(root: string): string {
+    return path.join(storeDir(root), 'pending');
+}
+
+function resolvedDir(root: string): string {
+    return path.join(storeDir(root), 'resolved');
+}
+
+/**
+ * A token is a filename before it is an identifier, so every site that turns
+ * one into a path checks it first — the read verbs, the write verb, and the
+ * record guard itself.
+ *
+ * `deriveToken` returns a 16-char sha256 prefix, so a token this module mints
+ * is always safe. Everything else is a way in: `readPending`,
+ * `claimConfirmation` and `declineConfirmation` take a caller-supplied token;
+ * `putPending` joins `stage.token` from a caller-built record (verified: it
+ * wrote outside the store root); and `isStage` accepted any string, so a record
+ * written by something else carried its token into the prune path. All four are
+ * guarded, and `path.join(pendingDir(root), '../x.json')` resolving outside
+ * `pending/` is what makes that necessary.
+ */
+const _TOKEN_RE = /^[0-9a-f]{8,64}$/;
+
+export function isSafeToken(token: string): boolean {
+    return _TOKEN_RE.test(token);
+}
+
+/**
+ * Every field the module later reads, `staged_at` included.
+ *
+ * It checked four of five while still asserting `v is StagedAction`, so a
+ * record that was valid JSON but carried no `staged_at` passed the guard and
+ * reached `listPending`'s `staged_at.localeCompare(...)`: a TypeError thrown
+ * through `roadmap_gates.renderPending`, i.e. one malformed file on disk taking
+ * out a shipped gate. An unsound guard is worse than no guard — it makes the
+ * caller's `!== null` check read as a proof that it is not.
+ */
+function isStage(v: unknown): v is StagedAction {
+    if (typeof v !== 'object' || v === null) {
+        return false;
+    }
+    const s = v as Partial<StagedAction>;
+    return (
+        typeof s.token === 'string' &&
+        isSafeToken(s.token) &&
+        typeof s.action === 'string' &&
+        typeof s.object === 'string' &&
+        typeof s.staged_at === 'string' &&
+        typeof s.expires_at === 'string'
+    );
+}
+
+function readStageFile(file: string): StagedAction | null {
+    try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        return isStage(parsed) ? parsed : null;
+    } catch {
+        return null;
+    }
+}
+
+function writeStageFile(file: string, stage: StagedAction): void {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(stage, null, 2)}\n`, 'utf-8');
+}
+
+/**
+ * Persist a freshly staged action. Returns the path written.
+ *
+ * Throws on an unsafe token rather than returning: a caller reaching here with
+ * one built the record itself and has a bug, and `writeStageFile` creates
+ * directories, so a silent refusal would look like a successful stage nothing
+ * can ever confirm.
+ */
+export function putPending(root: string, stage: StagedAction): string {
+    if (!isSafeToken(stage.token)) {
+        throw new Error(
+            `staged-confirmation: refusing to write under an unsafe token '${stage.token}' — ` +
+                'a token is a filename and must match the deriveToken shape',
+        );
+    }
+    const file = path.join(pendingDir(root), `${stage.token}.json`);
+    writeStageFile(file, stage);
+    return file;
+}
+
+export function readPending(root: string, token: string): StagedAction | null {
+    if (!isSafeToken(token)) {
+        return null;
+    }
+    return readStageFile(path.join(pendingDir(root), `${token}.json`));
+}
+
+export function readResolved(root: string, token: string): StagedAction | null {
+    if (!isSafeToken(token)) {
+        return null;
+    }
+    return readStageFile(path.join(resolvedDir(root), `${token}.json`));
+}
+
+/**
+ * Every stage still in `pending/`, with its effective status at `now` so an
+ * expired one is never rendered as awaiting approval. Sorted by `staged_at`
+ * (oldest first, ties by token) so two runs on an unchanged store print
+ * byte-identical output.
+ */
+export function listPending(
+    root: string,
+    now: number,
+): { stage: StagedAction; status: StageState | 'expired' }[] {
+    let names: string[];
+    try {
+        names = fs.readdirSync(pendingDir(root));
+    } catch {
+        return [];
+    }
+    const out: { stage: StagedAction; status: StageState | 'expired' }[] = [];
+    for (const n of names.sort()) {
+        if (!n.endsWith('.json')) {
+            continue;
+        }
+        const stage = readStageFile(path.join(pendingDir(root), n));
+        if (stage !== null) {
+            out.push({ stage, status: stageStatus(stage, now) });
+        }
+    }
+    out.sort(
+        (a, b) =>
+            a.stage.staged_at.localeCompare(b.stage.staged_at) ||
+            a.stage.token.localeCompare(b.stage.token),
+    );
+    return out;
+}
+
+/**
+ * Atomically claim a pending stage and decide the outcome.
+ *
+ * Order matters and is the whole mechanism:
+ *
+ *   1. Read the record. An absent one is `token-mismatch` — from the caller's
+ *      side an unknown token and a wrong token are the same fact, and inventing
+ *      a third outcome for "was never staged" would only be actionable if the
+ *      store were a public index, which it is not.
+ *   2. Ask `confirmOnce` what the outcome WOULD be. A mismatch, a decline, or
+ *      an expiry never claims anything — a stale surface must not consume a
+ *      stage a human might still legitimately confirm.
+ *   3. Only for `execute`: rename `pending/` → `resolved/`. That is the claim.
+ *      `ENOENT` means a concurrent caller won the race, so this caller reports
+ *      `already-confirmed` and does NOT act — the exactly-once guarantee.
+ *   4. Write the confirmed record into `resolved/`, overwriting the moved file
+ *      with the same content plus `state`/`resolved_at`.
+ */
+export function claimConfirmation(
+    root: string,
+    token: string,
+    now: number,
+): { outcome: ConfirmOutcome; stage: StagedAction | null } {
+    if (!isSafeToken(token)) {
+        // Nothing this module staged can have that shape, so the honest answer
+        // is the same one an unknown token gets — and refusing here is what
+        // keeps the rename below off an arbitrary path.
+        return { outcome: 'token-mismatch', stage: null };
+    }
+    const pendingFile = path.join(pendingDir(root), `${token}.json`);
+    const stage = readStageFile(pendingFile);
+    if (stage === null) {
+        const already = readResolved(root, token);
+        if (already !== null) {
+            // `pruneExpired` moves a stage here WITHOUT rewriting `state`, so the
+            // status is derived rather than read off the field — otherwise an
+            // expired stage swept out of `pending/` would report as confirmed,
+            // which is the one wrong answer available here.
+            const status = stageStatus(already, now);
+            const outcome: ConfirmOutcome =
+                status === 'expired' ? 'expired' : status === 'declined' ? 'declined' : 'already-confirmed';
+            return { outcome, stage: already };
+        }
+        return { outcome: 'token-mismatch', stage: null };
+    }
+
+    const decided = confirmOnce(stage, token, now);
+    if (decided.outcome !== 'execute') {
+        return decided;
+    }
+
+    const resolvedFile = path.join(resolvedDir(root), `${token}.json`);
+    fs.mkdirSync(resolvedDir(root), { recursive: true });
+    try {
+        fs.renameSync(pendingFile, resolvedFile);
+    } catch {
+        // Lost the race, or the pending file vanished between the read and the
+        // rename. Either way this caller has NOT claimed the stage and must not
+        // act on it.
+        return { outcome: 'already-confirmed', stage: readResolved(root, token) ?? stage };
+    }
+    writeStageFile(resolvedFile, decided.stage);
+    return decided;
+}
+
+/** Decline a pending stage. Same claim discipline as `claimConfirmation`. */
+export function declineConfirmation(
+    root: string,
+    token: string,
+    now: number,
+): { declined: boolean; stage: StagedAction | null } {
+    if (!isSafeToken(token)) {
+        return { declined: false, stage: null };
+    }
+    const pendingFile = path.join(pendingDir(root), `${token}.json`);
+    const stage = readStageFile(pendingFile);
+    if (stage === null) {
+        return { declined: false, stage: readResolved(root, token) };
+    }
+    const decided = declineStage(stage, token, now);
+    if (!decided.declined) {
+        return { declined: false, stage };
+    }
+    const resolvedFile = path.join(resolvedDir(root), `${token}.json`);
+    fs.mkdirSync(resolvedDir(root), { recursive: true });
+    try {
+        fs.renameSync(pendingFile, resolvedFile);
+    } catch {
+        return { declined: false, stage: readResolved(root, token) ?? stage };
+    }
+    writeStageFile(resolvedFile, decided.stage);
+    return { declined: true, stage: decided.stage };
+}
+
+/**
+ * Move expired stages out of `pending/` so the enumeration stays a list of
+ * live decisions. Housekeeping only — `stageStatus` already derives expiry, so
+ * skipping the sweep changes what is *listed*, never what may execute.
+ */
+export function pruneExpired(root: string, now: number): number {
+    let names: string[];
+    try {
+        names = fs.readdirSync(pendingDir(root));
+    } catch {
+        return 0;
+    }
+    let moved = 0;
+    for (const name of names.sort()) {
+        if (!name.endsWith('.json')) {
+            continue;
+        }
+        // Move the file that was ENUMERATED, never a path rebuilt from the
+        // record's `token` field. The two disagree whenever a filename and its
+        // token do — a record written by anything but `putPending` — and the
+        // rebuilt path then hits ENOENT, gets swallowed by the catch below, and
+        // the stage sits in `pending/` forever while `moved` under-reports it.
+        const from = path.join(pendingDir(root), name);
+        const stage = readStageFile(from);
+        if (stage === null || stageStatus(stage, now) !== 'expired') {
+            continue;
+        }
+        const to = path.join(resolvedDir(root), name);
+        fs.mkdirSync(resolvedDir(root), { recursive: true });
+        try {
+            fs.renameSync(from, to);
+        } catch {
+            continue;
+        }
+        moved += 1;
+    }
+    return moved;
+}

package/src/config/agent-settings.template.yml

@@ -1207,9 +1207,17 @@ hooks:
   # language    — detector B: the user-visible prose is not in the pinned
   #               language, with code, quotes, paths and identifiers already
   #               excluded (19 measured).
+  # verification — detector C: the turn changed a file and then ran nothing that
+  #               could have checked it — no test, type-check, lint or build call
+  #               follows the LAST edit. Ordering is the point: a run before the
+  #               final edit did not exercise it, which is the freshness clause
+  #               verify-before-complete states. Reads the turn's tool calls, not
+  #               the prose. Deliberately narrow on what counts as verification —
+  #               a missed detection costs one unguarded turn, a false refusal
+  #               teaches you to switch the gate off.
   #
-  # Both detectors default ON *within* the master switch, so opting in needs
-  # one line, and either can be silenced without editing the hook manifest.
+  # All three detectors default ON *within* the master switch, so opting in needs
+  # one line, and any one can be silenced without editing the hook manifest.
   # A refused turn continues in the same turn and is never refused twice —
   # re-entrancy is `stop_hook_active` plus a marker keyed on the last user
   # message, never on the reply.
@@ -1217,6 +1225,7 @@ hooks:
     enabled: false
     promissory: true
     language: true
+    verification: true
 
   # PreToolUse RTK-wrap nudge (token-saving Phase 3). Default-OFF. When enabled
   # AND `rtk` is on PATH (a live probe — not a self-reported flag), warns (exit

package/src/config/quorum-attendance-budget.json

@@ -1,11 +1,11 @@
 {
-    "_comment": "Pre-registered council ATTENDANCE metrics (road-to-inbox-harvest-2026-08-b Phase 1.4). Registered here rather than in roadmap prose because a roadmap is archived when it closes and a metric outlives it — the sibling budget files (hook-token-budget.json, recycle-threshold-budget.json) already carry the owner / review_by / honest-gap discipline this reuses. The instrument is the quorum_result line appendQuorumEvent writes to agents/runtime/council/events.log (schema v2); nothing here is measured yet, and no threshold is committed before data exists.",
+    "_comment": "Pre-registered council ATTENDANCE metrics (road-to-inbox-harvest-2026-08-b Phase 1.4). Registered here rather than in roadmap prose because a roadmap is archived when it closes and a metric outlives it — the sibling budget files (hook-token-budget.json, recycle-threshold-budget.json) already carry the owner / review_by / honest-gap discipline this reuses. The instrument is the quorum_result line appendQuorumEvent writes to agents/runtime/council/events.log (schema v4 since the ADR-224 shadow floor added gate_class + floor_would_hold at v3 and min_present at v4; v2 lines carry none of the three and v3 lines carry no min_present, so a rate over them must exclude rather than assume them); nothing here is measured yet, and no threshold is committed before data exists.",
     "schema_version": 1,
     "registered_at": "2026-08-10",
     "owner": "maintainer",
     "review_by": "2026-11-10",
     "unit": "quorum_result event lines in agents/runtime/council/events.log",
-    "privacy": "a quorum_result line carries {phase, command, dispatch, verdict, threshold, configured_total, total, present, solo, absent[{member, reason}]} — counts, closed vocabularies, and member ids only. The type has no field able to hold free-form content, so the CLI's own `detail` string (provider error text, which can embed paths and prompt fragments) is dropped at the boundary rather than scrubbed.",
+    "privacy": "a quorum_result line carries {phase, command, dispatch, verdict, threshold, configured_total, total, present, solo, gate_class, min_present, floor_would_hold, absent[{member, reason}]} — counts, closed vocabularies, booleans, and member ids only. The type has no field able to hold free-form content, so the CLI's own `detail` string (provider error text, which can embed paths and prompt fragments) is dropped at the boundary rather than scrubbed. The two v3 additions are booleans and the v4 addition is a small integer read from config, none of which can widen that surface.",
     "phase_split": "A pass emits `pre_run` (build_members — who could be constructed) and, on the `run` path, `post_run` (_postRunQuorum — who actually returned a usable response). They disagree whenever a member constructs and then fails mid-flight, so a rate computed over both double-counts. A `pre_run` line is NOT evidence a pass ran: `command: estimate` is a spend-free preview, and a `run` / `debate` line is written before the `--confirm` gate (which defaults to false and returns before any provider call) and before the necessity and size-fit gates. A `post_run` line is the only line that proves providers were called — which is why every rate below is post_run-scoped, and why `command` exists at all.",
     "attendance_rate": {
         "definition": "of the members that entered the pass, how many answered: present / total per post_run pass. Bounded by 1 by construction (evaluateQuorum clamps present into [0, total]).",
@@ -21,7 +21,14 @@
     "solo_conclusion_rate": {
         "definition": "share of post_run passes with `solo: true` — written by the isSoloConcluded predicate in quorum.ts, never re-derived from the numbers here, so one change to the rule cannot leave this definition stale. ceil(n/2) makes 1-of-2 a legitimate conclusion; this measures how often that legitimacy is used, not whether it should be. THREE cases carry solo: true and they are not the same finding — a degraded multi-member council (configured_total > 1), a council configured with one member (configured_total = 1, dispatch = full), and a deliberate --single dispatch (dispatch = single). Split on dispatch and configured_total before reading the rate.",
         "instrument": "quorum_result lines, phase=post_run, command=run, field solo, split by dispatch + configured_total",
-        "threshold": "none committed before data. The quorum-solo-floor blocker pre-registers the three outcomes this rate decides between — a third CLI member, a gate-scoped min_present: 2, or a published null under 5 % — and that choice is made against real data, never ahead of it. It is decided on the degraded case only; a --single pass is the operator asking for one voice, not the council failing to assemble."
+        "threshold": "DECIDED 2026-08-11 against real data — see ADR-224 (docs/decisions/ADR-224-gate-scoped-solo-attendance-floor.md). The quorum-solo-floor blocker pre-registered three outcomes — a third CLI member, a gate-scoped min_present: 2, or a published null under 5 %. Read at 2026-08-11T09:30Z with the definition above: 1 of 8 post_run/command=run passes carried a degraded solo conclusion = 12.5 %, so the under-5 % null did not fire and the gate-scoped floor was chosen (council 2/2). It was decided on the degraded case only; a --single pass is the operator asking for one voice, not the council failing to assemble. Still no numeric threshold is committed here, deliberately: at n=8 the 95 % interval around 1/8 spans roughly 0.3 %-53 %, so the rate established urgency and not certainty, and ADR-224's review trigger reopens the null at n=40. What this metric measures does NOT change; once the floor lands, how often it FIRES is a second and different question needing its own instrument."
+    },
+    "shadow_floor_fire_rate": {
+        "definition": "share of post_run passes where a min_present floor WOULD have held the pass, had one been enforced: `floor_would_hold: true` over post_run/command=run lines. Written by the wouldSoloFloorHold predicate in quorum.ts, never re-derived from present/threshold here, for the same reason solo_conclusion_rate defers to isSoloConcluded — one definition, so a change to the rule cannot leave this file stale. This is the instrument solo_conclusion_rate's threshold note said the FIRING question would need; it answers 'how often would the floor hold a gate', which is NOT the question solo_conclusion_rate answers ('how often did a pass conclude on one voice'). The two are NOT the same rate and diverge in both directions. solo: true / floor_would_hold: false — a council configured with one member (the ceiling clamps to 1, deliberately). solo: false / floor_would_hold: true — any pass concluding on 2+ voices under a configured quorum_min_present above 2. They also AGREE on the case that matters most: a construction-degraded roster (2 configured, 1 constructed, 1 answered) is solo: true and floor_would_hold: true, because the floor is judged against max(total, configured_total) — judging it against total alone made this pass, the very one ADR-224 was decided on, structurally unable to fire.",
+        "instrument": "quorum_result lines, phase=post_run, command=run, field floor_would_hold, split by dispatch + configured_total AND BY min_present (schema v4+)",
+        "threshold": "none committed before data — and deliberately none at the review date either unless a gate-class caller exists by then. A fire-rate over passes that gate nothing measures a counterfactual, not a risk; it is registered now so ADR-224's review trigger (b) has an accumulating series rather than a series that starts on the day someone remembers to add one.",
+        "split_by_min_present_or_the_rate_is_uninterpretable": "The floor this rate counts against is `quorum_min_present`, which lives in the USER-GLOBAL .ai-council.yml (ADR-104) — per developer machine, gitignored, invisible in this repository. Schema v3 consumed that value and did not record it, so two operators produced byte-identical lines while measuring different counterfactuals, and a pooled rate over them was a mean of incomparable things. Schema v4 records it as `min_present`; group on it before reading, and treat v3 lines as a separate stratum whose floor is UNKNOWN rather than assuming the default. The sharpest case: `quorum_min_present: 1` is valid config and, per the predicate's own test, can never hold anything — so it drives this rate to a permanent zero. Without min_present on the line that zero is indistinguishable from 'the floor genuinely never would have fired', which is precisely the reading ADR-224's review trigger (b) would act on. No threshold was loosened by adding this field; nothing was gated on it before.",
+        "nothing_is_enforced": "No value of this metric holds, delays or fails a council pass. wouldSoloFloorHold is a counterfactual with no caller branching on it, and quorum_min_present configures only what the counterfactual is computed against. A reader must not cite this rate as evidence that the floor protected anything — it has never protected anything."
     },
     "absent_reason_distribution": {
         "definition": "count per reason over absent[] entries — no_binary / no_auth / timeout / quota (AbsentReason) plus the two runtime fallbacks the CLI writes directly, `unavailable` (transport resolved to nothing) and `binary_missing` (a CLI client refused to construct). Distinguishes a council degraded by configuration from one degraded by provider behaviour, which have opposite fixes.",
@@ -34,6 +41,7 @@
         "`lens` and `invocation` are empty on every pre_run line — neither is known at member-construction time — so any per-lens breakdown is post_run-only.",
         "`command: debate` carries the pre_run half ONLY. There is no _postRunQuorum on the debate path, and defining `usable response` for a multi-round debate is a separate question this registration does not answer. So debate contributes to absent_reason_distribution and to nothing else: attendance_rate and solo_conclusion_rate cover the `run` path, and a reader must not read them as covering every metered pass.",
         "A pre_run line proves construction happened, never that a pass followed — the `--confirm` gate (default false), the necessity gate and the size-fit gate all abort afterwards and nothing on the line records it. Any count over pre_run lines is an upper bound; pair it with a post_run line before treating it as a pass.",
+        "`gate_class` is `false` on EVERY line written so far and will stay false until a caller declares otherwise — nothing in the tree branches on QuorumStatus to hold a gate, so there is no gate-class caller to mark. shadow_floor_fire_rate is therefore a rate over ALL post_run passes, not over gate-class ones, and the gate-class-scoped rate ADR-224 actually cares about is UNMEASURED, not zero. Do not read a `false` majority as evidence that gate-class passes are rare; it is evidence that the concept has no consumer yet.",
         "The CLI emit wiring itself has no test. The two modules are covered directly, but nothing exercises build_members / cmd_run / cmd_debate end-to-end against a captured log — and `_emitQuorumEvent` forwards no AppendEventOptions, so there is no target to capture into. Two defects in this file's first version (a `dispatch` written from the flag rather than the outcome, and a rate mixing config entries with clients) were found by review rather than by a test, which is what that gap costs."
     ]
 }

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -57,8 +57,13 @@ export function templateEnvelope(): Record<string, unknown> {
         acceptance_criteria: ['<what done means, one line each>'],
         remaining: ['<open work, one line each>'],
         not_carried_forward: ['<what the successor must re-derive from source>'],
-        decisions: ['<decision — one-line rationale>'],
+        decisions: ['<decision — one-line rationale> [reversible]'],
         constraints: ['<binding constraint>'],
+        // Ships EMPTY, unlike the prose lists above: the entries are path refs,
+        // and a `<placeholder>` left in by a hurried writer would be a fake path
+        // rather than obvious filler. An empty list is also the honest default —
+        // nothing off limits is the common case.
+        do_not_touch: [],
         open_worker_envelopes: [],
         artifact_paths: ['<path to a deliverable / note / evidence file>'],
         assumptions: [],

package/src/scripts/_dispatch.bash

@@ -194,7 +194,10 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
   code-graph                 Deterministic code-graph engine (ADR-124, Class A).
                              Usage: code-graph build|validate|detect|query|explain|affected|path [options]
   sessions:list              List live agent sessions on this repository (shared
-                             session register). Flags: --json
+                             session register) PLUS the unmerged branches checked
+                             out in other worktrees — the axis that needs no
+                             claim. Flags: --json, --branches (adds the branch
+                             axis to the JSON; the human form always shows it)
   sessions:claim             Claim a roadmap for this session so other sessions skip
                              it; --release clears the claim
   session:recycle            Validate + write the main-session recycle envelope (--verify validates only)
@@ -209,7 +212,8 @@ Tier 2 — maintenance / internal (hooks, MCP, memory, telemetry):
                              first. Flags: --all (include maintainer/external),
                              --json, --reply (reply-close form: the one blocking
                              decision in full, the rest as a count; prints
-                             nothing when none are yours)
+                             nothing when none are yours), --pending (staged
+                             requires_confirmation actions awaiting you)
   capabilities:index         Regenerate CAPABILITIES.yaml — the package coverage index
                              (capability area → coverage → backing skills/commands → gaps).
                              Pass --check to fail if stale (for CI). Reads src/ (package repo).

package/src/scripts/_lib/env_kill_switch.ts

@@ -0,0 +1,37 @@
+/**
+ * One definition of "is this env kill-switch on?".
+ *
+ * WHY THIS EXISTS: the predicate was written out twice, byte-for-byte —
+ * `ai_council/events_log.ts` and `ai_team/review_gate.ts` each carried a
+ * private `_kill_switch_active()` with the identical body AND the identical
+ * env var (`AGENT_CONFIG_NO_EVENTS_LOG`). `diff` over the two blocks was empty
+ * and no shared helper existed. Two copies of a boolean coercion is two places
+ * for the next accepted spelling to land in only one.
+ *
+ * The subtle half is why `'false'` is listed at all: `process.env` values are
+ * strings, so the obvious `Boolean(process.env.X)` reads the *string* `'false'`
+ * as true and silently arms a switch the operator explicitly disarmed. The
+ * off-set is therefore explicit — unset, `''`, `'0'`, `'false'`, `'False'` —
+ * and everything else is on, so a typo fails toward the safer direction (the
+ * switch suppresses a log; a spurious suppression is visible, a spurious write
+ * is not).
+ *
+ * SCOPE, stated because the source over-claimed it. `grep -rn "=== 'false'"
+ * src/scripts/` returns 10 hits; only the two migrated here share one
+ * predicate. The others are deliberately different and stay put:
+ * `orchestration_record.ts` is a CLI-flag coercion whose invalid-string
+ * fall-through is documented, `turn_end_gate_hook.ts` additionally accepts
+ * `yes`/`on`, and `validate_frontmatter.ts` is a YAML scalar parser. Folding
+ * those in would change three behaviours to remove three lines.
+ */
+
+/** The env values that mean "off". Everything else — including a typo — is on. */
+const _OFF_VALUES: ReadonlySet<string> = new Set(['', '0', 'false', 'False']);
+
+/**
+ * True when the named environment variable is set to anything outside the
+ * off-set. Unset reads as off.
+ */
+export function isEnvKillSwitchActive(name: string): boolean {
+    return !_OFF_VALUES.has(process.env[name] ?? '');
+}

package/src/scripts/_lib/security_lint.ts

@@ -408,10 +408,13 @@ export function* iter_corpus(
  * Exit 1 iff at least one finding `is_fail` (HIGH + full weight). WARN-level
  * (weighted-down or < HIGH) findings print but never fail the build.
  */
-export function report(findings: readonly Finding[], opts: { check_label: string }): number {
+export function report(
+    findings: readonly Finding[],
+    opts: { check_label: string; scanned_roots?: readonly string[] },
+): number {
     const check_label = opts.check_label;
     if (findings.length === 0) {
-        process.stdout.write(`✅  ${check_label}: clean (${_corpus_note()}).\n`);
+        process.stdout.write(`✅  ${check_label}: clean (${_corpus_note(opts.scanned_roots)}).\n`);
         return 0;
     }
 
@@ -459,8 +462,19 @@ function _pyG(n: number): string {
     return s;
 }
 
-function _corpus_note(): string {
-    return 'scanned ' + DEFAULT_SCAN_ROOTS.join(', ');
+// The clean-path line names the corpus the caller ACTUALLY walked, not the
+// shared default. Two of five callers diverge from `DEFAULT_SCAN_ROOTS`
+// (`lint_skill_frontmatter_safety` replaces the set outright,
+// `lint_mcp_config_security` appends `src/templates`), so a hardcoded note made
+// this gate report a scope in both directions at once: it claimed `src/rules`
+// and `dist/agent-src`, which it never reads, and omitted `src/subagents`,
+// which is the one root holding the artefact its over-broad-grant check exists
+// for. A reader verifying that root by running the gate read the opposite of
+// the truth. Same contract as `_lib/scan_scope.reportScanned` — the emitted
+// scope is the scope that was walked.
+function _corpus_note(scanned_roots?: readonly string[]): string {
+    const roots = scanned_roots && scanned_roots.length > 0 ? scanned_roots : DEFAULT_SCAN_ROOTS;
+    return 'scanned ' + roots.join(', ');
 }
 
 // ---------------------------------------------------------------------

package/src/scripts/_lib/self_repair.ts

@@ -538,6 +538,66 @@ export function fingerprint(defect_class: DefectClass, evidence: string): string
 }
 
 /** Fold a finding into an existing record, or open a new one. */
+// ── creation rate cap ──────────────────────────────────────────────
+//
+// `upsertFinding` folds on fingerprint, so a *recurring* defect increments one
+// record and adds no file. What nothing bounded is **creation**: the fingerprint
+// is `defect_class + evidence`, and evidence is a quoted span from the turn, so a
+// defect whose span varies per turn mints a fresh record every time. The only
+// cap in the module pair was `MAX_EVIDENCE`, which bounds a span's *length* and
+// says nothing about how many records may exist.
+//
+// The cap is per `source` because the two intake paths have different plausible
+// rates and a runaway on one must not consume the other's headroom: a
+// `user-reported` record needs the user to complain, and `self-detected` fires at
+// most once per turn per detector. `NEW_RECORDS_PER_SOURCE_PER_WINDOW` sits above
+// any plausible day (three detector classes, a few evidence variants each) and
+// far below a runaway (one per turn over a long session).
+export const NEW_RECORDS_PER_SOURCE_PER_WINDOW = 20;
+export const CREATION_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * How many records of `source` were CREATED inside the window ending at `now`.
+ * Counts `first_seen`, never `last_seen` — an old record still being folded into
+ * is not creation and must not consume the budget.
+ */
+export function recentCreations(
+    existing: readonly DefectRecord[],
+    source: DefectSource,
+    now: string,
+): number {
+    const end = Date.parse(now);
+    if (Number.isNaN(end)) {
+        return 0;
+    }
+    return existing.filter((r) => {
+        if (r.source !== source) {
+            return false;
+        }
+        const t = Date.parse(r.first_seen);
+        // An unparseable stamp is counted: a malformed record is exactly what a
+        // runaway writer produces, and failing open there would uncap the store.
+        return Number.isNaN(t) || (end - t < CREATION_WINDOW_MS && end - t >= 0);
+    }).length;
+}
+
+/**
+ * Whether opening a NEW record for `finding` is over budget. A fingerprint that
+ * already exists is a fold, never a creation, so it is never capped — the cap
+ * must not silence a defect the store is already tracking.
+ */
+export function creationCapReached(
+    existing: readonly DefectRecord[],
+    finding: DefectFinding,
+    now: string,
+): boolean {
+    const fp = fingerprint(finding.defect_class, finding.evidence);
+    if (existing.some((r) => r.fingerprint === fp)) {
+        return false;
+    }
+    return recentCreations(existing, finding.source, now) >= NEW_RECORDS_PER_SOURCE_PER_WINDOW;
+}
+
 export function mergeRecord(
     existing: DefectRecord | null,
     finding: DefectFinding,

package/src/scripts/_lib/self_repair_store.ts

@@ -11,7 +11,14 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
-import { type DefectFinding, type DefectRecord, fingerprint, mergeRecord } from './self_repair.js';
+import {
+    creationCapReached,
+    type DefectFinding,
+    type DefectRecord,
+    type DefectSource,
+    fingerprint,
+    mergeRecord,
+} from './self_repair.js';
 
 export const STORE_REL = path.join('agents', 'runtime', 'self-repair');
 
@@ -61,7 +68,10 @@ export function listRecords(root: string): DefectRecord[] {
     }
     const out: DefectRecord[] = [];
     for (const n of names.sort()) {
-        if (!n.endsWith('.json')) {
+        // The overflow counter shares the directory and the extension but is not
+        // a record. `isRecord` would reject it anyway; naming it here keeps the
+        // exclusion intentional rather than incidental.
+        if (!n.endsWith('.json') || n === OVERFLOW_FILE) {
             continue;
         }
         const rec = readRecord(root, n.slice(0, -'.json'.length));
@@ -77,13 +87,63 @@ export function openRecords(root: string): DefectRecord[] {
     return listRecords(root).filter((r) => r.status === 'open');
 }
 
+/**
+ * Per-source counters for findings the creation cap refused. ONE file for the
+ * whole store, so the overflow record is bounded by construction — it is the
+ * counter a runaway writer increments instead of the file it would otherwise
+ * mint. Deliberately NOT a `DefectRecord`: an overflow is not a defect and must
+ * not need a `DefectClass`, an issue-form dropdown entry, or an egress route.
+ */
+export const OVERFLOW_FILE = '_overflow.json';
+
+export type OverflowCounts = Partial<Record<DefectSource, { dropped: number; last_seen: string }>>;
+
+function overflowPath(root: string): string {
+    return path.join(storeDir(root), OVERFLOW_FILE);
+}
+
+export function readOverflow(root: string): OverflowCounts {
+    try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(overflowPath(root), 'utf-8'));
+        return typeof parsed === 'object' && parsed !== null ? (parsed as OverflowCounts) : {};
+    } catch {
+        return {};
+    }
+}
+
+function bumpOverflow(root: string, source: DefectSource, now: string): void {
+    const counts = readOverflow(root);
+    const prev = counts[source]?.dropped ?? 0;
+    counts[source] = { dropped: prev + 1, last_seen: now };
+    const dir = storeDir(root);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(overflowPath(root), `${JSON.stringify(counts, null, 2)}\n`, 'utf-8');
+}
+
 /**
  * Fold a finding into the store: increments the existing record when the
- * fingerprint matches, otherwise opens a new one. Returns the stored record.
+ * fingerprint matches, otherwise opens a new one. Returns the stored record, or
+ * `null` when the per-source creation cap refused to open a new one.
+ *
+ * A refusal is COUNTED, never silent — `readOverflow` carries the per-source
+ * drop tally, so "the cap fired" is a readable fact rather than a defect that
+ * disappeared. A cap that quietly discarded reports would break this loop's own
+ * Iron Law (a defect is queued, never shrugged off) in the name of bounding it.
  */
-export function upsertFinding(root: string, finding: DefectFinding, now: string): DefectRecord {
+export function upsertFinding(
+    root: string,
+    finding: DefectFinding,
+    now: string,
+): DefectRecord | null {
     const fp = fingerprint(finding.defect_class, finding.evidence);
-    const merged = mergeRecord(readRecord(root, fp), finding, now);
+    const existing = readRecord(root, fp);
+    // The fold path never consults the cap: a fingerprint already in the store
+    // adds no file, so capping it would silence a tracked defect for no bound.
+    if (existing === null && creationCapReached(listRecords(root), finding, now)) {
+        bumpOverflow(root, finding.source, now);
+        return null;
+    }
+    const merged = mergeRecord(existing, finding, now);
     writeRecord(root, merged);
     return merged;
 }