@event4u/agent-config 9.34.0 → 9.36.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

@@ -355,6 +355,24 @@ project:
   # Branch prefix for improvement PRs
   improvement_pr_branch_prefix: "improve/agent-"
 
+  # Who this project is built for. Read by the demand gate
+  # (docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md
+  # § 8-pre), whose L0-L4 ladder measures MARKET demand and is therefore
+  # meaningless where no market is intended.
+  #   self     -> a tool its maintainer builds for themselves. The demand gate
+  #               is inert; work is classified L-self (build), never deferred
+  #               for lack of a user population that is not wanted.
+  #   internal -> a team / company internal tool. Only "what breaks without
+  #               it?" survives; the requester is known.
+  #   client   -> built for a named client. The client is the requester, not a
+  #               market segment.
+  #   public   -> a product with an intended market. Full three-question gate
+  #               and the full ladder.
+  # Default `public` = the behaviour every install had before this key existed.
+  # Absent resolves to `public` for the same reason: this package has no
+  # defaults layer, so absent means nobody said.
+  audience: public
+
 # --- GitHub integration ---
 github:
   # API method for replying to PR review comments
@@ -1207,9 +1225,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 +1243,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
@@ -1239,6 +1266,20 @@ hooks:
   design_slop:
     enabled: false
 
+  # PreToolUse UI-route nudge (road-to-frontend-skill-application Phase 4).
+  # Default-OFF. When enabled, a Write/Edit to a UI surface with no design
+  # consultation latched this session WARNS (exit 2, never blocks) naming the
+  # route: run existing-ui-audit, then the fe-design loop. A read or search
+  # touching fe-design / existing-ui-audit / design-review / design-intelligence
+  # latches consultation and silences it for the rest of the session, so the
+  # agent that did the right thing is never nagged. Anti-loop: at most 2 nudges
+  # per session. It does NOT read the two UI rules: the UI-surface decision
+  # comes from _lib/ui_surface.ts, so this runs parallel to them rather than
+  # consuming their triggers. Host-limited (pre_tool_use fires on ~2-3 hosts) —
+  # elsewhere the obligation stays model-carried, as the two UI rules declare.
+  ui_route_nudge:
+    enabled: false
+
   # PreToolUse code-graph nudge (ADR-124 Phase 4). Default-OFF. When enabled
   # AND a native code-graph engine has built a cache (or the repo ships a
   # graph.json / SCIP index), WARNS once per session (exit 2, never blocks) as

package/src/config/gate-coverage.yml

@@ -168,6 +168,18 @@ gates:
     corpus: "src/rules/*.md frontmatters (111 at baseline)"
     status: enforced
 
+  - id: lint_rule_skill_pack_reach
+    argv: ["--quiet"]
+    min_scanned: 90
+    corpus: "src/rules/*.md frontmatters joined against src/skills packs and the pack registry (116 rules at baseline)"
+    status: enforced
+    note: >
+      Advisory on findings, enforced on COVERAGE: the gate exits 0 while its
+      unreachable-route set is non-empty (12 at introduction), so only this
+      floor can catch it going blind. A collapse below 90 would mean it stopped
+      reading src/rules, which is exactly the shape that would make "0 findings"
+      read as clean.
+
   - id: check_condensation
     argv: []
     min_scanned: 380

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]).",
@@ -23,6 +23,13 @@
         "instrument": "quorum_result lines, phase=post_run, command=run, field solo, split by dispatch + configured_total",
         "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.",
         "instrument": "quorum_result lines, absent[].reason, split by phase (a pre_run absence is configuration; a post_run absence is mid-flight). Excluding `command: estimate` is NOT sufficient: `run` and `debate` also reach construction and return at the `--confirm` gate, which defaults to false. The reliable filter is a pre_run line whose pass produced a matching post_run line; a pre_run line with no post_run partner reached construction and stopped there, whatever its command says.",
@@ -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_doctor.ts

@@ -3591,10 +3591,42 @@ function main(argv: string[] | null = null): number {
 
 // --- CLI entry ---
 
+/**
+ * Defined by `build:cli-delegate` only — see `cmd_session_recycle.ts` for why a
+ * single "am I inside a bundle" flag cannot answer "may I run".
+ */
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
 function _isCliEntry(): boolean {
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    // Inlined into the installer / hook / MCP bundle: never auto-run. This
+    // file previously carried no such guard while its comment described the
+    // pairing, so the four siblings documented one mechanism and implemented
+    // two.
+    if (bundled && !cliDelegate) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (cliDelegate) {
+        // `--splitting` moves this module's body into a shared chunk, so the URL
+        // comparison below weighs the CHUNK against `argv[1]` and never matches.
+        // `agent-config doctor` shipped producing zero bytes and exit 0 for
+        // exactly that reason — a diagnostic reporting success while saying
+        // nothing. The invoked file name is the reliable signal inside this
+        // bundle; the delegate smoke test keeps the literal honest.
+        if (path.basename(process.argv[1], '.js') === 'cmd_doctor') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;

package/src/scripts/_cli/cmd_migrate.ts

@@ -932,14 +932,37 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 // build's `--define`) disables the auto-run there; under tsx/node it is
 // undefined, so `typeof` short-circuits and the standalone CLI guard fires
 // normally.
+// The sentinel above is true in EVERY esbuild target, `build:cli-delegate`
+// included — and there this file is the entry, so refusing on it refused to run
+// the bundle built to run it: `dist/cli-delegate/cmd_migrate.js` produced zero
+// bytes and exit 0, and `agent-config migrate` reported success while doing
+// nothing. `__AGENT_CONFIG_CLI_DELEGATE__` is defined by that one build only, so
+// the pair distinguishes "inlined into the installer" (never run) from "this
+// bundle's own target" (run, subject to the entry check below).
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
-const _bundled =
-    typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+const _inForeignBundle =
+    typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' &&
+    __AGENT_CONFIG_BUNDLE__ &&
+    !(typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__);
 const _HERE = fileURLToPath(import.meta.url);
 function _isCliEntry(): boolean {
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__) {
+        // `--splitting` moves this module's body into a shared chunk, so the URL
+        // comparison below weighs the CHUNK against `argv[1]` and never matches —
+        // `agent-config migrate` shipped producing zero bytes and exit 0. The
+        // invoked file name is the reliable signal inside this bundle.
+        if (path.basename(process.argv[1], '.js') === 'cmd_migrate') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;
@@ -958,7 +981,7 @@ function _isCliEntry(): boolean {
     }
 }
 
-if (!_bundled && (_isCliEntry() || process.argv[1] === _HERE)) {
+if (!_inForeignBundle && (_isCliEntry() || process.argv[1] === _HERE)) {
     try {
         process.exitCode = main(process.argv.slice(2));
     } catch (exc) {

package/src/scripts/_cli/cmd_refresh.ts

@@ -449,10 +449,39 @@ export function main(argv: string[] | null = null, options: MainOptions = {}): n
 
 // --- CLI entry ---
 
+/**
+ * Defined by `build:cli-delegate` only — see `cmd_session_recycle.ts` for why the
+ * URL comparison below cannot decide this inside that bundle.
+ */
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
 function _isCliEntry(): boolean {
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    // Inlined into the installer / hook / MCP bundle: never auto-run. This
+    // file previously carried no such guard while its comment described the
+    // pairing, so the four siblings documented one mechanism and implemented
+    // two.
+    if (bundled && !cliDelegate) {
+        return false;
+    }
     if (process.argv[1] === undefined) {
         return false;
     }
+    if (cliDelegate) {
+        // Found by running every delegate bundle, not by reading: `--splitting`
+        // had moved this body into a shared chunk too, so `agent-config refresh`
+        // was a silent exit 0 like doctor, migrate and session:recycle.
+        if (path.basename(process.argv[1], '.js') === 'cmd_refresh') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === argvUrl) {
         return true;

package/src/scripts/_cli/cmd_session_recycle.ts

@@ -252,11 +252,49 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     return result.code;
 }
 
-// Bundle-safety: never auto-run when inlined into an esbuild bundle.
+/**
+ * Bundle-safety: never auto-run when inlined into SOMEONE ELSE'S bundle.
+ *
+ * `__AGENT_CONFIG_BUNDLE__` alone cannot express that. All four esbuild targets
+ * define it, `build:cli-delegate` included — and that bundle's entry points ARE
+ * these files, so a guard refusing on the flag refuses to run the very bundle
+ * built to run it. That shipped: `dist/cli-delegate/cmd_session_recycle.js`
+ * produced zero bytes and exit 0 on every installed copy, so
+ * `agent-config session:recycle` reported success while writing no envelope.
+ * `cmd_doctor` and `cmd_migrate` carried the same guard and were dead the same
+ * way.
+ *
+ * `__AGENT_CONFIG_CLI_DELEGATE__` is defined by that one build only, so the pair
+ * says what a single flag could not: inlined elsewhere (install / hook / MCP
+ * bundle) → never run; this bundle's own target → run, and let the `argv[1]`
+ * comparison below decide whether THIS module is the entry or a shared chunk
+ * pulled in beside it.
+ */
 declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
 function _isCliEntry(): boolean {
-    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) return false;
+    const bundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+    const cliDelegate =
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' && __AGENT_CONFIG_CLI_DELEGATE__;
+    if (bundled && !cliDelegate) return false;
     if (process.argv[1] === undefined) return false;
+    if (cliDelegate) {
+        // `--splitting` turns the entry file into a re-export shim and moves this
+        // module's body into a shared chunk, where `import.meta.url` is the
+        // CHUNK's url and can never equal `argv[1]`. The comparison below then
+        // silently never fires — which is why two sibling commands shipped dead
+        // while others worked by accident, purely by where esbuild happened to
+        // place their code. Inside this bundle the invoked file name is the only
+        // reliable signal; the smoke test over every delegate bundle is what
+        // keeps this literal honest if the file is ever renamed.
+        if (path.basename(process.argv[1], '.js') === 'cmd_session_recycle') {
+            return true;
+        }
+        // A miss falls THROUGH to the realpath comparison below rather than
+        // returning false: a symlinked or renamed invocation is exactly the
+        // case that fallback exists for, and swallowing it here would rebuild
+        // the silent no-op this change removes.
+    }
     if (import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) return true;
     try {
         return (

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