@aragon-agent/cli 0.6.25 → 0.6.27

package/dist/ui/App.js

@@ -52,6 +52,7 @@ import { INDEX_KEY_FRAME } from '../input/limits.js';
 import { INDEX_SKILL_NAME, buildIndexConfirmSummary, hasProjectIndex, indexBuildInvocationArgs, } from '../commands/index-build.js';
 import { installConsoleBridge } from './console-bridge.js';
 import { publishExitSnapshot } from './exit-snapshot.js';
+import { publishSessionView } from './session-bridge.js';
 import { OverlayFrame } from './layout/OverlayFrame.js';
 import { helpRows } from './overlays/HelpOverlay.js';
 import { ModelPicker } from './overlays/ModelPicker.js';
@@ -121,10 +122,17 @@ function liveServiceCount(services) {
  * The lazy `useReducer` initializer. Module scope, so the reference is stable
  * across renders and React never re-runs it.
  */
-function seedViewState(thinkingVisible) {
-    return initialViewState({ thinkingVisible });
+function seedViewState(seed) {
+    const base = initialViewState({ thinkingVisible: seed.thinkingVisible });
+    // THE REDUCER'S OWN ADOPTION LOGIC, NOT A COPY OF IT (3.12): `restoreEntries`
+    // already lifts `seq` past the restored ids, trims to the retain ring and
+    // clears the live-target pointers, and a second implementation of those thirty
+    // lines is how the two would drift.
+    return seed.entries && seed.entries.length > 0
+        ? viewReducer(base, { type: 'restoreEntries', entries: seed.entries })
+        : base;
 }
-export function App({ controller, version, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, pasteBridge, terminal, }) {
+export function App({ controller, version, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, pasteBridge, terminal, initialEntries, session, sessionBridge, sessionNotice, }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
     const size = useTerminalSize();
@@ -157,7 +165,14 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     // `toggleThinking` would let `/resume` flash a restored thinking block on
     // frame 1. `seedViewState` is module-scope so the lazy initializer is a stable
     // function reference.
-    const [state, dispatch] = useReducer(viewReducer, cfg.showThinking, seedViewState);
+    const [state, dispatch] = useReducer(viewReducer, { thinkingVisible: cfg.showThinking, ...(initialEntries ? { entries: initialEntries } : {}) }, seedViewState);
+    // THE IDENTITY, SEEDED FROM THE PROP AND REPLACED ON ROTATION (D-15). A ref
+    // travels beside it because both readers -- the publish effect and the
+    // `/session` port -- must see the CURRENT id, and a rotation can land between
+    // two renders.
+    const [identity, setIdentity] = useState(session);
+    const identityRef = useRef(session);
+    const sessionId = identity?.id;
     const metrics = useRef(createRunMetrics());
     const manualMetrics = useRef(createRunMetrics());
     const [, setMetricsClock] = useState(0);
@@ -1025,8 +1040,9 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         : undefined);
     // --- Exit snapshot: the only way state reaches cli.tsx (§4.4). ----------
     useEffect(() => {
+        const merged = mergePendingEntries(state.entries, state.pendingSteering);
         publishExitSnapshot({
-            entries: mergePendingEntries(state.entries, state.pendingSteering),
+            entries: merged,
             usageTotal: state.usageTotal,
             provider: cfg.provider,
             model: cfg.model,
@@ -1036,7 +1052,18 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             // count (K-6).
             droppedEntries: state.droppedEntries,
         });
-    }, [state.entries, state.pendingSteering, state.usageTotal, state.droppedEntries, cfg.provider, cfg.model]);
+        // THE SAME `merged`, THE SAME RENDER (D-2 / 3.12). The checkpoint describes
+        // exactly what the exit summary would, because it is built from the same
+        // array in the same pass - and no second effect or subscription is added.
+        //
+        // `sessionId` IN THE DEPENDENCY ARRAY IS LOAD-BEARING (R-16): a rotation
+        // that leaves the `entries` reference untouched would otherwise never
+        // re-publish, and the writer would keep aiming at the OLD id's file - the
+        // "A's conversation written into B's file" failure I-5 rules out.
+        if (sessionId) {
+            publishSessionView({ id: sessionId, entries: merged, usageTotal: state.usageTotal });
+        }
+    }, [state.entries, state.pendingSteering, state.usageTotal, state.droppedEntries, cfg.provider, cfg.model, sessionId]);
     // --- `/perf` snapshot channel (tui-render-performance §5.4). ------------
     //
     // The deps are the two `useCallback`d members, NOT the handle objects: both
@@ -1146,6 +1173,33 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     // --- Helpers -----------------------------------------------------------
     const notify = (level, text) => dispatch({ type: 'notice', level, text });
     const toast = (level, text) => dispatch({ type: 'pushToast', level, text });
+    // THE BRANCH / `--save` NOTICE (D-13). Once, on mount, and only when the
+    // caller supplied one: "the session you branched from is unchanged" is the
+    // sentence that makes `--resume` safe to reach for, and it belongs in the
+    // transcript where it can be read again rather than in a toast that expires.
+    useEffect(() => {
+        if (sessionNotice)
+            notify('info', sessionNotice);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // --- Session bridge: identity write-back (D-15 / 3.12). -------------------
+    //
+    // INSTALLED AND CLEARED EXACTLY LIKE `confirmBridge.handler`: the rotation is
+    // performed by `cli.tsx` (which owns the writer's target file), and the only
+    // thing the view owns is the id it draws. Clearing on unmount keeps a late
+    // rotation from dispatching into a dead reducer.
+    useEffect(() => {
+        if (!sessionBridge)
+            return undefined;
+        const bridge = sessionBridge;
+        bridge.onIdentity = (next) => {
+            identityRef.current = next;
+            setIdentity(next);
+        };
+        return () => {
+            bridge.onIdentity = undefined;
+        };
+    }, [sessionBridge]);
     // --- Paste bridge (tui-paste-handling section 5.1.2 / I-15). -------------
     //
     // The filter exists before this component does, so it holds a slot rather than
@@ -1395,6 +1449,29 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         // tool cards of the abandoned run are appended AFTER the command starts. A
         // value here would archive the screen minus the part the user was watching.
         transcriptEntries: () => stateRef.current.entries,
+        // THE SESSION PORT (D-14 / D-15). `identity()` reads the ref at command time
+        // and never a captured value: `/resume` rotates the id under a live tree, and
+        // a captured one would report the previous id for the rest of the session.
+        // `checkpoint` / `rotate` are the writer's, installed by `cli.tsx`; the port
+        // is absent when this build has no session at all, which is what lets
+        // `/session` say so honestly instead of throwing.
+        ...(sessionBridge
+            ? {
+                session: {
+                    identity: () => identityRef.current,
+                    checkpoint: (opts) => sessionBridge.checkpoint?.(opts) ?? {
+                        ok: false,
+                        reason: 'no-identity',
+                        message: 'This session has no id.',
+                    },
+                    rotate: (loadedPath) => sessionBridge.rotate?.(loadedPath),
+                },
+            }
+            : {}),
+        // The branch port is projected from the bridge here rather than captured, so
+        // this object stays a view of the current bridge, exactly like `session`
+        // above. Absent means `/branch` reports that the build has none.
+        ...(sessionBridge?.branch ? { branch: sessionBridge.branch } : {}),
         dispatch: (action) => {
             if (action.type === 'resetConversation' || action.type === 'restoreEntries') {
                 metrics.current = createRunMetrics();
@@ -1868,6 +1945,23 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             requestIndexBuild();
             return;
         }
+        // Ctrl+L: branch this session into a NEW terminal (tui-branch-terminal-
+        // shortcut D-1 / D-2). Guarded exactly like Ctrl+G and Ctrl+I above it: an
+        // overlay owns the keyboard, and on a too-small terminal the feedback has
+        // nowhere to go. It has to sit BEFORE the `tooSmall` return below, because
+        // after that line the transcript and overlay paging own every key - and
+        // "the key did nothing" must stay distinguishable from "the key never
+        // arrived".
+        //
+        // NO `isRunning()` GUARD, unlike Ctrl+I: branching mid-run is the most likely
+        // moment to want it (D-22), and the command body is where running decides
+        // that the success needs a second, durable channel.
+        if (key.ctrl && (input === 'l' || input === 'L')) {
+            if (tooSmall || stateRef.current.overlay)
+                return;
+            void executeSlashInput('/branch');
+            return;
+        }
         if (tooSmall)
             return;
         // R-P1-7: the overlay branch MUST come before the transcript scroll branch
@@ -1913,21 +2007,21 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             applyMode(nextMode(controller.getAgentMode()));
             return;
         }
-        if (key.ctrl && (input === 'l' || input === 'L')) {
-            {
-                // Writing \x1B[2J here would erase the screen and then leave it blank:
-                // Ink sees no output change and skips the repaint (ink.js:132 +
-                // log-update.js:13), possibly forever on an idle empty session. Bump
-                // the nonce instead and let Ink redraw the frame normally (§4.13).
-                setRedrawNonce((n) => n + 1);
+        // Moved off Ctrl+L by D-1, because Ctrl+L is the branch key now.
+        //
+        // Ctrl+R, NOT Ctrl+Shift+L: legacy encodings deliver 0x0c for both, so a
+        // Shift binding would exist only behind keyboard enhancement - exactly the
+        // terminals least likely to need a recovery key. The overlay guard keeps the
+        // settings screen's own Ctrl+R (Test connection) unambiguous.
+        //
+        // Writing \x1B[2J here would erase the screen and then leave it blank: Ink
+        // sees no output change and skips the repaint (ink.js:132 +
+        // log-update.js:13), possibly forever on an idle empty session. Bump the
+        // nonce instead and let Ink redraw the frame normally (§4.13).
+        if (key.ctrl && (input === 'r' || input === 'R')) {
+            if (stateRef.current.overlay)
                 return;
-            }
-            try {
-                stdout.write('\x1B[2J\x1B[3J\x1B[H');
-            }
-            catch {
-                /* ignore */
-            }
+            setRedrawNonce((n) => n + 1);
             return;
         }
         {
@@ -2281,7 +2375,7 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     const team = state.team ? (_jsx(TeamPanel, { snapshot: state.team, layout: teamLayout, rows: rows, cols: contentCols, reducedMotion: viewReducedMotion, theme: theme, caps: caps })) : null;
     const rail = showRail && state.todos ? (_jsx(TodoPanel, { snapshot: state.todos, width: railWidth, rows: railRows, running: running, reducedMotion: viewReducedMotion, theme: theme, caps: caps })) : null;
     const viewport = (_jsxs(ScrollViewport, { active: overlay === null && !tooSmall, overlay: overlayNode, footer: _jsxs(_Fragment, { children: [team, _jsx(QueuePanel, { layout: queueLayout, theme: theme })] }), rail: rail, scrollbar: terminal?.scrollbar, resetKey: scrollResetKey, intent: scrollIntent, pinToBottomNonce: pinToBottomNonce, onScrolledLinesChange: setScrolledLines, onViewportShiftChange: onViewportShiftChange, onGeometryChange: onGeometryChange, geometryKey: `${rows}:${cols}:${viewportBudget}:${frameBudget.composerSlotRows}:${frameBudget.statusRows}:${contentCols}:${overlay}:${tooSmall}`, tailRowsRef: tailSink, hold: selectionHold, resumeMs: cfg.scrollResumeMs, showScrollIndicator: true, cols: contentCols, theme: theme, caps: caps, children: [opener, _jsx(TranscriptList, { entries: transcriptEntries, expandedToolIds: state.expandedToolIds, thinkingVisible: state.thinkingVisible, reducedMotion: viewReducedMotion, density: density, nowSec: nowSec, theme: theme, caps: caps, windowSize: transcriptWindow, cols: contentCols, heights: heights, mountedSink: mountedCount, tailSink: tailSink })] }));
-    return (_jsx(AppShell, { inactive: tooSmall, placeholder: _jsxs(Text, { wrap: "truncate", color: theme.noticeWarn, children: [glyphs.warn, " Terminal too small - needs at least 40 columns and 12 rows."] }), rows: rows, cols: cols, header: header, viewport: viewport, viewportRows: frameBudget.viewportRows, composer: composer, composerSlotRows: frameBudget.composerSlotRows, statusRows: frameBudget.statusRows, details: _jsx(BottomStatusRow, { plan: details, columns: cols, theme: theme }), status: _jsx(StatusBar, { columns: cols, speedKnown: speedKnown, ...feedbackProjection, interruptPhase: interruptGesture.current.phase, pendingSteering: state.pendingSteering, runPhase: state.runPhase, activeTool: state.activeTool, runOutcome: state.runOutcome, reducedMotion: reducedMotion, waitingForConfirmation: !!humanRequest || !!confirmState, stopping: interruptGesture.current.phase === 'stopping', interruptHint: interruptGesture.current.phase === 'stopping'
+    return (_jsx(AppShell, { inactive: tooSmall, placeholder: _jsxs(Text, { wrap: "truncate", color: theme.noticeWarn, children: [glyphs.warn, " Terminal too small - needs at least 40 columns and 12 rows."] }), rows: rows, cols: cols, header: header, viewport: viewport, viewportRows: frameBudget.viewportRows, composer: composer, composerSlotRows: frameBudget.composerSlotRows, statusRows: frameBudget.statusRows, details: _jsx(BottomStatusRow, { plan: details, columns: cols, theme: theme }), status: _jsx(StatusBar, { columns: cols, speedKnown: speedKnown, ...feedbackProjection, interruptPhase: interruptGesture.current.phase, pendingSteering: state.pendingSteering, runPhase: state.runPhase, activeTool: state.activeTool, runOutcome: state.runOutcome, reducedMotion: reducedMotion, ...(sessionId ? { sessionId } : {}), waitingForConfirmation: !!humanRequest || !!confirmState, stopping: interruptGesture.current.phase === 'stopping', interruptHint: interruptGesture.current.phase === 'stopping'
                 ? 'Esc force-stop' : 'Esc x2 interrupt', model: cfg.model, provider: cfg.provider, usageTotal: state.usageTotal, 
             // ONE OBJECT INSTEAD OF FOUR PARALLEL PROPS (§4.3). The four were a
             // projection of "many sources of truth" into the props layer, and a

package/dist/ui/Header.js

@@ -2,21 +2,13 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { basename } from 'node:path';
 import { Box, Text } from 'ink';
 import { Logo } from './Logo.js';
+import { planHeaderHints } from './layout/header-hints.js';
 export function Header({ cwd, provider, model, hasKey, variant, theme, caps, columns = 80, statusExpanded = false, scrolledLines = 0, overlayOpen = false }) {
-    const scroll = Number.isFinite(scrolledLines) && scrolledLines > 0
-        ? (scrolledLines > 9999 ? '^9999+' : '^' + Math.floor(scrolledLines)) + (overlayOpen ? ' ' : '  ') : '';
-    // The Ctrl+I project-index affordance sits LEFT of the ^G detail toggle:
-    // collapsed it names the key and the noun ('^I Index'); expanded - the
-    // same Ctrl+G state that adds the status detail row - it spells the action
-    // ('^I build index'). Hidden while an overlay owns the header and below the
-    // 72-column cutoff the composer hints also use: on a narrow terminal the
-    // scroll chip and the ^G toggle are the two affordances that must survive.
-    const indexHint = overlayOpen || columns < 72
-        ? ''
-        : (statusExpanded ? '^I build index  ' : '^I Index  ');
-    const detail = overlayOpen ? (statusExpanded ? 'Details on' : 'Details off')
-        : indexHint + '^G ' + (statusExpanded ? 'less' : 'more');
-    // Widest content: '^9999+  ' (8) + '^I build index  ^G less' (23) = 31.
-    const detailCells = indexHint ? 32 : 18;
-    return _jsxs(Box, { flexDirection: "row", height: 1, width: columns, flexShrink: 0, overflow: "hidden", children: [_jsx(Box, { width: Math.max(0, columns - detailCells), flexShrink: 0, overflow: "hidden", children: _jsxs(Text, { wrap: "truncate", children: [_jsx(Logo, { variant: variant === 'mini' ? 'mini' : 'bar', theme: theme, caps: caps }), variant !== 'mini' && _jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.accent, children: ['  ', provider, ":", model] }), _jsxs(Text, { color: theme.muted, children: ['  ', basename(cwd) || cwd] }), _jsxs(Text, { color: hasKey ? theme.toolDone : theme.toolRunning, children: ['  ', hasKey ? theme.symbols.keyOn : theme.symbols.keyOff] })] })] }) }), _jsx(Box, { width: detailCells, flexShrink: 0, justifyContent: "flex-end", children: _jsx(Text, { color: theme.muted, wrap: "truncate", children: scroll + detail }) })] });
+    // The right-hand hints are planned, not assembled (tui-branch-terminal-shortcut
+    // 3.9 / D-11). `plan.text` is exactly `plan.cells` wide and already carries the
+    // scroll chip's own trailing spacing, so this component can no longer clip a
+    // hint by guessing one cell short - and the ladder that decides which hints
+    // survive a narrow terminal lives in a pure function with its own tests.
+    const plan = planHeaderHints({ columns, statusExpanded, overlayOpen, scrolledLines });
+    return _jsxs(Box, { flexDirection: "row", height: 1, width: columns, flexShrink: 0, overflow: "hidden", children: [_jsx(Box, { width: Math.max(0, columns - plan.cells), flexShrink: 0, overflow: "hidden", children: _jsxs(Text, { wrap: "truncate", children: [_jsx(Logo, { variant: variant === 'mini' ? 'mini' : 'bar', theme: theme, caps: caps }), variant !== 'mini' && _jsxs(_Fragment, { children: [_jsxs(Text, { color: theme.accent, children: ['  ', provider, ":", model] }), _jsxs(Text, { color: theme.muted, children: ['  ', basename(cwd) || cwd] }), _jsxs(Text, { color: hasKey ? theme.toolDone : theme.toolRunning, children: ['  ', hasKey ? theme.symbols.keyOn : theme.symbols.keyOff] })] })] }) }), _jsx(Box, { width: plan.cells, flexShrink: 0, justifyContent: "flex-end", children: _jsx(Text, { color: theme.muted, wrap: "truncate", children: plan.text }) })] });
 }

package/dist/ui/StatusBar.d.ts

@@ -37,6 +37,14 @@ export interface StatusBarProps {
     caps: TermCapabilities;
     scrolledLines?: number;
     redrawNonce?: number;
+    /**
+     * This session's id, rendered at the right end of the primary row
+     * (tui-session-id-resume D-11 / D-12).
+     *
+     * OPTIONAL AND ABSENT BY DEFAULT, so a build without the feature and every
+     * existing test render exactly what they rendered before (I-6).
+     */
+    sessionId?: string;
     agentMode?: AgentMode;
     pendingAgentMode?: AgentMode | null;
     teamActive?: {

package/dist/ui/StatusBar.js

@@ -5,6 +5,7 @@ import { Box, Text } from 'ink';
 import { pickGlyphs } from './glyphs.js';
 import { liveSpinner } from './ActivityLine.js';
 import { planPrimaryStatusFields } from './layout/status-layout.js';
+import { planSessionChip } from './layout/session-chip.js';
 /** An invisible leading byte change forces Ink to repaint on Ctrl+L. */
 const redrawChar = (nonce) => nonce % 2 ? String.fromCharCode(0x00a0) : ' ';
 export function StatusBar(props) {
@@ -13,7 +14,15 @@ export function StatusBar(props) {
     const active = phase !== 'idle' || !!props.compactionActive?.inFlight;
     const glyph = pickGlyphs(props.caps).spinnerStill;
     const spinner = active ? liveSpinner(props.reducedMotion ?? false, props.caps) : null;
+    // THE CHIP IS PLANNED FIRST, and the plan then feeds the field budget: the two
+    // cannot disagree about how wide the terminal is if only one of them is asked.
+    const chip = planSessionChip({
+        columns: cols,
+        ...(props.sessionId ? { sessionId: props.sessionId } : {}),
+    });
+    const chipCells = chip.visible ? chip.cells + chip.gap : 0;
     const plan = planPrimaryStatusFields({
+        reserveRight: chipCells,
         columns: cols, phase, pendingCount: props.pendingSteering?.length ?? 0,
         context: props.context, usageTotal: props.usageTotal,
         thinkingLevel: props.thinkingLevel, elapsedMs: props.elapsedMs, tokPerSec: props.tokPerSec,
@@ -29,7 +38,7 @@ export function StatusBar(props) {
     const tones = { normal: props.theme.primary, muted: props.theme.muted,
         warning: props.theme.noticeWarn, error: props.theme.noticeError,
         accent: props.theme.accent };
-    return _jsxs(Box, { width: cols, height: 1, flexShrink: 0, flexDirection: "row", overflow: "hidden", children: [_jsx(Box, { width: 1, flexShrink: 0, children: _jsx(Text, { children: redrawChar(props.redrawNonce ?? 0) }) }), plan.fields.map((item, index) => _jsxs(React.Fragment, { children: [index > 0 && _jsx(Box, { width: plan.separatorCells, flexShrink: 0, children: _jsx(Text, { color: props.theme.muted, children: plan.separator }) }), _jsx(Box, { width: item.cells, flexShrink: 0, children: _jsx(Text, { color: tones[item.tone], wrap: "truncate", children: item.id === 'phase' && active
-                                ? _jsxs(_Fragment, { children: [spinner ?? glyph, item.text.slice(glyph.length)] })
-                                : item.text }) })] }, item.id))] });
+    return _jsxs(Box, { width: cols, height: 1, flexShrink: 0, flexDirection: "row", overflow: "hidden", children: [_jsx(Box, { width: 1, flexShrink: 0, children: _jsx(Text, { children: redrawChar(props.redrawNonce ?? 0) }) }), _jsx(Box, { width: Math.max(0, cols - 1 - chipCells), flexShrink: 0, flexDirection: "row", overflow: "hidden", children: plan.fields.map((item, index) => _jsxs(React.Fragment, { children: [index > 0 && _jsx(Box, { width: plan.separatorCells, flexShrink: 0, children: _jsx(Text, { color: props.theme.muted, children: plan.separator }) }), _jsx(Box, { width: item.cells, flexShrink: 0, children: _jsx(Text, { color: tones[item.tone], wrap: "truncate", children: item.id === 'phase' && active
+                                    ? _jsxs(_Fragment, { children: [spinner ?? glyph, item.text.slice(glyph.length)] })
+                                    : item.text }) })] }, item.id)) }), chip.visible && _jsx(Box, { width: chipCells, flexShrink: 0, justifyContent: "flex-end", overflow: "hidden", children: _jsx(Text, { color: props.theme.muted, wrap: "truncate", children: chip.text }) })] });
 }

package/dist/ui/layout/header-hints.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The right-hand hint budget for the header row (tui-branch-terminal-shortcut 3.8).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS IS A PLANNER AND NOT ANOTHER TERNARY IN THE JSX (R-0-4): the header's
+ * right side used to be one hand-computed width constant (`detailCells = indexHint
+ * ? 32 : 18`). Adding a third affordance to that arithmetic produces either a
+ * clipped hint or a pushed-out word mark on a 72-column terminal, and NO TEST
+ * WOULD SEE IT - the only thing lost is trailing characters. `ui/layout/session-chip.ts`
+ * already set the precedent for the same problem: the chip has to participate in
+ * one width budget rather than be appended and hoped for.
+ *
+ * THE RULE IS ONE COMPARISON. `budget = columns - minLeftCells`, then take the
+ * first ladder rung whose `cells` fits. There is no second magic constant, and the
+ * threshold table in the spec is what that comparison WORKS OUT TO, not an extra
+ * branch.
+ *
+ * WHY `minLeftCells` IS 24: the word mark is 13 cells and `provider:model` + cwd +
+ * the key symbol need at least 11 more to stay readable. It is lower than
+ * `status-layout`'s 34 because the top-left half has a brand to lose while the
+ * bottom-left half has a phase that must not disappear.
+ */
+/**
+ * Bounds for the hint budget.
+ *
+ * WHY THEY LIVE IN THIS FILE (R-21, accepted): `CLAUDE.md`'s general rule is that
+ * structural bounds live in the subsystem's `limits.ts`, and `ui/layout/` has none
+ * - `budget.ts` keeps `HINT_MIN_ROWS` beside its own module for the same reason.
+ * This module has exactly one consumer. If `ui/layout/` ever grows a real
+ * `limits.ts`, these three constants should move there together; this comment is
+ * that future migration's note.
+ */
+export declare const HEADER_HINT_LIMITS: {
+    /** Cells the LEFT half of the header must keep (`AragonAgent` is 13 of them). */
+    readonly minLeftCells: 24;
+    /** Fixed spacing between two hint clauses. */
+    readonly gapCells: 2;
+};
+export type HeaderHintId = 'branch' | 'index' | 'detail';
+export interface HeaderHintClause {
+    id: HeaderHintId;
+    text: string;
+}
+export interface HeaderHintPlan {
+    /** Clauses left to right (including the overlay's `Details on/off` replacement). */
+    clauses: HeaderHintClause[];
+    /** The whole right-hand string, scroll chip included with its trailing spacing. */
+    text: string;
+    /** Total cells of the right column; `Header` uses it to size the left one. */
+    cells: number;
+    /** Cells taken by the scroll chip (0 when there is none). */
+    scrollCells: number;
+    /** True while an overlay owns the keyboard: only the detail word remains. */
+    detailsOnly: boolean;
+}
+/**
+ * Plan the right-hand hints.
+ *
+ * The four inputs are exactly the props `Header` already receives - the call site
+ * does not change, only the arithmetic behind it (spec 3.11 step 5).
+ */
+export declare function planHeaderHints(input: {
+    columns: number;
+    statusExpanded: boolean;
+    overlayOpen: boolean;
+    scrolledLines: number;
+}): HeaderHintPlan;

package/dist/ui/layout/header-hints.js

@@ -0,0 +1,138 @@
+/**
+ * The right-hand hint budget for the header row (tui-branch-terminal-shortcut 3.8).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THIS IS A PLANNER AND NOT ANOTHER TERNARY IN THE JSX (R-0-4): the header's
+ * right side used to be one hand-computed width constant (`detailCells = indexHint
+ * ? 32 : 18`). Adding a third affordance to that arithmetic produces either a
+ * clipped hint or a pushed-out word mark on a 72-column terminal, and NO TEST
+ * WOULD SEE IT - the only thing lost is trailing characters. `ui/layout/session-chip.ts`
+ * already set the precedent for the same problem: the chip has to participate in
+ * one width budget rather than be appended and hoped for.
+ *
+ * THE RULE IS ONE COMPARISON. `budget = columns - minLeftCells`, then take the
+ * first ladder rung whose `cells` fits. There is no second magic constant, and the
+ * threshold table in the spec is what that comparison WORKS OUT TO, not an extra
+ * branch.
+ *
+ * WHY `minLeftCells` IS 24: the word mark is 13 cells and `provider:model` + cwd +
+ * the key symbol need at least 11 more to stay readable. It is lower than
+ * `status-layout`'s 34 because the top-left half has a brand to lose while the
+ * bottom-left half has a phase that must not disappear.
+ */
+/**
+ * Bounds for the hint budget.
+ *
+ * WHY THEY LIVE IN THIS FILE (R-21, accepted): `CLAUDE.md`'s general rule is that
+ * structural bounds live in the subsystem's `limits.ts`, and `ui/layout/` has none
+ * - `budget.ts` keeps `HINT_MIN_ROWS` beside its own module for the same reason.
+ * This module has exactly one consumer. If `ui/layout/` ever grows a real
+ * `limits.ts`, these three constants should move there together; this comment is
+ * that future migration's note.
+ */
+export const HEADER_HINT_LIMITS = {
+    /** Cells the LEFT half of the header must keep (`AragonAgent` is 13 of them). */
+    minLeftCells: 24,
+    /** Fixed spacing between two hint clauses. */
+    gapCells: 2,
+};
+/** The verbatim clause text (spec 3.8, appendix A). */
+const BRANCH_CLAUSE = { collapsed: '^L branch', expanded: '^L new branch' };
+const INDEX_CLAUSE = { collapsed: '^I Index', expanded: '^I build index' };
+const DETAIL_CLAUSE = { collapsed: '^G more', expanded: '^G less' };
+/** L3 gives the key name and nothing else: discoverability at the last width. */
+const BRANCH_KEY_ONLY = '^L';
+/** Overlay wording, kept exactly as `Header.tsx` had it. */
+const DETAILS_ON = 'Details on';
+const DETAILS_OFF = 'Details off';
+/** Above this, the chip stops counting and saturates (`^9999+`), as it always has. */
+const SCROLL_CHIP_MAX = 9999;
+/**
+ * Plan the right-hand hints.
+ *
+ * The four inputs are exactly the props `Header` already receives - the call site
+ * does not change, only the arithmetic behind it (spec 3.11 step 5).
+ */
+export function planHeaderHints(input) {
+    // NORMALISED HERE, NOT TRUSTED (R-14). `Header` defaults to 80, but a test or a
+    // future caller may pass anything; `budget.ts::dimension()` already set the rule
+    // (non-finite or < 1 falls back, everything else floors) and this follows it.
+    const columns = normalizeDimension(input.columns, 80);
+    const scrolledLines = Math.max(0, Math.floor(normalizeDimension(input.scrolledLines, 0)));
+    const scrollCells = scrollChip(scrolledLines, input.overlayOpen);
+    if (input.overlayOpen) {
+        // THE OVERLAY OWNS THE KEYBOARD, so every key hint disappears (D-14's sibling
+        // rule, unchanged from the old JSX). The scroll chip stays: it is a position
+        // indicator, not an affordance.
+        const detail = input.statusExpanded ? DETAILS_ON : DETAILS_OFF;
+        return buildPlan([{ id: 'detail', text: detail }], scrollCells, true);
+    }
+    const ladder = ladderFor(input.statusExpanded);
+    const budget = columns - HEADER_HINT_LIMITS.minLeftCells;
+    for (const rung of ladder) {
+        const plan = buildPlan(rung, scrollCells, false);
+        if (plan.cells <= budget)
+            return plan;
+    }
+    // L4 IS UNCONDITIONAL: `^G` is the only entry in this table that may never be
+    // dropped - it is how a user who hid the status detail fields gets them back.
+    // A header narrower than the last rung still renders; the LEFT column is what
+    // shrinks (to zero), and `overflow="hidden"` keeps that from overflowing.
+    return buildPlan(ladder[ladder.length - 1] ?? [], scrollCells, false);
+}
+/** The four rungs, widest first. Built per call because the widths are text-derived. */
+function ladderFor(statusExpanded) {
+    const branch = {
+        id: 'branch',
+        text: statusExpanded ? BRANCH_CLAUSE.expanded : BRANCH_CLAUSE.collapsed,
+    };
+    const index = {
+        id: 'index',
+        text: statusExpanded ? INDEX_CLAUSE.expanded : INDEX_CLAUSE.collapsed,
+    };
+    const detail = {
+        id: 'detail',
+        text: statusExpanded ? DETAIL_CLAUSE.expanded : DETAIL_CLAUSE.collapsed,
+    };
+    return [
+        [branch, index, detail],
+        [branch, detail],
+        [{ id: 'branch', text: BRANCH_KEY_ONLY }, detail],
+        [detail],
+    ];
+}
+/**
+ * Compose the final string. The chip carries its OWN trailing spacing and is the
+ * only source of it (R-8): one space while an overlay is open, two otherwise -
+ * copied byte for byte from the expression the header already used.
+ */
+function buildPlan(clauses, scrollChipText, detailsOnly) {
+    const body = clauses.map((clause) => clause.text).join(' '.repeat(HEADER_HINT_LIMITS.gapCells));
+    const text = scrollChipText.length > 0 ? `${scrollChipText}${body}` : body;
+    return {
+        clauses,
+        text,
+        cells: text.length,
+        scrollCells: scrollChipText.length,
+        detailsOnly,
+    };
+}
+/**
+ * `^<n>` plus its trailing spacing, or `''`.
+ *
+ * THE SPACING IS PART OF THE CHIP, not something `Header` adds afterwards: with two
+ * sources of spacing a reviewer has to read two files to answer "how wide is the
+ * chip", and the overlay's single-space case lived in the JSX as a ternary nobody
+ * would think to check.
+ */
+function scrollChip(scrolledLines, overlayOpen) {
+    if (scrolledLines <= 0)
+        return '';
+    const label = scrolledLines > SCROLL_CHIP_MAX ? `^${SCROLL_CHIP_MAX}+` : `^${scrolledLines}`;
+    return label + (overlayOpen ? ' ' : '  ');
+}
+/** The `budget.ts::dimension()` rule, local because that helper is not exported. */
+function normalizeDimension(value, fallback) {
+    return Number.isFinite(value) && value >= 1 ? Math.floor(value) : fallback;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * The session-id chip: pure width planning, no JSX
+ * (tui-session-id-resume §3.9 / D-11 / D-12).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY A PLANNER AND NOT A STYLED `<Text>`: the status bar is a cell-by-cell
+ * measured row with a six-rung degradation ladder (`status-layout.ts`), not a
+ * flex layout.
+ * Anything positioned "just to the right" pushes the left half over or covers
+ * `phase`, and `phase` is the field a user needs while a run is in flight. The
+ * chip therefore spends cells out of the SAME budget as every other field.
+ *
+ * THE ID IS NEVER TRUNCATED (D-12). A truncated id produces a `--resume` command
+ * that is guaranteed to fail, which is strictly worse than showing nothing: the
+ * rungs below are, in order, "drop the label" and only then "hide the whole
+ * chip", and `/session` reports the full id at any width.
+ */
+export declare const SESSION_CHIP_LIMITS: {
+    /** The same threshold `Header.tsx` uses for its `^I Index` hint. */
+    readonly labelMinCols: 72;
+    /** Blank cells between the last status field and the chip. */
+    readonly gapCells: 2;
+    /**
+     * The tightest rung's worst-case width for the fields on the LEFT, summed:
+     * phase glyph(1)+label(4)=5, sep 1 -> 6, deferred mode 'C>B' 3 -> 9,
+     * sep 1 -> 10, 'C'+'~999%' 6 -> 16, sep 1 -> 17, thinking code 1 -> 18,
+     * sep 1 -> 19, '>99M/s' 6 -> 25, sep 1 -> 26, '>999d' 5 -> 31.
+     *
+     * 34 IS A FLOOR ROUNDED UP, not a measurement: over-estimating hides the chip
+     * one column early, which is invisible; under-estimating lets the chip eat the
+     * phase field, which is not.
+     */
+    readonly minStatusCells: 34;
+};
+export interface SessionChipPlan {
+    visible: boolean;
+    text: string;
+    cells: number;
+    gap: number;
+}
+/**
+ * Plan the chip for `columns` and this session's id.
+ *
+ * Inputs are the same ones the status row already has, so the two plans cannot
+ * disagree about the terminal: `StatusBar` computes `chip` first and hands
+ * `chip.cells + chip.gap` to `planPrimaryStatusFields` as `reserveRight`.
+ */
+export declare function planSessionChip(input: {
+    columns: number;
+    sessionId?: string | null;
+}): SessionChipPlan;

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

@@ -0,0 +1,64 @@
+/**
+ * The session-id chip: pure width planning, no JSX
+ * (tui-session-id-resume §3.9 / D-11 / D-12).
+ *
+ * ASCII ONLY - `src/ui/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY A PLANNER AND NOT A STYLED `<Text>`: the status bar is a cell-by-cell
+ * measured row with a six-rung degradation ladder (`status-layout.ts`), not a
+ * flex layout.
+ * Anything positioned "just to the right" pushes the left half over or covers
+ * `phase`, and `phase` is the field a user needs while a run is in flight. The
+ * chip therefore spends cells out of the SAME budget as every other field.
+ *
+ * THE ID IS NEVER TRUNCATED (D-12). A truncated id produces a `--resume` command
+ * that is guaranteed to fail, which is strictly worse than showing nothing: the
+ * rungs below are, in order, "drop the label" and only then "hide the whole
+ * chip", and `/session` reports the full id at any width.
+ */
+import stringWidth from 'string-width';
+export const SESSION_CHIP_LIMITS = {
+    /** The same threshold `Header.tsx` uses for its `^I Index` hint. */
+    labelMinCols: 72,
+    /** Blank cells between the last status field and the chip. */
+    gapCells: 2,
+    /**
+     * The tightest rung's worst-case width for the fields on the LEFT, summed:
+     * phase glyph(1)+label(4)=5, sep 1 -> 6, deferred mode 'C>B' 3 -> 9,
+     * sep 1 -> 10, 'C'+'~999%' 6 -> 16, sep 1 -> 17, thinking code 1 -> 18,
+     * sep 1 -> 19, '>99M/s' 6 -> 25, sep 1 -> 26, '>999d' 5 -> 31.
+     *
+     * 34 IS A FLOOR ROUNDED UP, not a measurement: over-estimating hides the chip
+     * one column early, which is invisible; under-estimating lets the chip eat the
+     * phase field, which is not.
+     */
+    minStatusCells: 34,
+};
+/** `{visible:false}` - the shape every caller can cheaply branch on. */
+const HIDDEN = { visible: false, text: '', cells: 0, gap: 0 };
+/**
+ * Plan the chip for `columns` and this session's id.
+ *
+ * Inputs are the same ones the status row already has, so the two plans cannot
+ * disagree about the terminal: `StatusBar` computes `chip` first and hands
+ * `chip.cells + chip.gap` to `planPrimaryStatusFields` as `reserveRight`.
+ */
+export function planSessionChip(input) {
+    // No identity (the default build, a test, or a host with no session) is the
+    // `undefined` case, and it must cost nothing: reserveRight stays 0 and the
+    // status row's output is byte-identical to the pre-feature build (I-6).
+    if (!input.sessionId)
+        return HIDDEN;
+    const columns = Number.isFinite(input.columns) ? Math.floor(input.columns) : 80;
+    const id = input.sessionId;
+    const gap = SESSION_CHIP_LIMITS.gapCells;
+    const fits = (text) => columns - 1 - gap - stringWidth(text) >= SESSION_CHIP_LIMITS.minStatusCells;
+    // Widest form first, then drop the label, then hide: the order is the decision.
+    const labelled = `id ${id}`;
+    if (columns >= SESSION_CHIP_LIMITS.labelMinCols && fits(labelled)) {
+        return { visible: true, text: labelled, cells: stringWidth(labelled), gap };
+    }
+    if (fits(id))
+        return { visible: true, text: id, cells: stringWidth(id), gap };
+    return HIDDEN;
+}

package/dist/ui/layout/status-layout.d.ts

@@ -44,6 +44,16 @@ export interface StatusLayoutInput {
         inFlight: boolean;
     };
     scrolledLines?: number;
+    /**
+     * Cells already spent at the RIGHT end of this same row
+     * (tui-session-id-resume 3.10 / I-6).
+     *
+     * The session-id chip is not a layer above this row: it takes its cells out of
+     * the SAME budget, because the row is measured rather than laid out and
+     * anything overlapping it eats `phase` first. ABSENT MEANS 0, which is what
+     * keeps every existing caller's plan byte-identical (I-6).
+     */
+    reserveRight?: number;
 }
 export interface StatusPrimaryInput extends StatusLayoutInput {
     feedback?: StatusFeedback;