@scotthuang/agent-knock-knock 0.11.5 → 0.11.7

package/dist/src/cli.js

@@ -16,12 +16,13 @@ import { EXECUTOR_KINDS, executorDefinitionForKind, isExecutorKind } from "./exe
 import { redactString, writeRuntimeLog } from "./runtime-log.js";
 import { formatTranscript, readNdjsonLog } from "./transcript.js";
 import { appendEvent, assertStoreWriterCompatible, defaultStoreDir, ensureDir, ensureStoreWritable, inspectStoreCompatibility, listConversations, logPathForStatePath, loadConversationById, loadState, messageEvent, pathsForConversation, pathsForConversationDir, saveState, StoreLockTimeoutError, statePathForConversationId, withStoreWriterLease, withStoreWriterLeaseAsync } from "./store.js";
-import { createManagedSessionId, createNativeThreadTransitionId, isExactNativeThreadId, managedSessionBindingToken, nativeThreadCommandFingerprint, terminalBindingFrom, unmanagedTerminalBindingToken } from "./managed-session.js";
+import { createManagedSessionId, createNativeThreadTransitionId, isExactNativeThreadId, legacyManagedSessionBindingToken, legacyUnmanagedTerminalBindingToken, managedSessionBindingToken, nativeThreadCommandFingerprint, terminalBindingFrom, unmanagedTerminalBindingToken } from "./managed-session.js";
 import { classifyCodexLifecyclePostcondition, evaluateResumeCandidateAvailability, hasStrongCodexLifecycleIdentity, isFreshCodexPostProbeScreen } from "./native-thread-lifecycle-policy.js";
 import { createNativeThreadResumeSnapshot, nativeThreadCandidateSnapshotFingerprint, nativeThreadResumeSnapshotRowsMatchCandidates, resolveNativeThreadResumeSelection, saveNativeThreadResumeSnapshot, sortNativeThreadCandidates, terminalActionFingerprint, verifiedPreviousResumeCandidate } from "./native-thread-resume-snapshot.js";
 import { listManagedSessions, loadManagedSession, loadNativeThreadTransition, nativeThreadTransitionsDir, saveManagedSession, saveNativeThreadTransition, tryLoadManagedSession } from "./session-store.js";
-import { StaticTerminalControlProvider, TmuxTerminalControlProvider, terminalPaneContainsProcess } from "./terminal-control-provider.js";
+import { createTerminalControlProviderRegistry as createProviderRegistry, StaticTerminalControlProvider, TmuxTerminalControlProvider } from "./terminal-control-provider.js";
 import { parseTerminalConversationId } from "./terminal-agent-adapter.js";
+import { associateTerminalEndpointEvidence, hasCanonicalTerminalEndpoint, sameTerminalControlEvidenceIncarnation, sameTerminalControlIncarnation, terminalControlEvidence, terminalControlEvidenceMatches, terminalEndpointFromControlRef, terminalEndpointIdentityFromEvidence, terminalEndpointIdentityKey, terminalLegacyRuntimeRoute, sameTerminalEndpointIdentity } from "./terminal-control-ref.js";
 import { createProductionTerminalAgentRegistry } from "./terminal-agent-registry.js";
 import { parseProcessElapsedSeconds, StaticTerminalProcessSource, SystemTerminalProcessSource } from "./terminal-process-source.js";
 import { isExactClaudeNativeInspectionIdleComposer, NativeInspectionSubmissionError, TerminalAgentBridge, TerminalInputNotStartedError } from "./terminal-agent-bridge.js";
@@ -624,14 +625,22 @@ async function listActiveSessionsWithTerminalControl(provider, options, terminal
         : [];
     return createTerminalAgentBridge(options, terminalProvider).attachProcesses(provider.agent, activeSessions, { processTree });
 }
-function createTerminalControlProvider(options) {
-    if (options.terminalsJson || options.terminalScreensJson || options.processesJson) {
-        return new StaticTerminalControlProvider({
-            panes: options.terminalsJson ? parseJsonOption(options.terminalsJson, "--terminals-json") : [],
-            screens: options.terminalScreensJson ? parseJsonOption(options.terminalScreensJson, "--terminal-screens-json") : {}
-        });
-    }
-    return new TmuxTerminalControlProvider();
+function createRuntimeTerminalControlProviderRegistry(options) {
+    return createProviderRegistry([
+        options.terminalsJson || options.terminalScreensJson || options.processesJson
+            ? new StaticTerminalControlProvider({
+                panes: options.terminalsJson
+                    ? parseJsonOption(options.terminalsJson, "--terminals-json")
+                    : [],
+                screens: options.terminalScreensJson
+                    ? parseJsonOption(options.terminalScreensJson, "--terminal-screens-json")
+                    : {}
+            })
+            : new TmuxTerminalControlProvider()
+    ]);
+}
+function createTerminalControlProvider(options, registry = createRuntimeTerminalControlProviderRegistry(options)) {
+    return registry.require("tmux");
 }
 function createTerminalProcessSource(options) {
     if (options.processesJson) {
@@ -884,7 +893,10 @@ function createTerminalAgentBridge(options, terminalProvider = createTerminalCon
         terminalProvider,
         async verifyIdentity({ agent, pid, terminalControl, runtime }) {
             const adapter = registry.require(agent);
-            const expectedWorkspace = options.workspace ?? terminalControl.currentPath;
+            const requestedTerminal = terminalProvider.endpoint(terminalControl);
+            const resolvedTerminal = await terminalProvider.resolve(requestedTerminal);
+            const expectedWorkspace = options.workspace ?? resolvedTerminal.route.currentPath ??
+                terminalControl.currentPath;
             if (!expectedWorkspace) {
                 throw new Error(`refusing terminal access to ${terminalControl.target}; its workspace is unavailable`);
             }
@@ -896,15 +908,11 @@ function createTerminalAgentBridge(options, terminalProvider = createTerminalCon
             if (!snapshot || !adapter.classifyProcess(snapshot)) {
                 throw new Error(`terminal conversation agent ${agent} with pid ${pid} is no longer active`);
             }
-            const panes = await terminalProvider.listPanes();
-            const pane = panes.find((candidate) => candidate.kind === terminalControl.kind &&
-                candidate.target === terminalControl.target &&
-                candidate.panePid === terminalControl.panePid);
-            if (!pane || !terminalPaneContainsProcess(snapshot, pane, snapshots)) {
+            if (!terminalProvider.containsProcess(resolvedTerminal, snapshot, snapshots)) {
                 throw new Error(`terminal conversation agent ${agent} with pid ${pid} no longer belongs to pane ${terminalControl.target}`);
             }
             assertConfiguredWorkspace(expectedWorkspace, snapshot.cwd, `terminal access to ${terminalControl.target} by agent process ${pid}`);
-            assertConfiguredWorkspace(expectedWorkspace, pane.currentPath, `terminal access to ${terminalControl.target} by tmux pane`);
+            assertConfiguredWorkspace(expectedWorkspace, resolvedTerminal.route.currentPath, `terminal access to ${terminalControl.target} by terminal endpoint`);
             const requiresNativeIdentity = Boolean(runtime?.nativeSessionId ||
                 runtime?.nativeProcessUuid ||
                 runtime?.nativeProcessBirth ||
@@ -923,7 +931,7 @@ function createTerminalAgentBridge(options, terminalProvider = createTerminalCon
                     options,
                     agent,
                     pid,
-                    cwd: snapshot.cwd ?? pane.currentPath,
+                    cwd: snapshot.cwd ?? resolvedTerminal.route.currentPath,
                     preferredSessionId: runtime?.allowedPreMaterializationNativeIdentity &&
                         (runtime.expectedNativeSessionId ?? runtime.nativeSessionId) &&
                         runtime.allowedPreMaterializationNativeIdentity.sessionId !==
@@ -954,7 +962,7 @@ function createTerminalAgentBridge(options, terminalProvider = createTerminalCon
                     phase: "before",
                     pid,
                     processStartedAt: runtime.nativeProcessStartedAt,
-                    cwd: snapshot.cwd ?? pane.currentPath,
+                    cwd: snapshot.cwd ?? resolvedTerminal.route.currentPath,
                     agentRows
                 });
                 const exactRows = agentRows.filter((row) => row.pid === pid);
@@ -973,13 +981,7 @@ function createTerminalAgentBridge(options, terminalProvider = createTerminalCon
                 }
             }
             return {
-                terminalControl: {
-                    ...terminalControl,
-                    socketPath: pane.socketPath,
-                    panePid: pane.panePid,
-                    currentCommand: pane.currentCommand,
-                    currentPath: pane.currentPath
-                }
+                terminalControl: terminalProvider.toControlRef(resolvedTerminal, terminalControl.capabilities)
             };
         }
     });
@@ -1003,7 +1005,7 @@ function terminalControlFromTakeover(nativeTakeover) {
     const storedCapabilities = Array.isArray(terminalControl.capabilities)
         ? terminalControl.capabilities.filter(isTerminalControlCapability)
         : [];
-    return {
+    const control = {
         kind: "tmux",
         target,
         session,
@@ -1025,6 +1027,59 @@ function terminalControlFromTakeover(nativeTakeover) {
                 "terminal_cancel"
             ]
     };
+    const endpointEvidence = nativeTakeover["terminal_endpoint"];
+    if (endpointEvidence !== undefined) {
+        try {
+            associateTerminalEndpointEvidence(control, endpointEvidence);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return control;
+}
+function terminalEndpointTakeoverFields(terminalControl) {
+    return {
+        terminal_control: terminalControl,
+        ...(hasCanonicalTerminalEndpoint(terminalControl)
+            ? { terminal_endpoint: terminalControlEvidence(terminalControl) }
+            : {})
+    };
+}
+/**
+ * Add canonical endpoint evidence to a verified v0.11.x Turn without changing
+ * its public route-shaped terminal id or provider-owned control payload.
+ * Callers must already hold the terminal, Store-writer, and Turn state locks.
+ */
+function refineTerminalTurnEndpoint({ conversation, statePath, terminalControl }) {
+    const takeover = isRecord(conversation.native_session_takeover)
+        ? conversation.native_session_takeover
+        : undefined;
+    const storedControl = terminalControlFromTakeover(takeover);
+    if (!takeover ||
+        !storedControl ||
+        takeover.terminal_endpoint !== undefined ||
+        !hasCanonicalTerminalEndpoint(terminalControl)) {
+        return conversation;
+    }
+    if (!terminalControlsShareIncarnation(storedControl, terminalControl)) {
+        throw new Error(`cannot refine Turn ${turnIdForConversation(conversation)} terminal ` +
+            "endpoint after its terminal incarnation changed");
+    }
+    const terminalEndpoint = terminalControlEvidence(terminalControl);
+    // Validate that the additive evidence agrees with the exact legacy route
+    // before making it durable. This also restores the in-memory association on
+    // the old provider-owned control object.
+    associateTerminalEndpointEvidence(storedControl, terminalEndpoint);
+    const refined = {
+        ...conversation,
+        native_session_takeover: {
+            ...takeover,
+            terminal_endpoint: terminalEndpoint
+        }
+    };
+    saveState(statePath, refined);
+    return refined;
 }
 function terminalRuntimeIdentityForConversation(conversation, terminalControl) {
     const nativeTakeover = isRecord(conversation?.native_session_takeover)
@@ -1091,8 +1146,7 @@ function terminalRuntimeIdentityForConversation(conversation, terminalControl) {
         binding.generation !== Number(conversation.terminal_binding_generation) ||
         binding.native_thread_id !== expectedThreadId ||
         binding.native_process.pid !== runtime.pid ||
-        terminalControlSelectorKey(binding.terminal_control) !==
-            terminalControlSelectorKey(terminalControl)) {
+        !terminalControlsShareIncarnation(binding.terminal_control, terminalControl)) {
         return runtime;
     }
     return withCodexCompanionFences(runtime, codexAllowedCompanionSetForManagedSession({
@@ -1143,19 +1197,14 @@ async function migrateLegacyTerminalAgentIdentity({ conversation, statePath, log
         const registry = createRuntimeTerminalAgentRegistry(options);
         const adapter = registry.require("codex");
         const snapshots = await createTerminalProcessSource(options).listProcessSnapshots((snapshot) => adapter.classifyProcess(snapshot) !== undefined, { includeAncestors: true });
-        const panes = await createTerminalControlProvider(options).listPanes();
-        const matchingPanes = panes.filter((pane) => pane.kind === terminalControl.kind &&
-            pane.target === terminalControl.target &&
-            pane.panePid === terminalControl.panePid);
-        if (matchingPanes.length !== 1) {
-            return conversation;
-        }
+        const terminalProvider = createTerminalControlProvider(options);
+        const resolvedTerminal = await terminalProvider.resolve(terminalProvider.endpoint(terminalControl));
         const candidates = snapshots.flatMap((snapshot) => {
             const classified = adapter.classifyProcess(snapshot);
             return classified ? [{ ...classified, agent: "codex" }] : [];
         });
         const matches = candidates.filter((candidate) => candidate.sessionId === nativeSessionId &&
-            terminalPaneContainsProcess(candidate, matchingPanes[0], snapshots));
+            terminalProvider.containsProcess(resolvedTerminal, candidate, snapshots));
         if (matches.length !== 1) {
             return conversation;
         }
@@ -1189,9 +1238,7 @@ async function migrateLegacyTerminalAgentIdentity({ conversation, statePath, log
             return current;
         }
         if (currentTakeover.native_session_id !== nativeSessionId ||
-            currentControl.target !== terminalControl.target ||
-            currentControl.socketPath !== terminalControl.socketPath ||
-            currentControl.panePid !== terminalControl.panePid) {
+            !terminalControlsShareIncarnation(currentControl, terminalControl)) {
             return current;
         }
         const migratedAt = new Date().toISOString();
@@ -1271,10 +1318,8 @@ function assertSafeAbortedTerminalRetryBinding({ owner, receipt, storeDir, termi
         !Number.isSafeInteger(ownerAgentPid) ||
         binding.native_process.pid !== ownerAgentPid ||
         !ownerControl ||
-        terminalControlSelectorKey(ownerControl) !==
-            terminalControlSelectorKey(terminalControl) ||
-        terminalControlSelectorKey(binding.terminal_control) !==
-            terminalControlSelectorKey(terminalControl)) {
+        !terminalControlsShareIncarnation(ownerControl, terminalControl) ||
+        !terminalControlsShareIncarnation(binding.terminal_control, terminalControl)) {
         throw new Error(`terminal idempotency key ${messageId} belongs to a safe-aborted Turn ` +
             "whose Session binding is no longer current; no terminal input was sent");
     }
@@ -1346,16 +1391,17 @@ function stableDelegateTerminalRoute({ options, request, workspace, requestedAge
             receipt,
             conversationId,
             workspace: ownerWorkspace,
-            terminalKey: terminalControlSelectorKey(terminalControl),
-            panePid: terminalControl.panePid
+            terminalControl
         };
     });
     const authoritative = routed.filter(({ receipt }) => !(receipt.status === "aborted" && receipt.safe_to_retry === true));
     if (authoritative.length > 1) {
         throw new Error(`terminal idempotency key ${messageId} has multiple durable delegate receipts`);
     }
-    const terminalKeys = new Set(routed.map((entry) => `${entry.conversationId}\0${entry.terminalKey}\0${entry.panePid}`));
-    if (terminalKeys.size !== 1) {
+    const firstRoute = routed[0];
+    if (!firstRoute ||
+        routed.some((entry) => entry.conversationId !== firstRoute.conversationId ||
+            !terminalControlsShareIncarnation(entry.terminalControl, firstRoute.terminalControl))) {
         throw new Error(`terminal idempotency key ${messageId} has conflicting terminal routes`);
     }
     const selected = authoritative[0] ?? routed.at(-1);
@@ -1816,7 +1862,10 @@ function withTerminalBridgeSubmission({ conversation, messageId, messageType, me
             stringValue(nativeTakeover.terminal_agent_expected_session_id),
         terminal_target: storedControl?.target,
         terminal_socket_path: storedControl?.socketPath ?? null,
-        terminal_pane_pid: storedControl?.panePid
+        terminal_pane_pid: storedControl?.panePid,
+        terminal_endpoint: storedControl && hasCanonicalTerminalEndpoint(storedControl)
+            ? terminalControlEvidence(storedControl)
+            : previousReceipt?.terminal_endpoint
     };
     const immutableReceiptFields = Object.fromEntries(Object.entries(candidateImmutableReceiptFields).map(([key, value]) => [
         key,
@@ -1828,7 +1877,7 @@ function withTerminalBridgeSubmission({ conversation, messageId, messageType, me
         for (const [key, value] of Object.entries(candidateImmutableReceiptFields)) {
             if (previousReceipt[key] !== undefined &&
                 value !== undefined &&
-                String(previousReceipt[key]) !== String(value)) {
+                canonicalJson(previousReceipt[key]) !== canonicalJson(value)) {
                 throw new Error(`terminal submission receipt ${messageId} changed immutable ${key}`);
             }
         }
@@ -1909,27 +1958,18 @@ function replayExactActiveTerminalSubmission({ options, terminalControl, request
         throw new Error(`terminal idempotency key ${messageId} has multiple terminal-ledger receipts`);
     }
     const ledgerReceipt = ledgerReceiptMatches[0];
-    const loadedLedgerControl = isRecord(loadedLedger?.terminal_control)
-        ? loadedLedger.terminal_control
-        : undefined;
     const loadedLedgerMessageId = stringValue(loadedLedger?.message_id);
     const loadedLedgerStoreDir = stringValue(loadedLedger?.store_dir);
     const loadedLedgerStatePath = stringValue(loadedLedger?.state_path);
     const loadedLedgerOwner = loadedLedger && loadedLedgerMessageId === messageId
         ? loadTerminalDispatchLedgerOwner(loadedLedger)
         : undefined;
-    const ledgerReceiptControl = isRecord(ledgerReceipt?.terminal_control)
-        ? ledgerReceipt.terminal_control
-        : undefined;
     const expectedMessageBodyHash = createHash("sha256")
         .update(requestText)
         .digest("hex");
     if (ledgerReceipt &&
         !(ledgerReceipt.status === "aborted" && ledgerReceipt.safe_to_retry === true) &&
-        (stringValue(ledgerReceiptControl?.target) !== terminalControl.target ||
-            (stringValue(ledgerReceiptControl?.socket_path) ?? undefined) !==
-                terminalControl.socketPath ||
-            Number(ledgerReceiptControl?.pane_pid) !== Number(terminalControl.panePid) ||
+        (!terminalDispatchRecordMatchesControl(ledgerReceipt, terminalControl) ||
             (stringValue(ledgerReceipt.store_dir) !== undefined &&
                 path.resolve(String(ledgerReceipt.store_dir)) !==
                     path.resolve(expectedStoreDir)) ||
@@ -1954,10 +1994,7 @@ function replayExactActiveTerminalSubmission({ options, terminalControl, request
     }
     if (loadedLedger &&
         loadedLedgerMessageId === messageId &&
-        (stringValue(loadedLedgerControl?.target) !== terminalControl.target ||
-            (stringValue(loadedLedgerControl?.socket_path) ?? undefined) !==
-                terminalControl.socketPath ||
-            Number(loadedLedgerControl?.pane_pid) !== Number(terminalControl.panePid) ||
+        (!terminalDispatchRecordMatchesControl(loadedLedger, terminalControl) ||
             (loadedLedgerStoreDir !== undefined &&
                 path.resolve(loadedLedgerStoreDir) !== path.resolve(expectedStoreDir)) ||
             (expectedSessionId && stringValue(loadedLedger.session_id) !== undefined &&
@@ -2002,15 +2039,9 @@ function replayExactActiveTerminalSubmission({ options, terminalControl, request
     }
     const incarnationLedger = resolveTerminalDispatchLedgerPaneIncarnation(terminalControl, loadedLedger);
     const ledger = reconcilePreparedTerminalDispatchLedger(terminalControl, incarnationLedger);
-    const ledgerControl = isRecord(ledger?.terminal_control)
-        ? ledger.terminal_control
-        : undefined;
     if (!ledger ||
         !["submitted", "enter_dispatched", "agent_accepted"].includes(String(ledger.status)) ||
-        stringValue(ledgerControl?.target) !== terminalControl.target ||
-        (stringValue(ledgerControl?.socket_path) ?? undefined) !==
-            terminalControl.socketPath ||
-        Number(ledgerControl?.pane_pid) !== Number(terminalControl.panePid) ||
+        !terminalDispatchRecordMatchesControl(ledger, terminalControl) ||
         stringValue(ledger.message_id) !== messageId ||
         (stringValue(ledger.message_type) !== undefined &&
             stringValue(ledger.message_type) !== expectedMessageType) ||
@@ -2160,21 +2191,26 @@ function validateStoredTerminalSubmissionMatch({ owner, receipt, options, termin
         turnIdForConversation(owner);
     const receiptOpenClawSession = stringValue(receipt.openclaw_session) ??
         owner.openclaw_session;
-    const receiptTarget = stringValue(receipt.terminal_target) ??
-        storedControl?.target;
-    const receiptSocketPath = receipt.terminal_socket_path === null
-        ? undefined
-        : stringValue(receipt.terminal_socket_path) ?? storedControl?.socketPath;
-    const receiptPanePid = Number(receipt.terminal_pane_pid ?? storedControl?.panePid);
+    const receiptTerminalEvidence = receipt.terminal_endpoint !== undefined
+        ? receipt.terminal_endpoint
+        : {
+            kind: "tmux",
+            target: stringValue(receipt.terminal_target) ?? storedControl?.target,
+            socket_path: receipt.terminal_socket_path === null
+                ? null
+                : stringValue(receipt.terminal_socket_path) ??
+                    storedControl?.socketPath ??
+                    null,
+            pane_pid: Number(receipt.terminal_pane_pid ?? storedControl?.panePid)
+        };
     const requestedOpenClawSession = stringValue(options.openclawSession);
     if (!ownerStoreDir ||
         !receiptStoreDir ||
         path.resolve(ownerStoreDir) !== path.resolve(expectedStoreDir) ||
         path.resolve(receiptStoreDir) !== path.resolve(expectedStoreDir) ||
         !storedControl ||
-        receiptTarget !== terminalControl.target ||
-        receiptSocketPath !== terminalControl.socketPath ||
-        receiptPanePid !== Number(terminalControl.panePid) ||
+        !terminalControlsShareIncarnation(storedControl, terminalControl) ||
+        !terminalControlEvidenceMatches(receiptTerminalEvidence, terminalControl) ||
         receiptSessionId !== sessionIdForConversation(owner) ||
         receiptTurnId !== turnIdForConversation(owner) ||
         (expectedSessionId && receiptSessionId !== expectedSessionId) ||
@@ -2422,11 +2458,7 @@ function unresolvedTerminalBridgeSubmission(conversation) {
         : undefined;
 }
 function assertNoUnresolvedTerminalBridgeSubmission(storeDir, terminalControl, currentConversationId, requestText) {
-    const targetKey = terminalControlSelectorKey(terminalControl);
     const requestHash = terminalBridgeRequestFingerprint(requestText);
-    if (!targetKey) {
-        return;
-    }
     for (const candidate of listConversations(storeDir)) {
         const submission = terminalBridgeSubmission(candidate);
         if (candidate.conversation_id === currentConversationId ||
@@ -2450,7 +2482,7 @@ function assertNoUnresolvedTerminalBridgeSubmission(storeDir, terminalControl, c
         const nativeTakeover = isRecord(candidate.native_session_takeover)
             ? candidate.native_session_takeover
             : undefined;
-        if (terminalControlSelectorKey(terminalControlFromTakeover(nativeTakeover)) === targetKey) {
+        if (terminalControlsShareIncarnation(terminalControlFromTakeover(nativeTakeover), terminalControl)) {
             throw new Error(`terminal ${terminalControl.target} has a conflicting ${String(submission.status)} ` +
                 `AKK submission in ${candidate.conversation_id}; inspect that conversation and pane, ` +
                 "then close it before retrying");
@@ -2458,10 +2490,6 @@ function assertNoUnresolvedTerminalBridgeSubmission(storeDir, terminalControl, c
     }
 }
 function stallOtherTerminalBridgeConversationsForUncertainDispatch({ storeDir, terminalControl, currentConversationId, uncertainMessageId }) {
-    const targetKey = terminalControlSelectorKey(terminalControl);
-    if (!targetKey) {
-        return [];
-    }
     const stalledConversationIds = [];
     for (const listed of listConversations(storeDir)) {
         if (listed.conversation_id === currentConversationId ||
@@ -2472,7 +2500,7 @@ function stallOtherTerminalBridgeConversationsForUncertainDispatch({ storeDir, t
             ? listed.native_session_takeover
             : undefined;
         if (listedTakeover?.terminal_bridge !== true ||
-            terminalControlSelectorKey(terminalControlFromTakeover(listedTakeover)) !== targetKey) {
+            !terminalControlsShareIncarnation(terminalControlFromTakeover(listedTakeover), terminalControl)) {
             continue;
         }
         const listedStatePath = stringValue(listed.state_path);
@@ -2487,7 +2515,7 @@ function stallOtherTerminalBridgeConversationsForUncertainDispatch({ storeDir, t
                 : undefined;
             if (!isActiveStatus(current.status) ||
                 currentTakeover?.terminal_bridge !== true ||
-                terminalControlSelectorKey(terminalControlFromTakeover(currentTakeover)) !== targetKey) {
+                !terminalControlsShareIncarnation(terminalControlFromTakeover(currentTakeover), terminalControl)) {
                 continue;
             }
             const stalledAt = new Date().toISOString();
@@ -2686,13 +2714,7 @@ async function buildTerminalListGroup({ options, agentFilter, statusFilter }) {
     };
 }
 async function terminalControlDiagnostics(provider) {
-    if (provider instanceof TmuxTerminalControlProvider) {
-        return provider.diagnose();
-    }
-    return {
-        provider: "static",
-        paneCount: (await provider.listPanes()).length
-    };
+    return provider.diagnostics();
 }
 function managedTurnListEntry(task, { terminalBridge = false, approvalState, conversation } = {}) {
     const sessionId = stringValue(task.session_id) ??
@@ -2844,9 +2866,28 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
     const codexLifecycleIncarnationAvailable = session.agent !== "codex" ||
         Boolean(nativeProcessUuid && nativeProcessBirth);
     const nativeInspectionHasBlockingTurn = listConversations(storeDirFromOptions(options)).some((turn) => isDiscoverableTmuxConversation(turn) &&
-        terminalKeyForManagedConversation(turn) ===
-            terminalControlSelectorKey(terminalControl) &&
+        terminalControlsShareIncarnation(terminalControlForManagedConversation(turn), terminalControl) &&
         SESSION_SEND_BLOCKING_STATUSES.has(turn.status));
+    let nativeInspectionComposerReady = nativeInspectionComposerEmpty(session.agent, terminalState.screen_excerpt);
+    if (session.agent === "codex" &&
+        terminalState.activity_state === "idle" &&
+        terminalState.approval_state.blocked !== true &&
+        nativeInspectionCapability.status === "supported" &&
+        nativeInspectionCapability.statusInspection === true &&
+        terminalControl.capabilities.includes("send_keys") &&
+        terminalControl.capabilities.includes("screen_status")) {
+        try {
+            const provider = createTerminalControlProvider(options);
+            const resolvedTerminal = await provider.resolve(provider.endpoint(terminalControl));
+            const styledScreen = await provider.capture(resolvedTerminal, { scrollbackLines: 40, preserveEscapes: true });
+            nativeInspectionComposerReady = codexStyledComposerEmpty(styledScreen);
+        }
+        catch {
+            // Advertising an input action is optional. The action itself repeats the
+            // same styled composer proof under the terminal lock before any input.
+            nativeInspectionComposerReady = false;
+        }
+    }
     const entry = {
         id: bridge.terminalConversationId(session),
         short_ref: sessionShortRef(bridge.terminalConversationId(session)),
@@ -2905,7 +2946,7 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
                 codexLifecycleIncarnationAvailable,
             native_inspect: nativeInspectionCapability.status === "supported" &&
                 nativeInspectionCapability.statusInspection === true &&
-                nativeInspectionComposerEmpty(session.agent, terminalState.screen_excerpt) &&
+                nativeInspectionComposerReady &&
                 terminalControl.capabilities.includes("send_keys") &&
                 terminalControl.capabilities.includes("screen_status") &&
                 (session.agent === "codex"
@@ -2924,26 +2965,24 @@ async function terminalControlledListEntry(session, activeSessions, options, bri
     };
 }
 function terminalFirstListProjection({ storeDir, terminals, managedSessions, sessionAuthorityRequired, allConversations, displayedConversations, includeAll, managedOnly, statusFilter, mutationsAllowed }) {
-    const allByTerminal = managedConversationsByTerminal(allConversations);
-    const displayedByTerminal = managedConversationsByTerminal(displayedConversations);
-    const sessionsByTerminal = managedSessionsByTerminal(managedSessions);
-    const discoveredTerminalKeys = new Set();
+    const discoveredTerminalControls = terminals.flatMap((terminal) => {
+        const control = isRecord(terminal.terminal_control)
+            ? terminal.terminal_control
+            : undefined;
+        return control ? [control] : [];
+    });
     const projectedTerminals = terminals.map((terminal) => {
         const terminalControl = isRecord(terminal.terminal_control)
             ? terminal.terminal_control
             : undefined;
-        const terminalKey = terminalControlSelectorKey(terminalControl);
-        if (terminalKey) {
-            discoveredTerminalKeys.add(terminalKey);
-        }
-        const allRelated = terminalKey
-            ? [...(allByTerminal.get(terminalKey) ?? [])]
+        const allRelated = terminalControl
+            ? allConversations.filter((conversation) => terminalControlsShareIncarnation(terminalControlForManagedConversation(conversation), terminalControl))
             : [];
-        const displayedRelated = terminalKey
-            ? [...(displayedByTerminal.get(terminalKey) ?? [])]
+        const displayedRelated = terminalControl
+            ? displayedConversations.filter((conversation) => terminalControlsShareIncarnation(terminalControlForManagedConversation(conversation), terminalControl))
             : [];
-        const relatedSessions = terminalKey
-            ? [...(sessionsByTerminal.get(terminalKey) ?? [])]
+        const relatedSessions = terminalControl
+            ? managedSessions.filter((session) => terminalControlsShareIncarnation(session.binding?.terminal_control, terminalControl))
             : [];
         const matchingSessions = relatedSessions.filter((session) => managedSessionMatchesLiveTerminalEntry(session, terminal, storeDir));
         const conflictingBoundSessionClaims = relatedSessions.flatMap((session) => {
@@ -3210,8 +3249,8 @@ function terminalFirstListProjection({ storeDir, terminals, managedSessions, ses
     });
     const unavailableManagedTurns = displayedConversations
         .filter((conversation) => {
-        const terminalKey = terminalKeyForManagedConversation(conversation);
-        if (terminalKey && discoveredTerminalKeys.has(terminalKey)) {
+        const managedControl = terminalControlForManagedConversation(conversation);
+        if (discoveredTerminalControls.some((control) => terminalControlsShareIncarnation(managedControl, control))) {
             return false;
         }
         return (includeAll ||
@@ -3248,35 +3287,6 @@ function terminalFirstListProjection({ storeDir, terminals, managedSessions, ses
         unavailableManagedTurns
     };
 }
-function managedConversationsByTerminal(conversations) {
-    const groups = new Map();
-    for (const conversation of conversations) {
-        const key = terminalKeyForManagedConversation(conversation);
-        if (!key) {
-            continue;
-        }
-        const group = groups.get(key) ?? [];
-        group.push(conversation);
-        groups.set(key, group);
-    }
-    return groups;
-}
-function managedSessionsByTerminal(sessions) {
-    const groups = new Map();
-    for (const session of sessions) {
-        if (!session.binding) {
-            continue;
-        }
-        const key = terminalControlSelectorKey(session.binding.terminal_control);
-        if (!key) {
-            continue;
-        }
-        const group = groups.get(key) ?? [];
-        group.push(session);
-        groups.set(key, group);
-    }
-    return groups;
-}
 function managedSessionMatchesLiveTerminalEntry(session, terminal, storeDir) {
     const binding = session.binding;
     const liveControl = isRecord(terminal.terminal_control)
@@ -3285,10 +3295,8 @@ function managedSessionMatchesLiveTerminalEntry(session, terminal, storeDir) {
     if (session.status !== "bound" ||
         !binding ||
         session.agent !== terminal.agent ||
-        binding.terminal_id !== stringValue(terminal.id) ||
         binding.native_process.pid !== Number(terminal.pid) ||
-        terminalControlSelectorKey(binding.terminal_control) !==
-            terminalControlSelectorKey(liveControl) ||
+        !terminalControlAliasMatches(binding.terminal_id, binding.terminal_control, terminal.id, liveControl) ||
         !matchesConfiguredWorkspace(session.workspace, terminal.workspace ?? terminal.cwd)) {
         return false;
     }
@@ -3359,8 +3367,7 @@ function managedSessionClaimsLiveTerminalEntry(session, terminal) {
     return Boolean(binding &&
         session.agent === terminal.agent &&
         binding.native_process.pid === Number(terminal.pid) &&
-        terminalControlSelectorKey(binding.terminal_control) ===
-            terminalControlSelectorKey(liveControl));
+        terminalControlsShareIncarnation(binding.terminal_control, liveControl));
 }
 function listedTerminalProcessIncarnation(terminal) {
     const processUuid = stringValue(terminal.native_agent_process_uuid);
@@ -3403,7 +3410,9 @@ function managedBindingConflictKindForLiveTerminalEntry({ storeDir, session, ter
     if (relationship === "different") {
         return "stale_process_incarnation";
     }
-    if (binding.terminal_id !== stringValue(terminal.id) ||
+    if (!terminalControlAliasMatches(binding.terminal_id, binding.terminal_control, terminal.id, isRecord(terminal.terminal_control)
+        ? terminal.terminal_control
+        : undefined) ||
         !matchesConfiguredWorkspace(session.workspace, terminal.workspace ?? terminal.cwd)) {
         return "unverifiable";
     }
@@ -3469,10 +3478,10 @@ function managedSessionHasUnresolvedNativeTransition(storeDir, session) {
     }
     return false;
 }
-function terminalKeyForManagedConversation(conversation) {
-    return terminalControlSelectorKey(terminalControlFromTakeover(isRecord(conversation.native_session_takeover)
+function terminalControlForManagedConversation(conversation) {
+    return terminalControlFromTakeover(isRecord(conversation.native_session_takeover)
         ? conversation.native_session_takeover
-        : undefined));
+        : undefined);
 }
 function compareManagedConversationRecency(left, right) {
     const leftTime = Date.parse(String(left.updated_at ?? left.created_at ?? ""));
@@ -3520,16 +3529,10 @@ function terminalDispatchOwnership(terminalControl) {
     if (!ledger || ledger.status === "resolved") {
         return { state: "none" };
     }
-    const ledgerControl = isRecord(ledger.terminal_control)
-        ? ledger.terminal_control
-        : undefined;
-    const ledgerPanePid = Number(ledgerControl?.pane_pid);
-    const currentPanePid = Number(terminalControl.panePid);
-    if (Number.isSafeInteger(ledgerPanePid) &&
-        ledgerPanePid > 0 &&
-        Number.isSafeInteger(currentPanePid) &&
-        currentPanePid > 0 &&
-        ledgerPanePid !== currentPanePid) {
+    if (terminalDispatchRecordMatchesControl(ledger, terminalControl, {
+        requireProcessAnchor: false
+    }) &&
+        !terminalDispatchRecordMatchesControl(ledger, terminalControl)) {
         return { state: "none" };
     }
     if (![
@@ -3554,9 +3557,8 @@ function terminalDispatchOwnership(terminalControl) {
     if (TERMINAL_DISPATCH_RELEASE_STATUSES.has(owner.status)) {
         return { state: "none" };
     }
-    const ownerTerminalKey = terminalKeyForManagedConversation(owner);
-    const currentTerminalKey = terminalControlSelectorKey(terminalControl);
-    if (!ownerTerminalKey || ownerTerminalKey !== currentTerminalKey) {
+    const ownerTerminalControl = terminalControlForManagedConversation(owner);
+    if (!terminalControlsShareIncarnation(ownerTerminalControl, terminalControl)) {
         return {
             state: "conflict",
             conflict: terminalDispatchConflict(ledger, "dispatch owner does not reference this tmux pane incarnation")
@@ -3729,9 +3731,8 @@ function managedTurnMatchesLiveTerminal(conversation, terminal) {
         !Number.isSafeInteger(livePid) ||
         livePid <= 1 ||
         storedPid !== livePid ||
-        stringValue(takeover?.native_session_id) !== stringValue(terminal.id) ||
-        terminalControlSelectorKey(storedControl) !==
-            terminalControlSelectorKey(liveControl)) {
+        !terminalControlAliasMatches(stringValue(takeover?.native_session_id), storedControl, stringValue(terminal.id), liveControl) ||
+        !terminalControlsShareIncarnation(storedControl, liveControl)) {
         return false;
     }
     const liveSessionId = stringValue(terminal.native_agent_session_id);
@@ -3876,18 +3877,25 @@ async function listStateForTerminal(agent, terminalControl, options, bridge = cr
 function rootActiveProcesses(processes) {
     const pids = new Set(processes.map((process) => `${process.agent}:${process.pid}`));
     const roots = processes.filter((process) => !process.ppid || !pids.has(`${process.agent}:${process.ppid}`));
-    const seenTerminalTargets = new Set();
+    const seenTerminalIncarnations = new Set();
     return roots.filter((process) => {
-        const terminalTarget = process.terminalControl?.target
-            ? `${process.agent}:${process.terminalControl.target}:${process.terminalControl.panePid}`
+        const endpoint = process.terminalControl
+            ? terminalEndpointFromControlRef(process.terminalControl)
+            : undefined;
+        const terminalIncarnation = endpoint
+            ? JSON.stringify({
+                agent: process.agent,
+                identity: terminalEndpointIdentityKey(endpoint),
+                process_anchor_pid: endpoint.processAnchorPid ?? null
+            })
             : undefined;
-        if (!terminalTarget) {
+        if (!terminalIncarnation) {
             return true;
         }
-        if (seenTerminalTargets.has(terminalTarget)) {
+        if (seenTerminalIncarnations.has(terminalIncarnation)) {
             return false;
         }
-        seenTerminalTargets.add(terminalTarget);
+        seenTerminalIncarnations.add(terminalIncarnation);
         return true;
     });
 }
@@ -4508,17 +4516,43 @@ function terminalControlSelectorKey(value) {
     if (!isRecord(value)) {
         return undefined;
     }
-    const target = stringValue(value.target);
-    const panePid = Number(value.panePid);
-    if (!target || !Number.isSafeInteger(panePid) || panePid <= 1) {
+    let endpoint;
+    try {
+        endpoint = terminalEndpointFromControlRef(value);
+    }
+    catch {
+        return undefined;
+    }
+    const processAnchorPid = Number(endpoint.processAnchorPid);
+    if (!Number.isSafeInteger(processAnchorPid) || processAnchorPid <= 1) {
         return undefined;
     }
     return JSON.stringify({
-        target,
-        pane_pid: panePid,
-        socket_path: stringValue(value.socketPath) ?? null
+        identity: terminalEndpointIdentityKey(endpoint),
+        process_anchor_pid: processAnchorPid
     });
 }
+function terminalControlsShareIncarnation(left, right) {
+    if (!terminalControlSelectorKey(left) || !terminalControlSelectorKey(right)) {
+        return false;
+    }
+    return sameTerminalControlIncarnation(left, right);
+}
+/**
+ * `terminal:v2` is a route-shaped compatibility alias, not terminal
+ * ownership. Once both sides carry canonical endpoint evidence, a route
+ * rename must not detach or duplicate the stable resource. Legacy records
+ * continue to require the exact historical alias and route tuple.
+ */
+function terminalControlAliasMatches(storedTerminalId, storedControl, currentTerminalId, currentControl) {
+    if (!terminalControlsShareIncarnation(storedControl, currentControl)) {
+        return false;
+    }
+    const stored = storedControl;
+    const current = currentControl;
+    return (hasCanonicalTerminalEndpoint(stored) &&
+        hasCanonicalTerminalEndpoint(current)) || stringValue(storedTerminalId) === stringValue(currentTerminalId);
+}
 function sessionEntryRecency(entry, observedAtMs) {
     const timestamp = Date.parse(String(entry.updated_at ?? entry.created_at ?? ""));
     if (Number.isFinite(timestamp)) {
@@ -4812,14 +4846,12 @@ function codexAllowedCompanionSetForManagedSession({ storeDir, session }) {
             candidate.agent !== "codex" ||
             candidate.status !== "detached" ||
             !candidateBinding?.native_thread_id ||
-            candidateBinding.terminal_id !== binding.terminal_id ||
             candidateBinding.native_process.pid !== binding.native_process.pid ||
             candidateBinding.native_process.process_uuid !==
                 binding.native_process.process_uuid ||
             candidateBinding.native_process.process_birth !==
                 binding.native_process.process_birth ||
-            terminalControlSelectorKey(candidateBinding.terminal_control) !==
-                terminalControlSelectorKey(binding.terminal_control) ||
+            !terminalControlAliasMatches(candidateBinding.terminal_id, candidateBinding.terminal_control, binding.terminal_id, binding.terminal_control) ||
             path.resolve(candidate.workspace) !== path.resolve(session.workspace) ||
             !candidateBinding.native_process.process_uuid ||
             !candidateBinding.native_process.process_birth ||
@@ -4907,8 +4939,8 @@ function codexKnownRootSetForLifecycleTransition({ storeDir, terminal, transitio
     if (after?.native_thread_id &&
         after.native_process.process_uuid &&
         after.native_process.process_birth &&
-        after.terminal_id === terminal.conversationId &&
         after.native_process.pid === terminal.pid &&
+        terminalControlAliasMatches(after.terminal_id, after.terminal_control, terminal.conversationId, terminal.terminalControl) &&
         after.native_process.process_uuid === transition.before_process_uuid &&
         after.native_process.process_birth === transition.before_process_birth &&
         isCompleteNativeRollout(after.native_process.rollout)) {
@@ -4926,12 +4958,10 @@ function codexKnownRootSetForLifecycleTransition({ storeDir, terminal, transitio
             !binding?.native_thread_id ||
             !binding.native_process.process_uuid ||
             !binding.native_process.process_birth ||
-            binding.terminal_id !== terminal.conversationId ||
             binding.native_process.pid !== terminal.pid ||
             binding.native_process.process_uuid !== transition.before_process_uuid ||
             binding.native_process.process_birth !== transition.before_process_birth ||
-            terminalControlSelectorKey(binding.terminal_control) !==
-                terminalControlSelectorKey(terminal.terminalControl) ||
+            !terminalControlAliasMatches(binding.terminal_id, binding.terminal_control, terminal.conversationId, terminal.terminalControl) ||
             !matchesConfiguredWorkspace(transition.workspace, session.workspace) ||
             !isCompleteNativeRollout(binding.native_process.rollout)) {
             continue;
@@ -4994,11 +5024,9 @@ function nativeIdentityMatchesCodexPreMaterialization(identity, expected) {
         identity.rollout?.path === expected.rollout.path);
 }
 async function assertCodexComposerReadyForAutomatedInput({ options, terminalControl }) {
-    const styledScreen = await createTerminalControlProvider(options).capture(terminalControl.target, {
-        scrollbackLines: 40,
-        socketPath: terminalControl.socketPath,
-        preserveEscapes: true
-    });
+    const provider = createTerminalControlProvider(options);
+    const resolvedTerminal = await provider.resolve(provider.endpoint(terminalControl));
+    const styledScreen = await provider.capture(resolvedTerminal, { scrollbackLines: 40, preserveEscapes: true });
     if (!codexStyledComposerEmpty(styledScreen)) {
         throw new Error("Codex composer contains non-placeholder input; refusing automated terminal input");
     }
@@ -5086,10 +5114,8 @@ function bindingMatchesLiveTerminal(session, terminal, identity, storeDir) {
         return false;
     }
     if (session.agent !== terminal.agent ||
-        binding.terminal_id !== terminal.conversationId ||
         binding.native_process.pid !== terminal.pid ||
-        terminalControlSelectorKey(binding.terminal_control) !==
-            terminalControlSelectorKey(terminal.terminalControl) ||
+        !terminalControlAliasMatches(binding.terminal_id, binding.terminal_control, terminal.conversationId, terminal.terminalControl) ||
         !matchesConfiguredWorkspace(session.workspace, terminal.terminalControl.currentPath)) {
         return false;
     }
@@ -5131,9 +5157,7 @@ function boundManagedSessionForTerminal({ storeDir, terminal, identity }) {
     const unresolved = sessions.filter((session) => ["transitioning", "quarantined"].includes(session.status) &&
         session.binding &&
         session.agent === terminal.agent &&
-        session.binding.terminal_id === terminal.conversationId &&
-        terminalControlSelectorKey(session.binding.terminal_control) ===
-            terminalControlSelectorKey(terminal.terminalControl));
+        terminalControlAliasMatches(session.binding.terminal_id, session.binding.terminal_control, terminal.conversationId, terminal.terminalControl));
     if (unresolved.length > 0) {
         throw new Error(`terminal ${terminal.terminalControl.target} is still claimed by ` +
             `${unresolved[0].status} managed Session ${unresolved[0].session_id}` +
@@ -5149,8 +5173,7 @@ function boundManagedSessionForTerminal({ storeDir, terminal, identity }) {
     const conflicting = sessions.filter((session) => session.status === "bound" &&
         session.binding &&
         session.agent === terminal.agent &&
-        terminalControlSelectorKey(session.binding.terminal_control) ===
-            terminalControlSelectorKey(terminal.terminalControl) &&
+        terminalControlsShareIncarnation(session.binding.terminal_control, terminal.terminalControl) &&
         session.binding.native_process.pid === terminal.pid &&
         !managedSessionOwnerIsConclusivelyInactive({
             session,
@@ -5169,10 +5192,8 @@ function managedBindingConflictKindForResolvedTerminal({ storeDir, session, term
     if (session.status !== "bound" ||
         !binding ||
         session.agent !== terminal.agent ||
-        binding.terminal_id !== terminal.conversationId ||
         binding.native_process.pid !== terminal.pid ||
-        terminalControlSelectorKey(binding.terminal_control) !==
-            terminalControlSelectorKey(terminal.terminalControl) ||
+        !terminalControlAliasMatches(binding.terminal_id, binding.terminal_control, terminal.conversationId, terminal.terminalControl) ||
         !matchesConfiguredWorkspace(session.workspace, terminal.terminalControl.currentPath) ||
         bindingMatchesLiveTerminal(session, terminal, identity, storeDir)) {
         return undefined;
@@ -5211,10 +5232,8 @@ function soleBoundManagedSessionClaimForTerminal(storeDir, terminal) {
     const claims = listManagedSessions(storeDir).filter((session) => session.status === "bound" &&
         session.binding &&
         session.agent === terminal.agent &&
-        session.binding.terminal_id === terminal.conversationId &&
         session.binding.native_process.pid === terminal.pid &&
-        terminalControlSelectorKey(session.binding.terminal_control) ===
-            terminalControlSelectorKey(terminal.terminalControl) &&
+        terminalControlAliasMatches(session.binding.terminal_id, session.binding.terminal_control, terminal.conversationId, terminal.terminalControl) &&
         matchesConfiguredWorkspace(session.workspace, terminal.terminalControl.currentPath) &&
         !managedSessionOwnerIsConclusivelyInactive({
             session,
@@ -5368,6 +5387,32 @@ function lifecycleBindingToken({ session, terminal, identity }) {
         rollout: identity?.rollout
     });
 }
+function managedSessionBindingTokens(session) {
+    return [...new Set([
+            managedSessionBindingToken(session),
+            legacyManagedSessionBindingToken(session)
+        ])];
+}
+function lifecycleBindingTokens({ session, terminal, identity }) {
+    const current = lifecycleBindingToken({ session, terminal, identity });
+    const codexIncarnation = terminal.agent === "codex" && !identity
+        ? codexProcessIncarnationForPid(terminal.pid)
+        : undefined;
+    const legacy = session
+        ? legacyManagedSessionBindingToken(session)
+        : legacyUnmanagedTerminalBindingToken({
+            terminalId: terminal.conversationId,
+            terminalControl: terminal.terminalControl,
+            agent: terminal.agent,
+            pid: terminal.pid,
+            workspace: terminal.terminalControl.currentPath ?? process.cwd(),
+            nativeThreadId: identity?.sessionId,
+            processUuid: identity?.processUuid ?? codexIncarnation?.processUuid,
+            processBirth: identity?.processBirth ?? codexIncarnation?.processBirth,
+            rollout: identity?.rollout
+        });
+    return [...new Set([current, legacy])];
+}
 function agentVersionForRunningProcess(agent, pid, options) {
     const fixture = options.agentVersionsJson
         ? parseJsonOption(options.agentVersionsJson, "--agent-versions-json")
@@ -5408,8 +5453,7 @@ function assertTerminalLifecycleReady({ options, terminal, terminalStatus }) {
     }
     const blockers = listConversations(storeDirFromOptions(options))
         .filter(isDiscoverableTmuxConversation)
-        .filter((turn) => terminalKeyForManagedConversation(turn) ===
-        terminalControlSelectorKey(terminal.terminalControl) &&
+        .filter((turn) => terminalControlsShareIncarnation(terminalControlForManagedConversation(turn), terminal.terminalControl) &&
         SESSION_SEND_BLOCKING_STATUSES.has(turn.status));
     if (blockers.length > 0) {
         throw new Error(`terminal ${terminal.terminalControl.target} still has unresolved Turn ` +
@@ -5611,10 +5655,8 @@ async function assertLifecycleTargetHasExclusiveOwnership({ options, terminal, t
     if (!afterBinding ||
         !nativeThreadId ||
         !isExactNativeThreadId(nativeThreadId) ||
-        afterBinding.terminal_id !== terminal.conversationId ||
         afterBinding.native_process.pid !== terminal.pid ||
-        terminalControlSelectorKey(afterBinding.terminal_control) !==
-            terminalControlSelectorKey(terminal.terminalControl)) {
+        !terminalControlAliasMatches(afterBinding.terminal_id, afterBinding.terminal_control, terminal.conversationId, terminal.terminalControl)) {
         throw new Error("cannot exclude the current lifecycle process without an exact after_binding");
     }
     await assertNativeThreadHasExclusiveOwnership({
@@ -5907,7 +5949,7 @@ async function currentLifecycleSnapshot(options, terminal, { materialize = false
         allowedCompanionIdentity: claimedCodexCompanions.primary,
         allowedAdditionalIdentities: claimedCodexCompanions.additional
     });
-    const session = materialize
+    let session = materialize
         ? materializeCurrentManagedSession({
             options,
             terminal,
@@ -5918,13 +5960,26 @@ async function currentLifecycleSnapshot(options, terminal, { materialize = false
             terminal,
             identity: observedIdentity
         });
-    const identity = session
+    let identity = session
         ? logicalIdentityForManagedSession({
             storeDir,
             session,
             observedIdentity
         })
         : observedIdentity;
+    if (materialize && session) {
+        session = refineManagedSessionNativeIdentity({
+            storeDir,
+            session,
+            terminalControl: terminal.terminalControl,
+            identity
+        });
+        identity = logicalIdentityForManagedSession({
+            storeDir,
+            session,
+            observedIdentity
+        });
+    }
     const codexCompanions = terminal.agent === "codex" && session
         ? codexAllowedCompanionSetForManagedSession({ storeDir, session })
         : claimedCodexCompanions;
@@ -5949,6 +6004,7 @@ async function currentLifecycleSnapshot(options, terminal, { materialize = false
         resumeExact: false,
         reason: `${adapter.displayName} has no native-thread lifecycle adapter`
     };
+    const bindingTokens = lifecycleBindingTokens({ session, terminal, identity });
     return {
         identity,
         runtimeIdentity: observedIdentity,
@@ -5957,7 +6013,8 @@ async function currentLifecycleSnapshot(options, terminal, { materialize = false
         version,
         adapter,
         capabilities,
-        bindingToken: lifecycleBindingToken({ session, terminal, identity })
+        bindingToken: bindingTokens[0],
+        bindingTokens
     };
 }
 async function runListResumableThreads(options) {
@@ -6062,11 +6119,9 @@ async function runListResumableThreads(options) {
 function assertSameNativeInspectionTerminal(expected, actual, stage) {
     const expectedPath = expected.terminalControl.currentPath;
     const actualPath = actual.terminalControl.currentPath;
-    if (actual.conversationId !== expected.conversationId ||
-        actual.agent !== expected.agent ||
+    if (actual.agent !== expected.agent ||
         actual.pid !== expected.pid ||
-        terminalControlSelectorKey(actual.terminalControl) !==
-            terminalControlSelectorKey(expected.terminalControl) ||
+        !terminalControlAliasMatches(expected.conversationId, expected.terminalControl, actual.conversationId, actual.terminalControl) ||
         !expectedPath ||
         !actualPath ||
         path.resolve(actualPath) !== path.resolve(expectedPath)) {
@@ -6083,8 +6138,7 @@ function assertTerminalNativeInspectionReady({ options, terminal, terminalStatus
     }
     const blocker = listConversations(storeDirFromOptions(options))
         .filter(isDiscoverableTmuxConversation)
-        .find((turn) => terminalKeyForManagedConversation(turn) ===
-        terminalControlSelectorKey(terminal.terminalControl) &&
+        .find((turn) => terminalControlsShareIncarnation(terminalControlForManagedConversation(turn), terminal.terminalControl) &&
         SESSION_SEND_BLOCKING_STATUSES.has(turn.status));
     if (blocker) {
         throw new Error(`terminal ${terminal.terminalControl.target} still has unresolved Turn ` +
@@ -6148,7 +6202,7 @@ function nativeInspectionRuntime({ terminal, snapshot }) {
 }
 function assertNativeInspectionSnapshotUnchanged({ options, expectedTerminal, actualTerminal, expectedBindingToken, expectedVersion, actualSnapshot, stage, expectedClaudeState = "idle" }) {
     assertSameNativeInspectionTerminal(expectedTerminal, actualTerminal, stage);
-    if (actualSnapshot.bindingToken !== expectedBindingToken) {
+    if (!actualSnapshot.bindingTokens.includes(expectedBindingToken)) {
         throw new Error(`terminal binding changed ${stage}; refresh AKK list`);
     }
     if (actualSnapshot.version !== expectedVersion) {
@@ -6203,7 +6257,7 @@ function assertNativeInspectionAgentIdentity({ options, terminal, snapshot, stag
 }
 async function assertNativeInspectionExclusiveOwnership({ options, terminal, snapshot }) {
     // Claude's exact `claude agents` mapping makes global active ownership part
-    // of the 2.1.218 inspection profile. Keep the existing Codex #112 path
+    // of the supported exact Claude inspection profiles. Keep the existing Codex #112 path
     // unchanged: an unmanaged Codex pane may be inspected before a rollout
     // identity exists, and its status card is the bounded identity evidence.
     if (terminal.agent !== "claude") {
@@ -6239,12 +6293,13 @@ async function runNativeInspect(options) {
         throw new Error("native inspection requires a compatible AKK Store so binding authority can be verified");
     }
     const initiallyResolved = await resolveLifecycleTerminal(options);
-    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDir, initiallyResolved.terminalControl), { timeoutMs: 30000 });
+    const bridge = createTerminalAgentBridge(options);
+    const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDir, initiallyResolved.terminalControl, { timeoutMs: 30000 });
     try {
-        const terminal = await resolveLifecycleTerminal(options);
+        const terminal = await bridge.resolveStoredTerminal(initiallyResolved.agent, initiallyResolved.pid, initiallyResolved.terminalControl, { pid: initiallyResolved.pid });
         assertSameNativeInspectionTerminal(initiallyResolved, terminal, "while waiting for native-inspection control");
         const snapshot = await currentLifecycleSnapshot(options, terminal);
-        if (snapshot.bindingToken !== expectedBindingToken) {
+        if (!snapshot.bindingTokens.includes(expectedBindingToken)) {
             throw new Error("terminal binding changed after it was listed; refresh AKK list and retry");
         }
         const capability = snapshot.adapter.probeNativeInspection?.(snapshot.version);
@@ -6272,7 +6327,6 @@ async function runNativeInspect(options) {
             snapshot
         });
         const runtime = nativeInspectionRuntime({ terminal, snapshot });
-        const bridge = createTerminalAgentBridge(options);
         const initialStatus = await bridge.status(terminal.agent, terminal.terminalControl, { runtime });
         assertTerminalNativeInspectionReady({
             options,
@@ -6289,7 +6343,7 @@ async function runNativeInspect(options) {
             submission = await bridge.submitNativeInspection(terminal.agent, terminal.terminalControl, plan, {
                 runtime,
                 beforeEnter: async () => {
-                    const finalTerminal = await resolveLifecycleTerminal(options);
+                    const finalTerminal = await bridge.resolveStoredTerminal(terminal.agent, terminal.pid, terminal.terminalControl, runtime);
                     const finalSnapshot = await currentLifecycleSnapshot(options, finalTerminal);
                     assertNativeInspectionSnapshotUnchanged({
                         options,
@@ -6388,7 +6442,7 @@ async function runNativeInspect(options) {
                         runtime: postEnterRuntime,
                         scrollbackLines: 240,
                         beforeDismiss: async () => {
-                            const dismissTerminal = await resolveLifecycleTerminal(options);
+                            const dismissTerminal = await bridge.resolveStoredTerminal(terminal.agent, terminal.pid, terminal.terminalControl, postEnterRuntime);
                             const dismissSnapshot = await currentLifecycleSnapshot(options, dismissTerminal);
                             assertNativeInspectionSnapshotUnchanged({
                                 options,
@@ -6434,7 +6488,7 @@ async function runNativeInspect(options) {
                     throw new Error("Claude Status panel dismissal was dispatched exactly once, but the original idle composer was not restored; do not retry automatically");
                 }
             }
-            const finalTerminal = await resolveLifecycleTerminal(options);
+            const finalTerminal = await bridge.resolveStoredTerminal(terminal.agent, terminal.pid, terminal.terminalControl, runtime);
             const finalSnapshot = await currentLifecycleSnapshot(options, finalTerminal);
             assertNativeInspectionSnapshotUnchanged({
                 options,
@@ -6873,14 +6927,13 @@ async function runReconcileBinding(options) {
     }
     const expectedBindingToken = required(stringValue(options.expectedBindingToken), "--expected-binding-token is required");
     const expectedTerminalToken = required(stringValue(options.expectedTerminalToken), "--expected-terminal-token is required");
-    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDir, initiallyResolved.terminalControl), { timeoutMs: 30000 });
+    const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDir, initiallyResolved.terminalControl, { timeoutMs: 30000 });
     try {
         return await withStoreWriterLeaseAsync(storeDir, async () => {
             const terminal = await resolveLifecycleTerminal(options);
             if (terminal.pid !== initiallyResolved.pid ||
                 terminal.conversationId !== initiallyResolved.conversationId ||
-                terminalControlSelectorKey(terminal.terminalControl) !==
-                    terminalControlSelectorKey(initiallyResolved.terminalControl)) {
+                !terminalControlsShareIncarnation(terminal.terminalControl, initiallyResolved.terminalControl)) {
                 throw new Error("terminal identity changed while waiting to reconcile its binding; refresh AKK list");
             }
             await recoverLifecycleFenceBeforeMutation({ options, terminal });
@@ -6890,17 +6943,15 @@ async function runReconcileBinding(options) {
             }
             const session = loadManagedSession(storeDir, conflictingSessionId);
             if (session.revision !== expectedSessionRevision ||
-                managedSessionBindingToken(session) !== expectedBindingToken) {
+                !managedSessionBindingTokens(session).includes(expectedBindingToken)) {
                 throw new Error("managed Session binding changed after it was listed; refresh AKK list");
             }
             const binding = session.binding;
             if (session.status !== "bound" ||
                 !binding ||
                 session.agent !== terminal.agent ||
-                binding.terminal_id !== terminal.conversationId ||
                 binding.native_process.pid !== terminal.pid ||
-                terminalControlSelectorKey(binding.terminal_control) !==
-                    terminalControlSelectorKey(terminal.terminalControl) ||
+                !terminalControlAliasMatches(binding.terminal_id, binding.terminal_control, terminal.conversationId, terminal.terminalControl) ||
                 !matchesConfiguredWorkspace(session.workspace, terminal.terminalControl.currentPath)) {
                 throw new Error("the listed managed Session no longer claims this exact terminal");
             }
@@ -6910,11 +6961,11 @@ async function runReconcileBinding(options) {
                 pid: terminal.pid,
                 cwd: terminal.terminalControl.currentPath
             });
-            const terminalToken = lifecycleBindingToken({
+            const terminalTokens = lifecycleBindingTokens({
                 terminal,
                 identity
             });
-            if (terminalToken !== expectedTerminalToken) {
+            if (!terminalTokens.includes(expectedTerminalToken)) {
                 throw new Error("live terminal identity changed after the conflict was listed; refresh AKK list");
             }
             const bridge = createTerminalAgentBridge(options);
@@ -6929,8 +6980,7 @@ async function runReconcileBinding(options) {
             const finalTerminal = await resolveLifecycleTerminal(options);
             if (finalTerminal.pid !== terminal.pid ||
                 finalTerminal.conversationId !== terminal.conversationId ||
-                terminalControlSelectorKey(finalTerminal.terminalControl) !==
-                    terminalControlSelectorKey(terminal.terminalControl)) {
+                !terminalControlsShareIncarnation(finalTerminal.terminalControl, terminal.terminalControl)) {
                 throw new Error("terminal identity changed during binding reconciliation; refresh AKK list");
             }
             const finalStatus = await bridge.status(finalTerminal.agent, finalTerminal.terminalControl, {
@@ -6950,15 +7000,15 @@ async function runReconcileBinding(options) {
                 pid: finalTerminal.pid,
                 cwd: finalTerminal.terminalControl.currentPath
             });
-            if (lifecycleBindingToken({
+            if (!lifecycleBindingTokens({
                 terminal: finalTerminal,
                 identity: finalIdentity
-            }) !== expectedTerminalToken) {
+            }).includes(expectedTerminalToken)) {
                 throw new Error("live terminal identity changed during binding reconciliation; refresh AKK list");
             }
             const finalSession = loadManagedSession(storeDir, conflictingSessionId);
             if (finalSession.revision !== expectedSessionRevision ||
-                managedSessionBindingToken(finalSession) !== expectedBindingToken) {
+                !managedSessionBindingTokens(finalSession).includes(expectedBindingToken)) {
                 throw new Error("managed Session binding changed during reconciliation; refresh AKK list");
             }
             const conflictKind = managedBindingConflictKindForResolvedTerminal({
@@ -7016,12 +7066,14 @@ async function runReconcileBinding(options) {
 }
 function assertResumeSnapshotMatchesTerminal(snapshot, terminal) {
     const workspace = path.resolve(terminal.terminalControl.currentPath ?? process.cwd());
-    if (snapshot.terminal_id !== terminal.conversationId ||
+    const terminalMatches = snapshot.version === 2
+        ? terminalControlEvidenceMatches(snapshot.terminal_endpoint, terminal.terminalControl)
+        : terminalControlEvidenceMatches(snapshot.terminal_control, terminal.terminalControl);
+    if ((snapshot.version === 1 &&
+        snapshot.terminal_id !== terminal.conversationId) ||
         snapshot.agent !== terminal.agent ||
         path.resolve(snapshot.workspace) !== workspace ||
-        snapshot.terminal_control.target !== terminal.terminalControl.target ||
-        snapshot.terminal_control.socket_path !== terminal.terminalControl.socketPath ||
-        snapshot.terminal_control.pane_pid !== terminal.terminalControl.panePid) {
+        !terminalMatches) {
         throw new Error("resume selection terminal, process, or workspace changed; run /akk threads again");
     }
 }
@@ -7048,13 +7100,12 @@ function assertResumeSnapshotNotExpired(snapshot) {
 async function runNativeThreadTransition(options, operation) {
     const initiallyResolved = await resolveLifecycleTerminal(options);
     const storeDir = storeDirFromOptions(options);
-    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDir, initiallyResolved.terminalControl), { timeoutMs: 30000 });
+    const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDir, initiallyResolved.terminalControl, { timeoutMs: 30000 });
     try {
         return await withStoreWriterLeaseAsync(storeDir, async () => {
             const terminal = await resolveLifecycleTerminal(options);
             if (terminal.pid !== initiallyResolved.pid ||
-                terminalControlSelectorKey(terminal.terminalControl) !==
-                    terminalControlSelectorKey(initiallyResolved.terminalControl)) {
+                !terminalControlsShareIncarnation(terminal.terminalControl, initiallyResolved.terminalControl)) {
                 throw new Error("terminal identity changed while waiting for lifecycle control; refresh list");
             }
             if (operation.kind === "resume_thread" && operation.selectionSnapshot) {
@@ -7071,7 +7122,7 @@ async function runNativeThreadTransition(options, operation) {
             }
             const snapshot = await currentLifecycleSnapshot(options, terminal, { materialize: true });
             const expectedToken = required(stringValue(options.expectedBindingToken), "--expected-binding-token is required");
-            if (expectedToken !== snapshot.bindingToken) {
+            if (!snapshot.bindingTokens.includes(expectedToken)) {
                 throw new Error("terminal binding changed after it was listed; refresh AKK list and retry");
             }
             if (snapshot.capabilities.status !== "supported") {
@@ -7417,16 +7468,27 @@ async function runNativeThreadTransition(options, operation) {
                     // Candidate discovery and ownership revalidation can take long
                     // enough for a human to start typing after the /status probe. Keep
                     // this check immediately adjacent to the terminal mutation.
-                    await assertCodexComposerReadyForAutomatedInput({
-                        options,
-                        terminalControl: terminal.terminalControl
-                    });
+                    try {
+                        await assertCodexComposerReadyForAutomatedInput({
+                            options,
+                            terminalControl: terminal.terminalControl
+                        });
+                    }
+                    catch (error) {
+                        throw new TerminalInputNotStartedError(error instanceof Error ? error.message : String(error), { cause: error });
+                    }
                 }
                 if (operation.kind === "resume_thread" && operation.selectionSnapshot) {
                     assertResumeSnapshotNotExpired(operation.selectionSnapshot);
                 }
-                inputStarted = true;
-                await bridge.send(terminal.agent, terminal.terminalControl, transitionStep.command, { runtime: beforeRuntime });
+                await bridge.send(terminal.agent, terminal.terminalControl, transitionStep.command, {
+                    runtime: beforeRuntime,
+                    onTransportStage(event) {
+                        if (event.stage === "text_injected") {
+                            inputStarted = true;
+                        }
+                    }
+                });
                 const submittedAt = new Date().toISOString();
                 transition = {
                     ...transition,
@@ -7615,7 +7677,8 @@ async function runNativeThreadTransition(options, operation) {
                     });
                     return;
                 }
-                if (!inputStarted) {
+                if (!inputStarted &&
+                    error instanceof TerminalInputNotStartedError) {
                     transition = {
                         ...durableTransition,
                         status: "aborted",
@@ -7864,10 +7927,16 @@ function terminalBridgeApprovalFingerprint({ terminalControl, terminalStatus })
     if (adapterFingerprint) {
         return adapterFingerprint;
     }
+    const endpoint = terminalEndpointFromControlRef(terminalControl);
+    const processAnchorPid = Number(endpoint.processAnchorPid);
+    if (!Number.isSafeInteger(processAnchorPid) || processAnchorPid <= 1) {
+        throw new Error("terminal approval fingerprint requires a stable process anchor");
+    }
     const screen = isRecord(terminalStatus?.screen) ? terminalStatus.screen : {};
     return createHash("sha256")
         .update(JSON.stringify({
-        target: terminalControl.target,
+        terminal_identity: terminalEndpointIdentityKey(endpoint),
+        process_anchor_pid: processAnchorPid,
         keys: approval.keys ?? (approval.key ? [approval.key] : undefined),
         label: approval.label,
         prompt_kind: approval.prompt_kind,
@@ -7990,10 +8059,7 @@ function recordTerminalBridgeApprovalNotification({ statePath, logPath, terminal
             stringValue(currentNativeTakeover.terminal_bridge_message_id) !==
                 expectedConversation.messageId ||
             !currentTerminalControl ||
-            currentTerminalControl.kind !== terminalControl.kind ||
-            currentTerminalControl.target !== terminalControl.target ||
-            currentTerminalControl.socketPath !== terminalControl.socketPath ||
-            currentTerminalControl.panePid !== terminalControl.panePid) {
+            !terminalControlsShareIncarnation(currentTerminalControl, terminalControl)) {
             return {
                 conversation,
                 duplicate: false,
@@ -8301,7 +8367,7 @@ async function runSend(options) {
             throw new Error("raw tmux terminal sends require --background so AKK can persist and monitor the submission safely");
         }
         const rawStoreDir = storeDirFromOptions(options);
-        const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(rawStoreDir, terminalConversation.terminalControl), { timeoutMs: 30000 });
+        const releaseTerminalLock = acquireTerminalBridgeSendLock(rawStoreDir, terminalConversation.terminalControl, { timeoutMs: 30000 });
         try {
             await withStoreWriterLeaseAsync(rawStoreDir, async () => {
                 await recoverLifecycleFenceBeforeMutation({
@@ -8519,12 +8585,23 @@ async function runSend(options) {
     if (!rawTerminalId) {
         throw new Error(`managed Session ${sessionId} has no authoritative terminal binding`);
     }
-    const resolvedTerminal = await createTerminalAgentBridge(options)
-        .resolveConversationId(rawTerminalId);
+    const storedTerminalControl = initialSession?.binding?.terminal_control ??
+        terminalControlFromTakeover(legacyTakeover);
+    const storedAgent = initialSession?.agent ??
+        (legacyBindingTurn
+            ? executorForConversation(legacyBindingTurn).kind
+            : undefined);
+    const storedPid = initialSession?.binding?.native_process.pid ??
+        Number(legacyTakeover?.terminal_agent_pid);
+    const terminalBridge = createTerminalAgentBridge(options);
+    const resolvedTerminal = storedTerminalControl && storedAgent &&
+        Number.isSafeInteger(storedPid) && storedPid > 1
+        ? await terminalBridge.resolveStoredTerminal(storedAgent, storedPid, storedTerminalControl, { pid: storedPid })
+        : await terminalBridge.resolveConversationId(rawTerminalId);
     if (!resolvedTerminal) {
         throw new Error(`session ${sessionId} is not attached to a live tmux terminal`);
     }
-    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDir, resolvedTerminal.terminalControl), { timeoutMs: 30000 });
+    const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDir, resolvedTerminal.terminalControl, { timeoutMs: 30000 });
     try {
         await withStoreWriterLeaseAsync(storeDir, async () => {
             await recoverLifecycleFenceBeforeMutation({
@@ -8692,18 +8769,19 @@ async function runTurnResponse({ options, messageBody }) {
     if (!storedTerminalControl || !nativeTerminalId) {
         throw new Error(`turn ${turnIdForConversation(initialConversation)} is not attached to a live tmux terminal`);
     }
-    const liveTerminal = await createTerminalAgentBridge(options)
-        .resolveConversationId(nativeTerminalId);
+    const storedPid = Number(nativeTakeover?.terminal_agent_pid);
+    const storedAgent = executorForConversation(initialConversation).kind;
+    const liveTerminal = Number.isSafeInteger(storedPid) && storedPid > 1
+        ? await createTerminalAgentBridge(options).resolveStoredTerminal(storedAgent, storedPid, storedTerminalControl, terminalRuntimeIdentityForConversation(initialConversation, storedTerminalControl))
+        : undefined;
     if (!liveTerminal ||
         liveTerminal.agent !== executorForConversation(initialConversation).kind ||
-        liveTerminal.terminalControl.target !== storedTerminalControl.target ||
-        liveTerminal.terminalControl.socketPath !== storedTerminalControl.socketPath ||
-        liveTerminal.terminalControl.panePid !== storedTerminalControl.panePid) {
+        !terminalControlsShareIncarnation(liveTerminal.terminalControl, storedTerminalControl)) {
         throw new Error(`turn ${turnIdForConversation(initialConversation)} is not attached to its expected live tmux terminal`);
     }
     const terminalControl = liveTerminal.terminalControl;
     const responseStoreDir = pathsForConversationDir(path.dirname(statePath)).storeDir;
-    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(responseStoreDir, terminalControl), { timeoutMs: 30000 });
+    const releaseTerminalLock = acquireTerminalBridgeSendLock(responseStoreDir, terminalControl, { timeoutMs: 30000 });
     try {
         await withStoreWriterLeaseAsync(responseStoreDir, async () => {
             // Legacy identity migration may write the Turn, so keep it inside the
@@ -8711,17 +8789,15 @@ async function runTurnResponse({ options, messageBody }) {
             await migrateLegacyTerminalAgentIdentity({ ...loaded, options });
             const releaseStateLock = acquireFileLock(`${statePath}.lock`);
             try {
-                const lockedConversation = loadState(statePath);
-                const lockedTakeover = isRecord(lockedConversation.native_session_takeover)
+                let lockedConversation = loadState(statePath);
+                let lockedTakeover = isRecord(lockedConversation.native_session_takeover)
                     ? lockedConversation.native_session_takeover
                     : undefined;
                 const lockedControl = terminalControlFromTakeover(lockedTakeover);
                 if (stringValue(lockedTakeover?.native_session_id) !== nativeTerminalId ||
                     executorForConversation(lockedConversation).kind !== liveTerminal.agent ||
                     !lockedControl ||
-                    lockedControl.target !== terminalControl.target ||
-                    lockedControl.socketPath !== terminalControl.socketPath ||
-                    lockedControl.panePid !== terminalControl.panePid) {
+                    !terminalControlsShareIncarnation(lockedControl, terminalControl)) {
                     throw new Error("terminal control changed while waiting to respond; refresh status and retry");
                 }
                 if (requestedOpenClawSession &&
@@ -8729,6 +8805,14 @@ async function runTurnResponse({ options, messageBody }) {
                     throw new Error(`turn ${turnIdForConversation(lockedConversation)} belongs to a ` +
                         "different OpenClaw session; no terminal input was sent");
                 }
+                lockedConversation = refineTerminalTurnEndpoint({
+                    conversation: lockedConversation,
+                    statePath,
+                    terminalControl
+                });
+                lockedTakeover = isRecord(lockedConversation.native_session_takeover)
+                    ? lockedConversation.native_session_takeover
+                    : undefined;
                 if (replayExactActiveTerminalSubmission({
                     options,
                     terminalControl,
@@ -8757,7 +8841,7 @@ async function runTurnResponse({ options, messageBody }) {
                     ? prepared.conversation.native_session_takeover
                     : undefined;
                 const terminalAgentPid = Number(preparedTakeover?.terminal_agent_pid);
-                const responseManagedSession = tryLoadManagedSession(responseStoreDir, sessionIdForConversation(prepared.conversation));
+                let responseManagedSession = tryLoadManagedSession(responseStoreDir, sessionIdForConversation(prepared.conversation));
                 const responseCodexCompanions = prepared.executor.kind === "codex" && responseManagedSession
                     ? codexAllowedCompanionSetForManagedSession({
                         storeDir: responseStoreDir,
@@ -8780,11 +8864,22 @@ async function runTurnResponse({ options, messageBody }) {
                     currentIdentity: currentNativeIdentity,
                     operation: "respond to"
                 });
+                if (responseManagedSession) {
+                    const logicalResponseIdentity = logicalIdentityForManagedSession({
+                        storeDir: responseStoreDir,
+                        session: responseManagedSession,
+                        observedIdentity: currentNativeIdentity
+                    });
+                    responseManagedSession = refineManagedSessionNativeIdentity({
+                        storeDir: responseStoreDir,
+                        session: responseManagedSession,
+                        terminalControl,
+                        identity: logicalResponseIdentity
+                    });
+                }
                 const currentTerminalControl = terminalControlFromTakeover(prepared.nativeTakeoverForSend);
                 if (!currentTerminalControl ||
-                    currentTerminalControl.target !== terminalControl.target ||
-                    currentTerminalControl.socketPath !== terminalControl.socketPath ||
-                    currentTerminalControl.panePid !== terminalControl.panePid) {
+                    !terminalControlsShareIncarnation(currentTerminalControl, terminalControl)) {
                     throw new Error("terminal control changed while waiting to respond; refresh status and retry");
                 }
                 const responseOptions = {
@@ -8988,7 +9083,7 @@ async function runApprove(options) {
                 : {})
         };
     };
-    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDirFromOptions(options), terminalControl), { timeoutMs: 30000 });
+    const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 });
     let terminalLockReleased = false;
     const releaseApprovalTerminalLock = () => {
         if (!terminalLockReleased) {
@@ -9021,8 +9116,8 @@ async function runApprove(options) {
                 : undefined;
             if (currentConversation.status !== conversation.status ||
                 currentTakeover?.terminal_bridge_message_id !== nativeTakeover?.terminal_bridge_message_id ||
-                currentControl?.target !== terminalControl.target ||
-                currentControl?.socketPath !== terminalControl.socketPath ||
+                !currentControl ||
+                !terminalControlsShareIncarnation(currentControl, terminalControl) ||
                 (claudeScreenApproval &&
                     currentApproval?.fingerprint !== monitoredApproval?.fingerprint)) {
                 throw new Error("approval state changed while waiting for terminal control; refresh status and retry");
@@ -9147,8 +9242,7 @@ async function runApprove(options) {
                             latestNotifiedAt === undefined ||
                             Date.now() - latestNotifiedAt > CLAUDE_SCREEN_APPROVAL_TTL_MS ||
                             expectedFingerprint !== fingerprint ||
-                            latestControl?.target !== dispatchControl.target ||
-                            latestControl?.socketPath !== dispatchControl.socketPath ||
+                            !terminalControlsShareIncarnation(latestControl, dispatchControl) ||
                             (autoApproved &&
                                 (latestPolicyEvidence?.source !== "claude_transcript" ||
                                     latestPolicyEvidence.evidence_fingerprint !==
@@ -9342,7 +9436,7 @@ async function runApprove(options) {
     }
 }
 async function runTerminalConversationApprove({ options, conversationId, agent, terminalControl, pid }) {
-    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDirFromOptions(options), terminalControl), { timeoutMs: 30000 });
+    const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 });
     try {
         if (agent === "claude") {
             printJson({
@@ -9407,7 +9501,7 @@ async function runTerminalConversationApprove({ options, conversationId, agent,
 async function runTerminalControlSend({ options, conversation, nextConversation, statePath, logPath, executor, message, terminalControl, terminalSendLockHeld = false, terminalStateLockHeld = false, storeWriterLeaseHeld = false, recordMessageAfterSend = false, recordRawAttachmentAfterSend = false, onTerminalPreflightVerified = undefined, allowedPreMaterializationIdentity = undefined, allowedAdditionalIdentities = [], continuingTurnResponse = false }) {
     const bridge = terminalBridgeEnabled(conversation);
     if (!terminalSendLockHeld) {
-        const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDirFromOptions(options), terminalControl), { timeoutMs: 30000 });
+        const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 });
         try {
             return await runTerminalControlSend({
                 options,
@@ -9445,8 +9539,7 @@ async function runTerminalControlSend({ options, conversation, nextConversation,
                 currentConversation.updated_at !== nextConversation.updated_at ||
                 currentConversation.status !== nextConversation.status ||
                 currentConversation.response_rounds_used !== nextConversation.response_rounds_used ||
-                currentControl?.target !== terminalControl.target ||
-                currentControl?.socketPath !== terminalControl.socketPath) {
+                !terminalControlsShareIncarnation(currentControl, terminalControl)) {
                 throw new Error("conversation changed while waiting to send to the terminal; refresh status and retry");
             }
             return await runTerminalControlSend({
@@ -11469,9 +11562,8 @@ function migratedTerminalTurnMatchesSessionBinding({ conversation, takeover, ter
         session.agent !== agent ||
         path.resolve(session.workspace) !== path.resolve(conversation.workspace) ||
         !terminalId ||
-        binding.terminal_id !== terminalId ||
-        terminalControlSelectorKey(binding.terminal_control) !==
-            terminalControlSelectorKey(terminalControl) ||
+        !terminalControlAliasMatches(terminalId, terminalControl, binding.terminal_id, binding.terminal_control) ||
+        !terminalControlsShareIncarnation(binding.terminal_control, terminalControl) ||
         !Number.isSafeInteger(pid) ||
         binding.native_process.pid !== pid ||
         !turnNativeThreadId ||
@@ -11556,24 +11648,28 @@ function nativeThreadTransitionRevision(transition) {
 }
 function refineManagedSessionNativeIdentity({ storeDir, session, terminalControl, identity }) {
     const binding = session.binding;
-    if (!identity || session.status !== "bound" || !binding) {
+    if (session.status !== "bound" || !binding) {
         return session;
     }
-    if (terminalControlSelectorKey(binding.terminal_control) !==
-        terminalControlSelectorKey(terminalControl) ||
-        (binding.native_thread_id &&
+    if (!terminalControlsShareIncarnation(binding.terminal_control, terminalControl) ||
+        (identity && binding.native_thread_id &&
             binding.native_thread_id !== identity.sessionId)) {
         throw new Error(`managed Session ${session.session_id} changed native identity before send`);
     }
-    const refinedNativeThreadId = binding.native_thread_id ?? identity.sessionId;
-    const refinedProcessUuid = binding.native_process.process_uuid ?? identity.processUuid;
-    const refinedProcessBirth = binding.native_process.process_birth ?? identity.processBirth;
-    const refinedRollout = binding.native_process.rollout ?? identity.rollout;
+    const refinedNativeThreadId = binding.native_thread_id ?? identity?.sessionId;
+    const refinedProcessUuid = binding.native_process.process_uuid ?? identity?.processUuid;
+    const refinedProcessBirth = binding.native_process.process_birth ?? identity?.processBirth;
+    const refinedRollout = binding.native_process.rollout ?? identity?.rollout;
+    const refinedTerminalEndpoint = binding.terminal_endpoint ??
+        (hasCanonicalTerminalEndpoint(terminalControl)
+            ? terminalControlEvidence(terminalControl)
+            : undefined);
     const changed = refinedNativeThreadId !== binding.native_thread_id ||
         refinedProcessUuid !== binding.native_process.process_uuid ||
         refinedProcessBirth !== binding.native_process.process_birth ||
         JSON.stringify(refinedRollout) !==
-            JSON.stringify(binding.native_process.rollout);
+            JSON.stringify(binding.native_process.rollout) ||
+        refinedTerminalEndpoint !== binding.terminal_endpoint;
     if (!changed) {
         return session;
     }
@@ -11582,13 +11678,16 @@ function refineManagedSessionNativeIdentity({ storeDir, session, terminalControl
         ...session,
         binding: {
             ...binding,
+            ...(refinedTerminalEndpoint
+                ? { terminal_endpoint: refinedTerminalEndpoint }
+                : {}),
             native_thread_id: refinedNativeThreadId,
             native_process: {
                 ...binding.native_process,
                 process_uuid: refinedProcessUuid,
                 process_birth: refinedProcessBirth,
                 rollout: refinedRollout,
-                evidence: identity.evidence
+                evidence: identity?.evidence ?? binding.native_process.evidence
             },
             last_verified_at: now
         },
@@ -11611,8 +11710,7 @@ function persistManagedSessionNativeIdentity({ conversation, terminalControl, id
         !current.binding ||
         current.binding.binding_id !== bindingId ||
         current.binding.generation !== bindingGeneration ||
-        terminalControlSelectorKey(current.binding.terminal_control) !==
-            terminalControlSelectorKey(terminalControl)) {
+        !terminalControlsShareIncarnation(current.binding.terminal_control, terminalControl)) {
         throw new Error(`managed Session ${sessionId} binding changed before native identity commit`);
     }
     const expectedNativeThreadId = current.binding.native_thread_id;
@@ -11760,12 +11858,10 @@ function managedTurnMatchesResolvedTerminal(conversation, terminalConversation,
         currentTerminalIdentity &&
         executorForConversation(conversation).kind === terminalConversation.agent &&
         storedTerminalIdentity.agent === currentTerminalIdentity.agent &&
-        storedTerminalIdentity.target === currentTerminalIdentity.target &&
         storedTerminalIdentity.pid === currentTerminalIdentity.pid &&
         Number(takeover?.terminal_agent_pid) === terminalConversation.pid &&
         nativeAgentIdentityMatchesTurn(conversation, currentNativeIdentity) &&
-        terminalControlSelectorKey(storedControl) ===
-            terminalControlSelectorKey(terminalConversation.terminalControl) &&
+        terminalControlsShareIncarnation(storedControl, terminalConversation.terminalControl) &&
         matchesConfiguredWorkspace(conversation.workspace, terminalConversation.terminalControl.currentPath));
 }
 function createManagedTerminalTurn({ options, conversationId, agent, pid, messageBody, terminalControl, previousTurn, managedSession, nativeAgentIdentity }) {
@@ -11834,7 +11930,7 @@ function createManagedTerminalTurn({ options, conversationId, agent, pid, messag
             takeover_match_kind: previousTurn
                 ? "managed_session_send"
                 : "raw_terminal_send",
-            terminal_control: terminalControl,
+            ...terminalEndpointTakeoverFields(terminalControl),
             needs_bootstrap: false,
             terminal_bridge: true
         }
@@ -11898,10 +11994,11 @@ async function runRenew(options) {
     if (!terminalControl || nativeTakeover?.["terminal_bridge"] !== true) {
         throw new Error(`cannot renew ${conversation.conversation_id}; conversation is not a terminal bridge task`);
     }
-    const panes = await createTerminalControlProvider(options).listPanes();
-    const terminalExists = panes.some((pane) => pane.target === terminalControl.target &&
-        (terminalControl.socketPath === undefined || pane.socketPath === terminalControl.socketPath));
-    if (!terminalExists) {
+    const terminalProvider = createTerminalControlProvider(options);
+    try {
+        await terminalProvider.resolve(terminalProvider.endpoint(terminalControl));
+    }
+    catch {
         throw new Error(`cannot renew ${conversation.conversation_id}; terminal ${terminalControl.target} is no longer available`);
     }
     const expectedMessageId = stringValue(nativeTakeover?.terminal_bridge_message_id);
@@ -11924,9 +12021,7 @@ async function runRenew(options) {
             throw new Error(`cannot renew ${current.conversation_id}; conversation is not a terminal bridge task`);
         }
         if (current.conversation_id !== conversation.conversation_id ||
-            currentControl.target !== terminalControl.target ||
-            currentControl.socketPath !== terminalControl.socketPath ||
-            currentControl.panePid !== terminalControl.panePid ||
+            !terminalControlsShareIncarnation(currentControl, terminalControl) ||
             stringValue(currentTakeover.terminal_bridge_message_id) !== expectedMessageId ||
             stringValue(currentTakeover.terminal_bridge_started_at) !== expectedStartedAt) {
             throw new Error("conversation changed while waiting to renew; refresh status and retry");
@@ -12601,7 +12696,7 @@ async function runCancel(options) {
     throw new Error(`conversation ${conversation.conversation_id} is not attached to a live tmux terminal`);
 }
 async function runTerminalConversationCancel({ options, conversationId, agent, terminalControl, pid }) {
-    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDirFromOptions(options), terminalControl), { timeoutMs: 30000 });
+    const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 });
     try {
         const cancellation = await createTerminalAgentBridge(options).cancel(agent, terminalControl, {
             runtime: {
@@ -12639,7 +12734,7 @@ async function runTerminalConversationCancel({ options, conversationId, agent, t
     }
 }
 async function runTerminalControlCancel({ options, statePath, logPath, agent, terminalControl }) {
-    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDirFromOptions(options), terminalControl), { timeoutMs: 30000 });
+    const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 });
     let releaseStateLock;
     try {
         releaseStateLock = acquireFileLock(`${statePath}.lock`);
@@ -12654,8 +12749,7 @@ async function runTerminalControlCancel({ options, statePath, logPath, agent, te
                 : undefined;
             const currentControl = terminalControlFromTakeover(currentTakeover);
             if (!currentControl ||
-                currentControl.target !== terminalControl.target ||
-                currentControl.socketPath !== terminalControl.socketPath) {
+                !terminalControlsShareIncarnation(currentControl, terminalControl)) {
                 throw new Error("terminal control changed while waiting to cancel; refresh status and retry");
             }
             assertManagedTerminalDispatchOwner({
@@ -12742,7 +12836,7 @@ async function runClose(options) {
         : undefined;
     const terminalControl = terminalControlFromTakeover(nativeTakeover);
     const releaseTerminalLock = terminalControl
-        ? acquireFileLock(terminalBridgeSendLockPath(storeDirFromOptions(options), terminalControl), { timeoutMs: 30000 })
+        ? acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 })
         : () => { };
     let releaseStateLock;
     try {
@@ -12816,7 +12910,7 @@ async function runClose(options) {
 async function runTerminalDispatchClose({ options, terminalConversation }) {
     const terminalControl = terminalConversation.terminalControl;
     const storeDir = storeDirFromOptions(options);
-    const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDir, terminalControl), { timeoutMs: 30000 });
+    const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDir, terminalControl, { timeoutMs: 30000 });
     try {
         return await withStoreWriterLeaseAsync(storeDir, async () => {
             let ledger = resolveTerminalDispatchLedgerPaneIncarnation(terminalControl, loadTerminalBridgeDispatchLedger(terminalControl));
@@ -13484,7 +13578,7 @@ async function runTerminalBridgeMonitorWithLock(options, lifecycle, expectedTerm
                     });
                     return;
                 }
-                const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDirFromOptions(options), terminalControl), { timeoutMs: 30000 });
+                const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 });
                 try {
                     const reconciliation = await reconcileTerminalAcceptanceInMonitor({
                         options,
@@ -13548,7 +13642,7 @@ async function runTerminalBridgeMonitorWithLock(options, lifecycle, expectedTerm
                     sleepSync(pollIntervalMs);
                     continue;
                 }
-                const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDirFromOptions(options), terminalControl), { timeoutMs: 30000 });
+                const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 });
                 try {
                     const writerStoreDir = pathsForConversationDir(path.dirname(statePath)).storeDir;
                     await withStoreWriterLeaseAsync(writerStoreDir, async () => {
@@ -13828,7 +13922,7 @@ async function runTerminalBridgeMonitorWithLock(options, lifecycle, expectedTerm
         let poll;
         const expectedUpdatedAt = conversation.updated_at;
         const expectedStatus = conversation.status;
-        const releaseTerminalPollLock = acquireFileLock(terminalBridgeSendLockPath(storeDirFromOptions(options), terminalControl), { timeoutMs: 30000 });
+        const releaseTerminalPollLock = acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 });
         try {
             let dispatchLedger = reconcilePreparedTerminalDispatchLedger(terminalControl, loadTerminalBridgeDispatchLedger(terminalControl));
             const durableSubmission = terminalBridgeSubmission(conversation);
@@ -13894,8 +13988,7 @@ async function runTerminalBridgeMonitorWithLock(options, lifecycle, expectedTerm
                 stringValue(lockedTakeover?.terminal_bridge_message_id) !==
                     currentMessageId ||
                 !lockedControl ||
-                terminalControlSelectorKey(lockedControl) !==
-                    terminalControlSelectorKey(terminalControl)) {
+                !terminalControlsShareIncarnation(lockedControl, terminalControl)) {
                 conversation = lockedConversation;
                 continue;
             }
@@ -14579,6 +14672,39 @@ function terminalBridgeSendLockPath(_storeDir, terminalControl) {
     const terminalKey = terminalBridgeRuntimeKey(terminalControl);
     return path.join(lockDir, `terminal-bridge-send-${terminalKey}.lock`);
 }
+function legacyTerminalBridgeSendLockPath(_storeDir, terminalControl) {
+    const lockDir = terminalBridgeRuntimeLockDir();
+    ensureDir(lockDir);
+    return path.join(lockDir, `terminal-bridge-send-${legacyTerminalBridgeRuntimeKey(terminalControl)}.lock`);
+}
+function acquireTerminalBridgeSendLock(storeDir, terminalControl, options = {}) {
+    const lockPaths = [...new Set([
+            terminalBridgeSendLockPath(storeDir, terminalControl),
+            legacyTerminalBridgeSendLockPath(storeDir, terminalControl)
+        ])].sort();
+    const releases = [];
+    try {
+        for (const lockPath of lockPaths) {
+            releases.push(acquireFileLock(lockPath, options));
+        }
+    }
+    catch (error) {
+        for (const release of releases.reverse()) {
+            release();
+        }
+        throw error;
+    }
+    let released = false;
+    return () => {
+        if (released) {
+            return;
+        }
+        released = true;
+        for (const release of [...releases].reverse()) {
+            release();
+        }
+    };
+}
 function terminalBridgeRuntimeLockDir() {
     return path.join(terminalBridgeRuntimeDir(), "terminal-locks");
 }
@@ -14589,46 +14715,101 @@ function terminalBridgeRuntimeDir() {
         : path.join(path.dirname(defaultStoreDir()), "runtime-v2");
 }
 function terminalBridgeRuntimeKey(terminalControl) {
+    if (hasCanonicalTerminalEndpoint(terminalControl)) {
+        return createHash("sha256")
+            .update(terminalEndpointIdentityKey(terminalControl))
+            .digest("hex")
+            .slice(0, 20);
+    }
+    return legacyTerminalBridgeRuntimeKey(terminalControl);
+}
+function legacyTerminalBridgeRuntimeKey(terminalControl) {
     return createHash("sha256")
-        .update(JSON.stringify({
-        target: terminalControl.target,
-        socket_path: terminalControl.socketPath ?? null
-    }))
+        .update(JSON.stringify(terminalLegacyRuntimeRoute(terminalControl)))
         .digest("hex")
         .slice(0, 20);
 }
-function terminalBridgeDispatchLedgerPath(terminalControl) {
+function terminalBridgeDispatchLedgerPath(terminalControl, options = {}) {
     const ledgerDir = path.join(terminalBridgeRuntimeDir(), "terminal-dispatch");
-    return path.join(ledgerDir, `terminal-dispatch-${terminalBridgeRuntimeKey(terminalControl)}.json`);
+    return path.join(ledgerDir, `terminal-dispatch-${options.legacy
+        ? legacyTerminalBridgeRuntimeKey(terminalControl)
+        : terminalBridgeRuntimeKey(terminalControl)}.json`);
+}
+function terminalBridgeDispatchLedgerPaths(terminalControl) {
+    return [...new Set([
+            terminalBridgeDispatchLedgerPath(terminalControl),
+            terminalBridgeDispatchLedgerPath(terminalControl, { legacy: true })
+        ])];
 }
 function loadTerminalBridgeDispatchLedger(terminalControl) {
-    const ledgerPath = terminalBridgeDispatchLedgerPath(terminalControl);
-    if (!fs.existsSync(ledgerPath)) {
+    const ledgerPaths = terminalBridgeDispatchLedgerPaths(terminalControl)
+        .filter((candidate) => fs.existsSync(candidate));
+    if (ledgerPaths.length === 0) {
         return undefined;
     }
+    if (ledgerPaths.length > 1) {
+        throw new Error(`terminal dispatch ledger has conflicting canonical and legacy owners: ` +
+            ledgerPaths.join(", "));
+    }
+    const ledgerPath = ledgerPaths[0];
     const stat = fs.lstatSync(ledgerPath);
     if (stat.isSymbolicLink() || !stat.isFile()) {
         throw new Error(`terminal dispatch ledger is not a regular file: ${ledgerPath}`);
     }
     const parsed = JSON.parse(fs.readFileSync(ledgerPath, "utf8"));
     if (!isRecord(parsed) ||
-        parsed.version !== 1 ||
-        stringValue(parsed.terminal_key) !== terminalBridgeRuntimeKey(terminalControl)) {
+        !(parsed.version === 1 || parsed.version === 2)) {
         throw new Error(`terminal dispatch ledger is invalid: ${ledgerPath}`);
     }
+    if (parsed.version === 1) {
+        const control = isRecord(parsed.terminal_control)
+            ? parsed.terminal_control
+            : undefined;
+        if (stringValue(parsed.terminal_key) !==
+            legacyTerminalBridgeRuntimeKey(terminalControl) ||
+            stringValue(control?.target) !== terminalControl.target ||
+            (stringValue(control?.socket_path) ?? undefined) !==
+                terminalControl.socketPath) {
+            throw new Error(`terminal dispatch ledger is invalid: ${ledgerPath}`);
+        }
+    }
+    else {
+        const identity = terminalEndpointIdentityFromEvidence(parsed.terminal_endpoint);
+        if (!identity ||
+            stringValue(parsed.terminal_key) !==
+                terminalBridgeRuntimeKey(terminalControl) ||
+            !sameTerminalEndpointIdentity(identity, terminalControl)) {
+            throw new Error(`terminal dispatch ledger is invalid: ${ledgerPath}`);
+        }
+    }
     return parsed;
 }
+function terminalDispatchRecordMatchesControl(record, terminalControl, options = {}) {
+    if (!record) {
+        return false;
+    }
+    const evidence = record.terminal_endpoint !== undefined
+        ? record.terminal_endpoint
+        : record.terminal_control;
+    return terminalControlEvidenceMatches(evidence, terminalControl, options);
+}
+function terminalDispatchRecordProcessAnchor(record) {
+    const evidence = isRecord(record.terminal_endpoint)
+        ? record.terminal_endpoint
+        : isRecord(record.terminal_control)
+            ? record.terminal_control
+            : undefined;
+    const panePid = Number(evidence?.process_anchor_pid ?? evidence?.pane_pid ?? evidence?.panePid);
+    return Number.isSafeInteger(panePid) && panePid > 0 ? panePid : undefined;
+}
 function assertTerminalNativeThreadStoreAuthority({ terminalControl, nativeThreadId, storeDir }) {
     const ledger = resolveTerminalDispatchLedgerPaneIncarnation(terminalControl, loadTerminalBridgeDispatchLedger(terminalControl));
     if (!ledger) {
         return;
     }
-    const ledgerControl = isRecord(ledger.terminal_control)
-        ? ledger.terminal_control
-        : undefined;
-    if (stringValue(ledgerControl?.target) !== terminalControl.target ||
-        (stringValue(ledgerControl?.socket_path) ?? undefined) !==
-            terminalControl.socketPath) {
+    if (!terminalDispatchRecordMatchesControl(ledger, terminalControl, {
+        requireProcessAnchor: false
+    })) {
         throw new Error(`terminal ${terminalControl.target} dispatch ledger selector is invalid`);
     }
     const binding = isRecord(ledger.binding) ? ledger.binding : undefined;
@@ -14672,11 +14853,6 @@ function orphanedTerminalDispatchForRecovery(terminalControl) {
         const recoveryIdentity = lifecycle
             ? stringValue(ledger?.transition_id)
             : stringValue(ledger?.message_id);
-        const ledgerControl = isRecord(ledger?.terminal_control)
-            ? ledger.terminal_control
-            : undefined;
-        const ledgerPanePid = Number(ledgerControl?.pane_pid);
-        const currentPanePid = Number(terminalControl.panePid);
         if (!ledger ||
             ![
                 "prepared",
@@ -14692,11 +14868,10 @@ function orphanedTerminalDispatchForRecovery(terminalControl) {
                 .includes(String(ledger.status)) ||
             !recoveryIdentity ||
             (!lifecycle &&
-                Number.isSafeInteger(ledgerPanePid) &&
-                ledgerPanePid > 0 &&
-                Number.isSafeInteger(currentPanePid) &&
-                currentPanePid > 0 &&
-                ledgerPanePid !== currentPanePid) ||
+                terminalDispatchRecordMatchesControl(ledger, terminalControl, {
+                    requireProcessAnchor: false
+                }) &&
+                !terminalDispatchRecordMatchesControl(ledger, terminalControl)) ||
             (!lifecycle && loadTerminalDispatchLedgerOwner(ledger))) {
             return undefined;
         }
@@ -14865,12 +15040,11 @@ function mergeTerminalLedgerReceipt(previous, next) {
     const nextControl = isRecord(next.terminal_control)
         ? next.terminal_control
         : undefined;
-    if (previousControl &&
-        nextControl &&
-        (stringValue(previousControl.target) !== stringValue(nextControl.target) ||
-            (stringValue(previousControl.socket_path) ?? undefined) !==
-                (stringValue(nextControl.socket_path) ?? undefined) ||
-            Number(previousControl.pane_pid) !== Number(nextControl.pane_pid))) {
+    const previousEvidence = previous.terminal_endpoint ?? previousControl;
+    const nextEvidence = next.terminal_endpoint ?? nextControl;
+    if (previousEvidence !== undefined &&
+        nextEvidence !== undefined &&
+        !sameTerminalControlEvidenceIncarnation(previousEvidence, nextEvidence)) {
         throw new Error(`terminal dispatch receipt ${messageId} changed immutable terminal_control`);
     }
     if (previous.status === "agent_accepted" &&
@@ -14899,17 +15073,40 @@ function mergeTerminalLedgerReceipt(previous, next) {
     if (!merged.terminal_control && previousControl) {
         merged.terminal_control = previousControl;
     }
+    if (!merged.terminal_endpoint && previous.terminal_endpoint) {
+        merged.terminal_endpoint = previous.terminal_endpoint;
+    }
     return merged;
 }
 function saveTerminalBridgeDispatchLedger(terminalControl, ledger) {
-    const ledgerPath = terminalBridgeDispatchLedgerPath(terminalControl);
+    const previousLedger = loadTerminalBridgeDispatchLedger(terminalControl);
+    const existingPaths = terminalBridgeDispatchLedgerPaths(terminalControl)
+        .filter((candidate) => fs.existsSync(candidate));
+    let ledgerPath = existingPaths[0] ??
+        terminalBridgeDispatchLedgerPath(terminalControl);
+    const canonicalLedgerPath = terminalBridgeDispatchLedgerPath(terminalControl);
+    const legacyLedgerPath = terminalBridgeDispatchLedgerPath(terminalControl, { legacy: true });
+    ensureDir(path.dirname(canonicalLedgerPath));
+    if (hasCanonicalTerminalEndpoint(terminalControl) &&
+        ledgerPath === legacyLedgerPath &&
+        legacyLedgerPath !== canonicalLedgerPath) {
+        // Promote a validated v0.11.x route-keyed ledger before writing the next
+        // generation. rename() removes the duplicate-owner window: after a crash,
+        // the canonical path may still contain v1 JSON, which the compatibility
+        // reader accepts and a later writer can finish upgrading to v2.
+        if (fs.existsSync(canonicalLedgerPath)) {
+            throw new Error(`terminal dispatch ledger has conflicting canonical and legacy owners: ` +
+                `${canonicalLedgerPath}, ${legacyLedgerPath}`);
+        }
+        fs.renameSync(legacyLedgerPath, canonicalLedgerPath);
+        fsyncTerminalBridgeDirectory(path.dirname(canonicalLedgerPath));
+        ledgerPath = canonicalLedgerPath;
+    }
+    const preserveLegacyFormat = !hasCanonicalTerminalEndpoint(terminalControl);
     ensureDir(path.dirname(ledgerPath));
     if (fs.existsSync(ledgerPath) && fs.lstatSync(ledgerPath).isSymbolicLink()) {
         throw new Error(`terminal dispatch ledger is a symlink: ${ledgerPath}`);
     }
-    const previousLedger = fs.existsSync(ledgerPath)
-        ? loadTerminalBridgeDispatchLedger(terminalControl)
-        : undefined;
     let baseReceiptHistory = terminalLedgerReceiptHistory(previousLedger);
     for (const incomingReceipt of terminalLedgerReceiptHistory(ledger)) {
         const incomingId = String(incomingReceipt.message_id);
@@ -14921,18 +15118,25 @@ function saveTerminalBridgeDispatchLedger(terminalControl, ledger) {
             ? baseReceiptHistory.map((receipt) => stringValue(receipt.message_id) === incomingId ? merged : receipt)
             : [...baseReceiptHistory, merged];
     }
-    const { terminal_submission_receipts: _incomingReceiptHistory, ...ledgerWithoutReceiptHistory } = ledger;
+    const { terminal_submission_receipts: _incomingReceiptHistory, terminal_endpoint: incomingTerminalEndpoint, ...ledgerWithoutReceiptHistory } = ledger;
     const nextWithoutHistory = {
         ...ledgerWithoutReceiptHistory,
-        version: 1,
-        terminal_key: terminalBridgeRuntimeKey(terminalControl),
+        version: hasCanonicalTerminalEndpoint(terminalControl) && !preserveLegacyFormat
+            ? 2
+            : 1,
+        terminal_key: preserveLegacyFormat
+            ? legacyTerminalBridgeRuntimeKey(terminalControl)
+            : terminalBridgeRuntimeKey(terminalControl),
         terminal_control: {
             kind: "tmux",
             target: terminalControl.target,
             socket_path: terminalControl.socketPath ?? null,
             pane_pid: terminalControl.panePid ?? null,
             current_path: terminalControl.currentPath ?? null
-        }
+        },
+        ...(hasCanonicalTerminalEndpoint(terminalControl) && !preserveLegacyFormat
+            ? { terminal_endpoint: terminalControlEvidence(terminalControl) }
+            : {})
     };
     // The top-level ledger follows the current tmux pane incarnation, while an
     // append-only receipt must retain the pane that actually accepted its
@@ -14940,10 +15144,16 @@ function saveTerminalBridgeDispatchLedger(terminalControl, ledger) {
     // pane with the same selector, so derive that receipt from the caller's
     // original control record instead of silently rebinding its proof.
     const receiptCandidateLedger = isRecord(ledgerWithoutReceiptHistory.terminal_control)
-        ? {
-            ...nextWithoutHistory,
-            terminal_control: ledgerWithoutReceiptHistory.terminal_control
-        }
+        ? (() => {
+            const { terminal_endpoint: _derivedTerminalEndpoint, ...nextWithoutDerivedTerminalEndpoint } = nextWithoutHistory;
+            return {
+                ...nextWithoutDerivedTerminalEndpoint,
+                terminal_control: ledgerWithoutReceiptHistory.terminal_control,
+                ...(incomingTerminalEndpoint && !preserveLegacyFormat
+                    ? { terminal_endpoint: incomingTerminalEndpoint }
+                    : {})
+            };
+        })()
         : nextWithoutHistory;
     const nextCandidate = terminalLedgerReceiptCandidate(receiptCandidateLedger);
     let nextReceiptHistory = baseReceiptHistory;
@@ -15018,23 +15228,20 @@ function resolveTerminalDispatchLedgerPaneIncarnation(terminalControl, ledger) {
         // released by the generic Turn-ledger cleanup path.
         return ledger;
     }
-    const ledgerControl = isRecord(ledger.terminal_control)
-        ? ledger.terminal_control
-        : undefined;
-    const ledgerPanePid = Number(ledgerControl?.pane_pid);
-    const currentPanePid = Number(terminalControl.panePid);
-    if (!Number.isSafeInteger(ledgerPanePid) ||
-        ledgerPanePid <= 0 ||
-        !Number.isSafeInteger(currentPanePid) ||
-        currentPanePid <= 0 ||
-        ledgerPanePid === currentPanePid) {
+    if (!terminalDispatchRecordMatchesControl(ledger, terminalControl, {
+        requireProcessAnchor: false
+    }) ||
+        terminalDispatchRecordMatchesControl(ledger, terminalControl)) {
         return ledger;
     }
+    const ledgerProcessAnchor = terminalDispatchRecordProcessAnchor(ledger);
+    const currentProcessAnchor = terminalEndpointFromControlRef(terminalControl).processAnchorPid;
     saveTerminalBridgeDispatchLedger(terminalControl, {
         ...ledger,
         status: "resolved",
         resolved_at: new Date().toISOString(),
-        reason: `tmux pane incarnation changed from pid ${ledgerPanePid} to ${currentPanePid}`
+        reason: "terminal process incarnation changed from anchor " +
+            `${ledgerProcessAnchor} to ${currentProcessAnchor ?? "unknown"}`
     });
     return loadTerminalBridgeDispatchLedger(terminalControl);
 }
@@ -15154,8 +15361,7 @@ function reconcilePreparedTerminalDispatchLedger(terminalControl, ledger) {
     if (conversation.conversation_id !==
         stringValue(ledger.conversation_id) ||
         !storedControl ||
-        terminalBridgeRuntimeKey(storedControl) !==
-            terminalBridgeRuntimeKey(terminalControl)) {
+        !sameTerminalControlIncarnation(storedControl, terminalControl)) {
         return ledger;
     }
     if (storedMessageId === messageId &&
@@ -15280,8 +15486,7 @@ function reconcileLaggingTerminalDispatchLedger(terminalControl, ledger) {
         stringValue(nativeTakeover?.terminal_bridge_message_id) !== messageId ||
         stringValue(submission?.message_id) !== messageId ||
         !storedControl ||
-        terminalBridgeRuntimeKey(storedControl) !==
-            terminalBridgeRuntimeKey(terminalControl)) {
+        !sameTerminalControlIncarnation(storedControl, terminalControl)) {
         return ledger;
     }
     const requestText = String(nativeTakeover?.terminal_bridge_request_text ?? conversation.user_request ?? "");
@@ -15709,16 +15914,13 @@ function assertLifecycleLedgerMatchesTransition({ options, terminal, ledger, tra
         stringValue(ledger.adapter_version) !== transition.adapter_version ||
         stringValue(ledger.command_fingerprint) !== transition.command_fingerprint ||
         path.resolve(storeDir) !== path.resolve(storeDirFromOptions(options)) ||
-        terminal.conversationId !== transition.terminal_id ||
         terminal.agent !== transition.agent ||
-        Number(ledgerControl?.pane_pid) !== terminal.terminalControl.panePid ||
-        stringValue(ledgerControl?.target) !== terminal.terminalControl.target ||
-        (stringValue(ledgerControl?.socket_path) ?? undefined) !==
-            terminal.terminalControl.socketPath ||
+        !terminalDispatchRecordMatchesControl(ledger, terminal.terminalControl) ||
         terminal.pid !== transition.before_binding?.native_process.pid &&
             transition.before_binding !== undefined ||
-        terminalControlSelectorKey(terminal.terminalControl) !==
-            terminalControlSelectorKey(transition.before_binding?.terminal_control ?? terminal.terminalControl) ||
+        !terminalControlsShareIncarnation(terminal.terminalControl, transition.before_binding?.terminal_control ?? terminal.terminalControl) ||
+        (transition.before_binding !== undefined &&
+            !terminalControlAliasMatches(transition.terminal_id, transition.before_binding.terminal_control, terminal.conversationId, terminal.terminalControl)) ||
         !matchesConfiguredWorkspace(transition.workspace, terminal.terminalControl.currentPath) ||
         JSON.stringify(ledger.binding ?? null) !==
             JSON.stringify(transition.before_binding ?? null)) {
@@ -15748,10 +15950,8 @@ async function verifyRecoveredLifecycleAfterBinding({ options, terminal, transit
     const binding = transition.after_binding;
     if (!binding ||
         !binding.native_thread_id ||
-        binding.terminal_id !== terminal.conversationId ||
         binding.native_process.pid !== terminal.pid ||
-        terminalControlSelectorKey(binding.terminal_control) !==
-            terminalControlSelectorKey(terminal.terminalControl)) {
+        !terminalControlAliasMatches(binding.terminal_id, binding.terminal_control, terminal.conversationId, terminal.terminalControl)) {
         throw new Error("verified after_binding no longer matches the terminal or pid");
     }
     const bridge = createTerminalAgentBridge(options);
@@ -16255,10 +16455,9 @@ async function assertNativeInspectionComposerReadyForAutomatedInput({ options, t
         });
         return;
     }
-    const screen = await createTerminalControlProvider(options).capture(terminal.terminalControl.target, {
-        scrollbackLines: 40,
-        socketPath: terminal.terminalControl.socketPath
-    });
+    const provider = createTerminalControlProvider(options);
+    const resolvedTerminal = await provider.resolve(provider.endpoint(terminal.terminalControl));
+    const screen = await provider.capture(resolvedTerminal, { scrollbackLines: 40 });
     if (!isExactClaudeNativeInspectionIdleComposer(screen)) {
         throw new Error("Claude composer contains input or is not at the exact idle frame; refusing automated terminal input");
     }
@@ -16677,7 +16876,7 @@ function prepareTerminalBridgeCompletionCallback({ options, statePath, logPath,
         });
         claim.release();
         claimReleased = true;
-        const releaseTerminalLock = acquireFileLock(terminalBridgeSendLockPath(storeDirFromOptions(options), terminalControl), { timeoutMs: 30000 });
+        const releaseTerminalLock = acquireTerminalBridgeSendLock(storeDirFromOptions(options), terminalControl, { timeoutMs: 30000 });
         try {
             resolveTerminalBridgeDispatchLedger({
                 terminalControl,