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

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));
@@ -1579,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)
@@ -1596,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 };
 }
@@ -1688,10 +1789,58 @@ export function detachHandoffStdin(stdin = process.stdin) {
     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,
@@ -1703,25 +1852,84 @@ 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
@@ -1777,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/crashDetail.d.ts

@@ -0,0 +1,56 @@
+/** One serialized level: the crash itself or a link of its `.cause` chain. */
+export interface CrashDetailLevel {
+    /** Constructor name (`TypeError`), or the JS typeof for non-Errors. */
+    readonly name: string;
+    readonly message: string;
+    /** Raw multi-frame stack when this level is an Error that carries one. */
+    readonly stack?: string;
+}
+/** Full crash serialization: the error, its cause chain, and React extras. */
+export interface CrashDetail {
+    readonly message: string;
+    /** Head-level stack (=== levels[0].stack). */
+    readonly stack?: string;
+    /** The error followed by every `.cause` link, outermost first. */
+    readonly levels: readonly CrashDetailLevel[];
+    /** React component tree trace when attached to the error object. */
+    readonly componentStack?: string;
+    /** React production digest when attached to the error object. */
+    readonly digest?: string;
+    /** `${name}: ${message}` one-liner for logs that must stay one line. */
+    readonly summary: string;
+    /** Full multi-line block crash.log stores after its header line. */
+    readonly text: string;
+}
+/** Stand-in text for a value whose own string conversion throws. */
+export declare const UNSERIALIZABLE = "[unserializable value]";
+/**
+ * Serialize an unknown crash value: head message + stack, the `.cause` chain
+ * level by level, and componentStack / digest when attached. Never throws and
+ * never loops — the crash path's own diagnostics must not become a second
+ * crash. Exported for scripts/verify-crash-detail.
+ */
+export declare function serializeCrashDetail(error: unknown): CrashDetail;
+/**
+ * Crash detail built from literals only, for when serializing or logging
+ * the real one failed. It never touches the thrown value, so it cannot throw.
+ */
+export declare function unserializableCrashDetail(): CrashDetail;
+/**
+ * The crash.log line: restart.log's `<UTC ISO> pid=<pid>` header style
+ * (writeRestartLine precedent, src/update.ts) followed by the detail block.
+ * @param detail - Serialized crash (serializeCrashDetail).
+ * @param at - Timestamp of the crash (injected so the format stays testable).
+ * @param pid - Process id (injected so the format stays testable).
+ */
+export declare function formatCrashLogLine(detail: CrashDetail, at: Date, pid: number): string;
+/**
+ * Append the crash detail to `<dir>/crash.log` (default `~/.dsh-tui`,
+ * DATA_DIR — same home-dir resolution as restart.log, never a hard-coded
+ * path). Every failure is swallowed: post-mortem diagnostics must never take
+ * the exit path down (mouse-debug.log precedent).
+ * @param detail - Serialized crash (serializeCrashDetail).
+ * @param dir - Data directory override (verify scripts point at a temp dir).
+ */
+export declare function appendCrashLog(detail: CrashDetail, dir?: string): void;
+//# sourceMappingURL=crashDetail.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crashDetail.d.ts","sourceRoot":"","sources":["../../../src/utils/crashDetail.ts"],"names":[],"mappings":"AAeA,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,8EAA8E;AAC9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,SAAS,gBAAgB,EAAE,CAAA;IAC5C,oEAAoE;IACpE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAUD,oEAAoE;AACpE,eAAO,MAAM,cAAc,2BAA2B,CAAA;AA+DtD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAsChE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,WAAW,CAYvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,GAAE,MAAiB,GAAG,IAAI,CAShF"}

package/lib/types/utils/crashDetail.js

@@ -0,0 +1,175 @@
+/**
+ * Crash serialization for the exit funnel (src/dsh-adapter/plugin.ts).
+ *
+ * A message-only crash line (`Minified React error #185`) loses the stack,
+ * the `.cause` chain and the React extras (componentStack, digest) that a
+ * production build still carries. These helpers serialize all of it and
+ * append it to ~/.dsh-tui/crash.log.
+ *
+ * Dependency-free (node builtins and paths only) so verify scripts can load
+ * it without the plugin graph.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { DATA_DIR } from './paths.js';
+/** A pathological (self- or mutually-referring) cause chain must not loop. */
+const MAX_CAUSE_LEVELS = 8;
+/** Cap the serialized block so huge synthetic stacks cannot grow crash.log unbounded. */
+const MAX_TEXT_CHARS = 32 * 1024;
+const isRecord = (value) => typeof value === 'object' && value !== null;
+/** Stand-in text for a value whose own string conversion throws. */
+export const UNSERIALIZABLE = '[unserializable value]';
+/**
+ * Read one property of a value that may throw on access (a getter or a Proxy
+ * trap); a throw reads as undefined. The crash funnel runs after the exit
+ * latch is set, so an exception escaping from here would skip the cleanup
+ * that follows it.
+ */
+function safeProp(record, key) {
+    try {
+        return record[key];
+    }
+    catch {
+        return undefined;
+    }
+}
+/** instanceof through a maybe-hostile value: a Proxy can trap
+ * getPrototypeOf too, and that must degrade the same way as a property read. */
+function safeInstanceOfError(value) {
+    try {
+        return value instanceof Error;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Three-tier stringify: String(value), then Object.prototype.toString.call
+ * (itself re-wrapped — a Symbol.toStringTag getter can throw too), then the
+ * fixed literal. Never throws.
+ */
+function safeString(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        // Fall through to the second conversion.
+    }
+    try {
+        return Object.prototype.toString.call(value);
+    }
+    catch {
+        // Fall through to the fixed literal.
+    }
+    return UNSERIALIZABLE;
+}
+function serializeLevel(error) {
+    if (safeInstanceOfError(error) && isRecord(error)) {
+        const rawName = safeProp(error, 'name');
+        const rawStack = safeProp(error, 'stack');
+        const rawMessage = safeProp(error, 'message');
+        const name = typeof rawName === 'string' && rawName !== '' ? rawName : 'Error';
+        const stack = typeof rawStack === 'string' && rawStack !== '' ? rawStack : undefined;
+        // A non-string message still stringifies (a hostile Error can carry 42);
+        // only a THROWING conversion degrades to the fixed literal.
+        const message = typeof rawMessage === 'string' ? rawMessage : safeString(rawMessage);
+        return { name, message, ...(stack === undefined ? {} : { stack }) };
+    }
+    return { name: typeof error, message: safeString(error) };
+}
+/** Indent every line of a (multi-frame) block for the text serialization. */
+const indentBlock = (block) => block.replace(/^/gm, '    ');
+/**
+ * Serialize an unknown crash value: head message + stack, the `.cause` chain
+ * level by level, and componentStack / digest when attached. Never throws and
+ * never loops — the crash path's own diagnostics must not become a second
+ * crash. Exported for scripts/verify-crash-detail.
+ */
+export function serializeCrashDetail(error) {
+    const levels = [serializeLevel(error)];
+    // Follow .cause links (ES2022 Error cause + manually attached ones); the
+    // seen-set stops self/mutual references, the cap stops absurd chains.
+    const seen = new Set([error]);
+    let current = isRecord(error) ? safeProp(error, 'cause') : undefined;
+    while (levels.length < MAX_CAUSE_LEVELS && current !== undefined && current !== null && !seen.has(current)) {
+        seen.add(current);
+        levels.push(serializeLevel(current));
+        current = isRecord(current) ? safeProp(current, 'cause') : undefined;
+    }
+    const head = levels[0];
+    const rawComponentStack = isRecord(error) ? safeProp(error, 'componentStack') : undefined;
+    const rawDigest = isRecord(error) ? safeProp(error, 'digest') : undefined;
+    const componentStack = typeof rawComponentStack === 'string' && rawComponentStack !== ''
+        ? rawComponentStack
+        : undefined;
+    const digest = typeof rawDigest === 'string' && rawDigest !== '' ? rawDigest : undefined;
+    const summary = safeInstanceOfError(error) ? `${head.name}: ${head.message}` : head.message;
+    const lines = [`dsh-tui crashed: ${summary}`];
+    levels.forEach((level, index) => {
+        lines.push(`level ${index}${index === 0 ? '' : ' (cause)'}: ${level.name}: ${level.message}`);
+        if (level.stack !== undefined)
+            lines.push('  stack:', indentBlock(level.stack));
+    });
+    if (componentStack !== undefined)
+        lines.push('componentStack:', indentBlock(componentStack));
+    if (digest !== undefined)
+        lines.push(`digest: ${digest}`);
+    let text = lines.join('\n');
+    if (text.length > MAX_TEXT_CHARS)
+        text = `${text.slice(0, MAX_TEXT_CHARS)}\n...(truncated)`;
+    return {
+        message: head.message,
+        ...(head.stack === undefined ? {} : { stack: head.stack }),
+        levels,
+        ...(componentStack === undefined ? {} : { componentStack }),
+        ...(digest === undefined ? {} : { digest }),
+        summary,
+        text,
+    };
+}
+/**
+ * Crash detail built from literals only, for when serializing or logging
+ * the real one failed. It never touches the thrown value, so it cannot throw.
+ */
+export function unserializableCrashDetail() {
+    const text = [
+        `dsh-tui crashed: ${UNSERIALIZABLE}`,
+        `level 0: Error: ${UNSERIALIZABLE}`,
+        '(crash detail serialization failed; every property of the thrown value was left unread)',
+    ].join('\n');
+    return {
+        message: UNSERIALIZABLE,
+        levels: [{ name: 'Error', message: UNSERIALIZABLE }],
+        summary: `Error: ${UNSERIALIZABLE}`,
+        text,
+    };
+}
+/**
+ * The crash.log line: restart.log's `<UTC ISO> pid=<pid>` header style
+ * (writeRestartLine precedent, src/update.ts) followed by the detail block.
+ * @param detail - Serialized crash (serializeCrashDetail).
+ * @param at - Timestamp of the crash (injected so the format stays testable).
+ * @param pid - Process id (injected so the format stays testable).
+ */
+export function formatCrashLogLine(detail, at, pid) {
+    return `${at.toISOString()} pid=${pid} ${detail.text}\n`;
+}
+/**
+ * Append the crash detail to `<dir>/crash.log` (default `~/.dsh-tui`,
+ * DATA_DIR — same home-dir resolution as restart.log, never a hard-coded
+ * path). Every failure is swallowed: post-mortem diagnostics must never take
+ * the exit path down (mouse-debug.log precedent).
+ * @param detail - Serialized crash (serializeCrashDetail).
+ * @param dir - Data directory override (verify scripts point at a temp dir).
+ */
+export function appendCrashLog(detail, dir = DATA_DIR) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        // 0600 on creation: the stack can mirror message content (mouse-debug.log
+        // and history.jsonl precedent, see scripts/verify-data-file-perms).
+        appendFileSync(join(dir, 'crash.log'), formatCrashLogLine(detail, new Date(), process.pid), { mode: 0o600 });
+    }
+    catch {
+        // Post-mortem only — see doc comment.
+    }
+}

package/lib/types/utils/imageResize.d.ts

@@ -1,30 +1,16 @@
-/**
- * Inbound image adaptation for the composer's staging gate.
- *
- * The upstream attachment store admits images by media type, byte budget,
- * pixel budget and a per-side dimension cap (`maxImageDimension`). Two kinds
- * of paste used to fail with no user-side recourse: one that exceeds the
- * dimension cap, and one whose format the deployment does not accept. This
- * module measures the bytes BEFORE staging and produces an admissible pair
- * (bytes + media type) through sharp — an optionalDependency, absent on
- * minimal installs, which must degrade with a clear error, not a crash.
- *
- * Sizing probe is pure byte inspection (PNG/JPEG/WebP/GIF). Formats the
- * probe cannot identify return null and MUST be forced through an actual
- * decode for measurement — the #432 review gap was letting an
- * "unrecognized but under the byte cap" image through, where a
- * large-resolution small-byte WebP/GIF would sail past the probe and be
- * rejected by upstream afterwards.
- *
- * The single entry point is {@link adaptImageForAdmission}: it decides
- * whether anything has to change (resample, re-encode, or both) and reports
- * exactly what it did, so the caller can tell the user instead of silently
- * rewriting their image.
- */
 export interface ImageSizeProbe {
     readonly width: number;
     readonly height: number;
 }
+/**
+ * The image media type the encoded bytes actually are, from the magic
+ * bytes alone (the same signatures {@link probeImageSize} dispatches on):
+ * PNG, JPEG, WebP (RIFF/WEBP) or GIF; anything else is undefined and the
+ * caller keeps its own label (those bytes take the decode-or-refuse path
+ * anyway). Used to keep a renamed file from travelling under a label its
+ * content contradicts.
+ */
+export declare function sniffImageMediaType(bytes: Uint8Array): 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif' | undefined;
 /**
  * Measure intrinsic pixel dimensions from the encoded bytes alone — no
  * decode, no dependencies. Recognizes PNG / JPEG / WebP (VP8X, VP8,

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

@@ -1 +1 @@
-{"version":3,"file":"imageResize.d.ts","sourceRoot":"","sources":["../../../src/utils/imageResize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAiFD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,GAAG,IAAI,CAevE;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,wCAAwC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAIzF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,GAAG,cAAc,CAW1F;AAqCD,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IACA,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B,GACC;IACA;;;qDAGiD;IACjD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,GAAG,sBAAsB,CAAA;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA;AAgCH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,YAAY,EACpB,kBAAkB,EAAE,SAAS,MAAM,EAAE,GACpC,OAAO,CAAC,YAAY,CAAC,CAqDvB"}
+{"version":3,"file":"imageResize.d.ts","sourceRoot":"","sources":["../../../src/utils/imageResize.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAiFD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,WAAW,GAAG,SAAS,CAO1H;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,cAAc,GAAG,IAAI,CAevE;AAED,iEAAiE;AACjE,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,wCAAwC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;CAChC;AAED,2EAA2E;AAC3E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAIzF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,GAAG,cAAc,CAW1F;AAqCD,MAAM,MAAM,YAAY,GACpB;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IACA,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B,GACC;IACA;;;qDAGiD;IACjD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,GAAG,sBAAsB,CAAA;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA;AAcH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,YAAY,EACpB,kBAAkB,EAAE,SAAS,MAAM,EAAE,GACpC,OAAO,CAAC,YAAY,CAAC,CAuDvB"}