termdock 1.4.321 → 1.4.324

package/dist/server/routes/terminal.js

@@ -1,3 +1,5 @@
+import { copyTmuxSelection } from '../utils/tmuxCopySelection.js';
+import { isConfirmedEmptyTmuxServer } from '../utils/tmuxEmptyServerProbe.js';
 import { collaborationSessionDisplayName } from '../utils/sessionDisplayName.js';
 import { integrationError } from '../agent/integrationStore.js';
 import { assertNativeResumeAvailable, collectNativeResumeOwnerCandidates } from '../agent/nativeResumeOwner.js';
@@ -14,6 +16,7 @@ import { ensureNodePty } from '../utils/ensureNodePty.js';
 import { PtySpawnBackoff, PtySpawnDeferredError } from '../utils/ptySpawnBackoff.js';
 import { collaborationGroupRoutes } from '../agent/collaborationGroupRoutes.js';
 import { TerminalClientAttachment } from '../utils/terminalClientAttachment.js';
+import { TerminalPasteBuffer } from '../utils/terminalPasteBuffer.js';
 import { SharedSessionSampler, SharedSnapshotCache } from '../utils/sharedSampling.js';
 import { batchTmuxOptions, TmuxMetadataWriter } from '../utils/tmuxMetadataWriter.js';
 import { redrawTmuxClient } from '../utils/tmuxClientRedraw.js';
@@ -51,7 +54,8 @@ import { archiveTaskWorkspace, restoreTaskWorkspace, snapshotTaskWorkspace } fro
 import { isTmuxRecoveryCandidate } from '../utils/tmuxRecoveryCandidate.js';
 import { AutomationStore, normalizeAutomationSchedule } from '../agent/automationStore.js';
 import { writeBracketedPrompt, canDeliverPromptToAgent } from '../agent/promptDelivery.js';
-import { captureTerminalInputGuard, waitAndWriteTerminalInput, TerminalInputTargetChangedError } from '../agent/terminalInput.js';
+import { captureTerminalInputGuard, captureRuntimeInputGuard, waitAndWriteTerminalInput } from '../agent/terminalInput.js';
+import { mergeSessionLaunchState } from '../agent/sessionLaunchState.js';
 import { agentLaunchBlockReason, normalizeAgentLaunchCheck } from '../agent/agentLaunchCheck.js';
 import { prepareSupervisionEnable } from '../utils/enableSupervision.js';
 import { buildServerHealthState, dismissServerHealth } from '../utils/serverHealth.js';
@@ -1082,8 +1086,9 @@ async function withInventoryOpenLock(key, task) {
     inventoryOpenLocks.set(key, pending);
     return pending;
 }
-function upsertGlobalSessionRecord(record) {
-    const normalized = normalizePersistedClientSession(record);
+function upsertGlobalSessionRecord(record, launchChange) {
+    const current = globalSessionState.sessions.find(candidate => candidate.sessionId === record.sessionId);
+    const normalized = normalizePersistedClientSession(mergeSessionLaunchState(record, current, launchChange));
     if (!normalized) {
         throw new Error('invalid session record');
     }
@@ -1462,8 +1467,16 @@ async function beginAgentLaunchCheck(frontendSessionId, agentSlug, nativeSession
     if (!record)
         throw new Error('SESSION_REMOVED');
     const id = randomUUID();
-    upsertGlobalSessionRecord({ ...record, agentLaunchGeneration: id, agentLaunchCheck: { id, agentSlug, nativeSessionId, deadline: Date.now() + 120_000 } });
-    await persistGlobalStateNow();
+    const updated = upsertGlobalSessionRecord(record, { expectedGeneration: record.agentLaunchGeneration ?? null,
+        expectedCheckId: record.agentLaunchCheck?.id ?? null, generation: id,
+        check: { id, agentSlug, nativeSessionId, deadline: Date.now() + 120_000 } });
+    // Capture the guard before persistence yields. The launch command must use
+    // this exact generation, even if another launch occurs during an await.
+    const assertCurrent = terminalInputGuard(updated);
+    assertCurrent('guard_capture');
+    await persistGlobalStateNow(true);
+    assertCurrent('launch_persisted');
+    return assertCurrent;
 }
 async function observeAgentLaunchCheck(record, observed) {
     const check = record.agentLaunchCheck;
@@ -1477,53 +1490,56 @@ async function observeAgentLaunchCheck(record, observed) {
         return { state: 'offline', reason: 'SESSION_REMOVED' };
     if (latest.agentLaunchCheck?.id !== check.id)
         return { state: 'recovering', reason: 'AGENT_LAUNCH_CHANGED' };
-    upsertGlobalSessionRecord({ ...latest, agentLaunchCheck: null });
+    upsertGlobalSessionRecord(latest, { expectedGeneration: latest.agentLaunchGeneration ?? null,
+        expectedCheckId: check.id, generation: latest.agentLaunchGeneration ?? null, check: null });
     await persistGlobalStateNow();
     return null;
 }
 function terminalInputGuard(record) {
     const frontendSessionId = record.sessionId;
     const backendSessionId = record.backendSessionId;
-    const launchId = record.agentLaunchGeneration ?? null;
-    const routeRevision = collaborationRouting.get(frontendSessionId)?.routeRevision ?? null;
-    const backend = backendSessionId ? terminalSessions.get(backendSessionId) : undefined;
-    return () => {
+    const expected = { backendSessionId, launchId: record.agentLaunchGeneration ?? null,
+        routeRevision: collaborationRouting.get(frontendSessionId)?.routeRevision ?? null,
+        backendInstance: backendSessionId ? terminalSessions.get(backendSessionId) : undefined };
+    return captureRuntimeInputGuard(() => {
         const latest = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
         if (!latest)
             throw new Error('SESSION_REMOVED');
-        const instanceMatches = !backendSessionId || terminalSessions.get(backendSessionId) === backend;
-        if ((collaborationRouting.get(frontendSessionId)?.routeRevision ?? null) !== routeRevision
-            || (latest.agentLaunchGeneration ?? null) !== launchId || latest.backendSessionId !== backendSessionId || !instanceMatches) {
-            throw new TerminalInputTargetChangedError({ expected_backend_session_id: backendSessionId, current_backend_session_id: latest.backendSessionId,
-                expected_launch_id: launchId, current_launch_id: latest.agentLaunchGeneration ?? null, backend_instance_matches: instanceMatches });
-        }
-    };
+        return { backendSessionId: latest.backendSessionId, launchId: latest.agentLaunchGeneration ?? null,
+            routeRevision: collaborationRouting.get(frontendSessionId)?.routeRevision ?? null,
+            backendInstance: latest.backendSessionId ? terminalSessions.get(latest.backendSessionId) : undefined };
+    }, expected);
 }
 /** tmux input always uses the pane queue, including automation and launch commands. */
 async function automaticTerminalInput(record, assertCurrent = terminalInputGuard(record), progress) {
-    assertCurrent();
+    progress?.('guard_captured');
+    assertCurrent('runtime_resolve');
+    progress?.('runtime_resolving');
     if (record.mode === 'tmux') {
         const binding = collaborationRouting.get(record.sessionId) ?? {
             sessionId: record.sessionId, backendSessionId: record.backendSessionId, mode: record.mode,
             tmuxSessionName: record.tmuxSessionName, agentSlug: null, nativeSessionId: null, pane: null,
         };
         const inspected = await inspectCollaborationTmux(binding, null, true);
-        assertCurrent();
+        assertCurrent('runtime_resolved');
         if (inspected.state !== 'ready' || !inspected.pane)
             throw new Error(inspected.reason ?? 'TMUX_PANE_UNAVAILABLE');
         const pane = inspected.pane;
+        progress?.('runtime_resolved');
         return (prompt) => writeCollaborationTmuxPane(runTmux, pane, prompt, runTmuxStdin, assertCurrent, progress);
     }
     const backend = record.backendSessionId ? terminalSessions.get(record.backendSessionId) : null;
     if (!backend)
         throw new Error('SHELL_BACKEND_NOT_RUNNING');
+    assertCurrent('runtime_resolved');
+    progress?.('runtime_resolved');
     return (prompt) => writeBracketedPrompt(backend.ptyProcess, prompt, assertCurrent, progress);
 }
-async function writeAutomaticTerminalPrompt(frontendSessionId, prompt, progress) {
+async function writeAutomaticTerminalPrompt(frontendSessionId, prompt, progress, launchGuard) {
     const record = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
     if (!record)
         throw new Error('SESSION_REMOVED');
-    const write = await automaticTerminalInput(record, terminalInputGuard(record), progress);
+    const write = await automaticTerminalInput(record, launchGuard ?? terminalInputGuard(record), progress);
     await write(prompt);
 }
 async function deliverAutomationPromptWhenReady(backendSessionId, prompt) {
@@ -1580,9 +1596,8 @@ async function runAgentAutomation(automation, req) {
                 throw new Error('自动任务会话创建失败');
             if (automation.command) {
                 const agent = detectAgentFromCommand(automation.command, agentCustomCommands());
-                if (agent)
-                    await beginAgentLaunchCheck(frontendSessionId, agent.slug);
-                await writeAutomaticTerminalPrompt(frontendSessionId, automation.command);
+                const launchGuard = agent ? await beginAgentLaunchCheck(frontendSessionId, agent.slug) : undefined;
+                await writeAutomaticTerminalPrompt(frontendSessionId, automation.command, undefined, launchGuard);
             }
             if (automation.prompt) {
                 if (automation.command)
@@ -1970,7 +1985,7 @@ async function spawnCollaborationAgentSession(req, group, sourceSessionId, input
     const backend = terminalSessions.get(opened.terminalSession.sessionId);
     if (!backend)
         throw new HttpStatusError(500, 'Agent Session 创建失败', 'COLLAB_AGENT_SESSION_FAILED');
-    await beginAgentLaunchCheck(frontendSessionId, launcher.slug);
+    const launchGuard = await beginAgentLaunchCheck(frontendSessionId, launcher.slug);
     const latestGroup = collaborationStore.getGroup(group.id);
     if (!latestGroup || latestGroup.deleted) {
         const created = globalSessionState.sessions.find(record => record.sessionId === frontendSessionId);
@@ -1993,7 +2008,7 @@ async function spawnCollaborationAgentSession(req, group, sourceSessionId, input
         collaborationStore.setRole({ groupId: group.id, sessionId: frontendSessionId, role: bootstrapRole, creationKey });
     if (profile)
         collaborationStore.setMemberLaunchProfile(group.id, frontendSessionId, profile);
-    await writeAutomaticTerminalPrompt(frontendSessionId, buildCollaborationSpawnCommand({ slug: launcher.slug, command: profile?.command ?? launcher.command }));
+    await writeAutomaticTerminalPrompt(frontendSessionId, buildCollaborationSpawnCommand({ slug: launcher.slug, command: profile?.command ?? launcher.command }), undefined, launchGuard);
     const requestedTask = typeof input.task === 'string' ? input.task.trim().slice(0, 20_000) : '';
     collaborationStore.send({
         groupId: updatedGroup.id,
@@ -2423,8 +2438,8 @@ async function launchIntegrationTerminal(record, restoring, prepared, progress,
         backend.agent = null;
         backend.agentResumeRecovered = false;
         progress?.('launch_intent');
-        await beginAgentLaunchCheck(record.session_id, record.agent_slug, restoring ? record.agent_native_session_id : null);
-        await writeAutomaticTerminalPrompt(record.session_id, integrationLaunchCommand(record, restoring), progress);
+        const launchGuard = await beginAgentLaunchCheck(record.session_id, record.agent_slug, restoring ? record.agent_native_session_id : null);
+        await writeAutomaticTerminalPrompt(record.session_id, integrationLaunchCommand(record, restoring), progress, launchGuard);
         broadcastClientState();
     });
 }
@@ -2471,12 +2486,12 @@ export function prepareCollaborationTaskWorker(task, template, dependencies, ser
                 throw error;
         }
         if (!currentAgent && (!launch || launch.backendId !== opened.terminalSession.sessionId)) {
-            await beginAgentLaunchCheck(record.sessionId, launcher.slug);
+            const launchGuard = await beginAgentLaunchCheck(record.sessionId, launcher.slug);
             // Persist before typing: a retry must never type the launcher into a newly booted Agent's prompt.
             const temporary = `${launchFile}.${process.pid}.tmp`;
             await fs.promises.writeFile(temporary, JSON.stringify({ sessionId: record.sessionId, backendId: opened.terminalSession.sessionId }), { mode: 0o600 });
             await fs.promises.rename(temporary, launchFile);
-            await writeAutomaticTerminalPrompt(opened.session.sessionId, buildCollaborationSpawnCommand({ slug: launcher.slug, command: inheritedProfile?.command ?? launcher.command }));
+            await writeAutomaticTerminalPrompt(opened.session.sessionId, buildCollaborationSpawnCommand({ slug: launcher.slug, command: inheritedProfile?.command ?? launcher.command }), undefined, launchGuard);
         }
         const group = collaborationStore.getGroup(task.groupId);
         if (!group || group.deleted)
@@ -2510,10 +2525,10 @@ function getTmuxBinary() {
     }
     return 'tmux'; // fallback to PATH
 }
-async function runTmux(args) {
+async function runTmux(args, options) {
     const { stdout } = await execFileAsync(getTmuxBinary(), args, {
         timeout: 5000,
-        maxBuffer: 2 * 1024 * 1024,
+        maxBuffer: options?.maxBuffer ?? 2 * 1024 * 1024,
         env: buildInteractiveColorEnvironment(process.env),
     });
     return stdout;
@@ -4672,19 +4687,26 @@ async function resolveTmuxClientTty(sessionName, preferredClientPid) {
 }
 async function ensureTmuxSessionExists(sessionName, cwd) {
     let serverWasMissing = false;
+    let serverIsEmpty = false;
+    let sessionExists = false;
     try {
         await runTmux(['has-session', '-t', sessionName]);
-        await ensureTmuxColorEnvironment(sessionName);
-        return;
+        sessionExists = true;
     }
     catch (error) {
         const errorMessage = getErrorMessage(error);
         serverWasMissing = isTmuxServerMissingMessage(errorMessage);
         if (!isTmuxSessionMissingMessage(errorMessage)) {
-            throw error;
+            serverIsEmpty = await isConfirmedEmptyTmuxServer(error, sessionName, runTmux);
+            if (!serverIsEmpty)
+                throw error;
         }
     }
-    if (!serverWasMissing) {
+    if (sessionExists) {
+        await ensureTmuxColorEnvironment(sessionName);
+        return;
+    }
+    if (!serverWasMissing && !serverIsEmpty) {
         await ensureTmuxColorEnvironment();
     }
     const innerTerm = await resolveTmuxInnerTerm();
@@ -6144,8 +6166,8 @@ router.post('/tmux/recovery/restore-all', async (_req, res) => {
                 const previous = collaborationRouting.get(frontendSessionId);
                 if (previous)
                     collaborationRouting.bind({ ...previous, pane: null });
-                await beginAgentLaunchCheck(frontendSessionId, agent.slug, target.nativeSessionId);
-                await writeAutomaticTerminalPrompt(frontendSessionId, command);
+                const launchGuard = await beginAgentLaunchCheck(frontendSessionId, agent.slug, target.nativeSessionId);
+                await writeAutomaticTerminalPrompt(frontendSessionId, command, undefined, launchGuard);
             }));
             outcomes.push({ sessionId: frontendSessionId, restored: true });
         }
@@ -7098,8 +7120,8 @@ router.post('/operations/execution-archives/:sessionId/restore', executionArchiv
         broadcastClientState();
         throw error;
     }
-    await beginAgentLaunchCheck(record.sessionId, target.slug, target.nativeSessionId);
-    await writeAutomaticTerminalPrompt(opened.session.sessionId, command);
+    const launchGuard = await beginAgentLaunchCheck(record.sessionId, target.slug, target.nativeSessionId);
+    await writeAutomaticTerminalPrompt(opened.session.sessionId, command, undefined, launchGuard);
     restoreArchivedMembership(entry, record.sessionId);
     await persistGlobalStateNow();
     broadcastClientState();
@@ -8294,7 +8316,10 @@ router.post('/:sessionId/input', express.text({ type: '*/*' }), (req, res) => {
     }
     const data = typeof req.body === 'string' ? req.body : '';
     try {
-        session.ptyProcess.write(data);
+        const paste = new TerminalPasteBuffer(() => { });
+        const parts = paste.complete(data);
+        for (const part of parts)
+            session.ptyProcess.write(part);
         session.lastActivity = Date.now();
         res.json({ success: true });
     }
@@ -8343,10 +8368,9 @@ router.post('/:sessionId/agent-resume', async (req, res) => {
     try {
         const frontend = globalSessionState.sessions.find(candidate => candidate.backendSessionId === sessionId);
         const launch = async () => {
+            const launchGuard = frontend ? await beginAgentLaunchCheck(frontend.sessionId, target.slug, target.nativeSessionId) : undefined;
             if (frontend)
-                await beginAgentLaunchCheck(frontend.sessionId, target.slug, target.nativeSessionId);
-            if (frontend)
-                await writeAutomaticTerminalPrompt(frontend.sessionId, target.command);
+                await writeAutomaticTerminalPrompt(frontend.sessionId, target.command, undefined, launchGuard);
             else
                 await writeBracketedPrompt(session.ptyProcess, target.command, captureTerminalInputGuard(() => terminalSessions.get(sessionId), session));
         };
@@ -8464,7 +8488,7 @@ router.post('/:sessionId/tmux', async (req, res) => {
             broadcastEvent(sessionId, { type: 'tmux-layout', layout });
             return res.json({ success: true, layout });
         }
-        return res.json({ success: true });
+        return res.json({ success: true, ...(result.selection ? { selection: result.selection } : {}) });
     }
     catch (error) {
         const errorMessage = getErrorMessage(error);
@@ -8559,6 +8583,10 @@ router.post('/force-kill', (req, res) => {
 async function executeTmuxAction(tmuxTarget, action, body, control) {
     let shouldBroadcastLayout = true;
     switch (action) {
+        case 'copy-selection': {
+            const selection = await copyTmuxSelection(tmuxTarget, runTmux);
+            return { shouldBroadcastLayout: false, selection };
+        }
         case 'select-pane': {
             const paneId = typeof body.paneId === 'string' ? body.paneId : '';
             if (!paneId)
@@ -8949,6 +8977,12 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
         if (ws.readyState === ws.OPEN)
             ws.send(JSON.stringify(event));
     });
+    const pasteInput = new TerminalPasteBuffer(error => {
+        if (ws.readyState === ws.OPEN) {
+            ws.send(JSON.stringify({ type: 'error', error }));
+            ws.close(1008, 'Incomplete terminal paste');
+        }
+    });
     // Handle client → server messages
     ws.on('message', async (raw) => {
         const messageReceivedAt = performance.now();
@@ -8963,20 +8997,30 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
             switch (msg.type) {
                 case 'input': {
                     if (typeof msg.data === 'string' && msg.data.length > 0) {
-                        const data = msg.data;
-                        if (attachment) {
-                            session.lastActivity = Date.now();
-                            attachment.write(data);
+                        let parts;
+                        try {
+                            parts = pasteInput.push(msg.data);
                         }
-                        else if (session.mode === 'tmux') {
-                            await enqueueTmuxIo(session, async () => {
+                        catch (error) {
+                            ws.send(JSON.stringify({ type: 'error', error: getErrorMessage(error) }));
+                            ws.close(1008, 'Invalid terminal paste');
+                            return;
+                        }
+                        for (const data of parts) {
+                            if (attachment) {
+                                session.lastActivity = Date.now();
+                                attachment.write(data);
+                            }
+                            else if (session.mode === 'tmux') {
+                                await enqueueTmuxIo(session, async () => {
+                                    session.lastActivity = Date.now();
+                                    session.ptyProcess.write(data);
+                                });
+                            }
+                            else {
                                 session.lastActivity = Date.now();
                                 session.ptyProcess.write(data);
-                            });
-                        }
-                        else {
-                            session.lastActivity = Date.now();
-                            session.ptyProcess.write(data);
+                            }
                         }
                     }
                     break;
@@ -9044,8 +9088,14 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
                     }
                     const result = await enqueueTmuxIo(session, async () => {
                         return executeTmuxAction(session.tmuxSessionName, msg.action, msg, session.tmuxControl);
+                    }).catch((error) => {
+                        // A correlated copy failure must settle this socket's request, not
+                        // become an unrelated terminal error followed by a 30-second wait.
+                        if (msg.action !== 'copy-selection')
+                            throw error;
+                        return { shouldBroadcastLayout: false, error: getErrorMessage(error) || 'Tmux selection copy failed' };
                     });
-                    ws.send(JSON.stringify({ type: 'tmux-result', reqId, success: !result.error, error: result.error }));
+                    ws.send(JSON.stringify({ type: 'tmux-result', reqId, success: !result.error, error: result.error, ...(result.selection ? { selection: result.selection } : {}) }));
                     if (result.shouldBroadcastLayout && session.tmuxSessionName) {
                         try {
                             const layout = await getTmuxLayout(session.tmuxSessionName);
@@ -9143,6 +9193,7 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
     });
     // Cleanup on close
     ws.on('close', () => {
+        pasteInput.clear();
         initialScreen?.cancel();
         initialScreen = null;
         attachment?.close();

package/dist/server/utils/autoUpdate.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { compareVersions, updateTermdockFromOfficialRegistry, } from './npmUpdate.js';
+import { compareVersions, verifyRunningTermdockInstallation, updateTermdockFromOfficialRegistry, } from './npmUpdate.js';
 export const AUTO_UPDATE_INITIAL_DELAY_MS = 15_000;
 export const AUTO_UPDATE_INTERVAL_MS = 6 * 60 * 60 * 1_000;
 function initialState(currentVersion) {
@@ -44,11 +44,11 @@ export class TermdockAutoUpdateManager {
             return;
         this.initialTimer = setTimeout(() => {
             this.initialTimer = null;
-            void this.checkNow();
+            void this.checkNow(false);
         }, AUTO_UPDATE_INITIAL_DELAY_MS);
         this.initialTimer.unref?.();
         this.intervalTimer = setInterval(() => {
-            void this.checkNow();
+            void this.checkNow(false);
         }, AUTO_UPDATE_INTERVAL_MS);
         this.intervalTimer.unref?.();
     }
@@ -60,12 +60,24 @@ export class TermdockAutoUpdateManager {
         this.initialTimer = null;
         this.intervalTimer = null;
     }
-    checkNow() {
+    checkNow(explicit = true) {
+        // Failed installation validation requires a user-requested check, not a timer retry.
+        if (!explicit && this.state.status === 'error' && hasPendingTermdockUpdate(this.state))
+            return Promise.resolve(this.getState());
         // Once an installed update is waiting for explicit confirmation, periodic
         // checks must never turn any external state change into implicit consent.
         // Keep the reminder until the user confirms or restarts manually.
         if (this.state.status === 'ready' && hasPendingTermdockUpdate(this.state)) {
-            return Promise.resolve(this.getState());
+            try {
+                this.verifyInstalled(this.state.latestVersion);
+                return Promise.resolve(this.getState());
+            }
+            catch (error) {
+                this.installationError(error);
+                if (!explicit)
+                    return Promise.resolve(this.getState());
+            }
+            // Only the explicit check repairs an invalid pending installation; never restart here.
         }
         if (this.checkPromise)
             return this.checkPromise;
@@ -78,10 +90,33 @@ export class TermdockAutoUpdateManager {
         if (this.state.status !== 'ready' || !hasPendingTermdockUpdate(this.state)) {
             throw new Error('No installed Termdock update is waiting for restart.');
         }
+        try {
+            this.verifyInstalled(this.state.latestVersion);
+            if (process.env.TERMDOCK_SUPERVISED !== '1' || !process.connected)
+                throw new Error('Automatic restart requires the verified supervised Termdock entry; restart manually.');
+            this.dependencies.verifyRestartEntry?.();
+        }
+        catch (error) {
+            this.installationError(error);
+            throw error;
+        }
         this.setState({ ...this.state, status: 'restarting', error: null });
-        this.dependencies.requestRestart();
+        try {
+            this.dependencies.requestRestart();
+        }
+        catch (error) {
+            this.installationError(error);
+            throw error;
+        }
         return this.getState();
     }
+    verifyInstalled(version) {
+        (this.dependencies.verifyInstalled ?? verifyRunningTermdockInstallation)(version);
+    }
+    installationError(error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        this.setState({ ...this.state, status: 'error', error: detail });
+    }
     async runCheck() {
         this.setState({ ...this.state, status: 'checking', checkedAt: Date.now(), error: null });
         try {
@@ -110,6 +145,7 @@ export class TermdockAutoUpdateManager {
                 });
                 return this.getState();
             }
+            this.verifyInstalled(result.latestVersion);
             this.setState({
                 status: 'ready',
                 currentVersion: result.currentVersion,
@@ -145,13 +181,24 @@ export class TermdockAutoUpdateManager {
                 return fallback;
             if (value.status !== 'ready' && value.status !== 'restarting' && value.status !== 'error')
                 return fallback;
+            let restoredStatus = value.status === 'restarting' ? 'ready' : value.status;
+            let restoredError = typeof value.error === 'string' ? value.error : null;
+            if (restoredStatus === 'ready') {
+                try {
+                    this.verifyInstalled(value.latestVersion);
+                }
+                catch (error) {
+                    restoredStatus = 'error';
+                    restoredError = error instanceof Error ? error.message : String(error);
+                }
+            }
             return {
-                status: value.status === 'restarting' ? 'ready' : value.status,
+                status: restoredStatus,
                 currentVersion: this.dependencies.currentVersion,
                 latestVersion: value.latestVersion,
                 source: value.source === 'configured' ? 'configured' : 'official',
                 checkedAt: typeof value.checkedAt === 'number' ? value.checkedAt : null,
-                error: typeof value.error === 'string' ? value.error : null,
+                error: restoredError,
             };
         }
         catch {

package/dist/server/utils/npmUpdate.js

@@ -1,5 +1,8 @@
 import { execFile, spawn } from 'node:child_process';
 import { promisify } from 'node:util';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 const execFileAsync = promisify(execFile);
 export const OFFICIAL_NPM_REGISTRY = 'https://registry.npmjs.org';
 const TERMDOCK_PACKAGE = 'termdock';
@@ -41,7 +44,7 @@ export function buildNpmViewArgs(registry = OFFICIAL_NPM_REGISTRY) {
         args.push('--registry', registry);
     return args;
 }
-export function buildNpmInstallArgs(version, registry = OFFICIAL_NPM_REGISTRY) {
+export function buildNpmInstallArgs(version, registry = OFFICIAL_NPM_REGISTRY, prefix) {
     if (!parseVersion(version))
         throw new Error(`Invalid Termdock version from npm: ${version}`);
     const args = [
@@ -49,11 +52,56 @@ export function buildNpmInstallArgs(version, registry = OFFICIAL_NPM_REGISTRY) {
         '--global',
         `${TERMDOCK_PACKAGE}@${version}`,
     ];
+    if (prefix)
+        args.push('--prefix', prefix);
     if (registry)
         args.push('--registry', registry);
     args.push('--foreground-scripts');
     return args;
 }
+function installedVersion(installation) {
+    // Fresh filesystem reads: npm replaces this package while this process keeps
+    // running old JS. Neither require/import caches nor TERMDOCK_VERSION attest it.
+    if (fs.realpathSync(installation.packageRoot) !== installation.packageRoot) {
+        throw new Error('Running Termdock installation changed location; check for updates again.');
+    }
+    const value = JSON.parse(fs.readFileSync(path.join(installation.packageRoot, 'package.json'), 'utf8'));
+    if (!value || typeof value !== 'object' || !('name' in value) || value.name !== TERMDOCK_PACKAGE
+        || !('version' in value) || typeof value.version !== 'string' || !parseVersion(value.version)) {
+        throw new Error('Running Termdock installation has invalid package metadata.');
+    }
+    return value.version;
+}
+/** Resolve the module which is actually running, never PATH's unrelated npm root. */
+export function resolveRunningTermdockInstallation(moduleUrl = import.meta.url, runningEntry = process.argv[1]) {
+    const moduleFile = fs.realpathSync(fileURLToPath(moduleUrl));
+    const packageRoot = path.resolve(path.dirname(moduleFile), '../../..');
+    const nodeModules = path.dirname(packageRoot);
+    if (path.basename(packageRoot) !== TERMDOCK_PACKAGE || path.basename(nodeModules) !== 'node_modules') {
+        throw new Error('Automatic updates require a supported global Termdock installation.');
+    }
+    const parent = path.dirname(nodeModules);
+    let prefix;
+    if (process.platform === 'win32')
+        prefix = parent;
+    else if (path.basename(parent) === 'lib')
+        prefix = path.dirname(parent);
+    else
+        throw new Error('Automatic updates require a supported global Termdock installation.');
+    const installation = { packageRoot, prefix };
+    // supervisor resolves and reuses this child's argv entry. A module loaded
+    // from another installation must never approve that different restart root.
+    if (!runningEntry || fs.realpathSync(runningEntry) !== path.join(packageRoot, 'dist/server/cli.js')) {
+        throw new Error('Running Termdock entry does not match its update installation.');
+    }
+    installedVersion(installation);
+    return installation;
+}
+export function verifyRunningTermdockInstallation(version, installation = resolveRunningTermdockInstallation()) {
+    if (compareVersions(installedVersion(installation), version) < 0) {
+        throw new Error('Running Termdock installation has not completed this update; check for updates again.');
+    }
+}
 export function parseNpmVersionOutput(output) {
     let value;
     try {
@@ -67,6 +115,26 @@ export function parseNpmVersionOutput(output) {
     }
     return value;
 }
+export function npmRuntimeEnvironment(execPath = process.execPath, env = process.env, platform = process.platform) {
+    const systemBins = platform === 'darwin' ? ['/opt/homebrew/bin', '/usr/local/bin'] : [];
+    return { ...env, PATH: [path.dirname(execPath), ...systemBins, env.PATH].filter(Boolean).join(path.delimiter) };
+}
+async function installEnvironment() {
+    const env = npmRuntimeEnvironment();
+    if (process.platform === 'darwin') {
+        // New CLT releases can leave node-gyp's implicit libc++ search path stale.
+        // Use the SDK selected by xcrun without changing the user's global setup.
+        const { stdout } = await execFileAsync('/usr/bin/xcrun', ['--show-sdk-path'], { timeout: 5000, env });
+        const sdk = stdout.trim();
+        const headers = path.join(sdk, 'usr/include/c++/v1');
+        if (!path.isAbsolute(sdk) || !fs.existsSync(path.join(headers, 'functional'))) {
+            throw new Error('macOS C++ SDK headers are unavailable. Install or repair Command Line Tools, then retry.');
+        }
+        env.SDKROOT = sdk;
+        env.CPLUS_INCLUDE_PATH = [headers, env.CPLUS_INCLUDE_PATH].filter(Boolean).join(path.delimiter);
+    }
+    return env;
+}
 function npmExecutable() {
     return process.platform === 'win32' ? 'npm.cmd' : 'npm';
 }
@@ -76,7 +144,7 @@ async function fetchLatestVersion(registry) {
         const result = await execFileAsync(npmExecutable(), buildNpmViewArgs(registry), {
             timeout: NPM_QUERY_TIMEOUT_MS,
             maxBuffer: 256 * 1024,
-            env: process.env,
+            env: npmRuntimeEnvironment(),
         });
         stdout = result.stdout;
     }
@@ -87,11 +155,15 @@ async function fetchLatestVersion(registry) {
     }
     return parseNpmVersionOutput(stdout);
 }
-function installVersion(version, registry) {
-    return new Promise((resolve, reject) => {
-        const child = spawn(npmExecutable(), buildNpmInstallArgs(version, registry), {
+export async function installTermdockVersion(version, registry, installation, executable = npmExecutable()) {
+    if (compareVersions(installedVersion(installation), version) > 0) {
+        throw new Error('Running Termdock location already contains a newer version; restart that installation manually.');
+    }
+    const env = await installEnvironment();
+    await new Promise((resolve, reject) => {
+        const child = spawn(executable, buildNpmInstallArgs(version, registry, installation.prefix), {
             stdio: 'inherit',
-            env: process.env,
+            env,
         });
         child.once('error', reject);
         child.once('exit', (code, signal) => {
@@ -103,6 +175,9 @@ function installVersion(version, registry) {
             reject(new Error(`npm failed to install Termdock (${reason}).`));
         });
     });
+    if (installedVersion(installation) !== version) {
+        throw new Error('npm did not install the requested version at the running Termdock location.');
+    }
 }
 export async function updateTermdockFromOfficialRegistry(currentVersion, onFallback, onLatest) {
     if (!parseVersion(currentVersion))
@@ -124,8 +199,9 @@ export async function updateTermdockFromOfficialRegistry(currentVersion, onFallb
         return { status: 'current', currentVersion, latestVersion, source };
     if (comparison > 0)
         return { status: 'newer-than-registry', currentVersion, latestVersion, source };
+    const installation = resolveRunningTermdockInstallation();
     try {
-        await installVersion(latestVersion, source === 'official' ? OFFICIAL_NPM_REGISTRY : null);
+        await installTermdockVersion(latestVersion, source === 'official' ? OFFICIAL_NPM_REGISTRY : null, installation);
     }
     catch (error) {
         if (source === 'configured')
@@ -133,7 +209,7 @@ export async function updateTermdockFromOfficialRegistry(currentVersion, onFallb
         const cause = error instanceof Error ? error : new Error(String(error));
         onFallback?.('install', cause);
         source = 'configured';
-        await installVersion(latestVersion, null);
+        await installTermdockVersion(latestVersion, null, installation);
     }
     return { status: 'updated', currentVersion, latestVersion, source };
 }