@aragon-agent/cli 0.6.2 → 0.6.4

package/dist/ui/entries/ServiceCard.d.ts

@@ -0,0 +1,66 @@
+/**
+ * ServiceCard — one supervised background service in the transcript
+ * (background-service-supervision §3.8).
+ *
+ * ASCII ONLY: every glyph comes from `pickGlyphs`. `ui/` is inside
+ * `glyphs.test.ts::inScope`, so a literal here fails the scan.
+ *
+ * NO ANIMATED SPINNER, IN ANY STATE (D-14 / P2-7). That is STRICTER than
+ * `single-spinner-while-running` D-1, which suppresses animation only while the
+ * activity line is mounted — and a service can sit at `starting` while the agent
+ * is IDLE, where D-1's "one owner on screen" argument does not reach because
+ * there is no owner on screen. A card that animated only when the agent happened
+ * to be idle would be the worst of both. It uses `glyphs.spinnerStill`
+ * throughout and still accepts `reducedMotion` for consistency with
+ * `EntryView`'s comparator.
+ *
+ * TWO SHAPES, ONE COMPONENT. `terminal: true` is the one-row record a service's
+ * exit appends (D-11); everything else is the live card. They share a component
+ * because they share a colour ladder and a status vocabulary, and splitting them
+ * would be two places to keep those in step.
+ */
+import React from 'react';
+import type { Theme } from '../theme.js';
+import type { TermCapabilities } from '../capabilities.js';
+import { pickGlyphs } from '../glyphs.js';
+import type { ServiceStatus } from '../../proc/types.js';
+export interface ServiceCardProps {
+    serviceId: string;
+    command: string;
+    status: ServiceStatus;
+    url?: string;
+    port?: number;
+    exitCode: number | null;
+    startedAt: number;
+    readyAt?: number;
+    endedAt?: number;
+    rows: readonly string[];
+    /** The one-row record a terminal transition appends. */
+    terminal?: boolean;
+    killIncomplete?: boolean;
+    expanded?: boolean;
+    /** Accepted for comparator consistency; this card never animates (D-14). */
+    reducedMotion?: boolean;
+    theme: Theme;
+    caps: TermCapabilities;
+}
+/**
+ * The card's colour.
+ *
+ * `running` is `toolRunning` rather than the accent: it is alive and listening
+ * on nothing, which is a real third state and not a lesser `ready`. A clean
+ * `exited(0)` is muted, because a command that finished on purpose is not a
+ * failure.
+ */
+export declare function serviceCardColor(props: Pick<ServiceCardProps, 'status' | 'exitCode'>, theme: Theme): string | undefined;
+/** The status glyph, by the same ladder as the colour. */
+export declare function serviceGlyph(props: Pick<ServiceCardProps, 'status' | 'exitCode'>, glyphs: ReturnType<typeof pickGlyphs>): string;
+declare function ServiceCardImpl(props: ServiceCardProps): React.ReactElement;
+/**
+ * `React.memo` with the DEFAULT comparator (tui-render-performance L2 / R3).
+ * `mapEntry` already preserves object identity for untouched entries, so the
+ * props below are stable references on a settled card, and `theme` / `caps` are
+ * `useMemo`d in `App.tsx` (I-L2-1).
+ */
+export declare const ServiceCard: React.MemoExoticComponent<typeof ServiceCardImpl>;
+export {};

package/dist/ui/entries/ServiceCard.js

@@ -0,0 +1,116 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * ServiceCard — one supervised background service in the transcript
+ * (background-service-supervision §3.8).
+ *
+ * ASCII ONLY: every glyph comes from `pickGlyphs`. `ui/` is inside
+ * `glyphs.test.ts::inScope`, so a literal here fails the scan.
+ *
+ * NO ANIMATED SPINNER, IN ANY STATE (D-14 / P2-7). That is STRICTER than
+ * `single-spinner-while-running` D-1, which suppresses animation only while the
+ * activity line is mounted — and a service can sit at `starting` while the agent
+ * is IDLE, where D-1's "one owner on screen" argument does not reach because
+ * there is no owner on screen. A card that animated only when the agent happened
+ * to be idle would be the worst of both. It uses `glyphs.spinnerStill`
+ * throughout and still accepts `reducedMotion` for consistency with
+ * `EntryView`'s comparator.
+ *
+ * TWO SHAPES, ONE COMPONENT. `terminal: true` is the one-row record a service's
+ * exit appends (D-11); everything else is the live card. They share a component
+ * because they share a colour ladder and a status vocabulary, and splitting them
+ * would be two places to keep those in step.
+ */
+import React from 'react';
+import { Box, Text } from 'ink';
+import { pickGlyphs } from '../glyphs.js';
+import { railBorderProps } from '../layout/Gutter.js';
+import { formatDuration } from '../../agent/usage.js';
+/** Tail rows the collapsed card draws. Mirrored as a NUMBER in `virtual-window.ts`. */
+const COLLAPSED_TAIL_ROWS = 2;
+/** Tail rows the expanded card draws — the snapshot's own cap. */
+const EXPANDED_TAIL_ROWS = 8;
+/**
+ * The card's colour.
+ *
+ * `running` is `toolRunning` rather than the accent: it is alive and listening
+ * on nothing, which is a real third state and not a lesser `ready`. A clean
+ * `exited(0)` is muted, because a command that finished on purpose is not a
+ * failure.
+ */
+export function serviceCardColor(props, theme) {
+    switch (props.status) {
+        case 'starting':
+            return theme.muted;
+        case 'ready':
+            return theme.accent;
+        case 'running':
+            return theme.toolRunning;
+        case 'failed':
+            return theme.toolError;
+        case 'exited':
+            return props.exitCode === 0 ? theme.muted : theme.toolError;
+        case 'stopped':
+            return theme.muted;
+        default:
+            return theme.muted;
+    }
+}
+/** The status glyph, by the same ladder as the colour. */
+export function serviceGlyph(props, glyphs) {
+    switch (props.status) {
+        case 'starting':
+            return glyphs.toolPending;
+        case 'ready':
+            return glyphs.toolDone;
+        case 'running':
+            return glyphs.toolRunning;
+        case 'failed':
+            return glyphs.toolError;
+        case 'exited':
+            return props.exitCode === 0 ? glyphs.toolDone : glyphs.toolError;
+        case 'stopped':
+            return glyphs.toolPending;
+        default:
+            return glyphs.toolPending;
+    }
+}
+/** The right-hand status clause: what happened, and how long it took. */
+function statusClause(props, dot) {
+    const { status, exitCode, startedAt, readyAt, endedAt } = props;
+    if (status === 'ready') {
+        const took = readyAt === undefined ? '' : `${dot}${formatDuration(readyAt - startedAt)}`;
+        return `ready${took}`;
+    }
+    if (status === 'running')
+        return 'running';
+    if (status === 'starting')
+        return 'starting';
+    const lived = endedAt === undefined ? '' : `${dot}${formatDuration(endedAt - startedAt)}`;
+    if (status === 'stopped')
+        return `stopped${lived}`;
+    if (status === 'failed')
+        return `failed${lived}`;
+    return `exited${exitCode === null ? '' : ` code ${exitCode}`}${lived}`;
+}
+function ServiceCardImpl(props) {
+    const { serviceId, command, url, rows, expanded, terminal, theme, caps } = props;
+    const glyphs = pickGlyphs(caps);
+    const color = serviceCardColor(props, theme);
+    const dot = `  ${glyphs.midDot}  `;
+    const clause = statusClause(props, dot);
+    // THE TERMINAL RECORD IS ONE ROW, ALWAYS. It is a SECOND event at a SECOND
+    // time — the only thing `<Static>` permits once the live card is printed — so
+    // it names what happened and nothing else (D-11).
+    if (terminal) {
+        return (_jsx(Box, { flexDirection: "row", children: _jsxs(Text, { color: color, wrap: "truncate", children: ["service ", serviceId, " ", clause, props.killIncomplete ? ' (may have left a detached child)' : ''] }) }));
+    }
+    const shown = rows.slice(-(expanded ? EXPANDED_TAIL_ROWS : COLLAPSED_TAIL_ROWS));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [_jsxs(Text, { color: theme.accent, bold: true, children: ["service ", serviceId] }), _jsxs(Text, { color: theme.muted, wrap: "truncate", children: ['  ', command] }), _jsxs(Text, { color: color, wrap: "truncate", children: [dot, clause] })] }), url !== undefined && (_jsxs(Box, { flexDirection: "row", flexShrink: 0, paddingLeft: 1, children: [_jsx(Text, { color: theme.primary, children: url }), _jsxs(Text, { color: theme.muted, children: [dot, "ctrl+c stop", dot, "ctrl+o log"] })] })), shown.length > 0 && (_jsx(Box, { flexDirection: "column", flexShrink: 0, paddingLeft: 1, ...railBorderProps(glyphs.railVertical, theme.border), children: shown.map((line, index) => (_jsx(Text, { color: theme.muted, wrap: "truncate", children: line }, index))) }))] }));
+}
+/**
+ * `React.memo` with the DEFAULT comparator (tui-render-performance L2 / R3).
+ * `mapEntry` already preserves object identity for untouched entries, so the
+ * props below are stable references on a settled card, and `theme` / `caps` are
+ * `useMemo`d in `App.tsx` (I-L2-1).
+ */
+export const ServiceCard = React.memo(ServiceCardImpl);

package/dist/ui/entries/UserEntry.d.ts

@@ -3,15 +3,29 @@
  *
  * The role glyph, the gutter rail and the inter-entry spacing all belong to
  * `EntryFrame` now (§4.3), so this component renders content and nothing else.
- * That is also why it takes no `caps`: it has no glyph of its own left to
- * degrade.
+ *
+ * IT DOES TAKE `caps` AS OF tui-paste-handling (G7): the row cap below needs one
+ * glyph, and a hardcoded ellipsis is the exact failure `glyphs.ts` exists to
+ * prevent. That is the only reason the earlier "it has no glyph of its own left
+ * to degrade" note no longer holds.
  */
 import React from 'react';
 import type { Theme } from '../theme.js';
-declare function UserEntryImpl({ text, theme }: {
+import type { TermCapabilities } from '../capabilities.js';
+declare function UserEntryImpl({ text, theme, caps, }: {
     text: string;
     theme: Theme;
+    caps: TermCapabilities;
 }): React.ReactElement;
+/**
+ * Rows this component renders for a given text.
+ *
+ * EXPORTED SO `virtual-window.ts` AND THIS FILE CANNOT DISAGREE (I-13). The
+ * render cap and the height estimate are ONE number; an over-estimated entry is
+ * never mounted, so it is never measured, so the estimate never self-corrects --
+ * which makes that particular disagreement permanent and silent.
+ */
+export declare function userEntryRenderedRows(lineCount: number): number;
 /**
  * `React.memo` with the DEFAULT comparator (tui-render-performance L2 / R3).
  * `mapEntry` already preserves object identity for untouched entries, so the

package/dist/ui/entries/UserEntry.js

@@ -1,16 +1,45 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 /**
  * Render a user message entry.
  *
  * The role glyph, the gutter rail and the inter-entry spacing all belong to
  * `EntryFrame` now (§4.3), so this component renders content and nothing else.
- * That is also why it takes no `caps`: it has no glyph of its own left to
- * degrade.
+ *
+ * IT DOES TAKE `caps` AS OF tui-paste-handling (G7): the row cap below needs one
+ * glyph, and a hardcoded ellipsis is the exact failure `glyphs.ts` exists to
+ * prevent. That is the only reason the earlier "it has no glyph of its own left
+ * to degrade" note no longer holds.
  */
 import React from 'react';
 import { Box, Text } from 'ink';
-function UserEntryImpl({ text, theme }) {
-    return (_jsx(Box, { flexDirection: "column", children: text.split('\n').map((line, i) => (_jsx(Text, { color: theme.user, bold: i === 0, children: line }, i))) }));
+import { pickGlyphs } from '../glyphs.js';
+import { USER_ENTRY_MAX_ROWS } from '../composer-limits.js';
+function UserEntryImpl({ text, theme, caps, }) {
+    const glyphs = pickGlyphs(caps);
+    const all = text.split('\n');
+    // A submitted 5 000-line paste otherwise asks Yoga to lay out 5 000 nodes
+    // inside a measured entry -- the hazard `render-cache.ts:37` already records
+    // in the same words ("a multi-megabyte 'code block' is almost always a pasted
+    // log"). The full text stays in `ViewState` and in the exit transcript, which
+    // is deliberately NOT capped: a replay a user pipes into an issue must be
+    // complete.
+    const hidden = Math.max(0, all.length - USER_ENTRY_MAX_ROWS);
+    const shown = hidden > 0 ? all.slice(0, USER_ENTRY_MAX_ROWS) : all;
+    return (_jsxs(Box, { flexDirection: "column", children: [shown.map((line, i) => (_jsx(Text, { color: theme.user, bold: i === 0, children: line }, i))), hidden > 0 && (
+            // The tail NAMES the number of hidden rows rather than hiding them
+            // silently, which is what makes the cap honest (D-9 / R-10).
+            _jsx(Text, { color: theme.muted, children: `${glyphs.ellipsis} +${hidden} more lines` }))] }));
+}
+/**
+ * Rows this component renders for a given text.
+ *
+ * EXPORTED SO `virtual-window.ts` AND THIS FILE CANNOT DISAGREE (I-13). The
+ * render cap and the height estimate are ONE number; an over-estimated entry is
+ * never mounted, so it is never measured, so the estimate never self-corrects --
+ * which makes that particular disagreement permanent and silent.
+ */
+export function userEntryRenderedRows(lineCount) {
+    return lineCount > USER_ENTRY_MAX_ROWS ? USER_ENTRY_MAX_ROWS + 1 : lineCount;
 }
 /**
  * `React.memo` with the DEFAULT comparator (tui-render-performance L2 / R3).

package/dist/ui/frame-differ.d.ts

@@ -58,6 +58,31 @@ export interface FrameDifferOptions {
     rows: () => number | undefined;
     /** Raised once, on the 0→1 edge of `fallbacks` (§5.6). */
     onFirstFallback?: () => void;
+    /**
+     * Raw frame lines in, lines to PAINT out. Identity when absent, and absent is
+     * the default — a session without drag-select never allocates a second array.
+     *
+     * Called AFTER the geometry stand-down and BEFORE the cache comparison, so a
+     * frame this module refuses to address never reaches the selection layer, and
+     * the diff below still compares what is actually on the screen (I-2).
+     *
+     * It MUST return the same number of lines it was given; a decorator that
+     * changes the count would desynchronise absolute addressing, so the result is
+     * discarded if it does.
+     */
+    decorate?: (lines: string[]) => string[];
+    /**
+     * Raised whenever the cache is dropped — a foreign write, a resize, a geometry
+     * stand-down, an explicit `invalidate()`.
+     *
+     * P1-7: on every one of those paths the RAW Ink frame reaches the screen
+     * verbatim, so any highlight is wiped off the terminal while the selection
+     * controller still believes it is painted and its mirror still holds the rows
+     * of the last DECORATED frame. A release would then copy text that is not on
+     * screen. I-4's "by construction" argument has exactly this hole, and one
+     * callback closes it: the controller clears the selection.
+     */
+    onInvalidate?: () => void;
 }
 export interface FrameWriterStats {
     /** Frames the differ EMITTED — `framesDiffed + framesFull`, never pass-throughs. */
@@ -78,6 +103,15 @@ export interface FrameWriterStats {
      * to stdout behind Ink's back" and is what raises the §5.6 notice.
      */
     fallbacks: number;
+    /**
+     * Self-initiated repaints — `repaint()` calls that emitted at least one row.
+     *
+     * A COUNTER OF ITS OWN, deliberately kept out of `framesTotal` /
+     * `framesDiffed` (P2-6). Those count frames INK PRODUCED, and folding a drag's
+     * highlight repaints into them would make `/perf`'s frame rate a function of
+     * how much the user moved the mouse.
+     */
+    repaints: number;
 }
 export interface FrameDiffer {
     /**
@@ -91,5 +125,17 @@ export interface FrameDiffer {
     invalidate(): void;
     /** Single owner of the counters (P2-2); the writer re-exports this. */
     stats(): FrameWriterStats;
+    /**
+     * Re-run `decorate` over the LAST RAW FRAME and emit only the rows whose paint
+     * changed; `''` when there is nothing safe to do.
+     *
+     * This is what makes a drag cost 1-3 addressed rows instead of a React commit
+     * and a whole-tree Yoga layout (D-6). `''` is a REAL state rather than an error
+     * — after an `invalidate()` there is no cache to diff against and no origin to
+     * address from — and the caller's fallback is `App`'s existing `redrawNonce`:
+     * ask for a React redraw, the next commit runs `decorate`, and the highlight
+     * appears one frame later instead of never.
+     */
+    repaint(): string;
 }
 export declare function createFrameDiffer(options: FrameDifferOptions): FrameDiffer;

package/dist/ui/frame-differ.js

@@ -92,8 +92,23 @@ function countErases(prefix) {
     return prefix.split(ERASE_LINE).length - 1;
 }
 export function createFrameDiffer(options) {
-    /** Last frame, one entry per row. `null` = no cache, next frame is a full repaint. */
+    /**
+     * Last frame AS PAINTED — what is actually on the screen.
+     *
+     * `null` = no cache, next frame is a full repaint. THE DIFF COMPARES PAINTED
+     * LINES (I-2): diffing raw against a painted screen would leave the highlight
+     * burned into rows the next frame never repaints, because those rows' RAW text
+     * did not change.
+     */
     let prev = null;
+    /**
+     * The same frame UNDECORATED — `repaint()`'s input.
+     *
+     * Two caches rather than one, because a repaint has to re-run `decorate` over
+     * the ORIGINAL rows: painting an already-painted row would nest the selection
+     * escapes and the highlight would never come off.
+     */
+    let rawPrev = null;
     /**
      * Whether any chunk has been seen at all.
      *
@@ -111,9 +126,37 @@ export function createFrameDiffer(options) {
         linesWritten: 0,
         bytesWritten: 0,
         fallbacks: 0,
+        repaints: 0,
     };
+    /**
+     * Re-entrancy guard for `onInvalidate`. The listener clears the selection,
+     * which asks for a repaint, which can reach `invalidate()` again; one flag is
+     * cheaper than reasoning about how deep that can go.
+     */
+    let notifying = false;
     const invalidate = () => {
         prev = null;
+        rawPrev = null;
+        if (notifying || !options.onInvalidate)
+            return;
+        notifying = true;
+        try {
+            options.onInvalidate();
+        }
+        finally {
+            notifying = false;
+        }
+    };
+    /**
+     * `decorate`, with the line-count contract enforced. A decorator that returned
+     * a different number of rows would shift every absolute address below it for
+     * the rest of the session, so its answer is discarded rather than trusted.
+     */
+    const applyDecorate = (lines) => {
+        if (!options.decorate)
+            return lines;
+        const painted = options.decorate(lines);
+        return painted.length === lines.length ? painted : lines;
     };
     /**
      * Write `chunk` verbatim — today's behaviour, and the only failure mode.
@@ -132,8 +175,9 @@ export function createFrameDiffer(options) {
         return null;
     };
     const wrapSync = (payload) => options.sync ? SYNC_BEGIN + payload + SYNC_END : payload;
-    const emit = (payload, lines, addressed, full) => {
+    const emit = (payload, lines, raw, addressed, full) => {
         prev = lines;
+        rawPrev = raw;
         counters.framesTotal += 1;
         if (full)
             counters.framesFull += 1;
@@ -175,16 +219,16 @@ export function createFrameDiffer(options) {
      * is no unchanged content that has to survive, and full repaints are rare by
      * construction — one per session, one per resize, one per invalidation.
      */
-    const fullRepaint = (lines) => {
+    const fullRepaint = (lines, raw) => {
         const payload = cursorTo(1) +
             SGR_RESET +
             ERASE_DOWN +
             lines.join('\r\n') +
             '\r\n' +
             cursorTo(lines.length + 1);
-        return emit(wrapSync(payload), lines, lines.length, true);
+        return emit(wrapSync(payload), lines, raw, lines.length, true);
     };
-    const diffRepaint = (lines, previous) => {
+    const diffRepaint = (lines, raw, previous) => {
         const out = [];
         for (let i = 0; i < lines.length; i += 1) {
             // I-4: paint, THEN clear the tail. Never `ERASE_LINE` first.
@@ -196,10 +240,45 @@ export function createFrameDiffer(options) {
         // on an identical frame, so a chunk that reaches here differs by at least one
         // line; the only way to observe zero is a cache that disagrees with the
         // screen, which is the state `invalidate()` exists to prevent.
+        //
+        // With a `decorate` hook it stops being unreachable in one direction and
+        // stays correct: a frame whose RAW rows changed only where the highlight
+        // already covers them paints identically, and writing nothing is right.
         if (out.length === 0)
-            return emit('', lines, 0, false);
+            return emit('', lines, raw, 0, false);
         out.push(cursorTo(lines.length + 1)); // I-5
-        return emit(wrapSync(out.join('')), lines, out.length - 1, false);
+        return emit(wrapSync(out.join('')), lines, raw, out.length - 1, false);
+    };
+    /**
+     * Re-paint the last frame's rows through `decorate` again, emitting only what
+     * changed. Called when the SELECTION moved rather than when Ink produced a
+     * frame — hence its own counter and no touch of the frame ones (P2-6).
+     *
+     * It carries the same DEC 2026 sync envelope and parks on row `H + 1` as every
+     * other batch, because it is addressed exactly like a diff frame and a
+     * half-applied highlight tears the same way a half-applied frame does.
+     */
+    const repaint = () => {
+        if (prev === null || rawPrev === null)
+            return '';
+        const rows = usableRows();
+        if (rows === undefined)
+            return ''; // I-9 — geometry we cannot address safely
+        if (rawPrev.length + 1 > rows)
+            return '';
+        const painted = applyDecorate(rawPrev);
+        const out = [];
+        for (let i = 0; i < painted.length; i += 1) {
+            if (painted[i] !== prev[i]) {
+                out.push(cursorTo(i + 1) + SGR_RESET + painted[i] + SGR_RESET + ERASE_TO_EOL);
+            }
+        }
+        prev = painted;
+        if (out.length === 0)
+            return '';
+        out.push(cursorTo(painted.length + 1)); // I-5
+        counters.repaints += 1;
+        return wrapSync(out.join(''));
     };
     const transform = (chunk) => {
         const firstChunk = !seenAnyChunk;
@@ -217,14 +296,19 @@ export function createFrameDiffer(options) {
         const lines = body.slice(0, -1).split('\n');
         if (lines.length + 1 > rows)
             return passThrough(false); // I-9
-        if (prev === null || prev.length !== lines.length || matched.erased !== prev.length + 1) {
-            return fullRepaint(lines);
+        // AFTER the geometry stand-down, BEFORE the cache comparison: a frame this
+        // module refuses to address never reaches the selection layer, and what is
+        // compared below is what the screen will hold.
+        const painted = applyDecorate(lines);
+        if (prev === null || prev.length !== painted.length || matched.erased !== prev.length + 1) {
+            return fullRepaint(painted, lines);
         }
-        return diffRepaint(lines, prev);
+        return diffRepaint(painted, lines, prev);
     };
     return {
         transform,
         invalidate,
+        repaint,
         stats: () => ({ ...counters }),
     };
 }

package/dist/ui/gauge.d.ts

@@ -17,8 +17,23 @@ export interface Gauge {
     /** Clamped percentage 0–100. */
     pct: number;
 }
+/**
+ * Where the bar changes colour, as percentages.
+ *
+ * The defaults are the values this function hardcoded before context compaction
+ * existed, so every existing call site and test is byte-identical (§6.2).
+ */
+export interface GaugeMarks {
+    /** Amber at or above this. */
+    warn: number;
+    /** Red strictly above this. */
+    high: number;
+}
 /**
  * Build a `width`-cell gauge for `pct` (0–100). Uses block glyphs on Unicode
  * terminals and `#`/`-` otherwise (e.g. `[######----]`).
+ *
+ * `marks` is OPTIONAL and defaults to today's values, so omitting it produces
+ * byte-identical output to the pre-compaction build.
  */
-export declare function buildGauge(pct: number, width: number, theme: Theme, caps: TermCapabilities): Gauge;
+export declare function buildGauge(pct: number, width: number, theme: Theme, caps: TermCapabilities, marks?: GaugeMarks): Gauge;

package/dist/ui/gauge.js

@@ -4,19 +4,38 @@
  * has no Unicode. Kept out of the `.tsx` so it is unit-testable without Ink.
  */
 import { pickGlyphs } from './glyphs.js';
-/** Pick the fill colour by threshold: <60 low · 60–85 mid · >85 high. */
-function thresholdColor(pct, theme) {
-    if (pct > 85)
+const DEFAULT_MARKS = { warn: 60, high: 85 };
+/**
+ * Pick the fill colour by threshold: `< warn` low · `>= warn` mid · `> high` high.
+ *
+ * THE TWO OPERATORS ARE PRESERVED EXACTLY (`> high`, `>= warn`), and that is not
+ * cosmetic: changing either would move the default 85 or 60 boundary and break
+ * the byte-identity claim that makes the `marks` parameter a free change.
+ *
+ * WHAT RED MEANS, PRECISELY (P2-4). The compaction trigger is
+ * `ratio >= threshold` (INCLUSIVE) while this fill is `pct > high` (EXCLUSIVE),
+ * so with `high = threshold` any occupancy that would render red has ALREADY
+ * triggered compaction, and the gauge repaints downward in the same frame. The
+ * red band is therefore only ever OBSERVABLE when compaction did not or could
+ * not run — the feature is off, it self-disabled, or the failure ladder ended at
+ * its last rung. That is a genuinely more useful meaning than "imminent", and it
+ * is the one the README and the settings screen state.
+ */
+function thresholdColor(pct, theme, marks) {
+    if (pct > marks.high)
         return theme.gauge.high;
-    if (pct >= 60)
+    if (pct >= marks.warn)
         return theme.gauge.mid;
     return theme.gauge.low;
 }
 /**
  * Build a `width`-cell gauge for `pct` (0–100). Uses block glyphs on Unicode
  * terminals and `#`/`-` otherwise (e.g. `[######----]`).
+ *
+ * `marks` is OPTIONAL and defaults to today's values, so omitting it produces
+ * byte-identical output to the pre-compaction build.
  */
-export function buildGauge(pct, width, theme, caps) {
+export function buildGauge(pct, width, theme, caps, marks = DEFAULT_MARKS) {
     const clamped = Math.max(0, Math.min(100, Math.round(pct)));
     const cells = Math.max(1, width);
     const filledCells = Math.max(0, Math.min(cells, Math.round((clamped / 100) * cells)));
@@ -29,7 +48,7 @@ export function buildGauge(pct, width, theme, caps) {
     return {
         filled: full.repeat(filledCells),
         empty: empty.repeat(cells - filledCells),
-        fillColor: thresholdColor(clamped, theme),
+        fillColor: thresholdColor(clamped, theme, marks),
         trackColor: theme.gauge.track,
         pct: clamped,
     };

package/dist/ui/glyphs.d.ts

@@ -117,6 +117,17 @@ export interface Glyphs {
      * scan fails the build if either spelling appears anywhere else.
      */
     retry: string;
+    /**
+     * Context compaction (context-auto-compaction §6.3). The rail marker on the
+     * compaction card.
+     *
+     * HERE RATHER THAN IN `CompactionCard`, for the reason this file's header
+     * gives: a literal in a component bypasses `pickGlyphs` entirely and shows
+     * mojibake on a legacy console whatever the capability probe said.
+     * `glyphs.test.ts`'s static scan fails the build if either spelling appears
+     * anywhere else — and `src/compaction/**` is inside that scan's scope too.
+     */
+    compaction: string;
     /**
      * Ink `borderStyle` name for every boxed region (composer, completion popup,
      * overlay frame).

package/dist/ui/glyphs.js

@@ -65,6 +65,7 @@ const UNICODE_GLYPHS = {
     todoActive: '▸',
     todoDone: '✔',
     retry: '↻',
+    compaction: '⤓',
     tool: {
         read_file: '▤',
         write_file: '✎',
@@ -127,6 +128,7 @@ const ASCII_GLYPHS = {
     todoActive: '>',
     todoDone: '[x]',
     retry: '[r]',
+    compaction: '[c]',
     tool: {
         read_file: '=',
         write_file: '+',