@event4u/agent-config 14.6.0 → 14.8.0

package/src/agent-src/scripts/dashboard_mode.ts

@@ -0,0 +1,212 @@
+// The `--check` tracked/untracked mode table for the roadmap dashboard.
+//
+// Extracted from `update_roadmap_progress.ts` so the verdict is a pure function
+// over observable state — the generator does the I/O, this decides. It also
+// keeps that script under its per-file size cap.
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+
+/**
+ * Is the dashboard expected to be a committed artefact? Explicit, never
+ * inferred from git state — an unconditional "absent means pass" cannot tell a
+ * correctly-untracked repo from a generator that silently stopped producing
+ * output. `tracked` is the default and the historical behaviour.
+ */
+export type DashboardMode = 'tracked' | 'untracked';
+
+/**
+ * Is `abs` in the git index? Used only by `--check --untracked-mode`, to tell
+ * "correctly absent" from "still committed". No git at all answers `false`,
+ * which is correct: nothing is tracked there.
+ */
+export function isTrackedInGit(abs: string, repo_root: string): boolean {
+    const r = spawnSync('git', ['ls-files', '--error-unmatch', '--', abs], {
+        cwd: repo_root,
+        encoding: 'utf-8',
+        timeout: 10_000,
+    });
+    return r.status === 0;
+}
+
+export interface DashboardStateInput {
+    mode: DashboardMode;
+    /** Is the file on disk? */
+    present: boolean;
+    /** Is the file in the git index? Only consulted in `untracked` mode. */
+    trackedInGit: boolean;
+    /** Does the on-disk content equal a fresh render? Only meaningful if present. */
+    current: boolean;
+    /** Repo-relative path, for the messages. */
+    rel: string;
+    /**
+     * How to regenerate, for the stale/missing messages. Defaults to the
+     * dashboard's own command. A second caller — `build_archive_index --check`
+     * — reuses this table for a different generated artefact, and a message
+     * telling that reader to run the dashboard generator would be wrong.
+     */
+    regen?: string;
+    /**
+     * What the artefact is called in the "deliberately does not commit the X"
+     * hint. Defaults to `dashboard` so every existing message is byte-identical.
+     */
+    noun?: string;
+}
+
+export interface DashboardStateVerdict {
+    /** True when the dashboard half of `--check` fails. */
+    stale: boolean;
+    /** Diagnostic for stderr, or null. */
+    error: string | null;
+    /** Success line for stdout, or null when `stale`. */
+    ok: string | null;
+}
+
+// The SOURCE path, not `.augment/scripts/…`: that tree is a gitignored
+// projection built by `task sync`, so the advice failed outright in a fresh
+// worktree and in any CI step ordered before the sync.
+const REGEN =
+    'Run `./scripts-run src/agent-src/scripts/update_roadmap_progress` ' +
+    'to regenerate (or `task roadmap-progress` in Taskfile projects).';
+
+/**
+ * The mode table:
+ *
+ *   tracked:   absent -> fail | present+stale -> fail | present+current -> pass
+ *   untracked: in-index -> fail | absent -> pass | present+stale -> fail
+ *              | present+current -> pass
+ *
+ * Absence is distinguished ONLY in untracked mode; a present file is
+ * freshness-checked in both, so untracked never means unchecked.
+ */
+export function evaluateDashboardState(inp: DashboardStateInput): DashboardStateVerdict {
+    const { mode, present, trackedInGit, current, rel } = inp;
+    const regen = inp.regen ?? REGEN;
+    const noun = inp.noun ?? 'dashboard';
+
+    if (mode === 'untracked' && trackedInGit) {
+        // Migration incomplete: declared untracked, still carried by git.
+        // Print the fix; never run it — git-index ops are the user's.
+        return {
+            stale: true,
+            error:
+                `❌  ${rel} is still tracked by git, but this repository runs ` +
+                '`--untracked-mode`. Untrack it, keeping the working-tree file:\n' +
+                `      git rm --cached ${rel}\n`,
+            ok: null,
+        };
+    }
+
+    if (!present) {
+        if (mode === 'tracked') {
+            return {
+                stale: true,
+                error:
+                    `❌  ${rel} is missing. ` +
+                    regen.replace('to regenerate', 'to generate it') +
+                    ' If this repository deliberately does not commit the ' +
+                    `${noun}, pass \`--untracked-mode\`.\n`,
+                ok: null,
+            };
+        }
+        // untracked + absent: the declared state. "up to date" would mislead.
+        return {
+            stale: false,
+            error: null,
+            ok: `✅  ${rel} is not committed here (--untracked-mode) and no stale copy is on disk.\n`,
+        };
+    }
+
+    if (!current) {
+        return { stale: true, error: `❌  ${rel} is stale. ${regen}\n`, ok: null };
+    }
+    return { stale: false, error: null, ok: `✅  ${rel} is up to date.\n` };
+}
+
+/**
+ * `evaluateDashboardState` against the real filesystem and git index. The
+ * generator hands over the paths; every read the verdict needs happens here, so
+ * the caller's check branch stays three lines.
+ */
+export function evaluateDashboardOnDisk(opts: {
+    mode: DashboardMode;
+    target: string;
+    repo_root: string;
+    rendered: string;
+    rel: string;
+    regen?: string;
+    noun?: string;
+}): DashboardStateVerdict {
+    const present = fs.existsSync(opts.target);
+    return evaluateDashboardState({
+        mode: opts.mode,
+        present,
+        trackedInGit: opts.mode === 'untracked' && isTrackedInGit(opts.target, opts.repo_root),
+        current: present && fs.readFileSync(opts.target, { encoding: 'utf-8' }) === opts.rendered,
+        rel: opts.rel,
+        ...(opts.regen === undefined ? {} : { regen: opts.regen }),
+        ...(opts.noun === undefined ? {} : { noun: opts.noun }),
+    });
+}
+
+/** One roadmap row, as far as the estate report below needs it. */
+export interface EstateRow {
+    rel: string;
+    done: number;
+    total_active: number;
+    deferred: number;
+}
+
+/**
+ * The `--check` report: the artefact's own verdict, then the estate-wide
+ * conditions — completed-but-unarchived, and Iron Law 3 deferred items.
+ *
+ * `dashboardOnly` drops the estate half. Two obligations with two blast radii:
+ * the artefact verdict is about ONE file and is safe behind a required status
+ * check, while the estate conditions are about roadmaps an unrelated change
+ * never touched, so requiring them turns any pre-existing estate defect into a
+ * merge block on every PR. It did, on 2026-08-22.
+ *
+ * Extracted from the generator so the report is a pure function of the verdict
+ * and two lists — and because the generator sits exactly on its 1500-line
+ * source ceiling, where the honest way to add a feature is to take lines out.
+ */
+export function reportCheckVerdict(inp: {
+    verdict: DashboardStateVerdict;
+    complete: readonly EstateRow[];
+    pending: readonly EstateRow[];
+    dashboardOnly: boolean;
+    warnMergeGated: () => void;
+    gatedCount: number;
+}): { rc: number; stdout: string; stderr: string } {
+    const { verdict, dashboardOnly } = inp;
+    const complete = dashboardOnly ? [] : inp.complete;
+    const pending = dashboardOnly ? [] : inp.pending;
+    let err = verdict.error ?? '';
+    if (complete.length) {
+        err +=
+            '❌  Completed roadmaps are still in `agents/roadmaps/` — ' +
+            'move them to `agents/roadmaps/archive/` (per the ' +
+            '`roadmap-progress-sync` rule):\n';
+        for (const r of complete) err += `      - ${r.rel}  (${r.done}/${r.total_active} done)\n`;
+    }
+    if (pending.length) {
+        err +=
+            '❌  Iron Law 3 — roadmaps with unresolved `[~]` deferred ' +
+            'items must NOT auto-archive. Resolve via `roadmap-management § 4b` ' +
+            '(spawn follow-up, restore, or cancel):\n';
+        for (const r of pending) {
+            err += `      - ${r.rel}  (${r.done}/${r.total_active} done · ${r.deferred} deferred)\n`;
+        }
+    }
+    if (!dashboardOnly && inp.gatedCount > 0) inp.warnMergeGated();
+    const rc = verdict.stale || complete.length > 0 || pending.length > 0 ? 1 : 0;
+    return { rc, stdout: rc === 0 ? (verdict.ok ?? '') : '', stderr: err };
+}
+
+/** `--tracked-mode` / `--untracked-mode` → the mode, or null for any other token. */
+export function parseModeToken(tok: string): DashboardMode | null {
+    if (tok === '--tracked-mode') return 'tracked';
+    if (tok === '--untracked-mode') return 'untracked';
+    return null;
+}

package/src/agent-src/scripts/gate_budget.ts

@@ -0,0 +1,282 @@
+/**
+ * gate_budget — the class-1 spend bound and its append-only receipt ledger
+ * (`road-to-gate-autonomy` Phase 2, blocker `b-gate-budget-preauth`).
+ *
+ * WHY THIS EXISTS. Class 1 of the gate taxonomy is "billable or long-running
+ * but reversible; the human ingredient is *spend consent*, not judgment".
+ * `gate_execute.ts` shipped without it on purpose — "no invented ledger",
+ * because the budget SHAPE was an open maintainer decision. That decision is
+ * now taken (option (a): a per-run cap AND a rolling-window cap, with an
+ * append-only receipt ledger as the audit surface), so this module supplies
+ * exactly the shape that was decided and nothing more.
+ *
+ * WHAT THIS IS NOT. It is **not** a consent bypass. `gates --execute` still
+ * requires `--confirm` on every class-1 run, so the this-turn,
+ * names-the-exact-object confirmation `non-destructive-by-default` asks for is
+ * unchanged. The caps bound the SIZE of an authorised spend; they never
+ * manufacture the authorisation. A ledger under `agents/runtime/state/` is
+ * agent-writable, so a mechanism that read an "authorisation" out of it would
+ * be an agent consenting on the user's behalf — which is precisely the threat
+ * model the live-trigger-eval terminal abort exists for. That is why the
+ * receipt records CONSUMPTION only, and why step 2.3's bypass flag is not
+ * built on top of this file.
+ *
+ * A per-run cap alone is not a spend bound — it bounds one mistake, not a week
+ * of them — which is the whole reason the decision carries two numbers.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * Ledger location, relative to the workspace root.
+ *
+ * The name is the one already present in `gate_execute.ts` as the
+ * absent-ledger placeholder, kept verbatim so the path a class-1 entry has
+ * been REPORTING since Phase 2 is the path it now reads. `agents/runtime/state/`
+ * is this tree's state convention (`run_checkpoint`, `unattended_guard`,
+ * `recycle_envelope_paths` all live there); a bare `agents/state/` is not.
+ */
+export const GATE_BUDGET_LEDGER_REL = path.join(
+    'agents',
+    'runtime',
+    'state',
+    'gate-budget-ledger.jsonl',
+);
+
+/**
+ * Build the absolute ledger path.
+ *
+ * Callers import THIS rather than joining {@link GATE_BUDGET_LEDGER_REL}
+ * themselves: a bare relative constant is the shape that goes silently dead
+ * when the location moves, because nothing joins it any more and nothing
+ * complains.
+ */
+export function gateBudgetLedgerPath(workspaceRoot: string): string {
+    return path.join(workspaceRoot, GATE_BUDGET_LEDGER_REL);
+}
+
+/** The two caps decided by option (a). Both are USD. */
+export interface GateBudgetCaps {
+    maxCostPerRunUsd: number;
+    maxCostPerRolling7dUsd: number;
+}
+
+/**
+ * One append-only ledger line.
+ *
+ * The five fields the decision names — blocker, authorization, estimated and
+ * actual cost, timestamp — plus the single-use marker. `authorization` records
+ * HOW the spend was consented to; today the only value a run can honestly
+ * write is `confirm-flag`, because `--confirm` is the consent. A future
+ * human-only authorisation surface would add its own value here rather than
+ * reinterpreting this one.
+ */
+export interface GateBudgetReceipt {
+    kind: 'consumption';
+    blocker: string;
+    authorization: 'confirm-flag';
+    estimated_usd: number;
+    actual_usd: number | null;
+    at: string;
+    single_use: true;
+}
+
+/** Rolling window, in days, that `maxCostPerRolling7dUsd` bounds. */
+export const ROLLING_WINDOW_DAYS = 7;
+
+function _num(value: unknown): number | null {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    return null;
+}
+
+function _dig(settings: unknown, keys: readonly string[]): unknown {
+    let cursor: unknown = settings;
+    for (const k of keys) {
+        if (cursor === null || typeof cursor !== 'object' || Array.isArray(cursor)) {
+            return undefined;
+        }
+        cursor = (cursor as Record<string, unknown>)[k];
+    }
+    return cursor;
+}
+
+/**
+ * Read the caps out of an already-merged settings dict.
+ *
+ * Returns `null` when either cap is absent or non-numeric — deliberately NOT a
+ * fallback to the template numbers. An install whose settings do not carry the
+ * caps has not authorised a standing budget, and inventing one from the
+ * template default would authorise spend nobody configured. The caller renders
+ * the consent line instead.
+ */
+export function readGateBudgetCaps(settings: unknown): GateBudgetCaps | null {
+    const perRun = _num(_dig(settings, ['roadmap', 'gate_budget', 'max_cost_per_run_usd']));
+    const rolling = _num(
+        _dig(settings, ['roadmap', 'gate_budget', 'max_cost_per_rolling_7d_usd']),
+    );
+    if (perRun === null || rolling === null) {
+        return null;
+    }
+    return { maxCostPerRunUsd: perRun, maxCostPerRolling7dUsd: rolling };
+}
+
+/**
+ * Parse a USD figure out of a blocker's `Budget:` field.
+ *
+ * An explicit currency marker (`$` or `USD`) is REQUIRED. Without it a field
+ * like "~50 queries per run" would be read as fifty dollars, and a spend bound
+ * derived from a misread is worse than no bound: it would let a large run
+ * through under a small number. Returns `null` when no USD figure is stated.
+ */
+export function parseBudgetUsd(field: string): number | null {
+    const text = field.trim();
+    if (text === '') {
+        return null;
+    }
+    const dollar = /\$\s*([0-9]+(?:[.,][0-9]+)?)/.exec(text);
+    if (dollar) {
+        return Number.parseFloat(dollar[1]!.replace(',', '.'));
+    }
+    const usd = /([0-9]+(?:[.,][0-9]+)?)\s*(?:usd|dollars?)\b/i.exec(text);
+    if (usd) {
+        return Number.parseFloat(usd[1]!.replace(',', '.'));
+    }
+    return null;
+}
+
+/** Read every well-formed receipt. A malformed line is skipped, never fatal. */
+export function readGateBudgetLedger(workspaceRoot: string): GateBudgetReceipt[] {
+    const file = gateBudgetLedgerPath(workspaceRoot);
+    if (!fs.existsSync(file)) {
+        return [];
+    }
+    const out: GateBudgetReceipt[] = [];
+    for (const line of fs.readFileSync(file, 'utf-8').split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed === '') {
+            continue;
+        }
+        let parsed: unknown;
+        try {
+            parsed = JSON.parse(trimmed);
+        } catch {
+            continue;
+        }
+        if (parsed === null || typeof parsed !== 'object') {
+            continue;
+        }
+        const rec = parsed as Record<string, unknown>;
+        if (rec['kind'] !== 'consumption' || typeof rec['blocker'] !== 'string') {
+            continue;
+        }
+        out.push({
+            kind: 'consumption',
+            blocker: rec['blocker'],
+            authorization: 'confirm-flag',
+            estimated_usd: _num(rec['estimated_usd']) ?? 0,
+            actual_usd: _num(rec['actual_usd']),
+            at: typeof rec['at'] === 'string' ? rec['at'] : '',
+            single_use: true,
+        });
+    }
+    return out;
+}
+
+/** Append one receipt. Append-only by construction — nothing here rewrites. */
+export function appendGateBudgetReceipt(
+    workspaceRoot: string,
+    receipt: GateBudgetReceipt,
+): void {
+    const file = gateBudgetLedgerPath(workspaceRoot);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.appendFileSync(file, `${JSON.stringify(receipt)}\n`, 'utf-8');
+}
+
+/**
+ * Spend inside the rolling window.
+ *
+ * `actual_usd` when the run reported one, the estimate otherwise — an
+ * unreported actual must not read as zero spend. A receipt with an unparseable
+ * timestamp counts as IN the window, because dropping it would understate the
+ * total and the cap is meant to fail closed.
+ */
+export function rollingSpendUsd(records: readonly GateBudgetReceipt[], now: Date): number {
+    const cutoff = now.getTime() - ROLLING_WINDOW_DAYS * 24 * 60 * 60 * 1000;
+    let total = 0;
+    for (const r of records) {
+        const stamp = Date.parse(r.at);
+        if (Number.isFinite(stamp) && stamp < cutoff) {
+            continue;
+        }
+        total += r.actual_usd ?? r.estimated_usd;
+    }
+    return total;
+}
+
+export type GateBudgetRefusal =
+    | 'no_caps'
+    | 'no_estimate'
+    | 'over_per_run'
+    | 'over_rolling_7d';
+
+export type GateBudgetVerdict =
+    | { ok: true; estimateUsd: number; rollingUsd: number }
+    | { ok: false; reason: GateBudgetRefusal; detail: string };
+
+/**
+ * Decide whether a class-1 run fits inside the standing budget.
+ *
+ * Every refusal path renders rather than runs — the blocker's own prescription
+ * for a missing ledger, generalised to every way the budget can say no.
+ */
+export function evaluateGateBudget(opts: {
+    caps: GateBudgetCaps | null;
+    records: readonly GateBudgetReceipt[];
+    estimateUsd: number | null;
+    now: Date;
+}): GateBudgetVerdict {
+    const { caps, records, estimateUsd, now } = opts;
+    if (caps === null) {
+        return {
+            ok: false,
+            reason: 'no_caps',
+            detail:
+                'no standing class-1 budget is configured ' +
+                '(`roadmap.gate_budget.max_cost_per_run_usd` and ' +
+                '`roadmap.gate_budget.max_cost_per_rolling_7d_usd`)',
+        };
+    }
+    if (estimateUsd === null) {
+        return {
+            ok: false,
+            reason: 'no_estimate',
+            detail:
+                'the entry states no USD estimate in its **Budget:** field, so no cap ' +
+                'can be compared against it',
+        };
+    }
+    if (estimateUsd > caps.maxCostPerRunUsd) {
+        return {
+            ok: false,
+            reason: 'over_per_run',
+            detail:
+                `the estimate ($${estimateUsd.toFixed(2)}) exceeds the per-run cap ` +
+                `($${caps.maxCostPerRunUsd.toFixed(2)})`,
+        };
+    }
+    const spent = rollingSpendUsd(records, now);
+    if (spent + estimateUsd > caps.maxCostPerRolling7dUsd) {
+        return {
+            ok: false,
+            reason: 'over_rolling_7d',
+            detail:
+                `$${spent.toFixed(2)} is already receipted in the last ` +
+                `${String(ROLLING_WINDOW_DAYS)} days and this run would add ` +
+                `$${estimateUsd.toFixed(2)}, over the rolling cap ` +
+                `($${caps.maxCostPerRolling7dUsd.toFixed(2)})`,
+        };
+    }
+    return { ok: true, estimateUsd, rollingUsd: spent };
+}

package/src/agent-src/scripts/gate_execute.ts

@@ -22,11 +22,17 @@
  *     instead of one entry.
  *   - **No resolve on failure.** A non-zero exit reports and changes nothing.
  *     A gate marked resolved by a command that failed is worse than an open one.
- *   - **No invented ledger.** Class 1 needs a standing budget, and the shape of
- *     that budget is an OPEN maintainer decision (`b-gate-budget-preauth`).
- *     Until it is taken there is no ledger, so class 1 takes the
- *     render-instead-of-run path — which is the behaviour the blocker itself
- *     prescribes for a missing ledger, not a stub of the decision.
+ *   - **No spend outside the standing budget.** Class 1 runs only under the
+ *     caps `b-gate-budget-preauth` decided (option (a), 2026-08-20): a per-run
+ *     cap AND a rolling-7-day cap, with an append-only receipt as the audit
+ *     surface. No caps configured, no USD estimate in the entry, over either
+ *     cap — every one of those RENDERS instead of running, which is the
+ *     behaviour the blocker itself prescribes for a missing ledger.
+ *   - **No consent from the ledger.** The receipt records CONSUMPTION only.
+ *     `agents/runtime/state/` is agent-writable, so reading an "authorisation"
+ *     out of it would be the agent consenting on the user's behalf — the exact
+ *     threat model the live-trigger-eval terminal abort exists for. `--confirm`
+ *     remains the consent on every class-1 run.
  *   - **No class-3 change.** The class-3 branch executes nothing and writes
  *     nothing, so `agent-config gates` renders a class-3 entry exactly as it did
  *     before this module existed. `--execute` on one returns a one-line notice
@@ -35,8 +41,9 @@
  *     markdown field. Without the flag the command is echoed and refused, so
  *     the operator sees the exact string first — the this-turn, names-the-object
  *     confirmation `non-destructive-by-default` requires. A command carrying a
- *     Hard-Floor action is refused even WITH the flag: class 0 means reversible,
- *     so such an entry is misclassified rather than merely dangerous.
+ *     Hard-Floor action is refused even WITH the flag: classes 0 and 1 are both
+ *     defined as reversible, so such an entry is misclassified rather than
+ *     merely dangerous.
  */
 
 import * as fs from 'node:fs';
@@ -44,15 +51,24 @@ import * as path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
 import { collect, blocker_class, type Blocker } from './update_roadmap_progress.js';
+import {
+    appendGateBudgetReceipt,
+    evaluateGateBudget,
+    GATE_BUDGET_LEDGER_REL,
+    parseBudgetUsd,
+    readGateBudgetCaps,
+    readGateBudgetLedger,
+} from './gate_budget.js';
+import { load_agent_settings } from '../templates/scripts/work_engine/_lib/agent_settings.js';
 
 /**
- * Where a class-1 receipt ledger would live once the budget decision is taken.
+ * Where the class-1 receipt ledger lives.
  *
- * Named here so the absent-ledger branch has something concrete to report, and
- * deliberately NOT created: the path is a consequence of the decision, and
- * writing it now would answer a question that is still the maintainer's.
+ * Kept as a name here because it was already exported, but the definition
+ * moved to `gate_budget.ts` when the budget decision landed — one path, one
+ * builder, so a relocation cannot leave a second joiner behind.
  */
-const LEDGER_REL = path.join('agents', 'runtime', 'state', 'gate-budget-ledger.jsonl');
+const LEDGER_REL = GATE_BUDGET_LEDGER_REL;
 
 type Outcome = 'resolved' | 'failed' | 'rendered' | 'not-found';
 
@@ -260,6 +276,7 @@ function execute(
     }
     const { blocker, file, rel } = found;
     const cls = blocker_class(blocker);
+    const repoRoot = path.dirname(path.dirname(roadmapRoot));
 
     if (cls === '3') {
         // Byte-identical to today by construction: nothing is executed and
@@ -273,28 +290,32 @@ function execute(
     if (cls === '2') {
         return { outcome: 'rendered', report: consentLine(blocker), code: 0 };
     }
+    // Class 1 runs under the standing budget decided by `b-gate-budget-preauth`
+    // option (a): a per-run cap AND a rolling-7-day cap, with an append-only
+    // receipt as the audit surface. Every refusal path RENDERS rather than
+    // running — the blocker's own prescription for a missing ledger,
+    // generalised to every way the budget can say no. The `--confirm`
+    // requirement below is untouched: the caps bound the size of an authorised
+    // spend, they never supply the authorisation.
+    let budgeted: { estimateUsd: number } | null = null;
     if (cls === '1') {
-        const ledger = path.join(path.dirname(path.dirname(roadmapRoot)), LEDGER_REL);
-        if (!fs.existsSync(ledger)) {
-            // The blocker's own prescription for a missing ledger: render the
-            // consent line INSTEAD of running. Not a degraded mode — the
-            // budget shape is an open decision and this is what open means.
+        const verdict = evaluateGateBudget({
+            caps: readGateBudgetCaps(load_agent_settings({ cwd: repoRoot })),
+            records: readGateBudgetLedger(repoRoot),
+            estimateUsd: parseBudgetUsd(blocker.budget),
+            now,
+        });
+        if (!verdict.ok) {
             return {
                 outcome: 'rendered',
                 report: consentLine(
                     blocker,
-                    'class 1 with no budget ledger, so it renders instead of running',
+                    `class 1 and ${verdict.detail}, so it renders instead of running`,
                 ),
                 code: 0,
             };
         }
-        return {
-            outcome: 'rendered',
-            report:
-                `${id} is class 1 and a ledger exists at ${LEDGER_REL}, but spend execution ` +
-                'is gated on `b-gate-budget-preauth`, which is open. Rendering instead of running.\n',
-            code: 0,
-        };
+        budgeted = { estimateUsd: verdict.estimateUsd };
     }
 
     const command = commandOf(blocker);
@@ -304,7 +325,7 @@ function execute(
         // and guessing a command here is the one thing that must not happen.
         return {
             outcome: 'failed',
-            report: `${id} is class 0 but carries no **Run:** command. Nothing was executed.\n`,
+            report: `${id} is class ${cls} but carries no **Run:** command. Nothing was executed.\n`,
             code: 1,
         };
     }
@@ -318,9 +339,9 @@ function execute(
         return {
             outcome: 'failed',
             report:
-                `${id} is class 0 but its **Run:** command contains \`${floor}\`, which is a ` +
-                'Hard-Floor action under non-destructive-by-default. Class 0 means ' +
-                'deterministic, free and REVERSIBLE, so this entry is misclassified. ' +
+                `${id} is class ${cls} but its **Run:** command contains \`${floor}\`, which is a ` +
+                'Hard-Floor action under non-destructive-by-default. Classes 0 and 1 are ' +
+                'both defined as REVERSIBLE, so this entry is misclassified. ' +
                 'Nothing was executed; re-author the class.\n',
             code: 1,
         };
@@ -333,7 +354,7 @@ function execute(
         return {
             outcome: 'rendered',
             report:
-                `${id} is class 0 and would run, from the repo root:\n\n` +
+                `${id} is class ${cls} and would run, from the repo root:\n\n` +
                 `    ${command}\n\n` +
                 'Nothing has been executed. Re-run with `--confirm` to execute it and ' +
                 'record the evidence at the blocker.\n',
@@ -344,7 +365,7 @@ function execute(
     const r = spawnSync(command, {
         shell: true,
         encoding: 'utf-8',
-        cwd: path.dirname(path.dirname(roadmapRoot)),
+        cwd: repoRoot,
         timeout: 120_000,
     });
     const output = `${r.stdout ?? ''}${r.stderr ?? ''}`;
@@ -367,6 +388,22 @@ function execute(
             code: 1,
         };
     }
+    if (budgeted !== null) {
+        // Written BEFORE the file rewrite: an unreceipted spend is invisible to
+        // the rolling cap, and the cap failing open is the one way this
+        // mechanism could become a blank cheque. `actual_usd` is null because
+        // nothing on this path observes the provider's billed amount — the
+        // estimate is what the cap compared against and what it records.
+        appendGateBudgetReceipt(repoRoot, {
+            kind: 'consumption',
+            blocker: id,
+            authorization: 'confirm-flag',
+            estimated_usd: budgeted.estimateUsd,
+            actual_usd: null,
+            at: now.toISOString(),
+            single_use: true,
+        });
+    }
     const when = today(now);
     if (!appendEvidence(file, id, command, output, when)) {
         return {
@@ -382,6 +419,10 @@ function execute(
         report:
             `${id} resolved. Ran \`${command}\` (exit 0); evidence appended in ${rel} ` +
             `and the status flipped to resolved ${when}.\n` +
+            (budgeted === null
+                ? ''
+                : `Receipt appended to ${LEDGER_REL} ` +
+                  `($${budgeted.estimateUsd.toFixed(2)} estimated).\n`) +
             // The dashboard is derived from the file this just rewrote, so it
             // is now stale. Saying so is the same follow-up `renderResumed`
             // already prints for its own file-move suggestion.