@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/config/ui-state.d.ts

@@ -105,6 +105,14 @@ export interface UiState {
      * and a boolean could only ever say "shown", never "shown WHAT".
      */
     promptKeyNoticeVersion: number;
+    /**
+     * Whether the one-time GOVERN explainer has been shown (governance-mode 4.3). A boolean is
+     * enough here, unlike the notices above: the sentence has never been reworded, so there is
+     * no audience of "already shown the OLD text" to reach. Like them it is a new scalar rather
+     * than a schema bump (which would reset every user's `submitCount`), and an older file reads
+     * it as `false`, which is exactly the first-run behaviour wanted.
+     */
+    governanceIntroSeen: boolean;
 }
 /** Read the state, caching it for the life of the process. Never throws. */
 export declare function loadUiState(): UiState;
@@ -125,6 +133,9 @@ export declare function setScrollModeNoticeVersion(version: number): void;
 /** `0` on a file written before the field existed; see the field's comment. */
 export declare function getPromptKeyNoticeVersion(): number;
 export declare function setPromptKeyNoticeVersion(version: number): void;
+/** `false` until the one-time GOVERN explainer has been shown; persisted across launches. */
+export declare function getGovernanceIntroSeen(): boolean;
+export declare function setGovernanceIntroSeen(seen: boolean): void;
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/config/ui-state.js

@@ -39,6 +39,7 @@ const DEFAULT_UI_STATE = {
     vtInputNoticeVersion: 0,
     scrollModeNoticeVersion: 0,
     promptKeyNoticeVersion: 0,
+    governanceIntroSeen: false,
 };
 let memory = null;
 /** Non-negative integer or `fallback`; shared by both numeric fields. */
@@ -73,6 +74,9 @@ function readFromDisk() {
             vtInputNoticeVersion: coerceCount(parsed.vtInputNoticeVersion, DEFAULT_UI_STATE.vtInputNoticeVersion),
             scrollModeNoticeVersion: coerceCount(parsed.scrollModeNoticeVersion, DEFAULT_UI_STATE.scrollModeNoticeVersion),
             promptKeyNoticeVersion: coerceCount(parsed.promptKeyNoticeVersion, DEFAULT_UI_STATE.promptKeyNoticeVersion),
+            governanceIntroSeen: typeof parsed.governanceIntroSeen === 'boolean'
+                ? parsed.governanceIntroSeen
+                : DEFAULT_UI_STATE.governanceIntroSeen,
         };
     }
     catch {
@@ -160,6 +164,13 @@ export function getPromptKeyNoticeVersion() {
 export function setPromptKeyNoticeVersion(version) {
     update({ promptKeyNoticeVersion: version });
 }
+/** `false` until the one-time GOVERN explainer has been shown; persisted across launches. */
+export function getGovernanceIntroSeen() {
+    return loadUiState().governanceIntroSeen;
+}
+export function setGovernanceIntroSeen(seen) {
+    update({ governanceIntroSeen: seen });
+}
 /**
  * Migration-only: fill in fields that are still at their default, and never
  * overwrite a value already here. A second import — after a half-finished

package/dist/diagnostics/doctor.js

@@ -16,6 +16,8 @@ import process from 'node:process';
 import { initProviders, ModelRegistry } from '@aragon-agent/core';
 import { getHomeResolutionWarning, getSessionsDir, getUserDataDir } from '../config/app-paths.js';
 import { readConfigFile } from '../config/store.js';
+import { describeGovernanceConfigAvailability, } from '../config/governance-config.js';
+import { unavailableReasonText } from '../governance/copy.js';
 import { loadConfig, makeGetApiKey } from '../config/load.js';
 import { isAdapterProvider, toRetryPolicy } from '../config/schema.js';
 import { MODE_TOGGLE_KEYS } from '../agent/agent-mode.js';
@@ -28,6 +30,7 @@ export async function runDoctorChecks(flags, opts = {}) {
     checks.push(checkModel(config));
     checks.push(checkSessionsDir());
     checks.push(checkValidationStrength());
+    checks.push(checkGovernance(config));
     if (opts.probe)
         checks.push(await probeProvider(config));
     return { ok: checks.every((c) => c.verdict !== 'fail'), checks };
@@ -64,6 +67,23 @@ function checkValidationStrength() {
     return pass('ajv', 'absent: required/properties/items/additionalProperties are still enforced by the ' +
         'built-in validator; pattern/format/multipleOf are not');
 }
+/**
+ * `governance: ready | unavailable (<reason>)` (governance-mode 13.2) - a `pass` either way.
+ *
+ * An unavailable feature is a CHOICE (a config key, `ARAGON_GOVERNANCE=0`, team mode off),
+ * not a defect, so it must not warn or move the exit code; the row exists so "why does
+ * Shift+Tab not reach GOVERN" has an answer next to the other install facts. Config-level
+ * reasons only: a missing API key is already reported by the `api-key` row, and the runtime
+ * reasons (`headless`, `restart_required`) are not properties of an installation.
+ * The sentences come from `governance/copy.ts`, the one definition `/gov` and the settings
+ * screen share.
+ */
+function checkGovernance(config) {
+    const availability = describeGovernanceConfigAvailability(config, process.env);
+    if (availability.ok)
+        return pass('governance', 'ready');
+    return pass('governance', `unavailable (${unavailableReasonText(availability.reason)})`);
+}
 function pass(name, detail) {
     return { name, verdict: 'pass', detail, remedy: '' };
 }

package/dist/governance/card-normalize.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `normalizeGovernanceCard` - turn an untrusted value (a session file, a hand-edited
+ * `entries` array) into a renderable `GovernanceCardData`, or `null` (section 10.4).
+ *
+ * Pure: no React, no I/O. ASCII ONLY.
+ *
+ * LENIENT BY DESIGN. A governance card is HISTORY: a resume that refuses because one row
+ * carried a string where a number belongs would throw away a conversation to protect a
+ * footnote (`validate-session.ts` makes the same argument for the todo card). So:
+ * unknown fields are dropped, a malformed ROW is dropped, a missing text field degrades
+ * to an empty string, and only a value that is not a card at all (not an object, no
+ * recognisable variant, nothing left to draw) returns `null` - which the caller turns into
+ * a one-line text entry.
+ */
+import type { GovernanceCardData } from './types.js';
+/** The one line a card degrades to when nothing of it can be drawn. */
+export declare const GOVERNANCE_CARD_FALLBACK_TEXT = "Governance card unavailable";
+/** Bounds so a corrupt file cannot make a card taller than the transcript can hold. */
+export declare const CARD_LIMITS: {
+    readonly rows: 24;
+    readonly notes: 12;
+    readonly textChars: 400;
+};
+export declare function normalizeGovernanceCard(value: unknown): GovernanceCardData | null;

package/dist/governance/card-normalize.js

@@ -0,0 +1,76 @@
+/**
+ * `normalizeGovernanceCard` - turn an untrusted value (a session file, a hand-edited
+ * `entries` array) into a renderable `GovernanceCardData`, or `null` (section 10.4).
+ *
+ * Pure: no React, no I/O. ASCII ONLY.
+ *
+ * LENIENT BY DESIGN. A governance card is HISTORY: a resume that refuses because one row
+ * carried a string where a number belongs would throw away a conversation to protect a
+ * footnote (`validate-session.ts` makes the same argument for the todo card). So:
+ * unknown fields are dropped, a malformed ROW is dropped, a missing text field degrades
+ * to an empty string, and only a value that is not a card at all (not an object, no
+ * recognisable variant, nothing left to draw) returns `null` - which the caller turns into
+ * a one-line text entry.
+ */
+const VARIANTS = [
+    'charter',
+    'phase',
+    'escalation',
+    'final',
+];
+const TONES = ['ok', 'warn', 'error', 'info'];
+const ROLES = ['DEV', 'REV', 'TEST', 'INSP'];
+/** The one line a card degrades to when nothing of it can be drawn. */
+export const GOVERNANCE_CARD_FALLBACK_TEXT = 'Governance card unavailable';
+/** Bounds so a corrupt file cannot make a card taller than the transcript can hold. */
+export const CARD_LIMITS = { rows: 24, notes: 12, textChars: 400 };
+function asRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function text(value) {
+    return typeof value === 'string' ? value.slice(0, CARD_LIMITS.textChars) : '';
+}
+function oneOf(value, allowed, fallback) {
+    return typeof value === 'string' && allowed.includes(value)
+        ? value
+        : fallback;
+}
+function normalizeRow(value) {
+    const source = asRecord(value);
+    if (source === null || typeof source.id !== 'string' || source.id === '')
+        return null;
+    const role = oneOf(source.role, ROLES, 'DEV');
+    const confirmed = typeof source.confirmed === 'number' && Number.isFinite(source.confirmed)
+        ? source.confirmed
+        : null;
+    return { id: text(source.id), role, confirmed, deltaText: text(source.deltaText) };
+}
+export function normalizeGovernanceCard(value) {
+    const source = asRecord(value);
+    if (source === null)
+        return null;
+    const rows = (Array.isArray(source.rows) ? source.rows : [])
+        .slice(0, CARD_LIMITS.rows)
+        .map(normalizeRow)
+        .filter((row) => row !== null);
+    const notes = (Array.isArray(source.notes) ? source.notes : [])
+        .slice(0, CARD_LIMITS.notes)
+        .filter((note) => typeof note === 'string')
+        .map((note) => note.slice(0, CARD_LIMITS.textChars));
+    const title = text(source.title);
+    const headline = text(source.headline);
+    // Nothing to draw: the caller degrades to a one-line text entry.
+    if (title === '' && headline === '' && rows.length === 0 && notes.length === 0)
+        return null;
+    return {
+        variant: oneOf(source.variant, VARIANTS, 'phase'),
+        runId: text(source.runId),
+        title,
+        headline,
+        tone: oneOf(source.tone, TONES, 'info'),
+        rows,
+        notes,
+    };
+}

package/dist/governance/copy.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Every user-visible governance sentence (governance-mode 10.6, 14.2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). UI components, the `/gov` command, `doctor`
+ * and the settings screen import their words from here and never inline a sentence: one
+ * place to review the wording, one place to change it, and one definition of what each
+ * "unavailable" reason means (`/gov`, `doctor` and settings share it).
+ *
+ * Nothing here reaches a model. Prompts live in `prompts/`; these strings are for the
+ * person at the keyboard, which is why they may be friendlier and less formal.
+ */
+import type { DispatchEstimate } from './engine/estimate.js';
+import { type Posture } from './posture.js';
+/** Why governance cannot be used right now. Spelled as in `config/governance-config.ts`. */
+export type GovernanceUnavailableReason = 'disabled_config' | 'disabled_env' | 'no_team' | 'team_off' | 'no_api_key' | 'headless' | 'restart_required';
+/** Shown for `restart_required`: the tool array is fixed at construction (RV-14). */
+export declare const RESTART_REQUIRED_TEXT = "Governance was disabled when this session started. Restart to enable it.";
+/** The one sentence for an unavailable reason (`/gov`, `doctor`, settings). */
+export declare function unavailableReasonText(reason: GovernanceUnavailableReason): string;
+export type GovernanceAvailability = {
+    ok: true;
+} | {
+    ok: false;
+    reason: GovernanceUnavailableReason;
+};
+/** `doctor` line: `governance: ready` or `governance: unavailable (<reason>)`. */
+export declare function doctorGovernanceLine(availability: GovernanceAvailability): string;
+/** One-time notice on the first entry into GOVERN (shown once across launches). */
+export declare const GOVERN_INTRO_NOTICE: string;
+/** One-time notice on the first entry into PLAN+GOVERN. */
+export declare const PLAN_GOVERN_INTRO_NOTICE: string;
+/** `<LABEL> mode.` after a posture change took effect. */
+export declare function postureAppliedToast(posture: Posture): string;
+/** The change was deferred to the end of the current run. */
+export declare function posturePendingToast(posture: Posture): string;
+/** D-23: a governed stage is in flight, so every posture change waits for it. */
+export declare function stageRunningToast(target: Posture): string;
+/** Toast when a PLAN+GOVERN plan is approved and the posture flips to GOVERN. */
+export declare const PLAN_APPROVED_TOAST = "Plan approved - GOVERN mode: the team takes over.";
+/** Hint rows (interaction-hints). */
+export declare const GOV_IDLE_HINT = "type a task - the Orchestrator will assemble the team";
+export declare const GOV_RUNNING_HINT = "esc x2 interrupt (run is resumable)";
+/** Shortcut-panel descriptions (`ui/shortcuts.ts`). */
+export declare const SHIFT_TAB_DESCRIPTION = "Cycle BUILD / PLAN / GOVERN / PLAN+GOVERN";
+export declare const GOV_COMMAND_SUMMARY = "Governed multi-agent team: /gov help";
+/**
+ * Chip on the question overlay during the PLAN+GOVERN interview. While rounds are still
+ * needed it shows the round being asked; once enough were ANSWERED the `+` becomes `OK`.
+ * `''` when no minimum is enforced.
+ */
+export declare function interviewChipText(answered: number, need: number): string;
+export declare const GOV_STAGE_BUSY_NOTICE: string;
+export declare const GOV_OFF_WITH_RUN_NOTICE: string;
+export declare const GOV_OFF_NOTICE = "Governance is off.";
+export declare const GOV_NO_STAGE_NOTICE = "No governed stage is running.";
+export declare const GOV_ABORTED_NOTICE = "The stage was stopped and the run is paused. /gov resume continues it.";
+export declare const GOV_NO_RUN_NOTICE = "There is no governed run to resume in this directory.";
+export declare const GOV_NO_RUNS_NOTICE = "No governed runs yet in this directory.";
+export declare const GOV_PAUSE_NO_RUN_NOTICE = "No governed run to pause.";
+export declare const GOV_PAUSE_ALREADY_NOTICE = "Already paused. /gov resume continues it.";
+export declare const GOV_PAUSE_ESCALATED_NOTICE: string;
+export declare const GOV_PAUSE_CANCELLED_TOAST = "Pause cancelled; the run continues.";
+export declare const GOV_PAUSE_NONE_PENDING_NOTICE = "No pause is pending.";
+/** Toast: the request is accepted and the stage keeps running. */
+export declare function govPausePendingToast(stage: string | null): string;
+/** Toast: no stage was running, so the run paused at once. */
+export declare function govPausedNowToast(runId: string): string;
+export declare const GOV_REPORT_USAGE = "Usage: /gov report [runId]";
+export declare function govReportBadIdNotice(raw: string): string;
+export declare function govReportMissingNotice(runId: string): string;
+export declare const GOV_REPORT_NO_RUN_NOTICE = "There is no governed run to report on in this directory.";
+export declare const GOV_REPORT_MAX_LINES = 120;
+/** `/gov on` and friends when governance cannot be used. */
+export declare function govUnavailableNotice(reason: GovernanceUnavailableReason): string;
+export declare function govBudgetSetNotice(tokens: number): string;
+export declare const GOV_BUDGET_OFF_NOTICE = "Team token budget removed (unlimited).";
+export declare const GOV_BUDGET_USAGE = "Usage: /gov budget <tokens>|off";
+export interface GovStatusRun {
+    runId: string;
+    /** 1-based. */
+    phase: number;
+    phaseCount: number;
+    stage: string | null;
+    status: string;
+    health: number | null;
+    /** A cooperative `/gov pause` is waiting for the running stage to finish. */
+    pauseRequested?: boolean;
+}
+export interface GovStatusInput {
+    posture: Posture;
+    availability: GovernanceAvailability;
+    run: GovStatusRun | null;
+    /** The `formatDispatchEstimate` line for the live run, when there is one. */
+    dispatchPlan?: string | null;
+}
+/** The `/gov` and `/gov status` notice. */
+export declare function formatGovStatus(input: GovStatusInput): string;
+/** `/gov help`: the three powers, GT, stages, keys, and how this differs from team fan-out. */
+export declare function buildGovHelpText(minAskRounds?: number): string;
+/**
+ * THE DISCIPLINE OF THIS WORDING. The three numbers are the only ones that can be proven
+ * true (see `engine/estimate.ts`), so the sentence says exactly what each one is: a CLEAN
+ * run, what ONE round "adds up to", and the cap. It never says "at most", "upper bound" or
+ * "worst case" - the rework cap is per work package and grants raise it, so any total
+ * would be a promise the engine does not keep. `governance-estimate.test.ts` asserts that.
+ */
+export declare function formatDispatchEstimate(estimate: DispatchEstimate): string;
+/** The same figures for the Orchestrator's `gov_run start` result (agent-facing, ASCII). */
+export declare function formatDispatchPlanForAgent(estimate: DispatchEstimate): string;

package/dist/governance/copy.js

@@ -0,0 +1,223 @@
+/**
+ * Every user-visible governance sentence (governance-mode 10.6, 14.2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). UI components, the `/gov` command, `doctor`
+ * and the settings screen import their words from here and never inline a sentence: one
+ * place to review the wording, one place to change it, and one definition of what each
+ * "unavailable" reason means (`/gov`, `doctor` and settings share it).
+ *
+ * Nothing here reaches a model. Prompts live in `prompts/`; these strings are for the
+ * person at the keyboard, which is why they may be friendlier and less formal.
+ */
+import { GOV_LIMITS } from './limits.js';
+import { POSTURE_LABEL } from './posture.js';
+/** Shown for `restart_required`: the tool array is fixed at construction (RV-14). */
+export const RESTART_REQUIRED_TEXT = 'Governance was disabled when this session started. Restart to enable it.';
+const UNAVAILABLE_TEXT = {
+    disabled_config: 'Governance is switched off in settings (governance.enabled is false).',
+    disabled_env: 'Governance is switched off by the ARAGON_GOVERNANCE=0 environment variable.',
+    no_team: 'Governance needs team mode, which this session started without (--no-team).',
+    team_off: 'Governance needs team mode, which is switched off. Turn it on with /team on.',
+    no_api_key: 'Governance needs an API key for the active provider. Set one first.',
+    headless: 'Governance mode needs an interactive terminal.',
+    restart_required: RESTART_REQUIRED_TEXT,
+};
+/** The one sentence for an unavailable reason (`/gov`, `doctor`, settings). */
+export function unavailableReasonText(reason) {
+    return UNAVAILABLE_TEXT[reason];
+}
+/** `doctor` line: `governance: ready` or `governance: unavailable (<reason>)`. */
+export function doctorGovernanceLine(availability) {
+    if (availability.ok)
+        return 'governance: ready';
+    return `governance: unavailable (${unavailableReasonText(availability.reason)})`;
+}
+// ---------------------------------------------------------------------------
+// Posture notices and toasts
+// ---------------------------------------------------------------------------
+/** One-time notice on the first entry into GOVERN (shown once across launches). */
+export const GOVERN_INTRO_NOTICE = 'GOVERN: your next message goes to an Orchestrator that runs a governed team ' +
+    '(dev / review / test / inspector). Esc interrupts. /gov for status, /gov off to leave.';
+/** One-time notice on the first entry into PLAN+GOVERN. */
+export const PLAN_GOVERN_INTRO_NOTICE = 'PLAN+GOVERN: the Orchestrator interviews you first, then a governed team executes the ' +
+    'approved plan. Esc interrupts. /gov for status, /gov off to leave.';
+/** `<LABEL> mode.` after a posture change took effect. */
+export function postureAppliedToast(posture) {
+    return `${POSTURE_LABEL[posture]} mode.`;
+}
+/** The change was deferred to the end of the current run. */
+export function posturePendingToast(posture) {
+    return `${POSTURE_LABEL[posture]} mode applies after this run.`;
+}
+/** D-23: a governed stage is in flight, so every posture change waits for it. */
+export function stageRunningToast(target) {
+    return (`GOVERN stage is running: ${POSTURE_LABEL[target]} applies after it ends. ` +
+        'Esc stops the stage now.');
+}
+/** Toast when a PLAN+GOVERN plan is approved and the posture flips to GOVERN. */
+export const PLAN_APPROVED_TOAST = 'Plan approved - GOVERN mode: the team takes over.';
+/** Hint rows (interaction-hints). */
+export const GOV_IDLE_HINT = 'type a task - the Orchestrator will assemble the team';
+export const GOV_RUNNING_HINT = 'esc x2 interrupt (run is resumable)';
+/** Shortcut-panel descriptions (`ui/shortcuts.ts`). */
+export const SHIFT_TAB_DESCRIPTION = 'Cycle BUILD / PLAN / GOVERN / PLAN+GOVERN';
+export const GOV_COMMAND_SUMMARY = 'Governed multi-agent team: /gov help';
+/**
+ * Chip on the question overlay during the PLAN+GOVERN interview. While rounds are still
+ * needed it shows the round being asked; once enough were ANSWERED the `+` becomes `OK`.
+ * `''` when no minimum is enforced.
+ */
+export function interviewChipText(answered, need) {
+    if (need <= 0)
+        return '';
+    if (answered >= need)
+        return `PLAN+GOVERN  interview round ${answered}/${need} OK`;
+    return `PLAN+GOVERN  interview round ${answered + 1}/${need}+`;
+}
+// ---------------------------------------------------------------------------
+// /gov command
+// ---------------------------------------------------------------------------
+export const GOV_STAGE_BUSY_NOTICE = 'A governed stage is running. Wait for it to finish, or press Esc / use /gov abort to ' +
+    'stop it first.';
+export const GOV_OFF_WITH_RUN_NOTICE = 'Governance is off. The run is paused, not ended: /gov resume continues it. ' +
+    'Use /gov pause first to stop at a clean boundary.';
+export const GOV_OFF_NOTICE = 'Governance is off.';
+export const GOV_NO_STAGE_NOTICE = 'No governed stage is running.';
+export const GOV_ABORTED_NOTICE = 'The stage was stopped and the run is paused. /gov resume continues it.';
+export const GOV_NO_RUN_NOTICE = 'There is no governed run to resume in this directory.';
+export const GOV_NO_RUNS_NOTICE = 'No governed runs yet in this directory.';
+// --- /gov pause (governance-mode-v1-1 6.1) ---------------------------------------------
+export const GOV_PAUSE_NO_RUN_NOTICE = 'No governed run to pause.';
+export const GOV_PAUSE_ALREADY_NOTICE = 'Already paused. /gov resume continues it.';
+export const GOV_PAUSE_ESCALATED_NOTICE = 'The run is waiting on your ruling (escalated); there is nothing to pause. ' +
+    '/gov board shows the open item.';
+export const GOV_PAUSE_CANCELLED_TOAST = 'Pause cancelled; the run continues.';
+export const GOV_PAUSE_NONE_PENDING_NOTICE = 'No pause is pending.';
+/** Toast: the request is accepted and the stage keeps running. */
+export function govPausePendingToast(stage) {
+    const where = stage === null ? 'the current stage' : `the current stage (${stage.toUpperCase()})`;
+    return `Pausing after ${where}. Nothing is stopped; /gov pause cancel undoes this.`;
+}
+/** Toast: no stage was running, so the run paused at once. */
+export function govPausedNowToast(runId) {
+    return `Run ${runId} paused. /gov resume continues it.`;
+}
+// --- /gov report (governance-mode-v1-1 7.2) ---------------------------------------------
+export const GOV_REPORT_USAGE = 'Usage: /gov report [runId]';
+export function govReportBadIdNotice(raw) {
+    return `"${raw.slice(0, 24)}" is not a run id. ${GOV_REPORT_USAGE}`;
+}
+export function govReportMissingNotice(runId) {
+    return (`No report is available for run ${runId} yet ` +
+        '(reports are written when a phase is integrated).');
+}
+export const GOV_REPORT_NO_RUN_NOTICE = 'There is no governed run to report on in this directory.';
+export const GOV_REPORT_MAX_LINES = 120;
+/** `/gov on` and friends when governance cannot be used. */
+export function govUnavailableNotice(reason) {
+    return `Governance is unavailable: ${unavailableReasonText(reason)}`;
+}
+export function govBudgetSetNotice(tokens) {
+    return `Team token budget set to ${tokens}. It limits team spend only.`;
+}
+export const GOV_BUDGET_OFF_NOTICE = 'Team token budget removed (unlimited).';
+export const GOV_BUDGET_USAGE = 'Usage: /gov budget <tokens>|off';
+/** The `/gov` and `/gov status` notice. */
+export function formatGovStatus(input) {
+    const lines = [`Posture: ${POSTURE_LABEL[input.posture]}`];
+    lines.push(input.availability.ok
+        ? 'Governance: available'
+        : `Governance: unavailable - ${unavailableReasonText(input.availability.reason)}`);
+    const run = input.run;
+    if (!run) {
+        lines.push('Run: none');
+    }
+    else {
+        const stage = run.stage ? `  ${run.stage.toUpperCase()}` : '';
+        const health = run.health === null ? '' : `  health ${Math.round(run.health)}`;
+        const pausing = run.pauseRequested === true ? ' (pausing after this stage)' : '';
+        lines.push(`Run: ${run.runId}  phase ${run.phase}/${run.phaseCount}${stage}  ` +
+            `${run.status}${pausing}${health}`);
+        if (input.dispatchPlan)
+            lines.push(input.dispatchPlan);
+    }
+    return lines.join('\n');
+}
+function planGovernHelpLine(rounds) {
+    if (rounds <= 0)
+        return '  PLAN+GOVERN: an interview, then the approved plan is the spec.';
+    const noun = rounds === 1 ? 'round' : 'rounds';
+    return `  PLAN+GOVERN: an interview of >= ${rounds} answered ${noun}, then the plan is the spec.`;
+}
+/** `/gov help`: the three powers, GT, stages, keys, and how this differs from team fan-out. */
+export function buildGovHelpText(minAskRounds = 2) {
+    const rounds = Math.max(0, Math.floor(minAskRounds));
+    return [
+        'GOVERNANCE - a governed engineering team',
+        '',
+        'Three powers and an inspector',
+        '  DEV   writes the code, one work package each.',
+        '  REV   reviews independently; can veto, or fix small things directly.',
+        '  TEST  verifies behavior and traces every requirement to evidence.',
+        '  INSP  the fourth power: rules on disputes, checks integration and books judgment',
+        '        events. It is not scored.',
+        'The Orchestrator (this session) plans and drives the run. It cannot edit files itself:',
+        'all implementation goes through the dispatched agents.',
+        '',
+        'GT (governance tokens)',
+        `  Each DEV / REV / TEST starts with ${GOV_LIMITS.initialTokens} GT. Good work earns GT;`,
+        '  rejections and incomplete work cost GT. Positive GT waits in ESCROW (P) until the phase',
+        '  integration check passes, and is clawed back if integration fails because of that',
+        `  agent. At zero confirmed GT an agent is replaced (${GOV_LIMITS.respawnTokens} GT, briefed).`,
+        '  GT is a score for this run, unrelated to LLM context tokens.',
+        '',
+        'Stages, per phase',
+        '  dev -> review -> test -> settle -> integrate. A failed integration adds fix and',
+        '  integrate again. Rework loops are automatic; disputes escalate to you.',
+        '',
+        'Postures and keys',
+        '  Shift+Tab (or Ctrl+N) cycles BUILD / PLAN / GOVERN / PLAN+GOVERN.',
+        '  GOVERN: your next message goes to the Orchestrator.',
+        planGovernHelpLine(rounds),
+        '  Esc interrupts; an interrupted run is paused and resumable.',
+        '  /gov pause stops at the end of the current stage: nothing is killed, no work is lost.',
+        '',
+        'Commands',
+        '  /gov status | on | plan | off | board | runs | resume [id] | abort | budget <n|off> | help',
+        '  /gov pause [cancel] | report [id]',
+        '',
+        'Team fan-out versus governance',
+        '  /team and the task tool fan out independent subtasks in parallel and the lead',
+        '  summarizes them: fast, with no independent check. Governance adds separated roles,',
+        '  structured submissions, independent review, testing and integration, and a score that',
+        '  makes skipping quality expensive. It is slower and costs more: use it where quality',
+        '  matters more than speed.',
+    ].join('\n');
+}
+// ---------------------------------------------------------------------------
+// Dispatch plan (governance-mode-v1-1 7.3, V-5)
+// ---------------------------------------------------------------------------
+/**
+ * THE DISCIPLINE OF THIS WORDING. The three numbers are the only ones that can be proven
+ * true (see `engine/estimate.ts`), so the sentence says exactly what each one is: a CLEAN
+ * run, what ONE round "adds up to", and the cap. It never says "at most", "upper bound" or
+ * "worst case" - the rework cap is per work package and grants raise it, so any total
+ * would be a promise the engine does not keep. `governance-estimate.test.ts` asserts that.
+ */
+export function formatDispatchEstimate(estimate) {
+    if (estimate.cleanRun === 0)
+        return '';
+    const chunked = estimate.chunked ? ' Wide stages are split into several calls.' : '';
+    return (`Dispatch plan: ${estimate.cleanRun} for a clean run; a rework round adds up to ` +
+        `${estimate.perReworkRound}, a fix cycle up to ${estimate.perFixCycle}; the run is ` +
+        `capped at ${estimate.hardCap}.${chunked} Counts only - tokens depend on the model ` +
+        'and the task.');
+}
+/** The same figures for the Orchestrator's `gov_run start` result (agent-facing, ASCII). */
+export function formatDispatchPlanForAgent(estimate) {
+    if (estimate.cleanRun === 0)
+        return '';
+    return (`DISPATCH PLAN: a clean run needs ${estimate.cleanRun} gov_dispatch calls; a rework ` +
+        `round adds up to ${estimate.perReworkRound} and a fix cycle up to ` +
+        `${estimate.perFixCycle}; the run is capped at ${estimate.hardCap}.`);
+}

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

@@ -0,0 +1,49 @@
+/**
+ * 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 type { LedgerEvent } from '../rules/ledger.js';
+import type { BookedEntry, EngineCore } from './engine-core.js';
+export interface AfterLedgerOptions {
+    /** 0-based phase the change belongs to (stamped on the respawn entry). */
+    phase: number;
+}
+export interface AfterLedgerResult {
+    eliminated: string[];
+    respawned: Array<{
+        predecessor: string;
+        successor: string;
+    }>;
+}
+/**
+ * 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 declare function afterLedgerChange(core: EngineCore, options: AfterLedgerOptions): AfterLedgerResult;
+/**
+ * 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 declare function applyEvents(core: EngineCore, events: readonly LedgerEvent[], options: {
+    actor?: string;
+    phase: number;
+}): BookedEntry[];
+export declare function emitLedger(core: EngineCore): void;
+/**
+ * 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 declare function runTailCheck(core: EngineCore, phase: number): string[];