@deepseek-harness-tui/dsh-tui 0.8.8 → 0.9.1

package/lib/types/dsh-adapter/channel.js

@@ -3,29 +3,35 @@ import { assembleContextFor, installModelSelection } from '@deepseek-ai/dsh-agen
 import { isUserInvocable, renderSkillContent } from '@deepseek-ai/dsh-skill';
 import { createUserMessage, isTokenDelta, MessageId, ReasoningEffortId, } from '@deepseek-ai/dsh-llm';
 import { runSideQuestion, wrapSideQuestion } from './sideQuestion.js';
+import { collectRecentActivity, parseRecapResponse, RECAP_RECENT_CHARS, wrapRecapPrompt } from './recap.js';
+import { SESSION_COLOR_NAMES } from '../cc/sessionColors.js';
 import { SessionId } from '@deepseek-ai/dsh-session';
 import { renderContextSections, renderPrompt } from '@deepseek-ai/dsh-system-prompt';
 import { loadBaselineInstructions } from '@deepseek-ai/dsh-agent-instructions';
 import { extname, isAbsolute, join } from 'node:path';
 import { completeCommands, HIDDEN_COMMAND_NAMES, isLocalCommandName, LOCAL_COMMANDS, parseCommandName } from '../commands.js';
 import { clearResumeTarget, forgetSession, readResumeTarget, touchSession, writeResumeTarget } from '../sessionHistory.js';
-import { appendSessionTitle, deleteSessionLog, ensureLegacySessionEventTypes, sessionsRoots } from './compat/index.js';
-import { listSummaries, locateSession, noteBranch, previewSession, } from './sessions/index.js';
+import { appendSessionTitle, defaultMaxScanned, deleteSessionLog, ensureLegacySessionEventTypes, readSessionEventsFromFile, readSessionEventsFromLog, sessionsRoots } from './compat/index.js';
+import { buildSessionTree, forkTarget, liveTailWindow, rewindTarget, turnUserText, } from './sessionTree.js';
+import { resolveDshProfileName } from '../update.js';
+import { listSummaries, locateSession, noteBranch, previewSession, readHeader, } from './sessions/index.js';
 import { writeActivityFrames } from '../activityPrefs.js';
 import { isPathLikeQuery, rankFileCandidates } from '../utils/fileSuggestions.js';
 import { readEffortPref, writeEffortPref } from '../effortPrefs.js';
 import { readModelPref, writeModelPref } from '../modelPrefs.js';
 import { explicitModelRoute, recordedModelRoute, resolveModelRoute, validateModelRoute } from '../modelRoute.js';
 import { readPresetPref, writePresetPref } from '../presetPrefs.js';
-import { composePreset, resolvePersistedPreset, rosterOf, runningPresetOf, serviceForAgent } from './presets.js';
-import { isPresetName } from '../components/activityFrames.js';
+import { composePreset, resolvePersistedPreset, resolvePersistedRoute, rosterOf, runningPresetOf, serviceForAgent } from './presets.js';
+import { isPresetName, PRESET_NAMES } from '../components/activityFrames.js';
 import { existsSync, statSync, writeFileSync } from 'node:fs';
 import { logForDebugging } from '../utils/debug.js';
 import { homeDir, LEGACY_DATA_DIR } from '../utils/paths.js';
 import { extractMentions } from '../utils/mentions.js';
-import { t } from '../i18n.js';
+import { getLang, LANGS, t } from '../i18n.js';
+import { AUTO_THEME_NAME, THEME_NAMES } from '../theme.js';
+import { listCustomThemes } from '../customTheme.js';
 import { modeDisplayName, resolveSessionModes } from '../sessionModes.js';
-import { normalizeStatusBar, normalizeToolBackground } from '../tuiDisplayPrefs.js';
+import { normalizeScrollGutter, normalizeStatusBar, normalizeToolBackground } from '../tuiDisplayPrefs.js';
 import { SubagentActivityStore } from './subagents.js';
 import { ActivityTracker } from 'dsh-working-activity/status';
 import { featureOn } from 'dsh-working-activity/config';
@@ -328,6 +334,72 @@ function toolResultText(event) {
         return '';
     return block.content.map(item => item.type === 'text' ? item.text : '').join('').trim();
 }
+/** Phase badge for the harness goal card — mirrors the panel's PhaseBadge. */
+const GOAL_RESULT_BADGE = {
+    active: '● active',
+    paused: '⏸ paused',
+    blocked: '⛔ blocked',
+    complete: '✓ complete',
+};
+/**
+ * Summary cards for the harness's goal/todo tools. Their results are machine
+ * JSON (`{"goal":{…}}` / `{"todos":[…]}`) that would otherwise dump under the
+ * tool card as a raw `⎿ {"goal":…}` line. Matched by tool-name substring AND
+ * payload shape, so unrelated tools and plain-text results pass through to
+ * the registry/raw-text path untouched. Runs on the live stream and replay.
+ */
+function harnessToolResultView(name, data) {
+    const lower = name.toLowerCase();
+    const isGoalTool = lower.includes('goal');
+    const isTodoTool = lower.includes('todo');
+    if (!isGoalTool && !isTodoTool)
+        return undefined;
+    const block = data.message.content[0];
+    if (block === undefined || block.type !== 'tool-result')
+        return undefined;
+    const text = block.content.map(item => item.type === 'text' ? item.text : '').join('').trim();
+    if (text === '' || !text.startsWith('{'))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const record = parsed;
+    if (isGoalTool && typeof record.goal === 'object' && record.goal !== null) {
+        const goal = record.goal;
+        if (typeof goal.objective === 'string' && typeof goal.phase === 'string') {
+            const badge = GOAL_RESULT_BADGE[goal.phase] ?? goal.phase;
+            const rounds = typeof goal.roundsStarted === 'number' && typeof goal.maxGoalRounds === 'number'
+                ? ` · ${goal.roundsStarted}/${goal.maxGoalRounds}`
+                : '';
+            const activation = typeof record.activation === 'string' ? ` · ${record.activation}` : '';
+            const lines = [`🎯 ${goal.objective}`, `${badge}${rounds}${activation}`];
+            const blocked = goal.blockedReason?.message;
+            if (typeof blocked === 'string')
+                lines.push(`⛔ ${blocked}`);
+            return { card: 'generic', content: lines.map(line => ({ type: 'text', text: line })) };
+        }
+    }
+    if (isTodoTool && Array.isArray(record.todos)) {
+        const rows = record.todos;
+        const done = rows.filter(row => row.status === 'completed').length;
+        const lines = [`todos ✓ ${done}/${rows.length}`];
+        for (const row of rows) {
+            if (row.status !== 'in_progress' || typeof row.content !== 'string')
+                continue;
+            lines.push(`● ${row.content}`);
+            if (lines.length >= 4)
+                break;
+        }
+        return { card: 'generic', content: lines.map(line => ({ type: 'text', text: line })) };
+    }
+    return undefined;
+}
 function toolErrorText(event) {
     const failure = event.data.error;
     if (failure === undefined)
@@ -433,8 +505,7 @@ export function createChannel(ctx, initialAgent, options) {
             try {
                 runtime.interrupt(target, { kind: 'ancestor', agent });
                 subagentStore.onCancelled(agentId, 'interrupted');
-                state.subagents = subagentStore.snapshot();
-                syncSubagentRows();
+                syncSubagentsNow();
                 state.emit();
                 return true;
             }
@@ -467,9 +538,12 @@ export function createChannel(ctx, initialAgent, options) {
     /**
      * Sync subagentStore state into ChatRows (insert/update in state.rows).
      * Called whenever subagent state changes (spawned/completed/failed/output).
+     * Accepts a caller-taken snapshot to avoid the double copy on the hot path
+     * (session/event fires per subagent token: snapshot here + snapshot in the
+     * caller = two full state copies before emitStream's 16ms throttle).
      */
-    const syncSubagentRows = () => {
-        const snapshot = subagentStore.snapshot();
+    const syncSubagentRows = (preSnapshot) => {
+        const snapshot = preSnapshot ?? subagentStore.snapshot();
         for (const sub of snapshot) {
             let row = subagentRowsByAgentId.get(sub.agentId);
             if (!row) {
@@ -546,6 +620,32 @@ export function createChannel(ctx, initialAgent, options) {
     const listeners = new Set();
     /** True while a frame-aligned stream notification is pending (emitStream). */
     let streamNotifyScheduled = false;
+    /** True while subagent assistant/chunk deltas have deferred their
+     *  snapshot+projection to the frame-aligned flush (emitStream's timer).
+     *  Chunks arrive at token rate (100-300 events/s) and the projection is a
+     *  full deep state copy (SubagentActivityStore.snapshot) plus a SubagentRow
+     *  rebuild per tracked agent — running that per token sits BEFORE
+     *  emitStream's 16ms coalescing and defeats it. Non-chunk events
+     *  (tool/call, subagent/end, interrupt) project immediately and clear
+     *  this flag, so lifecycle transitions stay synchronous. */
+    let subagentStreamDirty = false;
+    /** Deferred projection for the frame-aligned flush: runs INSIDE the
+     *  emitStream timer, before listeners wake, so React always reads fully
+     *  projected rows. No-op unless a chunk marked the projection dirty. */
+    const flushSubagentStream = () => {
+        if (!subagentStreamDirty)
+            return;
+        subagentStreamDirty = false;
+        state.subagents = subagentStore.snapshot();
+        syncSubagentRows(state.subagents);
+    };
+    /** Immediate projection; supersedes any pending deferred flush (the fresh
+     *  snapshot already contains everything the deferred pass would project). */
+    const syncSubagentsNow = () => {
+        subagentStreamDirty = false;
+        state.subagents = subagentStore.snapshot();
+        syncSubagentRows(state.subagents);
+    };
     // foldRows incremental cursor (see foldRows): rows only append past the
     // fold line, so each pass touches only newly-eligible rows.
     const foldCursor = { rows: null, index: 0 };
@@ -770,6 +870,79 @@ export function createChannel(ctx, initialAgent, options) {
             ctx.logger.warn('dsh-tui: tui/session-switched dispatch failed: %o', error);
         }
     };
+    /**
+     * Swap the live agent for a freshly created fork (rewindTo and the session
+     * tree's rewindToNode share this tail): reset every session-scoped
+     * projection, replay the fork's seed into a fresh transcript (tokens/
+     * spinner counters land back at the rewind point, matching the fork),
+     * rebind subscriptions to the new agent, and free the replaced handle.
+     * Returns the source session's id (for the session-switched notification).
+     */
+    const adoptForkedAgent = (handle, seed, agentPreset, childId) => {
+        // Replay the forked history into a fresh transcript (tokens/spinner
+        // counters land back at the rewind point, matching the fork).
+        streaming = undefined;
+        reasoning = undefined;
+        // Stale sealed/thinking bookkeeping belongs to the OLD agent's rows;
+        // keep it out of the next turn's settle logs and revive cache.
+        sealedReasoning.length = 0;
+        lastReasoningRow = undefined;
+        toolCards.clear();
+        nextRowId = 0;
+        state.rows.length = 0;
+        // Goal/todo/title are session-scoped; the replay re-derives them for
+        // the session being entered (or leaves them empty).
+        state.todos = [];
+        // Queued-but-undelivered messages live in the OLD agent's inbox; the
+        // swap must drop their previews or they linger forever (unretirable —
+        // retire events are filtered to the new agent, unwithdrawable — the
+        // new inbox never heard of them).
+        state.pending = [];
+        state.goal = undefined;
+        state.sessionTitle = '';
+        state.sessionColor = '';
+        state.tokens = { input: 0, output: 0 };
+        state.responseChars = 0;
+        state.activeToolCount = 0;
+        state.lastUserText = '';
+        state.working = false;
+        state.spinnerMode = 'requesting';
+        state.status = handle.agent.status;
+        state.agentId = handle.agent.id;
+        state.agentPreset = agentPreset;
+        state.tps = undefined;
+        state.tpsSamples = [];
+        state.lastUsage = undefined;
+        state.workingActivity = undefined;
+        state.contextSegments = {
+            system: 0,
+            prompt: 0,
+            assistant: 0,
+            thinking: 0,
+            tools: 0,
+        };
+        replayEvents(seed);
+        settleStreaming();
+        // A seed ending mid-turn replays a turn/start that set working=true;
+        // the boot path resets this after replay — mirror it here so an idle
+        // rewound agent doesn't sit with a live spinner (a still-running
+        // agent re-asserts on its next event).
+        state.working = handle.agent.status === 'running';
+        // Rebind subscriptions to the new agent, then free the old one.
+        const oldHandle = currentHandle;
+        const sourceSessionId = String(agent.session.id);
+        agent = handle.agent;
+        currentHandle = handle;
+        bindAgent();
+        refreshCommandList();
+        void refreshLoadedContext();
+        void refreshSkillCommands();
+        // The forked session (rewind) becomes the most recently used.
+        touchSession(childId);
+        state.emit();
+        void oldHandle?.dispose().catch(() => { });
+        return sourceSessionId;
+    };
     /** Monotonic token: only the latest `interruptAndDeliver` re-queues, so a
      *  second interrupt while the abort settles cannot double-deliver. */
     let interruptSeq = 0;
@@ -1136,12 +1309,86 @@ export function createChannel(ctx, initialAgent, options) {
     // it is keyed by cwd so a /workspace switch or resumed session never reuses
     // another directory's listing.
     const fileCandidateCache = { cwd: '', load: undefined };
+    // `/model <provider/id>` completion: the model catalog is async (one llm
+    // listModels per provider), so the first keystrokes that could be heading
+    // for /model warm a session-lifetime cache — the shared promise dedupes
+    // concurrent triggers, children() synchronously serves whatever has landed,
+    // and the arrival state.emit() reopens the menu mid-typing. switchModel's
+    // success path drops the cache so the [current] tag re-resolves against
+    // the new route.
+    const modelNodeCache = {
+        nodes: undefined,
+        load: undefined,
+    };
+    const warmModelNodes = () => {
+        if (modelNodeCache.load !== undefined)
+            return;
+        modelNodeCache.load = state.listModels().then((list) => {
+            modelNodeCache.nodes = list.map((model) => ({
+                name: `${model.provider}/${model.id}`,
+                description: model.name,
+                ...(state.provider === model.provider && state.model === model.id
+                    ? { tag: 'current' }
+                    : {}),
+            }));
+            state.emit();
+        }).catch(() => {
+            // listModels already swallows per-provider failures; this only fires
+            // when the llm service shape itself is missing — settle on an empty
+            // menu rather than retrying on every keystroke.
+            modelNodeCache.nodes = [];
+        });
+    };
+    // `/preset <id>` completion: same warm-cache pattern as models. The
+    // current/default tags resolve at children() time (sync state reads), so
+    // no cache invalidation is needed on switch.
+    const presetOptionCache = {
+        list: undefined,
+        load: undefined,
+    };
+    const warmPresetOptions = () => {
+        if (presetOptionCache.load !== undefined)
+            return;
+        presetOptionCache.load = state.listPresets().then((list) => {
+            presetOptionCache.list = list;
+            state.emit();
+        }).catch(() => {
+            presetOptionCache.list = [];
+        });
+    };
+    // `/effort <id>` completion: state.effortLevels is the sync vocabulary
+    // (populated on route changes); when still unknown, one best-effort
+    // resolveEfforts warms it. `tried` caps the retry — resolveEfforts
+    // notifies on hard errors, so keystroke-time retries would spam.
+    const effortWarm = { tried: false };
+    const warmEffortLevels = () => {
+        if (state.effortLevels !== undefined || effortWarm.tried)
+            return;
+        effortWarm.tried = true;
+        void resolveEfforts().then((resolved) => {
+            if (resolved === 'unavailable' || resolved === 'error')
+                return;
+            effortWarm.tried = false;
+            state.emit();
+        }).catch(() => { });
+    };
     const state = {
         effortLevels: undefined,
         version: 0,
         rows: [],
         status: 'starting',
         sessionTitle: '',
+        sessionColor: '',
+        get autoRecapOnOpen() {
+            // Live read (not a boot snapshot): a /settings change applies on the
+            // next session switch. No settings service → off (framework absent,
+            // e.g. headless fixtures — nothing to configure and no llm route).
+            const settings = ctx.get('settings');
+            if (settings === undefined)
+                return false;
+            const ns = settings.describe({ redactSecrets: true }).find(entry => entry.ns === 'dsh-tui');
+            return ns?.value?.recapOnOpen !== false;
+        },
         agentId: agent.id,
         model: options.model,
         provider: options.provider,
@@ -1166,9 +1413,16 @@ export function createChannel(ctx, initialAgent, options) {
         modeIndex: 0,
         workingActivity: undefined,
         activityFrames: options.activityFrames,
+        configuredProvider: options.configuredProvider,
+        configuredModel: options.configuredModel,
+        configuredPreset: options.configuredPreset,
+        configuredActivityFrames: options.configuredActivityFrames,
+        configuredLang: options.configuredLang,
         diffLayout: options.diffLayout ?? 'auto',
         thinkingFold: options.thinkingFold ?? 'preview',
         toolBackground: normalizeToolBackground(options.toolBackground),
+        scrollGutter: normalizeScrollGutter(options.scrollGutter),
+        promptSessionLabel: options.promptSessionLabel === true,
         statusBar: normalizeStatusBar(options.statusBar),
         whale: options.whale !== false,
         minimal: options.minimal === true,
@@ -1181,7 +1435,106 @@ export function createChannel(ctx, initialAgent, options) {
         pending: [],
         commandList: LOCAL_COMMANDS,
         commandCompletions(input) {
+            // Warm the async vocabularies as soon as the input could be heading
+            // for their commands (`/m`, `/pre`, …) — by the time a trailing space
+            // asks children() for nodes, the fetch has usually landed.
+            const head = input.slice(1).split(/[\t ]/)[0]?.toLowerCase() ?? '';
+            if (head !== '') {
+                if ('model'.startsWith(head))
+                    warmModelNodes();
+                if ('preset'.startsWith(head))
+                    warmPresetOptions();
+                if ('effort'.startsWith(head))
+                    warmEffortLevels();
+            }
             return completeCommands(input, state.commandList, (path) => {
+                if (path.length === 1 && path[0] === 'model') {
+                    // provider/id specs, current model tagged; see modelNodeCache.
+                    warmModelNodes();
+                    return modelNodeCache.nodes ?? [];
+                }
+                if (path.length === 1 && path[0] === 'lang') {
+                    return [
+                        { name: 'status', description: 'Show the current UI language', descriptionKey: 'sugg-status-desc' },
+                        ...LANGS.map((lang) => ({
+                            name: lang,
+                            description: `Switch the UI language to ${lang}`,
+                            descriptionKey: lang === 'zh' ? 'sugg-lang-zh-desc' : 'sugg-lang-en-desc',
+                            ...(getLang() === lang ? { tag: 'current' } : {}),
+                        })),
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'theme') {
+                    return [
+                        { name: 'status', description: 'Show the current theme', descriptionKey: 'sugg-status-desc' },
+                        { name: AUTO_THEME_NAME, description: 'Follow the terminal background', descriptionKey: 'sugg-theme-auto-desc' },
+                        ...THEME_NAMES.map((name) => ({
+                            name,
+                            description: `Built-in theme ${name}`,
+                            descriptionKey: 'sugg-theme-builtin-desc',
+                        })),
+                        ...listCustomThemes()
+                            .filter((spec) => spec.name !== AUTO_THEME_NAME)
+                            .map((spec) => ({
+                            name: spec.name,
+                            description: `User theme (${spec.base} base)`,
+                            descriptionKey: 'sugg-theme-user-desc',
+                        })),
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'color') {
+                    return [
+                        { name: 'status', description: 'Show the current session color', descriptionKey: 'sugg-status-desc' },
+                        { name: 'reset', description: 'Clear the session color', descriptionKey: 'sugg-color-reset-desc' },
+                        ...SESSION_COLOR_NAMES.map((name) => ({
+                            name,
+                            description: 'Session accent color',
+                            descriptionKey: 'sugg-color-name-desc',
+                            ...(state.sessionColor === name ? { tag: 'current' } : {}),
+                        })),
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'effort') {
+                    warmEffortLevels();
+                    return [
+                        { name: 'status', description: 'Show the current reasoning effort', descriptionKey: 'sugg-status-desc' },
+                        ...(state.effortLevels ?? []).map((id) => ({
+                            name: id,
+                            description: 'Reasoning effort level',
+                            descriptionKey: 'sugg-effort-level-desc',
+                            ...(state.reasoningEffort === id ? { tag: 'current' } : {}),
+                        })),
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'preset') {
+                    warmPresetOptions();
+                    return [
+                        { name: 'status', description: 'Show the current agent preset', descriptionKey: 'sugg-status-desc' },
+                        ...(presetOptionCache.list ?? []).map((preset) => ({
+                            name: preset.id,
+                            description: preset.description ?? preset.name ?? preset.id,
+                            ...(preset.id === state.agentPreset
+                                ? { tag: 'current' }
+                                : preset.isDefault
+                                    ? { tag: 'default' }
+                                    : {}),
+                        })),
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'activity') {
+                    return [
+                        { name: 'status', description: 'Show the current activity preset', descriptionKey: 'sugg-status-desc' },
+                        { name: 'frames', description: 'List or switch frame presets', descriptionKey: 'sugg-activity-frames-desc' },
+                    ];
+                }
+                if (path.length === 2 && path[0] === 'activity' && path[1] === 'frames') {
+                    return PRESET_NAMES.map((name) => ({
+                        name,
+                        description: 'Animation frame preset',
+                        descriptionKey: 'sugg-activity-frame-desc',
+                        ...(state.activityFrames === name ? { tag: 'current' } : {}),
+                    }));
+                }
                 if (path.length === 1 && path[0] === 'workspace') {
                     const builtins = [
                         { name: 'resume', description: 'Switch to another workspace', descriptionKey: 'cmd-desc-workspace-resume' },
@@ -1200,6 +1553,21 @@ export function createChannel(ctx, initialAgent, options) {
                         })),
                     ];
                 }
+                if (path.length === 1 && path[0] === 'permission') {
+                    // Sandbox-preset vocabulary of the `/permission` picker — Tab
+                    // completes it for keyboard users, Enter still dispatches.
+                    return [
+                        { name: 'read-only', description: 'Read-only session: no file writes, no commands', descriptionKey: 'permission-preset-readonly-desc' },
+                        { name: 'workspace-write', description: 'Read/write inside the workspace; writes need a prior read', descriptionKey: 'permission-preset-workspace-write-desc' },
+                        { name: 'danger-full-access', description: 'Unrestricted access, no approvals', descriptionKey: 'permission-preset-full-access-desc' },
+                    ];
+                }
+                if (path.length === 1 && path[0] === 'plan') {
+                    return [
+                        { name: 'on', description: 'Enter plan mode: read-only, plan before acting', descriptionKey: 'plan-mode-on-desc' },
+                        { name: 'off', description: 'Exit plan mode, back to normal execution', descriptionKey: 'plan-mode-off-desc' },
+                    ];
+                }
                 return commandTrees?.children(path) ?? [];
             });
         },
@@ -1240,6 +1608,9 @@ export function createChannel(ctx, initialAgent, options) {
             streamNotifyScheduled = true;
             const timer = setTimeout(() => {
                 streamNotifyScheduled = false;
+                // Deferred subagent projection rides this same frame: flush BEFORE
+                // the listeners wake so React reads fully projected rows.
+                flushSubagentStream();
                 foldRows(state.rows, MAX_ROWS, foldCursor);
                 for (const listener of listeners)
                     listener();
@@ -1509,67 +1880,9 @@ export function createChannel(ctx, initialAgent, options) {
             catch (error) {
                 state.notify(t('rewind-attach-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'warning', timeoutMs: 8000 });
             }
-            // Replay the forked history into a fresh transcript (tokens/spinner
-            // counters land back at the rewind point, matching the fork).
-            streaming = undefined;
-            reasoning = undefined;
-            // Stale sealed/thinking bookkeeping belongs to the OLD agent's rows;
-            // keep it out of the next turn's settle logs and revive cache.
-            sealedReasoning.length = 0;
-            lastReasoningRow = undefined;
-            toolCards.clear();
-            nextRowId = 0;
-            state.rows.length = 0;
-            // Goal/todo/title are session-scoped; the replay re-derives them for
-            // the session being entered (or leaves them empty).
-            state.todos = [];
-            // Queued-but-undelivered messages live in the OLD agent's inbox; the
-            // swap must drop their previews or they linger forever (unretirable —
-            // retire events are filtered to the new agent, unwithdrawable — the
-            // new inbox never heard of them).
-            state.pending = [];
-            state.goal = undefined;
-            state.sessionTitle = '';
-            state.tokens = { input: 0, output: 0 };
-            state.responseChars = 0;
-            state.activeToolCount = 0;
-            state.lastUserText = '';
-            state.working = false;
-            state.spinnerMode = 'requesting';
-            state.status = handle.agent.status;
-            state.agentId = handle.agent.id;
-            state.agentPreset = rewindComposed.agentPreset;
-            state.tps = undefined;
-            state.tpsSamples = [];
-            state.lastUsage = undefined;
-            state.workingActivity = undefined;
-            state.contextSegments = {
-                system: 0,
-                prompt: 0,
-                assistant: 0,
-                thinking: 0,
-                tools: 0,
-            };
-            replayEvents(seed);
-            settleStreaming();
-            // A seed ending mid-turn replays a turn/start that set working=true;
-            // the boot path resets this after replay — mirror it here so an idle
-            // rewound agent doesn't sit with a live spinner (a still-running
-            // agent re-asserts on its next event).
-            state.working = handle.agent.status === 'running';
-            // Rebind subscriptions to the new agent, then free the old one.
-            const oldHandle = currentHandle;
-            const sourceSessionId = String(agent.session.id);
-            agent = handle.agent;
-            currentHandle = handle;
-            bindAgent();
-            refreshCommandList();
-            void refreshLoadedContext();
-            void refreshSkillCommands();
-            // The forked session (rewind) becomes the most recently used.
-            touchSession(childId);
-            state.emit();
-            void oldHandle?.dispose().catch(() => { });
+            // Swap the live agent for the fork (shared with rewindToNode): replay
+            // the seed, rebind, and free the replaced handle.
+            const sourceSessionId = adoptForkedAgent(handle, seed, rewindComposed.agentPreset, childId);
             // Decision-event pair around the completed rewind: `tui/rewind-done`
             // (the first non-empty string is toasted as the post-rewind summary,
             // e.g. a plugin reporting restored files) and the generic
@@ -1609,6 +1922,685 @@ export function createChannel(ctx, initialAgent, options) {
             notifySessionSwitched('rewind', String(childId), sourceSessionId);
             return row.text;
         },
+        async buildSessionTree() {
+            const persistence = ctx.get('sessionPersistence');
+            if (!persistence) {
+                state.notify(t('tree-unavailable'), { color: 'error' });
+                return null;
+            }
+            // Pin the live session snapshot NOW: every await below (list/inspect)
+            // is a window in which a fire-and-forget switch (/new, /resume,
+            // /model) can swap `agent`. Reading agent.session piecemeal would
+            // stitch the NEW session's events under the OLD session's id — a
+            // confirm would then rewind from the wrong persisted log. Everything
+            // below reads this snapshot, and the result is discarded if the live
+            // session moved on before the build finished.
+            const liveSession = agent.session;
+            const currentId = String(liveSession.id);
+            // Same enumerate as the /resume listing (snapshots when the backend
+            // offers revisions, plain list otherwise), each header narrowed through
+            // the sessions reader — one malformed header costs that session its
+            // metadata, never the whole tree. `raw` stays the backend's own header
+            // object for locate() below.
+            let listed = [];
+            try {
+                if (typeof persistence.listSnapshots === 'function') {
+                    const snapshots = await persistence.listSnapshots();
+                    listed = snapshots.flatMap(snapshot => {
+                        const raw = snapshot?.header;
+                        const header = readHeader(raw);
+                        return header === undefined ? [] : [{ header, raw }];
+                    });
+                }
+                else if (typeof persistence.list === 'function') {
+                    const headers = await persistence.list();
+                    listed = headers.flatMap(raw => {
+                        const header = readHeader(raw);
+                        return header === undefined ? [] : [{ header, raw }];
+                    });
+                }
+            }
+            catch {
+                // A listing failure degrades the tree to the live session only.
+            }
+            // Same cwd scoping as /resume (Claude Code's project dimension): forks
+            // inherit cwd, so the family never crosses projects — and the match is
+            // the project-aware one /resume uses, so a pre-upgrade subdirectory
+            // path, Windows separators, or a case variant on one header cannot
+            // quietly amputate the ancestors and siblings it records. Subagent
+            // child sessions carry parentSession too, but they are delegation
+            // artifacts, not rewind branches — exclude them from the family.
+            const local = listed.filter(entry => sessionCwdMatches(state.cwd, entry.header.cwd ?? '') &&
+                entry.header.origin !== 'subagent' &&
+                (entry.header.delegationDepth ?? 0) === 0);
+            const headerById = new Map(local.map(entry => [entry.header.id, entry]));
+            // The live session's header may not be materialized in list() yet
+            // (the jsonl backend writes on first append) — overlay the in-memory
+            // header so the ancestor walk below still finds a fresh fork's parent.
+            const liveMeta = liveSession.header;
+            if (!headerById.has(currentId) && liveMeta !== undefined) {
+                headerById.set(currentId, { header: readHeader(liveMeta) ?? { id: currentId, cwd: undefined, createdAt: undefined, parentSession: undefined, origin: undefined, delegationDepth: undefined, seedLength: undefined, agentPreset: undefined }, raw: liveMeta });
+            }
+            // Family = the live session's ancestor chain PLUS every descendant of
+            // its topmost known ancestor (siblings and cousins included).
+            const childrenByParent = new Map();
+            for (const entry of local) {
+                if (entry.header.parentSession === undefined)
+                    continue;
+                const list = childrenByParent.get(entry.header.parentSession);
+                if (list === undefined)
+                    childrenByParent.set(entry.header.parentSession, [entry.header.id]);
+                else
+                    list.push(entry.header.id);
+            }
+            const ancestorIds = [];
+            {
+                const visited = new Set([currentId]);
+                let cursor = headerById.get(currentId);
+                while (cursor?.header.parentSession !== undefined) {
+                    const parentId = cursor.header.parentSession;
+                    if (visited.has(parentId))
+                        break;
+                    visited.add(parentId);
+                    if (!headerById.has(parentId))
+                        break;
+                    ancestorIds.push(parentId);
+                    cursor = headerById.get(parentId);
+                }
+            }
+            // BFS from the topmost ancestor. The scan must NOT be gated by family
+            // membership: ancestor-chain nodes are already in the family, and
+            // skipping them here would never enumerate their other children —
+            // siblings/cousins forking off a MIDDLE ancestor would be lost.
+            const family = new Set([currentId, ...ancestorIds]);
+            {
+                const scanned = new Set();
+                const queue = [ancestorIds.at(-1) ?? currentId];
+                while (queue.length > 0) {
+                    const id = queue.shift();
+                    if (scanned.has(id))
+                        continue;
+                    scanned.add(id);
+                    family.add(id);
+                    for (const child of childrenByParent.get(id) ?? []) {
+                        queue.push(child);
+                    }
+                }
+            }
+            // Processing order is TOPOLOGICAL (a parent before its children): the
+            // coverage bookkeeping below — which seq range each chain already
+            // shows — feeds the next read's inherited-prefix skip, so a parent
+            // must be read before its forks. Within each sibling group the live
+            // chain wins, then newest first (the same priority the read budget
+            // always had).
+            const ancestorSet = new Set(ancestorIds);
+            const priorityOf = (a, b) => {
+                const aChain = a === currentId || ancestorSet.has(a);
+                const bChain = b === currentId || ancestorSet.has(b);
+                if (aChain !== bChain)
+                    return aChain ? -1 : 1;
+                return (headerById.get(b)?.header.createdAt ?? 0) - (headerById.get(a)?.header.createdAt ?? 0);
+            };
+            const kidsOf = new Map();
+            const familyRoots = [];
+            for (const id of family) {
+                const parentId = headerById.get(id)?.header.parentSession;
+                if (parentId !== undefined && parentId !== id && family.has(parentId)) {
+                    const list = kidsOf.get(parentId);
+                    if (list === undefined)
+                        kidsOf.set(parentId, [id]);
+                    else
+                        list.push(id);
+                }
+                else {
+                    familyRoots.push(id);
+                }
+            }
+            familyRoots.sort(priorityOf);
+            for (const list of kidsOf.values())
+                list.sort(priorityOf);
+            const ordered = [];
+            {
+                const seen = new Set();
+                const stack = [...familyRoots].reverse();
+                while (stack.length > 0) {
+                    const id = stack.pop();
+                    if (seen.has(id))
+                        continue;
+                    seen.add(id);
+                    ordered.push(id);
+                    const kids = kidsOf.get(id);
+                    if (kids !== undefined) {
+                        for (let i = kids.length - 1; i >= 0; i--)
+                            stack.push(kids[i]);
+                    }
+                }
+                // Cycle-broken leftovers (corrupt parent headers) — never drop one.
+                for (const id of [...family].sort(priorityOf)) {
+                    if (!seen.has(id))
+                        ordered.push(id);
+                }
+            }
+            // Caps: the ancestor chain + live session ALWAYS stay selected — the
+            // structural invariant (the live branch must reach the family root)
+            // outranks the session cap, which therefore evicts only non-ancestors.
+            // The event budget bounds the READ cost too: non-live logs decode
+            // lazily and stop at the remaining budget (see below), the live
+            // session keeps only its tail.
+            const MAX_TREE_SESSIONS = 24;
+            const MAX_TREE_EVENTS = 200_000;
+            // The event budget alone does NOT bound read cost: skipped envelopes
+            // (ignorable frames, headers) are paid for but never collected, so a
+            // noisy log can return ZERO events and leave the next log a full scan
+            // allowance — 23 logs × ~800k envelopes would block the TUI for
+            // seconds. scanBudget caps the TOTAL envelopes inspected across all
+            // logs (the reader reports its real scanned count); per-log caps
+            // derive from the event budget as before, and the smaller of the two
+            // applies, so one flood cannot starve every later sibling either.
+            const MAX_TREE_SCANNED = defaultMaxScanned(MAX_TREE_EVENTS);
+            let scanBudget = MAX_TREE_SCANNED;
+            const selected = new Set();
+            let slots = MAX_TREE_SESSIONS;
+            for (const id of ordered) {
+                const chain = id === currentId || ancestorSet.has(id);
+                if (chain || slots > 0) {
+                    selected.add(id);
+                    if (!chain)
+                        slots -= 1;
+                }
+            }
+            // The live session's events come from memory (its header may not be
+            // materialized yet — the jsonl backend writes on first append).
+            const liveHeader = headerById.get(currentId);
+            const familySessions = [];
+            let truncated = selected.size < family.size;
+            let eventBudget = 0;
+            // Coverage bookkeeping: coveredThrough(S) = the highest K such that
+            // [0..K] is already displayed by S's chain or an ancestor's. A fork's
+            // inherited seed prefix duplicates that range, so non-live reads SKIP
+            // it (the reader's skipBelowSeq): the prefix still costs scan budget
+            // (its bytes are read and parsed) but NOT the event budget — a fork
+            // of a huge parent pays only for its OWN events, so two small forks
+            // of a 70k-event parent both stay visible. Unreadable/unloaded
+            // sessions are transparent: they claim nothing beyond what their own
+            // ancestors covered, so a fork of a dead branch dedups against the
+            // grandparent instead of hiding its self-contained history.
+            const coveredThrough = new Map();
+            for (const id of ordered) {
+                if (!selected.has(id))
+                    continue;
+                const entry = headerById.get(id);
+                if (id === currentId) {
+                    const liveParentId = liveHeader?.header.parentSession ?? liveMeta?.parentSession;
+                    const liveParent = liveParentId !== undefined ? String(liveParentId) : undefined;
+                    const parentCovered = liveParent !== undefined
+                        ? (coveredThrough.get(liveParent) ?? -1)
+                        : -1;
+                    const liveEvents = liveSession.events;
+                    const remaining = Math.max(0, MAX_TREE_EVENTS - eventBudget);
+                    // The live session's in-memory log is SELF-CONTAINED: a fork's
+                    // events still carry the inherited seed prefix, which the parent's
+                    // chain already displays (and already charged to the budget).
+                    // Skipping it exactly like the non-live reads do keeps a live fork
+                    // of a huge parent from spending the whole family budget on
+                    // duplicated history and evicting its own siblings.
+                    const liveSeed = liveHeader?.header.seedLength ?? liveMeta?.seedLength;
+                    const skipBelow = liveParent !== undefined && liveSeed !== undefined
+                        ? Math.min(liveSeed, parentCovered + 1)
+                        : 0;
+                    const own = skipBelow > 0 ? liveEvents.filter(event => event.seq >= skipBelow) : liveEvents;
+                    // A live session larger than the remaining budget keeps its TAIL,
+                    // aligned to whole turns (sessionTree.liveTailWindow): leftover
+                    // entries of a turn whose turn/start was cut away render as
+                    // selectable rows that can never rewind; a window holding no
+                    // turn/start at all (one oversized LAST turn spans the budget)
+                    // retries over the earlier complete turns instead of blacking the
+                    // session out. Rewind itself never reads this copy (rewindToNode
+                    // forks the real session), so the slice only narrows what the tree
+                    // can display.
+                    const events = liveTailWindow(own, remaining);
+                    // Charge the KEPT tail, not the in-memory length: extraction only
+                    // ever touches `events`, and charging the full log would black out
+                    // every other family member's budget behind a discarded prefix.
+                    eventBudget += events.length;
+                    if (events.length !== own.length)
+                        truncated = true;
+                    familySessions.push({
+                        id,
+                        createdAt: liveHeader?.header.createdAt ?? liveMeta?.createdAt ?? Date.now(),
+                        ...(liveParent !== undefined ? { parentSession: liveParent } : {}),
+                        ...(liveHeader?.header.seedLength !== undefined || liveMeta?.seedLength !== undefined
+                            ? { seedLength: liveHeader?.header.seedLength ?? liveMeta.seedLength }
+                            : {}),
+                        events,
+                        live: true,
+                        // The in-memory log always reaches the tip (liveTailWindow trims
+                        // the head only), so the adopt/warning UX facts are derivable.
+                        tailComplete: true,
+                    });
+                    // A kept tail cut off the front connects to nothing — coverage
+                    // stays at the parent's (a fork of the live session re-reads the
+                    // hidden prefix from its own log).
+                    const firstKept = events.length > 0 ? events[0].seq : Number.POSITIVE_INFINITY;
+                    const lastKept = events.length > 0 ? events[events.length - 1].seq : -1;
+                    coveredThrough.set(id, firstKept <= parentCovered + 1 ? Math.max(parentCovered, lastKept) : parentCovered);
+                    continue;
+                }
+                const header = entry?.header;
+                const parentId = header?.parentSession;
+                const parentCovered = parentId !== undefined ? (coveredThrough.get(parentId) ?? -1) : -1;
+                // Never skip past the seed prefix: events beyond it are this
+                // session's OWN — no ancestor can show them. A parent that was never
+                // read (evicted, or outside the family) covers nothing (skip 0).
+                const skipBelow = parentId !== undefined && header?.seedLength !== undefined
+                    ? Math.min(header.seedLength, parentCovered + 1)
+                    : 0;
+                const facts = {
+                    id,
+                    createdAt: header?.createdAt ?? 0,
+                    ...(parentId !== undefined ? { parentSession: parentId } : {}),
+                    ...(header?.seedLength !== undefined ? { seedLength: header.seedLength } : {}),
+                };
+                if (eventBudget >= MAX_TREE_EVENTS || scanBudget <= 0) {
+                    // Budget spent: keep the STRUCTURE — the session degrades to an
+                    // unloaded placeholder so its branch (and any ancestor chain
+                    // through it) stays visible instead of vanishing from the tree.
+                    truncated = true;
+                    familySessions.push({ ...facts, events: [], live: false, unloaded: true });
+                    coveredThrough.set(id, parentCovered);
+                    continue;
+                }
+                // Read-only, tolerant, bounded: the compat reader decodes frames
+                // lazily and stops at the remaining event budget. Browsing the tree
+                // must never REWRITE history logs (the ignorable-marking repair
+                // stays on the explicit resume/rewind path), and the strict backend
+                // inspect would both reject third-party event types wholesale and
+                // parse chunk-heavy logs whole. Header facts come from list().
+                const remaining = MAX_TREE_EVENTS - eventBudget;
+                // Source precedence, all read-only:
+                //  1. persistence.locate — the backend's OWN artifact resolution is
+                //     authoritative (custom root, workspace-key scheme). When it
+                //     names a path, ONLY that file is read: falling back to a
+                //     same-id copy under the stock root could surface a STALE log
+                //     from another backend configuration. A locate miss or an ABSENT
+                //     file falls through to inspect, never to the stock scan.
+                //  2. Stock root scan — only for backends WITHOUT locate (fakes,
+                //     older custom implementations).
+                //  3. inspect — the backend's strict read (non-file backends), with
+                //     the same budget enforced on what we keep — and ONLY when the
+                //     file read found NOTHING (undefined). A read that failed on a
+                //     safety cap or corruption (failed) must never escalate here:
+                //     inspect parses the WHOLE log up front, so falling through
+                //     would re-read unboundedly exactly the logs the caps exist to
+                //     bound (64 MiB frames, decode bombs) — degrade to a placeholder
+                //     instead.
+                let events;
+                let complete = true;
+                let failed = false;
+                // First seq the chosen source actually covers: the file readers start
+                // at the inherited-prefix skip, inspect always hands the whole log.
+                let readFrom = 0;
+                // Per-log scan allowance: the usual 4×-of-remaining derivation,
+                // clamped to what the tree-level scan budget still has.
+                const scanAllowance = Math.min(defaultMaxScanned(remaining), scanBudget);
+                const locate = persistence.locate;
+                const hasLocate = typeof locate === 'function';
+                if (hasLocate && entry !== undefined) {
+                    let locatedPath;
+                    try {
+                        const location = locate.call(persistence, entry.raw);
+                        // Only the jsonl kind enters the compat file layer — a foreign
+                        // kind's artifact is the backend's own format (inspect below).
+                        if (location !== null && typeof location === 'object') {
+                            const record = location;
+                            if (record.kind === 'jsonl' && typeof record.path === 'string') {
+                                locatedPath = record.path;
+                            }
+                        }
+                    }
+                    catch {
+                        // Best effort — a locate hiccup falls through to inspect.
+                    }
+                    if (locatedPath !== undefined) {
+                        const viaPath = readSessionEventsFromFile(locatedPath, remaining, scanAllowance, skipBelow);
+                        if (viaPath !== undefined) {
+                            scanBudget -= viaPath.scanned;
+                            if (viaPath.failed === true)
+                                failed = true;
+                            else {
+                                events = viaPath.events;
+                                complete = viaPath.complete;
+                                readFrom = skipBelow;
+                            }
+                        }
+                    }
+                }
+                else if (!hasLocate) {
+                    const read = readSessionEventsFromLog(id, remaining, scanAllowance, skipBelow);
+                    if (read !== undefined) {
+                        scanBudget -= read.scanned;
+                        if (read.failed === true)
+                            failed = true;
+                        else {
+                            events = read.events;
+                            complete = read.complete;
+                            readFrom = skipBelow;
+                        }
+                    }
+                }
+                if (!failed && events === undefined && typeof persistence.inspect === 'function') {
+                    try {
+                        const inspection = await persistence.inspect(SessionId(id));
+                        // inspect parses the WHOLE log up front: charge the full length
+                        // to the scan budget (may overdraw; the next iterations skip).
+                        scanBudget -= inspection.events.length;
+                        // Non-file backends hand back the self-contained log from seq 0:
+                        // the inherited-prefix skip the file readers got must apply here
+                        // too, or a long prefix would fill the slice and the branch's OWN
+                        // events — the only ones nobody else displays — would be cut.
+                        const all = skipBelow > 0 ? inspection.events.filter(event => event.seq >= skipBelow) : inspection.events;
+                        readFrom = skipBelow;
+                        events = all;
+                        if (events.length > remaining) {
+                            events = events.slice(0, remaining);
+                            complete = false;
+                        }
+                    }
+                    catch {
+                        events = undefined;
+                    }
+                }
+                if (failed || events === undefined) {
+                    // An unreadable log keeps the branch structure, no entries — and
+                    // stays transparent for coverage, so a fork of this branch dedups
+                    // against the grandparent instead of hiding its own history.
+                    familySessions.push({ ...facts, events: [], live: false, unreadable: true });
+                    coveredThrough.set(id, parentCovered);
+                    continue;
+                }
+                eventBudget += events.length;
+                if (!complete)
+                    truncated = true;
+                // tailComplete gates the branch-adopt target and the drop-turn
+                // warning: a budget-sliced read lost the tail, and a tip computed
+                // from it would fork mid-branch while claiming to keep everything.
+                familySessions.push({ ...facts, events, live: false, ...(complete ? { tailComplete: true } : {}) });
+                const lastRead = events.length > 0 ? events[events.length - 1].seq : -1;
+                coveredThrough.set(id, readFrom <= parentCovered + 1 ? Math.max(parentCovered, lastRead) : parentCovered);
+            }
+            // A session swap mid-build invalidates the whole assembly (it mixes
+            // the snapshot's lineage with headers listed for the OLD cwd state):
+            // drop it silently — the reopened tree rebuilds on the new session.
+            if (agent.session !== liveSession)
+                return null;
+            return buildSessionTree(familySessions, currentId, truncated);
+        },
+        async rewindToNode(sessionId, seq, mode = 'rewind') {
+            const agents = ctx.get('agents');
+            if (!agents) {
+                state.notify(t('rewind-unavailable'), { color: 'error' });
+                return null;
+            }
+            // Pin the entry-time session: the awaits below (log load, preset
+            // compose, agent create) are windows in which a queued switch
+            // (/new, /resume, /model) can swap `agent` — the mutation queue only
+            // serializes the REPLACING entries, so the boundary and restored text
+            // derive from THIS session's log and any swap along the way aborts
+            // the rewind (forking or disposing whatever agent happens to be
+            // current at the end would rewind the wrong session).
+            const entrySession = agent.session;
+            const currentId = String(entrySession.id);
+            const childId = SessionId(randomUUID());
+            // Source events: the live session from memory; any other family member
+            // from its durable log (legacy event types registered first — the same
+            // in-process compat seam as resumeTo, since load validates known types).
+            let sourceEvents;
+            let sourceCwd = state.cwd;
+            let forkFromLive = true;
+            if (sessionId === currentId) {
+                sourceEvents = entrySession.events;
+            }
+            else {
+                forkFromLive = false;
+                const persistence = ctx.get('sessionPersistence');
+                if (!persistence || typeof persistence.load !== 'function') {
+                    state.notify(t('rewind-no-persistence'), { color: 'error' });
+                    return null;
+                }
+                try {
+                    ensureLegacySessionEventTypes();
+                    const loaded = await persistence.load(SessionId(sessionId));
+                    sourceEvents = loaded.events;
+                    sourceCwd = loaded.meta.cwd ?? state.cwd;
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    state.notify(t('rewind-load-failed', { err: message }), { color: 'error' });
+                    return null;
+                }
+            }
+            // DSH event order is `turn/start → user/message → … → turn/end`, and a
+            // fork seed must not end inside an open turn. pi's navigateTree
+            // semantics mapped onto that constraint (sessionTree.rewindTarget): a
+            // USER message drops its turn — the boundary sits just before the
+            // turn/start and the prompt comes back into the input for re-editing;
+            // any OTHER entry keeps through its enclosing STEP — a mid-turn cut at
+            // the step/end with the turn closed synthetically (DSH agentic turns
+            // span thousands of events, so turn-granular keeping would barely move
+            // the visible history). Fork mode (pi's /fork) instead KEEPS the
+            // picked entry: a user message cuts right after itself (the turn's
+            // reply drops) and never returns text to the input.
+            const target = mode === 'fork'
+                ? forkTarget(sourceEvents, seq)
+                : rewindTarget(sourceEvents, seq);
+            const boundary = target.boundary;
+            if (boundary < 0) {
+                state.notify(t('rewind-first-message'), { color: 'error' });
+                return null;
+            }
+            // Keeping the entry can still be a NO-OP: when nothing message-bearing
+            // follows the boundary (only a turn/end, or nothing at all), the fork's
+            // transcript would be identical to the live one. pi truncates to right
+            // after the entry; DSH's step/turn-closed seed cannot always express
+            // that, so the honest answer is to say there is nothing to rewind. A
+            // DEAD session's tip still forks: that adopts the branch, a real
+            // switch.
+            if (forkFromLive && !sourceEvents.some(event => event.seq > boundary &&
+                (event.type === 'user/message' || event.type === 'assistant/message' ||
+                    event.type === 'tool/call' || event.type === 'tool/result'))) {
+                state.notify(t('rewind-noop'), { color: 'warning' });
+                return null;
+            }
+            // The dropped turn's own prompt text, restored into the input after
+            // the swap ('' whenever the entry was kept — fork mode included — or
+            // the turn had no human-typed text to restore).
+            const restoredText = mode === 'fork' ? '' : turnUserText(sourceEvents, seq);
+            // The fork continues under the source session's own preset: switches
+            // are blank-only, so every `agent-preset/selected` event predates any
+            // rewind boundary and the source log resolves the exact composition.
+            // The route likewise stays the live one — a rewind continues the same
+            // conversation, so a `/model` switch must survive it (issue #30).
+            const sourcePreset = forkFromLive
+                ? runningPresetOf(entrySession)
+                : ((await resolvePersistedPreset(ctx, SessionId(sessionId))) ?? runningPresetOf(entrySession));
+            const rewindComposed = await composePreset(ctx, sourcePreset);
+            // Everything fallible is done — only NOW stop a running turn (a load
+            // or preset failure above must not kill it). But bail first when the
+            // live session was swapped during those awaits: cancelling/forking
+            // now would hit the NEW session with THIS session's boundary.
+            if (agent.session !== entrySession) {
+                state.notify(t('rewind-session-changed'), { color: 'error' });
+                return null;
+            }
+            // Stop a running turn first and WAIT for its turn/end to land: fork
+            // rejects boundaries inside open turns, and Agent.cancel() closes the
+            // turn asynchronously (a long thinking turn can take seconds to
+            // settle). Cross-session rewinds need this too: the live agent is
+            // about to be disposed, and its turn must close cleanly.
+            const wasWorking = state.working;
+            const cancelSeq = agent.session.seq;
+            if (wasWorking)
+                agent.cancel({ kind: 'user' });
+            if (wasWorking) {
+                const turnSettled = await waitForTurnEnd(agent.session, cancelSeq, 30000);
+                if (!turnSettled) {
+                    state.notify(t('rewind-settling'), { color: 'error' });
+                    return null;
+                }
+            }
+            // Slice the seed from the PINNED event snapshot. Never sessions.fork
+            // here: fork() rejects a boundary inside an open turn, which is
+            // exactly where a keep-style cut lands (closeTurn set) — close it
+            // with the exact event a real user interrupt writes instead (the
+            // persistence layer closes crash-orphaned turns the same way).
+            // agents.create validates the result itself (contiguous from seq 0,
+            // no open turns).
+            const seed = sourceEvents.filter(event => event.seq <= boundary);
+            if (target.closeTurn !== undefined) {
+                const last = seed[seed.length - 1];
+                if (last !== undefined) {
+                    seed.push({
+                        type: 'turn/end',
+                        seq: last.seq + 1,
+                        time: last.time + 1,
+                        data: { turn: target.closeTurn, reason: { kind: 'aborted', reason: { kind: 'user' } } },
+                    });
+                }
+            }
+            let handle;
+            try {
+                handle = await agents.create({
+                    sessionId: childId,
+                    seed,
+                    meta: {
+                        cwd: sourceCwd,
+                        parentSession: SessionId(sessionId),
+                        seedLength: seed.length,
+                        ...(rewindComposed.agentPreset === undefined
+                            ? {}
+                            : { agentPreset: rewindComposed.agentPreset }),
+                    },
+                    agentOptions: { provider: state.provider, model: state.model },
+                    ...(rewindComposed.setup === undefined ? {} : { setup: rewindComposed.setup }),
+                });
+            }
+            catch {
+                state.notify(t('rewind-create-failed'), { color: 'error' });
+                return null;
+            }
+            try {
+                await attachSessionToWorkspace(ctx, sourceCwd, childId);
+            }
+            catch (error) {
+                state.notify(t('rewind-attach-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'warning', timeoutMs: 8000 });
+            }
+            // The create await was another swap window: adopting now would dispose
+            // the NEW session's agent. Free the fork we just made and bail.
+            if (agent.session !== entrySession) {
+                void handle.dispose().catch(() => { });
+                state.notify(t('rewind-session-changed'), { color: 'error' });
+                return null;
+            }
+            // Replay the forked history into a fresh transcript (the same swap
+            // tail rewindTo runs), then announce the session switch.
+            const sourceSessionId = adoptForkedAgent(handle, seed, rewindComposed.agentPreset, childId);
+            notifySessionSwitched(mode === 'fork' ? 'fork' : 'rewind', String(childId), sourceSessionId);
+            return restoredText;
+        },
+        async forkSession() {
+            const sessions = ctx.get('sessions');
+            const agents = ctx.get('agents');
+            if (!sessions || !agents) {
+                state.notify(t('fork-unavailable'), { color: 'error' });
+                return false;
+            }
+            // kimi-code /fork semantics: refuse mid-turn instead of cancelling —
+            // the fork must not surprise the user by killing their running turn,
+            // and sessions.fork rejects an open-turn log anyway.
+            if (state.working) {
+                state.notify(t('fork-while-working'), { color: 'warning' });
+                return false;
+            }
+            const source = agent.session;
+            const childId = SessionId(randomUUID());
+            // No boundary: the whole (turn-closed) log. Slice via sessions.fork for
+            // the same validation the rewind path gets, never sessions.fork's
+            // session-storing sibling — agents.create must own the new session.
+            let seed;
+            try {
+                seed = sessions.fork(source).events;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                state.notify(t('fork-failed', { err: message }), { color: 'error' });
+                return false;
+            }
+            // Same preset/route rule as a rewind fork: the source log's own
+            // composition, the live route (a /model switch survives forking).
+            const forkComposed = await composePreset(ctx, runningPresetOf(source));
+            let handle;
+            try {
+                handle = await agents.create({
+                    sessionId: childId,
+                    seed,
+                    meta: {
+                        cwd: state.cwd,
+                        // NO parentSession: a /fork copy is an independent conversation
+                        // (kimi-code semantics — a copy of the message list under a new
+                        // root session, like /new plus the history), not a rewind branch.
+                        // Recording lineage would fold it into the source's family in
+                        // /resume and the user would never find it.
+                        seedLength: seed.length,
+                        ...(forkComposed.agentPreset === undefined
+                            ? {}
+                            : { agentPreset: forkComposed.agentPreset }),
+                    },
+                    agentOptions: { provider: state.provider, model: state.model },
+                    ...(forkComposed.setup === undefined ? {} : { setup: forkComposed.setup }),
+                });
+            }
+            catch {
+                state.notify(t('fork-create-failed'), { color: 'error' });
+                return false;
+            }
+            // STAY in the source session: adopting the fork would dispose the live
+            // agent (killing its in-flight turn and background tasks) — the fork is
+            // an independent copy the user enters via /resume or the printed resume
+            // command. The teardown order matters:
+            // 1. attach while the fork's agent is still LIVE — the workspace's
+            //    header read resolves live sessions from the registry, so attaching
+            //    after dispose races the persistence index and can fail with
+            //    "cannot validate session".
+            // 2. await the dispose so the seed log finishes flushing…
+            // 3. …then append the Fork: title — appending mid-flush races the
+            //    writer and the frame is silently dropped.
+            try {
+                await attachSessionToWorkspace(ctx, state.cwd, childId);
+            }
+            catch (error) {
+                state.notify(t('fork-attach-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'warning', timeoutMs: 8000 });
+            }
+            try {
+                await handle.dispose();
+            }
+            catch (error) {
+                ctx.logger.warn('dsh-tui: forked session dispose failed: %o', error);
+            }
+            // kimi's naming convention: the fork wears `Fork: <source title>` (the
+            // prefix stays English in both locales). Best effort — a backend whose
+            // log the compat layer cannot reach just leaves the fork untitled.
+            const sourceTitle = state.sessionTitle.trim();
+            appendSessionTitle(String(childId), `Fork: ${sourceTitle === '' ? String(source.id).slice(0, 8) : sourceTitle}`);
+            // The same resume-command shape the exit hint prints (plugin.ts
+            // resumeCommand): DSH_TUI_RESUME_SESSION + the boot profile.
+            const profile = resolveDshProfileName();
+            const boot = profile === undefined ? 'dsh --config cordis.yml' : `dsh --profile ${profile}`;
+            const command = process.platform === 'win32'
+                ? `dsh-tui --resume ${childId}`
+                : `DSH_TUI_RESUME_SESSION=${childId} ${boot}`;
+            state.notify(t('fork-done', { id: String(childId), command }), { timeoutMs: 8000 });
+            return true;
+        },
         async resumeTo(sessionId) {
             // Switch the live agent to a persisted session: /resume picker Enter
             // loads the history immediately (the `--resume` launcher path keeps
@@ -1647,10 +2639,20 @@ export function createChannel(ctx, initialAgent, options) {
                 provider: options.configuredProvider,
                 model: options.configuredModel,
             });
+            // The recorded route feeds back into agentOptions too — not just the
+            // status line below: a provider-only cordis.yml pin (issue #67) leaves
+            // agentOptions.model undefined on resume, which breaks the `{{model}}`
+            // persona variable for the resumed agent's own assembly AND for every
+            // subagent it spawns (dsh-subagent's resolveChildAgentOptions inherits
+            // `parent.options.model`).
+            const recordedRoute = await resolvePersistedRoute(ctx, SessionId(sessionId));
             try {
                 handle = await agents.resume({
                     resumeSessionId: SessionId(sessionId),
-                    agentOptions: { provider: resumeRoute?.provider, model: resumeRoute?.model },
+                    agentOptions: {
+                        provider: resumeRoute?.provider ?? recordedRoute?.provider,
+                        model: resumeRoute?.model ?? recordedRoute?.model,
+                    },
                     ...(resumeComposed.setup === undefined ? {} : { setup: resumeComposed.setup }),
                 });
             }
@@ -1689,6 +2691,7 @@ export function createChannel(ctx, initialAgent, options) {
             state.pending = [];
             state.goal = undefined;
             state.sessionTitle = '';
+            state.sessionColor = '';
             state.tokens = { input: 0, output: 0 };
             state.responseChars = 0;
             state.activeToolCount = 0;
@@ -1856,6 +2859,7 @@ export function createChannel(ctx, initialAgent, options) {
             state.pending = [];
             state.goal = undefined;
             state.sessionTitle = '';
+            state.sessionColor = '';
             state.tokens = { input: 0, output: 0 };
             state.responseChars = 0;
             state.activeToolCount = 0;
@@ -2039,6 +3043,7 @@ export function createChannel(ctx, initialAgent, options) {
             state.pending = [];
             state.goal = undefined;
             state.sessionTitle = '';
+            state.sessionColor = '';
             state.tokens = { input: 0, output: 0 };
             state.responseChars = 0;
             state.activeToolCount = 0;
@@ -2050,6 +3055,11 @@ export function createChannel(ctx, initialAgent, options) {
             state.agentPreset = modelComposed.agentPreset;
             state.model = model;
             state.provider = provider;
+            // /model completion cache: the [current] tag was resolved at fetch
+            // time — drop the cache so the next `/model ` refetches for the new
+            // route.
+            modelNodeCache.nodes = undefined;
+            modelNodeCache.load = undefined;
             state.tps = undefined;
             state.tpsSamples = [];
             state.lastUsage = undefined;
@@ -2160,6 +3170,19 @@ export function createChannel(ctx, initialAgent, options) {
             state.toolBackground = normalized;
             state.emit();
         },
+        setScrollGutter(mode) {
+            const normalized = normalizeScrollGutter(mode);
+            if (normalized === state.scrollGutter)
+                return;
+            state.scrollGutter = normalized;
+            state.emit();
+        },
+        setPromptSessionLabel(enabled) {
+            if (enabled === state.promptSessionLabel)
+                return;
+            state.promptSessionLabel = enabled;
+            state.emit();
+        },
         setStatusBar(config) {
             const next = normalizeStatusBar({ ...state.statusBar, ...config });
             const changed = Object.keys(next).some(key => next[key] !== state.statusBar[key]);
@@ -2290,6 +3313,12 @@ export function createChannel(ctx, initialAgent, options) {
             return Promise.all(providers.map(provider => llm.listModels(provider.id).catch(() => [])))
                 .then(lists => lists.flat());
         },
+        listProviders() {
+            // Group labels for the two-level /model picker: the registry's own
+            // display names, detached so a registry swap cannot leak through.
+            const llm = ctx.get('llm');
+            return Promise.resolve(llm === undefined ? [] : llm.listProviders().map(info => ({ ...info })));
+        },
         async listSkills() {
             // snapshot() over list(): only a COMPLETE observation is authoritative
             // (same contract as the skill-command merge above) — a partial catalog
@@ -2386,7 +3415,12 @@ export function createChannel(ctx, initialAgent, options) {
                 return undefined;
             }
             const revision = () => settings.describe().find(descriptor => descriptor.ns === 'llm-pi-ai')?.revision;
+            // The OAuth sign-in surface (dsh-auth-style plugin), structural and
+            // optional: mounting the plugin lights up the wizard's OAuth branch,
+            // and without it the wizard is exactly what it was before.
+            const oauthApi = ctx.get('dshAuth')?.api;
             return {
+                ...(oauthApi === undefined ? {} : { oauth: oauthApi }),
                 listCatalogProviders() {
                     // declared === true marks routes the adapter knows only because a
                     // stored profile names them (user-added); the rest are activatable
@@ -2432,6 +3466,12 @@ export function createChannel(ctx, initialAgent, options) {
                 },
             };
         },
+        async oauthProviderStatuses() {
+            // Same optional seam the wizard's OAuth branch reads: absent plugin →
+            // undefined, and `/login` renders exactly its pre-plugin lines.
+            const api = ctx.get('dshAuth')?.api;
+            return api === undefined ? undefined : api.providers();
+        },
         async sideQuestion(question, options) {
             // CC /btw：无工具单轮辅助调用，重放 deriveMessages() 前缀 + 一条
             // 包装问题。tools 永不传（侧问无工具是核心语义）；usage 不回收
@@ -2524,6 +3564,61 @@ export function createChannel(ctx, initialAgent, options) {
             state.sessionTitle = title;
             state.emit();
         },
+        setSessionColor(color) {
+            // `session/color` is a dsh-tui plugin event — not in dsh-session's
+            // typed union, so appended through the same cast applyMode uses for
+            // its sandbox/approval overrides. It replays on resume/rewind like
+            // session/title, keeping each session's accent color its own.
+            ;
+            agent.session
+                .append('session/color', { color });
+            state.sessionColor = color;
+            state.emit();
+        },
+        async recapRecent(options) {
+            // `/recap` (pi-recap semantics): one tool-less LLM call over the
+            // session's TAIL exchanges — unlike /btw it does not replay the full
+            // derived history (the excerpt IS the payload), so it stays cheap.
+            // The answer is pure UI state: never appended to the session log.
+            const llm = ctx.get('llm');
+            if (!llm)
+                return { summary: null, error: t('recap-llm-unavailable') };
+            const header = agent.session.requestHeader();
+            const config = header?.config;
+            const activity = collectRecentActivity(agent.session.events, RECAP_RECENT_CHARS);
+            if (activity === '')
+                return { summary: null, error: t('recap-no-activity') };
+            const messages = [
+                createUserMessage({
+                    content: [{ type: 'text', text: wrapRecapPrompt(activity) }],
+                    source: { kind: 'plugin', plugin: 'dsh-tui/recap' },
+                }),
+            ];
+            const request = {
+                provider: config?.provider ?? state.provider,
+                model: config?.model ?? state.model,
+                messages,
+                ...(header?.system !== undefined && { system: header.system }),
+                ...(config?.reasoningEffort !== undefined && { reasoningEffort: config.reasoningEffort }),
+                ...(config?.temperature !== undefined && { temperature: config.temperature }),
+                ...(config?.maxTokens !== undefined && { maxTokens: config.maxTokens }),
+                ...(config?.stop !== undefined && { stop: [...config.stop] }),
+                sessionId: agent.session.id,
+                ...(options?.signal && { signal: options.signal }),
+            };
+            const outcome = await runSideQuestion({
+                stream: llm.stream.bind(llm),
+                options: request,
+                onText: options?.onText,
+                signal: options?.signal,
+            });
+            if (outcome.answer === null)
+                return { summary: null, error: outcome.error };
+            const parsed = parseRecapResponse(outcome.answer);
+            return parsed.title === undefined
+                ? { summary: parsed.summary }
+                : { summary: parsed.summary, title: parsed.title };
+        },
         async deleteSession(sessionId) {
             // The live session's log is still being appended by this process —
             // deleting it from under the writer is never offered in the picker
@@ -2619,7 +3714,13 @@ export function createChannel(ctx, initialAgent, options) {
                     .catch((error) => {
                     state.notify(t('compact-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'error', timeoutMs: 8000 });
                 });
-            })();
+            })().catch((error) => {
+                // Sync throws from compactNow (e.g. runMaintenance rejecting a
+                // non-idle agent right after /resume) reject this IIFE itself;
+                // uncaught, that is an unhandled rejection and Node exits the
+                // whole TUI. Surface it as the same failure notification.
+                state.notify(t('compact-failed', { err: error instanceof Error ? error.message : String(error) }), { color: 'error', timeoutMs: 8000 });
+            });
         },
         runExternalCommand(name, rawInput) {
             return executeRegistryCommand(name, rawInput);
@@ -3341,6 +4442,12 @@ ${output}
      *  its result-time contextual diff back from here). */
     const presentResultView = (name, rawArgs, data) => {
         try {
+            // Harness goal/todo tools first: their raw JSON reads as noise in the
+            // transcript — fold recognizable shapes into a summary card before the
+            // registry gets a chance to (not) know them.
+            const local = harnessToolResultView(name, data);
+            if (local !== undefined)
+                return local;
             const tool = toolsRegistry?.get(name, agent);
             if (tool?.presentResult === undefined)
                 return undefined;
@@ -3473,9 +4580,21 @@ ${output}
             state.spinnerMode = 'requesting';
         }
     };
+    /** Fold one goal mutation into the channel's goal projection. */
+    const applyGoalChange = (change) => {
+        if (change.operation === 'clear') {
+            state.goal = undefined;
+        }
+        else if (change.goal !== undefined) {
+            state.goal = {
+                ...change.goal,
+                roundsStarted: change.roundsStarted ?? state.goal?.roundsStarted ?? 0,
+            };
+        }
+    };
     /**
      * Fold one goal-sourced message into the channel's goal projection.
-     * Round-zero goal messages carry the full durable snapshot (or a clear
+     * Round-zero goal messages may carry the full durable snapshot (or a clear
      * tombstone) in their source; positive-round messages are admitted
      * continuation prompts that only advance the rounds counter.
      */
@@ -3495,15 +4614,7 @@ ${output}
         // oxlint-disable-next-line typescript/no-unnecessary-condition -- durable replay data may not match the static type
         if (change === undefined || change.kind !== 'goal/change')
             return;
-        if (change.operation === 'clear') {
-            state.goal = undefined;
-        }
-        else if (change.goal !== undefined) {
-            state.goal = {
-                ...change.goal,
-                roundsStarted: change.roundsStarted ?? state.goal?.roundsStarted ?? 0,
-            };
-        }
+        applyGoalChange(change);
     };
     /** True while the durable transcript is being replayed (boot /resume /
      *  rewind / model-switch fork). The assistant/message reasoning-rebuild
@@ -3531,6 +4642,15 @@ ${output}
         }
     };
     const renderEvent = (event) => {
+        // Top-level `goal/change` events are how the goal service actually
+        // records durable goal mutations (create/edit/pause/resume/complete/
+        // block/clear) — confirmed in production logs. The pinned peer's
+        // SessionEvent union predates the type, so admit it structurally: the
+        // goal chip and panel stay dark without this fold.
+        if (event.type === 'goal/change') {
+            applyGoalChange(event.data);
+            return;
+        }
         switch (event.type) {
             case 'user/message': {
                 // Compaction checkpoint: `source = { kind: 'plugin', plugin:
@@ -3573,10 +4693,13 @@ ${output}
                     contextWarned = false;
                     break;
                 }
-                // Same-session goal domain: round-zero goal-sourced messages carry
-                // the durable goal snapshot (or clear tombstone) in their source.
-                // They are not transcript bubbles — they drive the goal panel's
-                // live projection (replayed on resume/rewind like every other event).
+                // Same-session goal domain: goal-sourced messages are the round
+                // driver's continuation prompts (positive rounds advance the
+                // counter); some hosts also inline the durable snapshot in a
+                // round-zero source. They are not transcript bubbles — they drive
+                // the goal panel's live projection (replayed on resume/rewind like
+                // every other event; the snapshot itself arrives as the top-level
+                // `goal/change` event admitted above).
                 if (event.data.source.kind === 'goal') {
                     applyGoalEvent(event);
                     break;
@@ -3976,6 +5099,13 @@ ${output}
                     nextRowId += 1;
                     break;
                 }
+                // `/color` accent (dsh-tui plugin event, replayed on resume/rewind
+                // like session/title): last write wins, '' clears to the default.
+                if (event.type === 'session/color') {
+                    const data = event.data;
+                    state.sessionColor = typeof data.color === 'string' ? data.color : '';
+                    break;
+                }
                 // Custom plugin events (tuiRenderers seam): a registered renderer
                 // maps the payload to text rows — title as a local row, body as
                 // preview-clipped local-output rows, same shape pushLocal uses.
@@ -4158,12 +5288,18 @@ ${output}
                 const subagentId = subagentStore.getSubagentIdBySession(session);
                 if (subagentId) {
                     subagentStore.onSessionEvent(subagentId, event);
-                    state.subagents = subagentStore.snapshot();
-                    syncSubagentRows();
-                    if (event.type === 'assistant/chunk')
+                    if (event.type === 'assistant/chunk') {
+                        // Token-rate path (100-300 events/s): the store append stays
+                        // synchronous (cheap); the expensive snapshot + row projection
+                        // defers to the frame-aligned flush inside emitStream's 16ms
+                        // timer, so it coalesces exactly like the main-agent stream.
+                        subagentStreamDirty = true;
                         state.emitStream();
-                    else
+                    }
+                    else {
+                        syncSubagentsNow();
                         state.emit();
+                    }
                     return;
                 }
                 // Otherwise handle main agent session
@@ -4226,8 +5362,7 @@ ${output}
                     catch {
                         // Session discovery is best-effort and must not break the parent turn.
                     }
-                    state.subagents = subagentStore.snapshot();
-                    syncSubagentRows();
+                    syncSubagentsNow();
                     state.emit();
                 });
                 const disposeEnd = ctx.on('subagent/end', (info) => {
@@ -4249,8 +5384,7 @@ ${output}
                         subagentStore.onCancelled(info.id, info.stopReason, output);
                     else
                         subagentStore.onFailed(info.id, info.stopReason || 'Unknown error');
-                    state.subagents = subagentStore.snapshot();
-                    syncSubagentRows();
+                    syncSubagentsNow();
                     state.emit();
                 });
                 return () => {
@@ -4519,6 +5653,20 @@ const MENTION_IMAGE_MEDIA_TYPES = {
 function mentionImageMediaType(path) {
     return MENTION_IMAGE_MEDIA_TYPES[extname(path).toLowerCase()];
 }
+/** Resolve+stat one candidate path; undefined when it throws OR stats
+ * absent — both are a miss for strip-first mention resolution (issue #359). */
+async function tryResolveMention(fs, absolute) {
+    try {
+        const target = await fs.resolve(absolute);
+        const info = await fs.stat(target);
+        if (info === undefined)
+            return undefined;
+        return { target, info };
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Expand a submitted text's `@` mentions (issue #15) into model-facing
  * attachment blocks: supported image files become durable image blocks,
@@ -4537,68 +5685,99 @@ export async function expandMentions(fs, cwd, text, attachments, stagedImages) {
     let imageBytes = 0;
     if (fs !== undefined) {
         for (const mention of mentions) {
+            const display = mention.literal ?? mention.path;
             const imageMediaType = mentionImageMediaType(mention.path);
             if (budget <= 0 && imageMediaType === undefined)
                 break;
             // Mentions resolve against the session cwd, same as the model-facing fs
-            // tools; absolute paths pass through untouched.
+            // tools; absolute paths pass through untouched. A `#L12-14` line suffix
+            // (issue #359) is stripped before resolution; when the stripped path
+            // misses, the typed literal (suffix intact) gets ONE fallback try so
+            // filenames genuinely containing `#L…` still resolve as whole files.
             const absolute = isAbsolute(mention.path) ? mention.path : join(cwd, mention.path);
-            let target;
-            let info;
-            try {
-                target = await fs.resolve(absolute);
-                info = await fs.stat(target);
-            }
-            catch {
-                missing.push(mention.path);
+            let resolved = await tryResolveMention(fs, absolute);
+            let literalFallback = false;
+            if (resolved === undefined && mention.literal !== undefined) {
+                const literalPath = isAbsolute(mention.literal) ? mention.literal : join(cwd, mention.literal);
+                resolved = await tryResolveMention(fs, literalPath);
+                literalFallback = resolved !== undefined;
+            }
+            if (resolved === undefined) {
+                missing.push(display);
                 continue;
             }
+            const { target, info } = resolved;
+            // On a literal-fallback hit the attached file IS the typed name — the
+            // model must see that path, not the suffix-stripped one.
+            const shownPath = literalFallback ? display : mention.path;
+            // …and judge image-ness by the typed extension in that case too.
+            const imageType = literalFallback && mention.literal !== undefined
+                ? mentionImageMediaType(mention.literal)
+                : imageMediaType;
             if (info?.type === 'file') {
-                if (imageMediaType !== undefined && attachments !== undefined && fs.readBytes !== undefined) {
+                if (imageType !== undefined && attachments !== undefined && fs.readBytes !== undefined) {
                     const limits = attachments.imageLimits;
-                    if (!limits.mediaTypes.includes(imageMediaType) || imageCount >= limits.maxImagesPerMessage) {
-                        missing.push(mention.path);
+                    if (!limits.mediaTypes.includes(imageType) || imageCount >= limits.maxImagesPerMessage) {
+                        missing.push(display);
                         continue;
                     }
                     try {
                         const data = await fs.readBytes(target, undefined, limits.maxImageBytes);
                         if (imageBytes + data.byteLength > limits.maxMessageImageBytes) {
-                            missing.push(mention.path);
+                            missing.push(display);
                             continue;
                         }
                         const attachment = await attachments.saveImage({
                             data,
-                            mediaType: imageMediaType,
+                            mediaType: imageType,
                             name: basename(target.displayPath),
                         });
                         blocks.push({ type: 'image', attachment });
                         imageCount += 1;
                         imageBytes += data.byteLength;
-                        attached.push(mention.path);
+                        attached.push(display);
                     }
                     catch {
-                        missing.push(mention.path);
+                        missing.push(display);
                     }
                     continue;
                 }
                 try {
                     const cap = Math.min(MENTION_MAX_FILE_CHARS, budget);
-                    let content = await fs.readText(target);
+                    const content = await fs.readText(target);
+                    let body = content;
                     let truncated = false;
-                    if (content.length > cap) {
-                        content = content.slice(0, cap);
+                    let header = `<attached-file path="${shownPath}">`;
+                    if (mention.startLine !== undefined && !literalFallback) {
+                        // Line-range slice (issue #359): 1-based inclusive. An endLine
+                        // past EOF clamps to the file; a startLine past EOF falls back
+                        // to the whole file with an in-band note — never a silent
+                        // empty attach. Line ranges never apply to literal-fallback
+                        // hits (those files really are named `…#L…`, no suffix typed).
+                        const lines = content.split('\n');
+                        if (mention.startLine > lines.length) {
+                            header = `<attached-file path="${shownPath}" lines="${mention.startLine}-${mention.endLine}" note="requested lines beyond EOF (file has ${lines.length} line${lines.length === 1 ? '' : 's'}); whole file attached">`;
+                        }
+                        else {
+                            const endLine = Math.min(mention.endLine ?? mention.startLine, lines.length);
+                            header = `<attached-file path="${shownPath}" lines="${mention.startLine}${endLine === mention.startLine ? '' : `-${endLine}`}">`;
+                            body = lines.slice(mention.startLine - 1, endLine).join('\n');
+                        }
+                    }
+                    if (body.length > cap) {
+                        body = body.slice(0, cap);
                         truncated = true;
                     }
-                    budget -= content.length;
+                    budget -= body.length;
                     blocks.push({
                         type: 'text',
-                        text: `<attached-file path="${mention.path}">\n${content}${truncated ? '\n[… truncated]' : ''}\n</attached-file>`,
+                        text: `${header}\n${body}${truncated ? '\n[… truncated]' : ''}\n</attached-file>`,
                     });
-                    attached.push(mention.path);
+                    attached.push(display);
                 }
                 catch {
                     // Binary/undecodable or unreadable — report it like a miss.
-                    missing.push(mention.path);
+                    missing.push(display);
                 }
                 continue;
             }
@@ -4615,17 +5794,17 @@ export async function expandMentions(fs, cwd, text, attachments, stagedImages) {
                     budget -= body.length;
                     blocks.push({
                         type: 'text',
-                        text: `<attached-directory path="${mention.path}">\n${body}\n</attached-directory>`,
+                        text: `<attached-directory path="${shownPath}">\n${body}\n</attached-directory>`,
                     });
-                    attached.push(mention.path);
+                    attached.push(display);
                 }
                 catch {
-                    missing.push(mention.path);
+                    missing.push(display);
                 }
                 continue;
             }
             // Absent (stat → undefined) or a special file.
-            missing.push(mention.path);
+            missing.push(display);
         }
     }
     if (attachments !== undefined && stagedImages !== undefined) {