handmux 0.26.0 → 0.27.2

package/dist/src/agents/codexConversationActivation.js

@@ -1,14 +1,19 @@
+import { ConversationActivationError } from '../agent-runtime/conversationActivation.js';
 import { serializePaneInput } from '../paneInput.js';
-import { codex, codexExitSessionId } from './codex.js';
+import { codex } from './codex.js';
+import { sameCodexOpenSession } from './codexOpenSession.js';
 const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const SHELLS = new Set(['sh', 'bash', 'zsh', 'fish', 'dash', 'ksh', 'tcsh']);
+const REMOTE_ARG_RE = /(?:^|\s)--remote(?:=|\s|$)/;
 function throwIfAborted(signal) {
     if (signal.aborted)
         throw signal.reason instanceof Error ? signal.reason : new Error('Activation cancelled');
 }
-export function createCodexConversationActivationController({ panes, process, commands, wait = pause, }) {
-    if (!panes || !process || !commands || typeof commands.sendKey !== 'function'
-        || typeof commands.capturePlain !== 'function' || typeof commands.runPaneCommand !== 'function') {
+export function createCodexConversationActivationController({ app, panes, process, commands, receipts, wait = pause, }) {
+    if (!app || typeof app.discover !== 'function' || !panes || !process || !commands
+        || typeof commands.openOutputCapture !== 'function'
+        || typeof commands.inspectOpenSession !== 'function'
+        || typeof commands.runPaneCommand !== 'function') {
         throw new TypeError('Codex Conversation activation requires pane control');
     }
     const pane = async (paneId) => (await panes.list()).find((item) => item.paneId === paneId) ?? null;
@@ -22,6 +27,22 @@ export function createCodexConversationActivationController({ panes, process, co
         return await codex.process.verify(current, { inspectForeground: async () => identity })
             ? identity : null;
     };
+    const nativeCodexTakeoverIdentity = async (paneId) => {
+        const identity = await codexIdentity(paneId);
+        if (!identity)
+            return null;
+        const ownership = await app.discover(paneId);
+        if (ownership?.managed === true && ownership.threadId) {
+            receipts?.clearManaged(paneId, ownership.threadId);
+        }
+        if (identity.commandLine && REMOTE_ARG_RE.test(identity.commandLine))
+            return null;
+        if (ownership?.managed === false)
+            return identity;
+        // A dead App Server can leave its socket file behind. Only an explicit unknown ownership result
+        // plus a complete native command line is authoritative enough to treat that process as native.
+        return ownership?.managed === null && identity.commandLine ? identity : null;
+    };
     const shellIdentity = async (paneId) => {
         const current = await pane(paneId);
         if (!current)
@@ -30,91 +51,270 @@ export function createCodexConversationActivationController({ panes, process, co
         if (!identity)
             return null;
         const executable = identity.executable?.split('/').pop()?.toLowerCase();
-        return SHELLS.has(current.currentCommand.toLowerCase()) || (executable && SHELLS.has(executable))
-            ? identity : null;
+        return executable && SHELLS.has(executable) ? identity : null;
+    };
+    const processAfterInterrupt = async (paneId) => {
+        const current = await pane(paneId);
+        if (!current)
+            return null;
+        const identity = await process.inspectForeground(current);
+        if (!identity)
+            return { kind: 'unknown', identity: null };
+        // During Codex shutdown, tmux/ps can briefly expose the old pane command without an executable.
+        // Only this bounded post-interrupt wait treats that incomplete snapshot as transient.
+        if (!identity.executable)
+            return { kind: 'unknown', identity };
+        const executable = identity.executable.split('/').pop()?.toLowerCase();
+        if (executable && SHELLS.has(executable))
+            return { kind: 'shell', identity };
+        const isCodex = await codex.process.verify(current, { inspectForeground: async () => identity });
+        return { kind: isCodex ? 'codex' : 'other', identity };
     };
     const sameProcess = (first, second) => (first.pid === second.pid
-        && (first.startedAt === undefined || second.startedAt === first.startedAt)
-        && (first.tty === undefined || second.tty === first.tty));
+        && first.startedAt !== undefined && second.startedAt === first.startedAt
+        && first.tty !== undefined && second.tty === first.tty
+        && first.executable !== undefined && second.executable === first.executable);
+    const sameRunProcess = (locked, current) => (locked.pid === current.pid
+        && locked.startedAt !== undefined && current.startedAt === locked.startedAt
+        && locked.tty !== undefined && current.tty === locked.tty);
+    const samePane = (first, second) => (first.paneId === second.paneId && first.sessionName === second.sessionName
+        && first.windowId === second.windowId && first.tty === second.tty);
+    const receiptRecovery = (receipt) => ({
+        kind: 'codex_resume',
+        sessionId: receipt.sessionId,
+        command: receipt.command,
+    });
+    const recoveryReceipt = async (paneId, expectedOperationId) => {
+        const receipt = expectedOperationId
+            ? receipts?.get(expectedOperationId) : receipts?.latestForPane(paneId);
+        if (!receipt || receipt.pane.paneId !== paneId)
+            return null;
+        const ownership = await app.discover(paneId);
+        if (ownership?.managed === true && ownership.threadId === receipt.sessionId) {
+            receipts?.clearManaged(paneId, receipt.sessionId);
+            return null;
+        }
+        const currentPane = await pane(paneId);
+        const currentEpoch = await commands.paneEpoch?.(paneId);
+        const current = !!currentPane
+            && currentPane.paneId === receipt.pane.paneId
+            && currentPane.sessionName === receipt.pane.sessionName
+            && currentPane.windowId === receipt.pane.windowId
+            && !!currentEpoch && currentEpoch === receipt.pane.tmuxEpoch;
+        let canResume = false;
+        if (current && receipt.phase !== 'resuming') {
+            const identity = await shellIdentity(paneId);
+            canResume = identity !== null;
+        }
+        return {
+            receipt,
+            view: {
+                operationId: receipt.operationId,
+                recovery: receiptRecovery(receipt),
+                phase: receipt.phase,
+                state: current ? 'current' : 'stale',
+                canResume,
+            },
+        };
+    };
     return {
         apiVersion: 1,
+        async recovery(paneId) {
+            return (await recoveryReceipt(paneId))?.view ?? null;
+        },
+        async recover(paneId, operationId, signal, progress) {
+            return await serializePaneInput(paneId, async () => {
+                throwIfAborted(signal);
+                const resolved = await recoveryReceipt(paneId, operationId);
+                if (!resolved)
+                    throw new ConversationActivationError('Conversation recovery is no longer available', 'unavailable');
+                const recovery = receiptRecovery(resolved.receipt);
+                progress.recovery(recovery);
+                if (resolved.view.state !== 'current' || !resolved.view.canResume) {
+                    if (resolved.receipt.phase === 'resuming')
+                        return { recovery };
+                    throw new ConversationActivationError('The original pane is no longer safe to resume; copy the recovery command instead', 'unavailable', recovery);
+                }
+                const claimed = receipts?.transition(operationId, ['prepared', 'interrupted'], 'resuming');
+                if (!claimed)
+                    throw new ConversationActivationError('Conversation recovery is unavailable', 'unavailable', recovery);
+                throwIfAborted(signal);
+                const rechecked = await recoveryReceipt(paneId, operationId);
+                if (!rechecked || rechecked.view.state !== 'current') {
+                    throw new ConversationActivationError('The pane changed before Conversation recovery; copy the recovery command instead', 'unavailable', recovery);
+                }
+                const shell = await shellIdentity(paneId);
+                if (!shell)
+                    throw new ConversationActivationError('The pane shell changed before Conversation recovery; copy the recovery command instead', 'unavailable', recovery);
+                // The service can time out while either asynchronous recheck above is still pending.
+                // Revalidate cancellation at the side-effect boundary, not only before the rechecks.
+                throwIfAborted(signal);
+                await commands.runPaneCommand(paneId, recovery.command);
+                return { recovery };
+            });
+        },
         async describe(run) {
-            if (run.ref.sessionId || run.signal.aborted || !await codexIdentity(run.ref.paneId))
+            if (run.ref.sessionId || run.signal.aborted)
+                return null;
+            const lockedProcess = run.process;
+            if (!lockedProcess || lockedProcess.startedAt === undefined || !lockedProcess.tty)
+                return null;
+            let processIdentity;
+            try {
+                processIdentity = await nativeCodexTakeoverIdentity(run.ref.paneId);
+            }
+            catch {
+                return null;
+            }
+            if (!processIdentity || !processIdentity.executable
+                || !sameRunProcess(lockedProcess, processIdentity))
+                return null;
+            if (!await commands.inspectOpenSession(processIdentity.pid))
                 return null;
             return { effect: 'replace-process-preserve-session' };
         },
-        async activate(run, signal) {
-            await serializePaneInput(run.ref.paneId, async () => {
+        async activate(run, signal, progress) {
+            return await serializePaneInput(run.ref.paneId, async () => {
                 const paneId = run.ref.paneId;
                 throwIfAborted(signal);
+                const originalPane = await pane(paneId);
+                if (!originalPane)
+                    throw new Error('The pane closed before Conversation activation');
+                const lockedProcess = run.process;
+                if (!lockedProcess || lockedProcess.startedAt === undefined || !lockedProcess.tty) {
+                    throw new Error('The Agent run identity is incomplete; continue in the terminal');
+                }
                 const original = !run.ref.sessionId && !run.signal.aborted
-                    ? await codexIdentity(paneId) : null;
+                    ? await nativeCodexTakeoverIdentity(paneId) : null;
                 throwIfAborted(signal);
-                if (!original)
+                if (!original || !sameRunProcess(lockedProcess, original)) {
                     throw new Error('The Agent run changed before Conversation activation');
-                // Authorization is bound to the verified run above. Exiting that exact process intentionally revokes
-                // its lease, so subsequent checks bind recovery to the shell that replaced it.
-                let exited = false;
-                let shell = null;
-                for (let press = 0; press < 2 && !exited; press += 1) {
-                    throwIfAborted(signal);
-                    const beforePress = await codexIdentity(paneId);
-                    if (!beforePress || !sameProcess(original, beforePress)) {
-                        throw new Error('The Agent process changed before Conversation activation');
-                    }
+                }
+                if (original.startedAt === undefined || !original.tty || !original.executable) {
+                    throw new Error('The Agent process identity is incomplete; continue in the terminal');
+                }
+                const lockedSession = await commands.inspectOpenSession(original.pid);
+                throwIfAborted(signal);
+                if (!lockedSession) {
+                    throw new Error('Codex current session could not be identified safely; continue in the terminal');
+                }
+                const tmuxEpoch = receipts ? await commands.paneEpoch?.(paneId) : null;
+                if (receipts && (!tmuxEpoch || original.startedAt === undefined || !original.tty
+                    || !original.executable)) {
+                    throw new Error('The pane identity is incomplete; continue in the terminal');
+                }
+                const sessionId = lockedSession.sessionId;
+                const resume = codex.sessions.managedResumeCmd?.(sessionId);
+                if (!resume)
+                    throw new Error('Managed Conversation activation is unavailable');
+                const recovery = { kind: 'codex_resume', sessionId, command: resume };
+                let durable = null;
+                if (receipts && tmuxEpoch && original.startedAt !== undefined && original.tty && original.executable) {
+                    durable = receipts.prepare({
+                        pane: {
+                            paneId,
+                            sessionName: originalPane.sessionName,
+                            windowId: originalPane.windowId,
+                            tmuxEpoch,
+                        },
+                        process: {
+                            pid: original.pid,
+                            startedAt: original.startedAt,
+                            tty: original.tty,
+                            executable: original.executable,
+                        },
+                        sessionId,
+                        command: resume,
+                    });
+                }
+                progress.recovery(recovery);
+                const outputCapture = await commands.openOutputCapture(paneId);
+                const abortCapture = () => outputCapture.close();
+                signal.addEventListener('abort', abortCapture, { once: true });
+                try {
                     throwIfAborted(signal);
-                    await commands.sendKey(paneId, 'C-c');
-                    for (let attempt = 0; attempt < 10; attempt += 1) {
-                        await wait(500);
+                    // Authorization is bound to the verified run above. Exiting that exact process intentionally revokes
+                    // its lease, so subsequent checks bind recovery to the shell that replaced it.
+                    let exited = false;
+                    let shell = null;
+                    for (let press = 0; press < 2 && !exited; press += 1) {
                         throwIfAborted(signal);
-                        if (!await pane(paneId))
-                            throw new Error('The pane closed during Conversation activation');
-                        const currentIdentity = await codexIdentity(paneId);
-                        if (!currentIdentity) {
-                            shell = await shellIdentity(paneId);
-                            if (!shell)
-                                throw new Error('The pane did not return to the expected shell');
-                            exited = true;
-                            break;
+                        const beforePane = await pane(paneId);
+                        if (!beforePane || !samePane(originalPane, beforePane)) {
+                            throw new Error('The pane changed before Conversation activation');
                         }
-                        if (!sameProcess(original, currentIdentity)) {
-                            throw new Error('The Agent process changed during Conversation activation');
+                        if (tmuxEpoch && await commands.paneEpoch?.(paneId) !== tmuxEpoch) {
+                            throw new Error('The tmux server changed before Conversation activation');
                         }
+                        // A previous activation may have returned before Runtime revoked this sessionless lease.
+                        // Re-read provider ownership at the irreversible boundary so a second client can never
+                        // interrupt the newly managed replacement through the still-resolvable old run.
+                        const beforePress = await nativeCodexTakeoverIdentity(paneId);
+                        if (!beforePress || !sameProcess(original, beforePress)) {
+                            throw new Error('The Agent process changed before Conversation activation');
+                        }
+                        const stillOpen = await commands.inspectOpenSession(original.pid);
+                        if (!stillOpen || !sameCodexOpenSession(lockedSession, stillOpen)) {
+                            throw new Error('The Codex session changed before Conversation activation');
+                        }
+                        throwIfAborted(signal);
+                        // This exact control-mode connection sends C-c and arms collection synchronously at that
+                        // command's %end. Output rendered before the interrupt can never satisfy freshness.
+                        await outputCapture.sendKey('C-c');
+                        if (durable) {
+                            durable = receipts?.transition(durable.operationId, ['prepared', 'interrupted'], 'interrupted') ?? durable;
+                        }
+                        let originalStillVerified = true;
+                        for (let attempt = 0; attempt < 10; attempt += 1) {
+                            await wait(500);
+                            throwIfAborted(signal);
+                            const current = await processAfterInterrupt(paneId);
+                            if (!current)
+                                throw new Error('The pane closed during Conversation activation');
+                            if (current.kind === 'unknown') {
+                                originalStillVerified = false;
+                                continue;
+                            }
+                            if (current.kind === 'shell') {
+                                shell = current.identity;
+                                exited = true;
+                                break;
+                            }
+                            if (current.kind === 'other' || !current.identity
+                                || !sameProcess(original, current.identity)) {
+                                throw new Error('The Agent process changed during Conversation activation');
+                            }
+                            originalStillVerified = true;
+                        }
+                        // Never send another interrupt unless the last complete snapshot still proves the original Codex.
+                        if (!originalStillVerified)
+                            break;
                     }
-                }
-                if (!exited || !shell)
-                    throw new Error('Codex did not exit; close any open panel in the terminal and try again');
-                let sessionId = null;
-                for (let attempt = 0; attempt < 20; attempt += 1) {
-                    throwIfAborted(signal);
-                    const beforeCapture = await shellIdentity(paneId);
-                    if (!beforeCapture || !sameProcess(shell, beforeCapture)) {
-                        throw new Error('The pane shell changed during Conversation activation');
-                    }
+                    if (!exited || !shell)
+                        throw new Error('Codex did not exit; close any open panel in the terminal and try again');
                     try {
-                        const candidate = codexExitSessionId(await commands.capturePlain(paneId));
-                        if (codex.sessions.isId(candidate)) {
-                            sessionId = candidate;
-                            break;
+                        throwIfAborted(signal);
+                        const beforeResume = await shellIdentity(paneId);
+                        if (!beforeResume || !sameProcess(shell, beforeResume)) {
+                            throw new Error('The pane shell changed before Conversation activation');
                         }
+                        throwIfAborted(signal);
+                        if (durable) {
+                            durable = receipts?.transition(durable.operationId, ['interrupted', 'resuming'], 'resuming') ?? durable;
+                        }
+                        await commands.runPaneCommand(paneId, resume);
                     }
-                    catch {
-                        throw new Error('The pane closed during Conversation activation');
+                    catch (error) {
+                        if (error instanceof ConversationActivationError)
+                            throw error;
+                        throw new ConversationActivationError('Conversation activation could not finish; use the recovery command or continue in the terminal', 'unavailable', recovery);
                     }
-                    await wait(100);
+                    return { recovery };
                 }
-                if (!sessionId)
-                    throw new Error('Codex did not expose a resumable session; continue in the terminal');
-                const resume = codex.sessions.managedResumeCmd?.(sessionId);
-                if (!resume)
-                    throw new Error('Managed Conversation activation is unavailable');
-                throwIfAborted(signal);
-                const beforeResume = await shellIdentity(paneId);
-                if (!beforeResume || !sameProcess(shell, beforeResume)) {
-                    throw new Error('The pane shell changed before Conversation activation');
+                finally {
+                    signal.removeEventListener('abort', abortCapture);
+                    outputCapture.close();
                 }
-                throwIfAborted(signal);
-                await commands.runPaneCommand(paneId, resume);
             });
         },
     };

package/dist/src/agents/codexOpenSession.js

@@ -0,0 +1,164 @@
+import path from 'node:path';
+import { promises as fsp } from 'node:fs';
+import { defaultRun, isSessionUuid } from './scanUtils.js';
+import { rolloutSessionId } from './codex.js';
+const MAX_SESSION_META_BYTES = 1024 * 1024;
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function lsofOpenFiles(value) {
+    const files = [];
+    let fd = '';
+    for (const line of String(value || '').split('\n')) {
+        if (line[0] === 'f') {
+            fd = line.slice(1).trim();
+            continue;
+        }
+        if (line[0] === 'n' && fd)
+            files.push({ fd, file: line.slice(1) });
+    }
+    return files;
+}
+async function procOpenFiles(pid, fs) {
+    const directory = `/proc/${pid}/fd`;
+    let names;
+    try {
+        names = await fs.readdir(directory);
+    }
+    catch {
+        return [];
+    }
+    const files = [];
+    for (const fd of names) {
+        if (!/^\d+$/.test(fd))
+            continue;
+        try {
+            const file = await fs.readlink(path.join(directory, fd));
+            // Linux appends this marker after the original path once the directory entry is gone. A deleted
+            // rollout cannot be resumed by id, so it is never a takeover candidate.
+            if (file && !file.endsWith(' (deleted)'))
+                files.push({ fd, file });
+        }
+        catch { /* the descriptor closed while enumerating */ }
+    }
+    return files;
+}
+async function readFirstLine(file, fs) {
+    let handle;
+    try {
+        handle = await fs.open(file, 'r');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const buffer = Buffer.alloc(MAX_SESSION_META_BYTES + 1);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        if (bytesRead === 0)
+            return null;
+        const newline = buffer.subarray(0, bytesRead).indexOf(0x0a);
+        if (newline < 0 && bytesRead > MAX_SESSION_META_BYTES)
+            return null;
+        return buffer.subarray(0, newline < 0 ? bytesRead : newline).toString('utf8').replace(/\r$/, '');
+    }
+    finally {
+        await handle.close();
+    }
+}
+function rootSessionMeta(line, sessionId) {
+    if (!line)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!isRecord(value) || value.type !== 'session_meta' || !isRecord(value.payload))
+        return null;
+    const meta = value.payload;
+    if (meta.id !== sessionId || meta.session_id !== sessionId
+        || (meta.parent_thread_id !== undefined && meta.parent_thread_id !== null)
+        || meta.thread_source !== 'user'
+        || typeof meta.cwd !== 'string' || !meta.cwd)
+        return null;
+    return { cwd: meta.cwd };
+}
+function inside(root, file) {
+    const relative = path.relative(root, file);
+    return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative);
+}
+// Resolve the exact root conversation owned by one already-verified foreground Codex process. The process
+// may also hold many subagent rollouts; metadata, not cwd or mtime, distinguishes the single TUI root.
+// Every uncertainty fails closed before activation can interrupt the process.
+export async function inspectCodexOpenRootSession(pid, sessionsRoot, { platform = process.platform, run = defaultRun, fs = fsp, } = {}) {
+    if (!Number.isSafeInteger(pid) || pid <= 0 || !path.isAbsolute(sessionsRoot))
+        return null;
+    let canonicalRoot;
+    try {
+        canonicalRoot = await fs.realpath(sessionsRoot);
+    }
+    catch {
+        return null;
+    }
+    let openFiles;
+    if (platform === 'linux') {
+        openFiles = await procOpenFiles(pid, fs);
+    }
+    else {
+        let output = '';
+        try {
+            output = await run('lsof', ['-a', '-p', String(pid), '-Fn']);
+        }
+        catch {
+            return null;
+        }
+        openFiles = lsofOpenFiles(output);
+    }
+    if (!openFiles.length)
+        return null;
+    const candidates = new Map();
+    for (const open of openFiles) {
+        let canonicalFile;
+        try {
+            canonicalFile = await fs.realpath(open.file);
+        }
+        catch {
+            continue;
+        }
+        if (!inside(canonicalRoot, canonicalFile))
+            continue;
+        const sessionId = rolloutSessionId(path.basename(canonicalFile));
+        if (!sessionId || !isSessionUuid(sessionId))
+            continue;
+        let stat;
+        try {
+            stat = await fs.stat(canonicalFile);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        const meta = rootSessionMeta(await readFirstLine(canonicalFile, fs), sessionId);
+        if (!meta)
+            continue;
+        const candidate = {
+            sessionId: sessionId.toLowerCase(),
+            file: canonicalFile,
+            cwd: meta.cwd,
+            fd: open.fd,
+            device: String(stat.dev),
+            inode: String(stat.ino),
+        };
+        const key = `${candidate.device}:${candidate.inode}`;
+        candidates.set(key, candidate);
+    }
+    return candidates.size === 1 ? [...candidates.values()][0] ?? null : null;
+}
+export function sameCodexOpenSession(first, second) {
+    return first.sessionId === second.sessionId && first.file === second.file
+        && first.fd === second.fd && first.device === second.device && first.inode === second.inode;
+}