@event4u/agent-config 16.0.0 → 16.1.0

package/src/scripts/_lib/activation_payload.ts

@@ -0,0 +1,247 @@
+/**
+ * The runtime activation payload — what a trigger match charges per fire.
+ *
+ * The third of the three numbers `road-to-the-delivery-flip-that-tells-the-truth`
+ * Phase 3 separates. The other two already have names and a record: ADR-270
+ * calls them `source_corpus` (what the source tree could deliver) and
+ * `host_payload` (what one host actually receives at rest), and requires them to
+ * be structurally separate fields because "until the two are named apart, every
+ * ceiling discussion risks comparing unlike quantities". After a per-host
+ * projection flip a third quantity diverges from both: the bytes a delivery
+ * concern injects when a rule's trigger fires. A standing reduction published
+ * without it is a saving published without its cost.
+ *
+ * MEASURED THROUGH THE CONCERN'S OWN SELECTION, never a second model of it.
+ * `matchTierRules` + `selectForInjection` are the functions the runtime concern
+ * calls; an offline figure computed by a different matcher would price a set the
+ * concern does not deliver. That is the same single-definition rule
+ * `_lib/rule_injection.ts` was written for, applied one layer out.
+ *
+ * THE CAP IS A PARAMETER, not an import. The value lives on the concern
+ * (`hooks/rule_inject_hook.ts::CAP_BYTES`) and every caller passes it, so this
+ * module stays free of the hook's import closure and can be read from a gate, a
+ * report, or a bundled path without dragging a hook into it.
+ *
+ * Moved here from `report_standing_payload_by_host.ts`, which had the only
+ * implementation and is still its largest caller — same move, and for the same
+ * reason, as `censusRuleDir` into `_lib/carrier_divergence.ts`: a second reader
+ * needed it and a second copy is how two numbers start disagreeing.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { loadRouter, matchTierRules, selectForInjection } from './rule_injection.js';
+
+/** The frozen corpus every fire figure in this module is sampled from. */
+export const ROUTING_MATRIX_REL = path.join('tests', 'eval', 'routing-matrix');
+
+/** One positive prompt of the frozen corpus, with the open files it declares. */
+export interface CorpusPrompt {
+    prompt: string;
+    openFiles: string[] | null;
+}
+
+/**
+ * Every YAML shape inside `positives:` this hand parser cannot read.
+ *
+ * `readCorpusPositives` accepts only `- prompt: "…"` with a double-quoted
+ * same-line scalar and an inline `open_files: [...]`. Any other legal shape —
+ * single quotes, an unquoted scalar, a folded block, a block sequence for
+ * `open_files` — is SILENTLY SKIPPED, which drops fires out of the distribution
+ * a budget row is derived from. A measurement that governs a budget must fail
+ * loudly on a shape it cannot read rather than under-count, so callers refuse on
+ * a non-empty result here.
+ *
+ * Reported as a shape problem rather than fixed by widening the parser: this
+ * module must not grow a second YAML implementation, and the corpus is frozen,
+ * so the honest answer to an unreadable shape is to say which file carries it.
+ */
+export function corpusShapeProblems(root: string): string[] {
+    const dir = path.join(root, ROUTING_MATRIX_REL);
+    const problems: string[] = [];
+    if (!fs.existsSync(dir)) return problems;
+    for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.yaml')).sort()) {
+        let inPositives = false;
+        let lineNo = 0;
+        for (const raw of fs.readFileSync(path.join(dir, f), 'utf-8').split('\n')) {
+            lineNo += 1;
+            if (/^positives:/u.test(raw)) { inPositives = true; continue; }
+            if (/^near_misses:/u.test(raw)) { inPositives = false; continue; }
+            if (!inPositives) continue;
+            if (/^\s*-\s*prompt:/u.test(raw) && !/^\s*-\s*prompt:\s*"(.*)"\s*$/u.test(raw)) {
+                problems.push(
+                    `${f}:${String(lineNo)}: a \`- prompt:\` this parser cannot read — only a ` +
+                        `double-quoted same-line scalar is accepted: ${JSON.stringify(raw.trim())}`,
+                );
+                continue;
+            }
+            if (/^\s*-\s*/u.test(raw) && !/^\s*-\s*(prompt|command|open_files):/u.test(raw)
+                && raw.trim() !== '-' && raw.trim() !== '') {
+                // A bare sequence item under `positives:` is a shape with no
+                // `prompt:` key on its first line — folded or nested.
+                if (!/^\s{4,}/u.test(raw)) {
+                    problems.push(
+                        `${f}:${String(lineNo)}: a positives entry whose first line carries no ` +
+                            `\`prompt:\` key: ${JSON.stringify(raw.trim())}`,
+                    );
+                }
+            }
+            if (/^\s*open_files:\s*$/u.test(raw)) {
+                problems.push(
+                    `${f}:${String(lineNo)}: a BLOCK-sequence \`open_files:\` — only the inline ` +
+                        '`[...]` form is read, so this entry\'s files would be dropped',
+                );
+            }
+        }
+    }
+    return problems;
+}
+
+/** Every positive prompt in the frozen routing-matrix corpus. Near-misses are not fires. */
+export function readCorpusPositives(root: string): CorpusPrompt[] {
+    const dir = path.join(root, ROUTING_MATRIX_REL);
+    const out: CorpusPrompt[] = [];
+    if (!fs.existsSync(dir)) return out;
+    for (const f of fs.readdirSync(dir).filter((n) => n.endsWith('.yaml')).sort()) {
+        let inPositives = false;
+        let cur: CorpusPrompt | null = null;
+        for (const raw of fs.readFileSync(path.join(dir, f), 'utf-8').split('\n')) {
+            if (/^positives:/u.test(raw)) { inPositives = true; continue; }
+            if (/^near_misses:/u.test(raw)) { inPositives = false; continue; }
+            if (!inPositives) continue;
+            const p = /^\s*-\s*prompt:\s*"(.*)"\s*$/u.exec(raw);
+            if (p !== null) {
+                cur = { prompt: p[1] as string, openFiles: null };
+                out.push(cur);
+                continue;
+            }
+            const of = /^\s*open_files:\s*\[(.*)\]\s*$/u.exec(raw);
+            if (of !== null && cur !== null) {
+                cur.openFiles = (of[1] as string)
+                    .split(',')
+                    .map((x) => x.trim().replace(/^["']|["']$/gu, ''))
+                    .filter((x) => x !== '');
+            }
+        }
+    }
+    return out;
+}
+
+/** Nearest-rank percentile over an unsorted sample. Empty sample → 0. */
+export function percentile(xs: readonly number[], q: number): number {
+    if (xs.length === 0) return 0;
+    const s = [...xs].sort((a, b) => a - b);
+    return s[Math.min(s.length - 1, Math.floor(q * (s.length - 1)))] as number;
+}
+
+export interface SlotFireSizes {
+    readonly slot: string;
+    readonly fires: number;
+    readonly p50: number;
+    readonly p90: number;
+    readonly max: number;
+}
+
+/**
+ * Gate-open per-fire emission sizes for the delivery concern, per slot.
+ *
+ * `pre_compact` is 0 by construction rather than by measurement: that branch of
+ * `rule_inject_hook` clears the seen-set and returns allow without writing to
+ * stdout, so there is no emission to sample.
+ */
+export function slotFireSizes(root: string, capBytes: number): SlotFireSizes[] {
+    const router = loadRouter(root);
+    const prompts = readCorpusPositives(root);
+    const sample = (mode: 'prompt' | 'file'): number[] => {
+        const out: number[] = [];
+        for (const r of prompts) {
+            if (mode === 'file' && (r.openFiles === null || r.openFiles.length === 0)) continue;
+            const matches =
+                mode === 'prompt'
+                    ? matchTierRules(router, r.prompt, null, null)
+                    : matchTierRules(router, '', r.openFiles, null);
+            if (matches.length === 0) continue;
+            const sel = selectForInjection(root, matches, capBytes);
+            if (sel.selected.length > 0) out.push(sel.bytes);
+        }
+        return out;
+    };
+    const row = (slot: string, xs: number[]): SlotFireSizes => ({
+        slot,
+        fires: xs.length,
+        p50: percentile(xs, 0.5),
+        p90: percentile(xs, 0.9),
+        max: xs.length === 0 ? 0 : Math.max(...xs),
+    });
+    return [
+        row('user_prompt_submit', sample('prompt')),
+        row('pre_tool_use', sample('file')),
+        row('pre_compact', []),
+    ];
+}
+
+/** The third labelled number, or the reason it could not be taken on this tree. */
+export interface ActivationPayload {
+    /** Always the literal `activation-payload` — the label a reader and a caller key on. */
+    readonly scope: 'activation-payload';
+    /** `false` when the corpus or the router is absent; every figure is then 0. */
+    readonly measured: boolean;
+    /** Why it is unmeasured, or `null`. Never an estimate in place of a number. */
+    readonly unmeasured_reason: string | null;
+    /** The cap the sampled selection was taken at — the concern's `CAP_BYTES`. */
+    readonly cap_bytes: number;
+    readonly corpus: string;
+    readonly slots: readonly SlotFireSizes[];
+    readonly basis: string;
+}
+
+/**
+ * The runtime activation payload, or an honestly unmeasured reading.
+ *
+ * Never throws and never estimates: a missing corpus or router yields
+ * `measured: false` with the reason named, because a fabricated distribution
+ * published beside a standing saving is the exact defect this number exists to
+ * prevent.
+ */
+export function measureActivationPayload(root: string, capBytes: number): ActivationPayload {
+    const basis =
+        'Gate-open per-fire emission of the `rule-inject` concern over the frozen ' +
+        '`tests/eval/routing-matrix` positives, measured through the same ' +
+        '`matchTierRules` + `selectForInjection` the runtime concern calls, at the ' +
+        'concern\'s own CAP_BYTES. Bytes per fire, never tokens — the unit ' +
+        '`hook-token-budget.json` enforces.';
+    const empty = (reason: string): ActivationPayload => ({
+        scope: 'activation-payload',
+        measured: false,
+        unmeasured_reason: reason,
+        cap_bytes: capBytes,
+        corpus: ROUTING_MATRIX_REL,
+        slots: [],
+        basis,
+    });
+    if (!fs.existsSync(path.join(root, ROUTING_MATRIX_REL))) {
+        return empty(`the frozen corpus ${ROUTING_MATRIX_REL} is absent under ${root}`);
+    }
+    const shape = corpusShapeProblems(root);
+    if (shape.length > 0) {
+        return empty(
+            `${String(shape.length)} corpus entry/entries are in a shape the reader cannot parse, ` +
+                `so the distribution would be under-counted — first: ${shape[0] as string}`,
+        );
+    }
+    let slots: SlotFireSizes[];
+    try {
+        slots = slotFireSizes(root, capBytes);
+    } catch (err) {
+        return empty(`the fire sample could not be taken: ${(err as Error).message}`);
+    }
+    return {
+        scope: 'activation-payload',
+        measured: true,
+        unmeasured_reason: null,
+        cap_bytes: capBytes,
+        corpus: ROUTING_MATRIX_REL,
+        slots,
+        basis,
+    };
+}

package/src/scripts/_lib/agent_settings.ts

@@ -53,6 +53,7 @@ import { fileURLToPath } from 'node:url';
 
 import * as user_global_paths from './user_global_paths.js';
 import { carveOutKeys } from '../../shared/settingsCarveOut.js';
+import { applyRenamedKeys } from './settings_renamed_keys.js';
 import type * as YamlModule from 'yaml';
 
 // ESM has no `require`; `createRequire(import.meta.url)` restores it so the
@@ -956,9 +957,9 @@ export function load_agent_settings(
     // precedence here is the inverse of the server family's, so the order of
     // these three statements is the whole contract.
     const merged: SettingsDict = template_defaults(template_path ?? undefined);
-    _deep_merge(merged, user_global_filtered);
+    _deep_merge(merged, applyRenamedKeys(user_global_filtered));
     for (const p of cascade) {
-        const layer = _read_yaml(p) ?? {};
+        const layer = applyRenamedKeys(_read_yaml(p) ?? {});
         if (Object.keys(layer).length > 0) {
             _deep_merge(merged, layer);
         }
@@ -967,6 +968,7 @@ export function load_agent_settings(
     return merged;
 }
 
+
 /**
  * Settings keys this package has DELETED. A leftover value from an older
  * install is ignored — never applied by any reader — and surfaced with ONE

package/src/scripts/_lib/authority_path.ts

@@ -0,0 +1,102 @@
+/**
+ * The strictest path, reserved for authority —
+ * `road-to-adversarial-verification-and-long-runs` 11.1.
+ *
+ * An authority-expanding change takes four independent passes — an independent
+ * TEST author, an independent GOVERNANCE reviewer, a COUNCIL pass, and a
+ * PROVIDER-DIVERSE reviewer — plus the ratification artefact. Until the artefact
+ * carries `verdict: ratified`, the new authority is **inert**.
+ *
+ * ```
+ * NEW AUTHORITY IS INERT UNTIL RATIFIED. AN AGENT MAY AUTHOR THE CHANGE
+ * AND MAY NEVER RATIFY ITS OWN INCREASE IN POWER (ADR-268 § 4).
+ * FOUR PASSES, ALL FOUR, AND THEY MAY NOT BE THE SAME REVIEWER TWICE.
+ * ```
+ *
+ * **Inert-until-ratified is the property that makes the rest safe.** Without it
+ * the four passes are a process an author could complete and then merge; with it
+ * the change can land, be read, and still do nothing — so the ratification is a
+ * separate act on a separate turn by a party that is not the author.
+ *
+ * Pure.
+ */
+
+/** The four passes. All four, and the list is closed. */
+export const REQUIRED_PASSES = [
+    'independent-test-author',
+    'independent-governance-reviewer',
+    'council',
+    'provider-diverse-reviewer',
+] as const;
+export type Pass = (typeof REQUIRED_PASSES)[number];
+
+export interface PassRecord {
+    readonly pass: Pass;
+    /** Who performed it. Two passes by the same identity is not two passes. */
+    readonly by: string;
+    /** The provider, so provider-diversity is checkable rather than asserted. */
+    readonly provider: string;
+}
+
+export interface RatificationArtefact {
+    /** Anything other than `ratified` leaves the authority inert. */
+    readonly verdict: string;
+    readonly passes: readonly PassRecord[];
+    /** The author of the change under ratification. */
+    readonly author: string;
+}
+
+export type AuthorityState = 'inert' | 'active';
+
+export interface AuthorityVerdict {
+    readonly state: AuthorityState;
+    readonly blockers: readonly string[];
+}
+
+/**
+ * Is the new authority active yet?
+ *
+ * Returns EVERY blocker rather than the first: the artefact is a checklist a
+ * human completes, and handing them one item at a time turns four passes into
+ * four round trips.
+ */
+export function authorityState(a: RatificationArtefact | null): AuthorityVerdict {
+    if (a === null) {
+        return { state: 'inert', blockers: ['no ratification artefact exists'] };
+    }
+    const blockers: string[] = [];
+
+    for (const required of REQUIRED_PASSES) {
+        if (!a.passes.some((p) => p.pass === required)) {
+            blockers.push(`missing pass: ${required}`);
+        }
+    }
+
+    // The author may perform NONE of the four. This is the ADR-268 § 4 clause
+    // and the one a process can satisfy on paper while violating in substance.
+    for (const p of a.passes) {
+        if (p.by === a.author) {
+            blockers.push(`${p.pass} was performed by the author (${p.by}) — an agent may not ratify its own increase in power`);
+        }
+    }
+
+    // Provider diversity is a property of the SET, so it is checked over the set
+    // rather than trusted from the pass that carries the name.
+    const providers = new Set(a.passes.map((p) => p.provider));
+    if (a.passes.length > 1 && providers.size < 2) {
+        blockers.push(
+            `every pass ran on one provider (${[...providers].join(', ')}) — provider-diverse means at least two`,
+        );
+    }
+
+    if (a.verdict !== 'ratified') {
+        blockers.push(`verdict is "${a.verdict}", not "ratified"`);
+    }
+
+    return { state: blockers.length === 0 ? 'active' : 'inert', blockers };
+}
+
+/** `true` only for an artefact that clears everything. */
+export function isRatified(a: RatificationArtefact | null): boolean {
+    return authorityState(a).state === 'active';
+}

package/src/scripts/_lib/cascade_base.ts

@@ -0,0 +1,94 @@
+/**
+ * The cascade base — `road-to-adversarial-verification-and-long-runs` 5.1.
+ *
+ * `check_branch_freshness` asks whether a branch is behind THE BASE ITS PR
+ * TARGETS. That is one hop, and it is the right question for the common case
+ * where the base is the trunk. On a stacked PR it is only half of it: a branch
+ * targeting `feat/parent` can be perfectly current with `feat/parent` while
+ * `feat/parent` itself is fifty commits behind `main`, so the branch is stale
+ * against the tree it will eventually land in and every gate reports green.
+ *
+ * The cascade is the ordered list of refs a branch must be current with, nearest
+ * first. Merging in that order is not arbitrary: taking the trunk first would
+ * pull trunk commits past the parent and make the stack's own diff unreadable,
+ * which is the thing a stack exists to avoid.
+ *
+ * **Depth is bounded and the bound is deliberate.** A cascade is a chain of
+ * bases, and a chain can cycle — a branch whose PR targets a branch that targets
+ * it. `MAX_HOPS` stops the walk and the result says it was truncated, because
+ * a hop list silently cut short is indistinguishable from a short one.
+ *
+ * Pure: the caller supplies the base-of lookup, so the whole thing is testable
+ * without a forge.
+ */
+
+/** How many bases a cascade may chain through before the walk stops. */
+export const MAX_HOPS = 8;
+
+export interface Cascade {
+    /** Refs to merge in, nearest base first, trunk last. Never includes `branch`. */
+    readonly hops: readonly string[];
+    /** True when the walk stopped on a cycle rather than on the trunk. */
+    readonly cycle: boolean;
+    /** True when the walk stopped on {@link MAX_HOPS}. */
+    readonly truncated: boolean;
+}
+
+/** `null` when the ref has no PR base — i.e. it is a trunk or is unknown. */
+export type BaseOf = (ref: string) => string | null;
+
+/**
+ * Walk from `branch` to `trunk`, collecting every base on the way.
+ *
+ * A branch whose base IS the trunk yields one hop — identical to the single-hop
+ * behaviour that existed before, which is the compatibility property that
+ * matters: this widens the check, it does not change the common case.
+ */
+export function cascadeBase(branch: string, trunk: string, baseOf: BaseOf): Cascade {
+    const hops: string[] = [];
+    const seen = new Set<string>([branch]);
+    let current = branch;
+
+    for (let i = 0; i < MAX_HOPS; i += 1) {
+        const base = baseOf(current);
+        if (base === null || base === '') {
+            // No PR base. The trunk is still owed unless we are already on it.
+            if (current !== trunk && !hops.includes(trunk)) hops.push(trunk);
+            return { hops, cycle: false, truncated: false };
+        }
+        if (seen.has(base)) {
+            return { hops, cycle: true, truncated: false };
+        }
+        seen.add(base);
+        hops.push(base);
+        if (base === trunk) {
+            return { hops, cycle: false, truncated: false };
+        }
+        current = base;
+    }
+    return { hops, cycle: false, truncated: true };
+}
+
+/** One ref's freshness, as the caller measured it. */
+export interface HopReading {
+    readonly ref: string;
+    /** `true` behind · `false` current · `null` not measured. */
+    readonly behind: boolean | null;
+}
+
+/**
+ * Which hops still need merging, in order.
+ *
+ * An UNMEASURED hop is returned alongside the behind ones rather than skipped:
+ * "we could not tell" and "it is current" are different states, and treating the
+ * first as the second is how a single-hop check reported green on a stale stack
+ * in the first place.
+ */
+export function hopsNeedingMerge(readings: readonly HopReading[]): HopReading[] {
+    return readings.filter((r) => r.behind !== false);
+}
+
+/** True only when every hop was measured and every hop is current. */
+export function cascadeCurrent(readings: readonly HopReading[]): boolean {
+    return readings.length > 0 && readings.every((r) => r.behind === false);
+}

package/src/scripts/_lib/changelog_eras.ts

@@ -231,8 +231,13 @@ export function archive_file_header(boundary: string): string {
         '> `tests/test_changelog_eras.py`.\n' +
         '>\n' +
         '> **Read-only.** New entries land in `CHANGELOG.md`. Entries\n' +
-        '> here are not amended — git tags remain the canonical source\n' +
-        '> for what shipped.\n' +
+        '> here are not rewritten — git tags remain the canonical source\n' +
+        '> for what shipped. The one amendment an archive permits is a\n' +
+        '> **correction that adds**: where a published entry says something\n' +
+        '> the shipped tree contradicts, the correction is appended beside\n' +
+        '> it and names the commit that decided the matter. Nothing is\n' +
+        '> deleted, so both the original claim and its correction stay\n' +
+        '> readable.\n' +
         '>\n' +
         '> Entry shape follows\n' +
         '> [`../contracts/CHANGELOG-conventions.md`](../contracts/CHANGELOG-conventions.md).\n' +

package/src/scripts/_lib/continuation_ladder.ts

@@ -60,6 +60,122 @@ export const HALT_ACTIONS: readonly LadderAction[] = [
     'halt-premise-invalidated',
 ];
 
+/**
+ * The delivery state machine — `road-to-adversarial-verification-and-long-runs`
+ * Phase 8.1, in the order a run walks it.
+ *
+ * A run's checkboxes and its DELIVERY are two different completions, and until
+ * now only the first one could end a run. That is the defect: a run whose
+ * roadmap reads zero-open while its PR sits on red CI, or on a target that moved
+ * underneath it, reported `complete` — a completion claim about work whose only
+ * evidence (the CI verdict on the final head) says otherwise.
+ *
+ * Two of these are ENDINGS and the rest are not:
+ *   · `merged` — a grant existed and was spent.
+ *   · `open-green` — no grant; the PR is open, its CI is green on the head CI
+ *     actually observed, and the run says so. This is a success, not a
+ *     shortfall: a run without a merge grant is not supposed to merge.
+ * Every earlier position means work remains, whatever the checkboxes read.
+ */
+export const DELIVERY_STATES = [
+    'working',
+    'local-green',
+    'pushed',
+    'pr-open',
+    'ci-pending',
+    'ci-red',
+    'target-sync-check',
+    'target-moved',
+    'delivery-ready',
+    'merged',
+    'open-green',
+] as const;
+export type DeliveryState = (typeof DELIVERY_STATES)[number];
+
+/** The two positions at which a run has actually delivered. */
+export const DELIVERY_ENDINGS: readonly DeliveryState[] = ['merged', 'open-green'];
+
+/**
+ * True when this delivery position means work remains.
+ *
+ * `null` — nothing recorded a position — is NOT incomplete. The ladder runs on
+ * the Stop path, where a `gh` probe is not affordable, so the position is READ
+ * from what the run wrote rather than measured here. An unrecorded position
+ * therefore means *this run does not report delivery*, and inventing
+ * incompleteness from that absence would hang every run that never adopted the
+ * field. Fail-open, in the one direction that cannot manufacture a stall.
+ */
+export function deliveryBlocksCompletion(state: DeliveryState | null | undefined): boolean {
+    if (state === null || state === undefined) return false;
+    return !DELIVERY_ENDINGS.includes(state);
+}
+
+/** The facts one terminal ledger line records about a run. */
+export interface LedgerEventInput {
+    readonly action: LadderAction;
+    readonly runId: string;
+    readonly slug: string;
+    readonly turn: number;
+    readonly iterations: number;
+    readonly open: number;
+    readonly blocked: number;
+    readonly delivery: DeliveryState | null;
+}
+
+/**
+ * Build the terminal ledger line for a run.
+ *
+ * Extracted from `hooks/run_continuation_hook.ts` by
+ * `road-to-adversarial-verification-and-long-runs` 8.1, for the reason this
+ * module's own header gives: the hook sits past `check_source_size_budget`'s
+ * 1,500-line cap, where every added line is an added violation, so a phase pays
+ * for its additions by moving the code it is editing to a file under the cap.
+ * The `delivery` field is that addition.
+ *
+ * A ledger line is a persisted shape carrying a `RunTerminalState`, so it names
+ * the vocabulary version it was written against: a reader meeting an unknown
+ * value can then tell a newer writer from a corrupt row. `delivery` is OMITTED
+ * when the run reported no position rather than written as a null — `complete`
+ * alone cannot tell a merged run from an open-green one, and a null would read
+ * as "neither" rather than "unreported".
+ */
+export function buildLedgerEvent(
+    input: LedgerEventInput,
+    vocabularyVersion: number,
+    now: Date,
+): Record<string, unknown> {
+    return {
+        event: input.action,
+        run_id: input.runId,
+        roadmap: input.slug,
+        turn: input.turn,
+        iterations: input.iterations,
+        open: input.open,
+        blocked: input.blocked,
+        terminal_state: terminalStateFor(input.action),
+        terminal_vocabulary_version: vocabularyVersion,
+        ...(input.delivery !== null ? { delivery: input.delivery } : {}),
+        at: now.toISOString(),
+    };
+}
+
+/**
+ * Read a persisted delivery position tolerantly — `undefined` for anything this
+ * build does not recognise.
+ *
+ * Same forward-compatibility shape as {@link parseHaltStamp}, and the opposite
+ * fail direction on purpose: an unknown HALT is preserved, because dropping it
+ * re-engages a deliberately ended run; an unknown DELIVERY position is dropped,
+ * because preserving it would hold a run open on a state this build cannot
+ * evaluate. Both choose the branch that cannot manufacture a stall.
+ */
+export function parseDeliveryState(raw: unknown): DeliveryState | undefined {
+    if (typeof raw !== 'string') return undefined;
+    return (DELIVERY_STATES as readonly string[]).includes(raw)
+        ? (raw as DeliveryState)
+        : undefined;
+}
+
 /**
  * The subset of a run's state this decision reads. The hook's `RunState`
  * satisfies it structurally; nothing here may widen beyond what the rungs use.
@@ -128,6 +244,10 @@ export function ladder(
     // `_lib/context_observation.premiseMoved`. Optional and defaulted false, so
     // a caller that cannot observe the world decides exactly as it did before.
     premiseInvalidated: boolean = false,
+    // `road-to-adversarial-verification-and-long-runs` 8.1. The delivery position
+    // the run RECORDED, or `null` where it recorded none. Optional and defaulted,
+    // so a caller that does not track delivery decides exactly as it did before.
+    delivery: DeliveryState | null = null,
 ): LadderAction {
     // A halt is terminal for this run id. Checked BEFORE `complete` so a
     // halted run whose roadmap later reads zero-open does not report a
@@ -136,7 +256,26 @@ export function ladder(
     // `scanOpenSteps` EXCLUDES `blocked-by:` steps from `openCount`, so zero-open
     // with blocked steps left is exhaustion of runnable work, not completion —
     // ADR-235's own terminal outcome, and never a sixth halt.
-    if (openCount === 0) return blockedCount > 0 ? 'blocked' : 'complete';
+    //
+    // 8.1 — delivery is checked INSIDE the zero-open branch and only against
+    // `complete`. Two boundaries, both deliberate. It does not touch `blocked`:
+    // a run whose remaining work is blocked has not failed to deliver, it has
+    // run out of deliverable work, and holding it open on a PR it cannot advance
+    // would convert a nameable blocker into a stall. And it is not checked while
+    // steps are still open, because there the run continues anyway — adding a
+    // second reason to continue would only make the ledger's `open` count lie
+    // about why.
+    const deliveringOnly =
+        openCount === 0 && blockedCount === 0 && deliveryBlocksCompletion(delivery);
+    if (openCount === 0) {
+        if (blockedCount > 0) return 'blocked';
+        if (!deliveringOnly) return 'complete';
+        // Fall THROUGH to the budget rungs rather than returning `engage` here.
+        // Returning early would put the run outside every bound in this function
+        // — an unbounded loop, which is the failure the ladder exists against —
+        // so a run held open for delivery is still capped by iterations and the
+        // wall clock. Only the STALL rung is exempted, below.
+    }
     // BEFORE the counter rungs, deliberately: a missing credential, an absent
     // binary or an exhausted quota is not closed by iterating, so spending the
     // budget on it converts a nameable blocker into an anonymous cap-out.
@@ -151,8 +290,16 @@ export function ladder(
     if (Number.isFinite(started) && nowMs - started >= caps.wallClockMs) {
         return 'halt-wall-clock';
     }
+    // The stall rung reads OPEN-STEP progress, and during delivery open-step
+    // progress is definitionally zero: the checkboxes are all flipped and the
+    // remaining work is a CI red or a moved target. Applying it here would halt
+    // a healthy delivery loop on its third turn — a stall manufactured by the
+    // stall detector, which is exactly the failure `run_continuation_hook`'s own
+    // header warns about in the abstract and the one this file's mechanics call
+    // "a metric that stops moving because the MEASUREMENT broke". The iteration
+    // and wall-clock caps above still bound the loop; only this rung is skipped.
     const tail = state.history.slice(-caps.stallWindow);
-    if (tail.length >= caps.stallWindow && tail.every((n) => n === openCount)) {
+    if (!deliveringOnly && tail.length >= caps.stallWindow && tail.every((n) => n === openCount)) {
         return 'halt-stall';
     }
     return 'engage';