@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/engine/lifecycle.js

@@ -0,0 +1,656 @@
+/**
+ * Run lifecycle: start, resume, close, abandon, resolve, status (governance-mode 7.2, 8.4).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * Every function here answers with plain text that begins `OK:` / `NOT ACCEPTED:` /
+ * `ESCALATION:` and ends with `NEXT:` (D-16, 14.5). A refusal is a normal tool RESULT, never
+ * an error: an error result invites an identical retry, a result that says what to do
+ * instead does not.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { GOV_LIMITS, GOV_SCHEMA_VERSION } from '../limits.js';
+import { formatDispatchEstimate, formatDispatchPlanForAgent } from '../copy.js';
+import { rosterIds, rosterSizes } from '../roles.js';
+import { createLedger } from '../rules/ledger-state.js';
+import { formatNotAccepted, isRecord, Issues } from '../tools/normalize-util.js';
+import { newRunUsage, shouldStopNewStages } from './budget.js';
+import { charterCard, escalationCard, finalCard } from './cards.js';
+import { composeDigest, refusal } from './digest.js';
+import { estimateDispatches, estimateForRun } from './estimate.js';
+import { planPhases } from './phase-planner.js';
+import { recoverInterruptedStage, replayCheckpoints } from './rebuild.js';
+import { buildBoardMarkdown, buildFinalReport, renderPhases, renderWpTable, } from './report.js';
+import { applyResolveDisposition, canClose, closeEscalation, nextEscalationId, } from './state-machine.js';
+import { normalizeStartInput } from './start-input.js';
+export const BUDGET_TOPIC_PREFIX = 'Team token budget';
+const LIVE_STATUSES = new Set([
+    'executing',
+    'escalated',
+    'paused',
+]);
+// ---------------------------------------------------------------------------
+// start
+// ---------------------------------------------------------------------------
+/** `package.json` `scripts.test` -> `npm test`, so a run without commands can still verify. */
+async function inferIntegrationCommands(cwd) {
+    try {
+        const text = await readFile(join(cwd, 'package.json'), 'utf8');
+        const parsed = JSON.parse(text);
+        const scripts = isRecord(parsed) && isRecord(parsed.scripts) ? parsed.scripts : {};
+        return typeof scripts.test === 'string' && scripts.test.trim() !== '' ? ['npm test'] : [];
+    }
+    catch {
+        return [];
+    }
+}
+function composeSpec(plan, addendum) {
+    const parts = [];
+    if (plan !== null && plan.trim() !== '')
+        parts.push(plan.trim());
+    if (addendum.trim() !== '') {
+        parts.push(plan ? `## Orchestrator addendum\n${addendum.trim()}` : addendum.trim());
+    }
+    const joined = parts.join('\n\n');
+    return joined.length > GOV_LIMITS.specChars
+        ? `${joined.slice(0, GOV_LIMITS.specChars - 12)}\n[truncated]`
+        : joined;
+}
+function buildCharterInput(input, charter) {
+    const { ceiling: teamCeiling, commands: cmds, plan } = charter;
+    const wps = input.workPackages;
+    const files = [...new Set(wps.flatMap((w) => w.files))];
+    const risks = [
+        ...(input.contracts ?? []).map((c) => `Contract ${c.id} ${c.name}: ${c.definition}`),
+        ...cmds.map((c) => `Integration command (the inspector may run it): ${c}`),
+    ];
+    return {
+        title: input.goal,
+        summary: `${wps.length} work package(s), one DEV agent each plus reviewers, testers and one ` +
+            `inspector; stage width <= ${teamCeiling}.${plan === '' ? '' : ` ${plan}`}`,
+        steps: wps.map((w) => ({
+            title: `${w.id}: ${w.title}`,
+            detail: `${w.goal}\nFiles: ${w.files.join(', ') || '(none)'}\n` +
+                `Acceptance: ${w.acceptance.join('; ')}` +
+                (w.dependsOn && w.dependsOn.length > 0 ? `\nDepends on: ${w.dependsOn.join(', ')}` : ''),
+        })),
+        filesTouched: files,
+        risks,
+    };
+}
+function makeWorkPackages(input, phaseOf) {
+    const out = {};
+    input.workPackages.forEach((w, index) => {
+        out[w.id] = {
+            id: w.id,
+            title: w.title,
+            goal: w.goal,
+            files: w.files,
+            acceptance: w.acceptance,
+            dependsOn: w.dependsOn ?? [],
+            phase: phaseOf[w.id] ?? 0,
+            assignee: `dev${index + 1}`,
+            reviewer: null,
+            tester: null,
+            status: 'pending',
+            reworkCount: 0,
+            rejections: [],
+            appealUsed: false,
+            submissions: { dev: [], review: [], test: [], settle: [], integrate: [], fix: [] },
+            reworkGrants: 0,
+            acceptedWithIssues: false,
+        };
+    });
+    return out;
+}
+function makePhase(index, wpIds) {
+    return {
+        index,
+        wpIds,
+        settled: false,
+        integrated: false,
+        integrationAttempts: 0,
+        fixCycles: 0,
+        extraFixGrants: 0,
+        integrationAccepted: true,
+        lastIntegrationFailed: false,
+    };
+}
+async function refuseStartReasons(core) {
+    if (core.readOnly)
+        return 'this session cannot write governance records (newer format).';
+    const existing = core.run;
+    if (existing !== null && LIVE_STATUSES.has(existing.status)) {
+        return (`run ${existing.runId} is still ${existing.status}. Finish it with gov_run close, ` +
+            'stop it with gov_run abandon, or continue it (gov_run status / resume).');
+    }
+    if (!core.deps.hasApiKey()) {
+        return 'no model API key is available, so a team cannot run. Configure one and retry.';
+    }
+    return null;
+}
+function startDigest(core, notes, chunkNote) {
+    const run = core.requireRun();
+    const agents = Object.keys(core.ledger.agents).length;
+    const plan = formatDispatchPlanForAgent(estimateForRun(run, core.deps.getTeamCeiling()));
+    const results = [
+        renderPhases(run),
+        ...(plan === '' ? [] : [plan]),
+        ...(chunkNote ? [chunkNote] : []),
+    ];
+    return composeDigest(core, {
+        headline: `OK: run ${run.runId} started. ${run.wpOrder.length} work package(s) in ` +
+            `${run.phases.length} phase(s); ${agents} scored agents + 1 inspector ` +
+            `(profile ${run.profile}).`,
+        results,
+        warnings: notes.map((n) => `NOTE: ${n}`),
+        standings: true,
+    });
+}
+/** `gov_run start`. Creates nothing unless every check passes (7.2). */
+export async function startRun(core, raw, signal) {
+    const refused = await refuseStartReasons(core);
+    if (refused !== null)
+        return refusal(core, refused);
+    const normalized = normalizeStartInput(raw);
+    if (!normalized.ok)
+        return formatNotAccepted('gov_run start', normalized.errors);
+    const input = normalized.value;
+    const notes = [...normalized.notes];
+    const cfg = core.config();
+    const ceiling = core.deps.getTeamCeiling();
+    const planned = planPhases({
+        workPackages: input.workPackages,
+        ...(input.contracts ? { contracts: input.contracts } : {}),
+        config: {
+            maxWorkPackages: cfg.maxWorkPackages,
+            maxPhases: cfg.maxPhases,
+            teamCeiling: ceiling,
+        },
+    });
+    if (!planned.ok)
+        return formatNotAccepted('gov_run start', planned.errors);
+    notes.push(...planned.notes);
+    // PEEK, never take: a refused start must not lose the approved plan the user is waiting on.
+    const peeked = core.deps.peekApprovedPlan?.() ?? null;
+    if (input.spec.trim() === '' && (peeked === null || peeked.trim() === '')) {
+        return formatNotAccepted('gov_run start', [
+            'spec is required: pass the user requirement (or the approved plan) verbatim.',
+        ]);
+    }
+    let commands = input.integrationCommands ?? [];
+    if (commands.length === 0) {
+        commands = await inferIntegrationCommands(core.deps.getCwd());
+        if (commands.length > 0) {
+            notes.push(`integration command inferred from package.json: ${commands[0]}`);
+        }
+    }
+    const plan = formatDispatchEstimate(estimateDispatches({
+        phaseWpCounts: planned.phases.map((phase) => phase.wpIds.length),
+        teamCeiling: ceiling,
+    }));
+    const confirmation = await confirmCharter(core, input, { ceiling, commands, plan }, signal);
+    if (confirmation !== null)
+        return refusal(core, confirmation);
+    return createRun(core, {
+        input,
+        commands,
+        planned: planned.phases,
+        phaseOf: planned.phaseOf,
+        notes,
+    });
+}
+async function confirmCharter(core, input, charter, signal) {
+    const cfg = core.config();
+    const confirm = core.deps.confirmCharter;
+    if (!cfg.confirmCharter || confirm === undefined)
+        return null;
+    const answer = await confirm(buildCharterInput(input, charter), signal);
+    if (answer === null || answer.decision === 'dismissed') {
+        return 'the user declined the charter; the posture stays GOVERN. Ask what they want changed.';
+    }
+    if (answer.decision === 'revise') {
+        return `the user asked for changes before the run starts: ${answer.feedback ?? '(no details)'}`;
+    }
+    return null;
+}
+function buildRunState(core, c, runId, plan) {
+    const { input } = c;
+    const cfg = core.config();
+    const now = core.now();
+    const sessionId = core.deps.getSessionId();
+    return {
+        schemaVersion: GOV_SCHEMA_VERSION,
+        runId,
+        cwd: core.deps.getCwd(),
+        ...(sessionId !== undefined ? { sessionId } : {}),
+        goal: input.goal,
+        profile: (input.profile ?? cfg.profile),
+        status: 'executing',
+        createdAt: now,
+        updatedAt: now,
+        phases: c.planned.map((p) => makePhase(p.index, p.wpIds)),
+        workPackages: makeWorkPackages(input, c.phaseOf),
+        wpOrder: input.workPackages.map((w) => w.id),
+        contracts: (input.contracts ?? []).map((x) => ({ ...x })),
+        integrationCommands: c.commands,
+        claims: [],
+        escalations: [],
+        stage: null,
+        usage: newRunUsage(),
+        dispatches: 0,
+        seq: 0,
+        ...(plan !== null ? { planSnapshot: plan } : {}),
+        limits: {
+            maxRework: Math.min(cfg.maxRework, GOV_LIMITS.hardMaxRework),
+            maxFixCycles: Math.min(cfg.maxFixCycles, GOV_LIMITS.hardMaxFixCycles),
+            budgetTokens: cfg.budgetTokens,
+        },
+    };
+}
+/** Reset every per-run field of the core and wire it to the new run. */
+function adoptRun(core, run) {
+    core.run = run;
+    core.seq = 0;
+    core.pauseRequested = false;
+    core.userPaused = false;
+    core.ledger = createLedger([]);
+    core.submissionCache.clear();
+    core.phaseFlags.clear();
+    core.viewRequests.clear();
+    core.resetStageScratch();
+    core.attachTeam();
+}
+async function createRun(core, c) {
+    const store = core.deps.store;
+    const plan = core.deps.takeApprovedPlan?.() ?? null;
+    const spec = composeSpec(plan, c.input.spec);
+    const run = buildRunState(core, c, await store.allocateRunId(), plan);
+    await store.createRun({ state: run, spec });
+    const lock = await store.acquireLock(run.runId);
+    if (!lock.ok)
+        return refusal(core, lock.message);
+    store.startHeartbeat(run.runId);
+    adoptRun(core, run);
+    seedRoster(core, c.input.workPackages.length, core.deps.getTeamCeiling());
+    core.log('run_started', 'engine', {
+        goal: run.goal,
+        profile: run.profile,
+        workPackages: run.wpOrder,
+        phases: run.phases.map((p) => p.wpIds),
+    });
+    core.checkpoint();
+    core.exportScoreboard();
+    core.emit((snapshot) => ({ type: 'run_started', snapshot, card: charterCard(core) }));
+    pruneOnce(core);
+    const ceiling = core.deps.getTeamCeiling();
+    const chunkNote = run.wpOrder.length > ceiling
+        ? `NOTE: stages will be dispatched in chunks of ${ceiling} (team.maxSubagents).`
+        : null;
+    const flushNote = await core.flush();
+    const digest = startDigest(core, c.notes, chunkNote);
+    return flushNote === null ? digest : `${digest}
+${flushNote}`;
+}
+/** DEV per WP in WP order, REV / TEST by `rosterSizes` (5.2). Logged as ledger ops. */
+function seedRoster(core, wpCount, ceiling) {
+    const sizes = rosterSizes(wpCount, ceiling);
+    for (const id of rosterIds('DEV', sizes.dev)) {
+        core.ledgerOp({ op: 'add_agent', spec: { id, role: 'DEV' } });
+    }
+    for (const id of rosterIds('REV', sizes.rev)) {
+        core.ledgerOp({ op: 'add_agent', spec: { id, role: 'REV' } });
+    }
+    for (const id of rosterIds('TEST', sizes.test)) {
+        core.ledgerOp({ op: 'add_agent', spec: { id, role: 'TEST' } });
+    }
+}
+/** Retention prune, once per engine instance, never blocking and never throwing. */
+export function pruneOnce(core) {
+    if (core.pruned)
+        return;
+    core.pruned = true;
+    void core.deps.store.pruneOld().catch(() => undefined);
+}
+// ---------------------------------------------------------------------------
+// resume
+// ---------------------------------------------------------------------------
+async function cacheSubmissions(core, runId) {
+    core.submissionCache.clear();
+    const refs = await core.deps.artifacts.list(runId);
+    for (const ref of refs) {
+        const read = await core.deps.artifacts.read(runId, ref.id);
+        if (read === null || !isRecord(read.json) || typeof read.json.kind !== 'string')
+            continue;
+        core.submissionCache.set(ref.id, read.json);
+    }
+}
+async function loadForResume(core, runId) {
+    const store = core.deps.store;
+    const lock = await store.acquireLock(runId);
+    if (!lock.ok)
+        return { ok: false, message: lock.message };
+    const loaded = await store.load(runId, { replay: replayCheckpoints });
+    const release = async (message) => {
+        await store.releaseLock(runId);
+        return { ok: false, message };
+    };
+    if (loaded.readOnly) {
+        return release(`run ${runId} was written by a newer version of this program and is read-only here. ` +
+            'Update the CLI to resume it.');
+    }
+    if (loaded.eventsUnreadable || loaded.run === null) {
+        return release(`run ${runId} cannot be resumed: its saved state is missing or corrupt ` +
+            `(${loaded.problems.join('; ') || 'no readable records'}). It is left on disk for ` +
+            'inspection. Start a new run with gov_run start.');
+    }
+    if (loaded.run.status === 'closed' || loaded.run.status === 'abandoned') {
+        return release(`run ${runId} is already ${loaded.run.status}; start a new run.`);
+    }
+    core.run = loaded.run;
+    core.pauseRequested = false;
+    core.userPaused = false;
+    core.ledger = loaded.ledger ?? createLedger([]);
+    core.seq = Math.max(loaded.tailSeq, loaded.run.seq);
+    core.phaseFlags.clear();
+    core.viewRequests.clear();
+    core.resetStageScratch();
+    await cacheSubmissions(core, runId);
+    if (loaded.problems.length > 0) {
+        core.stageWarnings.push(`Recovered with notes: ${loaded.problems.join('; ')}`);
+    }
+    store.startHeartbeat(runId);
+    return { ok: true };
+}
+/** Put a paused / interrupted in-memory run back to `executing`. */
+function reactivate(core) {
+    const run = core.requireRun();
+    const reset = recoverInterruptedStage(run);
+    core.pauseRequested = false;
+    core.userPaused = false;
+    if (run.status === 'paused')
+        run.status = 'executing';
+    core.log('run_resumed', 'engine', { reset });
+    core.checkpoint();
+    core.attachTeam();
+    core.emit((snapshot) => ({ type: 'run_resumed', snapshot }));
+}
+/** `gov_run resume`. Only WPs that lack a submission for their stage will be re-run. */
+export async function resumeRun(core, runId) {
+    const current = core.run;
+    if (core.isStageRunning())
+        return refusal(core, 'a stage is running; wait for it to finish.');
+    const sameRun = current !== null && (runId === undefined || runId === current.runId);
+    if (sameRun && current !== null && LIVE_STATUSES.has(current.status)) {
+        if (current.status === 'escalated') {
+            return composeDigest(core, {
+                headline: `ESCALATION: run ${current.runId} is waiting for the user's ruling.`,
+                standings: true,
+            });
+        }
+        if (current.status === 'paused')
+            reactivate(core);
+        pruneOnce(core);
+        return finishResume(core);
+    }
+    const target = runId ?? (await core.deps.store.latestResumable(core.deps.getCwd()))?.runId ?? undefined;
+    if (target === undefined) {
+        return refusal(core, 'there is no unfinished governance run for this directory to resume.');
+    }
+    const loaded = await loadForResume(core, target);
+    if (!loaded.ok)
+        return refusal(core, loaded.message);
+    const run = core.requireRun();
+    run.status = run.status === 'escalated' ? 'escalated' : 'paused';
+    if (run.status === 'paused')
+        reactivate(core);
+    else {
+        core.attachTeam();
+        core.checkpoint();
+    }
+    pruneOnce(core);
+    return finishResume(core);
+}
+async function finishResume(core) {
+    const run = core.requireRun();
+    const warnings = core.stageWarnings.splice(0);
+    const flushNote = await core.flush();
+    const text = composeDigest(core, {
+        headline: `OK: run ${run.runId} resumed (${run.status}). Goal: ${run.goal}`,
+        results: [renderPhases(run), renderWpTable(run)],
+        warnings,
+        standings: true,
+    });
+    return flushNote === null ? text : `${text}\n${flushNote}`;
+}
+// ---------------------------------------------------------------------------
+// status
+// ---------------------------------------------------------------------------
+/** `gov_run status`: the board as text. Rebuildable by a compacted orchestrator (R-11). */
+export function statusText(core) {
+    const run = core.run;
+    if (run === null) {
+        return ('OK: no governance run is active in this session.\n' +
+            'NEXT:\n  gov_run {"action":"start","goal":"...","spec":"...","workPackages":[...]}\n' +
+            '  gov_run {"action":"resume"} (continues the latest unfinished run for this directory)');
+    }
+    const recent = core
+        .snapshot()
+        ?.recent.map((r) => {
+        const sign = r.delta > 0 ? '+' : '';
+        return `${r.agentId} ${sign}${r.delta}${r.provisional ? 'P' : ''} ${r.code} ${r.reason}`;
+    });
+    const open = run.escalations.filter((e) => e.status === 'open');
+    const results = [renderPhases(run), renderWpTable(run)];
+    if (run.claims.some((c) => c.status === 'open')) {
+        const openIds = run.claims.filter((c) => c.status === 'open').map((c) => c.id);
+        results.push(`Open claims: ${openIds.join(', ')}`);
+    }
+    if (open.length > 0) {
+        results.push(`Open escalations: ${open.map((e) => `${e.id} (${e.topic})`).join(' | ')}`);
+    }
+    if (recent && recent.length > 0)
+        results.push(`Recent ledger: ${recent.join(' | ')}`);
+    const statusWord = run.status === 'escalated' ? 'ESCALATION' : 'OK';
+    return composeDigest(core, {
+        headline: `${statusWord}: run ${run.runId} is ${run.status}. Goal: ${run.goal}`,
+        results,
+        warnings: [
+            'NOTE: token figures are TEAM tokens (children + supervisor); the orchestrator\'s own ' +
+                'spend is in the status bar.',
+        ],
+        standings: true,
+    });
+}
+// ---------------------------------------------------------------------------
+// close / abandon
+// ---------------------------------------------------------------------------
+function finalize(core, summary, abandoned) {
+    const run = core.requireRun();
+    core.pauseRequested = false;
+    core.userPaused = false;
+    const rows = core.standingRows();
+    const board = { run, standings: rows, health: core.health(), recent: [] };
+    core.writeFile('board.md', buildBoardMarkdown(board));
+    const report = buildFinalReport({
+        ...board,
+        ...(summary !== undefined ? { summary } : {}),
+        wallMs: core.now() - run.createdAt,
+    });
+    core.writeFile('reports/final.md', report);
+    core.exportScoreboard();
+    core.log('run_closed', 'engine', { abandoned, ...(summary ? { summary } : {}) });
+    core.checkpoint();
+    core.emit((snapshot) => ({ type: 'run_closed', snapshot, card: finalCard(core) }));
+}
+async function releaseRun(core) {
+    const runId = core.run?.runId;
+    await core.flush();
+    if (runId !== undefined) {
+        core.deps.store.stopHeartbeat(runId);
+        await core.deps.store.releaseLock(runId);
+    }
+}
+function unfinishedList(run) {
+    return run.wpOrder
+        .map((id) => run.workPackages[id])
+        .filter((w) => w !== undefined && !['integrated', 'dropped'].includes(w.status))
+        .map((w) => `${w.id} (${w.status})`)
+        .join(', ');
+}
+/** `gov_run close`: only when every phase is integrated (or the run was abandoned). */
+export async function closeRun(core, summary) {
+    const run = core.run;
+    if (run === null)
+        return refusal(core, 'there is no governance run to close.');
+    if (run.status === 'closed')
+        return refusal(core, `run ${run.runId} is already closed.`);
+    if (run.status !== 'abandoned' && !canClose(run)) {
+        return refusal(core, `run ${run.runId} cannot close yet: not every phase is integrated ` +
+            `(unfinished: ${unfinishedList(run) || 'none'}).`);
+    }
+    if (run.status !== 'abandoned')
+        run.status = 'closed';
+    run.stage = run.stage !== null && run.stage.status === 'running' ? null : run.stage;
+    finalize(core, summary, false);
+    await releaseRun(core);
+    const report = buildFinalReport({
+        run,
+        standings: core.standingRows(),
+        health: core.health(),
+        recent: [],
+        ...(summary !== undefined ? { summary } : {}),
+        wallMs: core.now() - run.createdAt,
+    });
+    return composeDigest(core, {
+        headline: `OK: run ${run.runId} closed.`,
+        results: [report.trimEnd()],
+        standings: false,
+    });
+}
+/** `gov_run abandon`: keeps every artifact, ends the run, frees the directory for a new one. */
+export async function abandonRun(core, reason) {
+    const run = core.run;
+    if (run === null)
+        return refusal(core, 'there is no governance run to abandon.');
+    if (run.status === 'closed' || run.status === 'abandoned') {
+        return refusal(core, `run ${run.runId} is already ${run.status}.`);
+    }
+    if (core.isStageRunning())
+        core.abortStage();
+    recoverInterruptedStage(run);
+    run.status = 'abandoned';
+    for (const e of run.escalations) {
+        if (e.status === 'open')
+            closeEscalation(run, e, `run abandoned: ${reason}`);
+    }
+    run.status = 'abandoned';
+    finalize(core, `abandoned: ${reason}`, true);
+    await releaseRun(core);
+    return composeDigest(core, {
+        headline: `OK: run ${run.runId} abandoned (${reason}). All artifacts are kept on disk.`,
+        standings: true,
+    });
+}
+// ---------------------------------------------------------------------------
+// resolve (L3)
+// ---------------------------------------------------------------------------
+const DISPOSITIONS = [
+    'retry',
+    'accept_as_is',
+    'drop',
+    'accept_failing',
+];
+function normalizeResolve(raw) {
+    const issues = new Issues();
+    const args = isRecord(raw) ? raw : {};
+    const escalationId = issues.str(args.escalationId, 'escalationId', 40, true);
+    const ruling = issues.str(args.ruling, 'ruling', GOV_LIMITS.rulingChars, true);
+    const favor = issues.str(args.favor, 'favor', 80);
+    const disposition = issues.oneOf(args.disposition, 'disposition', DISPOSITIONS);
+    if (issues.errors.length > 0)
+        return { ok: false, errors: issues.errors };
+    return {
+        ok: true,
+        value: {
+            escalationId,
+            ruling,
+            ...(favor !== '' ? { favor } : {}),
+            ...(disposition !== undefined ? { disposition } : {}),
+        },
+    };
+}
+/** Open a budget escalation (called by the stage runner when the cap is hit). */
+export function openBudgetEscalation(core) {
+    const run = core.requireRun();
+    const existing = run.escalations.find((e) => e.status === 'open' && e.topic.startsWith(BUDGET_TOPIC_PREFIX));
+    if (existing !== undefined)
+        return existing;
+    const escalation = {
+        id: nextEscalationId(run),
+        level: 'L3',
+        kind: 'dispute',
+        topic: `${BUDGET_TOPIC_PREFIX} is exhausted (${run.usage.inputTokens + run.usage.outputTokens} ` +
+            `of ${core.config().budgetTokens}). Raise the budget (/gov budget <n>) or abandon the run.`,
+        positions: [],
+        status: 'open',
+    };
+    run.escalations.push(escalation);
+    run.status = 'escalated';
+    core.log('escalation', 'engine', { id: escalation.id, kind: 'budget' });
+    core.checkpoint();
+    core.emit((snapshot) => ({
+        type: 'escalation',
+        snapshot,
+        escalation,
+        card: escalationCard(core, escalation),
+    }));
+    return escalation;
+}
+function budgetStillExhausted(core, escalation) {
+    const run = core.requireRun();
+    return (escalation.topic.startsWith(BUDGET_TOPIC_PREFIX) &&
+        shouldStopNewStages(run.usage, core.config().budgetTokens));
+}
+/** `gov_run resolve`: the user's L3 ruling, optionally with a disposition (7.2). */
+export async function resolveEscalation(core, raw) {
+    const run = core.run;
+    if (run === null)
+        return refusal(core, 'there is no governance run.');
+    const parsed = normalizeResolve(raw);
+    if (!parsed.ok)
+        return formatNotAccepted('gov_run resolve', parsed.errors);
+    const input = parsed.value;
+    const escalation = run.escalations.find((e) => e.id === input.escalationId);
+    if (escalation === undefined) {
+        const open = run.escalations.filter((e) => e.status === 'open').map((e) => e.id);
+        return refusal(core, `unknown escalation '${input.escalationId}' (open: ${open.join(', ') || 'none'}).`);
+    }
+    if (budgetStillExhausted(core, escalation) && input.disposition === undefined) {
+        return refusal(core, 'the team-token budget is still exhausted. Ask the user to raise it (/gov budget <n>), ' +
+            'then resolve again, or abandon the run.');
+    }
+    const applied = applyResolveDisposition(run, escalation, input.disposition);
+    if (!applied.ok)
+        return composeDigest(core, { headline: applied.message });
+    closeEscalation(run, escalation, input.ruling);
+    core.log('resolution', 'user', {
+        id: escalation.id,
+        ruling: input.ruling,
+        ...(input.favor ? { favor: input.favor } : {}),
+        ...(input.disposition ? { disposition: input.disposition } : {}),
+    });
+    core.checkpoint();
+    core.emit((snapshot) => ({ type: 'agent_state', snapshot }));
+    const flushNote = await core.flush();
+    const warnings = applied.affectedDependents.length > 0
+        ? [`WARNING: dependent work package(s) affected: ${applied.affectedDependents.join(', ')}.`]
+        : [];
+    const text = composeDigest(core, {
+        headline: `OK: ${escalation.id} resolved. ${applied.message}`,
+        warnings,
+        standings: false,
+    });
+    return flushNote === null ? text : `${text}\n${flushNote}`;
+}