handmux 0.26.0 → 0.27.2

package/dist/src/agent-runtime/conversationActivation.js

@@ -1,8 +1,37 @@
+const CODEX_SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function validRecovery(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const recovery = value;
+    return recovery.kind === 'codex_resume'
+        && typeof recovery.sessionId === 'string'
+        && CODEX_SESSION_ID_RE.test(recovery.sessionId)
+        && recovery.command === `handmux codex resume ${recovery.sessionId}`;
+}
+function sameRecovery(first, second) {
+    return first.kind === second.kind
+        && first.sessionId === second.sessionId
+        && first.command === second.command;
+}
+function validRecoveryReceipt(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const receipt = value;
+    return typeof receipt.operationId === 'string'
+        && /^[0-9a-f]{64}$/.test(receipt.operationId)
+        && validRecovery(receipt.recovery)
+        && (receipt.phase === 'prepared' || receipt.phase === 'interrupted' || receipt.phase === 'resuming')
+        && (receipt.state === 'current' || receipt.state === 'stale')
+        && typeof receipt.canResume === 'boolean'
+        && (!receipt.canResume || (receipt.state === 'current' && receipt.phase !== 'resuming'));
+}
 export class ConversationActivationError extends Error {
     code;
-    constructor(message, code) {
+    recovery;
+    constructor(message, code, recovery) {
         super(message);
         this.code = code;
+        this.recovery = recovery;
         this.name = 'ConversationActivationError';
     }
 }
@@ -47,6 +76,19 @@ export class AgentConversationActivationService {
             throw new ConversationActivationError('Conversation activation is already in progress', 'in_progress');
         }
         this.#active.add(key);
+        let reportedRecovery;
+        const progress = {
+            recovery: (value) => {
+                if (!validRecovery(value)) {
+                    throw new ConversationActivationError('Invalid Conversation activation recovery', 'contract_violation');
+                }
+                const next = structuredClone(value);
+                if (reportedRecovery && !sameRecovery(reportedRecovery, next)) {
+                    throw new ConversationActivationError('Conversation activation recovery changed', 'contract_violation');
+                }
+                reportedRecovery = next;
+            },
+        };
         const operation = new AbortController();
         const cancel = () => operation.abort(signal?.reason ?? new Error('Activation request cancelled'));
         signal?.addEventListener('abort', cancel, { once: true });
@@ -59,16 +101,106 @@ export class AgentConversationActivationService {
             const aborted = new Promise((_resolve, reject) => {
                 operation.signal.addEventListener('abort', () => reject(operation.signal.reason), { once: true });
             });
-            await Promise.race([controller.activate(run, operation.signal), aborted]);
+            const result = await Promise.race([controller.activate(run, operation.signal, progress), aborted]);
+            if (!result)
+                return reportedRecovery ? { recovery: reportedRecovery } : undefined;
+            if (!validRecovery(result.recovery)
+                || (reportedRecovery && !sameRecovery(reportedRecovery, result.recovery))) {
+                throw new ConversationActivationError('Invalid Conversation activation recovery', 'contract_violation');
+            }
+            return { recovery: structuredClone(result.recovery) };
+        }
+        catch (error) {
+            if (error instanceof ConversationActivationError) {
+                if (error.recovery !== undefined && (!validRecovery(error.recovery)
+                    || (reportedRecovery !== undefined && !sameRecovery(reportedRecovery, error.recovery)))) {
+                    throw new ConversationActivationError('Invalid Conversation activation recovery', 'contract_violation');
+                }
+                if (error.recovery !== undefined || reportedRecovery === undefined)
+                    throw error;
+                throw new ConversationActivationError(error.message, error.code, reportedRecovery);
+            }
+            throw new ConversationActivationError('Conversation activation could not finish; continue in the terminal or try again', 'unavailable', reportedRecovery);
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', cancel);
+            this.#active.delete(key);
+        }
+    }
+    async recovery(paneId) {
+        if (!/^%\d+$/.test(paneId)) {
+            throw new ConversationActivationError('Invalid Conversation activation pane', 'contract_violation');
+        }
+        for (const controller of this.#controllers.values()) {
+            if (!controller.recovery)
+                continue;
+            try {
+                const receipt = await controller.recovery(paneId);
+                if (receipt === null)
+                    continue;
+                if (!validRecoveryReceipt(receipt)) {
+                    throw new ConversationActivationError('Invalid Conversation recovery receipt', 'contract_violation');
+                }
+                return structuredClone(receipt);
+            }
+            catch (error) {
+                if (error instanceof ConversationActivationError)
+                    throw error;
+                throw new ConversationActivationError('Conversation recovery is temporarily unavailable', 'unavailable');
+            }
+        }
+        return null;
+    }
+    async recover(paneId, operationId) {
+        if (!/^%\d+$/.test(paneId) || !/^[0-9a-f]{64}$/.test(operationId)) {
+            throw new ConversationActivationError('Invalid Conversation recovery request', 'contract_violation');
+        }
+        const controller = [...this.#controllers.values()].find((candidate) => candidate.recover);
+        if (!controller?.recover) {
+            throw new ConversationActivationError('Conversation recovery unsupported', 'unsupported');
+        }
+        const key = `recovery\0${operationId}`;
+        if (this.#active.has(key)) {
+            throw new ConversationActivationError('Conversation recovery is already in progress', 'in_progress');
+        }
+        this.#active.add(key);
+        let reportedRecovery;
+        const progress = { recovery: (value) => {
+                if (!validRecovery(value)) {
+                    throw new ConversationActivationError('Invalid Conversation recovery', 'contract_violation');
+                }
+                const next = structuredClone(value);
+                if (reportedRecovery && !sameRecovery(reportedRecovery, next)) {
+                    throw new ConversationActivationError('Conversation recovery changed', 'contract_violation');
+                }
+                reportedRecovery = next;
+            } };
+        const operation = new AbortController();
+        const timer = setTimeout(() => operation.abort(new Error('Conversation recovery timed out')), this.#timeoutMs);
+        try {
+            const aborted = new Promise((_resolve, reject) => {
+                operation.signal.addEventListener('abort', () => reject(operation.signal.reason), { once: true });
+            });
+            const result = await Promise.race([
+                controller.recover(paneId, operationId, operation.signal, progress),
+                aborted,
+            ]);
+            if (!result)
+                return reportedRecovery ? { recovery: reportedRecovery } : undefined;
+            if (!validRecovery(result.recovery)
+                || (reportedRecovery && !sameRecovery(reportedRecovery, result.recovery))) {
+                throw new ConversationActivationError('Invalid Conversation recovery', 'contract_violation');
+            }
+            return { recovery: structuredClone(result.recovery) };
         }
         catch (error) {
             if (error instanceof ConversationActivationError)
                 throw error;
-            throw new ConversationActivationError('Conversation activation could not finish; continue in the terminal or try again', 'unavailable');
+            throw new ConversationActivationError('Conversation recovery could not finish; copy the command or continue in the terminal', 'unavailable', reportedRecovery);
         }
         finally {
             clearTimeout(timer);
-            signal?.removeEventListener('abort', cancel);
             this.#active.delete(key);
         }
     }

package/dist/src/agent-runtime/run.js

@@ -108,7 +108,8 @@ export class AgentRunRuntime {
         }
         return Object.freeze({
             attach: (candidate) => this.#attach(agentId, verify, candidate),
-            associateSession: (lease, sessionId) => (this.#associateSession(agentId, lease, sessionId)),
+            associateSession: (lease, sessionId) => (this.#associateSession(agentId, verify, lease, sessionId)),
+            replaceSession: (lease, sessionId) => (this.#replaceSession(agentId, verify, lease, sessionId)),
             replace: (current, candidate, reason) => this.#replace(agentId, verify, current, candidate, reason),
             revoke: (lease, reason) => this.#revoke(agentId, lease, reason),
         });
@@ -206,6 +207,7 @@ export class AgentRunRuntime {
         record.lease = Object.freeze({
             get ref() { return record.ref; },
             signal: abort.signal,
+            process: record.process,
         });
         this.#records.set(record.lease, record);
         return record;
@@ -274,7 +276,7 @@ export class AgentRunRuntime {
             return this.#replaceInstalled(paneOwner, created, 'process_exit');
         });
     }
-    async #associateSession(agentId, lease, sessionId) {
+    async #associateSession(agentId, verify, lease, sessionId) {
         if (!validText(sessionId, 1024)) {
             throw new AgentRunError('invalid-candidate', 'sessionId must be a non-empty bounded string');
         }
@@ -284,6 +286,14 @@ export class AgentRunRuntime {
             if (this.#byRunId.get(record.ref.runId) !== record || record.abort.signal.aborted) {
                 throw new AgentRunError('stale-lease', 'Cannot associate a session with a stale Agent run');
             }
+            await this.#verify(verify, {
+                paneId: record.paneId,
+                attachmentId: record.attachmentId,
+                ...(record.ref.sessionId === undefined ? {} : { sessionId: record.ref.sessionId }),
+                ...(record.ref.implementationVersion === undefined
+                    ? {} : { implementationVersion: record.ref.implementationVersion }),
+                process: { ...record.process },
+            });
             if (record.ref.sessionId === sessionId)
                 return record.ref;
             if (record.ref.sessionId !== undefined) {
@@ -317,6 +327,17 @@ export class AgentRunRuntime {
             return this.#replaceInstalled(record, created, reason);
         });
     }
+    async #replaceSession(agentId, verify, current, sessionId) {
+        const record = this.#recordFor(agentId, current);
+        return this.#replace(agentId, verify, current, {
+            paneId: record.paneId,
+            attachmentId: record.attachmentId,
+            sessionId,
+            ...(record.ref.implementationVersion === undefined
+                ? {} : { implementationVersion: record.ref.implementationVersion }),
+            process: { ...record.process },
+        }, 'session_replaced');
+    }
     async #revoke(agentId, lease, reason) {
         const known = this.#recordFor(agentId, lease);
         await this.#withPane(known.paneId, async () => {

package/dist/src/agent-runtime/runtime.js

@@ -58,16 +58,43 @@ export function validSubscriptionUsageAdapter(value) {
     return adapter !== null && typeof adapter === 'object' && adapter.apiVersion === 1
         && typeof adapter.snapshot === 'function';
 }
-function sameProcess(candidate, pane, foreground) {
+function compareProcess(candidate, pane, foreground) {
     if (foreground.pid !== candidate.process.pid)
-        return false;
-    if (pane.foregroundPid !== undefined && pane.foregroundPid !== candidate.process.pid)
-        return false;
+        return 'invalid';
+    if (pane.foregroundPid !== undefined
+        && pane.foregroundPid !== candidate.process.pid)
+        return 'invalid';
     if (candidate.process.startedAt !== undefined
+        && foreground.startedAt !== undefined
         && foreground.startedAt !== candidate.process.startedAt)
-        return false;
+        return 'invalid';
     const observedTty = foreground.tty ?? pane.tty;
-    return candidate.process.tty === undefined || observedTty === candidate.process.tty;
+    if (candidate.process.tty !== undefined && observedTty
+        && observedTty !== candidate.process.tty)
+        return 'invalid';
+    if ((candidate.process.startedAt !== undefined && foreground.startedAt === undefined)
+        || (candidate.process.tty !== undefined && !observedTty))
+        return 'unknown';
+    return 'valid';
+}
+function processAttachmentCandidate(adapter, pane, foreground) {
+    const process = {
+        pid: foreground.pid,
+        ...(foreground.startedAt === undefined ? {} : { startedAt: foreground.startedAt }),
+        ...(foreground.tty === undefined
+            ? (pane.tty === undefined ? {} : { tty: pane.tty })
+            : { tty: foreground.tty }),
+    };
+    const fingerprint = crypto.createHash('sha256').update(JSON.stringify({
+        agentId: adapter.id,
+        paneId: pane.paneId,
+        process,
+    })).digest('hex');
+    return {
+        paneId: pane.paneId,
+        attachmentId: `runtime.process:${fingerprint}`,
+        process,
+    };
 }
 function recoverCorruptState({ file, kind, logger, create, isContractError, }) {
     try {
@@ -154,7 +181,8 @@ export class AgentRuntime {
     #health = new Map();
     #transport;
     #unsubscribePanes;
-    #reconcileTail = Promise.resolve();
+    #pendingReconcile;
+    #reconcileDrain;
     #startPromise;
     #started = false;
     #closed = false;
@@ -567,14 +595,20 @@ export class AgentRuntime {
             if (this.#closed)
                 throw new Error('AgentRuntime is closed');
             unsubscribe = this.#panes.subscribe((snapshot) => {
-                const operation = this.#reconcileTail.then(() => this.#reconcile(snapshot));
-                this.#reconcileTail = operation.catch((error) => {
-                    this.#logger.warn('Agent pane reconciliation failed', {
-                        error: error instanceof Error ? error.message : String(error),
-                    });
-                });
+                this.#offerReconcile(snapshot);
             });
             this.#unsubscribePanes = unsubscribe;
+            // Establish Runtime-owned process runs before capability coordinators consume provider rows.
+            // The subscription remains the retry path when this best-effort initial read is unavailable.
+            try {
+                const initial = await this.#panes.list();
+                await this.#waitForReconcile(initial);
+            }
+            catch (error) {
+                this.#logger.warn('Initial Agent pane reconciliation failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
             for (const adapter of this.adapters) {
                 if (this.#closed)
                     throw new Error('AgentRuntime is closed');
@@ -609,10 +643,11 @@ export class AgentRuntime {
         if (this.#closed)
             return;
         this.#closed = true;
+        this.#cancelPendingReconcile(new Error('AgentRuntime is closed'));
         await this.#startPromise?.catch(() => { });
         this.#unsubscribePanes?.();
         this.#unsubscribePanes = undefined;
-        await this.#reconcileTail.catch(() => { });
+        await this.#reconcileDrain?.catch(() => { });
         await this.#transport.close();
         await this.runs.shutdown();
         await this.interaction?.shutdown();
@@ -680,6 +715,7 @@ export class AgentRuntime {
             runControl: this.#controllers.get(adapter.id),
             panes: this.#panes,
             process: this.#process,
+            currentRunForPane: (paneId) => this.runs.currentForPane(paneId),
             bridge: this.bridge.hostFor(adapter.id),
             resources: this.resources.forAdapter(adapter.id),
             logger: this.#logger,
@@ -698,6 +734,79 @@ export class AgentRuntime {
         const key = `${adapterId}\0${update.capability ?? ''}`;
         this.#health.set(key, { adapterId, ...structuredClone(update) });
     }
+    #offerReconcile(snapshot) {
+        if (this.#closed)
+            return;
+        if (this.#pendingReconcile)
+            this.#pendingReconcile.snapshot = structuredClone(snapshot);
+        else
+            this.#pendingReconcile = { snapshot: structuredClone(snapshot), waiters: [] };
+        this.#ensureReconcileDrain();
+    }
+    #waitForReconcile(snapshot) {
+        if (this.#closed)
+            return Promise.reject(new Error('AgentRuntime is closed'));
+        const operation = new Promise((resolve, reject) => {
+            const waiter = { resolve, reject };
+            if (this.#pendingReconcile) {
+                this.#pendingReconcile.snapshot = structuredClone(snapshot);
+                this.#pendingReconcile.waiters.push(waiter);
+            }
+            else {
+                this.#pendingReconcile = { snapshot: structuredClone(snapshot), waiters: [waiter] };
+            }
+        });
+        this.#ensureReconcileDrain();
+        return operation;
+    }
+    #ensureReconcileDrain() {
+        if (this.#closed || this.#reconcileDrain || !this.#pendingReconcile)
+            return;
+        const drain = this.#drainReconciles();
+        this.#reconcileDrain = drain;
+        const finish = () => {
+            if (this.#reconcileDrain === drain)
+                this.#reconcileDrain = undefined;
+            if (!this.#closed && this.#pendingReconcile)
+                this.#ensureReconcileDrain();
+        };
+        void drain.then(finish, (error) => {
+            try {
+                this.#logger.warn('Agent pane reconciliation drain failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            catch { /* diagnostics must not create an unhandled rejection */ }
+            finish();
+        });
+    }
+    async #drainReconciles() {
+        while (!this.#closed) {
+            const pending = this.#pendingReconcile;
+            if (!pending)
+                return;
+            this.#pendingReconcile = undefined;
+            try {
+                await this.#reconcile(pending.snapshot);
+                pending.waiters.forEach((waiter) => waiter.resolve());
+            }
+            catch (error) {
+                pending.waiters.forEach((waiter) => waiter.reject(error));
+                try {
+                    this.#logger.warn('Agent pane reconciliation failed', {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                catch { /* diagnostics must not strand reconciliation waiters */ }
+            }
+        }
+        this.#cancelPendingReconcile(new Error('AgentRuntime is closed'));
+    }
+    #cancelPendingReconcile(error) {
+        const pending = this.#pendingReconcile;
+        this.#pendingReconcile = undefined;
+        pending?.waiters.forEach((waiter) => waiter.reject(error));
+    }
     #trackedController(adapter, raw) {
         return Object.freeze({
             attach: async (candidate) => (this.#track(adapter, await raw.attach(candidate), candidate)),
@@ -708,6 +817,14 @@ export class AgentRuntime {
                     tracked.candidate.sessionId = sessionId;
                 return ref;
             },
+            replaceSession: async (lease, sessionId) => {
+                const tracked = this.#tracked.get(lease.ref.runId);
+                if (!tracked || tracked.adapter.id !== adapter.id || tracked.lease !== lease) {
+                    throw new Error('Agent run lease is not tracked by Runtime');
+                }
+                const candidate = { ...cloneCandidate(tracked.candidate), sessionId };
+                return this.#track(adapter, await raw.replaceSession(lease, sessionId), candidate);
+            },
             replace: async (current, candidate, reason) => (this.#track(adapter, await raw.replace(current, candidate, reason), candidate)),
             revoke: (lease, reason) => raw.revoke(lease, reason),
         });
@@ -809,7 +926,9 @@ export class AgentRuntime {
                 const foreground = await context.inspectForeground(pane);
                 if (foreground === null)
                     return 'unknown';
-                return sameProcess(candidate, pane, foreground) ? 'valid' : 'invalid';
+                // A partial best-effort probe cannot prove that the process generation changed. Preserve the
+                // complete lease and retry only when every field that is present still agrees.
+                return compareProcess(candidate, pane, foreground);
             })(), this.#verifyTimeoutMs, 'Agent process verification');
         }
         catch {
@@ -831,5 +950,45 @@ export class AgentRuntime {
                 await this.runs.revokePane(tracked.lease.ref.paneId, pane ? 'process_exit' : 'pane_detached');
             }
         }
+        const activeAdapters = this.adapters.filter((adapter) => (!this.#lifecycles.get(adapter.id)?.abort.signal.aborted));
+        for (const pane of panes.values()) {
+            if (this.#closed || this.runs.currentForPane(pane.paneId))
+                continue;
+            let inspected;
+            const context = {
+                inspectForeground: () => {
+                    inspected ??= this.#process.inspectForeground(pane);
+                    return inspected;
+                },
+            };
+            const identity = await resolveAgentIdentity(pane, activeAdapters, context, {
+                verifyTimeoutMs: this.#verifyTimeoutMs,
+            });
+            if (identity.kind !== 'matched' || identity.adapter.process.runtimeAttach !== true)
+                continue;
+            let foreground;
+            try {
+                // Exact command matches skip Adapter verification, so bound this probe at its own use site.
+                // A timed-out result must not attach later or block other panes and subsequent snapshots.
+                foreground = await lifecycleWithin(context.inspectForeground(pane), this.#verifyTimeoutMs, 'Agent process discovery');
+            }
+            catch {
+                continue;
+            }
+            // A PID without its start time is not a process generation. Do not publish a lease that
+            // destructive capabilities must permanently reject; the next pane poll retries the probe.
+            if (!foreground || foreground.startedAt === undefined || !(foreground.tty ?? pane.tty))
+                continue;
+            try {
+                await this.#controllers.get(identity.adapter.id).attach(processAttachmentCandidate(identity.adapter, pane, foreground));
+            }
+            catch (error) {
+                this.#logger.warn('Agent process attachment failed', {
+                    adapterId: identity.adapter.id,
+                    paneId: pane.paneId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
     }
 }

package/dist/src/agent-runtime/tmuxRuntime.js

@@ -10,14 +10,14 @@ function pane(value) {
         ...(value.tty ? { tty: value.tty } : {}),
     };
 }
-// Tmux has no lifecycle subscription. One shared, non-overlapping poller publishes complete snapshots;
-// an unavailable tmux command preserves the last trusted snapshot instead of fabricating process exits.
+// Tmux has no lifecycle subscription. One shared, non-overlapping poller publishes every successful
+// complete snapshot: unchanged pane metadata can still hide a replaced foreground PID. An unavailable
+// tmux command preserves the last trusted snapshot instead of fabricating process exits.
 export class TmuxAgentPaneSource {
     #commands;
     #pollMs;
     #listeners = new Set();
     #timer;
-    #signature = '';
     #polling = false;
     constructor({ commands, pollMs = 1_000 }) {
         if (!commands || typeof commands.listLivePanes !== 'function'
@@ -59,10 +59,6 @@ export class TmuxAgentPaneSource {
             catch {
                 return;
             }
-            const signature = JSON.stringify(snapshot);
-            if (signature === this.#signature)
-                return;
-            this.#signature = signature;
             for (const listener of this.#listeners)
                 listener(structuredClone(snapshot));
         })().finally(() => {

package/dist/src/agents/codex.js

@@ -14,20 +14,76 @@ export function rolloutSessionId(name) {
     const m = String(name).match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/i);
     return m?.[1] || null;
 }
-const UUID_PARTS = '([0-9a-f]{8})\\s*-\\s*([0-9a-f]{4})\\s*-\\s*([0-9a-f]{4})\\s*-\\s*([0-9a-f]{4})\\s*-\\s*([0-9a-f]{12})';
-function lastUuidAfter(text, prefix) {
-    const matches = [...String(text || '').matchAll(new RegExp(`${prefix}\\s*${UUID_PARTS}`, 'gi'))];
-    const match = matches.at(-1);
-    if (!match)
-        return null;
-    const parts = match.slice(1, 6);
-    return parts.length === 5 && parts.every(Boolean) ? parts.join('-').toLowerCase() : null;
-}
+const CODEX_EXIT_PREFIX = 'To continue this session, run\\s+codex\\s+resume';
+const UUID_VALUE = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const CODEX_DIRECT_EXIT = new RegExp(`^\\s*${CODEX_EXIT_PREFIX}\\s+(${UUID_VALUE})\\s*$`, 'i');
+const CODEX_PICKER_EXIT = new RegExp(`^\\s*${CODEX_EXIT_PREFIX}\\s*,\\s*then\\s+select\\s+.+\\(\\s*(${UUID_VALUE})\\s*\\)\\s*$`, 'i');
 // A normal Codex exit prints the exact command for the session that just exited. Keep this deliberately
 // stricter than a generic `codex resume` search so conversation text or shell history is not mistaken for
 // the current exit notice.
 export function codexExitSessionId(text) {
-    return lastUuidAfter(text, 'To continue this session, run\\s+codex\\s+resume');
+    let sessionId = null;
+    for (const line of String(text || '').split(/\r?\n/)) {
+        const candidate = line.match(CODEX_DIRECT_EXIT)?.[1] ?? line.match(CODEX_PICKER_EXIT)?.[1];
+        if (candidate && isSessionUuid(candidate))
+            sessionId = candidate.toLowerCase();
+    }
+    return sessionId;
+}
+const OSC_SEQUENCE = /\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g;
+const CSI_SEQUENCE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+const MAX_CODEX_EXIT_FRAMES = 4_096;
+const MAX_CODEX_EXIT_LINE_BYTES = 8 * 1_024;
+function collectCodexExitOutputCandidates(output, candidates) {
+    const plain = String(output || '').replace(OSC_SEQUENCE, '').replace(CSI_SEQUENCE, '');
+    for (const line of plain.split(/\r?\n/)) {
+        const candidate = codexExitSessionId(line);
+        if (candidate)
+            candidates.add(candidate);
+    }
+}
+export function codexExitOutputSessionId(output) {
+    const candidates = new Set();
+    collectCodexExitOutputCandidates(output, candidates);
+    return candidates.size === 1 ? [...candidates][0] ?? null : null;
+}
+// A tmux control-mode frame is also a trustworthy output boundary. Codex can emit its exit notice in a
+// fresh frame without first writing CR/LF after the preceding TUI status, and tmux can split that notice
+// across later frames. Test only the first bounded logical line from each real frame boundary, plus normal
+// CR/LF-delimited lines from the full stream; never scan for the prefix at an arbitrary text offset.
+export function codexExitOutputFramesSessionId(frames) {
+    if (!frames.length || frames.length > MAX_CODEX_EXIT_FRAMES)
+        return null;
+    const candidates = new Set();
+    collectCodexExitOutputCandidates(Buffer.concat(frames), candidates);
+    for (let start = 0; start < frames.length; start += 1) {
+        const chunks = [];
+        let bytes = 0;
+        let complete = false;
+        for (let index = start; index < frames.length && bytes < MAX_CODEX_EXIT_LINE_BYTES; index += 1) {
+            const frame = frames[index];
+            if (!frame)
+                continue;
+            const newline = frame.indexOf(0x0a);
+            const available = newline < 0 ? frame.length : newline + 1;
+            const take = Math.min(available, MAX_CODEX_EXIT_LINE_BYTES - bytes);
+            if (take > 0) {
+                chunks.push(frame.subarray(0, take));
+                bytes += take;
+            }
+            if (newline >= 0 && take === available) {
+                complete = true;
+                break;
+            }
+            if (take < available)
+                break;
+            if (index === frames.length - 1)
+                complete = true;
+        }
+        if (complete)
+            collectCodexExitOutputCandidates(Buffer.concat(chunks, bytes), candidates);
+    }
+    return candidates.size === 1 ? [...candidates][0] ?? null : null;
 }
 // Last user turn out of a Codex rollout tail, for a recognizable one-line label. Codex records turns as
 // response_item messages: {payload:{type:'message',role:'user',content:[{type:'input_text',text}]}} (and a
@@ -188,6 +244,17 @@ export async function resolveCodexRollout(dir, sessionId) {
     }
     return found;
 }
+export async function codexSessionCwd(sessionId, dir = sessionsDir()) {
+    const file = await resolveCodexRollout(dir, sessionId);
+    if (!file)
+        return null;
+    try {
+        return firstCwd(await readHead(file)) || null;
+    }
+    catch {
+        return null;
+    }
+}
 // Resolve a live orphan's cwd to its Codex session: the newest rollout whose recorded cwd matches. Same
 // shape as Claude's resolver ({ sessionId, state, snippet, lastActivity }) so the orphan engine is agnostic.
 export async function resolveCodexSession(dir, cwd, { busyMs = 8000, now = Date.now } = {}) {
@@ -222,6 +289,7 @@ export const codex = {
     process: {
         commands: ['codex'],
         ambiguousCommands: ['node'],
+        runtimeAttach: true,
         verify: async (pane, context) => {
             const foreground = await context.inspectForeground(pane);
             const executable = foreground?.executable;