@event4u/agent-config 15.0.0 → 16.1.0

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';

package/src/scripts/_lib/council_transport.ts

@@ -0,0 +1,129 @@
+/**
+ * Council transport and cost — `road-to-adversarial-verification-and-long-runs`
+ * 10.1.
+ *
+ * The posture is CLI → CLI quota exhausted → API within the ceiling → API over
+ * the ceiling → **pause and report**. The last rung is the step's whole point:
+ * over the ceiling the run does not ask whether to buy more technical API usage.
+ * It reports.
+ *
+ * ```
+ * AN OVER-CEILING COUNCIL REQUIREMENT PRODUCES A REPORT, NEVER A QUESTION.
+ * TECHNICAL API SPEND IS NOT A DECISION THE OWNER IS ASKED FOR MID-RUN.
+ * BUSINESS SPEND IS A TYPED OP AND A DIFFERENT CATEGORY ENTIRELY.
+ * ```
+ *
+ * **Why a report rather than an ask, when both interrupt.** They do not
+ * interrupt the same way. An ask BLOCKS: the run stops until an answer arrives,
+ * and the thing being asked about — a few dollars of inference — is worth less
+ * than the run's remaining work. A report does not block: it says what needed the
+ * council, why the cheaper route was unavailable, what it would cost, and — the
+ * load-bearing field — **what can still proceed without it**. Most of a mission
+ * can.
+ *
+ * Pure.
+ */
+
+/** The routes, cheapest first. */
+export type Route = 'cli' | 'api' | 'paused';
+
+export interface TransportInput {
+    /** Is the CLI route configured and within quota? */
+    readonly cliAvailable: boolean;
+    /** Why the CLI is unavailable, when it is not. */
+    readonly cliUnavailableReason: string | null;
+    /** Estimated USD for the API route. */
+    readonly estimateUsd: number;
+    /** The run's remaining technical-spend ceiling in USD. */
+    readonly ceilingUsd: number;
+}
+
+export interface PauseReport {
+    readonly needed: string;
+    readonly cliUnavailableBecause: string;
+    readonly estimateUsd: number;
+    readonly ceilingUsd: number;
+    readonly missionState: string;
+    /** What the run continues with meanwhile. Empty is a real, reportable answer. */
+    readonly canStillProceed: readonly string[];
+}
+
+export interface TransportDecision {
+    readonly route: Route;
+    readonly reason: string;
+    /** Present only on `paused`. */
+    readonly report: PauseReport | null;
+}
+
+export interface PauseContext {
+    readonly needed: string;
+    readonly missionState: string;
+    readonly canStillProceed: readonly string[];
+}
+
+/**
+ * Route one council requirement.
+ *
+ * A ceiling of zero pauses rather than dividing by it, and an estimate exactly
+ * AT the ceiling is within it — the ceiling is a limit, not an exclusive bound,
+ * and reading it the other way would pause a run that had budgeted exactly.
+ */
+export function routeCouncil(input: TransportInput, ctx: PauseContext): TransportDecision {
+    if (input.cliAvailable) {
+        return { route: 'cli', reason: 'the CLI route is available and within quota', report: null };
+    }
+    const why = input.cliUnavailableReason ?? 'unstated';
+    if (input.estimateUsd <= input.ceilingUsd) {
+        return {
+            route: 'api',
+            reason: `CLI unavailable (${why}); the API estimate $${input.estimateUsd.toFixed(2)} is within the $${input.ceilingUsd.toFixed(2)} ceiling`,
+            report: null,
+        };
+    }
+    return {
+        route: 'paused',
+        reason: `the API estimate $${input.estimateUsd.toFixed(2)} exceeds the $${input.ceilingUsd.toFixed(2)} ceiling`,
+        report: {
+            needed: ctx.needed,
+            cliUnavailableBecause: why,
+            estimateUsd: input.estimateUsd,
+            ceilingUsd: input.ceilingUsd,
+            missionState: ctx.missionState,
+            canStillProceed: ctx.canStillProceed,
+        },
+    };
+}
+
+/** The six fields a pause report must carry. */
+export const REPORT_FIELDS: readonly (keyof PauseReport)[] = [
+    'needed',
+    'cliUnavailableBecause',
+    'estimateUsd',
+    'ceilingUsd',
+    'missionState',
+    'canStillProceed',
+];
+
+/**
+ * Render the report.
+ *
+ * It ends on what can still proceed, and that placement is deliberate: a reader
+ * who stops after the cost has read a complaint, and a reader who reaches the
+ * last line has read a status. Nothing here is phrased as a question, and the
+ * renderer emits no `?` — asserted by a test, because the failure mode is a
+ * report that drifts into an ask one helpful sentence at a time.
+ */
+export function renderReport(r: PauseReport): string {
+    const proceeding =
+        r.canStillProceed.length > 0
+            ? r.canStillProceed.map((x) => `  - ${x}`).join('\n')
+            : '  - nothing; the mission is blocked on this council pass alone';
+    return [
+        `Council paused: ${r.needed}`,
+        `CLI route unavailable: ${r.cliUnavailableBecause}`,
+        `API estimate $${r.estimateUsd.toFixed(2)} over the $${r.ceilingUsd.toFixed(2)} technical ceiling`,
+        `Mission state: ${r.missionState}`,
+        'Proceeding meanwhile with:',
+        proceeding,
+    ].join('\n');
+}

package/src/scripts/_lib/delivery_ready.ts

@@ -0,0 +1,112 @@
+/**
+ * Is a PR delivery-ready? — `road-to-adversarial-verification-and-long-runs` 3.1.
+ *
+ * The step's acceptance clause is that *a fixture PR with a disabled required
+ * check cannot reach delivery-ready*, and that is the one case a naive reader
+ * gets wrong: a PR whose required context was SKIPPED has a green rollup. GitHub
+ * reports `SKIPPED` as a non-failure, so a predicate that asks "did anything
+ * fail" answers no, and the gate the context was supposed to enforce did not run.
+ *
+ * So this asks two questions rather than one: did every required context report,
+ * and did each of those reports actually pass. A context that is missing from
+ * the rollup entirely fails the first; a context present but skipped, cancelled
+ * or neutral fails the second.
+ *
+ * Pure — the caller supplies the rollup and the required set, so both polarities
+ * are testable without a forge.
+ */
+
+/** One check as a forge rollup reports it. */
+export interface CheckRun {
+    readonly name: string;
+    /** `SUCCESS` · `FAILURE` · `SKIPPED` · `CANCELLED` · `NEUTRAL` · `null` while running. */
+    readonly conclusion: string | null;
+    /** `COMPLETED` · `IN_PROGRESS` · `QUEUED`. */
+    readonly status: string;
+}
+
+/** Why a PR is not delivery-ready. Empty means it is. */
+export type DeliveryBlock =
+    | { readonly kind: 'required-context-absent'; readonly context: string }
+    | { readonly kind: 'required-context-not-passing'; readonly context: string; readonly conclusion: string }
+    | { readonly kind: 'still-running'; readonly context: string }
+    | { readonly kind: 'stale-head'; readonly observed: string; readonly head: string };
+
+/**
+ * The only conclusion that counts as a required check having done its job.
+ *
+ * `SKIPPED` is deliberately NOT here, and it is the reason this module exists:
+ * a skipped required check is an unenforced gate wearing a green rollup.
+ * `NEUTRAL` and `CANCELLED` are excluded on the same ground — a check that
+ * reached no verdict enforced nothing, whatever colour it rendered.
+ */
+const PASSING = 'SUCCESS';
+
+export interface DeliveryInput {
+    /** Contexts the forge requires, from `forge_protection`'s ruleset read. */
+    readonly requiredContexts: readonly string[];
+    /** The rollup on the head under test. */
+    readonly checks: readonly CheckRun[];
+    /** The head CI actually observed. */
+    readonly observedHead: string;
+    /** The branch head right now. */
+    readonly head: string;
+}
+
+/**
+ * Every reason this PR is not delivery-ready, in report order.
+ *
+ * Returns ALL blocks rather than the first: a run that fixes one and re-pushes
+ * to discover the next has spent a CI cycle per block, which is the cost layer 1
+ * of the delivery contract exists to avoid paying at layer 4.
+ */
+export function deliveryBlocks(input: DeliveryInput): DeliveryBlock[] {
+    const out: DeliveryBlock[] = [];
+    const byName = new Map(input.checks.map((c) => [c.name, c]));
+
+    for (const context of input.requiredContexts) {
+        const run = byName.get(context);
+        if (run === undefined) {
+            out.push({ kind: 'required-context-absent', context });
+            continue;
+        }
+        if (run.status !== 'COMPLETED') {
+            out.push({ kind: 'still-running', context });
+            continue;
+        }
+        if (run.conclusion !== PASSING) {
+            out.push({
+                kind: 'required-context-not-passing',
+                context,
+                conclusion: run.conclusion ?? 'null',
+            });
+        }
+    }
+
+    // Checked LAST and always: a green rollup on a head that is no longer the
+    // branch head is a verdict about a different tree. `ci_settle` names the head
+    // its verdict is about precisely so this comparison is possible.
+    if (input.observedHead !== input.head) {
+        out.push({ kind: 'stale-head', observed: input.observedHead, head: input.head });
+    }
+    return out;
+}
+
+/** True only when nothing blocks. */
+export function isDeliveryReady(input: DeliveryInput): boolean {
+    return deliveryBlocks(input).length === 0;
+}
+
+/** One human-readable line per block. */
+export function renderBlock(b: DeliveryBlock): string {
+    switch (b.kind) {
+        case 'required-context-absent':
+            return `required check "${b.context}" did not report at all`;
+        case 'required-context-not-passing':
+            return `required check "${b.context}" concluded ${b.conclusion}, not SUCCESS — a skipped or cancelled required check is an unenforced gate, not a pass`;
+        case 'still-running':
+            return `required check "${b.context}" has not completed`;
+        case 'stale-head':
+            return `CI was observed on ${b.observed} but the branch head is ${b.head} — the verdict describes a different tree`;
+    }
+}

package/src/scripts/_lib/dropped_decision.ts

@@ -0,0 +1,142 @@
+/**
+ * Detector E of `turn-end-gate`, extracted so its prose costs nothing.
+ *
+ * It lives here rather than in the hook for one mechanical reason and one real
+ * one. The mechanical one: `turn_end_gate_hook.ts` sits past the 1500-line
+ * source ceiling, where every line is one unit of ratchet debt, and this module
+ * is under it. The real one: E is the only detector that reads a LIST of the
+ * turn's assistant texts rather than the single closing one, so it shares no
+ * input with A-D and F, and its dependencies are the reply-consistency parser
+ * rather than anything the hook owns.
+ */
+import {
+    find_option_blocks,
+    recommendationsUnder,
+    splitAndMask,
+} from '../check_reply_consistency.js';
+import type { RefusalDetectorId } from './turn_end_refusals.js';
+
+/** The shape the gate collects. Kept structural so this module imports no hook. */
+export interface DroppedDecisionFinding {
+    detector: RefusalDetectorId;
+    evidence: string;
+    reason: string;
+}
+
+/**
+ * Detector E — a decision put to the user in this turn, dropped before the turn
+ * ended.
+ *
+ * THE MEASURED FAILURE. An assistant turn put three numbered options and a
+ * recommendation line to the user. The `end-review-nudge` stop concern then
+ * produced a SECOND assistant execution with no intervening user message, and
+ * that second reply handled the nudge while demoting the open question to a
+ * subordinate clause — "bleibt davon unberührt und liegt bei Dir". From the
+ * user's side the conversation ended without a question. No rule stated this
+ * when the detector was written: `user-interaction` Iron Law 1 inspects a reply
+ * that HAS an options block, `check_reply_consistency` receives a draft and not
+ * a transcript, `active-remediation` governs findings rather than issued
+ * decisions, and `no-cheap-questions` guards the opposite direction. That gap
+ * is now closed from the other side — `user-interaction` Iron Law 3 states the
+ * continuity obligation, and the refusal below cites it — so this paragraph
+ * records why the detector exists, not a gap that is still open.
+ *
+ * WHAT IT READS. `assistantTurnTexts` — the assistant texts since the last
+ * GENUINE user prompt, with synthetic prompts and sidechain entries already
+ * filtered by `readTranscriptTail`. So a task notification, a system reminder or
+ * a subagent's own prompt does not read as an answer, which is the whole point:
+ * the failure is defined by the absence of a real user turn.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO. It does not model the decision — no id, no
+ * `pending → answered` lifecycle, no semantic matching of a free-text reply
+ * against an option. That object is grant-shaped and
+ * `road-to-decision-closure` owns its ownership routing; a second obligation
+ * ledger here would be the parallel taxonomy that roadmap exists to prevent.
+ * This is transcript adjacency and nothing above it.
+ *
+ * AN ASK IS A BLOCK **PLUS** ITS RECOMMENDATION LINE, and that qualifier is
+ * load-bearing rather than pedantic. `find_option_blocks` calls any run of two
+ * or more consecutive numbered lines a block — a plan, a findings list, an
+ * ordinary enumeration. Keyed on the block alone this detector fired on 29 of
+ * this repository's own 592 assistant turns, and 8 of those blocks carried no
+ * recommendation line anywhere near them: pure false positives on narrative
+ * lists, in a detector that can REFUSE a turn. `user-interaction` Iron Law 1
+ * already says the recommendation line is the ask, so requiring it removes that
+ * whole class by applying the rule this refusal cites rather than by bolting a
+ * heuristic beside it.
+ *
+ * The cost, stated rather than discovered: an options block whose recommendation
+ * line was omitted is invisible here. That reply is ALREADY a
+ * `check_reply_consistency` finding and a stated Iron Law 1 violation, so it is
+ * the malformed-ask problem rather than the dropped-ask problem — a different
+ * defect with a different owner.
+ *
+ * REUSE. `find_option_blocks` and `recommendationsUnder` are both the
+ * spec-backed readings behind `check_reply_consistency`, extracted rather than
+ * copied. `interruption_ledger_hook` carries its own `hasNumberedOptions` for
+ * the capture-only ledger; a third reading of the same rule would drift from
+ * both.
+ *
+ * TWO KNOWN FALSE-POSITIVE PATHS, named because a refusing detector owes its
+ * residual rather than only its fix:
+ *
+ *   · A BLOCKQUOTED illustration of an ask — `> 1.` / `> 2.` plus a quoted
+ *     recommendation line — reads as live. `OPTION_LINE_RE` accepts a leading
+ *     `>` deliberately, because this suite's own documented ask shape is often
+ *     blockquoted, so excluding it would miss real asks to avoid a quoted one.
+ *     Fenced illustrations ARE excluded and tested; blockquoted ones are not,
+ *     and narrowing the shared parser to fix that would change what
+ *     `check_reply_consistency` enforces about Iron Law 1.
+ *   · A genuine user turn carrying NO `type: 'text'` block — an image-only
+ *     message — does not reset the turn, because `readTranscriptTail` skips an
+ *     entry with no text before reaching the reset. Changing that would move
+ *     `turnOrdinal` for all four other detectors on a shape none of them has
+ *     been measured against.
+ *
+ * Both cost one extra line in a reply, once: the re-entrancy layers cap a turn
+ * at ONE refusal, so neither can wedge a session.
+ */
+export function detectDroppedDecision(
+    assistantTurnTexts: readonly string[],
+    closingFromPayload = false,
+): DroppedDecisionFinding | null {
+    if (assistantTurnTexts.length < 2) return null;
+    // Masked once per text, not once per block: this runs on the stop path over
+    // every assistant text of the turn, and a reply with four numbered blocks
+    // would otherwise split and fence-mask the whole reply four times.
+    const asksIn = (text: string): ReturnType<typeof find_option_blocks> => {
+        const blocks = find_option_blocks(text);
+        if (blocks.length === 0) return blocks;
+        const masked = splitAndMask(text);
+        return blocks.filter((b) => recommendationsUnder(text, b, masked).length > 0);
+    };
+    const closing = assistantTurnTexts[assistantTurnTexts.length - 1]!;
+    if (asksIn(closing).length > 0) return null;
+    for (let i = assistantTurnTexts.length - 2; i >= 0; i -= 1) {
+        const earlier = assistantTurnTexts[i]!;
+        const blocks = asksIn(earlier);
+        if (blocks.length === 0) continue;
+        const block = blocks[blocks.length - 1]!;
+        return {
+            detector: 'pending-decision',
+            // The option NUMBERS and the line span, never the option text: the
+            // evidence is quoted into a refusal that reaches the transcript, and
+            // an options block can carry anything the reply carried.
+            evidence:
+                `options ${block.numbers.join('/')} at lines ${block.startLine}-${block.endLine} ` +
+                `of an earlier reply this turn (closing reply read from ` +
+                `${closingFromPayload ? 'the stop payload' : 'the transcript'})`,
+            reason:
+                'an earlier reply in THIS turn put numbered options to the user ' +
+                'and no user answer followed — this closing reply carries no ' +
+                'options block, so the decision disappeared without being ' +
+                'answered, cancelled or superseded. A hook nudge, a reviewer ' +
+                'result or a task notification may ADD to a turn; it may not ' +
+                'displace a question already asked (user-interaction Iron Law 3: ' +
+                'a decision handed to the user outlives the turn). ' +
+                'Re-present the block and its recommendation line at the end of ' +
+                'this reply',
+        };
+    }
+    return null;
+}