@aragon-agent/cli 0.6.24 → 0.6.26

package/dist/session/store.js

@@ -91,6 +91,19 @@ export function sessionPathFor(id) {
  * prevent, arriving through the flag next to it. `meta.id` is no safer: it comes
  * out of a file, and files are inputs.
  *
+ * A TUI CHECKPOINT NEVER NAMES ITSELF (D-20 / R-1). This is the single line that
+ * keeps `aragon exec --resume <tui-id>` from OVERWRITING the parent checkpoint:
+ * before this check, a TUI file carrying `meta.id` made `exec` take that id,
+ * write its own result into `a4k2m9.json` and move the `--continue` pointer -
+ * silent, unrecoverable loss of the one conversation the user was still having,
+ * arriving through a directory the design had declared out of scope. The rule
+ * belongs HERE rather than in `exec/**` because every exec write-back path
+ * already funnels through this function, so one check covers all of them and
+ * `exec/**` stays untouched.
+ *
+ * The fallthrough is the "stranger file" branch that already existed below:
+ * mint a fresh id rather than build a path out of the leftovers.
+ *
  * The order is the one that keeps every legitimate resume landing where the user
  * expects: an exec-written session names itself, a TUI `/save` is named by its
  * file, and anything else gets a fresh id rather than a guess - reported back in
@@ -98,6 +111,8 @@ export function sessionPathFor(id) {
  * wondering which session it just wrote.
  */
 export function resumedSessionId(path, saved) {
+    if (saved.meta?.origin === 'tui')
+        return randomUUID();
     const declared = saved.meta?.id;
     if (typeof declared === 'string' && isValidSessionId(declared))
         return declared;
@@ -106,6 +121,17 @@ export function resumedSessionId(path, saved) {
         return base;
     return randomUUID();
 }
+/**
+ * Whether a `--resume` value is meant as a PATH rather than an id.
+ *
+ * EXPORTED SO THE FAILURE MESSAGE CANNOT DISAGREE WITH THE LOOKUP: the startup
+ * path prints one sentence for "no such id" and another for "no such file", and
+ * a second copy of this predicate is a copy that can drift (`isAbsolute` was
+ * missing from exactly such a copy).
+ */
+export function looksLikeSessionPath(value) {
+    return (isAbsolute(value) || value.includes('/') || value.includes('\\') || value.endsWith('.json'));
+}
 function ensureDir() {
     const dir = getSessionsDir();
     if (!existsSync(dir))
@@ -135,8 +161,7 @@ export function resolveSessionRef(idOrPath, cwd) {
     const value = idOrPath.trim();
     if (value.length === 0)
         return null;
-    const looksLikePath = isAbsolute(value) || value.includes('/') || value.includes('\\') || value.endsWith('.json');
-    const path = looksLikePath
+    const path = looksLikeSessionPath(value)
         ? resolve(cwd, value)
         : isValidSessionId(value)
             ? sessionPathFor(value)
@@ -199,9 +224,24 @@ function describe(path, session) {
         provider: meta?.provider ?? session.model?.providerId ?? '',
         model: meta?.model ?? session.model?.modelId ?? '',
         managed: typeof meta?.id === 'string' && meta.id.length > 0,
+        // UNTRUSTED INPUT, DEGRADED TO THE OLD BEHAVIOUR. `origin` is read out of a
+        // file, so an unknown or hostile value must not be able to make a TUI
+        // checkpoint look like an exec one (or the reverse); anything that is not
+        // exactly `'tui'` reads as `'exec'`, which is what every pre-feature file
+        // means.
+        origin: meta?.origin === 'tui' ? 'tui' : 'exec',
+        pinned: meta?.pinned === true,
+        live: meta?.live === true,
     };
 }
-function basenameId(path) {
+/**
+ * The file name without its directory or `.json` suffix.
+ *
+ * Exported because session IDENTITY derives the parent of a branch from this
+ * value and NOT from `meta.id` (D-5): the contents of a file are input, so a
+ * hand-written `meta.id` must not be able to name where this process writes.
+ */
+export function basenameId(path) {
     const name = path.replace(/\\/g, '/').split('/').pop() ?? path;
     return name.endsWith('.json') ? name.slice(0, -'.json'.length) : name;
 }
@@ -242,8 +282,12 @@ function safeReaddir(dir) {
 /** `--dry-run` reports and deletes nothing; nothing is ever pruned automatically. */
 export function pruneSessions(opts = {}) {
     const now = (opts.now ?? Date.now)();
+    const isAlive = opts.isProcessAlive ?? defaultIsProcessAlive;
     const cutoff = opts.olderThanDays === undefined ? now : now - opts.olderThanDays * 24 * 60 * 60 * 1000;
-    const doomed = listSessions({ ...(opts.all ? { all: true } : {}) }).filter((entry) => entry.updatedAt <= cutoff);
+    const doomed = listSessions({ ...(opts.all ? { all: true } : {}) }).filter((entry) => entry.updatedAt <= cutoff &&
+        isInPruneScope(entry, opts.origin ?? 'exec') &&
+        !entry.pinned &&
+        !isOwnedByALiveProcess(entry, isAlive));
     if (opts.dryRun)
         return doomed;
     for (const entry of doomed) {
@@ -257,6 +301,41 @@ export function pruneSessions(opts = {}) {
     }
     return doomed;
 }
+/**
+ * The origin half of the truth table. Files WITHOUT metadata are governed by
+ * `all` alone (they were already included or already excluded by the listing),
+ * so they pass here rather than being re-judged by a `meta` they do not have.
+ */
+function isInPruneScope(entry, origin) {
+    if (origin === 'all')
+        return true;
+    if (!entry.managed)
+        return true;
+    return (entry.origin ?? 'exec') === origin;
+}
+/**
+ * `live: true` PLUS A LIVE OWNER PID IS NEVER DELETED (§3.7 / T-33).
+ *
+ * The pid comes from the file's `.lock` payload, which is the only per-session
+ * process identity this directory carries and the same source
+ * `tryAcquireSessionLock` trusts. A `live: true` file with NO lock is deletable,
+ * and that is the honest answer rather than a gap: the flag says a writer
+ * believed itself live, not that one is alive now - a process killed in the
+ * night leaves the flag behind, and a protection that could never expire is a
+ * file nobody can ever clean up.
+ */
+function isOwnedByALiveProcess(entry, isAlive) {
+    if (!entry.live)
+        return false;
+    // THE FILE NAME, NOT `meta.id`: the lock is named after the file, and `meta.id`
+    // comes out of that file (I-12). Reading it here would probe the wrong lock for
+    // a file whose metadata disagrees with its name - and, since `join` normalises,
+    // a hostile id containing separators would read outside this directory.
+    const holder = readLock(join(getSessionsDir(), `${basenameId(entry.path)}.lock`));
+    if (!holder || holder.host !== hostname())
+        return false;
+    return isAlive(holder.pid);
+}
 // ---------------------------------------------------------------------------
 // `--continue`: the pointer, and the scan that makes it safe to keep
 // ---------------------------------------------------------------------------
@@ -299,16 +378,26 @@ export function latestSessionForCwd(cwd) {
     if (hinted && isValidSessionId(hinted.id)) {
         const path = sessionPathFor(hinted.id);
         const session = existsSync(path) ? readSessionFile(path) : null;
-        if (session?.meta && sameCwd(session.meta.cwd, cwd))
+        // BOTH BRANCHES EXCLUDE TUI CHECKPOINTS (tui-session-id-resume §3.7). The
+        // pointer branch is not defensive padding: `--continue` promises "the newest
+        // EXEC session", and TUI sessions are resumed by id. Today only
+        // `writeSession()` moves the pointer, so a TUI file cannot be named there -
+        // and that is precisely the kind of "nobody writes it today" assumption this
+        // repository has already paid for. One predicate, applied twice, is cheap.
+        if (session?.meta && originOf(session.meta) === 'exec' && sameCwd(session.meta.cwd, cwd)) {
             return describe(path, session);
+        }
     }
     const target = resolve(cwd);
     for (const entry of listSessions()) {
-        if (sameCwd(entry.cwd, target))
+        if (originOf(entry) === 'exec' && sameCwd(entry.cwd, target))
             return entry;
     }
     return null;
 }
+function originOf(value) {
+    return value.origin === 'tui' ? 'tui' : 'exec';
+}
 function sameCwd(a, b) {
     if (!a || !b)
         return false;

package/dist/todo/types.d.ts

@@ -42,9 +42,11 @@ export interface TodoSnapshot {
 /**
  * Why a list went away.
  *
- *   `user`  - `/todo clear`, or `/clear`. Both are an explicit user instruction,
- *             which is I-2's standing exception; neither touches `messages`.
- *   `reset` - `/reset`, or a `/resume` whose file carried no list (§3.13).
+ *   `user`  - `/todo clear`, or `/clear screen` (the screen-only form). Both are
+ *             an explicit user instruction, which is I-2's standing exception;
+ *             neither touches `messages`.
+ *   `reset` - `/clear` (or its alias `/reset`) through `clearMessages()`, or a
+ *             `/resume` whose file carried no list (§3.13).
  *   `turn`  - a new TUI task started, or a legacy caller began a turn after
  *             every item was completed.
  *   `stale` - unfinished, and unwritten for more than `TODO_LIMITS.staleTurns`

package/dist/ui/App.d.ts

@@ -8,10 +8,13 @@ import React from 'react';
 import type { ScrollbarBridge } from './scrollbar-controller.js';
 import type { AgentController } from '../agent/controller.js';
 import type { ConfirmRequest } from '../tools/index.js';
-import { type Overlay, type ToastLevel } from '../agent/reducer.js';
+import { type Entry, type Overlay, type ToastLevel } from '../agent/reducer.js';
 import type { UpdateBridge } from '../update/types.js';
 import type { MouseSource } from '../input/stdin-filter.js';
 import { type PasteBridge } from '../input/limits.js';
+import type { CheckpointResult } from '../session/checkpoint.js';
+import type { BranchCommandPort } from '../commands/branch-command.js';
+import type { SessionIdentity } from '../session/startup-session.js';
 import type { SelectionBridge } from './selection/selection-controller.js';
 import type { HumanInputBridge } from '../tools/human-input.js';
 export interface ConfirmBridge {
@@ -83,6 +86,55 @@ export interface AppProps {
      */
     pasteBridge?: PasteBridge;
     terminal?: TerminalBridge;
+    /**
+     * The transcript to seed the first frame with, from a resumed session
+     * (tui-session-id-resume 3.12).
+     *
+     * ABSENT IN EVERY ORDINARY LAUNCH, and absent is what keeps the first frame
+     * byte-identical to the pre-feature build (I-6).
+     */
+    initialEntries?: Entry[];
+    /** This process's session identity. `undefined` means "no chip, no checkpoint". */
+    session?: SessionIdentity;
+    /** The two actions `cli.tsx` owns: checkpoint now, and rotate after `/resume`. */
+    sessionBridge?: SessionBridge;
+    /**
+     * One line to show when the identity is NOT the obvious one (D-13): a branch,
+     * or a `--save` name. An ordinary new session says nothing - the chip is the
+     * affordance, and a notice on every launch trains users to ignore notices.
+     */
+    sessionNotice?: string;
+}
+/**
+ * `App`'s and `cli.tsx`'s small two-way surface for the session, shaped exactly
+ * like `confirmBridge` / `pasteBridge`.
+ *
+ * `checkpoint` and `rotate` are INSTALLED BY `cli.tsx` because the writer lives
+ * outside React (two of its callers are process-level); `onIdentity` is
+ * installed by the App so a rotation can move the chip, which is the only piece
+ * of the identity the view owns.
+ */
+export interface SessionBridge {
+    /**
+     * Write a checkpoint now; `pin` also marks the file as never-prunable, and
+     * `force` skips the fingerprint short circuit so `/branch` can guarantee that
+     * the file the new process is about to read is current (D-15).
+     */
+    checkpoint?: (opts?: {
+        pin?: boolean;
+        force?: boolean;
+    }) => CheckpointResult;
+    /** Adopt another conversation's identity (D-15); `undefined` if it cannot. */
+    rotate?: (loadedPath: string) => SessionIdentity | undefined;
+    /**
+     * Ctrl+L / `/branch`: branch this session into a NEW terminal. Installed by
+     * `cli.tsx`, because opening a window is a process-level act the App only asks
+     * for (tui-branch-terminal-shortcut 3.11). Absent in a build with no session,
+     * which is what lets `/branch` say so instead of throwing.
+     */
+    branch?: BranchCommandPort;
+    /** Installed by `App`; called by `rotate` after the new id is claimed. */
+    onIdentity?: (identity: SessionIdentity) => void;
 }
 export interface TerminalBridge {
     scrollbar?: ScrollbarBridge;
@@ -96,4 +148,4 @@ export interface TerminalBridge {
     writeForeign?: (text: string) => void;
     selection?: SelectionBridge;
 }
-export declare function App({ controller, version, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, pasteBridge, terminal, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, pasteBridge, terminal, initialEntries, session, sessionBridge, sessionNotice, }: AppProps): React.ReactElement;

package/dist/ui/App.js

@@ -52,9 +52,11 @@ 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';
+import { createModelProbe } from '../agent/model-probe.js';
 import { SettingsScreen, compactionSettingsFrom, fastSettingsFrom, } from './overlays/SettingsScreen.js';
 import { ConfirmDialog } from './overlays/ConfirmDialog.js';
 import { QuestionOverlay } from './overlays/QuestionOverlay.js';
@@ -120,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();
@@ -156,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);
@@ -1024,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,
@@ -1035,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
@@ -1145,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
@@ -1388,6 +1443,35 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         requestCopy: copyCoordinator.requestCopy,
         controller,
         state: stateRef.current,
+        // THE ARCHIVE'S ONLY WAY TO SEE THE SCREEN (P0-1 / §3.7), and a thunk for a
+        // reason `state` above illustrates: `state` is a snapshot of this render,
+        // while `/clear` interrupts a run and then waits for it to unwind, so the last
+        // 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();
@@ -1535,12 +1619,25 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     };
     submitRef.current = submitMessage;
     const executeSlashInput = async (raw) => {
-        const switchWhileBusy = controller.isCompactionBusy?.()
-            && /^\s*\/(clear|reset|resume)(?:\s|$)/.test(raw);
-        if (switchWhileBusy) {
+        // A CONVERSATION SWITCH OWNS THE QUEUE FOR THE WHOLE COMMAND (B-6 / §3.7).
+        //
+        // The guard used to be raised only when a compaction happened to be busy,
+        // which left the one window this feature is about unwatched: `/clear` on an
+        // IDLE session took the flag nowhere, and `drainCompactionQueue` was still
+        // free to `continue()` a message queued in the previous conversation into
+        // the one the user had just started. Whether there is work to cancel is a
+        // separate question, so the two are now separate values: `switching` decides
+        // the lock, `switchWhileBusy` decides the cancellation.
+        //
+        // `/resume` is still refused mid-run by `handleSubmit` below, so for it the
+        // lock only ever matters while idle - that is the minimum this invariant
+        // asks for, not a contradiction.
+        const switching = /^\s*\/(clear|reset|resume)(?:\s|$)/.test(raw);
+        const switchWhileBusy = switching && Boolean(controller.isCompactionBusy?.());
+        if (switching)
             switchingConversation.current = true;
+        if (switchWhileBusy)
             await controller.cancelCompaction();
-        }
         // Retain a recoverable command before any asynchronous handler can fail.
         const safe = redactText(raw, getSecrets());
         recordPrompt(safe);
@@ -1553,7 +1650,7 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             notify('error', `Command failed: ${redactText(reason, getSecrets())}\nInput: ${safe}`);
         }
         finally {
-            if (switchWhileBusy) {
+            if (switching) {
                 switchingConversation.current = false;
                 drainCompactionQueue.current();
             }
@@ -1563,7 +1660,7 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
         const trimmed = raw.trimStart();
         const slash = trimmed.startsWith('/') && !trimmed.startsWith('//');
         if (slash && (interactionPhase.current === 'running' || controller.isRunning()) &&
-            /^\/(reset|resume)(?:\s|$)/.test(trimmed)) {
+            /^\/resume(?:\s|$)/.test(trimmed)) {
             return { accepted: false,
                 reason: 'Interrupt the current run before switching conversations.' };
         }
@@ -1848,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
@@ -1893,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;
         }
         {
@@ -2050,6 +2164,18 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
     const overlay = state.overlay;
     const settingsDraft = useMemo(() => overlay === 'settings'
         ? controller.createModelSettingsDraft() : undefined, [controller, overlay]);
+    // ONE PROBE PER APP (model-profile-connection-test 5 row 9): the port needs the
+    // controller's provider registry, which the overlay has no business owning.
+    // Built only while the settings overlay is open, so no other screen pays for it.
+    const probe = useMemo(() => {
+        if (overlay !== 'settings')
+            return undefined;
+        // A test double or an embedded host may predate this port; absent means the
+        // two probe rows read `(unavailable)` rather than the screen crashing.
+        if (typeof controller.getProviderRegistry !== 'function')
+            return undefined;
+        return createModelProbe({ registry: controller.getProviderRegistry() });
+    }, [controller, overlay]);
     const hasKey = controller.hasApiKey();
     const empty = state.entries.length === 0;
     // RENDER SCOPE, so the chip and the composer hint agree with what the Ctrl+C
@@ -2155,7 +2281,7 @@ export function App({ controller, version, initialOverlay, initialPrompt, confir
             // the save handler cannot disagree about what `(inherit)` means.
             ...fastSettingsFrom(cfg.fast),
             ...compactionSettingsFrom(cfg.compaction),
-        }, apiKeys: cfg.apiKeys, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, draft: settingsDraft, onProfileSave: handleProfileSave, onReload: () => controller.createModelSettingsDraft(), onClose: () => dispatch({ type: 'setOverlay', overlay: null }), 
+        }, apiKeys: cfg.apiKeys, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, draft: settingsDraft, probe: probe, onProfileSave: handleProfileSave, onReload: () => controller.createModelSettingsDraft(), onClose: () => dispatch({ type: 'setOverlay', overlay: null }), 
         // Read from `cfg` (render scope, re-read every frame), so `/retry off`
         // while the screen is open shows the new value on the next paint.
         retrySummary: cfg.retry.enabled && cfg.retry.maxRetries > 0 ? String(cfg.retry.maxRetries) : 'off' })) : overlay === 'confirm' && confirmState ? (_jsx(ConfirmDialog, { isActive: !tooSmall, state: confirmState, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onClose: closeConfirm })) : overlay === 'question' && humanRequest?.kind === 'questions' ? (_jsx(QuestionOverlay, { isActive: !tooSmall, questions: humanRequest.questions, maxRows: overlayMaxRows, cols: cols, theme: theme, caps: caps, onSubmit: (answers) => resolveHuman({ kind: 'answers', answers, cancelled: false }) })) : overlay === 'plan' && humanRequest?.kind === 'plan' ? (_jsx(PlanReviewOverlay, { isActive: !tooSmall, plan: humanRequest.plan, maxRows: overlayMaxRows, cols: cols, scrollOffset: overlayScroll, onScrollClamp: setOverlayScroll, theme: theme, caps: caps, onVerdict: handlePlanVerdict })) : null;
@@ -2249,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?: {