termdock 1.4.356 → 1.4.357

package/dist/server/routes/terminal.js

@@ -1,11 +1,13 @@
 import { sessionViewModeRoutes, SessionViewModeStore } from '../agent/sessionViewModeRoutes.js';
+import { incompleteOscSuffix } from '../utils/oscBuffer.js';
+import { terminalProgramStatus, PROGRAM_STATUS_REPLY } from '../shared/programStatus.js';
 import { sessionAttachmentRoutes } from '../agent/sessionAttachmentRoutes.js';
 import { TodoStore, TodoError } from '../todos/store.js';
 import { TodoRunner, todoRoutes } from '../todos/routes.js';
 import { TerminalInputQueue } from '../utils/terminalInputQueue.js';
 import { copyTmuxSelection } from '../utils/tmuxCopySelection.js';
 import { isConfirmedEmptyTmuxServer } from '../utils/tmuxEmptyServerProbe.js';
-import { collaborationSessionDisplayName } from '../utils/sessionDisplayName.js';
+import { getSessionPresentation } from '../utils/sessionDisplayName.js';
 import { integrationError } from '../agent/integrationStore.js';
 import { assertNativeResumeAvailable, collectNativeResumeOwnerCandidates } from '../agent/nativeResumeOwner.js';
 import { nativeIdentityDirectory, readNativeProcessIdentity, resolveProfileNativeIdentity } from '../agent/nativeProcessIdentity.js';
@@ -25,8 +27,9 @@ 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';
-import { claimTmuxSize } from '../utils/tmuxSizeOwnership.js';
+import { TmuxDisplayGeometry } from '../utils/tmuxDisplayGeometry.js';
 import { TmuxInitialScreen } from '../utils/tmuxInitialScreen.js';
+import { readTmuxObserverSize } from '../utils/tmuxObserverSize.js';
 import { TerminalOutputDelivery, resolveTerminalReplayCursor } from '../utils/terminalOutputDelivery.js';
 import express from 'express';
 import fs from 'fs';
@@ -44,7 +47,7 @@ import { getPtyHostManager } from '../ptyhost/manager.js';
 import { pathValidator } from '../utils/pathValidator.js';
 import { TERMINAL, TMUX } from '../config.js';
 import { localAccessManager, localAccessInterfaceUrl } from '../utils/localAccess.js';
-import { normalizeLocalAccessName, getLocaleSetting, setLocaleSetting, getContextDraftHeightSetting, setContextDraftHeightSetting, getAutoRenameAgentsSetting, setAutoRenameAgentsSetting, getAutoRenameNamerSetting, setAutoRenameNamerSetting, getAutoRenameModelsSetting, setAutoRenameModelsSetting, getAutoRenameIntervalMinutesSetting, setAutoRenameIntervalMinutesSetting, getAutoRenamePromptPreferenceSetting, setAutoRenamePromptPreferenceSetting, getAutoRenamePromptPayloadCharsSetting, setAutoRenamePromptPayloadCharsSetting, getNewSessionAgentSlugSetting, setNewSessionAgentSlugSetting, getRunningSessionButtonEnabledSetting, getAttentionButtonEnabledSetting, getCollaborationPanelsSetting, setCollaborationPanelSetting, getAndroidPanelSetting, setAndroidPanelSetting, getRightSidebarTabsSetting, setRightSidebarTabsSetting, normalizeAndroidPanel, getCollaborationFloatingGroupIdSetting, setCollaborationFloatingGroupIdSetting, getServiceSwitcherExpandedSetting, setServiceSwitcherExpandedSetting, setRunningSessionButtonEnabledSetting, setAttentionButtonEnabledSetting, getFileSortModesSetting, getHideGitIgnoredRootsSetting, getGitIgnoreExceptionsSetting, setGitIgnoreExceptionsSetting, setHideGitIgnoredRootSetting, setFileSortModesSetting, setFileSortModeSetting, getNestedGitScanRootsSetting, setNestedGitScanRootSetting, getPinnedExplorerRootsSetting, setPinnedExplorerRootsSetting, setPinnedExplorerRootSetting, watchPinnedExplorerRootsSetting, getActiveGitReposSetting, setActiveGitRepoSetting, } from '../utils/settings.js';
+import { normalizeLocalAccessName, getLocaleSetting, setLocaleSetting, getContextDraftHeightSetting, setContextDraftHeightSetting, getAutoRenameAgentsSetting, setAutoRenameAgentsSetting, getAutoRenameNamerSetting, setAutoRenameNamerSetting, getAutoRenameModelsSetting, setAutoRenameModelsSetting, getAutoRenameIntervalMinutesSetting, setAutoRenameIntervalMinutesSetting, getAutoRenamePromptPreferenceSetting, setAutoRenamePromptPreferenceSetting, getAutoRenamePromptPayloadCharsSetting, setAutoRenamePromptPayloadCharsSetting, getNewSessionAgentSlugSetting, setNewSessionAgentSlugSetting, getRunningSessionButtonEnabledSetting, getAttentionButtonEnabledSetting, getCollaborationPanelsSetting, setCollaborationPanelSetting, getAndroidPanelSetting, setAndroidPanelSetting, getRightSidebarTabsSetting, setRightSidebarTabsSetting, getCollaborationFloatingGroupIdSetting, setCollaborationFloatingGroupIdSetting, getServiceSwitcherExpandedSetting, setServiceSwitcherExpandedSetting, setRunningSessionButtonEnabledSetting, setAttentionButtonEnabledSetting, getFileSortModesSetting, getHideGitIgnoredRootsSetting, getGitIgnoreExceptionsSetting, setGitIgnoreExceptionsSetting, setHideGitIgnoredRootSetting, setFileSortModesSetting, setFileSortModeSetting, getNestedGitScanRootsSetting, setNestedGitScanRootSetting, getPinnedExplorerRootsSetting, setPinnedExplorerRootsSetting, setPinnedExplorerRootSetting, watchPinnedExplorerRootsSetting, getActiveGitReposSetting, setActiveGitRepoSetting, } from '../utils/settings.js';
 import { loadContextDraft, saveContextDraft } from '../utils/contextDraft.js';
 import { getOnboardingServerUrl } from '../onboardingServer.js';
 import { inspectLinuxInotifyUsage, isWatchResourceExhaustion } from '../utils/fileWatchPolicy.js';
@@ -86,7 +89,7 @@ import { assertDetachedCloseOwnership } from '../agent/integrationCloseOwnership
 import { readTmuxLayout, readTmuxLayouts } from '../utils/tmuxLayoutReader.js';
 import { CollaborationDeliveryWorker } from '../agent/collaborationDeliveryWorker.js';
 import { approveCollaborationDialog, captureTmuxPaneHistory, captureTmuxPaneText, sendTmuxPaneKey, writeCollaborationTmuxPane } from '../agent/collaborationTmuxDelivery.js';
-import { listAllHookAgents, refreshStaleHooksAtLaunch, installHooksForSlug, uninstallHooksForSlug, } from '../agent/installers.js';
+import { listAllHookAgents, refreshStaleHooksAtLaunch, installHooksForSlug, runtimeHooksStateForSlug, uninstallHooksForSlug, } from '../agent/installers.js';
 import { loadPlugins, savePlugin, removePlugin, readPluginIcon, validateManifest, } from '../agent/plugins.js';
 import { TmuxLifecycleCoordinator } from '../utils/tmuxLifecycle.js';
 import { buildInteractiveColorEnvironment, buildTmuxColorEnvironmentCommands, ensureTmuxColorCapabilities, resolveTmuxInnerTerm, } from '../utils/terminalColorEnvironment.js';
@@ -1471,6 +1474,11 @@ function orchestrationSessionSnapshot(record) {
     const terminalConnected = Boolean(backend);
     const slug = binding?.pane?.agentSlug ?? binding?.agentSlug ?? record.agentResume?.slug;
     const agent = slug ? agentBySlug(slug) : backend?.agent;
+    const presentation = getSessionPresentation({ ...record,
+        activeProgram: backend?.activeProgram?.command ?? record.activeProgram,
+        shellTitle: backend?.lastOscTitle ?? record.shellTitle, cwd: backend?.cwd ?? record.cwd,
+        promptState: backend?.lastPromptState ?? null, agent,
+    }, shellNamesBackend);
     return {
         ...collaborationStore.sessionFacts(record.sessionId, terminalConnected || route.state === 'ready' || route.state === 'shell'),
         last_terminal_output_at: backend?.lastOutputAt || null,
@@ -1483,12 +1491,8 @@ function orchestrationSessionSnapshot(record) {
         sessionId: record.sessionId,
         agentNativeSessionId: binding?.pane ? binding.pane.nativeSessionId : binding?.nativeSessionId ?? backend?.agentSession?.sessionId ?? record.agentResume?.sessionId ?? null,
         backendSessionId: backendId ?? null,
-        name: collaborationSessionDisplayName({ ...record,
-            activeProgram: backend?.activeProgram?.command ?? record.activeProgram,
-            shellTitle: backend?.lastOscTitle ?? record.shellTitle,
-            cwd: backend?.cwd ?? record.cwd,
-            agent: agent ? { displayName: agent.displayName } : null,
-        }),
+        name: presentation.displayName,
+        ...presentation,
         cwd: backend?.cwd ?? record.cwd ?? '',
         agent: agent ? { slug: agent.slug, displayName: agent.displayName } : null,
         status: route.state === 'unchecked' && terminalConnected ? 'terminal-connected' : route.state,
@@ -1939,20 +1943,22 @@ async function resolveCollaborationRoute(frontendSessionId) {
             return { state: 'detached', reason: 'TMUX_BACKEND_UNAVAILABLE' };
         assertGeneration();
         const assertCurrent = terminalInputGuard(globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId));
-        return { state: 'ready', isShell: pane.isShell, capture: async () => captureTmuxPaneText(runTmux, pinned), write: async (messages) => {
-                if (!globalSessionState.sessions.some((candidate) => candidate.sessionId === frontendSessionId))
-                    throw new Error('SESSION_REMOVED');
-                if (recoveredNativeIdentity) {
-                    const current = await inspectCollaborationTmux(binding, null, false, true, true, true);
-                    const proof = current.candidates?.find(candidate => candidate.serverPid === pinned.serverPid && candidate.sessionId === pinned.sessionId
-                        && candidate.paneId === pinned.paneId && candidate.panePid === pinned.panePid);
-                    if (!proof?.nativeIdentityVerified || proof.nativeIdentityFailure || proof.nativeSessionId !== pinned.nativeSessionId
-                        || proof.agentSlug !== pinned.agentSlug || !routeOwnershipConfirmed(frontendSessionId, binding, [proof]))
-                        throw new Error('ROUTE_NATIVE_IDENTITY_CHANGED_BEFORE_WRITE');
-                }
-                await writeCollaborationTmuxPane(runTmux, pinned, formatLocalCollaborationMessages(frontendSessionId, messages), runTmuxStdin, () => { assertGeneration(); assertCurrent(); });
-                backend.lastActivity = Date.now();
-            } };
+        const writeText = async (prompt) => {
+            if (!globalSessionState.sessions.some((candidate) => candidate.sessionId === frontendSessionId))
+                throw new Error('SESSION_REMOVED');
+            if (recoveredNativeIdentity) {
+                const current = await inspectCollaborationTmux(binding, null, false, true, true, true);
+                const proof = current.candidates?.find(candidate => candidate.serverPid === pinned.serverPid && candidate.sessionId === pinned.sessionId
+                    && candidate.paneId === pinned.paneId && candidate.panePid === pinned.panePid);
+                if (!proof?.nativeIdentityVerified || proof.nativeIdentityFailure || proof.nativeSessionId !== pinned.nativeSessionId
+                    || proof.agentSlug !== pinned.agentSlug || !routeOwnershipConfirmed(frontendSessionId, binding, [proof]))
+                    throw new Error('ROUTE_NATIVE_IDENTITY_CHANGED_BEFORE_WRITE');
+            }
+            await writeCollaborationTmuxPane(runTmux, pinned, prompt, runTmuxStdin, () => { assertGeneration(); assertCurrent(); });
+            backend.lastActivity = Date.now();
+        };
+        return { state: 'ready', isShell: pane.isShell, capture: async () => captureTmuxPaneText(runTmux, pinned), writeText,
+            write: messages => writeText(formatLocalCollaborationMessages(frontendSessionId, messages)) };
     }
     if (!backend || !binding.backendSessionId)
         return { state: 'offline', reason: 'SHELL_BACKEND_NOT_RUNNING' };
@@ -1967,22 +1973,23 @@ async function resolveCollaborationRoute(frontendSessionId) {
         if (launch)
             return launch;
     }
+    const writeText = async (prompt) => {
+        if (!globalSessionState.sessions.some((candidate) => candidate.sessionId === frontendSessionId))
+            throw new Error('SESSION_REMOVED');
+        if (terminalSessions.get(binding.backendSessionId) !== target)
+            throw new Error('SHELL_BACKEND_CHANGED');
+        await writeBracketedPrompt(target.ptyProcess, prompt, () => {
+            assertGeneration();
+            assertCurrent();
+            if (terminalSessions.get(binding.backendSessionId) !== target)
+                throw new Error('TERMINAL_INPUT_TARGET_CHANGED');
+        });
+        target.lastActivity = Date.now();
+    };
     return { state: 'ready',
         isShell: backend.activeProgram?.source !== 'unknown' && shellNamesBackend.has(backend.activeProgram?.command?.toLowerCase() ?? ''),
-        capture: async () => target.autoTitleContext,
-        write: async (messages) => {
-            if (!globalSessionState.sessions.some((candidate) => candidate.sessionId === frontendSessionId))
-                throw new Error('SESSION_REMOVED');
-            if (terminalSessions.get(binding.backendSessionId) !== target)
-                throw new Error('SHELL_BACKEND_CHANGED');
-            await writeBracketedPrompt(target.ptyProcess, formatLocalCollaborationMessages(frontendSessionId, messages), () => {
-                assertGeneration();
-                assertCurrent();
-                if (terminalSessions.get(binding.backendSessionId) !== target)
-                    throw new Error('TERMINAL_INPUT_TARGET_CHANGED');
-            });
-            target.lastActivity = Date.now();
-        } };
+        capture: async () => target.autoTitleContext, writeText,
+        write: messages => writeText(formatLocalCollaborationMessages(frontendSessionId, messages)) };
 }
 async function refreshCollaborationAgentIdentity(backendSessionId, session, freshProcess = false) {
     let activeProgram = null;
@@ -3441,7 +3448,7 @@ async function buildSessionInventory() {
         const tmuxMeta = session.tmuxSessionName ? liveTmuxByName.get(session.tmuxSessionName) : undefined;
         const activeProgram = backend?.activeProgram?.command ?? tmuxMeta?.program ?? session.activeProgram ?? null;
         const cwd = backend?.cwd ?? tmuxMeta?.cwd ?? session.cwd ?? null;
-        const shellTitle = tmuxMeta?.shellTitle ?? backend?.lastOscTitle ?? session.shellTitle ?? null;
+        const shellTitle = backend?.lastOscTitle ?? tmuxMeta?.shellTitle ?? session.shellTitle ?? null;
         // Identity is available without opening a terminal stream. Use foreground
         // argv for interpreter/wrapper launches, and resume identity at shell prompts.
         const foregroundAgent = (backend ? detectSessionAgent(backend) : null)
@@ -3467,6 +3474,7 @@ async function buildSessionInventory() {
             cwd,
             shellTitle,
             agent,
+            ...getSessionPresentation({ ...session, activeProgram, cwd, shellTitle, agent, promptState: backend?.lastPromptState ?? null }, shellNamesBackend),
         };
     });
     const clientByTmux = new Map();
@@ -3623,7 +3631,7 @@ function getPtyProcessPid(ptyProcess) {
     return null;
 }
 // ── OSC sniffing for CWD tracking + prompt state + title ──
-const OSC_SNIFF_CAP = 32768; // 32 KB rolling buffer
+const OSC_SNIFF_CAP = 512 * 1024; // bounded incomplete hook payload (JSON escaping can expand stdin)
 // Match all OSC sequences we care about:
 //   OSC 0;... / OSC 2;...  → title (may contain cwd or command name)
 //   OSC 7;...              → cwd report (kitty-shell-cwd://host/path)
@@ -3787,7 +3795,7 @@ function sniffOsc(buf, home) {
             }
         }
     }
-    const remaining = buf.slice(lastMatchEnd).slice(-128);
+    const remaining = incompleteOscSuffix(buf, lastMatchEnd, OSC_SNIFF_CAP);
     return { cwd: lastCwd, title: lastTitle, promptState, exitCode, tuiProgress, agentEvents, notification, remaining };
 }
 /** The body of a `notify;<title>;<body>` OSC 777 payload, or null. */
@@ -4111,7 +4119,7 @@ function serializeAgentIdentity(agent) {
         : null;
 }
 let lastAgentStatusSnapshots = new Map();
-function broadcastAgentStatus(sessionId, session, force = false) {
+function broadcastAgentStatus(sessionId, session, force = false, notify = true) {
     const payload = buildAgentStatusPayload(sessionId, session);
     const snapshot = JSON.stringify(payload);
     const previousSnapshot = lastAgentStatusSnapshots.get(sessionId);
@@ -4123,7 +4131,36 @@ function broadcastAgentStatus(sessionId, session, force = false) {
     const previous = previousSnapshot
         ? JSON.parse(previousSnapshot)
         : null;
-    notifyAgentTransition(sessionId, previous, payload);
+    if (notify)
+        notifyAgentTransition(sessionId, previous, payload);
+}
+const nativeStatusRecoveryTimers = new WeakMap();
+function cancelNativeStatusRecovery(session) {
+    const timer = nativeStatusRecoveryTimers.get(session);
+    if (timer)
+        clearTimeout(timer);
+    nativeStatusRecoveryTimers.delete(session);
+}
+/** A matching program's explicit terminal completion can recover a missed
+ * Stop/Interrupt hook. Never infer completion from output silence or CPU. */
+function scheduleNativeStatusRecovery(sessionId, session, endedApps) {
+    const agent = session.agent, state = session.agentSession;
+    if (!agent || state?.status !== 'working' || !endedApps.some(app => agent.slug === app || agent.aliases.includes(app)))
+        return;
+    cancelNativeStatusRecovery(session);
+    const timer = setTimeout(() => {
+        nativeStatusRecoveryTimers.delete(session);
+        if (terminalSessions.get(sessionId) !== session || session.agent !== agent || session.agentSession !== state || state.status !== 'working')
+            return;
+        if (terminalProgramStatus(session).activeApps().some(app => agent.slug === app || agent.aliases.includes(app)))
+            return;
+        state.status = 'idle';
+        state.message = null;
+        state.presentation = null;
+        broadcastAgentStatus(sessionId, session, false, false);
+    }, 3000);
+    timer.unref?.();
+    nativeStatusRecoveryTimers.set(session, timer);
 }
 /** Persist the info needed to resume this pane's agent conversation after the
  *  agent exits / the server restarts (last-known semantics, debounced). */
@@ -4252,6 +4289,7 @@ function applyAgentSignals(sessionId, session, events, notification) {
     for (const event of events) {
         if (!agentEventMatchesCurrentAgent(session.agent, event))
             continue;
+        cancelNativeStatusRecovery(session);
         // An event naming an agent brands the pane even when the process poll
         // can't see through a wrapper: identity via protocol.
         if (!session.agent && event.agent) {
@@ -5605,11 +5643,11 @@ function processSessionOutput(sessionId, session, data, opts) {
     // Sniff OSC sequences for CWD tracking + prompt state + title
     try {
         const buf = session.oscSniffBuf + data;
-        if (buf.length > OSC_SNIFF_CAP) {
-            session.oscSniffBuf = buf.slice(-OSC_SNIFF_CAP / 4); // trim
-        }
         const result = sniffOsc(buf, home);
         session.oscSniffBuf = result.remaining;
+        const progress = terminalProgramStatus(session).feed(data);
+        if (progress.query && opts.broadcast)
+            session.ptyProcess.write(PROGRAM_STATUS_REPLY);
         // CWD change
         if (result.cwd && result.cwd !== session.lastOscCwd) {
             session.lastOscCwd = result.cwd;
@@ -5642,8 +5680,8 @@ function processSessionOutput(sessionId, session, data, opts) {
                 refreshGitStatus(sessionId, session);
             }
         }
-        if (result.tuiProgress !== null) {
-            session.tuiProgress = result.tuiProgress.state === 'remove' ? null : result.tuiProgress;
+        if (progress.changed) {
+            session.tuiProgress = progress.progress;
             broadcastJsonWs(sessionId, {
                 type: 'tui-progress',
                 tuiProgress: session.tuiProgress,
@@ -5654,6 +5692,8 @@ function processSessionOutput(sessionId, session, data, opts) {
         if (result.agentEvents.length > 0 || result.notification) {
             applyAgentSignals(sessionId, session, result.agentEvents, result.notification);
         }
+        if (progress.endedApps.length)
+            scheduleNativeStatusRecovery(sessionId, session, progress.endedApps);
     }
     catch { /* sniff failure should never block data */ }
     appendAutoTitleContext(sessionId, session, data, opts.broadcast);
@@ -5672,6 +5712,11 @@ function setupPtyHandlers(sessionId, session) {
     });
     session.exitDisposable = session.ptyProcess.onExit(({ exitCode, signal }) => {
         console.log(`Terminal session ${sessionId} exited with code ${exitCode}, signal ${signal}`);
+        const progress = terminalProgramStatus(session).exit();
+        if (progress.changed) {
+            session.tuiProgress = progress.progress;
+            broadcastEvent(sessionId, { type: 'tui-progress', tuiProgress: session.tuiProgress });
+        }
         broadcastEvent(sessionId, { type: 'exit', exitCode, signal });
         // User-initiated closes dispose this listener before killing the pty, so
         // reaching here means the process exited on its own. Sessions with a live
@@ -5729,8 +5774,8 @@ async function spawnTerminalSession(req, input) {
 }
 async function spawnTerminalSessionUnlocked(req, input) {
     const cwd = await resolveWorkingDirectory(req, input.cwd);
-    const cols = input.cols || 80;
-    const rows = input.rows || 24;
+    let cols = input.cols || 80;
+    let rows = input.rows || 24;
     const sessionId = Math.random().toString(36).substring(2, 15) +
         Math.random().toString(36).substring(2, 15);
     let mode = normalizeMode(input.mode);
@@ -5752,6 +5797,7 @@ async function spawnTerminalSessionUnlocked(req, input) {
         }
         else
             await prepareManagedTmuxSession(tmuxSessionName, cwd);
+        ({ cols, rows } = await readTmuxObserverSize(runTmux, input.tmuxAttachTarget ?? `=${tmuxSessionName}`));
     }
     const command = mode === 'tmux'
         ? getTmuxBinary()
@@ -6610,6 +6656,23 @@ router.get('/session-inventory', async (_req, res) => {
     }
 });
 const todoRuntime = {
+    async target(id) {
+        const record = globalSessionState.sessions.find(session => session.sessionId === id);
+        if (!record)
+            throw new TodoError('这个会话已关闭，请重新选择', 409);
+        const route = await resolveCollaborationRoute(id);
+        const facts = orchestrationSessionSnapshot(record);
+        if (route.state !== 'ready' || route.isShell || !facts.agent)
+            throw new TodoError('这个会话暂时无法接收待办，请先在终端启动 Agent', 409);
+        const launcher = (await listDetectedAgentLaunchers()).find(agent => agent.slug === facts.agent.slug);
+        return { name: facts.name, config: { agentSlug: facts.agent.slug, command: launcher?.command ?? facts.agent.slug, cwd: record.cwd ?? '', prompt: '' } };
+    },
+    async deliver(run, prompt) {
+        const route = await resolveCollaborationRoute(run.sessionId);
+        if (route.state !== 'ready' || route.isShell || !route.writeText)
+            throw new TodoError('目标会话状态已变化，请检查终端后重试', 409);
+        await route.writeText(prompt);
+    },
     async validate(config, req) {
         const launcher = (await listDetectedAgentLaunchers()).find(agent => agent.slug === config.agentSlug);
         if (!launcher)
@@ -7815,16 +7878,7 @@ router.put('/settings', async (req, res) => {
         setRightSidebarTabsSetting(body.rightSidebarTabs);
     }
     if (body.androidPanel && typeof body.androidPanel === 'object') {
-        // 与现有设置合并后再校验：允许只更新部分字段（如仅切开关）。
-        const merged = normalizeAndroidPanel({ ...getAndroidPanelSetting(), ...body.androidPanel });
-        setAndroidPanelSetting({
-            enabled: merged.enabled,
-            quality: merged.quality,
-            activePresetId: merged.activePresetId,
-            presets: merged.presets,
-            docked: merged.docked,
-            deviceSerial: merged.deviceSerial,
-        });
+        setAndroidPanelSetting(body.androidPanel);
     }
     if (body.collaborationPanel && typeof body.collaborationPanel.clientId === 'string') {
         setCollaborationPanelSetting(body.collaborationPanel.clientId, body.collaborationPanel.state);
@@ -8089,7 +8143,7 @@ router.post('/agent-hooks/:agent/install', async (req, res) => {
     const agent = req.params.agent;
     try {
         const result = await installHooksForSlug(agent);
-        res.json({ agent, ...result, state: 'installed' });
+        res.json({ agent, ...result, state: await runtimeHooksStateForSlug(agent) });
     }
     catch (error) {
         res.status(400).json({ error: error.message });
@@ -9065,16 +9119,18 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
     let clientPaused = false;
     let replayRequest = null;
     let replayRetryTimer = null;
-    let clientCols = session.cols;
-    let clientRows = session.rows;
-    let initialAttachmentResize = true;
     let tmuxSizeOwnershipSupported = false;
     let initialScreen = null;
-    if (initialDimensions && options.independentTmux) {
-        clientCols = initialDimensions.cols;
-        clientRows = initialDimensions.rows;
-    }
     const ownTmux = session.mode === 'tmux' && options.independentTmux === true;
+    const displayGeometry = ownTmux ? new TmuxDisplayGeometry(session, runTmux, session.tmuxSessionName, () => {
+        const pids = new Set();
+        for (const client of wsClients.get(sessionId)?.values() ?? []) {
+            const pid = tmuxAttachments.get(client)?.pid;
+            if (pid !== undefined)
+                pids.add(pid);
+        }
+        return pids;
+    }, initialDimensions) : null;
     if (ownTmux)
         independentTmuxClients.add(ws);
     const attachment = ownTmux ? new TerminalClientAttachment(async (cols, rows) => {
@@ -9083,13 +9139,7 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
         const tmuxBinary = getTmuxBinary();
         const supportsFeatures = await supportsTmuxClientFeatures(tmuxBinary);
         tmuxSizeOwnershipSupported = supportsFeatures;
-        // The metadata observer must not choose the pane size while a browser
-        // owns an attached client. Resolve by exact PID, never another client.
-        const raw = await runTmux(['list-clients', '-t', session.tmuxSessionName, '-F', '#{client_pid} #{client_tty}']);
-        const metadata = raw.split('\n').map(line => line.trim().split(/\s+/))
-            .find(([pid]) => pid === String(session.ptyProcess.pid));
-        if (metadata?.[1] && supportsFeatures)
-            await runTmux(['refresh-client', '-t', metadata[1], '-f', 'ignore-size']);
+        await displayGeometry.prepareAttach({ cols, rows }, supportsFeatures);
         const env = buildInteractiveColorEnvironment({ ...process.env, PATH: buildAugmentedPath() });
         delete env.TMUX;
         delete env.TMUX_PANE;
@@ -9134,7 +9184,7 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
             attachment.close();
             initialScreen?.cancel();
             initialScreen = null;
-            initialAttachmentResize = true;
+            displayGeometry.reset();
             delivery.setActive(false); // Discard only this observer's obsolete stream.
         }
         replayRequest = (async () => {
@@ -9175,20 +9225,16 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
                 if (delivery.active) {
                     const screen = new TmuxInitialScreen();
                     initialScreen = screen;
-                    if (!await attachment.open(clientCols, clientRows)) {
+                    if (!await attachment.open(displayGeometry.size.cols, displayGeometry.size.rows)) {
                         screen.cancel();
                         return;
                     }
                     const first = await screen.ready;
-                    if (initialScreen === screen)
-                        initialScreen = null;
                     if (first.status === 'cancelled' || ws.readyState !== ws.OPEN)
                         return;
                     if (first.status === 'overflow')
                         throw new Error('Initial tmux screen exceeded output budget');
-                    // Bootstrap with the actual first PTY redraw, not a standalone empty
-                    // reset followed by the screen in a second client write. Subsequent
-                    // bytes already wait in delivery and retain their original ordering.
+                    initialScreen = null;
                     replayChunks = first.data ? [first.data] : ['\x1bc'];
                 }
                 else {
@@ -9228,8 +9274,8 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
                 streamEpoch: TERMINAL_STREAM_EPOCH,
                 outputProtocol: options.flowControl ? 2 : undefined,
                 copyModeInput: ownTmux,
-                cols: session.cols,
-                rows: session.rows,
+                cols: displayGeometry?.size.cols ?? session.cols,
+                rows: displayGeometry?.size.rows ?? session.rows,
                 runtime,
                 ptyBackend: session.ptyBackend || 'unknown',
                 mode: session.mode,
@@ -9280,7 +9326,11 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
             }
             else if (ws.readyState === ws.OPEN)
                 ws.close(1011, 'Replay unavailable');
-        }).finally(() => { replayRequest = null; });
+        }).finally(() => {
+            initialScreen?.cancel();
+            initialScreen = null;
+            replayRequest = null;
+        });
         return replayRequest;
     };
     if (attachment)
@@ -9359,38 +9409,19 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
                     if (Number.isFinite(cols) && Number.isFinite(rows) && cols > 0 && rows > 0) {
                         if (attachment) {
                             await enqueueTmuxIo(session, async () => {
-                                const cleanCols = Math.floor(cols), cleanRows = Math.floor(rows);
-                                const displayPids = new Set();
-                                for (const client of wsClients.get(sessionId)?.values() ?? []) {
-                                    const pid = tmuxAttachments.get(client)?.pid;
-                                    if (pid !== undefined)
-                                        displayPids.add(pid);
-                                }
-                                if (tmuxSizeOwnershipSupported) {
-                                    await claimTmuxSize(runTmux, session.tmuxSessionName, attachment.pid, displayPids);
-                                }
-                                const sameSize = clientCols === cleanCols && clientRows === cleanRows;
-                                const ok = sameSize ? attachment.attached : attachment.resize(cleanCols, cleanRows);
-                                if (ok) {
-                                    // The first resize confirms the grid supplied at attachment.
-                                    // Its PTY is already drawing that grid; forcing refresh-client
-                                    // here repeats the initial clear/full redraw. Later same-size
-                                    // requests remain explicit display recovery requests.
-                                    const needsRedraw = sameSize && !initialAttachmentResize;
-                                    initialAttachmentResize = false;
-                                    clientCols = cleanCols;
-                                    clientRows = cleanRows;
+                                const result = await displayGeometry.resize(attachment, { cols, rows }, tmuxSizeOwnershipSupported);
+                                if (result.ok) {
                                     session.lastActivity = Date.now();
                                     broadcastJsonWs(sessionId, {
-                                        type: 'pty-size', cols: clientCols, rows: clientRows, source: `ws-resize:${clientId}`,
+                                        type: 'pty-size', cols: result.cols, rows: result.rows, source: `ws-resize:${clientId}`,
                                     }, clientId);
-                                    if (needsRedraw)
+                                    if (result.redraw)
                                         await redrawTmuxClient(runTmux, session.tmuxSessionName, attachment.pid);
                                 }
                                 if (ws.readyState === ws.OPEN)
                                     ws.send(JSON.stringify({
                                         type: 'resize-ack', seq: typeof msg.seq === 'number' ? msg.seq : undefined,
-                                        ok, cols: clientCols, rows: clientRows, screenSyncPending: false,
+                                        ok: result.ok, cols: result.cols, rows: result.rows, screenSyncPending: false,
                                     }));
                             });
                             break;
@@ -9475,10 +9506,17 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
                         break;
                     outputWanted = msg.active;
                     const resumed = delivery.setActive(outputWanted);
-                    if (!delivery.active)
+                    if (!delivery.active) {
                         attachment?.close();
+                        initialScreen?.cancel();
+                    }
                     if (resumed && delivery.active) {
-                        void sendReplay(typeof msg.since === 'number' ? msg.since : 0, typeof msg.epoch === 'string' ? msg.epoch : undefined);
+                        // A rapid hide/show can resume while the cancelled first redraw
+                        // is still unwinding. Start a new attachment after it has settled.
+                        await replayRequest;
+                        if (ws.readyState === ws.OPEN && outputWanted) {
+                            void sendReplay(typeof msg.since === 'number' ? msg.since : 0, typeof msg.epoch === 'string' ? msg.epoch : undefined);
+                        }
                     }
                     break;
                 }

package/dist/server/shared/androidDevices.js

@@ -0,0 +1,64 @@
+export function isValidAndroidSerial(serial) {
+    if (!serial || serial.length > 128 || !/^(?:[0-9a-zA-Z_.:\-]+|\[[0-9a-fA-F:.]+\]:\d{1,5})$/.test(serial))
+        return false;
+    return serial.startsWith('[') || /^[^:]+:\d+$/.test(serial) ? normalizeAndroidAddress(serial) !== null : true;
+}
+export function normalizeAndroidAddress(raw) {
+    let value = raw.trim();
+    const pasted = /^[a-z]+:\/\/([^/]+)/i.exec(value);
+    if (pasted)
+        value = pasted[1];
+    value = value.replace(/^\/+|\/+$/g, '');
+    const v6 = /^\[([^\]]+)\](?::(\d{1,5}))?$/.exec(value);
+    if (v6) {
+        try {
+            new URL(`http://[${v6[1]}]`);
+        }
+        catch {
+            return null;
+        }
+        const port = v6[2] ?? '5555';
+        return Number(port) >= 1 && Number(port) <= 65535 ? `[${v6[1]}]:${port}` : null;
+    }
+    if (!/^[0-9a-zA-Z_.\-]+(?::\d{1,5})?$/.test(value))
+        return null;
+    const [host, port = '5555'] = value.split(':');
+    if (/^\d+\.\d+\.\d+\.\d+$/.test(host) && host.split('.').some(part => Number(part) > 255))
+        return null;
+    return Number(port) >= 1 && Number(port) <= 65535 ? `${host}:${port}` : null;
+}
+export function androidDeviceKey(device) {
+    return device.physicalId ? `physical:${device.physicalId}` : `serial:${device.serial}`;
+}
+export function groupAndroidDevices(devices, selectedSerial = '') {
+    const groups = new Map();
+    const rank = (device) => (device.state === 'device' ? 0 : 10)
+        + (device.serial === selectedSerial ? 0 : !device.isNetwork ? 1 : device.serial.startsWith('[') ? 3 : 2);
+    for (const device of devices) {
+        const key = androidDeviceKey(device), group = groups.get(key);
+        if (!group)
+            groups.set(key, { key, device, routes: [device] });
+        else {
+            group.routes.push(device);
+            if (rank(device) < rank(group.device))
+                group.device = device;
+        }
+    }
+    return [...groups.values()];
+}
+/** Never switch an explicit selection to an unrelated phone. */
+export function resolveAndroidSelection(devices, serial, physicalId) {
+    const groups = groupAndroidDevices(devices, serial);
+    const exact = devices.find(device => device.serial === serial);
+    const identity = physicalId || exact?.physicalId;
+    if (identity)
+        return groups.find(group => group.device.physicalId === identity)?.device;
+    if (serial)
+        return exact;
+    const ready = groups.filter(group => group.device.state === 'device');
+    return ready.length === 1 ? ready[0].device : undefined;
+}
+export function androidRouteAccess(grants, serial) {
+    const matching = grants?.filter(grant => grant.serial === serial) || [];
+    return matching.some(grant => grant.access === 'control') ? 'control' : matching.length ? 'view' : undefined;
+}