@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/ui/layout/governance-board.js

@@ -0,0 +1,382 @@
+/**
+ * The `/gov board` overlay's model and geometry (governance-mode section 10.5): the tab
+ * model, the data adapters, the row builders and the scroll arithmetic - every decision
+ * the overlay makes, in pure code.
+ *
+ * Pure and total: no Ink, no clock (`now` is not even needed: rows carry sequence
+ * numbers, not times), no I/O. ASCII ONLY.
+ *
+ * TWO DATA SOURCES, ONE SHAPE. The live `GovernanceSnapshot` knows the roster and the
+ * ticker; the work-package matrix, the full ledger and the claims live in `RunState` /
+ * `LedgerState`. `GovernanceBoardData` is the UI's own flat projection of all of it, with
+ * two builders: `boardDataFromSnapshot` (what the renderer always has) and
+ * `boardDataFromRun` (what the wiring can supply). A board built from the snapshot alone
+ * still reads correctly - the tabs it cannot fill say so instead of going blank.
+ *
+ * EVERY ROW IS ONE TERMINAL ROW. Rows are `Segment[]` rendered `wrap="truncate"`, so
+ * scrolling is arithmetic on a list length (`sliceWindow`), never a re-measure.
+ */
+import { govChildStatus, labelTag, scoreText, scoreToneKey, segment, signedDeltaText, sortRoster, statusTone, } from '../governance-status.js';
+import { BOARD_EMPTY, BOARD_TAB_LABEL, ROLE_LABEL, STATE_WORD, WORKING_VERB, replacedByText, } from '../governance-copy.js';
+import { statusMarkerCell } from '../team-status.js';
+import { cellWidth, fitCells, padCells } from './cells.js';
+import { sliceWindow } from './overlay-window.js';
+export const BOARD_TABS = ['roster', 'work', 'ledger', 'claims'];
+/** Terminals narrower than this get the single-column form with a `1/4` pager. */
+export const BOARD_NARROW_COLS = 80;
+/** Recent ledger lines shown under each identity on the roster tab (spec 10.5). */
+export const BOARD_RECENT_PER_AGENT = 5;
+/** Ledger rows kept in the projection, newest first. */
+export const BOARD_LEDGER_MAX = 200;
+/** The tab `delta` steps away, wrapping at both ends. */
+export function stepTab(tab, delta) {
+    const index = BOARD_TABS.indexOf(tab);
+    const size = BOARD_TABS.length;
+    return BOARD_TABS[(((index + delta) % size) + size) % size];
+}
+export function tabIndex(tab) {
+    return BOARD_TABS.indexOf(tab);
+}
+/** What the renderer always has: the live snapshot. WPs and claims stay empty. */
+export function boardDataFromSnapshot(snapshot, boardPath = null) {
+    const ledger = [...snapshot.recent]
+        .sort((a, b) => b.at - a.at)
+        .map((row, index) => ({
+        seq: snapshot.recent.length - index,
+        agentId: row.agentId,
+        code: row.code,
+        delta: row.delta,
+        provisional: row.provisional,
+        by: '',
+        reason: row.reason,
+        evidence: '',
+        capped: false,
+    }));
+    return { snapshot, workPackages: [], ledger, claims: [], boardPath };
+}
+function workPackageRow(wp) {
+    return {
+        id: wp.id,
+        title: wp.title,
+        status: wp.status,
+        reworkCount: wp.reworkCount,
+        assignee: wp.assignee ?? '',
+        reviewer: wp.reviewer ?? '',
+        tester: wp.tester ?? '',
+        fileCount: wp.files.length,
+        blockedAt: wp.blockedAt ?? '',
+    };
+}
+function claimRow(claim) {
+    return {
+        id: claim.id,
+        kind: 'claim',
+        status: claim.status,
+        detail: claim.kind,
+        subject: `${claim.raisedBy} -> ${claim.against} (${claim.wpId})`,
+        text: claim.rulingText ?? claim.justification,
+    };
+}
+function escalationRow(esc) {
+    return {
+        id: esc.id,
+        kind: 'escalation',
+        status: esc.status,
+        detail: esc.kind,
+        subject: esc.wpId ?? (esc.phase === undefined ? '' : `phase ${esc.phase + 1}`),
+        text: esc.ruling ?? esc.topic,
+    };
+}
+function ledgerRows(ledger) {
+    const rows = [];
+    for (const agent of Object.values(ledger.agents)) {
+        for (const entry of agent.history) {
+            rows.push({
+                seq: entry.seq,
+                agentId: agent.id,
+                code: entry.code,
+                delta: entry.delta,
+                provisional: entry.settlement === 'provisional',
+                by: entry.by,
+                reason: entry.reason,
+                evidence: entry.evidence ?? '',
+                capped: entry.capped !== undefined,
+            });
+        }
+    }
+    return rows.sort((a, b) => b.seq - a.seq).slice(0, BOARD_LEDGER_MAX);
+}
+/** The full projection, for a wiring that can read the run and the ledger. */
+export function boardDataFromRun(input) {
+    const { snapshot, run, ledger } = input;
+    return {
+        snapshot,
+        workPackages: run.wpOrder
+            .map((id) => run.workPackages[id])
+            .filter((wp) => wp !== undefined)
+            .map(workPackageRow),
+        ledger: ledgerRows(ledger),
+        claims: [...run.claims.map(claimRow), ...run.escalations.map(escalationRow)],
+        boardPath: input.boardPath ?? null,
+    };
+}
+function boardLine(key, segments) {
+    return { key, segments };
+}
+function emptyLine(text) {
+    return [boardLine('empty', [segment(text, 'muted')])];
+}
+function head(key, text) {
+    return boardLine(key, [segment(text, 'muted')]);
+}
+function agentState(row) {
+    return row.state === 'working' ? WORKING_VERB[row.role] : STATE_WORD[row.state];
+}
+function recentLines(data, agentId) {
+    return data.ledger
+        .filter((row) => row.agentId === agentId)
+        .slice(0, BOARD_RECENT_PER_AGENT)
+        .map((row) => boardLine(`${agentId}:r${row.seq}`, [
+        segment('      ', 'muted'),
+        segment(padCells(signedDeltaText(row.delta, row.provisional), 7), row.delta >= 0 ? 'ok' : 'error'),
+        segment(padCells(row.code, 5), 'muted'),
+        segment(row.reason.replace(/\s+/g, ' '), 'text'),
+        ...(row.capped ? [segment(` [capped]`, 'warn')] : []),
+    ]));
+}
+function rosterIdentityLine(row, glyphs, narrow) {
+    const status = govChildStatus(row.state);
+    const tone = statusTone(status);
+    const score = row.confirmed === null ? '-' : scoreText(row.confirmed);
+    const prov = row.provisional > 0 ? `+${row.provisional}P` : '';
+    const tag = labelTag(row.label);
+    const marker = ` ${statusMarkerCell(status, glyphs)} `;
+    if (narrow) {
+        return boardLine(row.id, [
+            segment(marker, tone),
+            segment(padCells(row.id, 9), 'primary'),
+            segment(padCells(ROLE_LABEL[row.role], 5), 'muted'),
+            segment(padCells(score, 5), scoreToneKey(row.label), true),
+            segment(prov, 'muted'),
+            ...(tag === '' ? [] : [segment(` ${tag}`, scoreToneKey(row.label), true)]),
+        ]);
+    }
+    const state = row.state === 'eliminated' ? replacedByText(row.replacedBy) : agentState(row);
+    return boardLine(row.id, [
+        segment(marker, tone),
+        segment(padCells(row.id, 10), 'primary'),
+        segment(padCells(ROLE_LABEL[row.role], 6), 'muted'),
+        segment(padCells(`g${row.generation}`, 4), 'muted'),
+        segment(padCells(score, 6), scoreToneKey(row.label), true),
+        segment(padCells(prov, 7), 'muted'),
+        segment(padCells(tag, 8), scoreToneKey(row.label), true),
+        segment(padCells(state, 22), tone),
+        segment(row.wpId ?? '-', 'text'),
+    ]);
+}
+function rosterRows(data, glyphs, narrow) {
+    const roster = sortRoster(data.snapshot.roster);
+    if (roster.length === 0)
+        return emptyLine(BOARD_EMPTY.roster);
+    const lines = narrow
+        ? []
+        : [head('h', '    id        role  gen score  prov   label   state                 work')];
+    for (const row of roster) {
+        lines.push(rosterIdentityLine(row, glyphs, narrow));
+        lines.push(...recentLines(data, row.id));
+    }
+    return lines;
+}
+const WP_TONE = {
+    pending: 'pending',
+    dev_running: 'running',
+    awaiting_review: 'pending',
+    review_running: 'running',
+    awaiting_test: 'pending',
+    test_running: 'running',
+    rework: 'warn',
+    tested_ok: 'ok',
+    integrated: 'ok',
+    blocked: 'error',
+    dropped: 'muted',
+};
+function workRows(data, narrow) {
+    if (data.workPackages.length === 0)
+        return emptyLine(BOARD_EMPTY.work);
+    const lines = narrow
+        ? []
+        : [head('h', 'wp          status            rw  dev      rev      test     files  title')];
+    for (const wp of data.workPackages) {
+        const status = wp.blockedAt === '' ? wp.status : `${wp.status}@${wp.blockedAt}`;
+        if (narrow) {
+            lines.push(boardLine(wp.id, [
+                segment(padCells(wp.id, 12), 'primary'),
+                segment(status, WP_TONE[wp.status]),
+                ...(wp.reworkCount > 0 ? [segment(` rw${wp.reworkCount}`, 'warn')] : []),
+            ]));
+            lines.push(boardLine(`${wp.id}:t`, [segment(`  ${wp.title}`, 'muted')]));
+            continue;
+        }
+        lines.push(boardLine(wp.id, [
+            segment(padCells(wp.id, 12), 'primary'),
+            segment(padCells(status, 18), WP_TONE[wp.status]),
+            segment(padCells(String(wp.reworkCount), 4), wp.reworkCount > 0 ? 'warn' : 'muted'),
+            segment(padCells(wp.assignee || '-', 9), 'text'),
+            segment(padCells(wp.reviewer || '-', 9), 'text'),
+            segment(padCells(wp.tester || '-', 9), 'text'),
+            segment(padCells(String(wp.fileCount), 7), 'muted'),
+            segment(wp.title, 'muted'),
+        ]));
+    }
+    return lines;
+}
+function ledgerBoardRows(data, narrow) {
+    if (data.ledger.length === 0)
+        return emptyLine(BOARD_EMPTY.ledger);
+    const lines = narrow
+        ? []
+        : [head('h', '#      agent     delta   code  by                 reason')];
+    for (const row of data.ledger) {
+        const tone = row.delta >= 0 ? 'ok' : 'error';
+        const amount = signedDeltaText(row.delta, row.provisional);
+        const reason = row.reason.replace(/\s+/g, ' ');
+        const cap = row.capped ? [segment(' [capped]', 'warn')] : [];
+        if (narrow) {
+            lines.push(boardLine(`l${row.seq}:${row.agentId}`, [
+                segment(padCells(row.agentId, 9), 'primary'),
+                segment(padCells(amount, 7), tone),
+                segment(padCells(row.code, 5), 'muted'),
+                segment(reason, 'text'),
+                ...cap,
+            ]));
+        }
+        else {
+            lines.push(boardLine(`l${row.seq}:${row.agentId}`, [
+                segment(padCells(String(row.seq), 7), 'muted'),
+                segment(padCells(row.agentId, 10), 'primary'),
+                segment(padCells(amount, 8), tone),
+                segment(padCells(row.code, 6), 'muted'),
+                segment(padCells(row.by, 19), 'muted'),
+                segment(reason, 'text'),
+                ...cap,
+            ]));
+        }
+        if (row.evidence !== '') {
+            lines.push(boardLine(`l${row.seq}:${row.agentId}:e`, [
+                segment(`        evidence: ${row.evidence.replace(/\s+/g, ' ')}`, 'muted'),
+            ]));
+        }
+    }
+    return lines;
+}
+function claimsRows(data, narrow) {
+    if (data.claims.length === 0)
+        return emptyLine(BOARD_EMPTY.claims);
+    const lines = [];
+    for (const claim of data.claims) {
+        const open = claim.status === 'open';
+        lines.push(boardLine(claim.id, [
+            segment(padCells(claim.id, 8), 'primary'),
+            segment(padCells(claim.status, 10), open ? 'warn' : 'ok', open),
+            ...(narrow ? [] : [segment(padCells(claim.detail, 20), 'muted')]),
+            segment(claim.subject, 'text'),
+        ]));
+        if (claim.text !== '') {
+            lines.push(boardLine(`${claim.id}:t`, [
+                segment(`        ${claim.text.replace(/\s+/g, ' ')}`, 'muted'),
+            ]));
+        }
+    }
+    return lines;
+}
+function tabCount(tab, data) {
+    switch (tab) {
+        case 'roster':
+            return data.snapshot.roster.length;
+        case 'work':
+            return data.workPackages.length;
+        case 'ledger':
+            return data.ledger.length;
+        case 'claims':
+            return data.claims.filter((claim) => claim.status === 'open').length;
+    }
+}
+export function buildTabStrip(tab, data, narrow, glyphs) {
+    if (narrow) {
+        const pager = `${tabIndex(tab) + 1}/${BOARD_TABS.length}`;
+        return {
+            pager,
+            segments: [
+                segment(`${glyphs.arrowLeft} `, 'muted'),
+                segment(BOARD_TAB_LABEL[tab], 'govern', true),
+                segment(` ${pager} ${glyphs.arrowRight}`, 'muted'),
+            ],
+        };
+    }
+    const segments = [];
+    BOARD_TABS.forEach((candidate, index) => {
+        if (index > 0)
+            segments.push(segment(`  ${glyphs.midDot}  `, 'border'));
+        const active = candidate === tab;
+        const count = tabCount(candidate, data);
+        segments.push(segment(`${active ? glyphs.cursor : ' '}${BOARD_TAB_LABEL[candidate]}`, active ? 'govern' : 'muted', active));
+        if (count > 0)
+            segments.push(segment(` ${count}`, active ? 'text' : 'hint'));
+    });
+    return { segments, pager: '' };
+}
+const NO_RUN_LINES = [boardLine('norun', [segment(BOARD_EMPTY.noRun, 'muted')])];
+export function buildGovernanceBoardLayout(input) {
+    const { tab, data, glyphs } = input;
+    const narrow = input.cols < BOARD_NARROW_COLS;
+    if (data === null) {
+        const strip = { segments: [segment(BOARD_TAB_LABEL[tab], 'govern', true)], pager: '' };
+        return { narrow, tabStrip: strip, lines: NO_RUN_LINES };
+    }
+    const tabStrip = buildTabStrip(tab, data, narrow, glyphs);
+    switch (tab) {
+        case 'roster':
+            return { narrow, tabStrip, lines: rosterRows(data, glyphs, narrow) };
+        case 'work':
+            return { narrow, tabStrip, lines: workRows(data, narrow) };
+        case 'ledger':
+            return { narrow, tabStrip, lines: ledgerBoardRows(data, narrow) };
+        case 'claims':
+            return { narrow, tabStrip, lines: claimsRows(data, narrow) };
+    }
+}
+// ---------------------------------------------------------------------------
+// Scroll windowing
+// ---------------------------------------------------------------------------
+/** Body rows left for content once the tab strip has taken one of the frame's rows. */
+export function boardBodyRows(frameBodyRows) {
+    return Math.max(1, Math.floor(frameBodyRows) - 1);
+}
+export function boardWindow(total, offset, height) {
+    return sliceWindow(total, offset, height);
+}
+/** Position text for the footer, e.g. `3-14/40`; '' when everything fits. */
+export function boardPosition(window, glyphs) {
+    if (window.visible >= window.total)
+        return '';
+    const up = window.start > 0 ? glyphs.arrowUp : ' ';
+    const down = window.start + window.visible < window.total ? glyphs.arrowDown : ' ';
+    return `${up}${down} ${window.start + 1}-${window.start + window.visible}/${window.total}`;
+}
+/** Footer hint, shortened to the width the frame can print on one row. */
+export function boardHint(cols, glyphs) {
+    const dot = ` ${glyphs.midDot} `;
+    const full = [
+        `${glyphs.arrowLeft}/${glyphs.arrowRight} tab`,
+        `${glyphs.arrowUp}/${glyphs.arrowDown} PgUp/PgDn scroll`,
+        'e copy path',
+        'Esc close',
+    ];
+    for (let size = full.length; size >= 1; size -= 1) {
+        const kept = size === full.length ? full : [...full.slice(0, size - 1), full[full.length - 1]];
+        const text = kept.join(dot);
+        if (cellWidth(text) <= cols)
+            return text;
+    }
+    return fitCells('Esc close', Math.max(0, cols), glyphs.ellipsis);
+}

package/dist/ui/layout/governance-card.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The settlement card's layout (governance-mode section 10.4): what a
+ * `kind: 'governance'` transcript entry says, as pure data, plus the plain-text export
+ * of the same card.
+ *
+ * Pure and total. ASCII ONLY.
+ *
+ * WIDTH-INDEPENDENT ON PURPOSE. A transcript entry is measured by two parties that must
+ * agree - `virtual-window.ts::estimateEntryRows` and the Ink tree - and neither is handed
+ * the terminal width for a card (`EntryView` has no `cols`). Every line here is
+ * single-row and rendered `wrap="truncate"`, so the card's HEIGHT is a function of the
+ * data alone (`governanceCardRows`) and the estimate is exact rather than an upper bound.
+ * The spec's "narrow terminal -> one plain line per agent" falls out for free: the table
+ * is only a fixed prefix (id, role, confirmed) and an elastic delta, so truncation at 40
+ * columns leaves exactly `dev1 DEV 115 +15P->...`.
+ */
+import type { GovernanceCardData } from '../../governance/types.js';
+import type { Glyphs } from '../glyphs.js';
+import { type Segment, type Tone } from '../governance-status.js';
+export interface CardTableRow {
+    key: string;
+    cells: Segment[][];
+}
+export interface GovernanceCardLayout {
+    /** Rail / headline tone for the whole card. */
+    tone: Tone;
+    title: Segment[];
+    headline: Segment[] | null;
+    /** Fixed prefix widths: id, role, confirmed. The delta cell is elastic. */
+    widths: [number, number, number];
+    tableHeader: Segment[][] | null;
+    rows: CardTableRow[];
+    notes: Segment[] | null;
+    height: number;
+}
+export declare function cardTone(card: GovernanceCardData): Tone;
+/**
+ * Colour the signed tokens of a delta text: `+15P->C D1  +10 D12  -20 D5`. Gains read in
+ * the success tone, losses in the error tone, event codes stay muted. The spelling comes
+ * from the engine (`deltaText`), this only paints it.
+ */
+export declare function colorizeDelta(text: string): Segment[];
+export declare function buildGovernanceCardLayout(card: GovernanceCardData, glyphs: Glyphs): GovernanceCardLayout;
+/**
+ * The card's row count, from the data alone: title, headline, table header + one row per
+ * agent, notes. Exact (not an upper bound) because every line truncates instead of wrapping.
+ */
+export declare function governanceCardRows(card: GovernanceCardData): number;
+/**
+ * The card as plain lines for `/export` and `/save` (no colour, ASCII-safe through
+ * `glyphs`). The caller indents them; the text matches what the card prints.
+ */
+export declare function governanceCardLines(card: GovernanceCardData, glyphs: Glyphs): string[];

package/dist/ui/layout/governance-card.js

@@ -0,0 +1,134 @@
+/**
+ * The settlement card's layout (governance-mode section 10.4): what a
+ * `kind: 'governance'` transcript entry says, as pure data, plus the plain-text export
+ * of the same card.
+ *
+ * Pure and total. ASCII ONLY.
+ *
+ * WIDTH-INDEPENDENT ON PURPOSE. A transcript entry is measured by two parties that must
+ * agree - `virtual-window.ts::estimateEntryRows` and the Ink tree - and neither is handed
+ * the terminal width for a card (`EntryView` has no `cols`). Every line here is
+ * single-row and rendered `wrap="truncate"`, so the card's HEIGHT is a function of the
+ * data alone (`governanceCardRows`) and the estimate is exact rather than an upper bound.
+ * The spec's "narrow terminal -> one plain line per agent" falls out for free: the table
+ * is only a fixed prefix (id, role, confirmed) and an elastic delta, so truncation at 40
+ * columns leaves exactly `dev1 DEV 115 +15P->...`.
+ */
+import { segment } from '../governance-status.js';
+import { CARD_COLUMNS, CARD_TITLE } from '../governance-copy.js';
+import { cellWidth, padCells } from './cells.js';
+const TONE_OF_CARD = {
+    ok: 'ok',
+    warn: 'warn',
+    error: 'error',
+    info: 'govern',
+};
+export function cardTone(card) {
+    return TONE_OF_CARD[card.tone];
+}
+/** The glyph in front of the headline: what the card's verdict looks like at a glance. */
+function toneGlyph(tone, glyphs) {
+    switch (tone) {
+        case 'ok':
+            return glyphs.check;
+        case 'warn':
+            return glyphs.warn;
+        case 'error':
+            return glyphs.times;
+        case 'info':
+            return glyphs.bullet;
+    }
+}
+/**
+ * Colour the signed tokens of a delta text: `+15P->C D1  +10 D12  -20 D5`. Gains read in
+ * the success tone, losses in the error tone, event codes stay muted. The spelling comes
+ * from the engine (`deltaText`), this only paints it.
+ */
+export function colorizeDelta(text) {
+    return text
+        .split(/(\s+)/)
+        .filter((part) => part !== '')
+        .map((part) => {
+        if (/^\+\d/.test(part))
+            return segment(part, 'ok');
+        if (/^-\d/.test(part))
+            return segment(part, 'error');
+        return segment(part, 'muted');
+    });
+}
+function titleText(card, glyphs) {
+    const detail = card.title.trim();
+    if (detail === '')
+        return CARD_TITLE;
+    return /^governance\b/i.test(detail) ? detail : `${CARD_TITLE} ${glyphs.midDot} ${detail}`;
+}
+const ID_MIN = 6;
+const ID_MAX = 14;
+const ROLE_CELLS = 6;
+const CONFIRMED_CELLS = 11;
+export function buildGovernanceCardLayout(card, glyphs) {
+    const tone = cardTone(card);
+    const idCells = Math.min(ID_MAX, Math.max(ID_MIN, ...card.rows.map((row) => cellWidth(row.id) + 2)));
+    const headlineText = card.headline.trim();
+    const rows = card.rows.map((row, index) => ({
+        key: `${row.id}:${index}`,
+        cells: [
+            [segment(padCells(row.id, idCells), 'primary')],
+            [segment(padCells(row.role, ROLE_CELLS), 'muted')],
+            [segment(padCells(row.confirmed === null ? '-' : String(Math.round(row.confirmed)), CONFIRMED_CELLS), 'text', true)],
+            colorizeDelta(row.deltaText),
+        ],
+    }));
+    const tableHeader = rows.length === 0
+        ? null
+        : [
+            [segment(padCells(CARD_COLUMNS.id, idCells), 'muted')],
+            [segment(padCells(CARD_COLUMNS.role, ROLE_CELLS), 'muted')],
+            [segment(padCells(CARD_COLUMNS.confirmed, CONFIRMED_CELLS), 'muted')],
+            [segment(CARD_COLUMNS.delta, 'muted')],
+        ];
+    const notes = card.notes.length === 0
+        ? null
+        : [segment(`notes: ${card.notes.join('; ')}`, 'muted')];
+    return {
+        tone,
+        title: [segment(titleText(card, glyphs), 'govern', true)],
+        headline: headlineText === ''
+            ? null
+            : [segment(`${toneGlyph(card.tone, glyphs)} `, tone, true), segment(headlineText, 'text')],
+        widths: [idCells, ROLE_CELLS, CONFIRMED_CELLS],
+        tableHeader,
+        rows,
+        notes,
+        height: governanceCardRows(card),
+    };
+}
+/**
+ * The card's row count, from the data alone: title, headline, table header + one row per
+ * agent, notes. Exact (not an upper bound) because every line truncates instead of wrapping.
+ */
+export function governanceCardRows(card) {
+    return 1
+        + Number(card.headline.trim() !== '')
+        + (card.rows.length > 0 ? 1 + card.rows.length : 0)
+        + Number(card.notes.length > 0);
+}
+/**
+ * The card as plain lines for `/export` and `/save` (no colour, ASCII-safe through
+ * `glyphs`). The caller indents them; the text matches what the card prints.
+ */
+export function governanceCardLines(card, glyphs) {
+    const layout = buildGovernanceCardLayout(card, glyphs);
+    const flat = (segments) => segments.map((s) => s.text).join('');
+    const lines = [flat(layout.title)];
+    if (layout.headline)
+        lines.push(flat(layout.headline));
+    if (layout.tableHeader) {
+        lines.push(layout.tableHeader.map(flat).join('').trimEnd());
+        for (const row of layout.rows)
+            lines.push(row.cells.map(flat).join('').trimEnd());
+    }
+    if (layout.notes)
+        lines.push(flat(layout.notes));
+    return lines;
+}

package/dist/ui/layout/governance-chip.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The status bar's governance chip: pure width planning, no JSX
+ * (governance-mode section 10.2).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * SAME SHAPE AS `kit-chip.ts` / `session-chip.ts`, for the same reason: the status row is
+ * measured cell by cell, and a chip appended "just to the right" eats `phase`, the one
+ * field a user needs mid-run. The chip therefore competes for the SAME budget as every
+ * other field: it takes the longest rung that still leaves the left half its floor.
+ *
+ * THE LADDER (spec 10.2): `GOV p2/3 REVIEW` -> `GOV p2/3` -> `GOV`. A paused run reads
+ * `GOV paused`, one with a `/gov pause` still pending `GOV pausing` (warn tone: the stop is
+ * coming), an escalated one `GOV ! escalated` (warn tone - it is the run asking for
+ * the user), and a budget at or past 80% appends ` $` at every rung where there is room,
+ * because the hint is worth more than the stage name when space is short.
+ */
+import type { GovernanceSnapshot } from '../../governance/types.js';
+import { type Tone } from '../governance-status.js';
+export declare const GOVERNANCE_CHIP_LIMITS: {
+    /** Blank cells between the chip and the field run. */
+    readonly gapCells: 2;
+    /** The floor the left half must keep; the same 34 the session and kit chips use. */
+    readonly minStatusCells: 34;
+};
+export interface GovernanceChipPlan {
+    visible: boolean;
+    text: string;
+    cells: number;
+    gap: number;
+    tone: Tone;
+}
+export interface GovernanceChipInput {
+    columns: number;
+    snapshot?: GovernanceSnapshot | null | undefined;
+}
+/** Plan the chip for `columns` and this session's live run snapshot. */
+export declare function planGovernanceChip(input: GovernanceChipInput): GovernanceChipPlan;

package/dist/ui/layout/governance-chip.js

@@ -0,0 +1,64 @@
+/**
+ * The status bar's governance chip: pure width planning, no JSX
+ * (governance-mode section 10.2).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * SAME SHAPE AS `kit-chip.ts` / `session-chip.ts`, for the same reason: the status row is
+ * measured cell by cell, and a chip appended "just to the right" eats `phase`, the one
+ * field a user needs mid-run. The chip therefore competes for the SAME budget as every
+ * other field: it takes the longest rung that still leaves the left half its floor.
+ *
+ * THE LADDER (spec 10.2): `GOV p2/3 REVIEW` -> `GOV p2/3` -> `GOV`. A paused run reads
+ * `GOV paused`, one with a `/gov pause` still pending `GOV pausing` (warn tone: the stop is
+ * coming), an escalated one `GOV ! escalated` (warn tone - it is the run asking for
+ * the user), and a budget at or past 80% appends ` $` at every rung where there is room,
+ * because the hint is worth more than the stage name when space is short.
+ */
+import { budgetState, isFinishedRun, isPausePending, activeStepKey, } from '../governance-status.js';
+import { PIPELINE_LABEL, STATUS_WORD, phaseText } from '../governance-copy.js';
+export const GOVERNANCE_CHIP_LIMITS = {
+    /** Blank cells between the chip and the field run. */
+    gapCells: 2,
+    /** The floor the left half must keep; the same 34 the session and kit chips use. */
+    minStatusCells: 34,
+};
+const HIDDEN = { visible: false, text: '', cells: 0, gap: 0, tone: 'muted' };
+/** Candidate texts, longest first. ASCII `!` is the escalation mark in both glyph tiers. */
+function rungs(snapshot) {
+    const budget = budgetState(snapshot);
+    const hint = budget === 'warn' || budget === 'over' ? ' $' : '';
+    if (isPausePending(snapshot)) {
+        return [`GOV ${STATUS_WORD.pausing}${hint}`, `GOV${hint}`];
+    }
+    if (snapshot.status === 'paused')
+        return [`GOV paused${hint}`, `GOV${hint}`];
+    if (snapshot.status === 'escalated') {
+        return [`GOV ! escalated${hint}`, `GOV !${hint}`, 'GOV !'];
+    }
+    const phase = phaseText(snapshot.phase, snapshot.phaseCount);
+    const stage = activeStepKey(snapshot);
+    const named = stage === null ? phase : `${phase} ${PIPELINE_LABEL[stage]}`;
+    return [`GOV ${named}${hint}`, `GOV ${phase}${hint}`, `GOV${hint}`, 'GOV'];
+}
+function chipTone(snapshot) {
+    if (snapshot.status === 'escalated' || budgetState(snapshot) === 'over')
+        return 'warn';
+    if (isPausePending(snapshot))
+        return 'warn';
+    return snapshot.status === 'paused' ? 'muted' : 'govern';
+}
+/** Plan the chip for `columns` and this session's live run snapshot. */
+export function planGovernanceChip(input) {
+    const snapshot = input.snapshot;
+    if (!snapshot || isFinishedRun(snapshot.status))
+        return HIDDEN;
+    const columns = Number.isFinite(input.columns) ? Math.floor(input.columns) : 0;
+    const gap = GOVERNANCE_CHIP_LIMITS.gapCells;
+    for (const text of rungs(snapshot)) {
+        if (columns - (text.length + gap) >= GOVERNANCE_CHIP_LIMITS.minStatusCells) {
+            return { visible: true, text, cells: text.length, gap, tone: chipTone(snapshot) };
+        }
+    }
+    return HIDDEN;
+}