@aragon-agent/cli 0.6.25 → 0.6.27

package/dist/cli.js

@@ -42,6 +42,11 @@ import { registerExecCommand } from './exec/cli-commands.js';
 import { registerSessionsCommand } from './session/cli-commands.js';
 import { registerDoctorCommand, registerInfoCommand } from './diagnostics/cli-commands.js';
 import { App } from './ui/App.js';
+import { readSessionView, publishSessionView } from './ui/session-bridge.js';
+import { SessionCheckpointWriter } from './session/checkpoint.js';
+import { resolveStartupSession, rotateToChildOf } from './session/startup-session.js';
+import { createBranchLauncher } from './session/branch-launch.js';
+import { EMPTY_USAGE_TOTAL } from './agent/reducer.js';
 import { createFrameDiffer } from './ui/frame-differ.js';
 import { wrapStdoutForFrames } from './ui/stdout-frame-writer.js';
 import { setFrameStatsProvider } from './commands/perf.js';
@@ -200,6 +205,13 @@ function toFlags(opts) {
         // reports nothing, does nothing, and leaves compaction armed.
         compaction: opts.compaction,
         compactionThreshold: opts.compactionThreshold,
+        // Site three of three for `--resume` / `--save` -- ELEVEN features, one trap
+        // (`mouse` P1-2, `team` P1-4, `todo` C-9, render L4, retry, fast, update,
+        // compaction, now session identity). A flag needs the `.option()`
+        // declaration below, a field on `CliFlags`, AND a line here; miss this one
+        // and `aragon --resume <id>` starts a brand new session with no error at all.
+        resumeSession: opts.resume,
+        saveSessionAs: opts.save,
     };
 }
 // ---------------------------------------------------------------------------
@@ -388,7 +400,33 @@ function runInteractive(flags, extras = {}) {
         process.exitCode = 2;
         return;
     }
+    // --- Session identity, resolved BEFORE the controller exists (D-9). ------
+    //
+    // BEFORE, not after, because every failure here is exit 2 with one copyable
+    // sentence and NO writes: a controller that already exists has to be disposed
+    // on a path that never rendered anything. The only write this performs is the
+    // `wx` claim of the new id.
+    const startup = resolveStartupSession({
+        ...(flags.resumeSession === undefined ? {} : { resume: flags.resumeSession }),
+        ...(flags.saveSessionAs === undefined ? {} : { saveAs: flags.saveSessionAs }),
+        cwd: process.cwd(),
+        // An explicit `--model` / `--provider` outranks the model recorded in the
+        // file: the user said what they wanted more recently than the file did.
+        explicitModel: flags.model !== undefined || flags.provider !== undefined,
+    });
+    if (!startup.ok) {
+        process.stderr.write(`${startup.message}\n`);
+        process.exitCode = 2;
+        return;
+    }
+    // MUTABLE BECAUSE `/resume` ROTATES IT (D-15). The chip follows through the
+    // App's `onIdentity`, and the writer reads `parentId` from here on every write.
+    let identity = startup.identity;
     const { controller, confirmBridge, humanInputBridge } = makeController(flags);
+    // THE RESTORE HAPPENS BEFORE THE FIRST FRAME. `initialEntries` seeds the
+    // reducer, so a resumed transcript is complete on frame one instead of filling
+    // in behind the user's eyes.
+    startup.apply(controller);
     void controller.refreshModelMetadata();
     const config = controller.getConfig();
     const caps = resolveTuiCapabilities({}, config.color);
@@ -403,6 +441,76 @@ function runInteractive(flags, extras = {}) {
     // outcome for the one feature here that runs five agents the user cannot
     // watch (§3.13 / P1-2 / R-19).
     attachTeamEvents(logger, controller);
+    // --- The checkpoint writer (D-2 / D-21 / I-10). --------------------------
+    //
+    // BUILT HERE, BEFORE EVERY EXIT PATH BELOW, because all three of them flush
+    // through it and one of them is a `process.on('exit')` handler that can fire
+    // while the frame is still on screen.
+    //
+    // `readView` reads the module-level slot `App` publishes into; with no frame
+    // yet (or after unmount) it answers `undefined` and the writer reports
+    // `no-identity` instead of writing a guess.
+    const checkpointWriter = createSessionWriter({
+        controller,
+        readView: readSessionView,
+        readParentId: () => identity.parentId,
+        startPinned: identity.pinned === true,
+    });
+    // --- The branch port (D-1 / D-2 / D-5 / D-16). ---------------------------
+    //
+    // BUILT HERE FOR THE SAME REASON THE WRITER IS: it needs the writer (to flush
+    // before spawning) and it needs `process.env` / `process.argv`, both of which
+    // belong to the host rather than to the view. The App only forwards it.
+    //
+    // The `checkpoint` closure is a THIN WRAPPER, not the writer itself: the port
+    // asks for `force: true` and reports `{ok, message}`, while the writer returns
+    // a richer result whose `reason` the launcher must not interpret.
+    const branchLauncher = createBranchLauncher({
+        checkpoint: (opts) => {
+            const result = checkpointWriter.writeNow(opts);
+            return result.ok ? { ok: true } : { ok: false, message: result.reason };
+        },
+        platform: process.platform,
+        env: process.env,
+        argv: process.argv,
+        execPath: process.execPath,
+    });
+    const sessionBridge = {
+        branch: branchLauncher,
+        checkpoint: (opts) => {
+            const result = checkpointWriter.writeNow(opts ?? {});
+            // A PIN THE REPORT DOES NOT KNOW ABOUT IS A LIE ON SCREEN. `writeNow` sets
+            // the writer's sticky flag, and `/session` afterwards reads
+            // `port.identity()`, which is React state - so without this the file says
+            // `pinned: true` while `/session` still answers `pinned  no`.
+            if (opts?.pin === true && result.ok) {
+                identity = { ...identity, pinned: true };
+                sessionBridge.onIdentity?.(identity);
+            }
+            return result;
+        },
+        rotate: (loadedPath) => {
+            // CLAIM THE NEW ID FIRST, THEN TELL THE VIEW (D-15). If the claim fails the
+            // chip keeps the id whose file it is still writing, which is the only safe
+            // half of a failed rotation.
+            const next = rotateToChildOf(loadedPath);
+            if (!next)
+                return undefined;
+            identity = next;
+            // REPUBLISH SYNCHRONOUSLY, because the writer reads the id from the
+            // published slot while it reads `parentId` from `identity` above. Between
+            // this line and the next render those two would disagree, and a flush in
+            // that window (exit, signal, `/session pin`) would write the conversation
+            // into the OLD id's file carrying the NEW `branchOf` - the exact
+            // inconsistency I-5 / I-12 forbid (the view's `onIdentity` below is what
+            // keeps the chip in step; this is what keeps the WRITER in step).
+            const view = readSessionView();
+            if (view)
+                publishSessionView({ ...view, id: next.id });
+            sessionBridge.onIdentity?.(next);
+            return next;
+        },
+    };
     let screen = null;
     let replayed = false;
     // --- Mouse wheel region routing (mouse-wheel-region-routing §4.2). -------
@@ -624,7 +732,14 @@ function runInteractive(flags, extras = {}) {
         // Without it, `kill <pid>`, closing the terminal window (SIGHUP), or a dying
         // parent all leave the user staring at a blank alternate screen with `reset`
         // as their only way out.
-        process.on('exit', restore);
+        // THE THIRD PATH, AND NOT A REDUNDANT ONE (R-17 / I-10): `waitUntilExit()` is
+        // a microtask that a killed process never reaches, and `failInteractive`
+        // reaches neither it nor the signal hook. `flushSync` is idempotent, so the
+        // three can coexist without writing three times.
+        process.on('exit', () => {
+            checkpointWriter.flushSync('exit');
+            restore();
+        });
         // The signal listeners themselves now belong to `installLogging()`, which
         // registered them before this function ever ran — and a second listener per
         // signal would race the first. This branch owns the SCREEN, so it supplies
@@ -633,6 +748,9 @@ function runInteractive(flags, extras = {}) {
         // the alternate screen), and the signal path restores before exiting.
         setScreenRestore(restore);
         setSignalTerminator((signo) => {
+            // BEFORE `restore()`: both are synchronous, but only this one needs the
+            // controller and the published view to still be live.
+            checkpointWriter.flushSync('signal');
             restore(); // Synchronous: stdout.write on a TTY is sync on every platform.
             process.exit(128 + signo);
         });
@@ -747,7 +865,7 @@ function runInteractive(flags, extras = {}) {
             vtInputWarning: vtInputSupported ? undefined : { nodeVersion: process.versions.node }, updateBridge: updateEligible ? updateBridge : undefined, 
             // Absent when nothing can refuse a paste, so a `--no-paste` tree is
             // byte-identical to a build without this feature.
-            pasteBridge: pasteOn ? pasteBridge : undefined, terminal: terminalBridge }), 
+            pasteBridge: pasteOn ? pasteBridge : undefined, terminal: terminalBridge, session: identity, sessionBridge: sessionBridge, ...(startup.initialEntries.length > 0 ? { initialEntries: startup.initialEntries } : {}), ...(startup.notice ? { sessionNotice: startup.notice } : {}) }), 
         // Full-screen owns console.* itself (I-4): Ink's patchConsole writes
         // straight to stdout and permanently shifts the fixed frame's accounting.
         {
@@ -775,6 +893,17 @@ function runInteractive(flags, extras = {}) {
     // never armed it this is one read and one string compare. Gating it would mean
     // a user who switches `mode` to `off` between the install and the next launch
     // leaves the guard armed with nothing able to disarm it.
+    // THE FIRST WRITE, IMMEDIATELY AFTER `render()` (D-2). This is what makes the
+    // id on screen resumable BEFORE the first message: a zero-turn session is a
+    // legal session, and `--resume` of one is a legitimate thing to want.
+    checkpointWriter.start();
+    // ONE SUBSCRIPTION, ON ONE EVENT (I-10). `agent_end` is the only moment a
+    // checkpoint is honest: mid-stream the turn has not settled, and every extra
+    // event subscription is another timer source to reason about.
+    checkpointWriter.attach((onAgentEnd) => controller.subscribe((event) => {
+        if (event.type === 'agent_end')
+            onAgentEnd();
+    }));
     setImmediate(() => { if (!interactiveClosed)
         markBootHealthy(VERSION); });
     if (updateEligible) {
@@ -819,6 +948,10 @@ function runInteractive(flags, extras = {}) {
         .waitUntilExit()
         .then(() => {
         interactiveClosed = true;
+        // FIRST LINE, AND BEFORE `controller.dispose()`: this flush needs the live
+        // history, the live todos and the published view, all of which the
+        // disposers below take apart.
+        checkpointWriter.flushSync('exit');
         // Also cover a successful immediate exit when launched via dist/cli.js,
         // which bypasses the launcher's code-zero boot-guard backstop.
         markBootHealthy(VERSION);
@@ -852,11 +985,57 @@ function runInteractive(flags, extras = {}) {
     })
         .catch(failInteractive);
 }
+/**
+ * Build the checkpoint writer for one process (D-2 / D-21).
+ *
+ * ONE CONSTRUCTION SITE FOR TWO PATHS. The TUI and `-p` differ in exactly one
+ * thing - where `readView` gets its transcript - and in nothing else: the same
+ * `meta` fields, the same live model, the same todos, the same cwd. Writing the
+ * eight deps twice is how `meta.turns` would come to mean two things, which is
+ * the drift class D-9 exists to prevent for `applyRestoredSession`.
+ */
+function createSessionWriter(input) {
+    const { controller } = input;
+    return new SessionCheckpointWriter({
+        readView: input.readView,
+        readHistory: () => controller.getSessionSnapshot(),
+        readTodos: () => controller.getTodoSnapshot()?.items ?? [],
+        // READ AT WRITE TIME: `/model` rebuilds the config, and a checkpoint that
+        // recorded the model from launch would name the wrong one after a switch.
+        readModel: () => {
+            const live = controller.getConfig();
+            return {
+                providerId: live.provider,
+                modelId: live.model,
+                ...(live.baseUrl ? { baseUrl: live.baseUrl } : {}),
+            };
+        },
+        readCwd: () => controller.getCwd(),
+        version: VERSION,
+        readParentId: input.readParentId,
+        startPinned: input.startPinned,
+    });
+}
 async function runOneShot(flags, prompt, quiet) {
+    // THE SAME RESOLUTION THE TUI USES (D-9 / D-21). A `-p` run has no Ink, no
+    // `/session` and no `agent_end` subscription, so `--resume` here is one read
+    // and one write - not a different feature.
+    const startup = resolveStartupSession({
+        ...(flags.resumeSession === undefined ? {} : { resume: flags.resumeSession }),
+        ...(flags.saveSessionAs === undefined ? {} : { saveAs: flags.saveSessionAs }),
+        cwd: process.cwd(),
+        explicitModel: flags.model !== undefined || flags.provider !== undefined,
+    });
+    if (!startup.ok) {
+        process.stderr.write(`${startup.message}\n`);
+        process.exitCode = 2;
+        return;
+    }
     // Headless: no App is ever rendered, so there is no human to approve a skill
     // install. The gate must know that up front rather than discovering a null
     // handler and defaulting to "yes" (§7.4 / AC-13).
     const { controller } = makeController(flags, { interactive: false });
+    startup.apply(controller);
     void controller.refreshModelMetadata();
     const logger = getLogger();
     logger.info('cli', 'run_oneshot', { quiet });
@@ -876,6 +1055,27 @@ async function runOneShot(flags, prompt, quiet) {
     // `followThrough` is read off the REAL controller here rather than through
     // `HeadlessController`, which is deliberately the minimal surface a test can
     // satisfy with an object literal (todo-plan-followthrough §3.6).
+    // THE ONE WRITE `-p` MAKES (D-21), and it is a deliberate trade: `entries` is
+    // empty because there is no transcript, while `messages` is authoritative, so a
+    // later `--resume` inherits the full context and replays no scrollback. Faking
+    // entries would put something on screen that was never displayed.
+    const checkpointWriter = createSessionWriter({
+        controller,
+        readView: () => ({
+            id: startup.identity.id,
+            entries: [],
+            usageTotal: EMPTY_USAGE_TOTAL,
+        }),
+        readParentId: () => startup.identity.parentId,
+        startPinned: startup.identity.pinned === true,
+    });
+    // STDERR, NOT STDOUT (D-21): stdout may be a pipe whose consumer expects the
+    // answer and nothing else, while a human running `-p` by hand still gets told
+    // which session they branched into.
+    if (startup.identity.kind === 'branch' && startup.identity.parentId) {
+        process.stderr.write(`[session] Resumed ${startup.identity.parentId} as a new branch: ` +
+            `${startup.identity.id} (headless: context only, no transcript).\n`);
+    }
     let code;
     try {
         code = await runHeadless(controller, prompt, {
@@ -884,6 +1084,8 @@ async function runOneShot(flags, prompt, quiet) {
         });
     }
     finally {
+        // BEFORE `dispose()`: the flush needs the live history and todos.
+        checkpointWriter.flushSync('exit');
         controller.dispose();
     }
     // Flushed HERE and not inside `runHeadless`: that module is deliberately
@@ -1461,6 +1663,16 @@ function buildProgram() {
         .version(VERSION, '-v, --version', 'Print the version')
         .argument('[prompt]', 'Task prompt (starts the TUI, or a one-shot run with -p / piped stdin)')
         .option('-p, --print', 'Headless: stream the answer to stdout, then exit')
+        // ROOT-LEVEL, AND `exec` KEEPS ITS OWN (commander does not inherit parent
+        // options: `copyInheritedSettings` copies output/help configuration only, not
+        // `.option()` definitions), so the two can coexist. T-39 asserts both option
+        // tables structurally rather than by parsing help text.
+        //
+        // `--resume` ALWAYS BRANCHES. It reads the named session and continues it under
+        // a NEW id, so the session it came from is never written again by this process;
+        // `--save` names THIS run's persistent id and pins it against `sessions prune`.
+        .option('--resume <id|path>', 'Resume a saved session as a new branch (TUI or -p)')
+        .option('--save <id>', 'Persist this session under this id (pinned against prune)')
         .option('--provider <id>', 'anthropic | openai | google')
         .option('--model <id>', 'Model id')
         .option('--base-url <url>', 'Override the provider base URL')

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

@@ -0,0 +1,61 @@
+/**
+ * `/branch` - open a new terminal on this session (tui-branch-terminal-shortcut
+ * 3.5 / D-1 / D-2 / D-12 / D-13 / D-21 / D-22).
+ *
+ * ASCII ONLY - `src/commands/**` is inside `glyphs.test.ts::inScope`, which also
+ * means every sentence in `BRANCH_COPY` is plain ASCII (no em dashes, no arrows).
+ *
+ * WHY A COMMAND AND NOT A KEY HANDLER: `Ctrl+L` dispatches `/branch` exactly the
+ * way `Ctrl+I` dispatches `/skill:project-indexer` (`App.tsx` is a documented
+ * oversize file, so new logic goes into a module and the key handler keeps doing
+ * only guard + dispatch). The side benefit is that `/branch` becomes typeable,
+ * testable, listed by `/help`, and inherits `executeSlashInput`'s try/catch - a
+ * throwing command becomes one `Command failed: ...` line instead of an unhandled
+ * rejection. The cost is ONE transcript line per press (D-21), which `Ctrl+I`
+ * already pays today.
+ *
+ * THIS BODY NEVER TOUCHES SESSION DATA (I-5): no draft read, no queue change, no
+ * message edit, no id change, no write to the parent file. It calls `identity()`
+ * and `open()` and reports what came back.
+ */
+import type { CommandContext } from './registry.js';
+import type { BranchOpenResult, BranchRequest } from '../session/branch-launch.js';
+/** What `/branch` can do. The one seam a test needs. */
+export interface BranchCommandPort {
+    open(request: BranchRequest): Promise<BranchOpenResult>;
+}
+/**
+ * Every sentence `/branch` can print, verbatim.
+ *
+ * ONE SOURCE, THREE CHANNELS (D-12): success goes to the toast (plus a notice while
+ * the agent runs, D-22), failures go to `notify` because a user has to READ a full
+ * sentence and possibly copy a command out of it, and cooldown goes to the toast
+ * because it is not a failure - it is "you already did this", which expires in two
+ * seconds and would be permanent noise in the transcript.
+ *
+ * `noIdentity` REUSES `/session`'s SENTENCE (R-10). The same state must not read
+ * two different ways depending on which key the user pressed; only the consequence
+ * clause ("so there is nothing to branch from" / "") differs.
+ *
+ * There is deliberately NO `stopped` entry (R-9): nothing ever called it.
+ */
+export declare const BRANCH_COPY: {
+    readonly noIdentity: string;
+    readonly unavailable: "Branching into a new terminal is not available in this build.";
+    readonly cooldown: (ms: number) => string;
+    readonly opened: (id: string) => string;
+    readonly checkpointFailed: (reason: string) => string;
+    readonly noLauncher: (manual: string) => string;
+    readonly spawnFailed: (reason: string, manual: string) => string;
+    readonly lateError: (reason: string) => string;
+};
+/**
+ * Run `/branch`.
+ *
+ * ASYNC BY NECESSITY, NOT BY STYLE: "the window opened" and "`wt.exe` does not
+ * exist" are distinguishable only after the child emits `'spawn'` or `'error'`,
+ * and ENOENT is reported asynchronously. `SlashCommand.run` already allows
+ * `Promise<void>`, and `App` calls this as `void executeSlashInput('/branch')`, so
+ * the UI never waits.
+ */
+export declare function runBranchCommand(ctx: CommandContext): Promise<void>;

package/dist/commands/branch-command.js

@@ -0,0 +1,117 @@
+/**
+ * `/branch` - open a new terminal on this session (tui-branch-terminal-shortcut
+ * 3.5 / D-1 / D-2 / D-12 / D-13 / D-21 / D-22).
+ *
+ * ASCII ONLY - `src/commands/**` is inside `glyphs.test.ts::inScope`, which also
+ * means every sentence in `BRANCH_COPY` is plain ASCII (no em dashes, no arrows).
+ *
+ * WHY A COMMAND AND NOT A KEY HANDLER: `Ctrl+L` dispatches `/branch` exactly the
+ * way `Ctrl+I` dispatches `/skill:project-indexer` (`App.tsx` is a documented
+ * oversize file, so new logic goes into a module and the key handler keeps doing
+ * only guard + dispatch). The side benefit is that `/branch` becomes typeable,
+ * testable, listed by `/help`, and inherits `executeSlashInput`'s try/catch - a
+ * throwing command becomes one `Command failed: ...` line instead of an unhandled
+ * rejection. The cost is ONE transcript line per press (D-21), which `Ctrl+I`
+ * already pays today.
+ *
+ * THIS BODY NEVER TOUCHES SESSION DATA (I-5): no draft read, no queue change, no
+ * message edit, no id change, no write to the parent file. It calls `identity()`
+ * and `open()` and reports what came back.
+ */
+/**
+ * Every sentence `/branch` can print, verbatim.
+ *
+ * ONE SOURCE, THREE CHANNELS (D-12): success goes to the toast (plus a notice while
+ * the agent runs, D-22), failures go to `notify` because a user has to READ a full
+ * sentence and possibly copy a command out of it, and cooldown goes to the toast
+ * because it is not a failure - it is "you already did this", which expires in two
+ * seconds and would be permanent noise in the transcript.
+ *
+ * `noIdentity` REUSES `/session`'s SENTENCE (R-10). The same state must not read
+ * two different ways depending on which key the user pressed; only the consequence
+ * clause ("so there is nothing to branch from" / "") differs.
+ *
+ * There is deliberately NO `stopped` entry (R-9): nothing ever called it.
+ */
+export const BRANCH_COPY = {
+    noIdentity: 'This session has no id (session recording is off for this build), ' +
+        'so there is nothing to branch from.',
+    unavailable: 'Branching into a new terminal is not available in this build.',
+    cooldown: (ms) => `A branch was just opened - try again in ${ms} ms.`,
+    opened: (id) => `New terminal opened - it resumes ${id} as a new branch.`,
+    checkpointFailed: (reason) => `Could not checkpoint this session (${reason}), so a new branch would start from ` +
+        'stale context. Nothing was opened.',
+    noLauncher: (manual) => `No terminal window could be opened here. Run this in another terminal:\n${manual}`,
+    spawnFailed: (reason, manual) => `Could not start the terminal (${reason}). Run this in another terminal:\n${manual}`,
+    lateError: (reason) => `The new terminal reported an error after opening: ${reason}`,
+};
+/**
+ * Run `/branch`.
+ *
+ * ASYNC BY NECESSITY, NOT BY STYLE: "the window opened" and "`wt.exe` does not
+ * exist" are distinguishable only after the child emits `'spawn'` or `'error'`,
+ * and ENOENT is reported asynchronously. `SlashCommand.run` already allows
+ * `Promise<void>`, and `App` calls this as `void executeSlashInput('/branch')`, so
+ * the UI never waits.
+ */
+export async function runBranchCommand(ctx) {
+    // 1. No identity, no branch (D-13). Without an id there is nothing for the new
+    //    window to resume, and a silent no-op reads as a bug.
+    const identity = ctx.session?.identity();
+    if (!identity) {
+        ctx.notify('warn', BRANCH_COPY.noIdentity);
+        return;
+    }
+    // 2. A build without the port says so rather than pretending.
+    const port = ctx.branch;
+    if (!port) {
+        ctx.notify('warn', BRANCH_COPY.unavailable);
+        return;
+    }
+    // 3. The cwd is the CONTROLLER's (`/cwd` can change it), never `process.cwd()`,
+    //    and `--resume` does not restore a cwd - so this value is the only chance
+    //    the new window has to land in the right directory (D-16).
+    const result = await port.open({
+        id: identity.id,
+        cwd: ctx.controller.getCwd(),
+        onLateError: (message) => ctx.notify('warn', message),
+    });
+    if (result.ok) {
+        reportOpened(ctx, identity.id);
+        return;
+    }
+    reportFailure(ctx, result);
+}
+/**
+ * Success: the toast confirms the action; while the agent runs it ALSO gets one
+ * notice line (D-22 / R-5).
+ *
+ * THE SECOND CHANNEL IS NOT REDUNDANCY. The status bar's feedback slot shows the
+ * activity phrase during a run, so a toast at that moment is invisible; a user who
+ * sees nothing presses again, gets caught by the cooldown, and sees nothing again.
+ * The notice is also where "the child inherited the last settled turn, not the one
+ * being generated" becomes visible after the fact.
+ */
+function reportOpened(ctx, id) {
+    const text = BRANCH_COPY.opened(id);
+    ctx.toast('info', text);
+    if (ctx.controller.isRunning())
+        ctx.notify('info', text);
+}
+/**
+ * Failure: one notice, one sentence, and a command the user can paste (I-4).
+ *
+ * `cooldown` is the exception that goes to the toast (D-12): it is a time hint
+ * about something that just succeeded, not a defect. `checkpoint-failed` and the
+ * two spawn failures already carry their COMPLETE sentence - the launcher composes
+ * it from `BRANCH_COPY` because only the launcher knows whether the checkpoint
+ * failed because the history was unsendable or because this frame has no id yet
+ * (R-19), and a body that re-wrapped the text would print an internal reason code.
+ */
+function reportFailure(ctx, result) {
+    if (result.reason === 'cooldown') {
+        ctx.toast('info', result.message);
+        return;
+    }
+    ctx.notify('warn', result.message);
+}

package/dist/commands/builtins.js

@@ -15,6 +15,9 @@ import { TODO_FOLLOW_LIMITS } from '../todo/limits.js';
 import { buildContinuationMessage } from '../todo/follow-through.js';
 import { MODE_LABEL, nextMode } from '../agent/agent-mode.js';
 import { loadSession, resolveSessionPath, saveSession } from '../session/persist.js';
+import { applyRestoredSession } from '../session/startup-session.js';
+import { runSessionCommand } from './session-command.js';
+import { runBranchCommand } from './branch-command.js';
 import { getLogger } from '../logging/logger.js';
 import { resolveFastTier } from '../fast/resolve.js';
 import { subagentModelSummary } from '../ui/overlays/model-profile-state.js';
@@ -1037,15 +1040,38 @@ const COMMANDS = [
                 }
                 // Loading has validated and normalized every external value. Commit
                 // synchronously so no new run can start between clearing and restoring.
+                //
+                // THE THREE CONTROLLER CALLS COME FROM THE SHARED PORT (tui-session-id-resume
+                // 3.8 / D-9): the startup `--resume` path and this command must never be
+                // two implementations of "adopt a saved conversation", which is exactly
+                // how `/clear` and `/reset` drifted apart once. `clearAllQueues` and the
+                // `restoreEntries` dispatch stay HERE: the first is indispensable for a
+                // live TUI and a no-op at startup, and the second is a VIEW action with
+                // no controller to hang it on.
                 ctx.controller.clearAllQueues();
-                ctx.controller.replaceMessages(session.messages, session.compactionIdentity);
-                // Absence clears the previous conversation's list, including old files.
-                ctx.controller.restoreTodos(session.todos ?? []);
+                applyRestoredSession(ctx.controller, session);
                 ctx.dispatch({ type: 'restoreEntries', entries: session.entries });
-                if (session.model?.providerId && session.model?.modelId) {
-                    ctx.controller.setModel(session.model.providerId, session.model.modelId, session.model.baseUrl);
+                // A NEW ID, AND A ZEROED COUNTER, IN THAT ORDER (D-15 / D-10 / R-9).
+                // Without the rotation the next checkpoint would write THIS conversation
+                // into the previous id's file - silently destroying its disk record - and
+                // without the reset the new id's `meta.usage` would bill the previous
+                // conversation's spend to this one.
+                const rotated = ctx.session?.rotate(path);
+                // GATED ON THE ROTATION, NOT ON THE COMMAND (D-10: the criterion
+                // is 'the id changed'). With no session port - a host without this
+                // feature - or a failed claim the id is unchanged, and restarting
+                // the counter there would misreport this conversation's spend. A
+                // failed claim is also the one case where the NEXT checkpoint writes
+                // another conversation into this id's file, so it is said out loud
+                // rather than left to be discovered later.
+                if (rotated)
+                    ctx.dispatch({ type: 'resetUsage' });
+                if (ctx.session && !rotated) {
+                    ctx.notify('warn', 'Could not claim a new session id; this conversation keeps the current one.');
                 }
-                ctx.notify('info', `Resumed session from ${path}`);
+                ctx.notify('info', rotated
+                    ? `Resumed session from ${path} as ${rotated.id}.`
+                    : `Resumed session from ${path}`);
                 if (ctx.state.pendingSteering.length)
                     ctx.notify('warn', `\u5df2\u53d6\u6d88 ${ctx.state.pendingSteering.length} \u6761\u672a\u63a5\u6536\u6d88\u606f`);
             }
@@ -1054,6 +1080,22 @@ const COMMANDS = [
             }
         },
     },
+    {
+        // REGISTRATION ONLY - the body lives in `commands/session-command.ts`, for
+        // the reason `/clear` and `/compact` do: this file is past the 1000-line
+        // guideline and `/session` is a report with three branches, not a one-liner.
+        name: 'session',
+        description: 'Show this session id and file; "/session copy" copies the resume command',
+        run: runSessionCommand,
+    },
+    {
+        // REGISTRATION ONLY - the body lives in `commands/branch-command.ts`, for the
+        // reason `/session` above does. `Ctrl+L` dispatches this same command, so the
+        // key and the typed word are one code path including the cooldown (D-2).
+        name: 'branch',
+        description: 'Open a new terminal on this session (Ctrl+L); the branch gets its own id',
+        run: (ctx) => runBranchCommand(ctx),
+    },
     {
         name: 'copy',
         description: 'Copy the last answer to the clipboard',

package/dist/commands/registry.d.ts

@@ -10,6 +10,8 @@ import type { Entry, NoticeLevel, Overlay, ToastLevel, ViewAction, ViewState } f
 import type { PersistedConfig } from '../config/schema.js';
 import type { FollowThroughBudget } from '../todo/follow-through.js';
 import type { UpdateCommandPort } from '../update/types.js';
+import type { SessionCommandPort } from './session-command.js';
+import type { BranchCommandPort } from './branch-command.js';
 export interface CommandContext {
     /** App-owned shared lock and single feedback path for command and selection copies. */
     requestCopy?: (request: CopyRequest) => Promise<CopyRequestResult>;
@@ -127,6 +129,32 @@ export interface CommandContext {
      * (the same rule the `update/types.js` import above follows).
      */
     transcriptEntries?: () => Entry[];
+    /**
+     * The session's read-only identity plus the two actions `/session` and
+     * `/resume` need (tui-session-id-resume 3.11 / D-14 / D-15).
+     *
+     * OPTIONAL, like `followBudget` / `update` / `mouse` / `transcriptEntries`
+     * above: every existing `CommandContext` fixture in this package builds this
+     * object by literal, and a required field would break all of them at compile
+     * time for a feature none of them is about. Absent means the build has no
+     * session identity, and `/session` says exactly that rather than pretending.
+     */
+    session?: SessionCommandPort;
+    /**
+     * The `/branch` port: open a new terminal on this session (tui-branch-terminal-
+     * shortcut 3.11 / #8).
+     *
+     * OPTIONAL for the same reason `session` above is: every existing
+     * `CommandContext` fixture in this package builds this object by literal, and a
+     * required field would break all of them at compile time for a feature none of
+     * them is about. Absent means `/branch` says "not available in this build"
+     * rather than failing silently.
+     *
+     * TYPE-ONLY import, following the rule the `session-command.js` import above
+     * records: the command needs the SHAPE of the port and of its result, never a
+     * value at run time.
+     */
+    branch?: BranchCommandPort;
 }
 /** What `/mouse` can see and do. Read at command time, never captured. */
 export interface MouseCommandPort {

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

@@ -0,0 +1,54 @@
+/**
+ * `/session` - report this session's identity, and the two things a user does
+ * with it (tui-session-id-resume §3.11 / D-13 / D-14).
+ *
+ * ASCII ONLY - `src/commands/**` is inside `glyphs.test.ts::inScope`.
+ *
+ * WHY THE BODY LIVES HERE AND THE REGISTRATION STAYS IN `builtins.ts`: the same
+ * reason `/clear` and `/compact` do. `builtins.ts` is already past the
+ * 1000-line guideline, and this command is a report, not a one-liner.
+ *
+ * COPYING THE RESUME COMMAND IS THE POINT, NOT A CONVENIENCE (D-14). Typing 6
+ * characters off a status bar is the only step of this whole feature that can
+ * fail for a human, and `/session copy` removes it: one keystroke, the exact
+ * command in the clipboard, no transcription.
+ */
+import type { CheckpointResult } from '../session/checkpoint.js';
+import type { SessionIdentity } from '../session/startup-session.js';
+import type { CommandContext } from './registry.js';
+/**
+ * What `/session` can see and do.
+ *
+ * THREE MEMBERS AND NO MORE. `identity()` is read at command time rather than
+ * captured, because `/resume` rotates the id under a live App (D-15) and a
+ * captured value would report the previous one for the rest of the session.
+ */
+export interface SessionCommandPort {
+    /** The current identity, or `undefined` when this build has none. */
+    identity(): SessionIdentity | undefined;
+    /** Write once now; `pin` also marks the file as never-prunable. */
+    checkpoint(opts?: {
+        pin?: boolean;
+    }): CheckpointResult;
+    /** Adopt another conversation and move to a derived id; `undefined` if it cannot. */
+    rotate(loadedPath: string): SessionIdentity | undefined;
+}
+/**
+ * The one path an id maps to.
+ *
+ * THROUGH `sessionPathFor` RATHER THAN A SECOND `join` (§2.2): that function is
+ * the single choke point where an id becomes a file name, and a report that
+ * built its own path would be the first thing to disagree with the writer about
+ * where a session lives.
+ */
+export declare function sessionFilePath(id: string): string;
+/**
+ * Run `/session`, `/session copy` or `/session pin`.
+ *
+ * ONE NOTICE FOR THE WHOLE REPORT (§3.11 / R-20): six separate notices would put
+ * six cards in the transcript and replay them as six fragments on exit. The
+ * `file` line is NOT truncated even when it overflows: it is a path the user
+ * needs to be able to copy, and it is in the same family as `/save`'s
+ * `Saved session to <path>`.
+ */
+export declare function runSessionCommand(ctx: CommandContext): void;