@aragon-agent/cli 0.6.44 → 0.6.46

package/dist/commands/builtins.js

@@ -15,7 +15,9 @@ import { mergePendingEntries } from '../agent/queued-messages.js';
 import { TODO_FOLLOW_LIMITS } from '../todo/limits.js';
 import { buildContinuationMessage } from '../todo/follow-through.js';
 import { planIsResolved } from '../todo/acceptance.js';
-import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
+import { nextMode } from '../agent/agent-mode.js';
+import { POSTURE_LABEL } from '../governance/posture.js';
+import { registerGovernanceCommand } from './governance-command.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
 import { applyRestoredSession } from '../session/startup-session.js';
 import { runSessionCommand } from './session-command.js';
@@ -353,12 +355,13 @@ const COMMANDS = [
         run: (ctx) => {
             const arg = ctx.args.trim().toLowerCase();
             if (arg === 'status') {
-                const s = ctx.controller.getPlanStatus();
-                const pending = s.pending ? ` (pending ${MODE_LABEL[s.pending]} after this run)` : '';
+                // The full posture (GOVERN / PLAN+GOVERN included), not just the gate mode.
+                const s = ctx.controller.getPostureState();
+                const pending = s.pending ? ` (pending ${POSTURE_LABEL[s.pending]} after this run)` : '';
                 // NO ROUND COUNT. The old line ended with `Ask rounds used: 3/4.`, which
                 // told the user their agent was rationing questions - a limit that no
                 // longer exists. Nothing replaced it: "0 of unlimited" is noise.
-                ctx.notify('info', `Mode: ${MODE_LABEL[s.effective]}${pending}.`);
+                ctx.notify('info', `Mode: ${POSTURE_LABEL[s.effective]}${pending}.`);
                 return;
             }
             if (arg.length > 0 && arg !== 'on' && arg !== 'off') {
@@ -618,6 +621,8 @@ const COMMANDS = [
     },
     {
         name: 'todo',
+        // Same verb parse as `run` below, so the echo is suppressed exactly when a card can appear (I-8).
+        rendersInvocationCard: (args) => args.trim().toLowerCase().split(/\s+/)[0] === 'continue',
         description: 'Todo planning: status | on | off | panel on|off | follow <mode> | ' +
             'acceptance [on|off|reset] | clear | continue',
         /**
@@ -779,6 +784,16 @@ const COMMANDS = [
                 // the more verbose of the two forms (AC-17).
                 ctx.submit(buildContinuationMessage(snapshot), {
                     userInitiated: false, todoPolicy: 'continue',
+                    // The transcript shows a card instead of the canned paragraph; the payload above
+                    // is unchanged (tui-invocation-cards I-1).
+                    ...(ctx.invocationCards === false ? {} : {
+                        invocation: {
+                            variant: 'todo',
+                            name: 'continue',
+                            commandLine: '/todo continue',
+                            facts: [`${Math.max(0, snapshot.total - snapshot.doneCount)} of ${snapshot.total} steps left`],
+                        },
+                    }),
                 });
                 return;
             }
@@ -1346,6 +1361,9 @@ export function registerBuiltinCommands(registry) {
     // now live in the settings screen, and this command is the ACT: arm forced mode
     // and start work. Unconditional, for the reason `/subagent` above records.
     registerTeamCommand(registry);
+    // `/gov` (governance-mode 11.3). Unconditional, like `/team` and for the same reason: the
+    // session where governance cannot run is exactly where a user asks the command why.
+    registerGovernanceCommand(registry);
     // The keyboard drawer (`Ctrl+G` / `/keys`) and the task label (`/task`). Two
     // registrations, no new mechanism: `/keys` sets the panel's pre-filter and opens
     // the same overlay `Ctrl+G` opens, and `/task` reports what the header cell says.

package/dist/commands/governance-command.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `/gov`: enter, leave and inspect governance mode (governance-mode 11.3).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THE GUARD ORDER IS A CONTRACT, and it is the order `/team` uses (and for the same
+ * reasons), not an alphabetical one:
+ *
+ *   status / help / runs / report / board
+ *                                 - questions, answerable in ANY session, including the
+ *                                   ones where governance cannot run (that is where users
+ *                                   ask why). `report` only READS files already on disk.
+ *   off                           - leaving is always possible, even mid-stage.
+ *   available?                    - `on` / `plan` / `resume` / `pause` name the exact reason.
+ *   not busy                      - half a team dispatch under one posture and half under
+ *                                   another leaves a result nothing can explain.
+ *   act                           - switch posture / submit the resume turn / abort.
+ *
+ * `pause` sits BETWEEN `available?` and `not busy` and never takes the busy refusal: a stage
+ * running is exactly when someone wants to pause, and the request is cooperative (nothing is
+ * stopped), unlike `abort`.
+ *
+ * EVERY POSTURE CHANGE BELOW IS FOLLOWED BY A NOTICE OR TOAST IN THE SAME BRANCH: a
+ * posture change produces no `AgentEvent`, so without one the badge would wait for an
+ * unrelated state change to repaint (the lesson of team-command-forced-dispatch P1-6).
+ */
+import type { CommandContext, CommandRegistry } from './registry.js';
+/** The fixed English turn that makes the orchestrator call `gov_run resume` (11.3). */
+export declare function resumeTurnText(runId: string): string;
+/** `500`, `500k`, `2m`, `off`/`0`. NaN when unparseable. */
+export declare function parseBudgetTokens(raw: string): number;
+/** The command body; `registerGovernanceCommand` is the only registration site. */
+export declare function runGovernanceCommand(ctx: CommandContext): Promise<void>;
+/** Registered from `builtins.ts` with one line, next to every other subsystem. */
+export declare function registerGovernanceCommand(registry: CommandRegistry): void;

package/dist/commands/governance-command.js

@@ -0,0 +1,304 @@
+/**
+ * `/gov`: enter, leave and inspect governance mode (governance-mode 11.3).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * THE GUARD ORDER IS A CONTRACT, and it is the order `/team` uses (and for the same
+ * reasons), not an alphabetical one:
+ *
+ *   status / help / runs / report / board
+ *                                 - questions, answerable in ANY session, including the
+ *                                   ones where governance cannot run (that is where users
+ *                                   ask why). `report` only READS files already on disk.
+ *   off                           - leaving is always possible, even mid-stage.
+ *   available?                    - `on` / `plan` / `resume` / `pause` name the exact reason.
+ *   not busy                      - half a team dispatch under one posture and half under
+ *                                   another leaves a result nothing can explain.
+ *   act                           - switch posture / submit the resume turn / abort.
+ *
+ * `pause` sits BETWEEN `available?` and `not busy` and never takes the busy refusal: a stage
+ * running is exactly when someone wants to pause, and the request is cooperative (nothing is
+ * stopped), unlike `abort`.
+ *
+ * EVERY POSTURE CHANGE BELOW IS FOLLOWED BY A NOTICE OR TOAST IN THE SAME BRANCH: a
+ * posture change produces no `AgentEvent`, so without one the badge would wait for an
+ * unrelated state change to repaint (the lesson of team-command-forced-dispatch P1-6).
+ */
+import { GOV_ABORTED_NOTICE, GOV_BUDGET_OFF_NOTICE, GOV_BUDGET_USAGE, GOV_COMMAND_SUMMARY, GOV_NO_RUN_NOTICE, GOV_NO_RUNS_NOTICE, GOV_NO_STAGE_NOTICE, GOV_OFF_NOTICE, GOV_OFF_WITH_RUN_NOTICE, GOV_PAUSE_ALREADY_NOTICE, GOV_PAUSE_CANCELLED_TOAST, GOV_PAUSE_ESCALATED_NOTICE, GOV_PAUSE_NONE_PENDING_NOTICE, GOV_PAUSE_NO_RUN_NOTICE, GOV_REPORT_NO_RUN_NOTICE, GOV_STAGE_BUSY_NOTICE, buildGovHelpText, formatGovStatus, govBudgetSetNotice, govPausePendingToast, govPausedNowToast, govReportBadIdNotice, govReportMissingNotice, govUnavailableNotice, posturePendingToast, postureAppliedToast, stageRunningToast, RESTART_REQUIRED_TEXT, } from '../governance/copy.js';
+import { RUN_ID_PATTERN } from '../governance/limits.js';
+import { isGovernancePosture } from '../governance/posture.js';
+import { formatReportNotice, formatRunsTable } from './governance-runs-table.js';
+const USAGE = 'Usage: /gov [status|on|plan|off|board|runs|report [runId]|resume [runId]|pause [cancel]' +
+    '|abort|budget <n|off>|help]';
+/** The fixed English turn that makes the orchestrator call `gov_run resume` (11.3). */
+export function resumeTurnText(runId) {
+    return `Resume governance run ${runId}.`;
+}
+function unavailableText(ctx) {
+    const availability = ctx.controller.isGovernanceAvailable();
+    if (availability.ok)
+        return null;
+    return availability.reason === 'restart_required'
+        ? RESTART_REQUIRED_TEXT
+        : govUnavailableNotice(availability.reason);
+}
+function reportStatus(ctx) {
+    const snapshot = ctx.controller.getGovernanceSnapshot();
+    ctx.notify('info', formatGovStatus({
+        posture: ctx.controller.getPosture(),
+        availability: ctx.controller.isGovernanceAvailable(),
+        run: snapshot
+            ? {
+                runId: snapshot.runId,
+                phase: snapshot.phase,
+                phaseCount: snapshot.phaseCount,
+                stage: snapshot.stage,
+                status: snapshot.status,
+                health: snapshot.health,
+                pauseRequested: snapshot.pauseRequested === true,
+            }
+            : null,
+        dispatchPlan: snapshot ? ctx.controller.getGovernanceDispatchPlan() : null,
+    }));
+}
+async function reportRuns(ctx) {
+    const runs = await ctx.controller.listGovernanceRuns();
+    if (runs.length === 0) {
+        ctx.notify('info', GOV_NO_RUNS_NOTICE);
+        return;
+    }
+    // Two columns less than the terminal: the transcript indents notices.
+    ctx.notify('info', formatRunsTable(runs, (process.stdout.columns ?? 80) - 2));
+}
+/** `/gov report [runId]`: a stored report as one transcript notice (read-only). */
+async function report(ctx) {
+    const raw = ctx.args.trim().split(/\s+/)[1] ?? '';
+    // Checked HERE as well as in the reader: a malformed id never reaches the controller,
+    // let alone the file system (it would become a path segment).
+    if (raw !== '' && !RUN_ID_PATTERN.test(raw)) {
+        ctx.notify('warn', govReportBadIdNotice(raw));
+        return;
+    }
+    const result = await ctx.controller.readGovernanceReport(raw === '' ? undefined : raw);
+    switch (result.kind) {
+        case 'ok':
+            ctx.notify('info', formatReportNotice(result));
+            return;
+        case 'missing':
+            ctx.notify('info', govReportMissingNotice(result.runId));
+            return;
+        case 'bad_id':
+            ctx.notify('warn', govReportBadIdNotice(raw));
+            return;
+        case 'no_run':
+            ctx.notify('info', GOV_REPORT_NO_RUN_NOTICE);
+    }
+}
+/** `/gov pause [cancel]`: stop at the next clean stage boundary; nothing is killed. */
+async function pause(ctx) {
+    const unavailable = unavailableText(ctx);
+    if (unavailable !== null) {
+        ctx.notify('warn', unavailable);
+        return;
+    }
+    const arg = (ctx.args.trim().split(/\s+/)[1] ?? '').toLowerCase();
+    if (arg === 'cancel') {
+        if (ctx.controller.cancelGovernancePause())
+            ctx.toast('info', GOV_PAUSE_CANCELLED_TOAST);
+        else
+            ctx.notify('info', GOV_PAUSE_NONE_PENDING_NOTICE);
+        return;
+    }
+    if (arg !== '') {
+        ctx.notify('warn', `Unknown argument "${arg}". Usage: /gov pause [cancel]`);
+        return;
+    }
+    const outcome = await ctx.controller.requestGovernancePause();
+    const snapshot = ctx.controller.getGovernanceSnapshot();
+    switch (outcome) {
+        case 'pending':
+            ctx.toast('info', govPausePendingToast(snapshot?.stage ?? null));
+            return;
+        case 'paused_now':
+            ctx.toast('info', govPausedNowToast(snapshot?.runId ?? ''));
+            return;
+        case 'already_paused':
+            ctx.notify('info', GOV_PAUSE_ALREADY_NOTICE);
+            return;
+        case 'escalated':
+            ctx.notify('info', GOV_PAUSE_ESCALATED_NOTICE);
+            return;
+        case 'no_run':
+            ctx.notify('info', GOV_PAUSE_NO_RUN_NOTICE);
+    }
+}
+/** Switch posture through the App's single write path and report what was ADOPTED. */
+function switchPosture(ctx, target) {
+    if (ctx.applyPosture === undefined) {
+        ctx.notify('warn', 'Governance is unavailable here: this surface cannot change posture.');
+        return null;
+    }
+    const applied = ctx.applyPosture(target);
+    if (applied.pending !== null) {
+        ctx.toast('info', ctx.controller.isGovernanceStageRunning()
+            ? stageRunningToast(applied.pending)
+            : posturePendingToast(applied.pending));
+    }
+    else {
+        ctx.toast('info', postureAppliedToast(applied.effective));
+    }
+    return applied;
+}
+function leave(ctx) {
+    const wasGoverned = isGovernancePosture(ctx.controller.getPosture());
+    const snapshot = ctx.controller.getGovernanceSnapshot();
+    if (!wasGoverned && ctx.controller.getPostureState().pending === null) {
+        ctx.notify('info', GOV_OFF_NOTICE);
+        return;
+    }
+    const applied = switchPosture(ctx, 'build');
+    // A deferred change (a stage is running) already said so in its toast.
+    if (applied === null || applied.pending !== null)
+        return;
+    // Leaving never kills an in-flight stage; the run is left resumable.
+    const hasRun = snapshot !== null && snapshot.status !== 'closed' && snapshot.status !== 'abandoned';
+    ctx.notify('info', hasRun ? GOV_OFF_WITH_RUN_NOTICE : GOV_OFF_NOTICE);
+}
+function enter(ctx, target) {
+    const unavailable = unavailableText(ctx);
+    if (unavailable !== null) {
+        ctx.notify('warn', unavailable);
+        return;
+    }
+    if (ctx.controller.isTeamBusy()) {
+        ctx.notify('warn', ctx.controller.isGovernanceStageRunning()
+            ? GOV_STAGE_BUSY_NOTICE
+            : 'Cannot change posture while a team dispatch is running.');
+        return;
+    }
+    switchPosture(ctx, target);
+}
+async function resume(ctx) {
+    const unavailable = unavailableText(ctx);
+    if (unavailable !== null) {
+        ctx.notify('warn', unavailable);
+        return;
+    }
+    if (ctx.controller.isTeamBusy()) {
+        ctx.notify('warn', GOV_STAGE_BUSY_NOTICE);
+        return;
+    }
+    const requested = ctx.args.trim().split(/\s+/)[1] ?? '';
+    const runId = await ctx.controller.findResumableGovernanceRun(requested);
+    if (runId === null) {
+        ctx.notify('info', GOV_NO_RUN_NOTICE);
+        return;
+    }
+    if (ctx.controller.getPosture() !== 'govern' && switchPosture(ctx, 'govern') === null)
+        return;
+    // `userInitiated: false` keeps the canned turn out of the prompt history, exactly like
+    // `/todo continue` (todo-plan-followthrough C-12).
+    ctx.submit(resumeTurnText(runId), {
+        userInitiated: false,
+        ...(ctx.invocationCards === false ? {} : {
+            invocation: {
+                variant: 'govern',
+                name: 'resume',
+                commandLine: requested === '' ? '/gov resume' : `/gov resume ${requested}`,
+                facts: [`run ${runId.slice(0, 8)}`],
+            },
+        }),
+    });
+}
+function abort(ctx) {
+    if (!ctx.controller.isGovernanceStageRunning()) {
+        ctx.notify('info', GOV_NO_STAGE_NOTICE);
+        return;
+    }
+    ctx.controller.abortGovernanceStage();
+    ctx.notify('info', GOV_ABORTED_NOTICE);
+}
+/** `500`, `500k`, `2m`, `off`/`0`. NaN when unparseable. */
+export function parseBudgetTokens(raw) {
+    const text = raw.trim().toLowerCase();
+    if (text === 'off' || text === '0')
+        return 0;
+    const match = /^(\d+(?:\.\d+)?)([km]?)$/.exec(text);
+    if (!match)
+        return Number.NaN;
+    const scale = match[2] === 'm' ? 1_000_000 : match[2] === 'k' ? 1_000 : 1;
+    return Math.floor(Number(match[1]) * scale);
+}
+function setBudget(ctx) {
+    const raw = ctx.args.trim().split(/\s+/)[1];
+    if (raw === undefined) {
+        ctx.notify('info', GOV_BUDGET_USAGE);
+        return;
+    }
+    const tokens = parseBudgetTokens(raw);
+    if (!Number.isFinite(tokens) || tokens < 0) {
+        ctx.notify('warn', GOV_BUDGET_USAGE);
+        return;
+    }
+    // BOTH CALLS, AND NEITHER MAY BE DROPPED (the `/fast` rule): the setter makes the running
+    // session honour it and re-renders the prompt; persisting alone changes nothing until
+    // relaunch, and the setter alone is forgotten by morning.
+    const adopted = ctx.controller.setGovernanceConfig({ budgetTokens: tokens });
+    ctx.persistConfig({ governance: adopted });
+    ctx.notify('info', adopted.budgetTokens === 0 ? GOV_BUDGET_OFF_NOTICE : govBudgetSetNotice(adopted.budgetTokens));
+}
+/** The command body; `registerGovernanceCommand` is the only registration site. */
+export async function runGovernanceCommand(ctx) {
+    const verb = (ctx.args.trim().split(/\s+/)[0] ?? '').toLowerCase();
+    switch (verb) {
+        case '':
+        case 'status':
+            reportStatus(ctx);
+            return;
+        case 'help':
+            ctx.notify('info', buildGovHelpText(ctx.controller.getGovernanceConfig().minAskRounds));
+            return;
+        case 'runs':
+            await reportRuns(ctx);
+            return;
+        case 'report':
+            await report(ctx);
+            return;
+        case 'board':
+            ctx.setOverlay('governance');
+            return;
+        case 'off':
+            leave(ctx);
+            return;
+        case 'on':
+            enter(ctx, 'govern');
+            return;
+        case 'plan':
+            enter(ctx, 'plan_govern');
+            return;
+        case 'resume':
+            await resume(ctx);
+            return;
+        case 'pause':
+            await pause(ctx);
+            return;
+        case 'abort':
+            abort(ctx);
+            return;
+        case 'budget':
+            setBudget(ctx);
+            return;
+        default:
+            ctx.notify('warn', `Unknown argument "${verb}". ${USAGE}`);
+    }
+}
+/** Registered from `builtins.ts` with one line, next to every other subsystem. */
+export function registerGovernanceCommand(registry) {
+    registry.register({
+        name: 'gov',
+        // Same verb parse as `runGovernanceCommand`, so the echo is suppressed exactly when a card can appear (I-8).
+        rendersInvocationCard: (args) => (args.trim().split(/\s+/)[0] ?? '').toLowerCase() === 'resume',
+        description: GOV_COMMAND_SUMMARY,
+        run: (ctx) => runGovernanceCommand(ctx),
+    });
+}

package/dist/commands/governance-runs-table.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The `/gov runs` table and the `/gov report` notice text (governance-mode-v1-1 7.1, 7.2).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`. Everything this module
+ * ADDS is ASCII (column rules, the `...` cut mark, `n/a`); the only non-ASCII that can pass
+ * through is the user's own goal text, which is measured and cut in terminal CELLS
+ * (`ui/layout/cells.ts`), never in code units, so a CJK goal cannot push a row past the edge.
+ *
+ * PURE. The command hands in rows and a width; nothing here reads the terminal or the clock
+ * except through arguments, which is what lets the width matrix be tested.
+ *
+ * THE COLUMNS DEGRADE BY WIDTH, in the order of how much each one is missed: first
+ * HEALTH and COST go (they are the cheapest to look up again in `/gov board`), then UPDATED
+ * and TOKENS, and at the narrowest only `RUN STATUS PHASE GOAL` remain. The goal gets
+ * whatever is left and is cut with `...`.
+ */
+import type { GovernanceRunRow } from '../agent/governance-wiring.js';
+interface Column {
+    key: 'run' | 'status' | 'phase' | 'health' | 'tokens' | 'cost' | 'updated' | 'updatedShort';
+    title: string;
+    width: number;
+}
+/** `184k`, `2.1M`, `950`. */
+export declare function formatTokensCompact(tokens: number): string;
+/** `$1.42`; unknown pricing is `n/a`, never `$0.00` (v1 8.5 / C-11). */
+export declare function formatCostCell(costUsd: number | null): string;
+/** `2026-10-24 14:02` in local time. */
+export declare function formatStamp(ms: number): string;
+/** One row of the table, already cut to `cols` cells. */
+export declare function formatRunRow(row: GovernanceRunRow, keys: ReadonlyArray<Column['key']>, cols: number): string;
+/** The whole `/gov runs` notice for `cols` terminal columns. */
+export declare function formatRunsTable(runs: readonly GovernanceRunRow[], cols: number): string;
+/** The transcript text for a found report: header, body capped by lines, full path. */
+export declare function formatReportNotice(input: {
+    runId: string;
+    file: string;
+    text: string;
+    path: string;
+}): string;
+export {};

package/dist/commands/governance-runs-table.js

@@ -0,0 +1,130 @@
+/**
+ * The `/gov runs` table and the `/gov report` notice text (governance-mode-v1-1 7.1, 7.2).
+ *
+ * ASCII ONLY: `src/commands/**` is inside `glyphs.test.ts::inScope`. Everything this module
+ * ADDS is ASCII (column rules, the `...` cut mark, `n/a`); the only non-ASCII that can pass
+ * through is the user's own goal text, which is measured and cut in terminal CELLS
+ * (`ui/layout/cells.ts`), never in code units, so a CJK goal cannot push a row past the edge.
+ *
+ * PURE. The command hands in rows and a width; nothing here reads the terminal or the clock
+ * except through arguments, which is what lets the width matrix be tested.
+ *
+ * THE COLUMNS DEGRADE BY WIDTH, in the order of how much each one is missed: first
+ * HEALTH and COST go (they are the cheapest to look up again in `/gov board`), then UPDATED
+ * and TOKENS, and at the narrowest only `RUN STATUS PHASE GOAL` remain. The goal gets
+ * whatever is left and is cut with `...`.
+ */
+import { GOV_REPORT_MAX_LINES } from '../governance/copy.js';
+import { cellWidth, fitCells, padCells } from '../ui/layout/cells.js';
+const UNFINISHED = new Set(['executing', 'paused', 'escalated']);
+const MIN_GOAL_CELLS = 8;
+const GAP = '  ';
+const COLUMNS = {
+    run: { key: 'run', title: 'RUN', width: 13 },
+    status: { key: 'status', title: 'STATUS', width: 9 },
+    phase: { key: 'phase', title: 'PHASE', width: 5 },
+    health: { key: 'health', title: 'HEALTH', width: 6 },
+    tokens: { key: 'tokens', title: 'TOKENS', width: 7 },
+    cost: { key: 'cost', title: 'COST', width: 8 },
+    updated: { key: 'updated', title: 'UPDATED', width: 16 },
+    // The same column without the year, for widths where the goal text is worth more.
+    updatedShort: { key: 'updatedShort', title: 'UPDATED', width: 11 },
+};
+/** Column sets from widest to narrowest; the first whose goal still gets room wins. */
+const TIERS = [
+    ['run', 'status', 'phase', 'health', 'tokens', 'cost', 'updated'],
+    ['run', 'status', 'phase', 'tokens', 'updatedShort'],
+    ['run', 'status', 'phase', 'tokens'],
+    ['run', 'status', 'phase'],
+];
+/** `184k`, `2.1M`, `950`. */
+export function formatTokensCompact(tokens) {
+    if (tokens >= 1_000_000)
+        return `${(tokens / 1_000_000).toFixed(1)}M`;
+    if (tokens >= 10_000)
+        return `${Math.round(tokens / 1_000)}k`;
+    if (tokens >= 1_000)
+        return `${(tokens / 1_000).toFixed(1)}k`;
+    return String(Math.max(0, Math.round(tokens)));
+}
+/** `$1.42`; unknown pricing is `n/a`, never `$0.00` (v1 8.5 / C-11). */
+export function formatCostCell(costUsd) {
+    if (costUsd === null)
+        return 'n/a';
+    return costUsd < 0.01 && costUsd > 0 ? '<$0.01' : `$${costUsd.toFixed(2)}`;
+}
+function two(n) {
+    return String(n).padStart(2, '0');
+}
+/** `2026-10-24 14:02` in local time. */
+export function formatStamp(ms) {
+    const d = new Date(ms);
+    if (Number.isNaN(d.getTime()))
+        return '-';
+    const date = `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`;
+    return `${date} ${two(d.getHours())}:${two(d.getMinutes())}`;
+}
+function cellFor(key, row, digest) {
+    switch (key) {
+        case 'run':
+            return row.runId;
+        case 'status':
+            return row.status;
+        case 'phase':
+            return digest === undefined ? '-' : `${digest.phase}/${digest.phaseCount}`;
+        case 'health':
+            return digest?.health == null ? '-' : String(digest.health);
+        case 'tokens':
+            return digest === undefined ? '-' : formatTokensCompact(digest.tokens);
+        case 'cost':
+            return digest === undefined ? '-' : formatCostCell(digest.costUsd);
+        case 'updated':
+            return formatStamp(row.updatedAt);
+        case 'updatedShort': {
+            const stamp = formatStamp(row.updatedAt);
+            return stamp === '-' ? stamp : stamp.slice(5);
+        }
+    }
+}
+function prefixWidth(keys) {
+    const widths = keys.reduce((sum, key) => sum + COLUMNS[key].width, 0);
+    return 2 + widths + GAP.length * keys.length;
+}
+function pickTier(cols) {
+    const last = TIERS[TIERS.length - 1];
+    return (TIERS.find((keys) => cols - prefixWidth(keys) - 2 >= MIN_GOAL_CELLS + 4) ?? last);
+}
+/** One row of the table, already cut to `cols` cells. */
+export function formatRunRow(row, keys, cols) {
+    const cells = keys.map((key) => padCells(cellFor(key, row, row.digest), COLUMNS[key].width));
+    const star = UNFINISHED.has(row.status) ? ' *' : '';
+    const goalRoom = cols - prefixWidth(keys) - star.length;
+    const goal = goalRoom >= 4 ? fitCells(row.goal.replace(/\s+/g, ' '), goalRoom) : '';
+    const line = `  ${cells.join(GAP)}${GAP}${goal}${star}`.trimEnd();
+    return cellWidth(line) <= cols ? line : fitCells(line, cols);
+}
+/** The whole `/gov runs` notice for `cols` terminal columns. */
+export function formatRunsTable(runs, cols) {
+    const width = Number.isFinite(cols) ? Math.max(20, Math.floor(cols)) : 80;
+    const keys = pickTier(width);
+    const header = `  ${keys.map((k) => padCells(COLUMNS[k].title, COLUMNS[k].width)).join(GAP)}`;
+    const lines = ['Governed runs (newest first):', header.trimEnd()];
+    for (const run of runs)
+        lines.push(formatRunRow(run, keys, width));
+    if (runs.some((run) => UNFINISHED.has(run.status))) {
+        lines.push('* unfinished: /gov resume <runId>');
+    }
+    return lines.join('\n');
+}
+/** The transcript text for a found report: header, body capped by lines, full path. */
+export function formatReportNotice(input) {
+    const body = input.text.replace(/\r\n/g, '\n').trimEnd().split('\n');
+    const shown = body.slice(0, GOV_REPORT_MAX_LINES);
+    const more = body.length - shown.length;
+    return [
+        `Report for run ${input.runId} (${input.file}):`,
+        ...shown,
+        ...(more > 0 ? [`... (${more} more lines; see the file below)`] : []),
+        `Full file: ${input.path}`,
+    ].join('\n');
+}

package/dist/commands/index-build.d.ts

@@ -26,6 +26,14 @@ export declare function hasProjectIndex(cwd: string): boolean;
  * second time (the skill's own edge-case list says exactly that).
  */
 export declare function indexBuildInvocationArgs(hasExistingIndex: boolean): string;
+/**
+ * True when `args` is one of the two machine-written sentences above. The invocation
+ * card uses this to NOT present them as something the user said (tui-invocation-cards
+ * RV-3): it shows a `ctrl+i` fact instead. Same file as the generator so the two cannot
+ * drift - a reworded sentence that stops matching would silently put machine words
+ * back on the card.
+ */
+export declare function isIndexBuildArgs(args: string): boolean;
 export interface IndexConfirmInput {
     cwd: string;
     /** True when `.claude-index/index.md` already exists (rebuild, not first build). */

package/dist/commands/index-build.js

@@ -40,6 +40,17 @@ export function indexBuildInvocationArgs(hasExistingIndex) {
         ? 'The user pressed Ctrl+I and confirmed. Rebuild the project index for this workspace now, reusing the existing .claude-index/config.md preferences.'
         : 'The user pressed Ctrl+I and confirmed. Build the project index for this workspace now, asking the configuration questions first.';
 }
+/**
+ * True when `args` is one of the two machine-written sentences above. The invocation
+ * card uses this to NOT present them as something the user said (tui-invocation-cards
+ * RV-3): it shows a `ctrl+i` fact instead. Same file as the generator so the two cannot
+ * drift - a reworded sentence that stops matching would silently put machine words
+ * back on the card.
+ */
+export function isIndexBuildArgs(args) {
+    const text = args.trim();
+    return text === indexBuildInvocationArgs(true) || text === indexBuildInvocationArgs(false);
+}
 /**
  * The Yes/No dialog body. It names WHAT WILL BE WRITTEN - an index run is a
  * batch of file writes the user never typed, and the one question a confirm