@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/engine/aftermath.js

@@ -0,0 +1,134 @@
+/**
+ * What follows a ledger change (governance-mode 5.8): elimination is already decided by the
+ * pure ledger (`confirmed <= 0` removes the agent inside `apply`), but a removed agent is
+ * only half the story - the roster needs a replacement and the work needs an owner.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * RESPAWN IS A SEPARATE LOGGED OP, NOT A SIDE EFFECT OF `apply`. The ledger is rebuilt by
+ * replaying `ledger` events; a respawn that happened implicitly in the live path would have
+ * no event to replay and the rebuilt ledger would silently lack the successor (I-G2). So
+ * the engine issues `{op:'respawn'}` through `core.ledgerOp` like any other mutation.
+ *
+ * Neither the orchestrator nor any model can trigger a respawn: it is a roster property,
+ * not an orchestration action (5.8), and this is the only caller.
+ */
+import { evaluateTail } from '../rules/elimination.js';
+import { successorId } from '../rules/ledger.js';
+const REASON_WORD = {
+    depleted: 'confirmed GT reached zero',
+    tail: 'lowest in role for two consecutive phases',
+    clawback: 'escrow clawed back after an integration failure',
+};
+function waitingForReplacement(core) {
+    return Object.values(core.ledger.agents)
+        .filter((a) => a.status === 'eliminated' && a.replacedBy === null)
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Hand the predecessor's unfinished work to the successor (sticky REV/TEST included). */
+function reassign(core, from, to) {
+    const run = core.run;
+    if (run === null)
+        return [];
+    const moved = [];
+    for (const id of run.wpOrder) {
+        const wp = run.workPackages[id];
+        if (wp === undefined || wp.status === 'integrated' || wp.status === 'dropped')
+            continue;
+        let touched = false;
+        if (wp.assignee === from) {
+            wp.assignee = to;
+            touched = true;
+        }
+        if (wp.reviewer === from) {
+            wp.reviewer = to;
+            touched = true;
+        }
+        if (wp.tester === from) {
+            wp.tester = to;
+            touched = true;
+        }
+        if (touched)
+            moved.push(id);
+    }
+    return moved;
+}
+function announceElimination(core, agent) {
+    const reason = agent.eliminatedReason ?? 'depleted';
+    core.log('eliminated', 'engine', { agentId: agent.id, role: agent.role, reason });
+    core.setAgentState(agent.id, 'eliminated');
+    core.emit((snapshot) => ({ type: 'eliminated', snapshot, agentId: agent.id, reason }));
+}
+/**
+ * Replace every eliminated-but-unreplaced agent. Idempotent: an agent with `replacedBy`
+ * set is skipped, so calling this after every ledger change is safe and cheap.
+ */
+export function afterLedgerChange(core, options) {
+    const result = { eliminated: [], respawned: [] };
+    for (const agent of waitingForReplacement(core)) {
+        result.eliminated.push(agent.id);
+        announceElimination(core, agent);
+        const id = successorId(agent);
+        const op = {
+            op: 'respawn',
+            request: { agentId: agent.id, phase: options.phase, at: core.now() },
+        };
+        const { booked } = core.ledgerOp(op);
+        const successor = core.ledger.agents[id];
+        if (successor === undefined)
+            continue;
+        const moved = reassign(core, agent.id, id);
+        core.setAgentState(id, 'idle');
+        core.log('respawned', 'engine', { predecessor: agent.id, successor: id, wps: moved });
+        const reason = REASON_WORD[agent.eliminatedReason ?? 'depleted'];
+        const takeover = moved.length > 0 ? `; takes over ${moved.join(', ')}` : '';
+        core.stageWarnings.push(`${agent.id} eliminated (${reason}); replaced by ${id} at ${successor.confirmed} ` +
+            `GT${takeover}.`);
+        core.noteBooked(booked);
+        result.respawned.push({ predecessor: agent.id, successor: id });
+        core.emit((snapshot) => ({
+            type: 'respawned',
+            snapshot,
+            agentId: id,
+            predecessor: agent.id,
+        }));
+    }
+    if (result.eliminated.length > 0)
+        core.checkpoint();
+    return result;
+}
+/**
+ * Apply a list of engine / inspector events one op each (each gets its own seq so the log
+ * reads as the sequence of decisions it was), then settle the roster. Returns every entry
+ * booked, in order.
+ */
+export function applyEvents(core, events, options) {
+    const booked = [];
+    for (const event of events) {
+        const op = { op: 'event', event };
+        booked.push(...core.ledgerOp(op, options.actor ?? 'engine').booked);
+    }
+    core.noteBooked(booked);
+    if (booked.length > 0)
+        emitLedger(core);
+    afterLedgerChange(core, { phase: options.phase });
+    return booked;
+}
+export function emitLedger(core) {
+    core.emit((snapshot) => ({ type: 'ledger', snapshot }));
+}
+/**
+ * Phase-end tail check (5.8): warn on the first strike, eliminate on the second, skip ties.
+ * The preview is computed on the current ledger first because `core.ledgerOp` returns only
+ * booked entries, and the warnings / tie notes are exactly what the digest should print.
+ */
+export function runTailCheck(core, phase) {
+    const at = core.now();
+    const preview = evaluateTail(core.ledger, { phase, at });
+    const { booked } = core.ledgerOp({ op: 'tail_check', phase, at });
+    core.noteBooked(booked);
+    for (const note of preview.notes)
+        core.stageWarnings.push(note);
+    afterLedgerChange(core, { phase });
+    return preview.notes;
+}

package/dist/governance/engine/artifact-persist.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Accept-then-persist for submissions and inspector reports.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * The cache entry is created synchronously (the next tool call must see it) and the file
+ * write is queued behind everything else on the engine's single write chain. The artifact
+ * id is computed HERE from the cache rather than discovered from disk, because a tool call
+ * cannot wait for a directory listing; `ArtifactStore.write` derives the same `n` from the
+ * files that earlier queued writes have already produced, so the two agree as long as
+ * writes succeed.
+ *
+ * A refused write (the 20 MB run budget, spec 12.1) cannot be reported to the call that
+ * caused it - that call has already returned. Instead the run flips to `storageExhausted`,
+ * escalates, and every LATER submission is refused with `NOT ACCEPTED: run storage budget
+ * exhausted`, which is the visible, non-silent form of the same rule.
+ */
+import type { InspectorReport, StageKind, Submission } from '../types.js';
+import type { EngineCore } from './engine-core.js';
+export declare const STORAGE_EXHAUSTED_TEXT = "NOT ACCEPTED: run storage budget exhausted";
+export interface PersistTarget {
+    /** 0-based phase (the artifact id shows it 1-based). */
+    phase: number;
+    wpId: string;
+    stage: StageKind;
+    identity: string;
+}
+/** Next 1-based attempt number for this (phase, wp, stage, identity). */
+export declare function nextAttempt(core: EngineCore, target: PersistTarget): number;
+export declare function artifactIdFor(core: EngineCore, target: PersistTarget): string;
+/**
+ * Cache `item` under `id` and queue its artifact write. `markdown` is the human rendering.
+ * The submission's own `id` field must already equal `id`.
+ */
+export declare function persistArtifact(core: EngineCore, target: PersistTarget, id: string, item: Submission | InspectorReport, markdown: string): void;

package/dist/governance/engine/artifact-persist.js

@@ -0,0 +1,86 @@
+/**
+ * Accept-then-persist for submissions and inspector reports.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * The cache entry is created synchronously (the next tool call must see it) and the file
+ * write is queued behind everything else on the engine's single write chain. The artifact
+ * id is computed HERE from the cache rather than discovered from disk, because a tool call
+ * cannot wait for a directory listing; `ArtifactStore.write` derives the same `n` from the
+ * files that earlier queued writes have already produced, so the two agree as long as
+ * writes succeed.
+ *
+ * A refused write (the 20 MB run budget, spec 12.1) cannot be reported to the call that
+ * caused it - that call has already returned. Instead the run flips to `storageExhausted`,
+ * escalates, and every LATER submission is refused with `NOT ACCEPTED: run storage budget
+ * exhausted`, which is the visible, non-silent form of the same rule.
+ */
+import { getLogger } from '../../logging/logger.js';
+import { buildArtifactId } from '../store/artifacts.js';
+import { openEscalation, nextEscalationId } from './state-machine.js';
+export const STORAGE_EXHAUSTED_TEXT = 'NOT ACCEPTED: run storage budget exhausted';
+/** Next 1-based attempt number for this (phase, wp, stage, identity). */
+export function nextAttempt(core, target) {
+    let n = 0;
+    for (const id of core.submissionCache.keys()) {
+        const prefix = `p${target.phase + 1}/${target.wpId}/${target.stage}-${target.identity}-`;
+        if (id.startsWith(prefix))
+            n += 1;
+    }
+    return n + 1;
+}
+export function artifactIdFor(core, target) {
+    return buildArtifactId({
+        phase: target.phase + 1,
+        wpId: target.wpId,
+        stage: target.stage,
+        identity: target.identity,
+        n: nextAttempt(core, target),
+    });
+}
+/** Flip the run into the storage-exhausted state, once. */
+function onExhausted(core, message) {
+    if (core.storageExhausted)
+        return;
+    core.storageExhausted = true;
+    const run = core.run;
+    if (run === null)
+        return;
+    openEscalation(run, {
+        id: nextEscalationId(run),
+        level: 'L3',
+        kind: 'dispute',
+        topic: `Run storage budget exhausted (${message}). Close or abandon the run.`,
+        positions: [],
+        status: 'open',
+    });
+    core.log('escalation', 'engine', { reason: 'storage_exhausted', message });
+    core.checkpoint();
+}
+/**
+ * Cache `item` under `id` and queue its artifact write. `markdown` is the human rendering.
+ * The submission's own `id` field must already equal `id`.
+ */
+export function persistArtifact(core, target, id, item, markdown) {
+    core.submissionCache.set(id, item);
+    const runId = core.run?.runId;
+    if (runId === undefined)
+        return;
+    core.enqueueTask(async () => {
+        const result = await core.deps.artifacts.write(runId, {
+            phase: target.phase + 1,
+            wpId: target.wpId,
+            stage: target.stage,
+            identity: target.identity,
+            json: item,
+            markdown,
+        });
+        if (!result.ok) {
+            getLogger().warn('agent', 'governance.artifact_write_refused', {
+                id,
+                message: result.message,
+            });
+            onExhausted(core, result.message);
+        }
+    });
+}

package/dist/governance/engine/budget.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Team-token budget accounting (governance-mode 8.5, RV-11).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure.
+ *
+ * WHAT IS COUNTED. `run.usage` and `governance.budgetTokens` cover the governed TEAM's
+ * spend only: every dispatch's `outcome.usage` plus `outcome.overseerUsage` (the
+ * supervisor's fast-tier spend). The orchestrator's own turns are already in the
+ * session total on the status bar, and labelling this figure "team tokens" everywhere
+ * keeps a user from reading it as the session total.
+ *
+ * COST IS NEVER FABRICATED. `costUsd` stays `null` until a price table is supplied; once
+ * it is `null` it is only replaced by a number when a price arrives, and a run that had
+ * an unpriced dispatch afterwards reports `null` again rather than a misleading partial
+ * sum (a partial sum would read as complete). Same rule as the status bar (C-11 / RV-4):
+ * unknown pricing is shown as unknown, never as `$0.00`.
+ *
+ * STOP RULE. At >= 80% of `budgetTokens` a warning is attached to the next digest; at
+ * >= 100% NEW stages are refused. A stage already running is never killed (the caller
+ * checks `shouldStopNewStages` only before starting one).
+ */
+import type { ModelCost, TokenUsage } from '@aragon-agent/core';
+import type { RunUsage } from '../types.js';
+export interface DispatchUsage {
+    usage?: TokenUsage;
+    overseerUsage?: TokenUsage;
+}
+export declare const EMPTY_RUN_USAGE: RunUsage;
+/** A fresh counter: cost starts at 0 and turns `null` only if something is unpriced. */
+export declare function newRunUsage(): RunUsage;
+/**
+ * Fold one dispatch into the run usage. Returns a NEW object. If any non-empty part of
+ * the dispatch cannot be priced (`price` absent) the running cost becomes `null`.
+ */
+export declare function accumulateUsage(previous: RunUsage, outcome: DispatchUsage, price?: ModelCost): RunUsage;
+/** Total team tokens (input + output) - the budget's unit. */
+export declare function totalTokens(usage: RunUsage): number;
+export type BudgetLevel = 'ok' | 'warning' | 'exhausted' | 'unlimited';
+/** `budgetTokens <= 0` means unlimited. */
+export declare function budgetLevel(usage: RunUsage, budgetTokens: number): BudgetLevel;
+/** Share of the budget used (0..); null when unlimited. */
+export declare function budgetFraction(usage: RunUsage, budgetTokens: number): number | null;
+/** True when no NEW stage may start. In-flight stages are never affected. */
+export declare function shouldStopNewStages(usage: RunUsage, budgetTokens: number): boolean;
+/** `1,234` style grouping without locale dependence (ASCII, deterministic). */
+export declare function formatTokens(count: number): string;
+/** "$0.42" or "pricing unknown". */
+export declare function formatCost(costUsd: number | null): string;
+/** One line for digests and `gov_run status`. Always says "team tokens". */
+export declare function budgetLine(usage: RunUsage, budgetTokens: number): string;
+/** The `BUDGET WARNING` / refusal text, or null when nothing needs saying. */
+export declare function budgetNotice(usage: RunUsage, budgetTokens: number): string | null;

package/dist/governance/engine/budget.js

@@ -0,0 +1,112 @@
+/**
+ * Team-token budget accounting (governance-mode 8.5, RV-11).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure.
+ *
+ * WHAT IS COUNTED. `run.usage` and `governance.budgetTokens` cover the governed TEAM's
+ * spend only: every dispatch's `outcome.usage` plus `outcome.overseerUsage` (the
+ * supervisor's fast-tier spend). The orchestrator's own turns are already in the
+ * session total on the status bar, and labelling this figure "team tokens" everywhere
+ * keeps a user from reading it as the session total.
+ *
+ * COST IS NEVER FABRICATED. `costUsd` stays `null` until a price table is supplied; once
+ * it is `null` it is only replaced by a number when a price arrives, and a run that had
+ * an unpriced dispatch afterwards reports `null` again rather than a misleading partial
+ * sum (a partial sum would read as complete). Same rule as the status bar (C-11 / RV-4):
+ * unknown pricing is shown as unknown, never as `$0.00`.
+ *
+ * STOP RULE. At >= 80% of `budgetTokens` a warning is attached to the next digest; at
+ * >= 100% NEW stages are refused. A stage already running is never killed (the caller
+ * checks `shouldStopNewStages` only before starting one).
+ */
+import { GOV_LIMITS } from '../limits.js';
+export const EMPTY_RUN_USAGE = { inputTokens: 0, outputTokens: 0, costUsd: 0 };
+/** A fresh counter: cost starts at 0 and turns `null` only if something is unpriced. */
+export function newRunUsage() {
+    return { ...EMPTY_RUN_USAGE };
+}
+function costOf(usage, price) {
+    const perMillion = (tokens, rate) => tokens && rate ? (tokens / 1_000_000) * rate : 0;
+    return (perMillion(usage.inputTokens, price.input) +
+        perMillion(usage.outputTokens, price.output) +
+        perMillion(usage.cacheReadTokens, price.cacheRead) +
+        perMillion(usage.cacheWriteTokens, price.cacheWrite));
+}
+function parts(outcome) {
+    return [outcome.usage, outcome.overseerUsage].filter((u) => u !== undefined);
+}
+/**
+ * Fold one dispatch into the run usage. Returns a NEW object. If any non-empty part of
+ * the dispatch cannot be priced (`price` absent) the running cost becomes `null`.
+ */
+export function accumulateUsage(previous, outcome, price) {
+    let inputTokens = previous.inputTokens;
+    let outputTokens = previous.outputTokens;
+    let costUsd = previous.costUsd;
+    for (const usage of parts(outcome)) {
+        inputTokens += usage.inputTokens;
+        outputTokens += usage.outputTokens;
+        if (costUsd === null)
+            continue;
+        if (price)
+            costUsd += usage.cost ?? costOf(usage, price);
+        else if (usage.cost !== undefined)
+            costUsd += usage.cost;
+        else if (usage.inputTokens + usage.outputTokens > 0)
+            costUsd = null;
+    }
+    return { inputTokens, outputTokens, costUsd };
+}
+/** Total team tokens (input + output) - the budget's unit. */
+export function totalTokens(usage) {
+    return usage.inputTokens + usage.outputTokens;
+}
+/** `budgetTokens <= 0` means unlimited. */
+export function budgetLevel(usage, budgetTokens) {
+    if (!(budgetTokens > 0))
+        return 'unlimited';
+    const fraction = totalTokens(usage) / budgetTokens;
+    if (fraction >= 1)
+        return 'exhausted';
+    return fraction >= GOV_LIMITS.budgetWarnFraction ? 'warning' : 'ok';
+}
+/** Share of the budget used (0..); null when unlimited. */
+export function budgetFraction(usage, budgetTokens) {
+    return budgetTokens > 0 ? totalTokens(usage) / budgetTokens : null;
+}
+/** True when no NEW stage may start. In-flight stages are never affected. */
+export function shouldStopNewStages(usage, budgetTokens) {
+    return budgetLevel(usage, budgetTokens) === 'exhausted';
+}
+/** `1,234` style grouping without locale dependence (ASCII, deterministic). */
+export function formatTokens(count) {
+    return Math.round(count).toString().replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+/** "$0.42" or "pricing unknown". */
+export function formatCost(costUsd) {
+    return costUsd === null ? 'pricing unknown' : `$${costUsd.toFixed(2)}`;
+}
+/** One line for digests and `gov_run status`. Always says "team tokens". */
+export function budgetLine(usage, budgetTokens) {
+    const used = `team tokens: ${formatTokens(totalTokens(usage))} ` +
+        `(in ${formatTokens(usage.inputTokens)} / out ${formatTokens(usage.outputTokens)}), ` +
+        `cost ${formatCost(usage.costUsd)}`;
+    if (!(budgetTokens > 0))
+        return `${used}; no team-token budget set`;
+    const pct = Math.round((totalTokens(usage) / budgetTokens) * 100);
+    return `${used}; ${pct}% of the ${formatTokens(budgetTokens)} team-token budget ` +
+        '(the budget covers team spend only, not the orchestrator)';
+}
+/** The `BUDGET WARNING` / refusal text, or null when nothing needs saying. */
+export function budgetNotice(usage, budgetTokens) {
+    const level = budgetLevel(usage, budgetTokens);
+    if (level === 'warning') {
+        const pct = Math.round((totalTokens(usage) / budgetTokens) * 100);
+        return `BUDGET WARNING: ${pct}% of the team-token budget is used; new stages stop at 100%.`;
+    }
+    if (level === 'exhausted') {
+        return ('NOT ACCEPTED: the team-token budget is exhausted; no new stage can start. ' +
+            'Ask the user to raise the budget (/gov budget <n> or settings) or abandon the run.');
+    }
+    return null;
+}

package/dist/governance/engine/cards.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Transcript card payloads (governance-mode 10.4): charter, phase settlement, escalation and
+ * final. Pure over `EngineCore` state; the result is plain data that is persisted with the
+ * transcript, so it holds no functions, no Dates and no class instances.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Cards only exist at those four moments - the
+ * per-stage chatter belongs to the panel, not the transcript.
+ */
+import type { Escalation, GovernanceCardData } from '../types.js';
+import type { EngineCore } from './engine-core.js';
+/** The run charter: goal, work packages, contracts, limits. Shown once at `start`. */
+export declare function charterCard(core: EngineCore): GovernanceCardData;
+/** A phase settlement: who gained or lost what, rework and eliminations, team health. */
+export declare function phaseCard(core: EngineCore, phaseIndex: number, headline: string, tone: GovernanceCardData['tone']): GovernanceCardData;
+/** An escalation to the user: what is disputed and which options exist. */
+export declare function escalationCard(core: EngineCore, escalation: Escalation): GovernanceCardData;
+/** The closing card: delivered / accepted with issues / dropped, standings, spend. */
+export declare function finalCard(core: EngineCore): GovernanceCardData;

package/dist/governance/engine/cards.js

@@ -0,0 +1,186 @@
+/**
+ * Transcript card payloads (governance-mode 10.4): charter, phase settlement, escalation and
+ * final. Pure over `EngineCore` state; the result is plain data that is persisted with the
+ * transcript, so it holds no functions, no Dates and no class instances.
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Cards only exist at those four moments - the
+ * per-stage chatter belongs to the panel, not the transcript.
+ */
+import { formatDispatchEstimate } from '../copy.js';
+import { formatCost } from './budget.js';
+import { estimateForRun } from './estimate.js';
+import { teamHealthStatus } from '../rules/elimination.js';
+const MAX_ROWS = 24;
+const MAX_NOTES = 12;
+function signed(delta) {
+    return delta > 0 ? `+${delta}` : String(delta);
+}
+/** `+15P D1`, `+25P->C`, `-20 D5`: one short ASCII token pair per ledger entry. */
+function entryText(entry) {
+    switch (entry.code) {
+        case 'ESCROW_RELEASE':
+            return `+${entry.delta}P->C`;
+        case 'CLAWBACK':
+            return `${signed(entry.delta)} clawback`;
+        case 'RESPAWN':
+            return `start ${entry.delta}`;
+        default: {
+            const pool = entry.settlement === 'provisional' ? 'P' : '';
+            return `${signed(entry.delta)}${pool} ${entry.code}`;
+        }
+    }
+}
+function deltaTextFor(core, agentId, phase) {
+    const agent = core.ledger.agents[agentId];
+    if (agent === undefined)
+        return '';
+    const entries = agent.history.filter((e) => e.delta !== 0 && (phase === null || e.phase === phase) && e.code !== 'RESPAWN');
+    const text = entries.slice(-8).map(entryText).join('  ');
+    return entries.length > 8 ? `... ${text}` : text;
+}
+function rowsFor(core, phase) {
+    const rows = [];
+    for (const agent of Object.values(core.ledger.agents)) {
+        const deltaText = deltaTextFor(core, agent.id, phase);
+        if (agent.status === 'eliminated' && deltaText === '')
+            continue;
+        rows.push({
+            id: agent.id,
+            role: agent.role,
+            confirmed: agent.confirmed,
+            deltaText: agent.status === 'eliminated'
+                ? `ELIMINATED${agent.replacedBy ? ` -> ${agent.replacedBy}` : ''}  ${deltaText}`.trim()
+                : deltaText,
+        });
+    }
+    return rows.slice(0, MAX_ROWS);
+}
+function wpsOf(core) {
+    const run = core.run;
+    if (run === null)
+        return [];
+    return run.wpOrder
+        .map((id) => run.workPackages[id])
+        .filter((w) => w !== undefined);
+}
+/** The run charter: goal, work packages, contracts, limits. Shown once at `start`. */
+export function charterCard(core) {
+    const run = core.requireRun();
+    const notes = [];
+    for (const wp of wpsOf(core)) {
+        notes.push(`${wp.id} (phase ${wp.phase + 1}): ${wp.title}`);
+    }
+    if (run.contracts.length > 0) {
+        notes.push(`contracts: ${run.contracts.map((c) => c.name).join(', ')}`);
+    }
+    notes.push(`limits: rework ${run.limits.maxRework}, fix cycles ${run.limits.maxFixCycles}` +
+        (run.limits.budgetTokens > 0 ? `, budget ${run.limits.budgetTokens} tokens` : ''));
+    const plan = formatDispatchEstimate(estimateForRun(run, core.deps.getTeamCeiling()));
+    if (plan !== '')
+        notes.push(plan);
+    if (run.integrationCommands.length > 0) {
+        notes.push(`integration: ${run.integrationCommands.join(' | ')}`);
+    }
+    return {
+        variant: 'charter',
+        runId: run.runId,
+        title: `Governance - run ${run.runId} started`,
+        headline: `${run.goal} (${Object.keys(run.workPackages).length} WPs, ${run.phases.length} ` +
+            `phase(s))`,
+        tone: 'info',
+        rows: rowsFor(core, null).map((r) => ({ ...r, deltaText: '' })),
+        notes: notes.slice(0, MAX_NOTES),
+    };
+}
+/** A phase settlement: who gained or lost what, rework and eliminations, team health. */
+export function phaseCard(core, phaseIndex, headline, tone) {
+    const run = core.requireRun();
+    const phase = run.phases[phaseIndex];
+    const notes = [];
+    const reworked = wpsOf(core).filter((w) => w.phase === phaseIndex && w.reworkCount > 0);
+    for (const wp of reworked)
+        notes.push(`${wp.id} reworked ${wp.reworkCount}x`);
+    const gone = Object.values(core.ledger.agents).filter((a) => a.status === 'eliminated');
+    for (const agent of gone) {
+        notes.push(`${agent.id} eliminated${agent.replacedBy ? `, replaced by ${agent.replacedBy}` : ''}`);
+    }
+    if (phase !== undefined && phase.fixCycles > 0)
+        notes.push(`fix cycles: ${phase.fixCycles}`);
+    const health = teamHealthStatus(core.ledger);
+    if (health.health !== null)
+        notes.push(`health ${Math.round(health.health)}`);
+    if (health.advisory !== null)
+        notes.push(health.advisory);
+    return {
+        variant: 'phase',
+        runId: run.runId,
+        title: `Governance - phase ${phaseIndex + 1} ${tone === 'error' ? 'failed' : 'integrated'}`,
+        headline,
+        tone,
+        rows: rowsFor(core, phaseIndex),
+        notes: notes.slice(0, MAX_NOTES),
+    };
+}
+/** An escalation to the user: what is disputed and which options exist. */
+export function escalationCard(core, escalation) {
+    const run = core.requireRun();
+    const notes = [escalation.topic];
+    for (const position of escalation.positions.slice(0, 4)) {
+        notes.push(`${position.by}: ${position.text}`);
+    }
+    notes.push(options(escalation));
+    const onWp = escalation.wpId ? ` on ${escalation.wpId}` : '';
+    return {
+        variant: 'escalation',
+        runId: run.runId,
+        title: `Governance - escalation ${escalation.id}`,
+        headline: `${escalation.kind.replace(/_/g, ' ')}${onWp}`,
+        tone: 'warn',
+        rows: [],
+        notes: notes.slice(0, MAX_NOTES),
+    };
+}
+function options(escalation) {
+    switch (escalation.kind) {
+        case 'wp_rework_cap':
+            return 'ruling needed: retry, accept as is, or drop the work package';
+        case 'integration_exhausted':
+            return 'ruling needed: retry once more or accept the failing integration';
+        case 'dispute':
+            return 'ruling needed: the user decides';
+    }
+}
+/** The closing card: delivered / accepted with issues / dropped, standings, spend. */
+export function finalCard(core) {
+    const run = core.requireRun();
+    const wps = wpsOf(core);
+    const delivered = wps.filter((w) => w.status === 'integrated' && !w.acceptedWithIssues);
+    const issues = wps.filter((w) => w.acceptedWithIssues);
+    const dropped = wps.filter((w) => w.status === 'dropped');
+    const open = wps.filter((w) => w.status !== 'integrated' && w.status !== 'dropped');
+    const notes = [];
+    if (issues.length > 0)
+        notes.push(`accepted with issues: ${issues.map((w) => w.id).join(', ')}`);
+    if (dropped.length > 0)
+        notes.push(`not delivered: ${dropped.map((w) => w.id).join(', ')}`);
+    if (open.length > 0)
+        notes.push(`unfinished: ${open.map((w) => w.id).join(', ')}`);
+    for (const phase of run.phases) {
+        if (phase.integrated && !phase.integrationAccepted) {
+            notes.push(`phase ${phase.index + 1}: integration FAILED, accepted by the user`);
+        }
+    }
+    const usage = run.usage;
+    notes.push(`team tokens in ${usage.inputTokens} out ${usage.outputTokens}, cost ` +
+        `${formatCost(usage.costUsd)}`);
+    const clean = issues.length === 0 && dropped.length === 0 && open.length === 0;
+    return {
+        variant: 'final',
+        runId: run.runId,
+        title: `Governance - run ${run.runId} ${run.status === 'abandoned' ? 'abandoned' : 'closed'}`,
+        headline: `${delivered.length}/${wps.length} work packages delivered`,
+        tone: run.status === 'abandoned' ? 'warn' : clean ? 'ok' : 'warn',
+        rows: rowsFor(core, null).map((r) => ({ ...r, deltaText: '' })),
+        notes: notes.slice(0, MAX_NOTES),
+    };
+}

package/dist/governance/engine/digest.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Digest assembly shared by the lifecycle and the stage runner (governance-mode D-16).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * Every `gov_run` / `gov_dispatch` answer is built here from the same four parts: a
+ * headline that starts with `OK:` / `NOT ACCEPTED:` / `ESCALATION:` / `PAUSED:`, the result
+ * lines, a footer with the limits and the TEAM-token line, and `NEXT:`. One builder means
+ * one place that guarantees the prefix, the byte budget and the footer wording.
+ */
+import type { EngineCore } from './engine-core.js';
+export interface DigestParts {
+    headline: string;
+    results?: string[];
+    ledger?: string[];
+    warnings?: string[];
+    /** Include the standings table (stage ends and status; not every refusal). */
+    standings?: boolean;
+}
+/** The footer every digest carries: limits, then team tokens (never the session total). */
+export declare function footerLines(core: EngineCore): string[];
+/**
+ * What a digest says to do next while the USER has paused the run (`/gov pause`). The usual
+ * `paused` answer is `gov_run resume`, which would invite the Orchestrator to resume a run
+ * its human just stopped; only the human resumes it (their `/gov resume` is what sends the
+ * Orchestrator to call `gov_run resume`).
+ */
+export declare const USER_PAUSED_NEXT = "wait for the user: only they resume this run (/gov resume). Do not dispatch.";
+/** Compose a complete tool answer for the current run state. */
+export declare function composeDigest(core: EngineCore, parts: DigestParts): string;
+/** A refusal with the legal next moves attached (no run needed). */
+export declare function refusal(core: EngineCore, reason: string): string;