@deepseek-harness-tui/dsh-tui 0.13.0 → 0.14.0

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

@@ -4,21 +4,26 @@ import { SessionId } from '@deepseek-ai/dsh-session';
 import UserQuestionService from '@deepseek-ai/dsh-user-questions';
 import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user';
 import Schema from '@deepseek-ai/schemastery';
-import { Config } from './index.js';
+import { Config, normalizeBackendChoice } from './index.js';
 import { configValues, createSettingsScope, resolveSettingsNamespace } from './compat/settings.js';
 import { createChannel } from './channel.js';
+import { createDshSession } from './backend/session.js';
+import { BACKEND_LOADERS, closeBackendResources, openBackendStartup, probeKernels, sdkInstall } from './backends.js';
+import { formatSessionRef } from '../agent/refs.js';
 import { createChannelSceneOutlet } from './channel-scene-outlet.js';
 import { mountChannelUi } from './channel-ui.js';
 import { bindChannelCommands } from './channel/commands.js';
 import { registerTuiChannel } from '../adapter/channel/host-registry.js';
 import { createChildStderrReporter, installChildStderrGuard } from './childStderr.js';
 import { removeClipboardImageDir } from '../utils/clipboard.js';
+import { appendCrashLog, serializeCrashDetail, unserializableCrashDetail } from '../utils/crashDetail.js';
 import { logForDebugging } from '../utils/debug.js';
 import { isEnvTruthy } from '../utils/envUtils.js';
 import { QuestionStore, bindQuestionStore } from './questions.js';
 import { prepareQuestionAnswerer } from './questions-answerer.js';
 import { adapterRuntimeFor } from '../adapter/kernel/runtime-context.js';
 import { ApprovalStore, bindApprovalStore } from './approvals.js';
+import { PermissionStore } from '../channel/permissions.js';
 import { registerPromptDebug } from './promptDebug.js';
 import { readActivityFrames } from '../activityPrefs.js';
 import { commitFullscreenFactoryMigration, planFullscreenFactoryMigration, readAppliedMigrations } from '../migrationPrefs.js';
@@ -33,11 +38,14 @@ import { ensureLegacySessionEventTypes, snapshotLiveSessionEvents } from './comp
 import { clearResumeTarget, resumeTargetFromArgv, writeResumeTarget } from '../sessionHistory.js';
 import { initialPromptFromCmdlineArgs } from './startup-args.js';
 import { readHomePrefs } from '../homePrefs.js';
+import { handoffEventTag, formatHandoffNotice } from '../handoffEvents.js';
+import { armFirstFrameAck, beginHandoffAck, handoffAttemptId, ownsAltScreenExit } from '../handoffAck.js';
+import { KERNEL_IDS, KERNEL_SWITCH_HANDOFF_ENV, kernelDisplayName, readKernelPrefs, resolveRememberedBackend, writeKernelPrefs } from '../kernelPrefs.js';
 import { shouldOfferOnboarding } from '../onboardingPrefs.js';
 import { resolveSessionCwd } from '../utils/workspaceRoot.js';
-import { beginRestartAttempt, checkForTuiUpdate, installedTuiVersion, isBootDeadlockTarget, isStandaloneRuntime, isVersionNewer, logRestartEvent, resolveDshProfileName, resolveTuiUpdateTarget, restartTui, updateTuiAndRestart, writeHandoffNotice } from '../update.js';
+import { beginRestartAttempt, checkForTuiUpdate, installedTuiVersion, isBootDeadlockTarget, isStandaloneRuntime, isVersionNewer, logRestartEvent, resolveDshProfileName, resolveTuiUpdateTarget, restartTui, updateTuiAndRestart, writeHandoffNotice, writeLastRunRecord } from '../update.js';
 import { getLang, isLang, resolveStartupLang, setLang, t, writeLangPref } from '../i18n.js';
-import { DEFAULT_PAGE_MARGIN, DEFAULT_SIDE_PANEL_IDS, DEFAULT_STATUS_BAR, SIDE_PANEL_ID_PATTERN, applyCompanionSkin, applyImageBacking, applyMathImageBacking, applyMathImageScale, applyMathRendering, applyMermaidDiagrams, applyPageMargin, applySidePanelOpen, applySidePanelPanels, applySidePanelRatio, applySidePanelSplitEnabled, isPageMarginMode, normalizeJobGroupFold, normalizePageMargin, normalizeScrollGutter, normalizeSidePanelPanels, normalizeStatusBar, normalizeToolBackground, parsePageMarginSpec, resolveMathRendering } from '../tuiDisplayPrefs.js';
+import { applyBtwContextBudget, applyBtwContextTurns, applyCodeFrameStyle, applyCompanionSkin, applyImageBacking, applyMathImageBacking, applyMathImageScale, applyMathRendering, applyMermaidDiagrams, applyPageMargin, applySidePanelOpen, applySidePanelPanels, applySidePanelRatio, applySidePanelSplitEnabled, BTW_CONTEXT_BUDGET_MAX, BTW_CONTEXT_BUDGET_MIN, BTW_CONTEXT_TURNS_MAX, BTW_CONTEXT_TURNS_MIN, DEFAULT_PAGE_MARGIN, DEFAULT_SIDE_PANEL_IDS, DEFAULT_STATUS_BAR, isPageMarginMode, normalizeJobGroupFold, normalizePageMargin, normalizeScrollGutter, normalizeSidePanelPanels, normalizeStatusBar, normalizeToolBackground, parsePageMarginSpec, resolveMathRendering, SIDE_PANEL_ID_PATTERN } from '../tuiDisplayPrefs.js';
 import { draftComboConflicts, effectiveComboString, parseComboDraft, setKeymapOverrides, SHORTCUT_ACTIONS, } from '../utils/keymap.js';
 import { attachHerdrIntegration } from '../herdr.js';
 import { logMouseDebug } from '../utils/debug.js';
@@ -59,6 +67,7 @@ import { compositionRoot, withHostRootCapability } from './host-access.js';
 import { render, ThemeProvider, AlternateScreen } from '../ui.js';
 import { PageMargin } from '../components/PageMargin.js';
 import { normalizeSplashFont } from '../components/splashFonts.js';
+import { normalizeBrandSetting, resolveBrand, setActiveBrand } from '../branding.js';
 import { SETTING_GROUPS, SHORTCUT_FIELD_META, settingField } from '../settings/definitions.js';
 import instances from '../ink/instances.js';
 import { cursorMove, DISABLE_KITTY_KEYBOARD, DISABLE_MODIFY_OTHER_KEYS, DISABLE_WIN32_INPUT_MODE } from '../ink/termio/csi.js';
@@ -419,43 +428,134 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
     const cmdline = ctx.cmdlineArgs;
     const cmdlineArgs = cmdline?.get?.() ?? cmdline?.args;
     const launchSessionId = config.sessionId ?? resumeTargetFromArgv(cmdlineArgs ?? process.argv.slice(2));
-    const { agent, handle, agentPreset, route: createdRoute } = await resolveAgent(ctx, launchSessionId, configuredRoute, startupRoute, meta, config.preset);
-    try {
-        // Opening a persisted TUI session is an explicit ownership action too.
-        // Older TUI versions only wrote the Session log, so attaching on every
-        // startup repairs those durable-but-ungrouped sessions idempotently.
-        //
-        // This is ALSO how a workspace enters the rail: `resolveByPath(cwd) ??
-        // create(cwd)` mints the durable record for the directory this terminal
-        // was launched in, so the session screen lists every directory a TUI has
-        // ever started in. The ledger is DSH's own workspace store, so the Web UI
-        // reads the same records. There is deliberately no rail-side "add a
-        // workspace" control any more: a terminal's launch directory is the whole
-        // registration story.
-        //
-        // A RESUMED session is accounted where its OWN header cwd lives, never
-        // where this terminal was launched. The launch directory can be an
-        // ANCESTOR of the resumed session's: launching in `~/projects` and
-        // resuming a session recorded in `~/projects/app` accounts the same
-        // session in both workspaces, and the next boot dies inside
-        // `validateStoredState` ("session ... is accounted by both workspace
-        // ..."), which leaves `workspaceRegistry` unactivated and the whole TUI
-        // pending forever. Ownership must therefore agree with the `cwd:` handed
-        // to `createChannel` below, which already prefers the persisted header.
-        // Fresh sessions record `meta.cwd` at creation, so the launch directory
-        // still registers through them.
-        const ownershipCwd = agent.session.header.cwd ?? meta.cwd;
-        const attached = await attachSessionToWorkspace(ctx, ownershipCwd, agent.session.id);
-        if (!attached) {
-            ctx.logger.warn(`dsh-tui: session "${agent.session.id}" has no workspace ownership because workspaceRegistry is not mounted`);
+    // The session's backend (Config `backend`, `dsh-tui --backend`). A non-DSH
+    // backend opens its own session here and skips everything DSH-specific
+    // below (preset composition, route validation, workspace ownership, the
+    // approval answerer); the DSH path is unchanged.
+    // The `backend` row reads DSH_TUI_BACKEND (`dsh-tui --backend`), but a
+    // launcher whose bundle patch predates that row (the issue #183 copy skew)
+    // never passes it — so the variable is also read here, below the config.
+    // Priority: an explicit Config row or env var always wins; then the
+    // launchpad kernel selector's memory (kernel.json — written only by the
+    // selector, never by boot); else dsh. An INVALID env value still means dsh
+    // (the warning below says exactly that), never the memory.
+    const rawBackend = process.env.DSH_TUI_BACKEND;
+    // A kernel switch (restartTui's backend option) and the launcher's crash
+    // retry set this so the boot lands on the chosen kernel even when a Config
+    // row pins the other one. Deleted right away so no child inherits it; an
+    // invalid value is ignored.
+    const handoffBackendRaw = process.env[KERNEL_SWITCH_HANDOFF_ENV];
+    if (handoffBackendRaw !== undefined)
+        delete process.env[KERNEL_SWITCH_HANDOFF_ENV];
+    const handoffBackend = normalizeBackendChoice(handoffBackendRaw);
+    // Fullscreen kernel switch: the old process spawned this one with an ACK
+    // pipe on fd 3 and the alternate screen still open (see handoffAck.ts).
+    const handoffAck = beginHandoffAck();
+    if (handoffAck !== undefined) {
+        logRestartEvent('handoff/boot: ack armed', { attemptId: handoffAttemptId() ?? '' });
+    }
+    const backendChoice = resolveRememberedBackend({
+        ...(handoffBackend === undefined ? {} : { handoff: handoffBackend }),
+        configured: config.backend,
+        envRaw: rawBackend,
+        memory: readKernelPrefs().backend,
+    });
+    if (rawBackend !== undefined && rawBackend.trim() !== '' && normalizeBackendChoice(rawBackend) === undefined) {
+        ctx.logger.warn(`dsh-tui: DSH_TUI_BACKEND="${rawBackend}" names no known backend (${KERNEL_IDS.join(', ')}); starting on dsh`);
+    }
+    /**
+     * Whether a Config row or DSH_TUI_BACKEND overrides the selector's
+     * remembered kernel. The selector then says so: a switch still restarts
+     * onto the chosen kernel, but the next plain launch follows the override.
+     */
+    const backendPinned = config.backend !== undefined
+        || (rawBackend !== undefined && rawBackend.trim() !== '');
+    // A remembered kernel whose backend cannot open (its SDK uninstalled, its
+    // session store unreadable, …) must not kill the boot: without an explicit
+    // flag or resume target the TUI falls back to DSH and says so — the wizard
+    // in /kernel is then one Enter away from installing what is missing.
+    // Explicit choices (flag/Config/handoff) and explicit resume targets keep
+    // the hard failure: silently swapping what the user named would be worse.
+    let backendStart;
+    let backendFallbackNotice;
+    if (backendChoice !== 'dsh') {
+        try {
+            backendStart = await openBackendStartup(ctx, await BACKEND_LOADERS[backendChoice](), {
+                cwd: sessionCwd,
+                stderr: line => {
+                    logForDebugging(`[${backendChoice}-stderr] ${line}`);
+                    stderrReporter.push(line);
+                },
+                ...(config.sessionId === undefined ? {} : { configuredSessionId: config.sessionId }),
+                argv: cmdlineArgs ?? process.argv.slice(2),
+            });
+        }
+        catch (error) {
+            if (backendPinned || handoffBackend !== undefined || launchSessionId !== undefined)
+                throw error;
+            const reason = error instanceof Error ? error.message : String(error);
+            logForDebugging(`dsh-tui: remembered backend "${backendChoice}" failed to open (${reason}); falling back to dsh`);
+            backendFallbackNotice = t('kernel-memory-fallback', { name: kernelDisplayName(backendChoice), reason });
         }
     }
-    catch (error) {
-        // The Session is already published and durable, matching Web's partial
-        // failure contract. Keep the TUI usable but make the missing ownership
-        // loud instead of silently leaving the conversation Ungrouped.
-        ctx.logger.warn(`dsh-tui: session "${agent.session.id}" workspace attachment failed: ${error instanceof Error ? error.message : String(error)}`);
+    // The backend session (and its child process) belongs to this fiber until the
+    // channel adopts it: a boot that throws before then disposes the fiber's
+    // effects, and this one stops the child instead of leaking it. Dispose is
+    // idempotent, so the channel's own release later is unaffected.
+    if (backendStart !== undefined) {
+        ctx.effect(() => () => {
+            void backendStart.session.dispose().catch((error) => {
+                logForDebugging(`dsh-tui: backend session dispose failed (${error instanceof Error ? error.message : String(error)})`);
+            });
+        }, 'dsh-tui backend startup session');
     }
+    // A non-DSH session's permission prompts park in the shared store the
+    // approval panel renders; its questions share the DSH questionnaire store.
+    // Teardown withdraws whatever is still parked.
+    const backendPermissions = backendStart === undefined ? undefined : new PermissionStore();
+    if (backendPermissions !== undefined)
+        ctx.effect(() => () => backendPermissions.settleAll());
+    const { agent, handle, agentPreset, route: createdRoute } = backendStart !== undefined
+        ? { agent: undefined, handle: undefined, agentPreset: undefined, route: undefined }
+        : await resolveAgent(ctx, launchSessionId, configuredRoute, startupRoute, meta, config.preset);
+    // Workspace ownership is a DSH session-store fact (skipped off DSH).
+    if (agent !== undefined)
+        try {
+            // Opening a persisted TUI session is an explicit ownership action too.
+            // Older TUI versions only wrote the Session log, so attaching on every
+            // startup repairs those durable-but-ungrouped sessions idempotently.
+            //
+            // This is ALSO how a workspace enters the rail: `resolveByPath(cwd) ??
+            // create(cwd)` mints the durable record for the directory this terminal
+            // was launched in, so the session screen lists every directory a TUI has
+            // ever started in. The ledger is DSH's own workspace store, so the Web UI
+            // reads the same records. There is deliberately no rail-side "add a
+            // workspace" control any more: a terminal's launch directory is the whole
+            // registration story.
+            //
+            // A RESUMED session is accounted where its OWN header cwd lives, never
+            // where this terminal was launched. The launch directory can be an
+            // ANCESTOR of the resumed session's: launching in `~/projects` and
+            // resuming a session recorded in `~/projects/app` accounts the same
+            // session in both workspaces, and the next boot dies inside
+            // `validateStoredState` ("session ... is accounted by both workspace
+            // ..."), which leaves `workspaceRegistry` unactivated and the whole TUI
+            // pending forever. Ownership must therefore agree with the `cwd:` handed
+            // to `createChannel` below, which already prefers the persisted header.
+            // Fresh sessions record `meta.cwd` at creation, so the launch directory
+            // still registers through them.
+            const ownershipCwd = agent.session.header.cwd ?? meta.cwd;
+            const attached = await attachSessionToWorkspace(ctx, ownershipCwd, agent.session.id);
+            if (!attached) {
+                ctx.logger.warn(`dsh-tui: session "${agent.session.id}" has no workspace ownership because workspaceRegistry is not mounted`);
+            }
+        }
+        catch (error) {
+            // The Session is already published and durable, matching Web's partial
+            // failure contract. Keep the TUI usable but make the missing ownership
+            // loud instead of silently leaving the conversation Ungrouped.
+            ctx.logger.warn(`dsh-tui: session "${agent.session.id}" workspace attachment failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
     // Status-line route: the exact route the agent runs with — on create the
     // validated startup resolution, on resume the route the target session's
     // own records carry (a complete cordis.yml pin wins over them).
@@ -476,18 +576,45 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
     // context-low warning. Created unconditionally (unlike the activity store,
     // there is no config gate: hiding the bar must not make the warning or the
     // footer read a stale sample). A composition without the meter leaves it
-    // empty and the channel falls back to the last-request sample.
+    // empty and the channel falls back to the last-request sample — as does a
+    // non-DSH session, whose id the DSH meter never projects.
     const contextOccupancyStore = createContextOccupancyStore(ctx);
-    const rawChannel = createChannel(ctx, agent, {
+    // The channel holds a backend session; this DSH one owns the resolved
+    // handle (disposed by the binding when a later adoption replaces it).
+    let startupSession;
+    if (backendStart !== undefined)
+        startupSession = backendStart.session;
+    else if (agent !== undefined)
+        startupSession = createDshSession(ctx, { agent, handle });
+    else
+        throw new Error('dsh-tui: no startup session was opened');
+    const rawChannel = createChannel(ctx, startupSession, {
         // The namespace this boot actually registered the settings section under
         // (the Config owner's Loader id; custom ids are supported). Chat and the
         // channel's own settings reads look the section up by it.
         settingsNs: tuiSettingsNs,
-        model: displayRoute.model,
+        // The backend reports its model with its first turn (`system/init`);
+        // until then the status line names the backend.
+        model: backendStart !== undefined ? backendStart.label : displayRoute.model,
+        ...(backendStart === undefined || backendPermissions === undefined ? {} : {
+            backendLabel: backendStart.label,
+            openSession: backendStart.open,
+            interaction: { permissions: backendPermissions, questions: questionStore },
+            // The session browser, /resume, /fork and rewind.
+            sessionCatalog: backendStart.catalog,
+            sessionPrefs: backendStart.sessionPrefs,
+            initialHistory: backendStart.initialHistory,
+            resumeCommand: backendStart.resumeCommand,
+        }),
         // The activity projection only pushes on change; read the current value as
         // soon as this session binds so a resumed or reattached session renders its
         // line immediately instead of waiting for the next event.
         seedActivity: session => activityStore.seed(session),
+        // A backend-provided working line lands
+        // in the SAME store the projection feed fills, so the Chat/StatusLine
+        // read side stays one seam for every backend.
+        publishActivity: (sessionId, view) => activityStore.update(sessionId, view),
+        clearActivity: sessionId => activityStore.clear(sessionId),
         // Same reason as the activity line: the occupancy projection only pushes on
         // change, so a resumed session reads one baseline at bind time.
         contextPressure: contextOccupancyStore,
@@ -497,8 +624,9 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
         // from the current launch directory would split @ expansion / file
         // completion (state.cwd) from the agent's own workspace record. Fresh
         // sessions record sessionCwd at creation, so both agree there.
-        cwd: agent.session.header.cwd ?? sessionCwd,
-        provider: displayRoute.provider,
+        // A resumed backend session runs where it was recorded.
+        cwd: backendStart?.session.cwd ?? agent?.session.header.cwd ?? sessionCwd,
+        provider: backendStart !== undefined ? backendStart.backendId : displayRoute.provider,
         // Raw cordis.yml route (undefined when unset): the channel's
         // new-session path re-resolves prefs against these, and resume passes
         // only explicit values so the target session's own record wins.
@@ -531,6 +659,7 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
         scrollGutter: config.scrollGutter,
         pageMargin: config.pageMargin,
         foldTerminalCommand: config.foldTerminalCommand,
+        turnUsageRow: config.turnUsageRow,
         promptSessionLabel: config.promptSessionLabel,
         expandEditor: config.expandEditor,
         smoothStreaming: config.smoothStreaming,
@@ -541,7 +670,9 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
         // 开屏大字字体：cordis.yml 这一层的值（未设置时 undefined → 通道归一化成
         // `daily`）；/settings 的改动由 applySplashFont 实时接上。
         splashFont: config.splashFont,
-        handle,
+        // 品牌外观（`dsh-tui.brand`）：`auto`（未设置）跟随后端自动切，/settings
+        // 的改动由 applyBrand 实时接上（branding.ts 负责解析）。
+        brand: config.brand,
     });
     // Register the live Channel for the adapter Kernel. The Channel driver
     // resolves it lazily from the composition root, so this can be called after
@@ -556,6 +687,32 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
     const uiMount = mountChannelUi(ctx, rawChannel, pluginHost, adapterRuntime.mode);
     const channel = uiMount.channel;
     bindChannelCommands(rawChannel, channel);
+    // last-run.json for the launcher's crash retry (see writeLastRunRecord):
+    // written once here, refreshed by the exit funnel with what is resumable
+    // at that point. The kernel-switch branch skips the refresh because the
+    // replacement writes its own record when it boots.
+    const bootAttemptId = `${process.pid.toString(36)}-${Date.now().toString(36)}`;
+    const refreshLastRunRecord = () => {
+        // An observational composition (replay/embedding) is not "the instance the
+        // user ran last" — it must not overwrite the interactive record.
+        if (adapterRuntime.mode === 'passive-shadow' || adapterRuntime.mode === 'replay-shadow')
+            return;
+        const resumable = backendStart !== undefined
+            ? backendStart.persisted(channel.agentId, channel.rows)
+            : isExitResumable({
+                pendingCount: channel.pending.length,
+                liveAgent: ctx.agents.get(SessionId(channel.agentId)),
+                startupAgent: agent,
+            });
+        writeLastRunRecord({
+            backendId: backendChoice,
+            sessionId: resumable ? channel.agentId : '',
+            cwd: sessionCwd,
+            attemptId: bootAttemptId,
+            pid: process.pid,
+        });
+    };
+    refreshLastRunRecord();
     const shadow = adapterRuntime.mode === 'passive-shadow' || adapterRuntime.mode === 'replay-shadow';
     // Bootstrap notices/prompts are deliberately dropped in observational mode;
     // interactive commands retain rejection semantics through the UI capability.
@@ -564,6 +721,10 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
             return () => undefined;
         return channel.notify(text, options);
     };
+    // The remembered-kernel fallback notice (set during backend startup above)
+    // lands once the channel can actually show it.
+    if (backendFallbackNotice !== undefined)
+        notifyChannel(backendFallbackNotice, { color: 'warning' });
     const submitChannel = text => {
         if (!shadow)
             channel.submit(text);
@@ -585,7 +746,10 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
     applySidePanelRatio(config.sidePanel?.ratio);
     applySidePanelPanels(config.sidePanel?.panels);
     applyCompanionSkin(config.companion?.skin);
+    applyBtwContextTurns(config.btw?.contextTurns);
+    applyBtwContextBudget(config.btw?.contextBudget);
     applyMermaidDiagrams(config.mermaidDiagrams);
+    applyCodeFrameStyle(config.codeFrameStyle);
     applyMathRendering(resolveMathRendering({}, config));
     applyMathImageScale(config.mathImageScale ?? 'auto');
     applyMathImageBacking(config.mathImageBacking ?? 'transparent');
@@ -648,6 +812,9 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
             // `?? config.foldTerminalCommand ?? false` already supplies the
             // default and keeps cordis.yml decisive.
             foldTerminalCommand: Schema.boolean(),
+            // Same no-default rule as foldTerminalCommand: applyDisplay resolves
+            // `?? config.turnUsageRow ?? false` so cordis.yml stays decisive.
+            turnUsageRow: Schema.boolean(),
             promptSessionLabel: Schema.boolean().default(false),
             // No schema default (same rule as foldTerminalCommand): applyDisplay
             // resolves `?? config.expandEditor ?? true` so cordis.yml stays
@@ -657,6 +824,8 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
             smoothStreaming: Schema.boolean(),
             // Same no-default rule: applyDisplay resolves `?? config.mermaidDiagrams ?? true`.
             mermaidDiagrams: Schema.boolean(),
+            // Code-frame shape; unset keeps the light rail frame.
+            codeFrameStyle: Schema.union(['light', 'full']),
             // Same no-default rule: resolveMathRendering falls back to cordis.yml.
             mathRendering: Schema.union(['auto', 'image', 'unicode', 'source']),
             // Display-formula image size; unset keeps the base (text) scale.
@@ -707,6 +876,13 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
             companion: Schema.object({
                 skin: Schema.string(),
             }),
+            // btw thread-context budgets (settings `btw.*`): no schema defaults
+            // (same rule as sidePanel above) — the apply* stores normalize an
+            // unset value to 4 turns / 24k chars.
+            btw: Schema.object({
+                contextTurns: Schema.number(),
+                contextBudget: Schema.number(),
+            }),
             // Header pixel whale art; on unless settings.yaml says otherwise.
             whale: Schema.boolean().default(true),
             // Idle whale behaviors after the intro settles; on by default —
@@ -723,6 +899,9 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
             // (undefined → daily), so cordis.yml stays decisive and junk lands on
             // daily.
             splashFont: Schema.string(),
+            // 品牌外观：与 splashFont 同规则——用户层不设默认，cordis.yml 保持
+            // 决定权；applyBrand 归一化（undefined → auto）。
+            brand: Schema.string(),
             // Minimal UI (极简界面, settings key `minimal` — never renamed): strips
             // the header splash, emoji glyphs, and decorative colors; code highlight
             // and tool colors stay. Unrelated to the kernel agent preset `minimal`.
@@ -768,6 +947,14 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
                 return;
             channel.setSplashFont(normalizeSplashFont(value.splashFont ?? config.splashFont));
         };
+        /** 品牌外观（`dsh-tui.brand`）：`auto` 跟随后端（Claude 后端整套换橙、
+         *  Codex 后端整套换薰衣草紫），其余固定一档；设置用户层优先于
+         *  cordis.yml，非法值回落 `auto`。 */
+        const applyBrand = (value) => {
+            if (shadow)
+                return;
+            channel.setBrand(normalizeBrandSetting(value.brand ?? config.brand));
+        };
         const applyMinimalUi = (value) => {
             if (shadow)
                 return;
@@ -811,10 +998,12 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
             channel.setPageMargin(pageMargin);
             applyPageMargin(pageMargin);
             channel.setFoldTerminalCommand(value.foldTerminalCommand ?? config.foldTerminalCommand ?? false);
+            channel.setTurnUsageRow(value.turnUsageRow ?? config.turnUsageRow ?? false);
             channel.setPromptSessionLabel(value.promptSessionLabel ?? config.promptSessionLabel ?? false);
             channel.setExpandEditor(value.expandEditor ?? config.expandEditor ?? true);
             channel.setSmoothStreaming(value.smoothStreaming ?? config.smoothStreaming ?? true);
             applyMermaidDiagrams(value.mermaidDiagrams ?? config.mermaidDiagrams);
+            applyCodeFrameStyle(value.codeFrameStyle ?? config.codeFrameStyle);
             applyMathRendering(resolveMathRendering(value, config));
             applyMathImageScale(value.mathImageScale ?? config.mathImageScale ?? 'auto');
             applyMathImageBacking(value.mathImageBacking ?? config.mathImageBacking ?? 'transparent');
@@ -829,6 +1018,8 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
             applySidePanelRatio(value.sidePanel?.ratio ?? config.sidePanel?.ratio);
             applySidePanelPanels(value.sidePanel?.panels ?? config.sidePanel?.panels);
             applyCompanionSkin(value.companion?.skin ?? config.companion?.skin);
+            applyBtwContextTurns(value.btw?.contextTurns ?? config.btw?.contextTurns);
+            applyBtwContextBudget(value.btw?.contextBudget ?? config.btw?.contextBudget);
         };
         // Legacy user scopes layer over cordis.yml. Modern Config is already
         // resolved: an unset action must not revive its startup override.
@@ -868,6 +1059,7 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
             applyWhaleIdle(next);
             applyWhaleGirl(next);
             applySplashFont(next);
+            applyBrand(next);
             applyMinimalUi(next);
             applyLang(next);
             applyDisplay(next);
@@ -1035,6 +1227,13 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
                         return String(typeof value === 'boolean' ? value : config.foldTerminalCommand === true);
                     },
                 },
+                {
+                    ...settingField('turnUsageRow'),
+                    format(value) {
+                        // Same effective-resolution rule as foldTerminalCommand's field.
+                        return String(typeof value === 'boolean' ? value : config.turnUsageRow === true);
+                    },
+                },
                 {
                     ...settingField('promptSessionLabel'),
                 },
@@ -1059,6 +1258,9 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
                         return String(typeof value === 'boolean' ? value : config.mermaidDiagrams !== false);
                     },
                 },
+                {
+                    ...settingField('codeFrameStyle'),
+                },
                 {
                     ...settingField('mathRendering'),
                 },
@@ -1202,6 +1404,42 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
                         return { kind: 'set', value: normalizeSidePanelPanels(draft) };
                     },
                 },
+                {
+                    // Like sidePanel.ratio: an out-of-range draft is rejected before
+                    // saving, and the store clamps to the same range anyway.
+                    ...settingField('btw.contextTurns'),
+                    placeholder: '4',
+                    format(value) {
+                        const turns = typeof value === 'number' && Number.isFinite(value) ? value : config.btw?.contextTurns;
+                        return String(turns ?? 4);
+                    },
+                    parse(text) {
+                        const draft = text.trim();
+                        if (draft === '')
+                            return { kind: 'clear' };
+                        const turns = Number(draft);
+                        if (!Number.isInteger(turns) || turns < BTW_CONTEXT_TURNS_MIN || turns > BTW_CONTEXT_TURNS_MAX)
+                            return undefined;
+                        return { kind: 'set', value: turns };
+                    },
+                },
+                {
+                    ...settingField('btw.contextBudget'),
+                    placeholder: '24000',
+                    format(value) {
+                        const budget = typeof value === 'number' && Number.isFinite(value) ? value : config.btw?.contextBudget;
+                        return String(budget ?? 24000);
+                    },
+                    parse(text) {
+                        const draft = text.trim();
+                        if (draft === '')
+                            return { kind: 'clear' };
+                        const budget = Number(draft);
+                        if (!Number.isInteger(budget) || budget < BTW_CONTEXT_BUDGET_MIN || budget > BTW_CONTEXT_BUDGET_MAX)
+                            return undefined;
+                        return { kind: 'set', value: budget };
+                    },
+                },
                 {
                     ...settingField('companion.skin'),
                 },
@@ -1223,6 +1461,12 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
                         return normalizeSplashFont(value ?? config.splashFont);
                     },
                 },
+                {
+                    ...settingField('brand'),
+                    format(value) {
+                        return normalizeBrandSetting(value ?? config.brand);
+                    },
+                },
                 {
                     ...settingField('minimal'),
                 },
@@ -1240,7 +1484,9 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
     // (/new, /resume, rewind), so ownership is re-evaluated per request.
     const approvalStore = new ApprovalStore(adapterRuntimeFor(ctx));
     bindApprovalStore(ctx, approvalStore);
-    if (ctx.get('approval') !== undefined) {
+    // A non-DSH backend answers its own permission prompts: the DSH answerer
+    // is not registered for it.
+    if (ctx.get('approval') !== undefined && backendStart === undefined) {
         ctx.on('approval/request', (req, next) => approvalStore.park(req).catch(() => next()));
         // Badge-flip push (P-4): React does not know the session log appended —
         // a source-badge verdict that only flips inside getSnapshot() surfaces
@@ -1255,10 +1501,12 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
     }
     // The agent view reads parked ask ids for its "needs input" state.
     rawChannel.bindApprovalStore(approvalStore);
+    // The panel source Chat renders: the backend's own prompts off DSH.
+    const panelApprovals = backendPermissions ?? approvalStore;
     const herdr = attachHerdrIntegration({
         channel,
         questions: questionStore,
-        approvals: approvalStore,
+        approvals: panelApprovals,
     });
     if (herdr !== undefined) {
         ctx.effect(() => () => herdr.dispose());
@@ -1302,6 +1550,10 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
     // write the resume target, restore the terminal, respawn the process with
     // the original argv, and let the fresh boot attach the same session.
     let restartRequested = false;
+    // The launchpad kernel selector's switch target: set once a choice was
+    // accepted; the exit funnel then respawns onto that kernel (a NEW session —
+    // no resume markers at all).
+    let backendSwitchRequested;
     // The profile this process was booted with (`dsh --profile <name>`); dsh
     // exposes it nowhere else, and /update must update the installation the
     // user is actually running, not a hard-coded one.
@@ -1311,46 +1563,86 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
     // not share a fate (issue #12). Teardown only unmounts the UI; user exit
     // runs the full leave sequence below (resume marker, terminal restore,
     // update handoff or resume hint).
+    /** The session id for a restart or update handoff, or empty when the backend
+     * has not persisted it and the replacement must start fresh. */
+    const handoffSessionId = () => backendStart === undefined || backendStart.persisted(channel.agentId, channel.rows) ? channel.agentId : '';
+    const handoffHint = backendStart === undefined ? undefined : (sessionId) => backendStart.resumeCommand(sessionId);
     const funnel = createExitFunnel({
         onUserExit: error => {
             // Mirror the funnel's internal exited flag for the /update and
             // background-check guards that still read the outer one.
             exited = true;
             if (error !== undefined) {
-                const message = error instanceof Error ? error.message : String(error);
-                ctx.logger.error(`dsh-tui: exit after error: ${message}`);
-                // A crash must leave the resume marker a clean exit would leave: the
-                // launcher's next start (and its safe-mode retry) then reopens the
-                // session the user was actually in instead of a blank one. Only the
-                // resumable case writes — unlike the clean-exit branch below, a crash
-                // never CLEARS a marker, so a session the user still has cannot be
-                // dropped by a failure that happened before the first message landed.
-                try {
-                    if (isExitResumable({
-                        pendingCount: channel.pending.length,
-                        liveAgent: ctx.agents.get(SessionId(channel.agentId)),
-                        startupAgent: agent,
-                    })) {
-                        writeResumeTarget(channel.agentId);
-                    }
-                }
-                catch {
-                    // Resume persistence is best effort and must never block the exit.
-                }
-                void finishExit(ctx, instance, bootedFullscreen, undefined, `dsh-tui crashed: ${message}`, () => disposeRootAndExit(ctx, 1));
+                // runCrashExit keeps the diagnostics apart from the resume markers
+                // and the terminal cleanup, so a throw while describing the error
+                // cannot skip finishExit.
+                runCrashExit({
+                    error,
+                    logError: message => { ctx.logger.error(message); },
+                    appendLog: appendCrashLog,
+                    logRestart: logRestartEvent,
+                    logDebug: logForDebugging,
+                    // A crash must leave the resume marker a clean exit would leave: the
+                    // launcher's next start (and its safe-mode retry) then reopens the
+                    // session the user was actually in instead of a blank one. Only the
+                    // resumable case writes — unlike the clean-exit branch below, a crash
+                    // never CLEARS a marker, so a session the user still has cannot be
+                    // dropped by a failure that happened before the first message landed.
+                    writeResumeMarkers: () => {
+                        if (isExitResumable({
+                            pendingCount: channel.pending.length,
+                            liveAgent: ctx.agents.get(SessionId(channel.agentId)),
+                            startupAgent: agent,
+                        })) {
+                            writeResumeTarget(channel.agentId);
+                        }
+                        // Non-DSH sessions use their backend preference as the launcher marker.
+                        if (backendStart !== undefined && backendStart.persisted(channel.agentId, channel.rows))
+                            backendStart.sessionPrefs.setLastSession(channel.agentId);
+                        // So the launcher's retry reopens this session, not the boot-time one.
+                        refreshLastRunRecord();
+                    },
+                    finish: crashLine => {
+                        void finishExit(ctx, instance, bootedFullscreen, undefined, crashLine, () => disposeRootAndExit(ctx, 1));
+                    },
+                });
                 return;
             }
             if (updateRequested) {
                 try {
-                    writeResumeTarget(channel.agentId);
+                    // Non-DSH sessions keep their marker in backend prefs, not DSH's `resume.txt`.
+                    if (backendStart === undefined)
+                        writeResumeTarget(channel.agentId);
+                    else if (backendStart.persisted(channel.agentId, channel.rows))
+                        backendStart.sessionPrefs.setLastSession(channel.agentId);
                 }
                 catch {
                     // Resume persistence is best effort and must never block an update.
                 }
+                refreshLastRunRecord();
                 const hintText = isStandaloneRuntime()
                     ? t('update-standalone-starting')
                     : t('update-starting');
-                void finishExit(ctx, instance, bootedFullscreen, hintText, undefined, () => runUpdate(ctx, profile, channel.agentId, updateTargetVersion));
+                void finishExit(ctx, instance, bootedFullscreen, hintText, undefined, () => runUpdate(ctx, profile, handoffSessionId(), updateTargetVersion, backendChoice, handoffHint));
+                return;
+            }
+            // The kernel selector's switch: the same respawn machinery, no resume.
+            // The new kernel starts a NEW session — no resume target is written
+            // (this kernel's sessions stay persisted; /resume finds them again
+            // after switching back), and restartTui's backend option deletes the
+            // inherited DSH_TUI_RESUME_SESSION marker from the replacement env.
+            // kernel.json was already written when the choice was accepted.
+            if (backendSwitchRequested !== undefined) {
+                logRestartEvent('funnel: backend-switch branch entered', { backend: backendSwitchRequested });
+                // Fullscreen keeps the alternate screen and writes the "switching"
+                // notice into it until the replacement takes over (see handoffAck.ts);
+                // inline restores the main screen and writes the notice there.
+                logRestartEvent(handoffEventTag('starting'), { backend: backendSwitchRequested });
+                const keepAlt = bootedFullscreen;
+                void finishExit(ctx, instance, bootedFullscreen, formatHandoffNotice('starting', { name: kernelDisplayName(backendSwitchRequested), color: process.stdout.isTTY === true }), undefined, () => runRestart(ctx, profile, '', undefined, {
+                    backend: backendSwitchRequested,
+                    ...(keepAlt ? { handoffScreen: 'alt' } : {}),
+                }), { keepAltScreen: keepAlt });
                 return;
             }
             // `/restart`: same handoff as the update path, no installation step.
@@ -1360,7 +1652,10 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
                 beginRestartAttempt(channel.agentId);
                 logRestartEvent('funnel: /restart branch entered');
                 try {
-                    writeResumeTarget(channel.agentId);
+                    if (backendStart === undefined)
+                        writeResumeTarget(channel.agentId);
+                    else if (backendStart.persisted(channel.agentId, channel.rows))
+                        backendStart.sessionPrefs.setLastSession(channel.agentId);
                     logRestartEvent('funnel: resume target written');
                 }
                 catch (error) {
@@ -1369,34 +1664,84 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
                         message: error instanceof Error ? error.message : String(error),
                     });
                 }
-                void finishExit(ctx, instance, bootedFullscreen, t('restart-starting'), undefined, () => runRestart(ctx, profile, channel.agentId));
+                refreshLastRunRecord();
+                void finishExit(ctx, instance, bootedFullscreen, t('restart-starting'), undefined, () => runRestart(ctx, profile, handoffSessionId(), handoffHint, { kernel: backendChoice }));
                 return;
             }
             // Judge against the live session behind the channel (channel.agentId),
             // not the boot-time agent captured above: /resume, /new and /model swap
             // the active agent, so the captured reference can go stale (see
             // isExitResumable).
-            const resumable = isExitResumable({
-                pendingCount: channel.pending.length,
-                liveAgent: ctx.agents.get(SessionId(channel.agentId)),
-                startupAgent: agent,
-            });
-            try {
-                if (resumable)
-                    writeResumeTarget(channel.agentId);
-                else
-                    clearResumeTarget();
+            let hint;
+            if (backendStart !== undefined) {
+                // Each non-DSH backend provides its marker and resume command; DSH uses
+                // `resume.txt`.
+                const resumable = backendStart.persisted(channel.agentId, channel.rows);
+                try {
+                    if (resumable)
+                        backendStart.sessionPrefs.setLastSession(channel.agentId);
+                }
+                catch {
+                    // Resume persistence is best effort and must never block shutdown.
+                }
+                hint = resumable ? `Resume with the command below:\n${backendStart.resumeCommand(channel.agentId)}` : undefined;
             }
-            catch {
-                // Resume persistence is best effort and must never block shutdown.
+            else {
+                const resumable = isExitResumable({
+                    pendingCount: channel.pending.length,
+                    liveAgent: ctx.agents.get(SessionId(channel.agentId)),
+                    startupAgent: agent,
+                });
+                try {
+                    if (resumable)
+                        writeResumeTarget(channel.agentId);
+                    else
+                        clearResumeTarget();
+                }
+                catch {
+                    // Resume persistence is best effort and must never block shutdown.
+                }
+                hint = resumable
+                    ? `Resume with the command below:\n${resumeCommand(profile, channel.agentId)}`
+                    : undefined;
             }
-            const hint = resumable
-                ? `Resume with the command below:\n${resumeCommand(profile, channel.agentId)}`
-                : undefined;
+            // Same resumability as the markers above.
+            refreshLastRunRecord();
             void finishExit(ctx, instance, bootedFullscreen, hint, undefined, () => disposeRootAndExit(ctx, 0));
         },
     });
     const handleExit = funnel.handleExit;
+    /** The launchpad kernel selector's accept path (the Chat side passes the
+     *  chosen kernel through onSwitchBackend — the prop wiring lands together
+     *  with the selector's Chat rendering). Persists the choice BEFORE the
+     *  teardown, so a crash mid-handoff still leaves the pick remembered, then
+     *  exits into the funnel's backend-switch branch: a fresh session on the
+     *  new kernel; this kernel's sessions stay persisted (/resume finds them
+     *  again after switching back). */
+    const switchBackend = (backend) => {
+        if (exited || restartRequested || backendSwitchRequested !== undefined)
+            return;
+        backendSwitchRequested = backend;
+        writeKernelPrefs({ backend });
+        logRestartEvent('command: backend switch accepted', { backend });
+        notifyChannel(t('kernel-switch-restarting', { name: kernelDisplayName(backend) }));
+        handleExit();
+    };
+    /** /channel changed the active channel's connection. The running CLI child
+     *  cannot change its baseUrl or token, so restart through the same funnel
+     *  branch as a kernel switch: same kernel, new session, no resume target.
+     *  The caller supplies the notice. */
+    const restartFreshSession = (notice) => {
+        if (exited || restartRequested || backendSwitchRequested !== undefined)
+            return;
+        if (backendChoice === 'codex')
+            restartRequested = true;
+        else
+            backendSwitchRequested = backendChoice;
+        logRestartEvent('command: channel connection switch accepted', { backend: backendChoice });
+        notifyChannel(notice);
+        handleExit();
+    };
     // Process-level crash backstop (see installNestedUpdateOverflowProcessGuard):
     // an uncaught exception or unhandled rejection that is NOT the React #185
     // overflow would otherwise take Node's default path and kill the process
@@ -1413,7 +1758,21 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
         // the funnel as-is: `error !== undefined` is what selects the crash path, so
         // a bare undefined would exit 0 while this sink claims the process.
         const fatal = fatalReasonForExit(error, origin);
-        ctx.logger.error(`dsh-tui: fatal ${origin}: ${fatal instanceof Error ? fatal.message : String(fatal)}`);
+        // Reading .message or String() can throw on a hostile value, and this
+        // runs before the funnel latch: an escape here would reach Node's default
+        // crash handler with no terminal cleanup. runCrashExit serializes the
+        // value safely later.
+        try {
+            ctx.logger.error(`dsh-tui: fatal ${origin}: ${fatal instanceof Error ? fatal.message : String(fatal)}`);
+        }
+        catch {
+            try {
+                ctx.logger.error(`dsh-tui: fatal ${origin}: (unserializable reason)`);
+            }
+            catch {
+                // Logging is gone; the funnel still must run.
+            }
+        }
         return handleExit(fatal);
     });
     // External injection controller: Chat fills it with `{ append, submit }`
@@ -1450,15 +1809,25 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
      * 目标喂进来（D:/node/dst.cmd 里 set DSH_TUI_WORKSPACE_TARGET=%CD%），一旦
      * 算进去，落地页在本机最主流的启动方式下**永远不出**——用户实测「既没看到
      * ob 也没看到 lp」的根因就是这一条。
+     *
+     * Two of the three boot screens are DSH screens: the workspace home lists
+     * DSH sessions and workspaces, and the first-run guide configures a DeepSeek
+     * key. The launchpad is not one of them: it is where the first sentence gets
+     * typed, so a remembered claude kernel boots onto it too (the session the
+     * plugin opened keeps warming underneath) — only a resume target skips it
+     * and opens straight into its conversation.
      */
+    const dshBoot = backendStart === undefined;
     const noResume = isLandingLaunch({ launchSessionId, initialPrompt });
-    const openHomeOnBoot = !homeSeen && noResume && requestedWorkspace === undefined;
+    const openHomeOnBoot = dshBoot && !homeSeen && noResume && requestedWorkspace === undefined;
     /**
      * The launchpad is NOT one-shot the way the workspace home is: every
      * ordinary launch starts on it, because it is where the first sentence gets
-     * typed rather than a tutorial that retires itself. `DSH_TUI_NO_LAUNCHPAD=1`
-     * is the escape hatch (an automation that wants the old blank conversation
-     * and no dialog in front of it).
+     * typed rather than a tutorial that retires itself — on every backend: a
+     * remembered claude kernel lands here exactly like a dsh one (the `dshBoot`
+     * gate below is deliberately absent). `DSH_TUI_NO_LAUNCHPAD=1` is the
+     * escape hatch (an automation that wants the old blank conversation and no
+     * dialog in front of it).
      */
     const launchpadOnBoot = noResume && process.env.DSH_TUI_NO_LAUNCHPAD !== '1';
     /**
@@ -1466,12 +1835,15 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
      * two answer different questions, and an install that already knows its
      * workspace may still never have configured a key.
      */
-    const onboardingOnBoot = noResume && shouldOfferOnboarding();
+    const onboardingOnBoot = dshBoot && noResume && shouldOfferOnboarding();
+    // 品牌镜像初值（branding.ts）：首帧渲染前铺好，避免 Claude 后端先画一屏
+    // 蓝再变橙。Chat 里的 effect 会在品牌解析变化时跟进更新这个镜像。
+    setActiveBrand(resolveBrand(config.brand, backendChoice));
     const chat = React.createElement(Chat, {
         channel,
         renderScene: createChannelSceneOutlet(() => rawChannel.pluginScene),
         questionStore,
-        approvalStore,
+        approvalStore: panelApprovals,
         injectControllerRef,
         openHomeOnBoot,
         launchpadOnBoot,
@@ -1502,6 +1874,19 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
             notifyChannel(t('restart-starting'));
             handleExit();
         },
+        // Kernel selector (/kernel and the launchpad row): the choice goes to
+        // kernel.json and the exit funnel restarts onto that kernel with a new
+        // session. The old kernel's sessions stay listed for /resume.
+        onSwitchBackend: switchBackend,
+        // /channel: restart with a new session after the connection changed.
+        onRestartFreshSession: restartFreshSession,
+        onProbeKernels: () => probeKernels(ctx, sessionCwd),
+        // The kernel picker's SDK install wizard (the dim Claude row, Enter).
+        onResolveSdkInstallTarget: sdkInstall.resolveTarget,
+        onStartSdkInstall: sdkInstall.start,
+        onCheckPnpm: sdkInstall.checkPnpm,
+        sdkInstallPinned: sdkInstall.pinned,
+        kernelPinned: backendPinned,
         // Only a `dsh --profile <name>` launch has a profile installation for
         // `/update` to act on; source checkouts and `--config` overlays get the
         // unavailable notice instead.
@@ -1579,6 +1964,9 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
         themeHost,
         children: marginChildren,
     });
+    // Kernel-switch replacement: send the ready ACK once the first frame after
+    // adoption is flushed. Does nothing on an ordinary boot.
+    armFirstFrameAck(process.stdout);
     instance = await render(tree, { exitOnCtrlC: false, terminalImages: bootedTerminalImages });
     const isRecompose = lastBootedFullscreen !== undefined;
     lastBootedFullscreen = bootedFullscreen;
@@ -1594,7 +1982,7 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
     // socket that appends text into the prompt input and submits it. Optional
     // integration — a bind failure degrades to "no channel" and never fails the
     // session. Closed on teardown so the socket and discovery record do not leak.
-    const injectChannel = openInjectChannel(agent.session.id, channel.cwd, {
+    const injectChannel = openInjectChannel(agent?.session.id ?? channel.agentId, channel.cwd, {
         append: (text) => injectControllerRef.current?.append(text),
         submit: () => injectControllerRef.current?.submit(),
     }, (message) => ctx.logger.warn(`dsh-tui: ${message}`));
@@ -1609,7 +1997,12 @@ export async function apply(ctx, runtimeConfig, configOwner = ctx) {
     // Registered on the same teardown funnel as everything else: the disposer
     // stops the heartbeat and removes the claim, so a clean exit frees its
     // sessions at once while a killed process is reclaimed by liveness.
-    ctx.effect(() => startSessionMountHeartbeat(ctx));
+    // A non-DSH session is in no DSH registry: the bound one is published under
+    // its backend-qualified key (`claude:<id>`), so a second TUI refuses it.
+    ctx.effect(() => startSessionMountHeartbeat(ctx, () => {
+        const ref = rawChannel.sessionRef;
+        return ref.backendId === 'dsh' ? [] : [formatSessionRef(ref)];
+    }));
     // Check in the background so registry latency never delays the first frame.
     // A failed/offline check is intentionally silent; the manual `/update`
     // command remains available regardless of network access.
@@ -1853,6 +2246,36 @@ export function createExitFunnel(deps) {
         },
     };
 }
+export function runCrashExit(deps) {
+    let detail;
+    try {
+        detail = (deps.serialize ?? serializeCrashDetail)(deps.error);
+        deps.logError(`dsh-tui: exit after error: ${detail.summary}`);
+        deps.appendLog(detail);
+        deps.logRestart('crash', { summary: detail.summary, ...(detail.digest === undefined ? {} : { digest: detail.digest }) });
+        deps.logDebug('dsh-tui: crash detail', { crash: detail.text });
+    }
+    catch {
+        // Ultimate degradation: fixed literals only — never re-read the throwable,
+        // never re-run the sink chain beyond one best-effort attempt.
+        detail = unserializableCrashDetail();
+        try {
+            deps.logError(`dsh-tui: exit after error: ${detail.summary}`);
+            deps.appendLog(detail);
+            deps.logRestart('crash', { summary: detail.summary });
+        }
+        catch {
+            // Nothing left to try — the cleanup below still must run.
+        }
+    }
+    try {
+        deps.writeResumeMarkers();
+    }
+    catch {
+        // Resume persistence is best effort and must never block the exit.
+    }
+    deps.finish(`dsh-tui crashed: ${detail.message}`);
+}
 /**
  * Whether a user exit should leave the resume marker (and print the resume
  * hint). Must be judged against the LIVE session behind the channel, not the
@@ -1866,6 +2289,8 @@ export function createExitFunnel(deps) {
  */
 export function isExitResumable(deps) {
     const agent = deps.liveAgent ?? deps.startupAgent;
+    if (agent === undefined)
+        return false;
     return (deps.pendingCount > 0 ||
         snapshotLiveSessionEvents(agent.session).some(event => event.type === 'user/message' && event.data.source.kind === 'user'));
 }
@@ -1873,7 +2298,7 @@ export function isExitResumable(deps) {
  * Finish terminal I/O before handing control to a process-level exit action.
  * Exported for scripts/verify-shutdown-fallback.
  */
-export async function finishExit(ctx, instance, fullscreen, notice, stderrNotice, done) {
+export async function finishExit(ctx, instance, fullscreen, notice, stderrNotice, done, options = {}) {
     try {
         // Resolve the Ink runtime twice: the instances map is keyed by stdout
         // identity, so a replaced/overridden stdout misses it; the render()
@@ -1921,8 +2346,14 @@ export async function finishExit(ctx, instance, fullscreen, notice, stderrNotice
         catch {
             ctx.logger.debug('dsh-tui: Ink shutdown detach failed; continuing with generic terminal cleanup');
         }
+        // Kernel-switch handoff (see handoffAck.ts):
+        //  - keepAltScreen: the old process stays in the alternate screen across
+        //    the spawn; it clears it and writes the switch notice there.
+        //  - ownsAltScreenExit() false: this is a replacement exiting before its
+        //    first frame, and the old process will close the alternate screen.
+        const exitAlt = fullscreen && !(options.keepAltScreen === true) && ownsAltScreenExit() ? EXIT_ALT_SCREEN : '';
         const cleanup = [
-            fullscreen ? EXIT_ALT_SCREEN : '',
+            exitAlt,
             cursor,
             DISABLE_MOUSE_TRACKING,
             DISABLE_MODIFY_OTHER_KEYS,
@@ -1935,7 +2366,8 @@ export async function finishExit(ctx, instance, fullscreen, notice, stderrNotice
             supportsTabStatus() ? wrapForMultiplexer(CLEAR_TAB_STATUS) : '',
         ].join('');
         const suffix = notice === undefined ? '' : `${notice}\n`;
-        await writeStream(process.stdout, `${cleanup}\r\n${suffix}`);
+        const restoreFrame = options.keepAltScreen === true ? '\x1b[2J\x1b[H' : '';
+        await writeStream(process.stdout, `${restoreFrame}${cleanup}\r\n${suffix}`);
         // Re-drain AFTER the cleanup sequences have landed (#507): terminal
         // replies and mouse packets already in flight when the exit started
         // keep arriving while cleanup is being written — the detach-time drain
@@ -2026,42 +2458,46 @@ function writeStream(stream, data) {
  * terminal handoff the /update path uses, minus the installation step.
  * The resume contract is dual-written (env + resume.txt) before this runs.
  */
-function runRestart(ctx, profile, sessionId) {
+/**
+ * The tail of a failed restart / update notice: how to resume the session —
+ * or nothing, when there is none to resume (a backend session the CLI never
+ * persisted hands over an empty id: a hint without an id would mislead).
+ */
+function preservedSessionTail(sessionId, hint) {
+    return sessionId === '' ? '\n\n' : ` Your session is preserved — resume with:\n${hint(sessionId)}\n\n`;
+}
+function runRestart(ctx, profile, sessionId, hint = id => resumeCommand(profile, id), options = {}) {
     logRestartEvent('runRestart: entered, disposing cordis root');
     disposeRootAndThen(ctx, () => {
         logRestartEvent('runRestart: root disposed, starting restartTui');
-        void restartTui(sessionId).then(restartCode => {
+        void restartTui(sessionId, options).then(restartCode => {
             logRestartEvent('runRestart: restartTui resolved', { restartCode });
             if (restartCode !== 0) {
-                writeHandoffNotice(`\ndsh-tui restart failed to spawn (exit ${restartCode}). Your session is preserved — resume with:\n` +
-                    `${resumeCommand(profile, sessionId)}\n\n`);
+                writeHandoffNotice(`\ndsh-tui restart failed to spawn (exit ${restartCode}).${preservedSessionTail(sessionId, hint)}`);
             }
             process.exit(restartCode);
         }, restartError => {
             const message = restartError instanceof Error ? restartError.message : String(restartError);
             logRestartEvent('runRestart: restartTui rejected', { message });
-            writeHandoffNotice(`\ndsh-tui restart failed: ${message}. Your session is preserved — resume with:\n` +
-                `${resumeCommand(profile, sessionId)}\n\n`);
+            writeHandoffNotice(`\ndsh-tui restart failed: ${message}.${preservedSessionTail(sessionId, hint)}`);
             process.exit(1);
         });
     });
 }
-function runUpdate(ctx, profile, sessionId, targetVersion) {
+function runUpdate(ctx, profile, sessionId, targetVersion, kernel, hint = id => resumeCommand(profile, id)) {
     disposeRootAndThen(ctx, () => {
         if (profile === undefined) {
             process.stderr.write(`\n${t('update-aborted-no-profile')}\n`);
             process.exit(1);
         }
-        void updateTuiAndRestart(sessionId, profile, targetVersion).then(({ updateCode, restartCode }) => {
+        void updateTuiAndRestart(sessionId, profile, targetVersion, kernel).then(({ updateCode, restartCode }) => {
             if (updateCode !== 0) {
-                process.stderr.write(`\ndsh-tui update failed (exit ${updateCode}). Your session is preserved — resume with:\n` +
-                    `${resumeCommand(profile, sessionId)}\n\n`);
+                process.stderr.write(`\ndsh-tui update failed (exit ${updateCode}).${preservedSessionTail(sessionId, hint)}`);
             }
             process.exit(restartCode);
         }, updateError => {
             const message = updateError instanceof Error ? updateError.message : String(updateError);
-            process.stderr.write(`\ndsh-tui update failed: ${message}. Your session is preserved — resume with:\n` +
-                `${resumeCommand(profile, sessionId)}\n\n`);
+            process.stderr.write(`\ndsh-tui update failed: ${message}.${preservedSessionTail(sessionId, hint)}`);
             process.exit(1);
         });
     });
@@ -2106,7 +2542,7 @@ function disposeRootAndThen(ctx, done, fallbackCode = 1) {
         process.exit(fallbackCode);
     }, 5000);
     timer.unref();
-    void withHostRootCapability(() => ctx.root.fiber.dispose()).then(() => {
+    void withHostRootCapability(() => ctx.root.fiber.dispose()).finally(() => closeBackendResources()).then(() => {
         clearTimeout(timer);
         done();
     }, () => {