@event4u/agent-config 9.34.0 → 9.35.0

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

@@ -0,0 +1,252 @@
+/**
+ * Staged confirmation — the pure half of exactly-once confirmed execution.
+ *
+ * `src/rules/non-destructive-by-default.md` already carries the whole policy:
+ * an irreversible action is confirmed on THIS turn, ask and action are strictly
+ * sequential ("Never act while asking"), and the approval names the exact
+ * object. What the tree had no mechanism for is the *sequencing itself* — a
+ * staged action, a confirmation that matches it, and the guarantee that a
+ * second approval of the same stage does not fire the action twice.
+ *
+ * Two properties carry that guarantee, and they are split across two files on
+ * purpose:
+ *
+ *   - **Identity is derived, not invented.** {@link stageAction} hashes the
+ *     action, the exact object, and a caller-supplied nonce into a token, so a
+ *     confirmation can only match the stage it was issued for. Restaging the
+ *     same object under a fresh nonce yields a different token — an approval
+ *     never carries over to "the next one like it".
+ *   - **The claim is atomic, and it lives in the store.** Nothing here can be
+ *     exactly-once by itself: two processes reading the same `pending` record
+ *     and both deciding "execute" is a check-then-act race no pure function can
+ *     close. This module decides WHAT the outcome should be;
+ *     `staged_confirmation_store.ts` makes the transition atomic with a
+ *     directory rename, which either succeeds once or fails.
+ *
+ * Nothing binds on this yet, deliberately. `pre_tool_use` exists on 3 of 8
+ * platform rows (`hook_manifest.yaml`), so a guard that claimed to enforce
+ * confirmation would be prose on the other five while reading like a control —
+ * the failure `src/rules/ui-audit-gate.md` names about its own scope. The
+ * decision is deferred behind blocker `confirmation-degraded-host-semantics`;
+ * until it lands, callers opt in explicitly.
+ *
+ * Pure: no filesystem, no clock, no randomness. `now` and `nonce` are
+ * parameters so a test pins a whole lifecycle without faking globals.
+ */
+
+import { createHash } from 'node:crypto';
+
+/**
+ * Lifecycle of one staged action. `expired` is not a stored state — it is
+ * derived from the clock by {@link stageStatus}, so a stale pending record
+ * cannot read as awaiting-approval merely because nobody swept it.
+ */
+export type StageState = 'pending' | 'confirmed' | 'declined';
+
+/** What {@link confirmOnce} concluded. Only `execute` authorizes the action. */
+export type ConfirmOutcome =
+    | 'execute'
+    | 'already-confirmed'
+    | 'expired'
+    | 'declined'
+    | 'token-mismatch';
+
+/**
+ * The `on_block_fallback` vocabulary from
+ * `work_engine/scoring/decision_engine.ts` (`stop` / `warn`, default `stop`),
+ * reused rather than re-invented: this module extends that gate's ask path, so
+ * a second fallback vocabulary would be a second contract to keep in sync.
+ */
+export type NonInteractiveFallback = 'stop' | 'warn';
+
+/**
+ * Default staging window. A confirmation the user never gives must not sit in
+ * the store as an approval waiting to be collected: an abandoned stage that
+ * stays valid indefinitely is a pre-approved irreversible action, which is the
+ * opposite of what the policy asks for. Fifteen minutes is long enough for a
+ * human to read the surface and answer, short enough that a turn which ended
+ * hours ago cannot authorize anything.
+ */
+export const STAGE_TTL_MS = 15 * 60 * 1000;
+
+export interface StagedAction {
+    /** Confirmation token — derived, never guessable from the object alone. */
+    readonly token: string;
+    /** What would fire: a command name, a skill slug, a concern id. */
+    readonly action: string;
+    /**
+     * The exact object the approval names — a path, a URL, a recipient, an
+     * amount. The policy's "names the exact object" clause lives here, which is
+     * why it is required rather than optional: a stage with no object is a
+     * category confirmation, and the rule forbids exactly that.
+     */
+    readonly object: string;
+    /** Who staged it — the surface a `gates --pending` reader needs. */
+    readonly source: string;
+    readonly staged_at: string;
+    readonly expires_at: string;
+    readonly state: StageState;
+    /** Set on the transition out of `pending`, never rewritten afterwards. */
+    readonly resolved_at?: string;
+}
+
+/** ISO-8601 seconds, matching the runtime records already in the tree. */
+function iso(ms: number): string {
+    return new Date(ms).toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+/**
+ * Derive the confirmation token.
+ *
+ * The nonce is a parameter and not read from a clock or an RNG here, so the
+ * derivation is reproducible in a test. It is also what makes two stages of the
+ * same object distinct: without it, approving a delete of `x` once would
+ * produce a token that matches every future delete of `x`.
+ *
+ * The separator is NUL, written as an escape sequence and never as a raw byte.
+ * NUL is the right separator — it cannot occur in an action, a path or a nonce,
+ * so no two different triples concatenate to the same string. A RAW NUL in a
+ * text source would make git, grep and file(1) treat the whole file as binary
+ * and skip it silently, which `lint_hidden_unicode` blocks on; the escape keeps
+ * the domain separation and leaves the file readable by every tool.
+ */
+export function deriveToken(action: string, object: string, nonce: string): string {
+    return createHash('sha256')
+        .update(`${action}\u0000${object}\u0000${nonce}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+
+/** Stage an action. Returns the record; it is the caller's job to persist it. */
+export function stageAction(args: {
+    action: string;
+    object: string;
+    source: string;
+    nonce: string;
+    now: number;
+    ttlMs?: number;
+}): StagedAction {
+    const ttl = args.ttlMs ?? STAGE_TTL_MS;
+    return {
+        token: deriveToken(args.action, args.object, args.nonce),
+        action: args.action,
+        object: args.object,
+        source: args.source,
+        staged_at: iso(args.now),
+        expires_at: iso(args.now + ttl),
+        state: 'pending',
+    };
+}
+
+/**
+ * Effective status at `now` — `expired` is derived, not stored.
+ *
+ * A pending record past its `expires_at` reads as `expired` even though no
+ * sweep has run, so the guarantee does not depend on a pruner having been
+ * called. Prune is housekeeping; this is the decision.
+ */
+export function stageStatus(stage: StagedAction, now: number): StageState | 'expired' {
+    if (stage.state === 'pending' && Date.parse(stage.expires_at) <= now) {
+        return 'expired';
+    }
+    return stage.state;
+}
+
+export function isExpired(stage: StagedAction, now: number): boolean {
+    return stageStatus(stage, now) === 'expired';
+}
+
+/**
+ * Decide what a confirmation attempt means. `execute` — and only `execute` —
+ * authorizes the action, and it is returned at most once per stage because the
+ * caller writes the returned record back before acting.
+ *
+ * The token is compared in full: a confirmation for a different stage is
+ * `token-mismatch` rather than a silent no-op, because a mismatch is a real
+ * signal (a stale surface, a copied token) and swallowing it would hide it.
+ */
+export function confirmOnce(
+    stage: StagedAction,
+    token: string,
+    now: number,
+): { outcome: ConfirmOutcome; stage: StagedAction } {
+    if (token !== stage.token) {
+        return { outcome: 'token-mismatch', stage };
+    }
+    const status = stageStatus(stage, now);
+    if (status === 'confirmed') {
+        return { outcome: 'already-confirmed', stage };
+    }
+    if (status === 'declined') {
+        return { outcome: 'declined', stage };
+    }
+    if (status === 'expired') {
+        return { outcome: 'expired', stage };
+    }
+    return {
+        outcome: 'execute',
+        stage: { ...stage, state: 'confirmed', resolved_at: iso(now) },
+    };
+}
+
+/** Decline a stage. Idempotent for the same reason `confirmOnce` is. */
+export function declineStage(
+    stage: StagedAction,
+    token: string,
+    now: number,
+): { declined: boolean; stage: StagedAction } {
+    if (token !== stage.token || stageStatus(stage, now) !== 'pending') {
+        return { declined: false, stage };
+    }
+    return { declined: true, stage: { ...stage, state: 'declined', resolved_at: iso(now) } };
+}
+
+/**
+ * What a non-interactive context does with a stage.
+ *
+ * Both fallbacks REFUSE — `decision_engine`'s `stop` and `warn` differ in how
+ * loudly they surface, never in whether the gated thing proceeds, and a staged
+ * irreversible action is the last place to invent an auto-approve. Naming the
+ * `warn` case explicitly is the point: a reader looking for the permissive
+ * branch finds it absent on purpose.
+ */
+export function nonInteractiveDecision(fallback: NonInteractiveFallback): {
+    execute: false;
+    surface: 'halt' | 'warn';
+} {
+    return { execute: false, surface: fallback === 'warn' ? 'warn' : 'halt' };
+}
+
+/**
+ * The confirmation surface, in the numbered-options shape
+ * `src/rules/user-interaction.md` requires. Returned as lines rather than
+ * written, so the same text serves a hook halt, a CLI pane, and a chat reply.
+ *
+ * `confirmWith` / `declineWith` are the caller's channel and are NOT defaulted
+ * to a command name. Which channel confirms a staged action is precisely what
+ * blocker `confirmation-degraded-host-semantics` has not decided — a
+ * `pre_tool_use` reply on three hosts, prose on the other five — and printing
+ * an invocation that does not exist yet would put a false instruction into a
+ * shipped surface. Until a binding caller supplies one, the surface names the
+ * token and says plainly that no channel is wired.
+ */
+export function confirmationSurface(
+    stage: StagedAction,
+    channel?: { confirmWith?: string; declineWith?: string },
+): string[] {
+    const confirm = channel?.confirmWith;
+    const decline = channel?.declineWith;
+    return [
+        `Confirmation required: ${stage.action}`,
+        `Object: ${stage.object}`,
+        `Staged by: ${stage.source} · token ${stage.token} · expires ${stage.expires_at}`,
+        confirm === undefined
+            ? `1) Confirm — quote token ${stage.token} back to the caller that staged it.`
+            : `1) Confirm — ${confirm}`,
+        decline === undefined
+            ? '2) Decline — say so; the stage is resolved without firing.'
+            : `2) Decline — ${decline}`,
+        '3) Do nothing — the stage expires and the action never fires.',
+        'Pending stages: `agent-config gates --pending`.',
+    ];
+}

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]).",
@@ -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/_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).