@event4u/agent-config 16.0.0 → 16.2.0

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`;
+    }
+}