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

package/lib/types/update.js

@@ -7,6 +7,12 @@ import { fileURLToPath } from 'node:url';
 import { gte, gt, lt, valid } from 'semver';
 import { shellQuote } from './utils/shellQuote.js';
 import { DATA_DIR } from './utils/paths.js';
+import { stripResumeArgs } from './sessionHistory.js';
+import { KERNEL_SWITCH_HANDOFF_ENV, isKernelId, kernelDisplayName } from './kernelPrefs.js';
+import { classifyReplacementOutcome, formatHandoffNotice, handoffEventTag, writeHandoffStage } from './handoffEvents.js';
+import { HANDOFF_ACK_FD_ENV, HANDOFF_ATTEMPT_ENV, HANDOFF_SCREEN_ENV, parseHandoffAckLine } from './handoffAck.js';
+import { DISABLE_KITTY_KEYBOARD, DISABLE_MODIFY_OTHER_KEYS, DISABLE_WIN32_INPUT_MODE } from './ink/termio/csi.js';
+import { DBP, DFE, DISABLE_MOUSE_TRACKING, EXIT_ALT_SCREEN, SHOW_CURSOR } from './ink/termio/dec.js';
 // Re-exported for scripts/verify-update.mjs and the bin launcher, which reads
 // the compiled copy at lib/types/utils/shellQuote.js.
 export { shellQuote };
@@ -62,6 +68,75 @@ function writeRestartLine(line) {
 export function logRestartEvent(event, data) {
     writeRestartLine(`${event}${data === undefined ? '' : ` ${JSON.stringify(data)}`}`);
 }
+const LAST_RUN_FILE = join(DATA_DIR, 'last-run.json');
+/** Windows rename retry cell (kernelPrefs writeKernelPrefs precedent). */
+const lastRunWaitCell = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * Stamp the last-run record atomically (tmp + rename, so the launcher's read
+ * never sees half a file). Best effort, never throws: a failed stamp only
+ * degrades the launcher's retry to its legacy sniffing path.
+ * @param record - Identity without updatedAt (stamped here, one clock).
+ * @param file - Path override (verify scripts point at a temp dir).
+ */
+export function writeLastRunRecord(record, file = LAST_RUN_FILE) {
+    const temporary = join(dirname(file), `.last-run.${process.pid}.${Date.now()}.tmp`);
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        const updatedAt = Date.now();
+        writeFileSync(temporary, `${JSON.stringify({ ...record, updatedAt }, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        for (let attempt = 0;; attempt++) {
+            try {
+                renameSync(temporary, file);
+                return;
+            }
+            catch (error) {
+                const code = typeof error === 'object' && error !== null ? String(error.code) : '';
+                if (process.platform !== 'win32' || attempt >= 7 || (code !== 'EPERM' && code !== 'EBUSY'))
+                    throw error;
+                Atomics.wait(lastRunWaitCell, 0, 0, 2 ** attempt);
+            }
+        }
+    }
+    catch (error) {
+        try {
+            rmSync(temporary, { force: true });
+        }
+        catch {
+            // The previous record stays; no safe remedy.
+        }
+        writeRestartLine(`last-run record write failed (${error instanceof Error ? error.message : String(error)})`);
+    }
+}
+/**
+ * Read the last-run record; unreadable/invalid/missing yields undefined (the
+ * caller falls back to its legacy behavior). Never throws.
+ * @param file - Path override (verify scripts point at a temp dir).
+ */
+export function readLastRunRecord(file = LAST_RUN_FILE) {
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        const record = parsed;
+        if (!isKernelId(record.backendId))
+            return undefined;
+        if (typeof record.sessionId !== 'string' || typeof record.cwd !== 'string' || typeof record.attemptId !== 'string')
+            return undefined;
+        if (typeof record.updatedAt !== 'number' || !Number.isFinite(record.updatedAt))
+            return undefined;
+        return {
+            backendId: record.backendId,
+            sessionId: record.sessionId,
+            cwd: record.cwd,
+            attemptId: record.attemptId,
+            updatedAt: record.updatedAt,
+            ...(typeof record.pid === 'number' ? { pid: record.pid } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
 /** Start a fresh, clearly delimited /restart attempt block in the log. */
 export function beginRestartAttempt(sessionId) {
     try {
@@ -94,6 +169,30 @@ export function writeHandoffNotice(text) {
         process.stderr.write(text);
     }
 }
+/**
+ * Hand the terminal back after a kernel-switch replacement that cannot clean
+ * up after itself: one that died before its first frame (this process still
+ * holds the alternate screen) or one killed by a signal. Besides leaving the
+ * alternate screen it turns off the input modes the replacement may already
+ * have enabled; each reset is harmless if the mode was never on. Written
+ * synchronously to fd 1 so the failure notice that follows lands on the main
+ * screen.
+ */
+export function restoreHandoffScreen() {
+    const reset = DISABLE_MOUSE_TRACKING + DISABLE_MODIFY_OTHER_KEYS + DISABLE_KITTY_KEYBOARD
+        + DISABLE_WIN32_INPUT_MODE + DFE + DBP + SHOW_CURSOR + EXIT_ALT_SCREEN + '\r\n';
+    try {
+        writeFileSync(1, reset);
+    }
+    catch {
+        try {
+            process.stdout.write(reset);
+        }
+        catch {
+            // Even a dead stdout must not block the exit path.
+        }
+    }
+}
 /** Read the version from either the compiled package or the source checkout. */
 export function installedTuiVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -966,16 +1065,38 @@ export function ensureProfileAllowBuilds(profile) {
  * (24h by default) — on release day that gate refuses the very version
  * `/update` is installing (ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION), which
  * reads to the user as a broken update until the window passes. Pre-seed the
- * profile's pnpm-workspace.yaml with a release-age exclusion scoped to this
- * package at the exact target version — the same best-effort, idempotent
- * pattern as {@link ensureProfileAllowBuilds}: foreign entries are preserved,
- * an existing entry for this package is replaced (one entry tracks the current
- * target instead of accumulating), a missing `minimumReleaseAgeExclude` block
- * is appended, a missing file is created, and an absent profile directory
- * resolves to undefined — the caller still runs pnpm, whose own diagnostic
- * stays the visible fallback.
+ * profile's pnpm-workspace.yaml with release-age exclusions scoped to this
+ * package at the exact versions pnpm verifies before it can swap the package:
+ * the target version itself, plus `alsoExempt` — the pre-update `updatedFrom`,
+ * read from the running package's own manifest (normally the version the
+ * profile lockfile pins). Two releases inside the 24h window leave the OLD
+ * lockfile entry inside it too, and pnpm fails the whole policy check on that
+ * entry before replacing the package (issue #1205), so exempting only the
+ * target is not enough. Same best-effort,
+ * idempotent pattern as {@link ensureProfileAllowBuilds}: entries for this
+ * package track exactly the versions the current update needs (older own
+ * entries are dropped instead of accumulating), foreign entries are
+ * preserved, a missing `minimumReleaseAgeExclude` block is appended, a
+ * missing file is created, and an absent profile directory resolves to
+ * undefined — the caller still runs pnpm, whose own diagnostic stays the
+ * visible fallback. Own entries are re-rendered target-first on every
+ * rewrite: pnpm 11.7.x honours only the FIRST entry per package (later
+ * entries for the same package are ignored against the real registry), and
+ * 11.21.x applies every entry in any order, so the target — the version the
+ * swap itself has to resolve, and published by construction while a
+ * dev-built `updatedFrom` need not be — takes the slot older pnpm still
+ * reads. Both exemptions come from the manifest, not from `pnpm-lock.yaml`:
+ * a profile whose manifest and lockfile diverged keeps the lockfile's entry
+ * unexempted. The 11.7.x `--frozen-lockfile` policy check reads that first
+ * entry only, so a two-entry list does not clear it there; the `pnpm add`
+ * path `/update` runs resolves the target and does pass.
+ *
+ * @param profile - The dsh profile whose workspace file is seeded.
+ * @param version - The update target (exact version).
+ * @param alsoExempt - Optional second version to keep exempt, normally the
+ *   pre-update `updatedFrom`; ignored when empty or equal to `version`.
  */
-export function ensureProfileReleaseAgeExclude(profile, version) {
+export function ensureProfileReleaseAgeExclude(profile, version, alsoExempt) {
     const yamlPath = profileWorkspaceYamlPath(profile);
     try {
         if (!existsSafe(dirname(yamlPath)))
@@ -988,6 +1109,10 @@ export function ensureProfileReleaseAgeExclude(profile, version) {
             // Missing file — start from an empty document; writeFileSync creates it.
         }
         const entry = `${PACKAGE_NAME}@${version}`;
+        const alsoEntry = alsoExempt !== undefined && alsoExempt !== '' && alsoExempt !== version
+            ? `${PACKAGE_NAME}@${alsoExempt}`
+            : undefined;
+        const keep = alsoEntry === undefined ? [entry] : [entry, alsoEntry];
         const lines = text.split(/\r?\n/u);
         let blockStart = -1;
         for (let i = 0; i < lines.length; i += 1) {
@@ -999,9 +1124,12 @@ export function ensureProfileReleaseAgeExclude(profile, version) {
         }
         /** Item text of a list line, unquoted (`- 'x@1'` / `- x@1` → `x@1`). */
         const itemOf = (line) => line.trim().replace(/^-\s*/u, '').replace(/^'(.*)'$/u, '$1');
-        const foreign = [];
+        /** Foreign exclusion lines, preserved verbatim and in file order. */
+        const foreignLines = [];
+        /** Keep-set entries already present in the block. */
+        const present = [];
+        let droppedStale = false;
         let blockEnd = -1;
-        let alreadyCurrent = false;
         if (blockStart !== -1) {
             blockEnd = blockStart + 1;
             for (let i = blockStart + 1; i < lines.length; i += 1) {
@@ -1010,21 +1138,27 @@ export function ensureProfileReleaseAgeExclude(profile, version) {
                     break; // dedent = block ends
                 blockEnd = i + 1;
                 const item = itemOf(line);
-                if (item === entry) {
-                    alreadyCurrent = true;
-                    foreign.push(line);
+                if (!item.startsWith(`${PACKAGE_NAME}@`)) {
+                    foreignLines.push(line);
                 }
-                else if (!item.startsWith(`${PACKAGE_NAME}@`)) {
-                    foreign.push(line);
+                else if (keep.includes(item)) {
+                    present.push(item);
+                }
+                else {
+                    // Own entries for older targets: dropped (no accumulation).
+                    droppedStale = true;
                 }
-                // Stale entries for THIS package (older targets) are dropped above.
             }
         }
-        if (alreadyCurrent) {
-            const entries = [entry, ...lines.slice(blockStart + 1, blockEnd).map(itemOf)];
-            return { entries, changed: false };
+        const missing = keep.filter(item => !present.includes(item));
+        if (!droppedStale && missing.length === 0) {
+            return { entries: [...foreignLines.map(itemOf), ...present], changed: false };
         }
-        const insert = foreign.concat(`  - '${entry}'`);
+        // Own entries are re-rendered in keep order (target first) instead of
+        // copied as found: pnpm 11.7.x honours only the first entry per package
+        // (11.21.x applies them all, order-independent), and the target is the
+        // version the swap must resolve, so it takes that first slot.
+        const insert = foreignLines.concat(keep.map(item => `  - '${item}'`));
         if (blockStart !== -1) {
             lines.splice(blockStart + 1, blockEnd - blockStart - 1, ...insert);
         }
@@ -1034,7 +1168,7 @@ export function ensureProfileReleaseAgeExclude(profile, version) {
             lines.push('minimumReleaseAgeExclude:', ...insert);
         }
         writeFileSync(yamlPath, `${lines.join('\n')}\n`);
-        return { entries: [...foreign.map(itemOf), entry], changed: true };
+        return { entries: insert.map(itemOf), changed: true };
     }
     catch {
         return undefined;
@@ -1446,13 +1580,17 @@ export async function updateTui(profile, targetVersion) {
     // pnpm ≥11's minimumReleaseAge (24h by default) refuses installs of
     // packages published within the window — on release day that gate rejects
     // the exact version /update pins, surfacing as a failed update that heals
-    // itself a day later. Scope-exempt this package at the exact target before
-    // pnpm runs (release-day /update parity with the allowBuilds seed above).
+    // itself a day later. Two releases inside the window (issue #1205) trip the
+    // same gate on the OLD lockfile entry pnpm verifies before the swap, so
+    // both the target and the still-installed updatedFrom are exempted.
     if (targetVersion !== undefined) {
-        const releaseAge = ensureProfileReleaseAgeExclude(profile, targetVersion);
+        const releaseAge = ensureProfileReleaseAgeExclude(profile, targetVersion, updatedFrom === '' ? undefined : updatedFrom);
         if (releaseAge !== undefined && releaseAge.changed) {
-            process.stderr.write(`dsh-tui: pre-seeded profile release-age exclusion (${PACKAGE_NAME}@${targetVersion}) — ` +
-                'a freshly published version installs without the 24h supply-chain delay\n');
+            const exempted = updatedFrom !== '' && updatedFrom !== targetVersion
+                ? `${PACKAGE_NAME}@${targetVersion} + ${PACKAGE_NAME}@${updatedFrom}`
+                : `${PACKAGE_NAME}@${targetVersion}`;
+            process.stderr.write(`dsh-tui: pre-seeded profile release-age exclusion (${exempted}) — ` +
+                'freshly published versions install without the 24h supply-chain delay\n');
         }
     }
     let updateStderr = '';
@@ -1540,9 +1678,10 @@ export async function updateTui(profile, targetVersion) {
  *   other profile would leave the running install untouched.
  * @param targetVersion - Exact version returned by the preflight registry
  *   check, or undefined when that check failed and pnpm should resolve latest.
+ * @param kernel - The kernel this process runs (TuiRestartOptions.kernel).
  * @returns Exit codes for the update run and the replacement process.
  */
-export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
+export async function updateTuiAndRestart(sessionId, profile, targetVersion, kernel) {
     const outcome = await updateTui(profile, targetVersion);
     const { updatedFrom } = outcome;
     if (outcome.code !== 0)
@@ -1557,6 +1696,7 @@ export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
     const restartCode = await restartTui(sessionId, {
         env: { [UPDATED_FROM_ENV]: updatedFrom },
         kind: 'update',
+        ...(kernel === undefined ? {} : { kernel }),
     });
     return { updateCode: 0, restartCode };
 }
@@ -1622,10 +1762,85 @@ export async function cliUpdate(profile) {
     }
     return outcome.code;
 }
+/**
+ * Release the shared console for the replacement without resetting it.
+ *
+ * A pty's termios is per-DEVICE: destroying this stream would write this
+ * process's saved cooked/ECHO mode back over the replacement's raw mode
+ * (libuv restores orig_termios on tty close; verified on Node 24 — mouse
+ * reports then echo as `^[[<…M` and keys wait for a newline). Detaching —
+ * no readers, paused, unref'd — keeps the mode untouched.
+ *
+ * Two deliberate trade-offs vs the old destroy():
+ * - destroy() doubled as a permanent gate ("a destroyed stream can never be
+ *   resumed"). Readers removed + paused already keep this process out of the
+ *   console's key path (#284/#307), and after the handoff only the
+ *   child-exit listener remains here — nothing re-attaches a reader.
+ * - On exit Node still writes the saved cooked mode back once (atexit
+ *   uv_tty_reset_mode). Fine in the normal order — this process outlives the
+ *   replacement, and the shell wants cooked back anyway; it only bites if
+ *   this process dies while the replacement is still running.
+ *
+ * @param stdin - Console stream to detach; injectable for the regression.
+ */
+export function detachHandoffStdin(stdin = process.stdin) {
+    stdin.removeAllListeners('readable');
+    stdin.removeAllListeners('data');
+    stdin.pause();
+    stdin.unref();
+}
+/**
+ * The replacement's env, pure: the resume marker, the /restart child stamp,
+ * the caller's extra markers and the kernel-switch overrides. Exported for
+ * scripts/verify-launchpad, which feeds it through the boot resolver.
+ */
+export function restartChildEnv(parentEnv, sessionId, kind, options) {
+    const childEnv = {
+        ...parentEnv,
+        // The replacement resumes the current session through the launcher
+        // contract (DSH_TUI_RESUME_SESSION; see src/sessionHistory.ts).
+        DSH_TUI_RESUME_SESSION: sessionId,
+        // Marks the replacement so its own boot logs to restart.log without
+        // noisy logging on every ordinary launch (/restart only).
+        ...(kind === 'restart' ? { [RESTART_CHILD_ENV]: '1' } : {}),
+        ...options.env,
+    };
+    // A stale handoff override never leaks into a plain replacement: the var is
+    // one-shot (consumed at this process's own boot), and a child that is NOT
+    // switching kernels keeps this process's kernel by config/env/memory as
+    // usual.
+    delete childEnv[KERNEL_SWITCH_HANDOFF_ENV];
+    // Same for the alt-screen handoff markers: a replacement must not adopt a
+    // screen or ACK pipe from an earlier attempt. restartTui sets them again
+    // when it opens a handoff.
+    delete childEnv[HANDOFF_SCREEN_ENV];
+    delete childEnv[HANDOFF_ACK_FD_ENV];
+    delete childEnv[HANDOFF_ATTEMPT_ENV];
+    if (options.backend === undefined && options.kernel !== undefined)
+        childEnv[KERNEL_SWITCH_HANDOFF_ENV] = options.kernel;
+    if (options.backend !== undefined) {
+        childEnv.DSH_TUI_BACKEND = options.backend;
+        // DSH_TUI_BACKEND alone loses to a Config row (config > env > memory),
+        // so the switch also sets the one-shot variable that ranks above config.
+        childEnv[KERNEL_SWITCH_HANDOFF_ENV] = options.backend;
+        // A kernel switch never resumes: the id of THIS backend's session means
+        // nothing to the next one, and an inherited marker (this process may
+        // itself be a /restart child) would send the new kernel looking for it —
+        // deleted outright, not blanked (the launcher row maps '' to
+        // config.sessionId='', not to "absent").
+        delete childEnv.DSH_TUI_RESUME_SESSION;
+    }
+    return childEnv;
+}
 export async function restartTui(sessionId, options = {}) {
     const kind = options.kind ?? 'restart';
-    const tag = kind === 'update' ? 'update-restart' : 'restart';
-    const argv = [...process.execArgv, ...process.argv.slice(1)];
+    const tag = options.backend !== undefined ? 'backend-switch' : kind === 'update' ? 'update-restart' : 'restart';
+    // A kernel switch must not hand the replacement THIS kernel's resume
+    // flags: an inherited `--resume <id>` in argv would send the new kernel
+    // looking for a session that belongs to the kernel it just left — the
+    // same reason DSH_TUI_RESUME_SESSION is deleted below.
+    const appArgs = process.argv.slice(1);
+    const argv = [...process.execArgv, ...(options.backend === undefined ? appArgs : stripResumeArgs(appArgs))];
     logRestartEvent(`${tag}: spawning replacement`, {
         node: process.execPath,
         argv,
@@ -1637,34 +1852,95 @@ export async function restartTui(sessionId, options = {}) {
         dshHome: process.env.DSH_HOME ?? null,
     });
     const startedAt = Date.now();
+    // Fullscreen kernel switch: keep the alternate screen until the replacement
+    // reports its first flushed frame on the ACK pipe (see handoffScreen).
+    const handoff = options.handoffScreen === 'alt' && options.backend !== undefined;
+    const attemptId = handoff ? 'hs-' + Date.now().toString(16) + '-' + Math.random().toString(16).slice(2, 8) : undefined;
+    // Ctrl+C while the replacement boots reaches this process too: same process
+    // group, and nothing has the terminal in raw mode yet. Dying here would
+    // leave behind the alternate screen this process still holds; the
+    // replacement gets the same signal, and its close below restores the screen.
+    const ignoreInterrupt = () => { };
+    if (handoff)
+        process.on('SIGINT', ignoreInterrupt);
+    // "Starting X…" goes out before the spawn, waiting for the write callback
+    // so it lands before the replacement draws anything.
+    if (options.backend !== undefined) {
+        await writeHandoffStage(process.stdout, formatHandoffNotice('stage-start', { name: kernelDisplayName(options.backend), color: process.stdout.isTTY === true }) + '\n');
+        logRestartEvent(handoffEventTag('stage-start'), { backend: options.backend, ...(attemptId === undefined ? {} : { attemptId }) });
+    }
     return new Promise(resolve => {
+        const childEnv = restartChildEnv(process.env, sessionId, kind, options);
+        if (handoff) {
+            // stdio[3] is the ACK pipe; the env tells the replacement its fd and the attempt id.
+            childEnv[HANDOFF_SCREEN_ENV] = 'alt';
+            childEnv[HANDOFF_ACK_FD_ENV] = '3';
+            childEnv[HANDOFF_ATTEMPT_ENV] = attemptId;
+            logRestartEvent('handoff: alt-screen bracket held for the replacement', { attemptId });
+        }
         const child = spawn(process.execPath, argv, {
-            env: {
-                ...process.env,
-                // The replacement resumes the current session through the launcher
-                // contract (DSH_TUI_RESUME_SESSION; see src/sessionHistory.ts).
-                DSH_TUI_RESUME_SESSION: sessionId,
-                // Marks the replacement so its own boot logs to restart.log without
-                // noisy logging on every ordinary launch (/restart only).
-                ...(kind === 'restart' ? { [RESTART_CHILD_ENV]: '1' } : {}),
-                ...options.env,
-            },
+            env: childEnv,
             // stdin/stdout stay inherited so the replacement owns the console the
             // moment it boots; stderr is captured so a boot failure is reportable
             // through THIS process (the terminal may already be mid-handoff when
-            // the child dies, and a raw inherit write can vanish).
-            stdio: ['inherit', 'inherit', 'pipe'],
+            // the child dies, and a raw inherit write can vanish). fd 3 is the
+            // one-way ACK pipe (replacement → supervisor): adopted / first frame.
+            stdio: handoff ? ['inherit', 'inherit', 'pipe', 'pipe'] : ['inherit', 'inherit', 'pipe'],
         });
-        logRestartEvent(`${tag}: replacement spawned`, { childPid: child.pid });
+        let ackAdoptedAt;
+        let ackReadyAt;
+        const ackStream = handoff ? (child.stdio[3] ?? undefined) : undefined;
+        if (ackStream !== undefined) {
+            ackStream.setEncoding('utf8');
+            let pending = '';
+            ackStream.on('data', (chunk) => {
+                pending += chunk;
+                for (;;) {
+                    const newline = pending.indexOf('\n');
+                    if (newline < 0)
+                        break;
+                    const line = pending.slice(0, newline);
+                    pending = pending.slice(newline + 1);
+                    const ack = parseHandoffAckLine(line);
+                    if (ack === null || ack.attemptId !== attemptId)
+                        continue;
+                    if (ack.kind === 'adopted' && ackAdoptedAt === undefined) {
+                        ackAdoptedAt = Date.now();
+                        logRestartEvent('handoff/screen-adopted', { attemptId, backend: options.backend });
+                    }
+                    if (ack.kind === 'ready' && ackReadyAt === undefined) {
+                        ackReadyAt = Date.now();
+                        // ready means the replacement's first frame was flushed, not just
+                        // that it mounted or is still alive.
+                        logRestartEvent(handoffEventTag('first-frame'), { attemptId, backend: options.backend, elapsedMs: ackReadyAt - startedAt });
+                    }
+                }
+            });
+            ackStream.on('error', () => {
+                // The supervisor outlives the pipe by contract; a broken pipe here
+                // means the replacement never speaks the protocol (e.g. an older
+                // build) — the close handler's no-ready branch still restores the
+                // screen, so the bracket can never be orphaned.
+            });
+            const ackWatch = setTimeout(() => {
+                if (ackReadyAt === undefined) {
+                    logRestartEvent('handoff/first-frame watch', { attemptId, note: 'no first-frame ACK within 30s (diagnosis only, never a success/failure fact)' });
+                }
+            }, 30000);
+            ackWatch.unref();
+        }
+        logRestartEvent(`${tag}: replacement spawned`, { childPid: child.pid, ...(options.backend === undefined ? {} : { backend: options.backend }) });
         // Handoff watchdog (field evidence 2026-08-24: restarted TUI mounts but
         // takes no input). Two jobs, both diagnosis-grade:
         // 1. SAMPLE this process's stdin state every second — if anything
         //    re-attaches a reader after the funnel's detachStdinForHandoff, the
         //    sample (taken before the re-assert below) shows it in the log.
-        // 2. RE-ASSERT the detach and finally destroy the stream: this process
-        //    must never read the shared console again — every keypress belongs
-        //    to the replacement, and a resumed pump here is exactly the
-        //    "restarted TUI sees dropped or swallowed input" failure (#284/#307).
+        // 2. RE-ASSERT the detach — never DESTROY the stream: destroying it
+        //    resets the shared pty and stomps the replacement's raw mode (see
+        //    detachHandoffStdin for the mechanism and trade-offs). This process
+        //    must never read the shared console again — every keypress belongs to
+        //    the replacement, and a resumed pump here is exactly the "restarted
+        //    TUI sees dropped or swallowed input" failure (#284/#307).
         let watchdogTicks = 0;
         const watchdog = setInterval(() => {
             watchdogTicks += 1;
@@ -1678,25 +1954,14 @@ export async function restartTui(sessionId, options = {}) {
                 buffered: stdin.readableLength,
             });
             try {
-                stdin.removeAllListeners('readable');
-                stdin.removeAllListeners('data');
-                stdin.pause();
+                detachHandoffStdin(stdin);
             }
             catch {
                 // Diagnosis/mitigation only.
             }
             if (watchdogTicks === 15) {
                 clearInterval(watchdog);
-                try {
-                    // Terminal safeguard: a destroyed stream can never be resumed by
-                    // any late re-attachment. The child holds its own inherited
-                    // handle, so closing ours does not affect it.
-                    process.stdin.destroy();
-                    logRestartEvent('parent: stdin destroyed after watchdog');
-                }
-                catch {
-                    // Best effort.
-                }
+                logRestartEvent('parent: stdin detached after watchdog (kept raw, not destroyed)');
             }
         }, 1000);
         watchdog.unref();
@@ -1720,19 +1985,78 @@ export async function restartTui(sessionId, options = {}) {
         timer.unref();
         child.once('error', error => {
             clearTimeout(timer);
+            process.removeListener('SIGINT', ignoreInterrupt);
             logRestartEvent(`${tag}: spawn error`, { message: error.message });
-            writeHandoffNotice(`dsh-tui: failed to spawn the restart: ${error.message}\n`);
+            if (options.backend !== undefined) {
+                // Nothing took the screen over: restore it before the notice.
+                if (handoff)
+                    restoreHandoffScreen();
+                // A spawn failure is a failed switch (yellow, with the safe-mode hint),
+                // not a crash.
+                logRestartEvent(handoffEventTag('failed'), { reason: 'spawn-error', message: error.message });
+                writeHandoffNotice(formatHandoffNotice('failed', {
+                    name: kernelDisplayName(options.backend),
+                    reason: 'spawn-error',
+                    safeHint: true,
+                    color: process.stderr.isTTY === true,
+                }) + `\n${error.message}\n`);
+            }
+            else {
+                writeHandoffNotice(`dsh-tui: failed to spawn the restart: ${error.message}\n`);
+            }
             resolve(127);
         });
         child.once('close', (code, signal) => {
             clearTimeout(timer);
+            process.removeListener('SIGINT', ignoreInterrupt);
             const elapsedMs = Date.now() - startedAt;
             logRestartEvent(`${tag}: replacement exited`, {
                 code: code ?? null,
                 signal: signal ?? null,
                 elapsedMs,
             });
-            if (elapsedMs < 4000) {
+            if (options.backend !== undefined) {
+                // Kernel switch outcome: success is quiet (restart.log only), a
+                // replacement that never came up is a yellow failure with the session
+                // kept and the safe-mode hint, and a later nonzero exit is a red
+                // crash. With the ACK pipe the first frame decides which of the two
+                // failures it was; see classifyReplacementOutcome.
+                const outcome = classifyReplacementOutcome({
+                    closed: true, code, signal, elapsedMs,
+                    ...(handoff ? { firstFrameAcked: ackReadyAt !== undefined } : {}),
+                });
+                logRestartEvent(handoffEventTag(outcome.kind), {
+                    ...(outcome.kind === 'crashed' ? { code: outcome.code } : outcome.kind === 'failed' ? { reason: outcome.reason } : {}),
+                    ...(attemptId === undefined ? {} : { attemptId }),
+                });
+                if (outcome.kind === 'failed') {
+                    // Before ready this process still holds the alternate screen:
+                    // restore it first so the notice lands on the main screen. After
+                    // ready the replacement's own exit cleanup closed it.
+                    if (handoff && ackReadyAt === undefined)
+                        restoreHandoffScreen();
+                    const suffix = childStderr.trim() === '' ? '' : `\n${childStderr.trimEnd()}`;
+                    writeHandoffNotice(formatHandoffNotice('failed', {
+                        name: kernelDisplayName(options.backend),
+                        reason: outcome.reason,
+                        safeHint: true,
+                        color: process.stderr.isTTY === true,
+                    }) + `${suffix}\n`);
+                }
+                else if (outcome.kind === 'crashed') {
+                    // A signal death after the first frame skipped the replacement's
+                    // own exit cleanup, so the screen and input modes are still its.
+                    if (handoff && signal !== null)
+                        restoreHandoffScreen();
+                    writeHandoffNotice('\n' + formatHandoffNotice('crashed', {
+                        name: kernelDisplayName(options.backend),
+                        code: outcome.code,
+                        safeHint: true,
+                        color: process.stderr.isTTY === true,
+                    }) + '\n');
+                }
+            }
+            else if (elapsedMs < 4000) {
                 // Fast death: the TUI never came up. Synchronous stderr write —
                 // process.exit() right after an async stream write skips the flush,
                 // and a vanished diagnosis is indistinguishable from silent failure.

package/lib/types/utils/bmp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bmp.d.ts","sourceRoot":"","sources":["../../../src/utils/bmp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA8DH;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuFlE"}
+{"version":3,"file":"bmp.d.ts","sourceRoot":"","sources":["../../../src/utils/bmp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA8DH;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA4FlE"}

package/lib/types/utils/bmp.js

@@ -74,6 +74,10 @@ export async function bmpToPng(bmp) {
         return null;
     if (bpp !== 24 && bpp !== 32)
         return null;
+    // High-colour DIBs may still carry a colour table. Without a file header
+    // its length is ambiguous; a BMP file instead locates pixels via bfOffBits.
+    if (!hasFileHeader && bmp.readUInt32LE(dib + 32) !== 0)
+        return null; // biClrUsed
     if (compression !== BI_RGB && compression !== BI_BITFIELDS && compression !== BI_ALPHABITFIELDS)
         return null;
     if (bpp === 24 && compression !== BI_RGB)
@@ -100,7 +104,10 @@ export async function bmpToPng(bmp) {
     if (bpp === 32 && (redMask === 0 || greenMask === 0 || blueMask === 0))
         return null;
     const declaredOffset = hasFileHeader ? bmp.readUInt32LE(10) : 0;
-    const pixelOffset = declaredOffset > 0 ? declaredOffset : dib + headerSize + maskBytes;
+    const minimumOffset = dib + headerSize + maskBytes;
+    if (hasFileHeader && declaredOffset < minimumOffset)
+        return null;
+    const pixelOffset = hasFileHeader ? declaredOffset : minimumOffset;
     const stride = Math.floor((bpp * width + 31) / 32) * 4;
     if (pixelOffset + stride * height > bmp.length)
         return null;

package/lib/types/utils/clipboard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../../../src/utils/clipboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAeH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAElC;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAA;AAE5F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA6BtD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAIvE;AAWD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAYtE;AAiDD;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAS9C;AAoeD;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC,CAStD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAcvE"}
+{"version":3,"file":"clipboard.d.ts","sourceRoot":"","sources":["../../../src/utils/clipboard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAeH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAElC;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,IAAI,CAAA;AAE5F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CA6BtD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAIvE;AAWD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAYtE;AAiDD;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAS9C;AAsfD;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAAC,aAAa,CAAC,CAStD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,IAAI,CAEhE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAcvE"}