@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/_lib/standing_bound_ratchet.ts

@@ -0,0 +1,154 @@
+/**
+ * The standing-payload bounds are shrink-only, checked against the base ref.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * `src/config/preamble-payload-budget.json` says of its grace ceiling: *"It may
+ * never move UP."* `grace_ceiling_history` in the same file records it moving up
+ * twice — 138,212 → 138,273 on 2026-09-02 and 138,273 → 138,490 on 2026-09-08 —
+ * each with a careful prose justification. ADR-264 resolved that contradiction
+ * against the practice: the sentence stands, the two raises are violations caused
+ * by contradictory wording, and standing-rule growth needs a compensating
+ * reduction elsewhere.
+ *
+ * That decision then had no enforcement. A sentence in a JSON string is not a
+ * gate, and the file's own history is the evidence: nothing objected either time.
+ * This module is the enforcement — and it is the ONLY thing
+ * `road-to-a-standing-budget-with-headroom` step 1.3 ships, because the 128-token
+ * Iron Law reserve that step designed was refused by an AI council 2/2 on
+ * 2026-09-08. See ADR-265.
+ *
+ * WHAT IT CANNOT DO, STATED PLAINLY
+ * ---------------------------------
+ * The change under review can edit this file. Both council seats named that as
+ * the defect fatal to the reserve — "the checker, its imports, token census,
+ * workflow, and status context are all part of the trusted computing base", so a
+ * protected record read by an unprotected verifier grants nothing. It is fatal to
+ * a mechanism that GRANTS budget and it is not fatal to one that only REFUSES,
+ * which is the whole reason the reserve stayed unshipped and this ratchet did
+ * not: disabling this check requires visibly editing it, and every gate in this
+ * repository already rests on that same review. A ratchet whose only failure mode
+ * is "someone deleted the ratchet" is strictly better than the sentence it
+ * replaces, which had no failure mode because it did nothing.
+ */
+import { spawnSync } from 'node:child_process';
+
+/** Repo-relative path of the budget config the bound lives in. */
+export const BUDGET_CONFIG_PATH = 'src/config/preamble-payload-budget.json';
+
+/** Injection seam: run git, capture output, never throw on a non-zero exit. */
+export type GitRunner = (args: readonly string[], cwd: string) => {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+};
+
+export const realGit: GitRunner = (args, cwd) => {
+    const r = spawnSync('git', [...args], { cwd, encoding: 'utf-8' });
+    return { ok: r.status === 0, stdout: r.stdout ?? '', stderr: r.stderr ?? '' };
+};
+
+export interface BoundsRatchetVerdict {
+    ok: boolean;
+    violations: string[];
+    /** The bound read at the base ref, or `null` when it could not be read. */
+    baseGraceCeiling: number | null;
+    /** The ref compared against, or `null` when none resolved. */
+    baseRef: string | null;
+    /** Why the comparison was skipped, when it was. Printed, never silent. */
+    note: string | null;
+}
+
+function showAtRef(git: GitRunner, repoRoot: string, ref: string, relPath: string): string | null {
+    const r = git(['show', `${ref}:${relPath}`], repoRoot);
+    return r.ok ? r.stdout : null;
+}
+
+/**
+ * Compare the grace ceiling in this tree against the one at the base ref.
+ *
+ * SKIPS rather than fails when the base ref or the base config cannot be read.
+ * That is the opposite of the fail-closed posture the same council demanded for
+ * the reserve, and the asymmetry is deliberate: an unreadable base there would
+ * have GRANTED budget on an infrastructure failure, whereas here it would REFUSE
+ * a change on one. A shallow clone, a first commit and a detached build all
+ * legitimately have no base, and a gate that reds on them gets switched off —
+ * which is how a repository loses the enforcement it just built. The skip is
+ * reported in both the human and JSON output so it cannot pass for a check.
+ */
+export function assertBoundsDidNotRise(opts: {
+    repoRoot: string;
+    baseRef: string | null;
+    git?: GitRunner;
+    /**
+     * The ceiling this run actually compares the payload against.
+     *
+     * The CI step passes `--ceiling <grace_ceiling>`, so the effective bound can
+     * be raised either by editing the config or by passing a bigger number. Both
+     * arrive here as one value, which closes the second path without a second
+     * check.
+     */
+    headGraceCeiling: number;
+}): BoundsRatchetVerdict {
+    const git = opts.git ?? realGit;
+    if (opts.baseRef === null || opts.baseRef.trim() === '') {
+        return {
+            ok: true,
+            violations: [],
+            baseGraceCeiling: null,
+            baseRef: null,
+            note: 'no base ref resolved, so the shrink-only bound was NOT verified in this run',
+        };
+    }
+    const cfg = showAtRef(git, opts.repoRoot, opts.baseRef, BUDGET_CONFIG_PATH);
+    if (cfg === null) {
+        return {
+            ok: true,
+            violations: [],
+            baseGraceCeiling: null,
+            baseRef: opts.baseRef,
+            note: `${BUDGET_CONFIG_PATH} could not be read at ${opts.baseRef}, so the shrink-only bound was NOT verified`,
+        };
+    }
+    let baseGrace: number | null = null;
+    try {
+        const parsed = JSON.parse(cfg) as Record<string, unknown>;
+        const delivery = (parsed['ci_delivery'] ?? {}) as Record<string, unknown>;
+        const n = Number(delivery['grace_ceiling']);
+        baseGrace = Number.isFinite(n) ? n : null;
+    } catch {
+        return {
+            ok: true,
+            violations: [],
+            baseGraceCeiling: null,
+            baseRef: opts.baseRef,
+            note: `${BUDGET_CONFIG_PATH} at ${opts.baseRef} is not parseable, so the shrink-only bound was NOT verified`,
+        };
+    }
+    if (baseGrace === null) {
+        return {
+            ok: true,
+            violations: [],
+            baseGraceCeiling: null,
+            baseRef: opts.baseRef,
+            note: `no ci_delivery.grace_ceiling at ${opts.baseRef}, so there is no earlier bound to ratchet against`,
+        };
+    }
+    if (opts.headGraceCeiling > baseGrace) {
+        return {
+            ok: false,
+            baseGraceCeiling: baseGrace,
+            baseRef: opts.baseRef,
+            note: null,
+            violations: [
+                `the standing-payload grace ceiling rose from ${String(baseGrace)} to ` +
+                    `${String(opts.headGraceCeiling)} against ${opts.baseRef}. ` +
+                    `${BUDGET_CONFIG_PATH} says it may not move upward and ADR-264 decided that ` +
+                    'the sentence stands: standing-rule growth needs a compensating reduction ' +
+                    'elsewhere, not a bigger ceiling. Lower the addition, migrate the prose out of ' +
+                    'the standing rule, or reduce another standing asset by the same amount.',
+            ],
+        };
+    }
+    return { ok: true, violations: [], baseGraceCeiling: baseGrace, baseRef: opts.baseRef, note: null };
+}

package/src/scripts/_lib/subagent_capsule.ts

@@ -143,10 +143,68 @@ export const CAPSULE_SCHEMA_VERSION = 4;
  */
 export const ACCEPTED_CAPSULE_VERSIONS: readonly number[] = [3, 4];
 
-/** The two CHECKPOINT variants sharing this schema. */
-export const CAPSULE_VARIANTS = ['worker', 'main_session'] as const;
+/** The three CHECKPOINT variants sharing this schema. */
+export const CAPSULE_VARIANTS = ['worker', 'main_session', 'continuity_record'] as const;
 export type CapsuleVariant = (typeof CAPSULE_VARIANTS)[number];
 
+/**
+ * `continuity_record` — the DETERMINISTIC main-session variant.
+ *
+ * Why a variant and not a relaxed `main_session`. `main_session` requires
+ * `failed_approaches` and `successful_approaches` with at least one entry each,
+ * and requires the explicit token `none` when nothing failed or worked — the
+ * whole point of those fields being that silence and "nothing was abandoned"
+ * stay distinguishable. A writer that runs without model spend cannot know
+ * either. It could only write `none`, which asserts a judgement nobody made.
+ *
+ * The AI council of 2026-09-07 ruled exactly this: add a variant rather than
+ * stuffing absence markers into `main_session`, because explicit absence
+ * markers "misrepresent unavailable model judgments as values". This constant
+ * set is that ruling in code.
+ *
+ * The fields below are FORBIDDEN on this variant rather than optional, and the
+ * distinction is load-bearing. Optional would leave the door open for a later
+ * writer to fill one with a guess and for a reader to be unable to tell a
+ * derived record from a judged one. Forbidden makes the variant's meaning
+ * checkable: everything a `continuity_record` carries was computed from disk.
+ *
+ * Nothing here is invented — every name is an existing key of this same schema.
+ * The council's constraint was explicit: the required fields "must be derived
+ * from the existing validated envelope contract; this ruling does not authorize
+ * inventing parallel identity or directive fields."
+ *
+ * Version compatibility is unchanged and envelope-wide: a `continuity_record`
+ * declares the same `capsule_version`, and a reader that does not know the
+ * variant refuses it by name (see `validateRecycleEnvelope`) rather than
+ * guessing at its required set.
+ */
+export const CONTINUITY_RECORD_FORBIDDEN_KEYS: ReadonlySet<string> = new Set([
+    'decisions',
+    'constraints',
+    'do_not_touch',
+    'assumptions',
+    'failed_approaches',
+    'successful_approaches',
+    'open_questions',
+    'not_carried_forward',
+    'status_summary',
+    'suggested_skills',
+    'open_worker_envelopes',
+]);
+
+/** Required on a `continuity_record` — each one computable from on-disk state. */
+export const CONTINUITY_RECORD_REQUIRED_KEYS: readonly string[] = [
+    'capsule_version',
+    'variant',
+    'summary',
+    'task',
+    'workspace',
+    'written_at',
+    'acceptance_criteria',
+    'remaining',
+    'predecessor',
+];
+
 /** A single-line token no longer than `max` chars. Rejects any body-shaped value. */
 function isShortLine(value: unknown, max: number): value is string {
     return typeof value === 'string' && value.length > 0 && value.length <= max && !value.includes('\n');
@@ -757,6 +815,31 @@ export function validateRecycleEnvelope(input: unknown): string[] {
         }
     }
 
+    // VARIANT FIRST, then version. The order is the contract, not a style
+    // choice. Required fields are variant-specific, so a reader that does not
+    // recognise the variant cannot know what to demand — and a reader that
+    // reports twenty field violations against a variant it never understood has
+    // told the operator nothing useful and, worse, has implied the record was
+    // malformed when the truth is that the reader is old. One refusal naming
+    // the variant is the honest output, and it is what makes an old reader
+    // meeting a new record a legible event rather than a pile of noise.
+    const variant = e['variant'];
+    if (typeof variant !== 'string' || !(CAPSULE_VARIANTS as readonly string[]).includes(variant)) {
+        return [
+            `unknown variant ${JSON.stringify(variant)} — this reader knows ` +
+                `${CAPSULE_VARIANTS.join(' | ')}. A reader that does not know a variant must not ` +
+                'guess at its required fields, so no further field checks were run.',
+        ];
+    }
+    if (variant === 'worker') {
+        return [
+            "variant 'worker' is a subagent generation handover and is validated by the worker " +
+                'path, not by the main-session recycle validator — routing it here would apply ' +
+                'the wrong required set to a well-formed record.',
+        ];
+    }
+    const isDerived = variant === 'continuity_record';
+
     const version = e['capsule_version'];
     if (typeof version !== 'number' || !ACCEPTED_CAPSULE_VERSIONS.includes(version)) {
         errors.push(`capsule_version must be one of ${ACCEPTED_CAPSULE_VERSIONS.join(' | ')}`);
@@ -766,9 +849,35 @@ export function validateRecycleEnvelope(input: unknown): string[] {
     // Demanding the new fields of an already-written record would be a
     // retroactive requirement, which is the one thing the recorded schema lock
     // forbids ("add fields or variants, never repurpose or remove one").
-    const atV4 = version === 4;
-    if (e['variant'] !== 'main_session') {
-        errors.push("variant must be 'main_session'");
+    //
+    // A `continuity_record` is exempt from the two v4 judgement fields for the
+    // opposite reason: it is forbidden from carrying them at all (below), so
+    // requiring them would make the variant unsatisfiable.
+    const atV4 = version === 4 && !isDerived;
+
+    if (isDerived) {
+        // Forbidden, not merely absent: a derived record that carries a
+        // judgement field is either a `main_session` mislabelled, or a
+        // deterministic writer that invented a value. Both are worth refusing
+        // loudly, and neither is distinguishable after the fact.
+        for (const key of Object.keys(e)) {
+            if (CONTINUITY_RECORD_FORBIDDEN_KEYS.has(key)) {
+                errors.push(
+                    `field "${key}" is forbidden on variant 'continuity_record' — it carries a ` +
+                        'model judgement, and a record written without model spend cannot have made ' +
+                        "one. Use variant 'main_session' for a judged record.",
+                );
+            }
+        }
+        for (const key of CONTINUITY_RECORD_REQUIRED_KEYS) {
+            if (e[key] === undefined) {
+                errors.push(
+                    `field "${key}" is required on variant 'continuity_record' — it is computable ` +
+                        'from on-disk state, so its absence is a writer defect rather than an ' +
+                        'unavailable judgement.',
+                );
+            }
+        }
     }
     if (!isShortLine(e['summary'], MAX_LINE_CHARS)) {
         errors.push(`summary must be a single line of 1–${MAX_LINE_CHARS} chars`);
@@ -789,7 +898,7 @@ export function validateRecycleEnvelope(input: unknown): string[] {
         errors.push('acceptance_criteria must carry at least one entry — the successor cannot know "done" without it');
     }
     checkList(errors, 'remaining', e['remaining'], MAX_LINE_CHARS, true);
-    checkList(errors, 'not_carried_forward', e['not_carried_forward'], MAX_LINE_CHARS, true);
+    checkList(errors, 'not_carried_forward', e['not_carried_forward'], MAX_LINE_CHARS, !isDerived);
     checkList(errors, 'decisions', e['decisions'], MAX_LINE_CHARS, false);
     errors.push(...decisionTagErrors(e['decisions']));
     checkList(errors, 'constraints', e['constraints'], MAX_LINE_CHARS, false);
@@ -809,7 +918,7 @@ export function validateRecycleEnvelope(input: unknown): string[] {
 
     // Required with ≥ 1 entry (Phase 2.3): a session that abandoned nothing
     // writes `none`. Absence must never be readable as "nothing failed".
-    checkList(errors, 'failed_approaches', e['failed_approaches'], MAX_LINE_CHARS, true);
+    checkList(errors, 'failed_approaches', e['failed_approaches'], MAX_LINE_CHARS, !isDerived);
     if (Array.isArray(e['failed_approaches']) && e['failed_approaches'].length === 0) {
         errors.push(
             'failed_approaches must carry at least one entry — write "none" explicitly, so ' +
@@ -835,7 +944,7 @@ export function validateRecycleEnvelope(input: unknown): string[] {
     // is a reader waiting for something that will not arrive.
     const predecessor = e['predecessor'];
     if (predecessor === undefined) {
-        if (atV4) {
+        if (atV4 || isDerived) {
             errors.push(
                 'predecessor is required — name the session this one continues, or write "none" ' +
                     'explicitly for the first session in a workspace',

package/src/scripts/_lib/vendored_grammar_upstream.ts

@@ -0,0 +1,280 @@
+/**
+ * The vendored grammars' one anchor outside the manifest.
+ *
+ * WHAT THIS ANSWERS.
+ *
+ * `packed_binary_predicate.ts` verifies eleven conditions over
+ * `src/config/packed-binary-manifest.json`, and every one of them is
+ * manifest-internal: the manifest states a sha256 and the bytes are hashed
+ * against it, so a single commit that edits both passes all eleven. The
+ * `release/14.22.0` self-review finding `d1696732ac28` names exactly that gap.
+ * This module closes it by comparing the vendored bytes against a source the
+ * repository does not author: the `tree-sitter-wasms` release pinned in
+ * `package-lock.json` and installed by `npm ci`.
+ *
+ * WHAT IT MAY CLAIM, AND WHAT IT MAY NOT.
+ *
+ * It MAY claim: the vendored bytes equal the bytes of the locked upstream
+ * package, independent of the binary manifest's own self-description.
+ *
+ * It MUST NOT claim to be independent of all repository state, and it MUST NOT
+ * claim to verify the grammars cryptographically against the registry
+ * independent of local build state. It does neither. The chain is
+ * registry tarball -> `npm ci` checks its sha512 against the lock's
+ * `integrity` -> extracted bytes -> vendored bytes, and only the last link is
+ * checked here. An attacker who edits `node_modules` after install defeats
+ * this, and a lock entry that points at a hostile package defeats it earlier
+ * still — that link is review's job, not a check's, because the lock is
+ * human-readable text and the manifest is machine-only JSON.
+ *
+ * Both scoping sentences are the AI council's wording (2026-09-09, 2 seats,
+ * unanimous on this question), kept verbatim so a later reader can tell the
+ * boundary from an oversight.
+ *
+ * WHY IT REFUSES RATHER THAN SKIPS.
+ *
+ * An upstream comparison is trivially written so that it passes when the
+ * upstream is absent, which is a green that verifies nothing — the exact shape
+ * of the eleven conditions it is here to supplement. So an absent package, a
+ * version that is not the locked one, an absent counterpart file, an empty
+ * claim set, and two admitted entries sharing a filename are all refusals,
+ * never passes.
+ *
+ * The last of those is the subtlest, and it was added on an R2 review finding
+ * rather than foreseen: the upstream keeps its grammars in one flat directory,
+ * so the counterpart is addressed by basename. Two manifest rows with the same
+ * filename in different directories would anchor to the same upstream file —
+ * one admitted binary silently unanchored while the verdict reported full
+ * coverage, which is the false green this module exists to remove. The vendored
+ * side resolves the entry's OWN repo-relative path, never a basename under a
+ * fixed directory, for the same reason.
+ */
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { loadManifest, VERIFIABLE_KIND, type PackedBinaryManifest } from './packed_binary_predicate.js';
+
+/**
+ * The upstream this repository copies from. Hardcoded rather than derived: the
+ * vendored set exists precisely because the package is NOT a runtime
+ * dependency, so there is no dependency edge to read it off, and
+ * `src/vendor/grammars/README.md` names the same string as the refresh source.
+ */
+export const UPSTREAM_PACKAGE = 'tree-sitter-wasms';
+
+/** Where the upstream keeps its compiled grammars inside its own package. */
+const UPSTREAM_GRAMMAR_SUBDIR = 'out';
+
+/** A refusal — the anchor could not be established, so no verdict is honest. */
+export class UpstreamAnchorRefusal extends Error {
+    constructor(message: string) {
+        super(message);
+        this.name = 'UpstreamAnchorRefusal';
+    }
+}
+
+/** One vendored file compared against its upstream counterpart. */
+export interface GrammarComparison {
+    readonly vendoredPath: string;
+    readonly upstreamPath: string;
+    readonly vendoredSha256: string;
+    readonly upstreamSha256: string;
+    readonly equal: boolean;
+}
+
+export interface UpstreamAnchorVerdict {
+    readonly lockedVersion: string;
+    readonly lockedIntegrity: string;
+    readonly installedVersion: string;
+    readonly comparisons: readonly GrammarComparison[];
+    /** Human-readable divergence lines. Empty iff every comparison is equal. */
+    readonly divergences: readonly string[];
+}
+
+export interface UpstreamAnchorOptions {
+    readonly repoRoot: string;
+    /** Defaults to `<repoRoot>/node_modules/<UPSTREAM_PACKAGE>`. Fixture seam. */
+    readonly upstreamPackageDir?: string;
+    /**
+     * Root the manifest's repo-relative `path` values resolve against.
+     * Defaults to `repoRoot`. Fixture seam — NOT a grammar directory: resolving
+     * by directory would discard the entry's own path, and two rows sharing a
+     * basename in different directories would then anchor to the same file.
+     */
+    readonly vendoredRoot?: string;
+    /** Defaults to the manifest at `<repoRoot>/src/config/…`. Fixture seam. */
+    readonly manifest?: PackedBinaryManifest;
+}
+
+export interface LockPin {
+    readonly version: string;
+    readonly integrity: string;
+}
+
+/**
+ * The locked pin for the upstream, read from `package-lock.json`.
+ *
+ * `integrity` is not used to verify anything here — it is carried into the
+ * verdict so the caller can print the anchor it is trusting, and its absence
+ * is a refusal because a lock row without one pins a version and not bytes.
+ */
+export function readLockPin(repoRoot: string): LockPin {
+    const lockPath = path.join(repoRoot, 'package-lock.json');
+    if (!fs.existsSync(lockPath)) {
+        throw new UpstreamAnchorRefusal(`no package-lock.json at ${lockPath} — there is no locked upstream to anchor to`);
+    }
+    const lock = JSON.parse(fs.readFileSync(lockPath, 'utf-8')) as {
+        packages?: Record<string, { version?: string; integrity?: string }>;
+    };
+    const key = `node_modules/${UPSTREAM_PACKAGE}`;
+    const row = lock.packages?.[key];
+    if (row === undefined) {
+        throw new UpstreamAnchorRefusal(`package-lock.json carries no \`${key}\` row — the vendored grammars have no locked source`);
+    }
+    if (typeof row.version !== 'string' || row.version.length === 0) {
+        throw new UpstreamAnchorRefusal(`\`${key}\` in package-lock.json carries no version`);
+    }
+    if (typeof row.integrity !== 'string' || row.integrity.length === 0) {
+        throw new UpstreamAnchorRefusal(
+            `\`${key}\` in package-lock.json carries no \`integrity\` — the row pins a version but not bytes, so \`npm ci\` verifies nothing for it`,
+        );
+    }
+    return { version: row.version, integrity: row.integrity };
+}
+
+/**
+ * The manifest, read through the predicate's own reader.
+ *
+ * A second reader would drift: a shape condition added there — a
+ * `schema_version` check, a kind allowlist — would leave this module accepting
+ * a manifest the predicate rejects, and this module's whole value is that it
+ * covers what the manifest admits. So `loadManifest` is the reader and this
+ * wrapper only re-types its failures as refusals, because an unreadable
+ * manifest means the anchor was not established rather than that it failed.
+ * R2 finding 2, 2026-09-09 — the duplicate reader this replaces was one
+ * identifier away from the import already at the top of this file.
+ */
+function readManifest(repoRoot: string): PackedBinaryManifest {
+    try {
+        return loadManifest(repoRoot);
+    } catch (err) {
+        throw new UpstreamAnchorRefusal(
+            `the packed-binary manifest could not be read, so nothing was compared: ${err instanceof Error ? err.message : String(err)}`,
+        );
+    }
+}
+
+function sha256(file: string): string {
+    return createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+/**
+ * Compare every vendored grammar the manifest admits against the locked
+ * upstream's copy of the same filename.
+ *
+ * Throws `UpstreamAnchorRefusal` when the anchor cannot be established at all;
+ * returns a verdict whose `divergences` is non-empty when it can be established
+ * and the bytes differ. The two are deliberately different outcomes: a refusal
+ * says "this was not checked", a divergence says "this was checked and is
+ * wrong", and collapsing them is how a check becomes a permanent green.
+ */
+export function verifyVendoredGrammarsAgainstUpstream(options: UpstreamAnchorOptions): UpstreamAnchorVerdict {
+    const { repoRoot } = options;
+    const upstreamDir = options.upstreamPackageDir ?? path.join(repoRoot, 'node_modules', UPSTREAM_PACKAGE);
+    const vendoredRoot = options.vendoredRoot ?? repoRoot;
+    const manifest = options.manifest ?? readManifest(repoRoot);
+
+    const pin = readLockPin(repoRoot);
+
+    const claims = manifest.entries.filter((e) => e.kind === VERIFIABLE_KIND);
+    if (claims.length === 0) {
+        throw new UpstreamAnchorRefusal(
+            `the manifest admits no \`${VERIFIABLE_KIND}\` entry — nothing was compared, and reporting that as a pass would be a green over an empty corpus`,
+        );
+    }
+
+    // The upstream keeps its grammars in one flat directory, so the counterpart
+    // is addressed by basename. Two admitted entries sharing a basename would
+    // therefore point at the same upstream file, which is an ambiguous anchor
+    // rather than a comparison — refuse instead of picking one.
+    const byBase = new Map<string, string[]>();
+    for (const e of claims) {
+        const base = path.basename(e.path);
+        byBase.set(base, [...(byBase.get(base) ?? []), e.path]);
+    }
+    const ambiguous = [...byBase.entries()].filter(([, paths]) => paths.length > 1);
+    if (ambiguous.length > 0) {
+        throw new UpstreamAnchorRefusal(
+            `two or more admitted entries share a filename, so they would anchor to the same upstream file: ${ambiguous
+                .map(([base, paths]) => `${base} <- ${paths.join(', ')}`)
+                .join('; ')}`,
+        );
+    }
+
+    const upstreamPkgJson = path.join(upstreamDir, 'package.json');
+    if (!fs.existsSync(upstreamPkgJson)) {
+        throw new UpstreamAnchorRefusal(
+            `${UPSTREAM_PACKAGE} is not installed at ${upstreamDir} — run \`npm ci\`. The vendored bytes were NOT verified; an absent upstream is a refusal, never a pass`,
+        );
+    }
+    const installed = JSON.parse(fs.readFileSync(upstreamPkgJson, 'utf-8')) as { version?: string };
+    if (installed.version !== pin.version) {
+        throw new UpstreamAnchorRefusal(
+            `installed ${UPSTREAM_PACKAGE} is ${String(installed.version)} but package-lock.json pins ${pin.version} — comparing against an unlocked tree would anchor to nothing`,
+        );
+    }
+
+    const comparisons: GrammarComparison[] = [];
+    const divergences: string[] = [];
+
+    for (const entry of claims) {
+        const vendoredPath = path.join(vendoredRoot, entry.path);
+        const upstreamPath = path.join(upstreamDir, UPSTREAM_GRAMMAR_SUBDIR, path.basename(entry.path));
+        if (!fs.existsSync(vendoredPath)) {
+            throw new UpstreamAnchorRefusal(`the manifest admits ${entry.path} but ${vendoredPath} does not exist`);
+        }
+        if (!fs.existsSync(upstreamPath)) {
+            throw new UpstreamAnchorRefusal(
+                `${entry.path} has no counterpart at ${upstreamPath} — the locked upstream does not carry this grammar, so this file has no anchor`,
+            );
+        }
+        const vendoredSha256 = sha256(vendoredPath);
+        const upstreamSha256 = sha256(upstreamPath);
+        const equal = vendoredSha256 === upstreamSha256;
+        comparisons.push({ vendoredPath, upstreamPath, vendoredSha256, upstreamSha256, equal });
+        if (!equal) {
+            divergences.push(
+                `${entry.path}: vendored sha256 ${vendoredSha256} != upstream ${upstreamSha256} (${UPSTREAM_PACKAGE}@${pin.version})`,
+            );
+        }
+    }
+
+    return buildVerdict({ pin, installedVersion: installed.version, comparisons, divergences });
+}
+
+/**
+ * Assemble the verdict from the two version sources, kept separate.
+ *
+ * Extracted so the sourcing is testable at all. On any tree the check accepts,
+ * `pin.version` and the installed version are equal — the strict guard above
+ * refuses otherwise — so a test driving the whole function can never tell which
+ * of the two the `installedVersion` field came from, and the round-1 regression
+ * test for exactly that defect passed with the defect restored. R2 finding 1,
+ * 2026-09-09. Here the two can be given different values, which is the only
+ * place the distinction is observable.
+ */
+export function buildVerdict(args: {
+    readonly pin: LockPin;
+    readonly installedVersion: string;
+    readonly comparisons: readonly GrammarComparison[];
+    readonly divergences: readonly string[];
+}): UpstreamAnchorVerdict {
+    return {
+        lockedVersion: args.pin.version,
+        lockedIntegrity: args.pin.integrity,
+        installedVersion: args.installedVersion,
+        comparisons: args.comparisons,
+        divergences: args.divergences,
+    };
+}

package/src/scripts/ai_council/api_transport.ts

@@ -47,6 +47,11 @@ export function curlJsonPost(url: string, extraHeaders: string[], body: unknown)
     // before the `spawnSync` timeout would kill it with an opaque ETIMEDOUT.
     // A full 16k-token generation legitimately runs several minutes, so the
     // ceiling is 300s, not 120s (the old value timed out long Anthropic calls).
+    // Both ceilings are PER CALL, never a run total. Members are iterated
+    // serially, so a run's worst case is members x passes x 290s, and nothing
+    // cancels a call mid-flight: `spawnSync` takes no signal, which is the
+    // synchronous contract the module docblock states. The only run-level bound
+    // is the USD cap, and it is checked AFTER a call returns.
     args.push('--connect-timeout', '30', '--max-time', '290');
     args.push('-w', '\n%{http_code}', '--data-binary', '@-');
     const r = spawnSync('curl', args, {