nterminal 1.2.79 → 1.2.81

package/dist/server/terminal/TmuxPtyAdapter.js

@@ -1,13 +1,17 @@
 import { spawnSync } from 'node:child_process';
-import { closeSync, existsSync, fstatSync, openSync, readFileSync, readdirSync, readSync, realpathSync, statSync } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { access, open as openFile, readFile, readdir, realpath, stat } from 'node:fs/promises';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 import * as nodePty from 'node-pty';
 import path from 'node:path';
+import { normalizeTerminalTitle, PtySessionUnavailableError } from './PtyAdapter.js';
 import { resolveCodexTranscriptFromOpenFds, resolveCodexTranscriptFromProcessLogs } from './codexTranscriptSource.js';
 import { isSessionId } from './sessionId.js';
-import { processStartTicksToSeconds, readProcessCwd, readProcessEnvValues, readProcessStartTicks } from './procfs.js';
+import { processStartTicksToSecondsAsync, readProcessCwdAsync, readProcessEnvValuesAsync, readProcessStartTicksAsync } from './procfs.js';
 import { TtlCache } from './ttlCache.js';
+import { KeyedSingleFlight, mapWithConcurrency, runCommand } from './asyncCommand.js';
 // Dedicated socket name so NTerminal's tmux server is completely isolated from
 // any tmux the operator runs themselves (different `-L` = different daemon).
 // Their `tmux ls` won't show our sessions, and our sessions don't pick up
@@ -22,9 +26,43 @@ const TRANSCRIPT_FILE_NEGATIVE_CACHE_TTL_MS = 20_000;
 // letting a history-paging burst (several page requests within seconds)
 // reuse one resolution instead of re-forking tmux/ps per page.
 const TRANSCRIPT_RESOLUTION_CACHE_TTL_MS = 3_000;
+const PROCESS_TREE_CACHE_TTL_MS = 1_000;
 const CLAUDE_TRANSCRIPT_START_SKEW_MS = 10_000;
 const CLAUDE_TRANSCRIPT_SAMPLE_BYTES = 512 * 1024;
+const CLAUDE_TRANSCRIPT_CACHE_LIMIT = 1_024;
+const TMUX_SYNC_TIMEOUT_MS = 750;
+const TMUX_SYNC_MAX_BUFFER_BYTES = 2 * 1024 * 1024;
+const TMUX_CREATE_TIMEOUT_MS = 5_000;
+const TMUX_HISTORY_TIMEOUT_MS = 5_000;
+const TMUX_HISTORY_MAX_BUFFER_BYTES = 8 * 1024 * 1024;
+const TMUX_HISTORY_CAPTURE_ATTEMPTS = 3;
+const TMUX_HISTORY_TOKEN_LINES = 128;
+const TMUX_SESSION_METADATA_CONCURRENCY = 8;
+const PENDING_CREATION_SESSION_PREFIX = 'nterminal-pending-';
+const CREATION_MARKER_OPTION = '@nterminal_creation_state';
+const PENDING_CREATION_MARKER_PREFIX = 'pending:';
+const CREATION_MARKER_NOT_OWNED_OUTPUT = 'nterminal-marker-not-owned';
 const transcriptFileCache = new TtlCache();
+const confirmedClaudeTranscripts = new Map();
+export function isMissingTmuxSessionError(error) {
+    const rawStderr = error?.stderr;
+    const stderr = typeof rawStderr === 'string'
+        ? rawStderr
+        : Buffer.isBuffer(rawStderr)
+            ? rawStderr.toString()
+            : '';
+    const message = error instanceof Error ? error.message : '';
+    return /(?:can't find (?:session|pane)(?::|\s*$)|no server running|no sessions?\b)/i.test(`${stderr}\n${message}`);
+}
+export function isCommandOutputLimitError(error) {
+    return error?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER';
+}
+function commandMayHaveCompleted(error) {
+    const commandError = error;
+    return commandError?.killed === true ||
+        typeof commandError?.signal === 'string' ||
+        commandError?.code === 'ETIMEDOUT';
+}
 // Wraps each PTY in a tmux session so shells survive `nterminalctl restart`
 // and NTerminal version updates without losing state. The operator never
 // interacts with tmux directly — the bundled `nterminal-tmux.conf` strips the
@@ -33,10 +71,30 @@ const transcriptFileCache = new TtlCache();
 export class TmuxPtyAdapter {
     configPath;
     socket;
+    commandRunner;
+    ptySpawner;
     transcriptResolutionCache = new TtlCache();
+    transcriptResolutionInflight = new KeyedSingleFlight();
+    processTreeCache = new TtlCache();
+    processTreeInflight = new KeyedSingleFlight();
+    historyTokenGeneration = randomBytes(16).toString('hex');
+    historyOutputGenerationBySession = new Map();
+    historyOutputUnreliableSessions = new Set();
+    panePidBySession = new Map();
+    inflightCreationSessions = new Set();
+    inflightFinalCreationMarkers = new Map();
+    pendingCreationCleanup = new Set();
+    pendingMarkerCleanup = new Map();
+    // listExisting() and pollSessions() both refresh panePidBySession. Serialize
+    // their complete catalog mutations so an older poll cannot clear a cache
+    // just refreshed for a lazy reattach.
+    catalogTail = Promise.resolve();
+    sessionCatalogLoaded = false;
     constructor(options = {}) {
         this.configPath = options.configPath ?? defaultConfigPath();
         this.socket = options.socket ?? TMUX_SOCKET;
+        this.commandRunner = options.commandRunner ?? runCommand;
+        this.ptySpawner = options.ptySpawner ?? nodePty.spawn;
     }
     // Returns an instance only when `tmux` is on PATH and the bundled config
     // file actually exists. The config-existence check prevents a confusing
@@ -46,7 +104,12 @@ export class TmuxPtyAdapter {
     // tmux (or with the config missing) still works — it just loses the
     // across-restart persistence.
     static detect(options = {}) {
-        const probe = spawnSync('sh', ['-c', 'command -v tmux'], { stdio: ['ignore', 'pipe', 'ignore'] });
+        const probe = spawnSync('sh', ['-c', 'command -v tmux'], {
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: TMUX_SYNC_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
+            maxBuffer: TMUX_SYNC_MAX_BUFFER_BYTES
+        });
         if (probe.status !== 0) {
             return null;
         }
@@ -56,114 +119,572 @@ export class TmuxPtyAdapter {
         }
         return new TmuxPtyAdapter({ ...options, configPath });
     }
-    spawn(options) {
+    async spawn(options) {
         if (!options.sessionId) {
             throw new Error('TmuxPtyAdapter.spawn requires a sessionId');
         }
-        // `new-session -A` = attach to the named session if it already exists,
-        // otherwise create it. On the create path tmux runs `shell` inside the
-        // session in `-c cwd`; on the attach path both are ignored, which is
-        // exactly the behavior we want for the "NTerminal restarted, reattach to
-        // live shells" flow.
-        //
-        // -n <title> sets the window name only on the create path. On attach it
-        // is ignored — we don't want a re-attach to overwrite a name the
-        // operator already chose via the rename UI in a previous session.
+        const creationToken = randomBytes(8).toString('hex');
+        const pendingSessionId = `${PENDING_CREATION_SESSION_PREFIX}${options.sessionId}-${creationToken}`;
+        const pendingMarker = `${PENDING_CREATION_MARKER_PREFIX}${creationToken}`;
+        const committedMarker = `committed:${creationToken}`;
+        this.inflightCreationSessions.add(pendingSessionId);
         const args = [
             '-L',
             this.socket,
             '-f',
             this.configPath,
             'new-session',
-            '-A',
+            '-d',
             '-s',
-            options.sessionId,
+            pendingSessionId,
             '-c',
             options.cwd
         ];
         if (options.title) {
-            args.push('-n', sanitizeWindowName(options.title));
+            args.push('-n', normalizeTerminalTitle(options.title));
         }
         args.push(options.shell);
-        const pty = nodePty.spawn('tmux', args, {
+        try {
+            await this.commandRunner('tmux', args, {
+                cwd: options.cwd,
+                env: options.env,
+                timeoutMs: TMUX_CREATE_TIMEOUT_MS,
+                maxBuffer: TMUX_SYNC_MAX_BUFFER_BYTES
+            });
+        }
+        catch (error) {
+            if (commandMayHaveCompleted(error)) {
+                await this.cleanupSpawnedSessionsOrThrow([pendingSessionId], error);
+            }
+            this.inflightCreationSessions.delete(pendingSessionId);
+            throw error;
+        }
+        try {
+            await this.setCreationMarker(pendingSessionId, pendingMarker);
+        }
+        catch (error) {
+            return await this.cleanupSpawnedSessionsOrThrow([pendingSessionId], error);
+        }
+        const panePid = await this.readPanePidAsync(pendingSessionId);
+        if (panePid === null) {
+            return await this.cleanupSpawnedSessionsOrThrow([pendingSessionId], new Error('tmux pane pid unavailable after session creation'));
+        }
+        this.inflightFinalCreationMarkers.set(options.sessionId, pendingMarker);
+        try {
+            await this.commandRunner('tmux', [
+                '-L',
+                this.socket,
+                '-f',
+                this.configPath,
+                'rename-session',
+                '-t',
+                exactSessionTarget(pendingSessionId),
+                options.sessionId
+            ], { timeoutMs: TMUX_CREATE_TIMEOUT_MS });
+        }
+        catch (error) {
+            const finalMarkerClaims = new Map();
+            if (commandMayHaveCompleted(error)) {
+                const marker = await this.readCreationMarker(options.sessionId);
+                if (marker.kind === 'found' && marker.value === pendingMarker) {
+                    finalMarkerClaims.set(options.sessionId, creationToken);
+                }
+                else if (marker.kind === 'missing' || marker.kind === 'unavailable') {
+                    // A timed-out tmux client may have handed the rename request to the
+                    // server just before it was killed. Keep the ownership claim even
+                    // when the immediate probe sees no final name; a later catalog pass
+                    // verifies the marker before hiding or deleting anything.
+                    finalMarkerClaims.set(options.sessionId, creationToken);
+                }
+            }
+            this.inflightFinalCreationMarkers.delete(options.sessionId);
+            return await this.cleanupSpawnedSessionsOrThrow([pendingSessionId], error, finalMarkerClaims);
+        }
+        try {
+            await this.setCreationMarker(options.sessionId, committedMarker);
+        }
+        catch (error) {
+            return await this.cleanupSpawnedSessionsOrThrow([pendingSessionId], error, new Map([[options.sessionId, creationToken]]));
+        }
+        let pty;
+        try {
+            pty = this.attachClient(options, panePid);
+        }
+        catch (error) {
+            return await this.cleanupSpawnedSessionsOrThrow([pendingSessionId], error, new Map([[options.sessionId, creationToken]]));
+        }
+        this.inflightCreationSessions.delete(pendingSessionId);
+        this.inflightFinalCreationMarkers.delete(options.sessionId);
+        this.pendingCreationCleanup.delete(pendingSessionId);
+        this.panePidBySession.delete(pendingSessionId);
+        this.panePidBySession.set(options.sessionId, panePid);
+        return pty;
+    }
+    async setCreationMarker(sessionId, marker) {
+        await this.commandRunner('tmux', [
+            '-L',
+            this.socket,
+            '-f',
+            this.configPath,
+            'set-option',
+            '-t',
+            exactWindowTarget(sessionId),
+            CREATION_MARKER_OPTION,
+            marker
+        ], { timeoutMs: TMUX_CREATE_TIMEOUT_MS });
+    }
+    async readCreationMarker(sessionId) {
+        try {
+            const result = await this.commandRunner('tmux', [
+                '-L',
+                this.socket,
+                '-f',
+                this.configPath,
+                'display-message',
+                '-p',
+                '-t',
+                exactWindowTarget(sessionId),
+                `#{${CREATION_MARKER_OPTION}}`
+            ], { timeoutMs: TMUX_CREATE_TIMEOUT_MS });
+            return { kind: 'found', value: result.stdout.trim() };
+        }
+        catch (error) {
+            return isMissingTmuxSessionError(error)
+                ? { kind: 'missing' }
+                : { kind: 'unavailable' };
+        }
+    }
+    async readTmuxSessionInternalId(sessionId) {
+        try {
+            const result = await this.commandRunner('tmux', [
+                '-L',
+                this.socket,
+                '-f',
+                this.configPath,
+                'display-message',
+                '-p',
+                '-t',
+                exactWindowTarget(sessionId),
+                '#{session_id}'
+            ], { timeoutMs: TMUX_CREATE_TIMEOUT_MS });
+            const value = result.stdout.trim();
+            if (!/^\$\d+$/.test(value)) {
+                return {
+                    kind: 'unavailable',
+                    error: new Error(`tmux returned an invalid internal session id for ${sessionId}`)
+                };
+            }
+            return { kind: 'found', value };
+        }
+        catch (error) {
+            return isMissingTmuxSessionError(error)
+                ? { kind: 'missing' }
+                : { kind: 'unavailable', error };
+        }
+    }
+    async destroySessionIfCreationMarkerOwned(sessionId, creationToken) {
+        if (!isCreationToken(creationToken)) {
+            return { kind: 'not-owned' };
+        }
+        const internalId = await this.readTmuxSessionInternalId(sessionId);
+        if (internalId.kind !== 'found') {
+            return internalId;
+        }
+        const markerMatches = `#{||:#{==:#{${CREATION_MARKER_OPTION}},${PENDING_CREATION_MARKER_PREFIX}${creationToken}},#{==:#{${CREATION_MARKER_OPTION}},committed:${creationToken}}}`;
+        try {
+            const result = await this.commandRunner('tmux', [
+                '-L',
+                this.socket,
+                '-f',
+                this.configPath,
+                'if-shell',
+                '-F',
+                '-t',
+                `${internalId.value}:0`,
+                markerMatches,
+                `kill-session -t ${internalId.value}`,
+                `display-message -p ${CREATION_MARKER_NOT_OWNED_OUTPUT}`
+            ], { timeoutMs: TMUX_CREATE_TIMEOUT_MS });
+            return {
+                kind: result.stdout.trim() === CREATION_MARKER_NOT_OWNED_OUTPUT
+                    ? 'not-owned'
+                    : 'destroyed'
+            };
+        }
+        catch (error) {
+            return isMissingTmuxSessionError(error)
+                ? { kind: 'missing' }
+                : { kind: 'unavailable', error };
+        }
+    }
+    async cleanupSpawnedSessionsOrThrow(sessionIds, cause, markerClaims = new Map()) {
+        const cleanupErrors = [];
+        const unresolved = new Set(sessionIds);
+        const unresolvedMarkerClaims = new Map(markerClaims);
+        for (const sessionId of unresolved) {
+            this.inflightCreationSessions.delete(sessionId);
+            this.pendingCreationCleanup.add(sessionId);
+        }
+        for (const [sessionId, creationToken] of unresolvedMarkerClaims) {
+            this.inflightFinalCreationMarkers.delete(sessionId);
+            this.pendingMarkerCleanup.set(sessionId, creationToken);
+        }
+        for (const sessionId of [...unresolved]) {
+            for (let attempt = 0; attempt < 2; attempt += 1) {
+                try {
+                    await this.commandRunner('tmux', [
+                        '-L',
+                        this.socket,
+                        '-f',
+                        this.configPath,
+                        'kill-session',
+                        '-t',
+                        exactSessionTarget(sessionId)
+                    ], { timeoutMs: TMUX_CREATE_TIMEOUT_MS });
+                    unresolved.delete(sessionId);
+                    this.clearSessionCaches(sessionId);
+                    break;
+                }
+                catch (error) {
+                    if (isMissingTmuxSessionError(error)) {
+                        unresolved.delete(sessionId);
+                        this.clearSessionCaches(sessionId);
+                        break;
+                    }
+                    cleanupErrors.push(error);
+                }
+            }
+        }
+        for (const [sessionId, creationToken] of [...unresolvedMarkerClaims]) {
+            for (let attempt = 0; attempt < 2; attempt += 1) {
+                const cleanup = await this.destroySessionIfCreationMarkerOwned(sessionId, creationToken);
+                if (cleanup.kind === 'missing') {
+                    // The final name may appear after a timed-out rename client exits.
+                    // Keep the marker claim for a later catalog pass, but preserve the
+                    // original creation error instead of replacing it with a cleanup
+                    // error when ownership cannot be checked yet.
+                    unresolvedMarkerClaims.delete(sessionId);
+                    break;
+                }
+                if (cleanup.kind === 'unavailable') {
+                    cleanupErrors.push(cleanup.error);
+                    continue;
+                }
+                if (cleanup.kind === 'not-owned') {
+                    unresolvedMarkerClaims.delete(sessionId);
+                    this.pendingMarkerCleanup.delete(sessionId);
+                    break;
+                }
+                if (cleanup.kind === 'destroyed') {
+                    unresolvedMarkerClaims.delete(sessionId);
+                    this.clearSessionCaches(sessionId);
+                    break;
+                }
+            }
+        }
+        if (unresolved.size === 0 && unresolvedMarkerClaims.size === 0) {
+            throw cause;
+        }
+        const quarantined = [...unresolved, ...unresolvedMarkerClaims.keys()];
+        throw new AggregateError([cause, ...cleanupErrors], `tmux sessions ${quarantined.join(', ')} are quarantined pending cleanup after failed creation`);
+    }
+    clearSessionCaches(sessionId) {
+        this.panePidBySession.delete(sessionId);
+        this.pendingCreationCleanup.delete(sessionId);
+        this.pendingMarkerCleanup.delete(sessionId);
+        this.historyOutputGenerationBySession.delete(sessionId);
+        this.historyOutputUnreliableSessions.delete(sessionId);
+        this.transcriptResolutionCache.delete(sessionId);
+    }
+    isInflightFinalCreation(sessionId, marker) {
+        const inflightMarker = this.inflightFinalCreationMarkers.get(sessionId);
+        return inflightMarker !== undefined &&
+            creationMarkerBelongsToToken(marker, creationTokenFromMarker(inflightMarker));
+    }
+    attachExisting(options) {
+        const panePid = this.panePidBySession.get(options.sessionId);
+        if (panePid === undefined) {
+            if (this.sessionCatalogLoaded) {
+                throw new PtySessionUnavailableError(options.sessionId);
+            }
+            throw new Error('tmux session catalog is not available yet');
+        }
+        return this.attachClient(options, panePid);
+    }
+    attachClient(options, panePid) {
+        const pty = this.ptySpawner('tmux', [
+            '-L',
+            this.socket,
+            '-f',
+            this.configPath,
+            'attach-session',
+            '-t',
+            exactSessionTarget(options.sessionId)
+        ], {
             name: 'xterm-256color',
             cols: options.cols,
             rows: options.rows,
             cwd: options.cwd,
             env: options.env
         });
-        const panePid = this.readPanePidWithRetry(options.sessionId) ?? pty.pid;
-        return wrapTmuxPty(pty, this.socket, this.configPath, options.sessionId, panePid);
-    }
-    listExisting() {
-        // Pull session name, the (single) window's name, and tmux's current pane
-        // path in one call so TerminalManager can restore both title and cwd
-        // without a per-session round-trip. The custom delimiter `\t` avoids
-        // ambiguity for spaces and pipes.
-        const result = spawnSync('tmux', [
-            '-L',
-            this.socket,
-            '-f',
-            this.configPath,
-            'list-sessions',
-            '-F',
-            '#{session_name}\t#{=128:window_name}\t#{pane_current_path}'
-        ], { stdio: ['ignore', 'pipe', 'pipe'] });
-        if (result.status !== 0) {
-            // Common when no server is running yet (no sessions exist). tmux exits
-            // non-zero with stderr "no server running"; treat as empty list.
-            return [];
-        }
-        return result.stdout
-            .toString()
-            .split('\n')
-            .filter(Boolean)
-            .map((line) => {
-            const firstTab = line.indexOf('\t');
-            if (firstTab === -1) {
-                return { sessionId: line };
+        this.panePidBySession.set(options.sessionId, panePid);
+        this.historyOutputUnreliableSessions.delete(options.sessionId);
+        this.bumpHistoryOutputGeneration(options.sessionId);
+        return wrapTmuxPty(pty, panePid, () => this.bumpHistoryOutputGeneration(options.sessionId), () => {
+            this.historyOutputUnreliableSessions.add(options.sessionId);
+            this.bumpHistoryOutputGeneration(options.sessionId);
+        }, () => {
+            this.historyOutputUnreliableSessions.delete(options.sessionId);
+            this.bumpHistoryOutputGeneration(options.sessionId);
+        });
+    }
+    bumpHistoryOutputGeneration(sessionId) {
+        const generation = this.historyOutputGenerationBySession.get(sessionId) ?? 0;
+        this.historyOutputGenerationBySession.set(sessionId, generation + 1);
+    }
+    async serializeCatalog(operation) {
+        const previous = this.catalogTail;
+        let release;
+        const gate = new Promise((resolve) => {
+            release = resolve;
+        });
+        // Advance the tail before awaiting the prior operation. A caller that
+        // arrives while this one is waiting will therefore queue behind it.
+        this.catalogTail = previous.then(() => gate, () => gate);
+        try {
+            await previous;
+            return await operation();
+        }
+        finally {
+            release();
+        }
+    }
+    async listExisting() {
+        return await this.serializeCatalog(() => this.listExistingUnserialized());
+    }
+    async listExistingUnserialized() {
+        // Keep variable strings out of the catalog: tabs and newlines are legal in
+        // cwd components. The stable tmux pane id ties subsequent metadata reads to
+        // the cataloged pane even if another session reuses the same visible name.
+        let stdout;
+        try {
+            const result = await this.commandRunner('tmux', [
+                '-L',
+                this.socket,
+                '-f',
+                this.configPath,
+                'list-panes',
+                '-a',
+                '-F',
+                `#{session_name}\t#{pane_pid}\t#{pane_id}\t#{pid}\t#{session_created}\t#{${CREATION_MARKER_OPTION}}`
+            ], {
+                timeoutMs: TMUX_SYNC_TIMEOUT_MS,
+                maxBuffer: TMUX_SYNC_MAX_BUFFER_BYTES
+            });
+            stdout = result.stdout;
+        }
+        catch (error) {
+            if (isMissingTmuxSessionError(error)) {
+                this.sessionCatalogLoaded = true;
+                this.clearUnavailableSessionCaches();
+                return [];
             }
-            const secondTab = line.indexOf('\t', firstTab + 1);
-            const sessionId = line.slice(0, firstTab);
-            const title = secondTab === -1 ? line.slice(firstTab + 1) : line.slice(firstTab + 1, secondTab);
-            const cwd = secondTab === -1 ? '' : line.slice(secondTab + 1);
-            if (!sessionId) {
-                return null;
+            throw error;
+        }
+        const listedSessions = parseFixedTmuxSessionCatalog(stdout);
+        if (!listedSessions) {
+            throw new Error('tmux returned an invalid fixed-field session catalog');
+        }
+        const liveSessionIds = new Set();
+        const restorableSessions = [];
+        for (const session of listedSessions) {
+            liveSessionIds.add(session.sessionId);
+            if (isPendingCreationSessionId(session.sessionId)) {
+                if (!this.inflightCreationSessions.has(session.sessionId)) {
+                    this.pendingCreationCleanup.add(session.sessionId);
+                }
+                continue;
+            }
+            if (this.isInflightFinalCreation(session.sessionId, session.creationMarker)) {
+                continue;
+            }
+            if (session.creationMarker.startsWith(PENDING_CREATION_MARKER_PREFIX)) {
+                this.pendingMarkerCleanup.set(session.sessionId, creationTokenFromMarker(session.creationMarker));
+                continue;
+            }
+            restorableSessions.push(session);
+        }
+        for (const sessionId of this.panePidBySession.keys()) {
+            if (!liveSessionIds.has(sessionId)) {
+                if (!this.inflightCreationSessions.has(sessionId)) {
+                    this.clearSessionCaches(sessionId);
+                }
+            }
+        }
+        await this.reconcilePendingCreationCleanup(liveSessionIds);
+        await this.reconcilePendingMarkerCleanup(liveSessionIds);
+        const hiddenSessions = new Set([
+            ...this.inflightCreationSessions,
+            ...this.pendingCreationCleanup,
+            ...this.pendingMarkerCleanup.keys()
+        ]);
+        const visibleSessions = restorableSessions.filter((session) => liveSessionIds.has(session.sessionId) &&
+            !hiddenSessions.has(session.sessionId));
+        const restoredSessions = await mapWithConcurrency(visibleSessions, TMUX_SESSION_METADATA_CONCURRENCY, async (session) => {
+            if (session.title !== undefined && session.cwd !== undefined) {
+                return {
+                    listed: session,
+                    persisted: toPersistedSession(session.sessionId, session.title, session.cwd)
+                };
+            }
+            return {
+                listed: session,
+                persisted: await this.readPersistedSessionMetadata(session)
+            };
+        });
+        const sessions = [];
+        for (const restored of restoredSessions) {
+            if (!restored.persisted) {
+                if (this.panePidBySession.get(restored.listed.sessionId) ===
+                    restored.listed.panePid) {
+                    this.clearSessionCaches(restored.listed.sessionId);
+                }
+                continue;
+            }
+            this.panePidBySession.set(restored.listed.sessionId, restored.listed.panePid);
+            sessions.push(restored.persisted);
+        }
+        this.sessionCatalogLoaded = true;
+        return sessions;
+    }
+    async readPersistedSessionMetadata(session) {
+        const paneId = session.paneId;
+        if (!paneId) {
+            return toPersistedSession(session.sessionId, '', '');
+        }
+        const readField = async (format) => {
+            const result = await this.commandRunner('tmux', [
+                '-L',
+                this.socket,
+                '-f',
+                this.configPath,
+                'display-message',
+                '-p',
+                '-t',
+                exactPaneIdTarget(paneId),
+                `#{pid}\t#{session_created}\t#{pane_pid}\t#{${CREATION_MARKER_OPTION}}\t#{session_name}\t${format}`
+            ], {
+                timeoutMs: TMUX_SYNC_TIMEOUT_MS,
+                maxBuffer: TMUX_SYNC_MAX_BUFFER_BYTES
+            });
+            const output = removeTmuxOutputTerminator(result.stdout);
+            const fields = splitFixedPrefix(output, 5);
+            if (!fields) {
+                throw new Error('tmux returned invalid pane metadata');
+            }
+            const [serverPidRaw = '', sessionCreatedRaw = '', panePidRaw = '', creationMarker = '', sessionId = '', value = ''] = fields;
+            const serverPid = Number(serverPidRaw);
+            const sessionCreated = Number(sessionCreatedRaw);
+            const panePid = Number(panePidRaw);
+            if (!Number.isInteger(serverPid) ||
+                serverPid <= 0 ||
+                !Number.isInteger(sessionCreated) ||
+                sessionCreated <= 0 ||
+                !Number.isInteger(panePid) ||
+                panePid <= 0) {
+                throw new Error('tmux returned invalid pane identity');
             }
             return {
                 sessionId,
-                ...(title ? { title } : {}),
-                ...(cwd ? { cwd } : {})
+                panePid,
+                serverPid,
+                sessionCreated,
+                creationMarker,
+                value
             };
-        })
-            .filter((session) => session !== null);
+        };
+        const [title, cwd] = await Promise.allSettled([
+            readField('#{window_name}'),
+            readField('#{pane_current_path}')
+        ]);
+        for (const result of [title, cwd]) {
+            if (result.status !== 'rejected') {
+                continue;
+            }
+            if (isMissingTmuxSessionError(result.reason)) {
+                return null;
+            }
+            throw result.reason;
+        }
+        if (title.status !== 'fulfilled' || cwd.status !== 'fulfilled') {
+            return null;
+        }
+        if (!tmuxMetadataMatchesCatalog(title.value, session) ||
+            !tmuxMetadataMatchesCatalog(cwd.value, session)) {
+            return null;
+        }
+        return toPersistedSession(session.sessionId, title.value.value, cwd.value.value);
     }
-    destroySession(sessionId) {
-        const result = spawnSync('tmux', ['-L', this.socket, '-f', this.configPath, 'kill-session', '-t', sessionId], { stdio: 'ignore' });
-        return result.status === 0;
+    async destroySession(sessionId) {
+        try {
+            await this.commandRunner('tmux', [
+                '-L',
+                this.socket,
+                '-f',
+                this.configPath,
+                'kill-session',
+                '-t',
+                exactSessionTarget(sessionId)
+            ]);
+        }
+        catch (error) {
+            if (!isMissingTmuxSessionError(error)) {
+                return false;
+            }
+        }
+        this.clearSessionCaches(sessionId);
+        return true;
     }
     async pollSessions() {
+        return await this.serializeCatalog(() => this.pollSessionsUnserialized());
+    }
+    async pollSessionsUnserialized() {
         // list-panes -a returns every pane across every session in one call.
         // We use one pane per session, so the result is one row per terminal.
         // `pane_current_command` is whichever process tmux sees as the
         // foreground in that pane (the shell when at a prompt, otherwise vim
         // / node / etc.). `pane_pid` is the root of that pane's process
         // subtree — we walk its descendants below to decide busy vs idle.
-        const result = spawnSync('tmux', [
-            '-L',
-            this.socket,
-            '-f',
-            this.configPath,
-            'list-panes',
-            '-a',
-            '-F',
-            '#{session_name}\t#{pane_pid}\t#{pane_current_command}'
-        ], { stdio: ['ignore', 'pipe', 'pipe'] });
+        let panesOutput;
+        let tree;
+        try {
+            const [panes, processTree] = await Promise.all([
+                this.commandRunner('tmux', [
+                    '-L',
+                    this.socket,
+                    '-f',
+                    this.configPath,
+                    'list-panes',
+                    '-a',
+                    '-F',
+                    `#{session_name}\t#{pane_pid}\t#{pane_current_command}\t#{${CREATION_MARKER_OPTION}}`
+                ]),
+                this.readProcessTreeSnapshot()
+            ]);
+            panesOutput = panes.stdout;
+            tree = processTree;
+        }
+        catch (error) {
+            if (isMissingTmuxSessionError(error)) {
+                this.sessionCatalogLoaded = true;
+                this.clearUnavailableSessionCaches();
+                return new Map();
+            }
+            throw error;
+        }
         const out = new Map();
-        if (result.status !== 0)
-            return out;
-        const tree = readProcessTree();
-        for (const line of result.stdout.toString().split('\n')) {
+        const rows = [];
+        for (const line of panesOutput.split('\n')) {
             const trimmed = line.trim();
             if (!trimmed)
                 continue;
@@ -173,124 +694,365 @@ export class TmuxPtyAdapter {
             const sessionId = parts[0];
             const panePid = Number(parts[1]);
             const currentCommand = parts[2].trim();
+            const creationMarker = parts[3]?.trim() ?? '';
             if (!sessionId || !currentCommand || !Number.isFinite(panePid))
                 continue;
-            const reportedCommand = resolveTranscriptForegroundCommand(tree, panePid, currentCommand);
-            const busy = tree ? hasRunningDescendant(tree, panePid) : false;
-            out.set(sessionId, { currentCommand: reportedCommand, busy });
+            if (isPendingCreationSessionId(sessionId) && !this.inflightCreationSessions.has(sessionId)) {
+                this.pendingCreationCleanup.add(sessionId);
+            }
+            if (!isPendingCreationSessionId(sessionId) &&
+                creationMarker.startsWith(PENDING_CREATION_MARKER_PREFIX)) {
+                if (!this.isInflightFinalCreation(sessionId, creationMarker)) {
+                    this.pendingMarkerCleanup.set(sessionId, creationTokenFromMarker(creationMarker));
+                }
+            }
+            rows.push({ sessionId, panePid, currentCommand, creationMarker });
+        }
+        const liveSessionIds = new Set();
+        for (const row of rows) {
+            liveSessionIds.add(row.sessionId);
+            this.panePidBySession.set(row.sessionId, row.panePid);
+        }
+        await this.reconcilePendingCreationCleanup(liveSessionIds);
+        await this.reconcilePendingMarkerCleanup(liveSessionIds);
+        const hiddenSessions = new Set([
+            ...this.inflightCreationSessions,
+            ...this.pendingCreationCleanup,
+            ...this.pendingMarkerCleanup.keys()
+        ]);
+        const visibleRows = rows.filter((row) => liveSessionIds.has(row.sessionId) &&
+            !isPendingCreationSessionId(row.sessionId) &&
+            !row.creationMarker.startsWith(PENDING_CREATION_MARKER_PREFIX) &&
+            !this.isInflightFinalCreation(row.sessionId, row.creationMarker) &&
+            !hiddenSessions.has(row.sessionId));
+        const normalizedCommands = tree
+            ? await mapWithConcurrency(visibleRows, 8, async (row) => await normalizeTmuxCurrentCommandAsync(row.currentCommand, tree, row.panePid))
+            : visibleRows.map((row) => row.currentCommand);
+        for (let index = 0; index < visibleRows.length; index += 1) {
+            const row = visibleRows[index];
+            out.set(row.sessionId, {
+                currentCommand: normalizedCommands[index] ?? row.currentCommand,
+                busy: tree ? hasRunningDescendant(tree, row.panePid) : false
+            });
         }
+        for (const sessionId of this.panePidBySession.keys()) {
+            if (!liveSessionIds.has(sessionId)) {
+                if (!this.inflightCreationSessions.has(sessionId)) {
+                    this.clearSessionCaches(sessionId);
+                }
+            }
+        }
+        this.sessionCatalogLoaded = true;
         return out;
     }
-    setSessionTitle(sessionId, title) {
+    clearUnavailableSessionCaches() {
+        for (const sessionId of new Set([
+            ...this.panePidBySession.keys(),
+            ...this.pendingCreationCleanup,
+            ...this.pendingMarkerCleanup.keys()
+        ])) {
+            // A concurrent new-session can observe "no server" immediately before
+            // it creates the first tmux session. Its quarantine state belongs to
+            // spawn(), not this catalog snapshot.
+            if (!this.inflightCreationSessions.has(sessionId)) {
+                if (this.pendingMarkerCleanup.has(sessionId)) {
+                    // An uncertain rename can become visible after the transient
+                    // no-server observation. Preserve its marker claim until a future
+                    // catalog can prove whether the final name is ours.
+                    this.panePidBySession.delete(sessionId);
+                    this.pendingCreationCleanup.delete(sessionId);
+                    this.transcriptResolutionCache.delete(sessionId);
+                }
+                else {
+                    this.clearSessionCaches(sessionId);
+                }
+            }
+        }
+    }
+    async reconcilePendingCreationCleanup(liveSessionIds) {
+        for (const sessionId of [...this.pendingCreationCleanup]) {
+            if (this.inflightCreationSessions.has(sessionId)) {
+                continue;
+            }
+            if (!liveSessionIds.has(sessionId)) {
+                this.clearSessionCaches(sessionId);
+                continue;
+            }
+            if (await this.destroySession(sessionId)) {
+                liveSessionIds.delete(sessionId);
+            }
+        }
+    }
+    async reconcilePendingMarkerCleanup(liveSessionIds) {
+        for (const [sessionId, creationToken] of [...this.pendingMarkerCleanup]) {
+            const inflightMarker = this.inflightFinalCreationMarkers.get(sessionId);
+            if (inflightMarker !== undefined &&
+                creationMarkerBelongsToToken(inflightMarker, creationToken)) {
+                continue;
+            }
+            if (!liveSessionIds.has(sessionId)) {
+                this.clearSessionCaches(sessionId);
+                continue;
+            }
+            const cleanup = await this.destroySessionIfCreationMarkerOwned(sessionId, creationToken);
+            if (cleanup.kind === 'unavailable') {
+                continue;
+            }
+            if (cleanup.kind === 'destroyed') {
+                liveSessionIds.delete(sessionId);
+                this.clearSessionCaches(sessionId);
+                continue;
+            }
+            if (cleanup.kind === 'missing') {
+                const currentMarker = await this.readCreationMarker(sessionId);
+                if (currentMarker.kind === 'unavailable') {
+                    continue;
+                }
+                if (currentMarker.kind === 'missing') {
+                    liveSessionIds.delete(sessionId);
+                    this.clearSessionCaches(sessionId);
+                    continue;
+                }
+                if (creationMarkerBelongsToToken(currentMarker.value, creationToken)) {
+                    continue;
+                }
+                this.pendingMarkerCleanup.delete(sessionId);
+                continue;
+            }
+            // The name was reused or another actor committed the session. Drop only
+            // our quarantine claim; its live pane/cache belongs to that session.
+            this.pendingMarkerCleanup.delete(sessionId);
+        }
+    }
+    async setSessionTitle(sessionId, title) {
         // Single-window-per-session in our setup, so renaming the window is the
         // visible "session title" the operator perceives via the tab/pill label.
         // tmux's rename-session is also possible but session names are how we
         // address sessions in spawn/kill — those must stay stable, so we change
         // window name instead.
-        spawnSync('tmux', [
+        await this.commandRunner('tmux', [
             '-L',
             this.socket,
             '-f',
             this.configPath,
             'rename-window',
             '-t',
-            `${sessionId}:0`,
-            sanitizeWindowName(title)
-        ], { stdio: 'ignore' });
+            exactWindowTarget(sessionId),
+            normalizeTerminalTitle(title)
+        ]);
     }
-    scrollbackScroll(sessionId, lines) {
+    async scrollbackScroll(sessionId, lines) {
         const count = normalizeScrollLines(lines);
         if (count === 0) {
             return true;
         }
         if (lines < 0) {
-            const entered = spawnSync('tmux', ['-L', this.socket, '-f', this.configPath, 'copy-mode', '-t', sessionId], { stdio: 'ignore' });
-            if (entered.status !== 0) {
+            try {
+                await this.commandRunner('tmux', [
+                    '-L',
+                    this.socket,
+                    '-f',
+                    this.configPath,
+                    'copy-mode',
+                    '-t',
+                    exactPaneTarget(sessionId)
+                ]);
+            }
+            catch {
                 return false;
             }
-            return this.sendCopyModeCommand(sessionId, 'scroll-up', count);
+            return await this.sendCopyModeCommand(sessionId, 'scroll-up', count);
         }
-        const inMode = this.readPaneInMode(sessionId);
+        const inMode = await this.readPaneInMode(sessionId);
         if (inMode === null) {
             return false;
         }
         if (!inMode) {
             return true;
         }
-        if (!this.sendCopyModeCommand(sessionId, 'scroll-down', count)) {
+        if (!await this.sendCopyModeCommand(sessionId, 'scroll-down', count)) {
             return false;
         }
-        if (this.readScrollPosition(sessionId) === 0) {
-            return this.sendCopyModeCommand(sessionId, 'cancel', 1);
+        if (await this.readScrollPosition(sessionId) === 0) {
+            return await this.sendCopyModeCommand(sessionId, 'cancel', 1);
         }
         return true;
     }
-    cancelScrollbackMode(sessionId) {
-        const inMode = this.readPaneInMode(sessionId);
+    async cancelScrollbackMode(sessionId) {
+        const inMode = await this.readPaneInMode(sessionId);
         if (inMode === null) {
             return false;
         }
         if (!inMode) {
             return true;
         }
-        return this.sendCopyModeCommand(sessionId, 'cancel', 1);
+        return await this.sendCopyModeCommand(sessionId, 'cancel', 1);
     }
-    captureHistory(sessionId, options) {
+    async captureHistory(sessionId, options) {
         const limit = normalizeHistoryLimit(options.limit);
-        const metrics = this.readPaneMetrics(sessionId);
+        let pageLimit = limit;
+        for (let attempt = 0; attempt < TMUX_HISTORY_CAPTURE_ATTEMPTS; attempt += 1) {
+            const before = await this.readPaneHistorySnapshot(sessionId);
+            if (!before) {
+                return null;
+            }
+            const oldestLine = -before.metrics.historySize;
+            const newestLine = Math.max(0, before.metrics.paneHeight - 1);
+            const anchoredEnd = options.beforeLine === undefined
+                ? newestLine
+                : anchoredHistoryEndLine(options.beforeLine, options.snapshotHistorySize, before.metrics.historySize, {
+                    ...(options.snapshotHistoryLimit !== undefined
+                        ? { snapshotHistoryLimit: options.snapshotHistoryLimit }
+                        : {}),
+                    currentHistoryLimit: before.metrics.historyLimit,
+                    ...(options.snapshotHistoryToken !== undefined
+                        ? { snapshotHistoryToken: options.snapshotHistoryToken }
+                        : {}),
+                    currentHistoryToken: before.token,
+                    ...(options.snapshotPaneWidth !== undefined
+                        ? { snapshotPaneWidth: options.snapshotPaneWidth }
+                        : {}),
+                    currentPaneWidth: before.metrics.paneWidth
+                });
+            if (anchoredEnd === null) {
+                return invalidHistoryCapture(before);
+            }
+            const endLine = Math.min(newestLine, anchoredEnd);
+            if (endLine < oldestLine) {
+                if (before.metrics.historySize === 0 &&
+                    options.beforeLine === 0 &&
+                    options.snapshotHistorySize === undefined) {
+                    const after = await this.readPaneHistorySnapshot(sessionId);
+                    if (!after) {
+                        return null;
+                    }
+                    if (!historyCaptureIsStable(before, after)) {
+                        if (attempt === TMUX_HISTORY_CAPTURE_ATTEMPTS - 1) {
+                            return null;
+                        }
+                        continue;
+                    }
+                    return emptyHistoryCapture(after);
+                }
+                return invalidHistoryCapture(before);
+            }
+            const startLine = Math.max(oldestLine, endLine - pageLimit + 1);
+            let text;
+            try {
+                const result = await this.commandRunner('tmux', [
+                    '-L',
+                    this.socket,
+                    '-f',
+                    this.configPath,
+                    'capture-pane',
+                    '-p',
+                    '-e',
+                    '-J',
+                    '-S',
+                    String(startLine),
+                    '-E',
+                    String(endLine),
+                    '-t',
+                    exactPaneTarget(sessionId)
+                ], {
+                    timeoutMs: TMUX_HISTORY_TIMEOUT_MS,
+                    maxBuffer: TMUX_HISTORY_MAX_BUFFER_BYTES
+                });
+                text = normalizeCapturedPane(result.stdout);
+            }
+            catch (error) {
+                if (isCommandOutputLimitError(error) && pageLimit > 1) {
+                    pageLimit = Math.max(1, Math.floor(pageLimit / 2));
+                    attempt -= 1;
+                    continue;
+                }
+                return null;
+            }
+            const after = await this.readPaneHistorySnapshot(sessionId);
+            if (!after) {
+                return null;
+            }
+            if (!historyCaptureIsStable(before, after)) {
+                if (attempt === TMUX_HISTORY_CAPTURE_ATTEMPTS - 1) {
+                    return null;
+                }
+                continue;
+            }
+            return {
+                startLine,
+                endLine,
+                hasMore: startLine > oldestLine,
+                snapshotHistorySize: after.metrics.historySize,
+                snapshotHistoryLimit: after.metrics.historyLimit,
+                snapshotHistoryToken: after.token,
+                snapshotPaneWidth: after.metrics.paneWidth,
+                output: text ? [text] : []
+            };
+        }
+        return null;
+    }
+    async readPaneHistorySnapshot(sessionId) {
+        if (this.historyOutputUnreliableSessions.has(sessionId)) {
+            return null;
+        }
+        const metrics = await this.readPaneMetricsAsync(sessionId);
         if (!metrics) {
             return null;
         }
-        const oldestLine = -metrics.historySize;
-        const newestLine = Math.max(0, metrics.paneHeight - 1);
-        const requestedEnd = options.beforeLine === undefined ? newestLine : options.beforeLine - 1;
-        const endLine = Math.min(newestLine, requestedEnd);
-        if (endLine < oldestLine) {
-            return { startLine: oldestLine, endLine: oldestLine - 1, hasMore: false, output: [] };
+        if (metrics.historySize === 0) {
+            return {
+                metrics,
+                token: historySnapshotToken(metrics, '', this.historyTokenGeneration, this.historyOutputGenerationBySession.get(sessionId) ?? 0)
+            };
         }
-        const startLine = Math.max(oldestLine, endLine - limit + 1);
-        const result = spawnSync('tmux', [
-            '-L',
-            this.socket,
-            '-f',
-            this.configPath,
-            'capture-pane',
-            '-p',
-            '-e',
-            '-J',
-            '-S',
-            String(startLine),
-            '-E',
-            String(endLine),
-            '-t',
-            sessionId
-        ], { stdio: ['ignore', 'pipe', 'pipe'] });
-        if (result.status !== 0) {
+        const anchorStart = -metrics.historySize;
+        const anchorEnd = Math.min(-1, anchorStart + TMUX_HISTORY_TOKEN_LINES - 1);
+        try {
+            const anchor = await this.commandRunner('tmux', [
+                '-L',
+                this.socket,
+                '-f',
+                this.configPath,
+                'capture-pane',
+                '-p',
+                '-e',
+                '-J',
+                '-S',
+                String(anchorStart),
+                '-E',
+                String(anchorEnd),
+                '-t',
+                exactPaneTarget(sessionId)
+            ], {
+                timeoutMs: TMUX_HISTORY_TIMEOUT_MS,
+                maxBuffer: TMUX_HISTORY_MAX_BUFFER_BYTES
+            });
+            return {
+                metrics,
+                token: historySnapshotToken(metrics, anchor.stdout, this.historyTokenGeneration, this.historyOutputGenerationBySession.get(sessionId) ?? 0)
+            };
+        }
+        catch {
             return null;
         }
-        const text = normalizeCapturedPane(result.stdout.toString());
-        return {
-            startLine,
-            endLine,
-            hasMore: startLine > oldestLine,
-            output: text ? [text] : []
-        };
     }
-    resolveTranscriptSource(sessionId) {
+    async resolveTranscriptSource(sessionId) {
         const cached = this.transcriptResolutionCache.get(sessionId);
         if (cached) {
             return cached.value;
         }
-        const source = this.resolveTranscriptSourceUncached(sessionId);
-        this.transcriptResolutionCache.set(sessionId, source, TRANSCRIPT_RESOLUTION_CACHE_TTL_MS);
-        return source;
+        return this.transcriptResolutionInflight.run(sessionId, async () => {
+            const source = await this.resolveTranscriptSourceUncached(sessionId);
+            this.transcriptResolutionCache.set(sessionId, source, TRANSCRIPT_RESOLUTION_CACHE_TTL_MS);
+            return source;
+        });
     }
-    resolveTranscriptSourceUncached(sessionId) {
-        const panePid = this.readPanePid(sessionId);
+    async resolveTranscriptSourceUncached(sessionId) {
+        const panePid = this.panePidBySession.get(sessionId) ?? await this.readPanePidAsync(sessionId);
         if (panePid === null) {
             return null;
         }
-        const tree = readProcessTree();
+        const tree = await this.readProcessTreeSnapshot();
         if (!tree) {
             return null;
         }
@@ -298,13 +1060,13 @@ export class TmuxPtyAdapter {
         const processDepthByPid = new Map();
         // The pane root itself is a candidate too: `exec claude` replaces the
         // shell, leaving the agent as pane_pid with no descendants.
-        for (const { pid, depth } of listProcessPidsWithDepth(tree, panePid)) {
-            const args = readProcessArgs(pid);
+        await mapWithConcurrency(listProcessPidsWithDepth(tree, panePid), 8, async ({ pid, depth }) => {
+            const args = await readProcessArgsAsync(pid);
             if (args.length > 0) {
                 argsByPid.set(pid, args);
                 processDepthByPid.set(pid, depth);
             }
-        }
+        });
         let entries = [];
         let claudeSessionPending = false;
         for (const [pid, args] of argsByPid) {
@@ -313,7 +1075,7 @@ export class TmuxPtyAdapter {
                 continue;
             }
             if (findCommandArg(args, 'claude') !== -1) {
-                const claude = resolveClaudeCandidateForPid(pid, args);
+                const claude = await resolveClaudeCandidateForPidAsync(pid, args);
                 if (claude.pending) {
                     claudeSessionPending = true;
                 }
@@ -331,7 +1093,7 @@ export class TmuxPtyAdapter {
                 // The append-open rollout is the authoritative owner signal. Check
                 // it before descendant suppression: recent Codex releases spawn
                 // helpers such as codex-code-mode-host beneath the real process.
-                const live = resolveCodexTranscriptFromOpenFds(pid);
+                const live = await resolveCodexTranscriptFromOpenFds(pid);
                 if (live) {
                     entries.push({ candidate: live, rank: 'live', processDepth });
                     continue;
@@ -345,7 +1107,7 @@ export class TmuxPtyAdapter {
                 }
                 // Process logs reflect the thread the process wrote to most
                 // recently, so they outrank launch args, which freeze at startup.
-                const stated = resolveCodexTranscriptFromProcessLogs(pid) ?? extractCodexArgsCandidate(args);
+                const stated = (await resolveCodexTranscriptFromProcessLogs(pid)) ?? extractCodexArgsCandidate(args);
                 if (stated) {
                     entries.push({ candidate: stated, rank: 'stated', processDepth });
                 }
@@ -362,114 +1124,244 @@ export class TmuxPtyAdapter {
         if (!candidate) {
             return null;
         }
-        const matches = candidate.filePath ? [candidate.filePath] : findTranscriptFiles(candidate.provider, candidate.sessionId);
+        const matches = candidate.filePath ? [candidate.filePath] : await findTranscriptFilesAsync(candidate.provider, candidate.sessionId);
         if (matches.length !== 1) {
             return null;
         }
         return { provider: candidate.provider, sessionId: candidate.sessionId, filePath: matches[0] };
     }
-    readPaneMetrics(sessionId) {
-        const result = spawnSync('tmux', [
-            '-L',
-            this.socket,
-            '-f',
-            this.configPath,
-            'display-message',
-            '-p',
-            '-t',
-            sessionId,
-            '#{history_size}\t#{pane_height}'
-        ], { stdio: ['ignore', 'pipe', 'pipe'] });
-        if (result.status !== 0) {
-            return null;
+    async readPaneMetricsAsync(sessionId) {
+        try {
+            const result = await this.commandRunner('tmux', [
+                '-L', this.socket, '-f', this.configPath,
+                'display-message', '-p', '-t', exactPaneTarget(sessionId),
+                '#{history_size}\t#{history_limit}\t#{pane_height}\t#{pane_width}\t#{history_bytes}\t#{pane_id}\t#{session_created}'
+            ]);
+            const [historyRaw, limitRaw, heightRaw, widthRaw, bytesRaw, paneId, sessionCreatedRaw] = result.stdout.trim().split('\t');
+            const historySize = Number(historyRaw);
+            const historyLimit = Number(limitRaw);
+            const paneHeight = Number(heightRaw);
+            const paneWidth = Number(widthRaw);
+            const historyBytes = Number(bytesRaw);
+            const sessionCreated = Number(sessionCreatedRaw);
+            return Number.isInteger(historySize) &&
+                historySize >= 0 &&
+                Number.isInteger(historyLimit) &&
+                historyLimit > 0 &&
+                Number.isInteger(paneHeight) &&
+                paneHeight > 0 &&
+                Number.isInteger(paneWidth) &&
+                paneWidth > 0 &&
+                Number.isSafeInteger(historyBytes) &&
+                historyBytes >= 0 &&
+                typeof paneId === 'string' &&
+                /^%[0-9]+$/.test(paneId) &&
+                Number.isSafeInteger(sessionCreated) &&
+                sessionCreated > 0
+                ? { historySize, historyLimit, paneHeight, paneWidth, historyBytes, paneId, sessionCreated }
+                : null;
         }
-        const [historyRaw, heightRaw] = result.stdout.toString().trim().split('\t');
-        const historySize = Number(historyRaw);
-        const paneHeight = Number(heightRaw);
-        if (!Number.isInteger(historySize) || historySize < 0 || !Number.isInteger(paneHeight) || paneHeight <= 0) {
+        catch {
             return null;
         }
-        return { historySize, paneHeight };
     }
-    readPaneInMode(sessionId) {
-        const result = spawnSync('tmux', [
-            '-L',
-            this.socket,
-            '-f',
-            this.configPath,
-            'display-message',
-            '-p',
-            '-t',
-            sessionId,
-            '#{pane_in_mode}'
-        ], { stdio: ['ignore', 'pipe', 'pipe'] });
-        if (result.status !== 0) {
+    async readPaneInMode(sessionId) {
+        try {
+            const result = await this.commandRunner('tmux', [
+                '-L',
+                this.socket,
+                '-f',
+                this.configPath,
+                'display-message',
+                '-p',
+                '-t',
+                exactPaneTarget(sessionId),
+                '#{pane_in_mode}'
+            ]);
+            return result.stdout.trim() === '1';
+        }
+        catch {
             return null;
         }
-        return result.stdout.toString().trim() === '1';
     }
-    readScrollPosition(sessionId) {
-        const result = spawnSync('tmux', [
-            '-L',
-            this.socket,
-            '-f',
-            this.configPath,
-            'display-message',
-            '-p',
-            '-t',
-            sessionId,
-            '#{scroll_position}'
-        ], { stdio: ['ignore', 'pipe', 'pipe'] });
-        if (result.status !== 0) {
+    async readScrollPosition(sessionId) {
+        try {
+            const result = await this.commandRunner('tmux', [
+                '-L',
+                this.socket,
+                '-f',
+                this.configPath,
+                'display-message',
+                '-p',
+                '-t',
+                exactPaneTarget(sessionId),
+                '#{scroll_position}'
+            ]);
+            const position = Number(result.stdout.trim());
+            return Number.isInteger(position) && position >= 0 ? position : null;
+        }
+        catch {
             return null;
         }
-        const position = Number(result.stdout.toString().trim());
-        return Number.isInteger(position) && position >= 0 ? position : null;
     }
-    sendCopyModeCommand(sessionId, command, repeatCount) {
+    async sendCopyModeCommand(sessionId, command, repeatCount) {
         const args = ['-L', this.socket, '-f', this.configPath, 'send-keys', '-X'];
         if (repeatCount > 1) {
             args.push('-N', String(repeatCount));
         }
-        args.push('-t', sessionId, command);
-        const result = spawnSync('tmux', args, { stdio: 'ignore' });
-        return result.status === 0;
+        args.push('-t', exactPaneTarget(sessionId), command);
+        try {
+            await this.commandRunner('tmux', args);
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
-    readPanePid(sessionId) {
-        const result = spawnSync('tmux', [
-            '-L',
-            this.socket,
-            '-f',
-            this.configPath,
-            'display-message',
-            '-p',
-            '-t',
-            sessionId,
-            '#{pane_pid}'
-        ], { stdio: ['ignore', 'pipe', 'pipe'] });
-        if (result.status !== 0) {
+    async readPanePidAsync(sessionId) {
+        try {
+            const result = await this.commandRunner('tmux', [
+                '-L', this.socket, '-f', this.configPath,
+                'display-message', '-p', '-t', exactPaneTarget(sessionId), '#{pane_pid}'
+            ]);
+            const panePid = Number(result.stdout.trim());
+            return Number.isInteger(panePid) && panePid > 0 ? panePid : null;
+        }
+        catch {
             return null;
         }
-        const panePid = Number(result.stdout.toString().trim());
-        return Number.isInteger(panePid) && panePid > 0 ? panePid : null;
     }
-    readPanePidWithRetry(sessionId) {
-        for (let attempt = 0; attempt < 3; attempt += 1) {
-            const panePid = this.readPanePid(sessionId);
-            if (panePid !== null) {
-                return panePid;
-            }
-        }
+    readProcessTreeSnapshot() {
+        const cached = this.processTreeCache.get('all');
+        if (cached)
+            return Promise.resolve(cached.value);
+        return this.processTreeInflight.run('all', async () => {
+            const tree = await readProcessTreeAsync();
+            this.processTreeCache.set('all', tree, PROCESS_TREE_CACHE_TTL_MS);
+            return tree;
+        });
+    }
+}
+export function anchoredHistoryEndLine(beforeLine, snapshotHistorySize, currentHistorySize, rollover = {}) {
+    if (snapshotHistorySize === undefined) {
+        // beforeLine=0 is the initial tail request emitted before a snapshot has
+        // supplied cursor metadata. Any older coordinate without an anchor came
+        // from a mixed-version client and cannot be shifted safely.
+        return beforeLine === 0 ? -1 : null;
+    }
+    if (rollover.snapshotPaneWidth === undefined ||
+        rollover.currentPaneWidth === undefined ||
+        rollover.snapshotPaneWidth !== rollover.currentPaneWidth) {
+        // tmux reflows scrollback when pane width changes, so line coordinates
+        // from the previous page no longer identify the same text.
         return null;
     }
+    if (currentHistorySize < snapshotHistorySize) {
+        // clear-history/session reset invalidated the relative tmux coordinates.
+        return null;
+    }
+    const currentLimit = rollover.currentHistoryLimit;
+    if (currentLimit !== undefined && currentHistorySize >= currentLimit) {
+        // Once tmux reaches history-limit, history_size no longer reports how
+        // many oldest lines were evicted. Continue only when the previous page
+        // was captured at the same limit and the oldest scrollback anchor is
+        // unchanged.
+        if (rollover.snapshotHistoryLimit !== currentLimit ||
+            snapshotHistorySize !== currentHistorySize ||
+            rollover.snapshotHistoryToken === undefined ||
+            rollover.currentHistoryToken === undefined ||
+            rollover.snapshotHistoryToken !== rollover.currentHistoryToken) {
+            return null;
+        }
+    }
+    return beforeLine - (currentHistorySize - snapshotHistorySize) - 1;
+}
+export function historyCaptureIsStable(before, after) {
+    return before.metrics.historySize === after.metrics.historySize &&
+        before.metrics.historyLimit === after.metrics.historyLimit &&
+        before.metrics.paneHeight === after.metrics.paneHeight &&
+        before.metrics.paneWidth === after.metrics.paneWidth &&
+        before.metrics.historyBytes === after.metrics.historyBytes &&
+        before.metrics.paneId === after.metrics.paneId &&
+        before.metrics.sessionCreated === after.metrics.sessionCreated &&
+        before.token === after.token;
+}
+function invalidHistoryCapture(snapshot) {
+    const oldestLine = -snapshot.metrics.historySize;
+    return {
+        startLine: oldestLine,
+        endLine: oldestLine - 1,
+        hasMore: false,
+        invalidated: true,
+        snapshotHistorySize: snapshot.metrics.historySize,
+        snapshotHistoryLimit: snapshot.metrics.historyLimit,
+        snapshotHistoryToken: snapshot.token,
+        snapshotPaneWidth: snapshot.metrics.paneWidth,
+        output: []
+    };
+}
+function emptyHistoryCapture(snapshot) {
+    return {
+        startLine: 0,
+        endLine: -1,
+        hasMore: false,
+        snapshotHistorySize: 0,
+        snapshotHistoryLimit: snapshot.metrics.historyLimit,
+        snapshotHistoryToken: snapshot.token,
+        snapshotPaneWidth: snapshot.metrics.paneWidth,
+        output: []
+    };
+}
+function historySnapshotToken(metrics, oldestAnchor, generation, outputGeneration) {
+    return createHash('sha256')
+        .update(generation)
+        .update('\0')
+        .update(metrics.paneId)
+        .update('\0')
+        .update(String(metrics.sessionCreated))
+        .update('\0')
+        .update(String(metrics.historySize))
+        .update('\0')
+        .update(String(metrics.historyLimit))
+        .update('\0')
+        .update(String(metrics.paneWidth))
+        .update('\0')
+        .update(String(metrics.historyBytes))
+        .update('\0')
+        .update(String(outputGeneration))
+        .update('\0')
+        .update(oldestAnchor)
+        .digest('hex');
+}
+export function exactSessionTarget(sessionId) {
+    return `=${sessionId}`;
+}
+export function exactWindowTarget(sessionId) {
+    return `=${sessionId}:0`;
+}
+export function exactPaneTarget(sessionId) {
+    return `=${sessionId}:0.0`;
+}
+function isPendingCreationSessionId(sessionId) {
+    return sessionId.startsWith(PENDING_CREATION_SESSION_PREFIX);
+}
+function creationTokenFromMarker(marker) {
+    if (marker.startsWith(PENDING_CREATION_MARKER_PREFIX)) {
+        const token = marker.slice(PENDING_CREATION_MARKER_PREFIX.length);
+        return isCreationToken(token) ? token : '';
+    }
+    if (marker.startsWith('committed:')) {
+        const token = marker.slice('committed:'.length);
+        return isCreationToken(token) ? token : '';
+    }
+    return '';
+}
+function creationMarkerBelongsToToken(marker, creationToken) {
+    return isCreationToken(creationToken) && (marker === `${PENDING_CREATION_MARKER_PREFIX}${creationToken}` ||
+        marker === `committed:${creationToken}`);
 }
-// tmux window names are a single line of text without ESC sequences. Cap the
-// length and strip anything that could break terminal output if a future read
-// path embedded the name in a status line. 80 chars is plenty for a tab
-// label and matches the length we ask for in list-sessions's =128 cap.
-function sanitizeWindowName(raw) {
-    const collapsed = raw.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim();
-    return collapsed.slice(0, 80) || 'Terminal';
+function isCreationToken(value) {
+    return /^[a-f0-9]{16}$/.test(value);
 }
 function normalizeHistoryLimit(value) {
     if (!Number.isInteger(value) || value <= 0) {
@@ -477,6 +1369,95 @@ function normalizeHistoryLimit(value) {
     }
     return Math.min(value, 5000);
 }
+function parseFixedTmuxSessionCatalog(raw) {
+    return parseTmuxCatalogLines(raw, (line) => {
+        const fields = line.split('\t');
+        if (fields.length === 6 &&
+            /^[0-9]+$/.test(fields[1] ?? '') &&
+            /^%[0-9]+$/.test(fields[2] ?? '') &&
+            /^[0-9]+$/.test(fields[3] ?? '') &&
+            /^[0-9]+$/.test(fields[4] ?? '')) {
+            const [sessionId = '', panePidRaw = '', paneId = '', serverPidRaw = '', sessionCreatedRaw = '', creationMarker = ''] = fields;
+            return parseListedTmuxSession(sessionId, panePidRaw, creationMarker, {
+                paneId,
+                serverPid: Number(serverPidRaw),
+                sessionCreated: Number(sessionCreatedRaw)
+            });
+        }
+        // Compatibility for command-runner fixtures written before pane ids were
+        // added. Real tmux output for the fixed format always takes the branch
+        // above and never carries variable title/cwd strings in this catalog.
+        if (fields.length === 4 || fields.length === 5) {
+            const [sessionId = '', title = '', cwd = '', panePidRaw = '', creationMarker = ''] = fields;
+            return parseListedTmuxSession(sessionId, panePidRaw, creationMarker, { title, cwd });
+        }
+        return null;
+    });
+}
+function parseTmuxCatalogLines(raw, parseLine) {
+    const output = removeTmuxOutputTerminator(raw);
+    if (!output) {
+        return [];
+    }
+    const sessions = [];
+    for (const line of output.split('\n')) {
+        const session = parseLine(line);
+        if (!session) {
+            return null;
+        }
+        sessions.push(session);
+    }
+    return sessions;
+}
+function parseListedTmuxSession(sessionId, panePidRaw, creationMarker, metadata = null) {
+    const panePid = Number(panePidRaw);
+    if (!sessionId || !Number.isInteger(panePid) || panePid <= 0) {
+        return null;
+    }
+    return {
+        sessionId,
+        panePid,
+        creationMarker,
+        ...(metadata ? metadata : {})
+    };
+}
+function removeTmuxOutputTerminator(value) {
+    return value.endsWith('\n') ? value.slice(0, -1) : value;
+}
+function splitFixedPrefix(value, fieldCount) {
+    const fields = [];
+    let offset = 0;
+    for (let index = 0; index < fieldCount; index += 1) {
+        const separator = value.indexOf('\t', offset);
+        if (separator === -1) {
+            return null;
+        }
+        fields.push(value.slice(offset, separator));
+        offset = separator + 1;
+    }
+    fields.push(value.slice(offset));
+    return fields;
+}
+function tmuxMetadataMatchesCatalog(metadata, session) {
+    return (metadata.sessionId === session.sessionId &&
+        metadata.panePid === session.panePid &&
+        metadata.serverPid === session.serverPid &&
+        metadata.sessionCreated === session.sessionCreated &&
+        metadata.creationMarker === session.creationMarker);
+}
+function exactPaneIdTarget(paneId) {
+    if (!/^%[0-9]+$/.test(paneId)) {
+        throw new Error('invalid tmux pane id');
+    }
+    return paneId;
+}
+function toPersistedSession(sessionId, title, cwd) {
+    return {
+        sessionId,
+        ...(title ? { title } : {}),
+        ...(cwd ? { cwd } : {})
+    };
+}
 function normalizeScrollLines(value) {
     if (!Number.isInteger(value) || value === 0) {
         return 0;
@@ -487,11 +1468,11 @@ function normalizeCapturedPane(text) {
     const stripped = text.replace(/\r?\n$/, '');
     return stripped ? `${stripped.replace(/\r?\n/g, '\r\n')}\r\n` : '';
 }
-// Wrap node-pty's IPty so PtyProcess.kill() destroys the tmux SESSION (the
-// goal of TerminalManager.closeTerminal — actually free the shell), not just
-// the local tmux client. Without this, "close pane" would leave a zombie
-// session behind and the operator's `tmux ls -L nterminal` would slowly grow.
-function wrapTmuxPty(pty, socket, configPath, sessionId, panePid) {
+// PtyProcess represents only the local tmux client. Persisted session
+// deletion is handled separately by destroySession(), so shutdown can detach
+// clients without destroying live shells and deletion never blocks the event
+// loop on a synchronous tmux subprocess.
+function wrapTmuxPty(pty, panePid, onOutput, onPause, onResume) {
     return {
         pid: panePid,
         write(data) {
@@ -502,18 +1483,13 @@ function wrapTmuxPty(pty, socket, configPath, sessionId, panePid) {
         },
         pause() {
             pty.pause();
+            onPause();
         },
         resume() {
             pty.resume();
+            onResume();
         },
         kill() {
-            // kill-session tears down the tmux session for this PTY. The local
-            // tmux client process (this pty) exits as a side effect once the
-            // server reports the session is gone. Done synchronously so the
-            // caller's "the shell is gone now" assumption holds.
-            spawnSync('tmux', ['-L', socket, '-f', configPath, 'kill-session', '-t', sessionId], { stdio: 'ignore' });
-            // Belt-and-suspenders: if kill-session failed (e.g., session already
-            // exited), make sure the client process is gone too.
             try {
                 pty.kill();
             }
@@ -522,7 +1498,10 @@ function wrapTmuxPty(pty, socket, configPath, sessionId, panePid) {
             }
         },
         onData(listener) {
-            const disposable = pty.onData(listener);
+            const disposable = pty.onData((data) => {
+                onOutput();
+                listener(data);
+            });
             return { dispose: () => disposable.dispose() };
         },
         onExit(listener) {
@@ -539,20 +1518,18 @@ function defaultConfigPath() {
     // tree's config. Same layout in dev (running directly under src/).
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../scripts/nterminal-tmux.conf');
 }
-// One `ps` dump covers every pane in the poll cycle — much cheaper than
-// per-pane shell-outs. The output is `pid ppid state` with leading
-// whitespace trimmed; state is the kernel-reported run state where
-// 'R' = runnable / on-cpu, 'D' = uninterruptible I/O wait, anything
-// else (S, T, t, Z, I) we treat as "not actively working right now".
-function readProcessTree() {
-    const result = spawnSync('ps', ['-eo', 'pid=,ppid=,state='], {
-        stdio: ['ignore', 'pipe', 'pipe']
-    });
-    if (result.status !== 0)
+async function readProcessTreeAsync() {
+    try {
+        return parseProcessTree((await runCommand('ps', ['-eo', 'pid=,ppid=,state='])).stdout);
+    }
+    catch {
         return null;
+    }
+}
+function parseProcessTree(raw) {
     const childrenByPpid = new Map();
     const stateByPid = new Map();
-    for (const line of result.stdout.toString().split('\n')) {
+    for (const line of raw.split('\n')) {
         const parts = line.trim().split(/\s+/);
         if (parts.length < 3)
             continue;
@@ -629,18 +1606,18 @@ function listProcessPidsWithDepth(tree, root) {
     }
     return out;
 }
-function resolveTranscriptForegroundCommand(tree, root, currentCommand) {
-    if (!tree || !isNodeCommand(currentCommand)) {
+async function normalizeTmuxCurrentCommandAsync(currentCommand, tree, root) {
+    if (!isNodeCommand(currentCommand)) {
         return currentCommand;
     }
-    const descendantArgs = [root, ...listDescendantPids(tree, root)].map((pid) => readProcessArgs(pid));
-    return normalizeTmuxCurrentCommand(currentCommand, descendantArgs);
+    const argsByProcess = await mapWithConcurrency(listProcessPidsWithDepth(tree, root), 8, async ({ pid }) => await readProcessArgsAsync(pid));
+    return normalizeTmuxCurrentCommand(currentCommand, argsByProcess);
 }
-export function normalizeTmuxCurrentCommand(currentCommand, descendantArgs) {
+export function normalizeTmuxCurrentCommand(currentCommand, processArgs) {
     if (!isNodeCommand(currentCommand)) {
         return currentCommand;
     }
-    for (const args of descendantArgs) {
+    for (const args of processArgs) {
         if (findCommandArg(args, 'codex') !== -1) {
             return 'codex';
         }
@@ -654,9 +1631,9 @@ function isNodeCommand(command) {
     const base = path.basename(command).toLowerCase();
     return base === 'node' || base === 'nodejs';
 }
-function readProcessArgs(pid) {
+async function readProcessArgsAsync(pid) {
     try {
-        const raw = readFileSync(`/proc/${pid}/cmdline`, 'utf8');
+        const raw = await readFile(`/proc/${pid}/cmdline`, 'utf8');
         return raw.split('\0').filter(Boolean);
     }
     catch {
@@ -686,6 +1663,7 @@ function extractClaudeArgsCandidate(args) {
 const NON_INTERACTIVE_CODEX_SUBCOMMANDS = new Set([
     'exec',
     'e',
+    'review',
     'mcp',
     'mcp-server',
     'app-server',
@@ -733,6 +1711,18 @@ export function isNonInteractiveCodexInvocation(args) {
     for (let index = commandIndex + 1; index < args.length; index += 1) {
         const arg = args[index];
         if (arg.startsWith('-')) {
+            if ((arg === '-i' || arg === '--image') && !arg.includes('=')) {
+                // --image accepts one or more paths. Stop only at a recognized
+                // subcommand; treating a second image as the command would let a
+                // later `exec`/`review` batch masquerade as an interactive pane.
+                while (index + 1 < args.length &&
+                    !args[index + 1].startsWith('-') &&
+                    !NON_INTERACTIVE_CODEX_SUBCOMMANDS.has(args[index + 1]) &&
+                    args[index + 1] !== 'resume') {
+                    index += 1;
+                }
+                continue;
+            }
             if (!arg.includes('=') && CODEX_VALUE_FLAGS.has(arg)) {
                 index += 1;
             }
@@ -788,150 +1778,104 @@ export function selectTranscriptCandidate(entries) {
     }
     return null;
 }
-function resolveClaudeCandidateForPid(pid, args) {
-    // One environ read serves every key, and the config root honors the
-    // process's own HOME / CLAUDE_CONFIG_DIR so a pane running claude under an
-    // overridden home never gets resolved against the server's ~/.claude.
-    const env = readProcessEnvValues(pid, ['CLAUDE_CONFIG_DIR', 'HOME', 'PWD']);
+async function resolveClaudeCandidateForPidAsync(pid, args) {
+    const env = await readProcessEnvValuesAsync(pid, ['CLAUDE_CONFIG_DIR', 'HOME', 'PWD']);
     const configRoot = env.get('CLAUDE_CONFIG_DIR') ?? path.join(env.get('HOME') ?? os.homedir(), '.claude');
-    const startTicks = readProcessStartTicks(pid);
-    const registry = resolveClaudeTranscriptFromSessionRegistry({ pid, configRoot, procStartTicks: startTicks });
-    if (registry.kind === 'resolved') {
+    const startTicks = await readProcessStartTicksAsync(pid);
+    const registry = await resolveClaudeTranscriptFromSessionRegistry({ pid, configRoot, procStartTicks: startTicks });
+    if (registry.kind === 'resolved')
         return { entry: { candidate: registry.candidate, rank: 'live' }, pending: false };
-    }
-    if (registry.kind === 'pending') {
+    if (registry.kind === 'pending')
         return { entry: null, pending: true };
-    }
     const projectsRoot = path.join(configRoot, 'projects');
     const stated = extractClaudeArgsCandidate(args);
     if (stated) {
-        const located = findTranscriptFiles('claude', stated.sessionId, projectsRoot);
+        const located = await findTranscriptFilesAsync('claude', stated.sessionId, projectsRoot);
         return {
-            entry: located.length === 1
-                ? { candidate: { ...stated, filePath: located[0] }, rank: 'stated' }
-                : null,
+            entry: located.length === 1 ? { candidate: { ...stated, filePath: located[0] }, rank: 'stated' } : null,
             pending: false
         };
     }
-    const startSeconds = processStartTicksToSeconds(startTicks);
-    const cwdCandidates = [readProcessCwd(pid), env.get('PWD') ?? null].filter((value) => Boolean(value));
-    if (cwdCandidates.length === 0) {
+    const [startSeconds, processCwd] = await Promise.all([
+        processStartTicksToSecondsAsync(startTicks),
+        readProcessCwdAsync(pid)
+    ]);
+    const cwdCandidates = [processCwd, env.get('PWD') ?? null].filter((value) => Boolean(value));
+    if (cwdCandidates.length === 0)
         return { entry: null, pending: false };
-    }
-    const inferred = resolveClaudeTranscriptFromProjectFiles({
+    const inferred = await resolveClaudeTranscriptFromProjectFiles({
         cwdCandidates,
         processStartedAtMs: startSeconds === null ? null : startSeconds * 1000,
         projectsRoot
     });
     return { entry: inferred ? { candidate: inferred, rank: 'inferred' } : null, pending: false };
 }
-// Claude Code maintains a live-session registry at
-// <configRoot>/sessions/<pid>.json (configRoot defaults to ~/.claude). Each
-// interactive top-level session writes {pid, sessionId, cwd, procStart, ...}
-// at startup, updates sessionId in place on /clear and /resume, and unlinks
-// the file on exit. `procStart` is the process start time in clock ticks
-// exactly as /proc/<pid>/stat reports it — comparing the two rejects stale
-// files left behind by a crashed process whose pid was since reused.
-//
-// This is an undocumented internal mechanism (Claude Code calls it
-// "concurrentSessions"), so parse defensively and treat any mismatch as
-// "registry unavailable" — the cwd heuristic below remains the fallback.
-export function resolveClaudeTranscriptFromSessionRegistry(options) {
-    if (!options.procStartTicks) {
+export async function resolveClaudeTranscriptFromSessionRegistry(options) {
+    if (!options.procStartTicks)
         return { kind: 'unavailable' };
-    }
-    let raw;
-    try {
-        raw = readFileSync(path.join(options.configRoot, 'sessions', `${options.pid}.json`), 'utf8');
-    }
-    catch {
-        return { kind: 'unavailable' };
-    }
     let entry;
     try {
-        entry = JSON.parse(raw);
+        entry = JSON.parse(await readFile(path.join(options.configRoot, 'sessions', `${options.pid}.json`), 'utf8'));
     }
     catch {
         return { kind: 'unavailable' };
     }
-    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
         return { kind: 'unavailable' };
-    }
     const record = entry;
-    // pid is a JSON number today and procStart a JSON string, but this is an
-    // undocumented format — normalize both sides so a serialization change
-    // degrades the comparison gracefully instead of silently disabling the
-    // registry forever.
     if (Number(record.pid) !== options.pid || record.procStart === undefined || record.procStart === null || String(record.procStart) !== options.procStartTicks) {
         return { kind: 'unavailable' };
     }
-    // bg / daemon / daemon-worker entries belong to background invocations a
-    // pane's tooling may have spawned, never to the pane's own conversation.
-    if (record.kind !== undefined && record.kind !== 'interactive') {
+    if (record.kind !== undefined && record.kind !== 'interactive')
         return { kind: 'unavailable' };
-    }
     const sessionId = typeof record.sessionId === 'string' ? record.sessionId : undefined;
-    if (!isSessionId(sessionId)) {
+    if (!isSessionId(sessionId))
         return { kind: 'unavailable' };
-    }
     const projectsRoot = path.join(options.configRoot, 'projects');
-    const cwdCandidates = typeof record.cwd === 'string' ? normalizeClaudeCwdCandidates([record.cwd]) : [];
+    const cwdCandidates = typeof record.cwd === 'string' ? await normalizeClaudeCwdCandidatesAsync([record.cwd]) : [];
     for (const cwd of cwdCandidates) {
         const filePath = path.join(projectsRoot, encodeClaudeProjectPath(cwd), `${sessionId}.jsonl`);
-        if (existsSync(filePath)) {
+        try {
+            await access(filePath);
             return { kind: 'resolved', candidate: { provider: 'claude', sessionId, filePath } };
         }
+        catch {
+            // Try the unique-id fallback below.
+        }
     }
-    // The registry cwd can disagree with where the transcript actually landed
-    // (chdir after startup, symlinked paths). The session id is a UUID, so a
-    // unique match anywhere under projects/ is unambiguous.
-    const matches = findTranscriptFiles('claude', sessionId, projectsRoot);
-    if (matches.length === 1) {
+    const matches = await findTranscriptFilesAsync('claude', sessionId, projectsRoot);
+    if (matches.length === 1)
         return { kind: 'resolved', candidate: { provider: 'claude', sessionId, filePath: matches[0] } };
-    }
-    if (matches.length === 0) {
-        return { kind: 'pending' };
-    }
-    // Duplicate copies of the same session id (backed-up project dirs) are
-    // ambiguity, not "not written yet" — report unavailable so lower tiers
-    // get a shot instead of waiting forever.
-    return { kind: 'unavailable' };
+    return matches.length === 0 ? { kind: 'pending' } : { kind: 'unavailable' };
 }
-export function resolveClaudeTranscriptFromProjectFiles(options) {
-    const cwdCandidates = normalizeClaudeCwdCandidates(options.cwdCandidates);
-    if (cwdCandidates.length === 0) {
+export async function resolveClaudeTranscriptFromProjectFiles(options) {
+    const cwdCandidates = await normalizeClaudeCwdCandidatesAsync(options.cwdCandidates);
+    if (cwdCandidates.length === 0)
         return null;
-    }
     const projectRoot = options.projectsRoot ?? path.join(options.homeDir ?? os.homedir(), '.claude', 'projects');
     const projectDirs = new Set(cwdCandidates.map((cwd) => path.join(projectRoot, encodeClaudeProjectPath(cwd))));
     const candidates = new Map();
     for (const projectDir of projectDirs) {
         let entries;
         try {
-            entries = readdirSync(projectDir, { withFileTypes: true });
+            entries = await readdir(projectDir, { withFileTypes: true });
         }
         catch {
             continue;
         }
         for (const entry of entries) {
-            if (!entry.isFile() || !entry.name.endsWith('.jsonl')) {
+            if (!entry.isFile() || !entry.name.endsWith('.jsonl'))
                 continue;
-            }
             const sessionId = entry.name.slice(0, -'.jsonl'.length);
-            if (!isSessionId(sessionId)) {
+            if (!isSessionId(sessionId))
                 continue;
-            }
             const filePath = path.join(projectDir, entry.name);
-            if (!isPlausibleClaudeTranscriptFile(filePath, sessionId, cwdCandidates, options.processStartedAtMs)) {
+            if (!(await isPlausibleClaudeTranscriptFileAsync(filePath, sessionId, cwdCandidates, options.processStartedAtMs)))
                 continue;
-            }
             candidates.set(sessionId, { provider: 'claude', sessionId, filePath });
         }
     }
-    if (candidates.size !== 1) {
-        return null;
-    }
-    return [...candidates.values()][0] ?? null;
+    return candidates.size === 1 ? ([...candidates.values()][0] ?? null) : null;
 }
 function findCommandArg(args, command) {
     if (command === 'codex') {
@@ -955,17 +1899,16 @@ function findCommandArg(args, command) {
         return false;
     });
 }
-function normalizeClaudeCwdCandidates(values) {
+async function normalizeClaudeCwdCandidatesAsync(values) {
     const out = new Set();
     for (const value of values) {
         const trimmed = value.trim();
-        if (!trimmed) {
+        if (!trimmed)
             continue;
-        }
         const resolved = path.resolve(trimmed);
         out.add(resolved);
         try {
-            out.add(realpathSync(resolved));
+            out.add(await realpath(resolved));
         }
         catch {
             // The process cwd is enough when the path no longer resolves.
@@ -973,58 +1916,111 @@ function normalizeClaudeCwdCandidates(values) {
     }
     return [...out];
 }
-function encodeClaudeProjectPath(cwd) {
+export function encodeClaudeProjectPath(cwd) {
     return cwd.replace(/[^A-Za-z0-9_-]/g, '-');
 }
-function isPlausibleClaudeTranscriptFile(filePath, sessionId, cwdCandidates, processStartedAtMs) {
-    let stat;
+async function isPlausibleClaudeTranscriptFileAsync(filePath, sessionId, cwdCandidates, processStartedAtMs) {
     try {
-        stat = statSync(filePath);
+        const fileStat = await stat(filePath);
+        if (!fileStat.isFile())
+            return false;
+        if (processStartedAtMs !== undefined && processStartedAtMs !== null && fileStat.mtimeMs + CLAUDE_TRANSCRIPT_START_SKEW_MS < processStartedAtMs) {
+            return false;
+        }
+        const cached = confirmedClaudeTranscripts.get(sessionId);
+        if (cached) {
+            if (cached.filePath === filePath &&
+                cached.dev === fileStat.dev &&
+                cached.ino === fileStat.ino &&
+                cwdCandidates.some((cwd) => cached.verifiedCwds.includes(cwd))) {
+                if (fileStat.size >= cached.verifiedSize) {
+                    touchConfirmedClaudeTranscript(sessionId, cached);
+                    return true;
+                }
+            }
+            confirmedClaudeTranscripts.delete(sessionId);
+        }
+        const sample = await readFileHeadTailAsync(filePath, CLAUDE_TRANSCRIPT_SAMPLE_BYTES, fileStat);
+        if (!sample)
+            return false;
+        const sessionNeedle = `"sessionId":${JSON.stringify(sessionId)}`;
+        const verifiedCwds = cwdCandidates.filter((cwd) => sample.includes(`"cwd":${JSON.stringify(cwd)}`));
+        const plausible = sample.includes(sessionNeedle) && verifiedCwds.length > 0;
+        if (plausible) {
+            rememberConfirmedClaudeTranscript(sessionId, {
+                filePath,
+                dev: fileStat.dev,
+                ino: fileStat.ino,
+                verifiedSize: fileStat.size,
+                verifiedCwds
+            });
+        }
+        return plausible;
     }
     catch {
         return false;
     }
-    if (!stat.isFile()) {
-        return false;
-    }
-    if (processStartedAtMs !== undefined &&
-        processStartedAtMs !== null &&
-        stat.mtimeMs + CLAUDE_TRANSCRIPT_START_SKEW_MS < processStartedAtMs) {
-        return false;
-    }
-    const sample = readFileHeadTail(filePath, CLAUDE_TRANSCRIPT_SAMPLE_BYTES);
-    if (!sample) {
-        return false;
-    }
-    const sessionNeedle = `"sessionId":${JSON.stringify(sessionId)}`;
-    if (!sample.includes(sessionNeedle)) {
-        return false;
-    }
-    return cwdCandidates.some((cwd) => sample.includes(`"cwd":${JSON.stringify(cwd)}`));
 }
-function readFileHeadTail(filePath, bytes) {
-    let fd = null;
+async function readFileHeadTailAsync(filePath, bytes, knownStat) {
+    let handle;
     try {
-        fd = openSync(filePath, 'r');
-        const stat = fstatSync(fd);
-        const headBytes = Math.min(bytes, stat.size);
+        handle = await openFile(filePath, 'r');
+        const initial = await handle.stat();
+        if (knownStat && (initial.dev !== knownStat.dev || initial.ino !== knownStat.ino)) {
+            return null;
+        }
+        const size = initial.size;
+        const headBytes = Math.min(bytes, size);
         const head = Buffer.alloc(headBytes);
-        readSync(fd, head, 0, headBytes, 0);
-        if (stat.size <= bytes) {
-            return head.toString('utf8');
+        const actualHeadBytes = await readExactly(handle, head, 0);
+        if (actualHeadBytes !== headBytes)
+            return null;
+        let sample = head.subarray(0, actualHeadBytes).toString('utf8');
+        if (size > bytes) {
+            const tailBytes = Math.min(bytes, size - headBytes);
+            const tail = Buffer.alloc(tailBytes);
+            const actualTailBytes = await readExactly(handle, tail, size - tailBytes);
+            if (actualTailBytes !== tailBytes)
+                return null;
+            sample = `${sample}\n${tail.toString('utf8')}`;
+        }
+        const after = await handle.stat();
+        if (after.dev !== initial.dev ||
+            after.ino !== initial.ino ||
+            after.size < size ||
+            (after.size === size && after.mtimeMs !== initial.mtimeMs)) {
+            return null;
         }
-        const tailBytes = Math.min(bytes, stat.size - headBytes);
-        const tail = Buffer.alloc(tailBytes);
-        readSync(fd, tail, 0, tailBytes, stat.size - tailBytes);
-        return `${head.toString('utf8')}\n${tail.toString('utf8')}`;
+        return sample;
     }
     catch {
         return null;
     }
     finally {
-        if (fd !== null) {
-            closeSync(fd);
-        }
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function readExactly(handle, buffer, position) {
+    let offset = 0;
+    while (offset < buffer.length) {
+        const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, position + offset);
+        if (bytesRead === 0)
+            break;
+        offset += bytesRead;
+    }
+    return offset;
+}
+function touchConfirmedClaudeTranscript(sessionId, entry) {
+    confirmedClaudeTranscripts.delete(sessionId);
+    confirmedClaudeTranscripts.set(sessionId, entry);
+}
+function rememberConfirmedClaudeTranscript(sessionId, entry) {
+    touchConfirmedClaudeTranscript(sessionId, entry);
+    while (confirmedClaudeTranscripts.size > CLAUDE_TRANSCRIPT_CACHE_LIMIT) {
+        const oldest = confirmedClaudeTranscripts.keys().next().value;
+        if (typeof oldest !== 'string')
+            break;
+        confirmedClaudeTranscripts.delete(oldest);
     }
 }
 function findCodexSessionId(args, commandIndex) {
@@ -1052,49 +2048,41 @@ function readLongOptionValue(arg, option) {
     const prefix = `${option}=`;
     return arg.startsWith(prefix) ? arg.slice(prefix.length) : null;
 }
-function findTranscriptFiles(provider, sessionId, root) {
-    const searchRoot = root ??
-        (provider === 'codex'
-            ? path.join(os.homedir(), '.codex', 'sessions')
-            : path.join(os.homedir(), '.claude', 'projects'));
+const transcriptFileInflight = new KeyedSingleFlight();
+export async function findTranscriptFilesAsync(provider, sessionId, root) {
+    const searchRoot = root ?? (provider === 'codex'
+        ? path.join(os.homedir(), '.codex', 'sessions')
+        : path.join(os.homedir(), '.claude', 'projects'));
     const cacheKey = `${provider}:${searchRoot}:${sessionId}`;
     const cached = transcriptFileCache.get(cacheKey);
-    if (cached) {
+    if (cached)
         return cached.value.slice();
-    }
-    const matches = [];
-    findTranscriptFilesUnder(searchRoot, provider, sessionId, matches);
-    transcriptFileCache.set(cacheKey, matches.slice(), matches.length === 1 ? TRANSCRIPT_FILE_CACHE_TTL_MS : TRANSCRIPT_FILE_NEGATIVE_CACHE_TTL_MS);
-    return matches;
+    return transcriptFileInflight.run(cacheKey, async () => {
+        const matches = [];
+        await findTranscriptFilesUnderAsync(searchRoot, provider, sessionId, matches);
+        transcriptFileCache.set(cacheKey, matches.slice(), matches.length === 1 ? TRANSCRIPT_FILE_CACHE_TTL_MS : TRANSCRIPT_FILE_NEGATIVE_CACHE_TTL_MS);
+        return matches;
+    });
 }
-function findTranscriptFilesUnder(root, provider, sessionId, matches) {
-    if (matches.length > 1) {
+async function findTranscriptFilesUnderAsync(root, provider, sessionId, matches) {
+    if (matches.length > 1)
         return;
-    }
     let entries;
     try {
-        entries = readdirSync(root, { withFileTypes: true });
+        entries = await readdir(root, { withFileTypes: true });
     }
     catch {
         return;
     }
     for (const entry of entries) {
-        if (matches.length > 1) {
+        if (matches.length > 1)
             return;
-        }
         const fullPath = path.join(root, entry.name);
         if (entry.isDirectory()) {
-            findTranscriptFilesUnder(fullPath, provider, sessionId, matches);
-            continue;
-        }
-        if (!entry.isFile()) {
-            continue;
-        }
-        if (provider === 'codex' && entry.name.startsWith('rollout-') && entry.name.endsWith(`${sessionId}.jsonl`)) {
-            matches.push(fullPath);
-            continue;
+            await findTranscriptFilesUnderAsync(fullPath, provider, sessionId, matches);
         }
-        if (provider === 'claude' && entry.name === `${sessionId}.jsonl`) {
+        else if (entry.isFile() && ((provider === 'codex' && entry.name.startsWith('rollout-') && entry.name.endsWith(`${sessionId}.jsonl`)) ||
+            (provider === 'claude' && entry.name === `${sessionId}.jsonl`))) {
             matches.push(fullPath);
         }
     }