@deepseek-harness-tui/dsh-tui 0.9.0 → 0.9.2

package/lib/types/update.js

@@ -1,10 +1,11 @@
 import { spawn } from 'node:child_process';
-import { readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { appendFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 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';
 // Re-exported for scripts/verify-update.mjs and the bin launcher, which reads
 // the compiled copy at lib/types/utils/shellQuote.js.
 export { shellQuote };
@@ -13,6 +14,72 @@ const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
 const UPDATE_CHECK_TIMEOUT_MS = 4000;
 /** env marker set on the /update restart; the new process verifies it at boot. */
 const UPDATED_FROM_ENV = 'DSH_TUI_UPDATED_FROM';
+/**
+ * env marker set on the /restart replacement: its boot logs to restart.log
+ * (ordinary launches stay silent, so the file is restart-only evidence).
+ */
+const RESTART_CHILD_ENV = 'DSH_TUI_RESTART_CHILD';
+/**
+ * Field-diagnosis log for the /restart terminal handoff, appended by BOTH
+ * processes: the exiting TUI logs the funnel path, the spawned replacement
+ * logs its boot progress, and every line carries pid + timestamp — so a
+ * handoff that dies at any stage (loader entry, TTY gate, session resume,
+ * even after the parent's survival window) leaves breadcrumbs on disk even
+ * when nothing reaches the already-confused terminal. Diagnosis only: every
+ * write is best effort and must never break the handoff itself.
+ */
+const RESTART_LOG = join(DATA_DIR, 'restart.log');
+/** Cap so a long debugging streak cannot grow the log unbounded. */
+const RESTART_LOG_MAX_BYTES = 256 * 1024;
+function writeRestartLine(line) {
+    try {
+        mkdirSync(DATA_DIR, { recursive: true });
+        appendFileSync(RESTART_LOG, `${new Date().toISOString()} pid=${process.pid} ${line}\n`);
+    }
+    catch {
+        // Diagnosis only.
+    }
+}
+/**
+ * Append a /restart handoff event to ~/.dsh-tui/restart.log.
+ * @param event - Short stable event name.
+ * @param data - Small JSON-safe detail (never credentials or session text).
+ */
+export function logRestartEvent(event, data) {
+    writeRestartLine(`${event}${data === undefined ? '' : ` ${JSON.stringify(data)}`}`);
+}
+/** Start a fresh, clearly delimited /restart attempt block in the log. */
+export function beginRestartAttempt(sessionId) {
+    try {
+        mkdirSync(DATA_DIR, { recursive: true });
+        let size = 0;
+        try {
+            size = statSync(RESTART_LOG).size;
+        }
+        catch {
+            size = 0;
+        }
+        if (size > RESTART_LOG_MAX_BYTES)
+            writeFileSync(RESTART_LOG, '');
+    }
+    catch {
+        // Diagnosis only.
+    }
+    writeRestartLine(`--- /restart attempt session=${sessionId} ---`);
+}
+/**
+ * Write a handoff notice to stderr synchronously: process.exit() right after
+ * an async stream write skips the flush, and a vanished diagnosis is
+ * indistinguishable from a silent failure.
+ */
+export function writeHandoffNotice(text) {
+    try {
+        writeFileSync(2, text);
+    }
+    catch {
+        process.stderr.write(text);
+    }
+}
 /** Read the version from either the compiled package or the source checkout. */
 export function installedTuiVersion() {
     const here = dirname(fileURLToPath(import.meta.url));
@@ -212,6 +279,111 @@ export function tuiUpdatePluginArgs(profile, targetVersion) {
         ? ['plugin', '--profile', profile, 'update', '--latest', PACKAGE_NAME]
         : ['plugin', '--profile', profile, 'update', `${PACKAGE_NAME}@${targetVersion}`];
 }
+/**
+ * Postinstall-only transitive dependencies of the dsh-tui chain
+ * (dsh-auth → @earendil-works/pi-ai → @google/genai + protobufjs, plus the
+ * esbuild/koffi peers of that chain): pnpm ≥11 refuses to run their build
+ * scripts unless the workspace allowlists them, and a profile that never
+ * opted in fails the WHOLE install with ERR_PNPM_IGNORED_BUILDS. None of
+ * these scripts is needed at runtime (the repo root allowBuilds them all to
+ * `false`), so the update flow pre-seeds the profile's pnpm-workspace.yaml
+ * with explicit `false` entries — an explicit decision pnpm honors silently.
+ */
+const PROFILE_ALLOW_BUILDS = {
+    '@google/genai': false,
+    esbuild: false,
+    koffi: false,
+    protobufjs: false,
+};
+/** The profile's pnpm-workspace.yaml (`$DSH_HOME ?? ~/.dsh` layout). */
+export function profileWorkspaceYamlPath(profile) {
+    const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(dshHome, 'profiles', profile, 'pnpm-workspace.yaml');
+}
+/** YAML key spelling for an allowBuilds entry (scoped names need quotes). */
+function allowBuildsKeyLine(key) {
+    const needsQuotes = key.includes('@') || key.includes('/');
+    return `  ${needsQuotes ? `'${key}'` : key}: false`;
+}
+/**
+ * Make sure the profile's pnpm-workspace.yaml carries explicit `false`
+ * allowBuilds entries for the dsh-tui chain's postinstall-only deps, so a
+ * pnpm ≥11 update is not killed by ERR_PNPM_IGNORED_BUILDS. Best effort and
+ * idempotent: existing entries are never overwritten (an explicit user
+ * decision wins), a missing `allowBuilds:` block is appended, and a missing
+ * file is created. Returns undefined when the profile directory is absent or
+ * the file could not be updated — the caller still runs pnpm, whose own
+ * ERR_PNPM_IGNORED_BUILDS diagnostic stays the visible fallback.
+ */
+export function ensureProfileAllowBuilds(profile) {
+    const yamlPath = profileWorkspaceYamlPath(profile);
+    try {
+        if (!existsSafe(dirname(yamlPath)))
+            return undefined;
+        let text = '';
+        try {
+            text = readFileSync(yamlPath, 'utf8');
+        }
+        catch {
+            // Missing file — start from an empty document; writeFileSync creates it.
+        }
+        const lines = text.split(/\r?\n/u);
+        let blockStart = -1;
+        for (let i = 0; i < lines.length; i += 1) {
+            const line = lines[i];
+            if (line !== '' && line === line.trimStart() && /^allowBuilds:/u.test(line)) {
+                blockStart = i;
+                break;
+            }
+        }
+        const present = new Set();
+        if (blockStart !== -1) {
+            for (let i = blockStart + 1; i < lines.length; i += 1) {
+                const line = lines[i];
+                if (line === '' || line === line.trimStart())
+                    break; // dedent = block ends
+                const keyMatch = /^\s+('?)(.+?)\1:\s/u.exec(line);
+                if (keyMatch !== null)
+                    present.add(keyMatch[2]);
+            }
+        }
+        const added = Object.keys(PROFILE_ALLOW_BUILDS).filter(key => !present.has(key));
+        if (added.length === 0)
+            return { existing: [...present], added };
+        const insert = added.map(allowBuildsKeyLine);
+        if (blockStart !== -1) {
+            // Append after the block's last existing entry (before the next
+            // top-level key), so existing entries keep their position.
+            let blockEnd = blockStart + 1;
+            for (let i = blockStart + 1; i < lines.length; i += 1) {
+                const line = lines[i];
+                if (line === '' || line === line.trimStart())
+                    break;
+                blockEnd = i + 1;
+            }
+            lines.splice(blockEnd, 0, ...insert);
+        }
+        else {
+            if (lines.length > 0 && lines[lines.length - 1] !== '')
+                lines.push('');
+            lines.push('allowBuilds:', ...insert);
+        }
+        writeFileSync(yamlPath, `${lines.join('\n')}\n`);
+        return { existing: [...present], added };
+    }
+    catch {
+        return undefined;
+    }
+}
+function existsSafe(path) {
+    try {
+        statSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * The pnpm Windows tmp-rename race signature (issue #225): pnpm swaps a
  * package directory via a `<name>_tmp_<pid>` staging dir, and a file lock or
@@ -225,6 +397,79 @@ export function tuiUpdatePluginArgs(profile, targetVersion) {
 export function isTransientUpdateFailure(stderr) {
     return /ENOENT|EPERM|EBUSY/i.test(stderr) && /_tmp_\d+/i.test(stderr);
 }
+/**
+ * The pnpm Linux flavor of the tmp-rename race (issue #479): the very same
+ * `importPackage` staging path, but overlayfs surfaces the second swap of an
+ * already-replaced package dir as EEXIST — deterministically, on every run,
+ * never transiently. A plain retry of the identical command ALWAYS fails the
+ * same way (the leftover `_tmp_<pid>_<threadId>` staging dir keeps colliding),
+ * so this signature must route to the recovery path
+ * (removeStalePackageInstall + rerun), not to the plain retry.
+ */
+export function isEexistTmpRenameFailure(stderr) {
+    return /EEXIST/i.test(stderr) && /_tmp_\d+/i.test(stderr);
+}
+/**
+ * The dsh profile layout places plugin packages under
+ * `$DSH_HOME ?? ~/.dsh` — the same root dsh itself resolves
+ * (`dshHomePath is $DSH_HOME ?? ~/.dsh`, and packaged presets resolve
+ * identically). /update's recovery path needs this location to clear a
+ * half-updated install pnpm can no longer swap in place (issue #479).
+ */
+export function profilePackageDir(profile) {
+    const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(dshHome, 'profiles', profile, 'node_modules', PACKAGE_NAME);
+}
+/**
+ * Recovery for the pnpm tmp-rename races (issues #225/#479): remove the
+ * profile's installed copy of this package plus the sibling `_tmp_`
+ * staging dirs a crashed swap leaves behind, so the next installer run
+ * takes the fresh-install path instead of renaming over the collision.
+ * Field-verified workaround (issue #479): `rm -rf <pkg dir>` + rerun
+ * succeeds where ten plain retries fail.
+ *
+ * A junction/symlink at the package dir is UNLINKED only — the link is
+ * removed, the target tree (a dev checkout it may point at) is never
+ * traversed or deleted. Best effort throughout: this runs inside a
+ * failure-recovery branch, so an unusable result simply falls through to
+ * the rerun and the manual repair hint.
+ */
+export function removeStalePackageInstall(profile) {
+    const pkgDir = profilePackageDir(profile);
+    const scopeDir = dirname(pkgDir);
+    const removal = { packageDir: 'absent', tmpDirs: [] };
+    try {
+        const stats = lstatSync(pkgDir);
+        // lstat reports junctions AND symlinks as isSymbolicLink — remove the
+        // link itself, never what it points at.
+        if (stats.isSymbolicLink() || stats.isDirectory()) {
+            rmSync(pkgDir, { recursive: true, force: true });
+            removal.packageDir = 'removed';
+        }
+    }
+    catch (error) {
+        removal.packageDir = error.code === 'ENOENT' ? 'absent' : 'failed';
+    }
+    try {
+        for (const name of readdirSync(scopeDir)) {
+            if (!/^dsh-tui_tmp_\d+_\d+$/.test(name))
+                continue;
+            const staging = join(scopeDir, name);
+            try {
+                rmSync(staging, { recursive: true, force: true });
+                removal.tmpDirs.push(name);
+            }
+            catch {
+                // Staging leftovers are best effort; the package dir removal is
+                // the load-bearing half of the recovery.
+            }
+        }
+    }
+    catch {
+        // Unreadable scope dir — nothing more to clear.
+    }
+    return removal;
+}
 /**
  * Best-effort migrate the GLOBAL launcher to the delegating shim (0.8.7):
  * after a successful profile update, copy this package's `bin/dsh-tui.js`
@@ -290,24 +535,17 @@ export function migrateGlobalLauncher() {
     return false;
 }
 /**
- * Update the installed dsh-tui package and restart the same launcher while
- * preserving the active session. The TUI must already be unmounted before
- * this is called so pnpm output cannot corrupt the rendered terminal frame.
+ * Install-only half of `/update`: run `dsh plugin add`, refuse boot-deadlock
+ * targets, verify the profile actually advanced, and migrate the global
+ * launcher. No restart — `updateTuiAndRestart` layers the session-preserving
+ * restart on top, and the `dsh-tui update` CLI stops here.
  *
- * When the preflight registry check resolved an exact target, pass that
- * version to pnpm instead of resolving `latest` a second time. This avoids a
- * stale mirror/dist-tag response between the check and install. If preflight
- * failed, retain the `--latest` fallback: a plain `pnpm update` stays inside
- * the manifest range and can restart unchanged across minor releases.
- *
- * @param sessionId - Session to resume in the replacement process.
- * @param profile - The dsh profile this TUI was launched with; updating any
- *   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.
- * @returns Exit codes for the update run and the replacement process.
+ * @param profile - The dsh profile to update.
+ * @param targetVersion - Exact version from the preflight registry check, or
+ *   undefined when that check failed and pnpm should resolve latest.
+ * @returns The update exit code plus the before/after versions.
  */
-export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
+export async function updateTui(profile, targetVersion) {
     // Stamp the pre-update version BEFORE pnpm runs: it reads this package's
     // manifest from disk, which the update replaces on the fly — a
     // post-update read already sees the NEW version, and the restarted
@@ -316,6 +554,15 @@ export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
     const updatedFrom = installedTuiVersion() ?? '';
     const dsh = process.platform === 'win32' ? 'dsh.cmd' : 'dsh';
     const updateArgs = tuiUpdatePluginArgs(profile, targetVersion);
+    // pnpm ≥11 hard-fails installs whose dependency tree carries un-allowlisted
+    // build scripts (ERR_PNPM_IGNORED_BUILDS). The dsh-auth chain pulls in
+    // postinstall-only deps (@google/genai/protobufjs via pi-ai), so pre-seed
+    // the profile workspace with explicit `false` entries before pnpm runs.
+    const allowBuilds = ensureProfileAllowBuilds(profile);
+    if (allowBuilds !== undefined && allowBuilds.added.length > 0) {
+        process.stderr.write(`dsh-tui: pre-seeded profile pnpm allowBuilds (${allowBuilds.added.join(', ')}) — ` +
+            'postinstall-only deps are explicitly ignored\n');
+    }
     let updateStderr = '';
     const capture = (chunk) => { updateStderr += chunk; };
     let updateCode = await runProcess(dsh, updateArgs, { shell: true, onStderr: capture });
@@ -327,8 +574,23 @@ export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
         updateStderr = '';
         updateCode = await runProcess(dsh, updateArgs, { shell: true, onStderr: capture });
     }
+    // Deterministic Linux tmp-rename race (issue #479): EEXIST never clears on
+    // a plain retry (the staging-dir collision reproduces every run), and a
+    // transient retry that failed again means the same leftover state. Both
+    // recover by removing the stale install + staging dirs, then rerunning —
+    // the field-verified workaround that takes pnpm down its fresh-install
+    // path instead of renaming over the collision.
+    if (updateCode !== 0 && (isEexistTmpRenameFailure(updateStderr) || isTransientUpdateFailure(updateStderr))) {
+        const flavor = isEexistTmpRenameFailure(updateStderr) ? 'EEXIST, issue #479' : 'retry failed, issue #225';
+        const removal = removeStalePackageInstall(profile);
+        const stagingNote = removal.tmpDirs.length > 0 ? ` + ${removal.tmpDirs.length} staging dir(s)` : '';
+        process.stderr.write(`dsh-tui: pnpm tmp-rename race (${flavor}) — cleared the stale install ` +
+            `(package dir: ${removal.packageDir}${stagingNote}) and rerunning the update…\n`);
+        updateStderr = '';
+        updateCode = await runProcess(dsh, updateArgs, { shell: true, onStderr: capture });
+    }
     if (updateCode !== 0)
-        return { updateCode, restartCode: updateCode };
+        return { code: updateCode, updatedFrom };
     // A --latest fallback (preflight failed) on a stale mirror can still land
     // on the 0.7.0–0.7.1 hard-inject range — restarting into it under an older
     // global-launcher patch is the permanent boot deadlock of issues
@@ -341,7 +603,7 @@ export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
             `(#183/#307) — NOT restarting into it. Repair with:\n` +
             `  dsh plugin --profile ${profile} add ${PACKAGE_NAME}@latest\n` +
             `(if the mirror has not synced the latest release yet, retry later)\n`);
-        return { updateCode: 1, restartCode: 1 };
+        return { code: 1, updatedFrom, installed: installedNow };
     }
     // Post-update verification (issue #225): pnpm can report success yet leave
     // the profile half-updated (manifest old / lockfile new). Verify against
@@ -358,7 +620,7 @@ export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
             process.stderr.write(`dsh-tui: update completed but the profile still runs ${installed ?? 'an unreadable version'} ` +
                 `(expected ${targetVersion}) — the profile is half-updated. Repair manually with:\n` +
                 `  dsh plugin --profile ${profile} add ${PACKAGE_NAME}@${targetVersion}\n`);
-            return { updateCode: 1, restartCode: 1 };
+            return { code: 1, updatedFrom, installed };
         }
     }
     // Launcher migration (0.8.7): the freshly installed profile carries the
@@ -368,15 +630,219 @@ export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
     if (migrateGlobalLauncher()) {
         process.stderr.write('dsh-tui: global launcher aligned to the delegating shim (no manual npm i -g needed anymore).\n');
     }
-    const restartCode = await runProcess(process.execPath, [...process.execArgv, ...process.argv.slice(1)], {
-        env: {
-            ...process.env,
-            // Dual-write the resume contract (issue #120): the cordis layer of a
-            // still-old TUI build reads only DSH_CC_RESUME_SESSION.
-            DSH_TUI_RESUME_SESSION: sessionId,
-            DSH_CC_RESUME_SESSION: sessionId,
-            [UPDATED_FROM_ENV]: updatedFrom,
-        },
+    return { code: 0, updatedFrom, installed: installedTuiVersion() };
+}
+/**
+ * Update the installed dsh-tui package and restart the same launcher while
+ * preserving the active session. The TUI must already be unmounted before
+ * this is called so pnpm output cannot corrupt the rendered terminal frame.
+ *
+ * When the preflight registry check resolved an exact target, pass that
+ * version to pnpm instead of resolving `latest` a second time. This avoids a
+ * stale mirror/dist-tag response between the check and install. If preflight
+ * failed, retain the `--latest` fallback: a plain `pnpm update` stays inside
+ * the manifest range and can restart unchanged across minor releases.
+ *
+ * @param sessionId - Session to resume in the replacement process.
+ * @param profile - The dsh profile this TUI was launched with; updating any
+ *   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.
+ * @returns Exit codes for the update run and the replacement process.
+ */
+export async function updateTuiAndRestart(sessionId, profile, targetVersion) {
+    const outcome = await updateTui(profile, targetVersion);
+    const { updatedFrom } = outcome;
+    if (outcome.code !== 0)
+        return { updateCode: outcome.code, restartCode: outcome.code };
+    // Restart through the same hardened handoff as /restart (issues
+    // #284/#307/#483): wait for the replacement's natural exit (the outer
+    // interpreter must not reclaim the console under it), re-assert the
+    // stdin detach from a watchdog so a revived pump cannot swallow the
+    // child's keypresses, and capture a fast-death stderr report. The old
+    // plain inherit spawn raced the interpreter for input on Windows
+    // Terminal (issue #483: "cannot type anything after /update").
+    const restartCode = await restartTui(sessionId, {
+        env: { [UPDATED_FROM_ENV]: updatedFrom },
+        kind: 'update',
+    });
+    return { updateCode: 0, restartCode };
+}
+/**
+ * Headless `dsh-tui update`: the `/update` decision flow (preflight, deadlock
+ * refusal, mirror-lag note, `--latest` fallback) followed by the install-only
+ * half — no TUI, no restart. The bin launcher dynamic-imports this from the
+ * profile copy's compiled lib.
+ *
+ * @param profile - The dsh profile to update.
+ * @returns Process exit code: 0 on success or already-latest, 1 otherwise.
+ */
+export async function cliUpdate(profile) {
+    const target = await resolveTuiUpdateTarget();
+    if (target.kind === 'latest') {
+        process.stdout.write(`dsh-tui: already the latest version (${target.current}).\n`);
+        return 0;
+    }
+    let targetVersion;
+    if (target.kind === 'update') {
+        // Mirror the /update flow exactly: refuse the 0.7.0–0.7.1 hard-inject
+        // range (permanent boot deadlock under older launcher patches, #183/#307)
+        // instead of installing it.
+        if (isBootDeadlockTarget(target.latest)) {
+            process.stderr.write(`dsh-tui: refusing to update onto ${target.latest} — that range can permanently deadlock boot ` +
+                `(#183/#307). Latest on the official registry: ${target.authoritative ?? target.latest}. ` +
+                `If you use a mirror, retry after it syncs.\n`);
+            return 1;
+        }
+        if (target.authoritative !== undefined) {
+            process.stdout.write(`dsh-tui: note — your registry serves ${target.latest} while npmjs.org has ${target.authoritative} (mirror lag).\n`);
+        }
+        targetVersion = target.latest;
+        process.stdout.write(`dsh-tui: updating ${target.current} → ${target.latest}…\n`);
+    }
+    else {
+        process.stdout.write('dsh-tui: version check failed (offline or unreadable install) — falling back to `--latest`.\n');
+    }
+    const outcome = await updateTui(profile, targetVersion);
+    if (outcome.code === 0) {
+        // A preflight-less run (`--latest` fallback) can "succeed" as a pnpm
+        // no-op: same manifest before and after. Say so instead of printing a
+        // vacuous `updated X → X` — the /update path surfaces the same state via
+        // the DSH_TUI_UPDATED_FROM stamp on restart.
+        if (targetVersion === undefined && outcome.installed !== undefined && outcome.installed === outcome.updatedFrom) {
+            process.stdout.write(`dsh-tui: version did not advance (still ${outcome.installed}) — already the latest, or the registry has no newer release yet.\n`);
+        }
+        else {
+            process.stdout.write(`dsh-tui: updated ${outcome.updatedFrom || '(unknown)'} → ${outcome.installed ?? '(unreadable)'}.\n`);
+        }
+    }
+    return outcome.code;
+}
+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)];
+    logRestartEvent(`${tag}: spawning replacement`, {
+        node: process.execPath,
+        argv,
+        cwd: process.cwd(),
+        stdinTty: process.stdin.isTTY === true,
+        stdoutTty: process.stdout.isTTY === true,
+        stderrTty: process.stderr.isTTY === true,
+        nodeOptions: process.env.NODE_OPTIONS ?? null,
+        dshHome: process.env.DSH_HOME ?? null,
+    });
+    const startedAt = Date.now();
+    return new Promise(resolve => {
+        const child = spawn(process.execPath, argv, {
+            env: {
+                ...process.env,
+                // Dual-write the resume contract (issue #120): the cordis layer of a
+                // still-old TUI build reads only DSH_CC_RESUME_SESSION.
+                DSH_TUI_RESUME_SESSION: sessionId,
+                DSH_CC_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,
+            },
+            // 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'],
+        });
+        logRestartEvent(`${tag}: replacement spawned`, { childPid: child.pid });
+        // 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).
+        let watchdogTicks = 0;
+        const watchdog = setInterval(() => {
+            watchdogTicks += 1;
+            const stdin = process.stdin;
+            logRestartEvent('parent: stdin watchdog', {
+                tick: watchdogTicks,
+                readableListeners: stdin.listenerCount('readable'),
+                dataListeners: stdin.listenerCount('data'),
+                paused: stdin.isPaused,
+                raw: stdin.isRaw === true,
+                buffered: stdin.readableLength,
+            });
+            try {
+                stdin.removeAllListeners('readable');
+                stdin.removeAllListeners('data');
+                stdin.pause();
+            }
+            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.
+                }
+            }
+        }, 1000);
+        watchdog.unref();
+        let childStderr = '';
+        let loggedStderrBytes = 0;
+        child.stderr?.on('data', (chunk) => {
+            childStderr += chunk.toString('utf8');
+            // Mirror chunks to the log capped: the full text still reaches the
+            // terminal report below, and unbounded output must not grow the file.
+            if (loggedStderrBytes < 4096) {
+                loggedStderrBytes += chunk.length;
+                logRestartEvent(`${tag}: replacement stderr`, { text: chunk.toString('utf8').slice(0, 2048) });
+            }
+        });
+        // Diagnosis marker only — never resolves: after the window the child owns
+        // the terminal, and this process must keep the launch chain open until
+        // the replacement exits (see the header comment).
+        const timer = setTimeout(() => {
+            logRestartEvent(`${tag}: survival window passed, following the replacement until it exits`);
+        }, 4000);
+        timer.unref();
+        child.once('error', error => {
+            clearTimeout(timer);
+            logRestartEvent(`${tag}: spawn error`, { message: error.message });
+            writeHandoffNotice(`dsh-tui: failed to spawn the restart: ${error.message}\n`);
+            resolve(127);
+        });
+        child.once('close', (code, signal) => {
+            clearTimeout(timer);
+            const elapsedMs = Date.now() - startedAt;
+            logRestartEvent(`${tag}: replacement exited`, {
+                code: code ?? null,
+                signal: signal ?? null,
+                elapsedMs,
+            });
+            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.
+                const suffix = childStderr.trim() === '' ? '' : `\n${childStderr.trimEnd()}`;
+                writeHandoffNotice(`dsh-tui: restart child exited during the handoff (code ${code ?? 'null'}` +
+                    `${signal === undefined || signal === null ? '' : `, signal ${signal}`}) — the TUI did not come up.` +
+                    `${suffix}\nYour session is preserved; resume with the launcher or retry the command.\n`);
+            }
+            else if (code !== 0 && code !== null) {
+                // Late nonzero exit: the session ended abnormally, say so briefly.
+                writeHandoffNotice(`\ndsh-tui: the restarted session exited with code ${code}.\n`);
+            }
+            resolve(code ?? 1);
+        });
     });
-    return { updateCode, restartCode };
 }

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

@@ -6,7 +6,7 @@
  */
 export declare function logForDebugging(message: string, fields?: Record<string, unknown>): void;
 /**
- * Mouse-chain diagnostics: appends to `~/.dsh-cc/mouse-debug.log` when
+ * Mouse-chain diagnostics: appends to `~/.dsh-tui/mouse-debug.log` when
  * `DSH_TUI_DEBUG_MOUSE` is set. Unlike logForDebugging (stderr), a file
  * keeps the fullscreen alt screen unpolluted and survives the session for
  * post-mortem reading. Every append is try/catch-guarded — diagnostics

package/lib/types/utils/debug.js

@@ -1,5 +1,5 @@
 import { appendFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { DATA_DIR } from './paths.js';
 import { join } from 'node:path';
 /**
  * Debug logger for the ported Ink core. Writes to stderr only when
@@ -14,7 +14,7 @@ export function logForDebugging(message, fields) {
     process.stderr.write(`[dsh-tui] ${message}${suffix}\n`);
 }
 /**
- * Mouse-chain diagnostics: appends to `~/.dsh-cc/mouse-debug.log` when
+ * Mouse-chain diagnostics: appends to `~/.dsh-tui/mouse-debug.log` when
  * `DSH_TUI_DEBUG_MOUSE` is set. Unlike logForDebugging (stderr), a file
  * keeps the fullscreen alt screen unpolluted and survives the session for
  * post-mortem reading. Every append is try/catch-guarded — diagnostics
@@ -28,7 +28,7 @@ export function logMouseDebug(message, fields) {
     const suffix = fields === undefined ? '' : ` ${JSON.stringify(fields)}`;
     try {
         const line = `${new Date().toISOString()} ${message}${suffix}\n`;
-        appendFileSync(join(homedir(), '.dsh-cc', 'mouse-debug.log'), line);
+        appendFileSync(join(DATA_DIR, 'mouse-debug.log'), line);
     }
     catch {
         // ignore — see doc comment