@event4u/agent-config 14.7.0 → 14.9.0

package/src/scripts/_lib/billing_grant.ts

@@ -0,0 +1,165 @@
+/**
+ * billing_grant — the run-scoped answer to "plan quota is gone, may I spend?".
+ *
+ * The problem this closes is a billing-class switch nobody chose at the moment
+ * it happened. A council seat on a vendor CLI under a subscription login is
+ * unmetered; its api twin is metered USD. Until `api_on_quota: 'ask'` existed
+ * that switch was decided once, at configuration time, and then applied
+ * silently mid-round — see `transport_resolver.ts` § `FallbackPolicy`.
+ *
+ * A grant is the human's yes, and it is scoped to ONE run for two reasons.
+ *
+ * The first is that a run is the unit the question is answerable in. "May I
+ * spend money finishing this?" needs the remaining scope in view; a standing
+ * setting has no scope to show. The second is the failure a wall-clock TTL
+ * produces: the git-guard grant expired after 30 minutes, so a drain outliving
+ * its own grant re-asked mid-run — which is the interruption this whole
+ * mechanism exists to remove. So the TTL here is the RUN, and `revoke` is
+ * called from the path that already clears run-continuation state. A wall
+ * clock appears only as a backstop for a run that died without cleaning up.
+ *
+ * Transport is an env var (`AC_BILLING_GRANT`) plus a file under
+ * `agents/runtime/`. Both are needed and neither is redundant: the env var is
+ * what a spawned subagent can read without knowing the repo root, and the file
+ * is what makes the grant survive a subprocess boundary in the other
+ * direction and gives `revoke` something to delete. `hardenedSpawnEnv()`
+ * passes the `AC_` family through — verified, and pinned by a test in
+ * `tests/scripts/_lib/spawn_env.test.ts`, because a future deny-family entry
+ * would otherwise break the chain silently.
+ *
+ * PII-exclusion-by-construction: a grant record holds a run id, an ISO
+ * timestamp, and nothing else. There is no field capable of carrying a prompt,
+ * a path, or a credential, so there is no scrubbing pass here that could fail.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** Env var the main session sets and every spawned worker reads. */
+export const BILLING_GRANT_ENV = 'AC_BILLING_GRANT';
+
+/** Directory, relative to the repo root, holding one file per live grant. */
+export const BILLING_GRANT_DIR_REL = path.join('agents', 'runtime', 'billing-grants');
+
+/**
+ * Backstop only. A run that exits through its normal path calls `revoke`; this
+ * bounds the damage of one that does not, and is deliberately far longer than
+ * any run so it can never be the thing that ends a live grant.
+ */
+export const BILLING_GRANT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+export interface BillingGrant {
+    readonly run_id: string;
+    readonly issued_at: string;
+}
+
+/** Filesystem-safe filename for a run id. Mirrors `run_checkpoint.checkpointFile`. */
+export function grantFile(repoRoot: string, runId: string): string {
+    return path.join(
+        repoRoot,
+        BILLING_GRANT_DIR_REL,
+        `${runId.replace(/[^A-Za-z0-9_-]/g, '_')}.json`,
+    );
+}
+
+/**
+ * Record the human's yes for `runId` and return the env pair to hand to
+ * subagents. Idempotent: re-issuing keeps the original `issued_at`, so a
+ * second yes inside one run cannot extend the backstop window.
+ */
+export function issueBillingGrant(
+    repoRoot: string,
+    runId: string,
+    now: () => Date = () => new Date(),
+): BillingGrant {
+    const file = grantFile(repoRoot, runId);
+    const existing = _read(file);
+    if (existing !== null && existing.run_id === runId) return existing;
+    const grant: BillingGrant = { run_id: runId, issued_at: now().toISOString() };
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(grant, null, 2)}\n`, 'utf8');
+    return grant;
+}
+
+/**
+ * Is a grant in force for `runId`?
+ *
+ * Both halves must agree, and the AND is the security property rather than
+ * belt-and-braces: an env var alone is settable by anything in the process
+ * tree, and a file alone would let a grant from a previous run authorise this
+ * one. Requiring the env var to NAME the run whose file exists is what makes
+ * a different run's grant unusable.
+ */
+export function isBillingGrantActive(
+    repoRoot: string,
+    runId: string,
+    env: NodeJS.ProcessEnv = process.env,
+    now: () => Date = () => new Date(),
+): boolean {
+    if ((env[BILLING_GRANT_ENV] ?? '').trim() !== runId) return false;
+    const grant = _read(grantFile(repoRoot, runId));
+    if (grant === null || grant.run_id !== runId) return false;
+    const age = now().getTime() - Date.parse(grant.issued_at);
+    return Number.isFinite(age) && age >= 0 && age <= BILLING_GRANT_MAX_AGE_MS;
+}
+
+/**
+ * Ambient check for a caller that does not carry a run id — the council CLI
+ * reading config, for instance. The env var names the run, so the file it
+ * names is the one that must exist; there is no "any grant will do" branch.
+ */
+export function hasBillingGrant(
+    repoRoot: string,
+    env: NodeJS.ProcessEnv = process.env,
+    now: () => Date = () => new Date(),
+): boolean {
+    const runId = (env[BILLING_GRANT_ENV] ?? '').trim();
+    if (runId === '') return false;
+    return isBillingGrantActive(repoRoot, runId, env, now);
+}
+
+/**
+ * Remove the grant for `runId`. Safe to call when none exists.
+ *
+ * Called from `run_continuation_hook.clearRunState` — the one place a run is
+ * declared over, and therefore the grant's real TTL. `clearRunState` is
+ * exported for that reason: reaching it through the concern chain would mean
+ * standing up the whole dispatch harness to assert one unlink.
+ */
+export function revokeBillingGrant(repoRoot: string, runId: string): void {
+    try {
+        fs.unlinkSync(grantFile(repoRoot, runId));
+    } catch {
+        // Already gone is the success case, not an error worth surfacing.
+    }
+}
+
+function _read(file: string): BillingGrant | null {
+    try {
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8')) as unknown;
+        if (raw === null || typeof raw !== 'object') return null;
+        const o = raw as Record<string, unknown>;
+        if (typeof o.run_id !== 'string' || typeof o.issued_at !== 'string') return null;
+        return { run_id: o.run_id, issued_at: o.issued_at };
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * The id of the run a grant would be scoped to.
+ *
+ * Resolution order, first non-empty wins: `AC_BILLING_GRANT` (a grant already
+ * in force names its own run), then `AC_RUN_ID` (what an orchestrating session
+ * sets), then the host's session id. Returns `null` when none resolves — and
+ * `null` is rendered as a literal placeholder rather than a fabricated id,
+ * because a grant command carrying an invented run id would be a command that
+ * silently authorises nothing.
+ */
+export function currentRunId(env: NodeJS.ProcessEnv = process.env): string | null {
+    for (const key of [BILLING_GRANT_ENV, 'AC_RUN_ID', 'CLAUDE_CODE_SESSION_ID']) {
+        const v = (env[key] ?? '').trim();
+        if (v !== '') return v;
+    }
+    return null;
+}

package/src/scripts/_lib/billing_grant_cli.ts

@@ -0,0 +1,123 @@
+/**
+ * The `council:{grant-billing,revoke-billing}` verbs, and the round's closing
+ * Human Gate line.
+ *
+ * Lives here rather than in `council_cli.ts` for the reason that file's other
+ * extractions give: it is ~2,500 lines over the source ceiling and the
+ * documented remedy is extraction, not a raised baseline
+ * (`gate-violation-baselines.json` § check_source_size_budget).
+ *
+ * IO is injected rather than imported so this module stays testable without a
+ * process: `council_cli.ts` owns the repo root and the stdout/stderr pair.
+ */
+
+import {
+    BILLING_GRANT_ENV,
+    currentRunId,
+    hasBillingGrant,
+    issueBillingGrant,
+    revokeBillingGrant,
+} from './billing_grant.js';
+import { renderBillingGateLines } from './council_fallback_posture.js';
+import { writeQuotaParked } from './quota_parked.js';
+
+export interface BillingCliDeps {
+    readonly repoRoot: string;
+    readonly stdout: (s: string) => void;
+    readonly stderr: (s: string) => void;
+}
+
+/** The verbs this module owns, spread into `council_cli`'s subcommand list. */
+export const BILLING_SUBCOMMANDS = ['grant-billing', 'revoke-billing'] as const;
+
+/**
+ * The arg spec for a billing verb, or `null` when `cmd` is not one.
+ *
+ * Consulted from `council_cli`'s `default:` arm rather than added as two more
+ * `case` labels there: the verb list already lives in this module, and a
+ * second copy of it in a switch is a copy that can drift.
+ */
+export function billingArgSpec(
+    cmd: string,
+): { positionals: string[]; opts: never[]; requiredOpts: never[] } | null {
+    return (BILLING_SUBCOMMANDS as readonly string[]).includes(cmd)
+        ? { positionals: ['run_id'], opts: [], requiredOpts: [] }
+        : null;
+}
+
+/**
+ * Dispatch a billing verb, or return `null` when `cmd` is not one.
+ *
+ * A `null` return rather than a thrown or a boolean out-param: the caller's
+ * dispatch chain is a run of `if (cmd === x) return f()`, and this has to slot
+ * into it as two lines without teaching the caller which verbs exist.
+ */
+export function handleBillingCommand(
+    cmd: string,
+    runId: unknown,
+    d: BillingCliDeps,
+): number | null {
+    if (cmd === 'grant-billing') return grantBilling(String(runId ?? ''), d);
+    if (cmd === 'revoke-billing') return revokeBilling(String(runId ?? ''), d);
+    return null;
+}
+
+/**
+ * Record the human's yes for one run.
+ *
+ * Writes the grant file and then prints the export line, because the file
+ * alone is not the grant: a grant is in force only when `AC_BILLING_GRANT`
+ * NAMES the run whose file exists (see `isBillingGrantActive`), and that AND
+ * is what stops a previous run's grant from authorising this one. Printing the
+ * export rather than setting it is not a limitation being apologised for — a
+ * process cannot set its parent's environment, and a command claiming to would
+ * be lying.
+ */
+export function grantBilling(runId: string, d: BillingCliDeps): number {
+    if (runId.trim() === '') {
+        d.stderr('❌  council:grant-billing: a run id is required.\n');
+        return 2;
+    }
+    const g = issueBillingGrant(d.repoRoot, runId.trim());
+    d.stdout(`✅  billing grant recorded for run ${g.run_id} (issued ${g.issued_at})\n`);
+    d.stdout(`    export ${BILLING_GRANT_ENV}=${g.run_id}\n`);
+    const live = hasBillingGrant(d.repoRoot) ? 'yes' : 'not until the export above is set';
+    d.stdout(`    in force: ${live}\n`);
+    return 0;
+}
+
+/**
+ * End the grant. Exit 0 on an absent one: "there is no grant for this run" is
+ * the state the caller asked for, and failing on it would make the run-end
+ * cleanup path noisy on exactly the runs that never needed a grant.
+ */
+export function revokeBilling(runId: string, d: BillingCliDeps): number {
+    if (runId.trim() === '') {
+        d.stderr('❌  council:revoke-billing: a run id is required.\n');
+        return 2;
+    }
+    revokeBillingGrant(d.repoRoot, runId.trim());
+    d.stdout(`✅  billing grant revoked for run ${runId.trim()}\n`);
+    return 0;
+}
+
+/**
+ * Print the round's closing question when `api_on_quota: 'ask'` parked seats.
+ * Silent when nothing parked, so the caller needs no branch.
+ */
+export function printBillingGate(parked: readonly string[], d: BillingCliDeps): void {
+    const runId = currentRunId();
+    // Record before rendering. A parked round is the one moment this repository
+    // KNOWS plan quota is exhausted without needing a host signal, and the
+    // printed line reaches whoever is watching the terminal — which for an
+    // autonomous drain is nobody. The marker is what survives to the next
+    // `run:supervise` report. Skipped when no run id resolves: a marker with a
+    // fabricated key is worse than none, because nothing would ever match it.
+    if (parked.length > 0 && runId !== null) writeQuotaParked(d.repoRoot, runId, parked);
+    for (const line of renderBillingGateLines(parked, {
+        runId: runId ?? '<run-id>',
+        estimatedUsd: null,
+    })) {
+        d.stdout(`${line}\n`);
+    }
+}

package/src/scripts/_lib/council_fallback_posture.ts

@@ -13,6 +13,8 @@
  * `council:status` is the one command that must stay free of side effects.
  */
 
+import type { ApiOnQuota } from '../ai_council/transport_resolver.js';
+
 export type FallbackPosture = 'api' | 'none' | 'n/a';
 
 export interface PostureInput {
@@ -59,7 +61,7 @@ export function fallbackPostureFor(input: PostureInput): FallbackPosture {
  */
 export function renderPostureLines(
     postures: ReadonlyArray<readonly [string, FallbackPosture]>,
-    apiOnQuota: boolean,
+    apiOnQuota: ApiOnQuota,
 ): string[] {
     const live = postures.filter(([, p]) => p !== 'n/a');
     if (live.length === 0) return [];
@@ -72,10 +74,55 @@ export function renderPostureLines(
     );
     // Separate from the per-seat lines: not a per-seat property but the one
     // billing-class decision, governing every seat at once.
-    lines.push(
-        `  fallback quota   api_on_quota: ${apiOnQuota ? 'on' : 'off'}` +
-            ` — an exhausted cli quota ${apiOnQuota ? 'MAY' : 'may not'}` +
-            ' retry on the metered rung',
-    );
+    // Three postures, rendered by name rather than by truthiness. `'ask'` is
+    // truthy, so an `apiOnQuota ? 'on' : 'off'` reading would print `on` for
+    // it — telling the operator that quota fall-through happens silently when
+    // the whole point of the value is that it does not.
+    const word = apiOnQuota === 'ask' ? 'ask' : apiOnQuota ? 'on' : 'off';
+    const consequence =
+        apiOnQuota === 'ask'
+            ? ' — an exhausted cli quota PARKS the seat and the round closes with a question,' +
+              ' unless a run-scoped billing grant is already in force'
+            : apiOnQuota
+              ? ' — an exhausted cli quota MAY retry on the metered rung'
+              : ' — an exhausted cli quota may not retry on the metered rung';
+    lines.push(`  fallback quota   api_on_quota: ${word}${consequence}`);
     return lines;
 }
+
+/**
+ * The Human Gate a round closes with when `api_on_quota: 'ask'` parked seats.
+ *
+ * A correction to this roadmap step, recorded rather than quietly absorbed:
+ * the step said to render this "through the existing `renderPostureLines`
+ * path". That path is `council:status`, which runs before any round and can
+ * therefore never know which seats a round parked. So this is a sibling in the
+ * same module rather than a branch inside that function — same place, same
+ * vocabulary, different moment.
+ *
+ * Returns `[]` when nothing parked, so a caller may render unconditionally
+ * without a heading over an empty list.
+ */
+export function renderBillingGateLines(
+    parked: readonly string[],
+    opts: { readonly runId: string; readonly estimatedUsd: number | null },
+): string[] {
+    if (parked.length === 0) return [];
+    const seats = [...new Set(parked)].sort();
+    const cost =
+        opts.estimatedUsd === null
+            ? 'unknown — no priced estimate for the retry'
+            : `~$${opts.estimatedUsd.toFixed(2)}`;
+    return [
+        '',
+        'HUMAN GATE — plan quota exhausted, metered spend not authorised',
+        `  parked seats     ${seats.join(', ')}`,
+        `  retry cost       ${cost}`,
+        // The command is printed rather than described because the whole
+        // mechanism fails if answering it takes a lookup: an operator who has
+        // to go find the syntax is an operator who says yes tomorrow, on a run
+        // that has already ended.
+        `  to authorise     agent-config council:grant-billing ${opts.runId}`,
+        '  to decline       do nothing — the grant is never implied by silence',
+    ];
+}

package/src/scripts/_lib/council_fallback_wiring.ts

@@ -13,13 +13,18 @@
  */
 
 import type { CliFallbackOptions, FallbackEvent } from '../ai_council/mid_flight_fallback.js';
+import type { ApiOnQuota } from '../ai_council/transport_resolver.js';
+import { parseApiOnQuota } from '../ai_council/transport_resolver.js';
+import { hasBillingGrant } from './billing_grant.js';
 import { CouncilConfigError } from '../ai_council/config.js';
 
 type Dict = Record<string, unknown>;
 
 /** Anything the twin factory needs that `council_cli.ts` owns. */
 export interface FallbackWiringDeps {
-    readonly apiOnQuota: boolean;
+    readonly apiOnQuota: ApiOnQuota;
+    /** Run-scoped billing grant in force. Read only under `'ask'`. */
+    readonly billingGrant?: boolean;
     /** Does this provider have an api constructor at all? */
     readonly hasApiRung: (provider: string) => boolean;
     /** This provider's `members.<name>` block, or `{}`. */
@@ -38,6 +43,7 @@ export interface FallbackWiringDeps {
     ) => unknown;
     /** The events-log appender. */
     readonly emit: (record: Dict) => unknown;
+
 }
 
 /**
@@ -77,8 +83,15 @@ function isRefusal(exc: unknown): boolean {
 }
 
 export function buildFallbackOptions(deps: FallbackWiringDeps): CliFallbackOptions {
+    // Owned here, not passed in. `establishTwin` emits `awaiting_grant` and
+    // this is the nearest thing to it that outlives one call, so a caller
+    // wanting the closing question reads `options.parked` instead of
+    // threading a collector through the factory.
+    const parked: string[] = [];
     return {
         api_on_quota: deps.apiOnQuota,
+        billing_grant: deps.billingGrant === true,
+        parked,
         // The orchestrator is a pure library and holds no sink; this is it.
         // One line per establishing escalation, so attendance analysis can
         // tell a seat SAVED by the fallback from one that was natively api.
@@ -93,6 +106,7 @@ export function buildFallbackOptions(deps: FallbackWiringDeps): CliFallbackOptio
             // during a fallback kills the whole round, and the mechanism whose
             // entire purpose is to SAVE a seat becomes the thing that loses
             // every seat. Losing the log line is the strictly smaller failure.
+            if (e.outcome === 'awaiting_grant') parked.push(e.provider);
             try {
                 deps.emit({
                     action: 'transport_fallback',
@@ -124,3 +138,49 @@ export function buildFallbackOptions(deps: FallbackWiringDeps): CliFallbackOptio
         },
     };
 }
+
+/** Everything `wireCouncilFallback` needs that `council_cli.ts` owns. */
+export interface CallSiteDeps {
+    readonly repoRoot: string;
+    readonly isDict: (v: unknown) => v is Dict;
+    readonly membersCfg: Dict;
+    readonly overrides: Dict;
+    readonly hasApiRung: (provider: string) => boolean;
+    readonly constructApi: FallbackWiringDeps['constructApi'];
+    readonly emit: (record: Dict) => unknown;
+}
+
+/**
+ * Build the fallback factory from the raw `ai_council` block and hand it back
+ * through the out-param `build_members` threads.
+ *
+ * Extracted from `council_cli.ts` when the billing-grant read joined the two
+ * config reads already here: that file is ~2,500 lines over the source ceiling
+ * and the documented remedy is extraction rather than a raised baseline
+ * (`gate-violation-baselines.json` § check_source_size_budget). Keeping the
+ * derivation next to the factory it feeds is the better shape anyway — the
+ * caller had to know that an absent `fallback` block means `false` and that
+ * the grant is read per-run, neither of which is the caller's business.
+ */
+export function wireCouncilFallback(
+    out: { options: CliFallbackOptions | null } | null,
+    ai: Dict,
+    d: CallSiteDeps,
+): void {
+    // The null check lives here, not at the call site: `fallback_out` is an
+    // optional out-param and "the caller passed no ref" is this function's
+    // business, not a branch every caller has to remember.
+    if (out === null) return;
+    // Absent/malformed block means `false`, never a throw. Why quota
+    // fall-through is opt-in: `FallbackPolicy.apiOnQuota`.
+    const cfg = d.isDict(ai['fallback']) ? ai['fallback'] : {};
+    out.options = buildFallbackOptions({
+        apiOnQuota: parseApiOnQuota(cfg['api_on_quota']),
+        billingGrant: hasBillingGrant(d.repoRoot),
+        hasApiRung: d.hasApiRung,
+        memberConfig: (p) => ((d.membersCfg[p] as Dict) || {}) as Dict,
+        modelOverride: (p) => (d.overrides[p] as string | undefined) ?? null,
+        constructApi: d.constructApi,
+        emit: d.emit,
+    });
+}

package/src/scripts/_lib/envelope_grounding.ts

@@ -160,7 +160,17 @@ export function readLastVerify(root: string, session_id: string | null): string
         const command = typeof rec['command'] === 'string' ? rec['command'] : null;
         if (!command) return null;
         const at = typeof rec['at'] === 'string' ? rec['at'] : 'unknown time';
-        return `${command} @ ${at} (no exit status is recorded anywhere)`.slice(0, MAX_FIELD_CHARS);
+        // Collapse whitespace BEFORE slicing. A recorded command is whatever
+        // the operator ran, and a heredoc (`git commit -F - <<'MSG'`) records a
+        // multi-line string — so slicing to 200 chars kept the newlines, and
+        // `validateRecycleEnvelope`'s `isShortLine` rejects any value containing
+        // one. The result was that `session:recycle` refused its OWN
+        // machine-collected field: composing a valid envelope was impossible
+        // whenever the previous verification command spanned more than one line,
+        // and the error named `last_verify` without hinting that the composer
+        // had not supplied it. Reproduced 2026-08-21 on a 512-char heredoc.
+        const flat = `${command} @ ${at} (no exit status is recorded anywhere)`.replace(/\s+/g, ' ').trim();
+        return flat.slice(0, MAX_FIELD_CHARS);
     } catch {
         return null;
     }

package/src/scripts/_lib/host_capability.ts

@@ -120,11 +120,65 @@ export function normalizeHostManifest(input: unknown): HostCapabilityManifest {
  * host identity a hook/dispatch envelope carries).
  *
  * Each row is partial: an omitted field stays at the `SAFE_DEFAULT` `false`
- * when the row is applied. Claude Code is the one host this roadmap's
- * transcript evidence measured spawning and running subagents concurrently
- * (`Agent` tool dispatch, parallel tool-use blocks); polling and a separate
- * quota pool were never observed, so they stay `false` — add a field only
- * once it is itself observed, never by inference.
+ * when the row is applied — and an ABSENT field is the record for "never
+ * looked", which is a different state from a field written as `false`
+ * deliberately. Add a field only once it is itself observed, never by
+ * inference.
+ *
+ * ## Rows are written under the observation protocol
+ *
+ * `contexts/execution/host-capability-manifest.md` § Observation protocol states
+ * the per-field criterion and the four-part citation (host · host version ·
+ * transcript or artefact reference · date). A row without all four is not
+ * admissible, and no row may be filled from a host's documentation.
+ *
+ * ## REACHABILITY, 2026-08-22 — one of eight, and the other seven are recorded
+ *
+ * `hook_manifest.yaml` declares eight platform keys. Reachable means a real
+ * session can be started on the host, not that it is installable in principle.
+ *
+ *   - `claude`   — REACHABLE. Row below, re-cited under the protocol.
+ *   - `augment`  — not reachable from this session: a different editor host, no
+ *                  session available to the running agent.
+ *   - `cowork`   — not reachable from this session, same reason.
+ *   - `cursor`   — not reachable from this session, same reason.
+ *   - `cline`    — not reachable from this session, same reason.
+ *   - `windsurf` — not reachable from this session, same reason.
+ *   - `gemini`   — not reachable from this session, same reason.
+ *   - `copilot`  — not reachable from this session, same reason; additionally
+ *                  `fallback_only` in the manifest.
+ *
+ * The seven have **no row**, so every field resolves to the safe default and
+ * `describeHostCapabilities` reports its source as `default`. That is the
+ * "never looked" state, and it is the honest one — a recorded silence rather
+ * than a table with gaps that reads as a table of negatives.
+ *
+ * ## The `claude` row, RE-CITED rather than grandfathered
+ *
+ * The row predated the protocol. Both its fields are now carried on transcript
+ * evidence, so it is brought up to the new shape rather than marked
+ * grandfathered — which was the other permitted disposition and would have left
+ * it looking like it passed a protocol it never ran.
+ *
+ * `subagent_spawn: true` — OBSERVED. claude (Claude Code, Opus 5 1M session,
+ *   2026-08-22). `agents/runtime/state/subagent-ledger/2026-08.jsonl`: **445**
+ *   `subagent_start` records, and **420** stops carrying a measured
+ *   `duration_ms` — i.e. 420 child legs whose start and stop pair, which is the
+ *   criterion (a measurable child duration, not an inferred one).
+ *
+ * `parallel_spawn: true` — OBSERVED. Same host, session and artefact.
+ *   **6,168** of 6,388 stop records carry `concurrent_open >= 2`, with a
+ *   maximum of **30** concurrently open children. Overlapping intervals at one
+ *   instant, which is the criterion — not two children in sequence.
+ *
+ * `status_polling`, `separate_quota_pool`, `worker_respawn` — **absent from the
+ *   row, and that is deliberate.** The ledger does not instrument any of the
+ *   three, so this is "never looked", NOT "observed absent". They stay at the
+ *   safe default and report `default` provenance. Writing any of them as an
+ *   explicit `false` would claim a measurement nobody took.
+ *
+ * `agent_teams` — out of scope for a row by construction; see its own field
+ *   doc comment and the protocol section.
  */
 const HOST_CAPABILITY_REGISTRY: Readonly<Record<string, Partial<HostCapabilityManifest>>> = {
     claude: { subagent_spawn: true, parallel_spawn: true },

package/src/scripts/_lib/layer_overlap_notice.ts

@@ -28,12 +28,21 @@ import * as path from 'node:path';
 /**
  * Artefact types both host layers can carry.
  *
- * All four, matching `check_single_delivery` (R2 finding): this notice read three
+ * All five, matching `check_single_delivery` (R2 finding): this notice read three
  * where the gate reads four, so a subagent duplicated across layers was invisible
  * on one surface and reported on the other — two surfaces disagreeing about the
  * same question is worse than one surface being silent.
+ *
+ * `personas` was added 2026-08-21. Both lists had read four types while the
+ * installer's `_CLAUDE_SKILL_BUNDLE` (`install.ts:1916-1921`) ships
+ * rules · skills · commands · **personas** — so the one family this repository
+ * actually delivered from both layers was the one neither surface looked at
+ * (29 shared names on a freshly regenerated tree). The two lists stay
+ * hand-written and independent of the installer's on purpose: deriving the
+ * verifier's scope from the producer would make the check inherit the producer's
+ * omissions, which is the defect being closed here.
  */
-const TYPES = ['rules', 'skills', 'commands', 'agents'] as const;
+const TYPES = ['rules', 'skills', 'commands', 'personas', 'user-types', 'agents'] as const;
 
 /**
  * Count shared entry names per artefact type between the two layers.

package/src/scripts/_lib/prune_empty_dirs.ts

@@ -0,0 +1,80 @@
+/**
+ * Remove empty directories under a root, deepest first.
+ *
+ * ## Why this exists as a shared helper
+ *
+ * A generator that stops writing into a tree leaves the tree's DIRECTORIES
+ * behind. Measured 2026-08-21 while extending the ADR-236 partition to the
+ * colon-form commands: after the generator was gated, `.claude/commands/`
+ * held **0 `.md` files and 40 empty cluster directories** — and
+ * `check_single_delivery` counts directory NAMES, so it still reported 40
+ * overlapping commands against a layer that delivered none. A partition that
+ * stops the writes and leaves the shape is invisible to the gate that is
+ * supposed to confirm it.
+ *
+ * `condense.ts` already carried this loop inline for the skills tree. It is
+ * lifted here rather than copied because the second caller is what turns an
+ * inline block into a shape two producers must agree on — and because
+ * `condense.ts` sits above `check_source_size_budget`'s ceiling, where a
+ * shrink-only ratchet refuses even a small addition.
+ *
+ * Best-effort by construction: a race or a permission error on one directory is
+ * swallowed, matching the inline original. Pruning is cleanup, never a gate.
+ *
+ * ## Symlinks: MEASURED, because a neutral review split on it
+ *
+ * One seat called an unguarded recursion a merge blocker (a directory symlink
+ * pointing at an ancestor would loop forever); the other called the finding
+ * false, on the grounds that `Dirent.isDirectory()` does not follow the target.
+ * A vote cannot settle that, so it was probed — `readdirSync(dir, {withFileTypes:
+ * true})` over a real symlink-to-directory on darwin, Node 26:
+ *
+ *     link  isDirectory=false  isSymbolicLink=true
+ *     real  isDirectory=true   isSymbolicLink=false
+ *
+ * `Dirent` carries `lstat` semantics, so the walk below cannot descend into a
+ * symlink at all and no loop is reachable — and no inode set is needed. The
+ * second seat was right. Recorded rather than fixed, so the next reader does not
+ * re-raise it: a defensive `!e.isSymbolicLink()` here would be dead code
+ * asserting something the type already guarantees.
+ *
+ * The same property is why this is safe on a tree of symlinks: `.claude/commands`
+ * holds symlinks into `src/domains/**`, and pruning must not follow one out of
+ * the tree it was pointed at.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/** @returns the number of directories removed. */
+export function pruneEmptyDirs(root: string): number {
+    let removed = 0;
+    const walk = (dir: string): void => {
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.isDirectory()) walk(path.join(dir, e.name));
+        }
+        try {
+            if (fs.readdirSync(dir).length === 0) {
+                fs.rmdirSync(dir);
+                removed += 1;
+            }
+        } catch {
+            /* race or permission — cleanup is best-effort, mirrors the inline original */
+        }
+    };
+    let top: fs.Dirent[];
+    try {
+        top = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+        return 0;
+    }
+    for (const e of top) {
+        if (e.isDirectory()) walk(path.join(root, e.name));
+    }
+    return removed;
+}