oh-my-codex 0.20.3 → 0.20.5

package/dist/hooks/session.js

@@ -5,14 +5,26 @@
  * serialized by an adjacent lock directory and become visible only after an
  * atomic rename of a transaction-owned temporary file.
  */
-import { appendFile, lstat as nodeLstat, mkdir as nodeMkdir, open, readFile as nodeReadFile, readdir as nodeReaddir, rename as nodeRename, rmdir as nodeRmdir, rm, unlink as nodeUnlink, writeFile as nodeWriteFile, } from 'fs/promises';
-import { readFileSync } from 'fs';
+import { execFileSync as nodeExecFileSync } from 'node:child_process';
+import { appendFile, mkdtemp as nodeMkdtemp, link as nodeLink, lstat as nodeLstat, mkdir as nodeMkdir, open, readFile as nodeReadFile, readdir as nodeReaddir, realpath, rename as nodeRename, rmdir as nodeRmdir, rm, unlink as nodeUnlink, writeFile as nodeWriteFile, } from 'fs/promises';
+import { appendFileSync, closeSync, constants as fsConstants, fstatSync, openSync, readFileSync } from 'fs';
+import { tmpdir } from 'node:os';
 import { createHash, randomUUID } from 'crypto';
-import { dirname, join } from 'path';
+import { basename, dirname, isAbsolute, join } from 'path';
 import { omxRoot, omxLogsDir, sameFilePath } from '../utils/paths.js';
+import { resolveRuntimeBinaryPath } from '../runtime/bridge.js';
 import { getBaseStateDirWithSource, resolveWorkingDirectoryForState, } from '../mcp/state-paths.js';
 import { emitDegradedDurabilityWarning, recordRegularFileSyncOutcome, syncRegularFile, } from '../utils/file-durability.js';
+export class CommittedLaunchBlockedError extends Error {
+    secondaryFailures;
+    name = 'CommittedLaunchBlockedError';
+    constructor(secondaryFailures) {
+        super('Session pointer committed, but lock release left recovery evidence.');
+        this.secondaryFailures = secondaryFailures;
+    }
+}
 const SESSION_FILE = 'session.json';
+const SESSION_OWNER_FILE = 'session-owner.json';
 const HISTORY_FILE = 'session-history.jsonl';
 const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
 const SESSION_POINTER_TOKEN_PATTERN = /^[A-Za-z0-9_-]{16,128}$/;
@@ -20,6 +32,14 @@ const SHA256_PATTERN = /^[a-f0-9]{64}$/;
 const LOCK_RETRY_DELAYS_MS = [25, 50, 100];
 const DEFAULT_POINTER_TIMEOUT_MS = 5_000;
 const NATIVE_POINTER_TIMEOUT_MS = 2_000;
+function traceSessionFinalizationOperation(operation) {
+    if (process.env.OMX_TEST_DETACHED_TRACE !== '1')
+        return;
+    const tracePath = process.env.OMX_TEST_DETACHED_TRACE_PATH;
+    if (!tracePath)
+        return;
+    appendFileSync(tracePath, `[omx-test-session-finalization] ${operation}\n`);
+}
 /**
  * Convert arbitrary input into a valid session ID without exposing validator
  * exceptions to lifecycle or hook inputs.
@@ -31,9 +51,9 @@ export function normalizeSessionId(value) {
     return SESSION_ID_PATTERN.test(trimmed) ? trimmed : undefined;
 }
 /** Resolve the one exact pointer path used by an operation. */
-export function resolveSessionPointerContext(cwd) {
-    const normalizedCwd = resolveWorkingDirectoryForState(cwd);
-    const { baseStateDir, rootSource } = getBaseStateDirWithSource(normalizedCwd);
+export function resolveSessionPointerContext(cwd, env = process.env) {
+    const normalizedCwd = resolveWorkingDirectoryForState(cwd, env);
+    const { baseStateDir, rootSource } = getBaseStateDirWithSource(normalizedCwd, env);
     const pointerPath = join(baseStateDir, SESSION_FILE);
     return {
         cwd: normalizedCwd,
@@ -43,6 +63,26 @@ export function resolveSessionPointerContext(cwd) {
         lockPath: `${pointerPath}.lock`,
     };
 }
+function resolveNativeSessionOwnerContext(cwd, nativeSessionId) {
+    const root = resolveSessionPointerContext(cwd);
+    const normalized = normalizeSessionId(nativeSessionId);
+    if (!normalized) {
+        throw resolvedAbort(root, {
+            code: 'session_pointer_io_failure',
+            operation: 'pointer-classify',
+            lockPath: root.lockPath,
+            reason: 'A valid native session ID is required for owner evidence.',
+        });
+    }
+    const baseStateDir = join(root.baseStateDir, 'sessions', normalized);
+    const sessionPath = join(baseStateDir, SESSION_OWNER_FILE);
+    return {
+        ...root,
+        baseStateDir,
+        sessionPath,
+        lockPath: `${sessionPath}.lock`,
+    };
+}
 function attemptedStateRootSource() {
     try {
         if (process.env.OMX_TEAM_STATE_ROOT?.trim())
@@ -139,6 +179,9 @@ const defaultFsDependencies = {
     rename: async (from, to) => {
         await nodeRename(from, to);
     },
+    link: async (path, dest) => {
+        await nodeLink(path, dest);
+    },
     unlink: async (path) => {
         await nodeUnlink(path);
     },
@@ -146,6 +189,28 @@ const defaultFsDependencies = {
         await nodeRmdir(path);
     },
 };
+async function defaultRecoveryRenameNoReplace(from, to) {
+    if (!from.trim() || !to.trim() || !isAbsolute(from) || !isAbsolute(to))
+        return 'unsupported';
+    try {
+        const stdout = nodeExecFileSync(resolveRuntimeBinaryPath(), ['fs-rename-no-replace', from, to], {
+            encoding: 'utf8',
+            maxBuffer: 64 * 1024,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: 10_000,
+        });
+        const parsed = JSON.parse(String(stdout));
+        if (parsed.outcome === 'moved' || parsed.outcome === 'not-moved' || parsed.outcome === 'unsupported') {
+            return parsed.outcome;
+        }
+    }
+    catch {
+        // Missing binaries, spawn failures, hard runtime errors, and malformed output
+        // all fail closed; recovery must never fall back to an overwriting rename.
+    }
+    return 'unsupported';
+}
 /** @internal Exposed only so source-module tests can verify default ESRCH handling. */
 export function __createDefaultPidProbeForTests(killZero) {
     return (pid) => {
@@ -163,26 +228,40 @@ function defaultProbePid(pid) {
         process.kill(targetPid, 0);
     })(pid);
 }
-function defaultReadProcessIdentity(pid, platform) {
-    if (platform !== 'linux')
-        return { status: 'indeterminate' };
-    const identity = readLinuxProcessIdentity(pid);
-    if (!identity)
-        return { status: 'indeterminate' };
-    const cmdlineHash = hashCmdline(identity.cmdline);
-    return {
-        status: 'matching',
-        startTicks: identity.startTicks,
-        ...(cmdlineHash ? { cmdlineHash } : {}),
-    };
+function defaultObserveProcess(pid, platform) {
+    if (platform === 'linux') {
+        return observeLinuxProcess(pid);
+    }
+    if (platform !== 'darwin' && platform !== 'win32') {
+        return { kind: 'unsupported' };
+    }
+    try {
+        const stdout = nodeExecFileSync(resolveRuntimeBinaryPath(), ['process-identity', String(pid)], {
+            encoding: 'utf8',
+            timeout: 3000,
+            maxBuffer: 64 * 1024,
+            shell: false,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return parseProcessIdentityOutput(stdout);
+    }
+    catch {
+        return { kind: 'unsupported' };
+    }
 }
 const defaultTransactionDependencies = {
     fs: defaultFsDependencies,
     nowMs: () => Date.now(),
     sleep: async (ms) => await new Promise((resolve) => setTimeout(resolve, ms)),
     token: () => randomUUID(),
+    runtimePlatform: process.platform,
     probePid: defaultProbePid,
-    readProcessIdentity: defaultReadProcessIdentity,
+    observeProcess: defaultObserveProcess,
+    atomicRenameNoReplace: defaultRecoveryRenameNoReplace,
+};
+export const defaultProcessInspectionProvider = {
+    probePid: defaultProbePid,
+    observeProcess: defaultObserveProcess,
 };
 let transactionDependencies = defaultTransactionDependencies;
 /** @internal Source-module test harness. Always reset after a test. */
@@ -234,13 +313,118 @@ function readLinuxProcessIdentity(pid) {
         return null;
     }
 }
-function defaultIsPidAlive(pid) {
+const NODE_PLATFORMS = new Set([
+    'aix', 'android', 'darwin', 'freebsd', 'haiku', 'linux', 'openbsd', 'sunos', 'win32', 'cygwin', 'netbsd',
+]);
+const PROCESS_BIRTH_PATTERN = /^\d+(?:\.\d+)?$/;
+function isNodePlatform(value) {
+    return typeof value === 'string' && NODE_PLATFORMS.has(value);
+}
+function isValidBirth(value) {
+    return typeof value === 'string' && PROCESS_BIRTH_PATTERN.test(value);
+}
+export function isValidProcessIdentity(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const identity = value;
+    if (Object.keys(identity).some((key) => key !== 'platform' && key !== 'birth' && key !== 'cmdline_hash'))
+        return false;
+    return isNodePlatform(identity.platform)
+        && isValidBirth(identity.birth)
+        && (identity.cmdline_hash === undefined
+            || typeof identity.cmdline_hash === 'string' && SHA256_PATTERN.test(identity.cmdline_hash));
+}
+function isComparableProcessIdentity(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const identity = value;
+    return isNodePlatform(identity.platform)
+        && typeof identity.birth === 'string'
+        && identity.birth.length > 0
+        && (identity.cmdline_hash === undefined
+            || typeof identity.cmdline_hash === 'string' && SHA256_PATTERN.test(identity.cmdline_hash));
+}
+function observeLinuxProcess(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return { kind: 'error' };
+    const identity = readLinuxProcessIdentity(pid);
+    if (identity) {
+        const cmdlineHash = hashCmdline(identity.cmdline);
+        return {
+            kind: 'identity',
+            identity: {
+                platform: 'linux',
+                birth: String(identity.startTicks),
+                ...(cmdlineHash ? { cmdline_hash: cmdlineHash } : {}),
+            },
+        };
+    }
+    let statContent;
     try {
-        process.kill(pid, 0);
-        return true;
+        statContent = readFileSync(`/proc/${pid}/stat`, 'utf8');
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code === 'ENOENT' || code === 'ESRCH')
+            return { kind: 'gone' };
+        if (code === 'EACCES' || code === 'EPERM')
+            return { kind: 'denied' };
+        return { kind: 'error' };
+    }
+    if (!statContent)
+        return { kind: 'error' };
+    const probe = defaultProbePid(pid);
+    if (probe === 'dead')
+        return { kind: 'gone' };
+    if (probe === 'indeterminate')
+        return { kind: 'denied' };
+    return { kind: 'error' };
+}
+function parseProcessIdentityOutput(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return { kind: 'error' };
+        const value = parsed;
+        const keys = Object.keys(value);
+        const outcome = value.outcome;
+        if (outcome !== undefined) {
+            if (typeof outcome !== 'string')
+                return { kind: 'error' };
+            if (outcome === 'gone' || outcome === 'denied' || outcome === 'unsupported') {
+                if (keys.length !== 1)
+                    return { kind: 'error' };
+                if (outcome === 'gone')
+                    return { kind: 'gone' };
+                if (outcome === 'denied')
+                    return { kind: 'denied' };
+                return { kind: 'unsupported' };
+            }
+            if (outcome === 'error')
+                return { kind: 'error' };
+            return { kind: 'error' };
+        }
+        if (keys.some((key) => key !== 'platform' && key !== 'birth' && key !== 'cmdline')) {
+            return { kind: 'error' };
+        }
+        const platform = value.platform;
+        const birth = value.birth;
+        if (!isNodePlatform(platform) || !isValidBirth(birth))
+            return { kind: 'error' };
+        if (value.cmdline !== undefined && typeof value.cmdline !== 'string')
+            return { kind: 'error' };
+        const cmdlineHash = hashCmdline(value.cmdline);
+        return {
+            kind: 'identity',
+            identity: {
+                platform,
+                birth,
+                ...(cmdlineHash ? { cmdline_hash: cmdlineHash } : {}),
+            },
+        };
     }
     catch {
-        return false;
+        return { kind: 'error' };
     }
 }
 /**
@@ -250,22 +434,122 @@ function defaultIsPidAlive(pid) {
 export function isSessionStale(state, options = {}) {
     if (!Number.isInteger(state.pid) || state.pid <= 0)
         return true;
-    const isPidAlive = options.isPidAlive ?? defaultIsPidAlive;
-    if (!isPidAlive(state.pid))
-        return true;
-    const platform = options.platform ?? process.platform;
-    if (platform !== 'linux')
-        return false;
-    const liveIdentity = (options.readLinuxIdentity ?? readLinuxProcessIdentity)(state.pid);
-    if (!liveIdentity || typeof state.pid_start_ticks !== 'number')
-        return true;
-    if (state.pid_start_ticks !== liveIdentity.startTicks)
-        return true;
-    const expectedCmdline = normalizeCmdline(state.pid_cmdline);
-    if (!expectedCmdline)
-        return false;
-    const liveCmdline = normalizeCmdline(liveIdentity.cmdline);
-    return !liveCmdline || liveCmdline !== expectedCmdline;
+    const runtimePlatform = options.platform ?? transactionDependencies.runtimePlatform ?? process.platform;
+    const probePid = options.probePid ?? (options.isPidAlive
+        ? (pid) => options.isPidAlive(pid) ? 'alive' : 'dead'
+        : transactionDependencies.probePid);
+    const observeProcess = options.observeProcess ?? (options.readLinuxIdentity
+        ? (pid, platform) => {
+            if (platform !== 'linux')
+                return { kind: 'unsupported' };
+            const identity = options.readLinuxIdentity(pid);
+            if (!identity)
+                return { kind: 'error' };
+            const cmdlineHash = hashCmdline(identity.cmdline);
+            return {
+                kind: 'identity',
+                identity: {
+                    platform: 'linux',
+                    birth: String(identity.startTicks),
+                    ...(cmdlineHash ? { cmdline_hash: cmdlineHash } : {}),
+                },
+            };
+        }
+        : transactionDependencies.observeProcess);
+    const dependencies = {
+        ...transactionDependencies,
+        runtimePlatform,
+        probePid,
+        observeProcess,
+    };
+    return classifySessionProcess(state, dependencies) !== 'usable';
+}
+function safeObserve(provider, pid, runtimePlatform) {
+    try {
+        return provider.observeProcess(pid, runtimePlatform);
+    }
+    catch {
+        return { kind: 'error' };
+    }
+}
+function compareObservation(recorded, observation, runtimePlatform) {
+    if (!observation || typeof observation !== 'object' || observation.kind !== 'identity') {
+        return 'identity-unavailable';
+    }
+    const identity = observation.identity;
+    if (!isComparableProcessIdentity(identity) || identity.platform !== runtimePlatform) {
+        return 'identity-unavailable';
+    }
+    if (identity.birth !== recorded.birth)
+        return 'birth-mismatch-retryable';
+    if (recorded.cmdline_hash !== undefined && identity.cmdline_hash !== recorded.cmdline_hash) {
+        return 'identity-unavailable';
+    }
+    return 'match';
+}
+/** Compare recorded process birth evidence with a fresh provider observation. */
+export function classifyRecordedIdentity(recorded, runtimePlatform, provider, pid) {
+    if (!isComparableProcessIdentity(recorded) || recorded.platform !== runtimePlatform || !Number.isInteger(pid) || pid <= 0) {
+        return { status: 'identity-unavailable' };
+    }
+    let probe;
+    try {
+        probe = provider.probePid(pid);
+    }
+    catch {
+        return { status: 'identity-unavailable' };
+    }
+    if (probe === 'dead')
+        return { status: 'gone' };
+    if (probe !== 'alive')
+        return { status: 'identity-unavailable' };
+    const first = compareObservation(recorded, safeObserve(provider, pid, runtimePlatform), runtimePlatform);
+    if (first === 'birth-mismatch-retryable') {
+        const second = compareObservation(recorded, safeObserve(provider, pid, runtimePlatform), runtimePlatform);
+        if (second === 'match')
+            return { status: 'match' };
+        if (second === 'birth-mismatch-retryable' || second === 'birth-mismatch')
+            return { status: 'birth-mismatch' };
+        return { status: 'identity-unavailable' };
+    }
+    if (first === 'match')
+        return { status: 'match' };
+    if (first === 'birth-mismatch')
+        return { status: 'birth-mismatch' };
+    return { status: 'identity-unavailable' };
+}
+function recordedIdentityForState(state, runtimePlatform) {
+    if (state.identity_schema_version !== undefined && state.identity_schema_version !== 2)
+        return 'invalid';
+    if (state.process_identity !== undefined) {
+        if (state.identity_schema_version !== 2 || !isValidProcessIdentity(state.process_identity))
+            return 'invalid';
+        if (state.platform !== undefined && state.platform !== state.process_identity.platform)
+            return 'invalid';
+        return state.process_identity;
+    }
+    if (state.identity_schema_version === 2)
+        return 'invalid';
+    const recordedPlatform = state.platform ?? runtimePlatform;
+    if (recordedPlatform === 'linux' && isValidStartTicks(state.pid_start_ticks)) {
+        const cmdlineHash = hashCmdline(state.pid_cmdline);
+        return {
+            platform: 'linux',
+            birth: String(state.pid_start_ticks),
+            ...(cmdlineHash ? { cmdline_hash: cmdlineHash } : {}),
+        };
+    }
+    return null;
+}
+function probeIdentitylessProcess(pid, dependencies) {
+    let probe;
+    try {
+        probe = dependencies.probePid(pid);
+    }
+    catch {
+        return 'identity-indeterminate';
+    }
+    return probe === 'dead' ? 'stale-dead' : 'identity-indeterminate';
 }
 export function isSessionStateAuthoritativeForCwd(state, cwd) {
     if (!normalizeSessionId(state.session_id))
@@ -285,54 +569,47 @@ export function isSessionStateUsable(state, cwd, options = {}) {
     if (typeof state.cwd === 'string' && state.cwd.trim() && !isSessionStateAuthoritativeForCwd(state, cwd))
         return false;
     const hasPidMetadata = Number.isInteger(state.pid) && state.pid > 0;
-    const hasLinuxIdentityMetadata = typeof state.pid_start_ticks === 'number'
-        || typeof state.pid_cmdline === 'string';
-    return !hasPidMetadata && !hasLinuxIdentityMetadata || !isSessionStale(state, options);
+    const hasIdentityMetadata = typeof state.pid_start_ticks === 'number'
+        || typeof state.pid_cmdline === 'string'
+        || state.identity_schema_version !== undefined
+        || state.process_identity !== undefined;
+    return !hasPidMetadata && !hasIdentityMetadata || !isSessionStale(state, options);
 }
 function isValidStartTicks(value) {
     return typeof value === 'number' && Number.isInteger(value) && value >= 0;
 }
 function classifySessionProcess(state, dependencies) {
     const hasPidMetadata = Number.isInteger(state.pid) && state.pid > 0;
-    const hasIdentityMetadata = typeof state.pid_start_ticks === 'number' || typeof state.pid_cmdline === 'string';
+    const hasIdentityMetadata = typeof state.pid_start_ticks === 'number'
+        || typeof state.pid_cmdline === 'string'
+        || state.identity_schema_version !== undefined
+        || state.process_identity !== undefined;
     if (!hasPidMetadata && !hasIdentityMetadata)
         return 'usable';
     if (!hasPidMetadata)
         return 'identity-indeterminate';
-    let pidStatus;
-    try {
-        pidStatus = dependencies.probePid(state.pid);
-    }
-    catch {
-        return 'identity-indeterminate';
-    }
-    if (pidStatus === 'dead')
-        return 'stale-dead';
-    if (pidStatus !== 'alive')
-        return 'identity-indeterminate';
-    const platform = state.platform ?? process.platform;
-    if (platform !== 'linux')
-        return 'usable';
-    if (!isValidStartTicks(state.pid_start_ticks))
-        return 'identity-indeterminate';
-    let liveIdentity;
-    try {
-        liveIdentity = dependencies.readProcessIdentity(state.pid, platform);
-    }
-    catch {
-        return 'identity-indeterminate';
-    }
-    if (!liveIdentity || !isValidStartTicks(liveIdentity.startTicks))
-        return 'identity-indeterminate';
-    if (liveIdentity.startTicks !== state.pid_start_ticks)
-        return 'stale-dead';
-    if (liveIdentity.status !== 'matching')
-        return 'identity-indeterminate';
-    const expectedCmdlineHash = hashCmdline(state.pid_cmdline);
-    if (expectedCmdlineHash && liveIdentity.cmdlineHash !== expectedCmdlineHash) {
+    const runtimePlatform = dependencies.runtimePlatform;
+    const recorded = recordedIdentityForState(state, runtimePlatform);
+    if (recorded === 'invalid')
         return 'identity-indeterminate';
+    if (!recorded)
+        return probeIdentitylessProcess(state.pid, dependencies);
+    const classification = classifyRecordedIdentity(recorded, runtimePlatform, dependencies, state.pid);
+    switch (classification.status) {
+        case 'match': return 'usable';
+        case 'gone':
+        case 'birth-mismatch': return 'stale-dead';
+        case 'identity-unavailable': return 'identity-indeterminate';
     }
-    return 'usable';
+}
+/**
+ * Classify process liveness for an already-parsed selected session pointer.
+ * Callers that need cwd/state_root authority must validate those against the
+ * SAME snapshot themselves; this evaluates only pid/start-tick evidence so a
+ * single immutable snapshot can drive both decisions.
+ */
+export function classifySessionStateLiveness(state) {
+    return classifySessionProcess(state, transactionDependencies);
 }
 function classifyParsedSessionPointer(context, value, raw) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
@@ -344,6 +621,16 @@ function classifyParsedSessionPointer(context, value, raw) {
     if (typeof state.cwd === 'string' && state.cwd.trim() && !isSessionStateAuthoritativeForCwd(state, context.cwd)) {
         return { status: 'foreign-cwd', raw, state };
     }
+    if (state.identity_schema_version !== undefined && state.identity_schema_version !== 2)
+        return { status: 'identity-indeterminate', raw, state };
+    if (state.process_identity !== undefined
+        && (state.identity_schema_version !== 2
+            || !isValidProcessIdentity(state.process_identity)
+            || state.platform !== undefined && state.platform !== state.process_identity.platform)) {
+        return { status: 'malformed', raw, state };
+    }
+    if (state.identity_schema_version === 2 && state.process_identity === undefined)
+        return { status: 'malformed', raw, state };
     const processStatus = classifySessionProcess(state, transactionDependencies);
     return { status: processStatus, state, raw };
 }
@@ -382,9 +669,9 @@ export async function readUsableSessionStateFromContext(context) {
     return state && isSessionStateUsable(state, context.cwd) ? state : null;
 }
 /** Read current session state from the exact selected root. */
-export async function readSessionState(cwd) {
+export async function readSessionState(cwd, env = process.env) {
     try {
-        return await readSessionStateFromContext(resolveSessionPointerContext(cwd));
+        return await readSessionStateFromContext(resolveSessionPointerContext(cwd, env));
     }
     catch {
         return null;
@@ -400,7 +687,7 @@ export async function readUsableSessionState(cwd, options = {}) {
         return null;
     }
 }
-function createSessionState(cwd, sessionId, pid, platform, linuxIdentity, options = {}) {
+function createSessionState(cwd, stateRoot, sessionId, pid, platform, identity, options = {}) {
     const nowIso = options.nowIso ?? new Date().toISOString();
     const nativeSessionId = normalizeNonempty(options.nativeSessionId);
     const previousNativeSessionId = normalizeNonempty(options.previousNativeSessionId);
@@ -408,6 +695,27 @@ function createSessionState(cwd, sessionId, pid, platform, linuxIdentity, option
     const ownerOmxSessionId = normalizeSessionId(options.ownerOmxSessionId);
     const tmuxSessionName = normalizeNonempty(options.tmuxSessionName);
     const tmuxPaneId = normalizeNonempty(options.tmuxPaneId);
+    const processIdentity = identity && 'birth' in identity
+        ? identity
+        : identity
+            ? {
+                platform: 'linux',
+                birth: String(identity.startTicks),
+                ...(hashCmdline(identity.cmdline) ? { cmdline_hash: hashCmdline(identity.cmdline) } : {}),
+            }
+            : undefined;
+    const publishIdentity = processIdentity && isValidProcessIdentity(processIdentity) && processIdentity.platform === platform
+        ? processIdentity
+        : undefined;
+    const legacyStartTicks = identity && 'startTicks' in identity
+        ? identity.startTicks
+        : publishIdentity?.platform === 'linux' && Number.isSafeInteger(Number(publishIdentity.birth))
+            ? Number(publishIdentity.birth)
+            : undefined;
+    const legacyLinuxIdentity = publishIdentity?.platform === 'linux' && publishIdentity.birth === String(legacyStartTicks)
+        ? readLinuxProcessIdentity(pid)
+        : null;
+    const legacyCmdline = identity && 'cmdline' in identity ? identity.cmdline : legacyLinuxIdentity?.cmdline;
     return {
         session_id: sessionId,
         ...(nativeSessionId ? { native_session_id: nativeSessionId } : {}),
@@ -415,15 +723,23 @@ function createSessionState(cwd, sessionId, pid, platform, linuxIdentity, option
         ...(nativeSessionSwitchedAt ? { native_session_switched_at: nativeSessionSwitchedAt } : {}),
         ...(ownerOmxSessionId ? { owner_omx_session_id: ownerOmxSessionId } : {}),
         started_at: options.startedAt ?? nowIso,
+        ...(isValidToken(options.launchLineageToken) ? { launch_lineage_token: options.launchLineageToken } : {}),
         cwd,
+        state_root: stateRoot,
         pid,
         platform,
-        ...(linuxIdentity ? { pid_start_ticks: linuxIdentity.startTicks } : {}),
-        ...(linuxIdentity?.cmdline ? { pid_cmdline: linuxIdentity.cmdline } : {}),
+        ...(publishIdentity ? { identity_schema_version: 2, process_identity: publishIdentity } : {}),
+        ...(legacyStartTicks !== undefined ? { pid_start_ticks: legacyStartTicks } : {}),
+        ...(legacyCmdline ? { pid_cmdline: legacyCmdline } : {}),
         ...(tmuxSessionName ? { tmux_session_name: tmuxSessionName } : {}),
         ...(tmuxPaneId ? { tmux_pane_id: tmuxPaneId } : {}),
     };
 }
+function preserveExistingLaunchLineageToken(existing, state) {
+    return existing && Object.hasOwn(existing, 'launch_lineage_token')
+        ? { ...state, launch_lineage_token: existing.launch_lineage_token }
+        : state;
+}
 function normalizeNonempty(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
@@ -431,7 +747,15 @@ function resolvePid(options) {
     return Number.isInteger(options.pid) && options.pid && options.pid > 0 ? options.pid : process.pid;
 }
 function sessionIdentityFor(pid, platform) {
-    return platform === 'linux' ? readLinuxProcessIdentity(pid) : null;
+    try {
+        const observation = transactionDependencies.observeProcess(pid, platform);
+        return observation.kind === 'identity' && isValidProcessIdentity(observation.identity) && observation.identity.platform === platform
+            ? observation.identity
+            : null;
+    }
+    catch {
+        return null;
+    }
 }
 function currentOwnerAlias(state) {
     return normalizeSessionId(state.owner_omx_session_id);
@@ -458,29 +782,38 @@ function isStartCompatible(existing, requestedSessionId) {
         || existing.native_session_id === requestedSessionId
         || currentOwnerAlias(existing) === requestedSessionId;
 }
-function getOmxLaunchSessionId(state) {
-    if (state.session_id.startsWith('omx-'))
-        return state.session_id;
-    const owner = currentOwnerAlias(state);
-    return owner?.startsWith('omx-') ? owner : undefined;
-}
 function parseLockOwner(raw) {
     try {
-        const value = JSON.parse(raw);
-        if (!value || typeof value !== 'object' || Array.isArray(value))
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
             return null;
-        if (value.version !== 1 || !isValidToken(value.token) || typeof value.pid !== 'number' || !Number.isInteger(value.pid) || value.pid <= 0)
+        const value = parsed;
+        if (!isValidToken(value.token) || typeof value.pid !== 'number' || !Number.isInteger(value.pid) || value.pid <= 0)
             return null;
-        if (typeof value.platform !== 'string' || !value.platform || typeof value.created_at !== 'string' || !value.created_at) {
+        if (!isNodePlatform(value.platform) || typeof value.created_at !== 'string' || !value.created_at)
             return null;
+        if (value.version === 1) {
+            if (value.pid_start_ticks !== undefined && !isValidStartTicks(value.pid_start_ticks))
+                return null;
+            if (value.pid_cmdline_hash !== undefined
+                && (typeof value.pid_cmdline_hash !== 'string' || !SHA256_PATTERN.test(value.pid_cmdline_hash))) {
+                return null;
+            }
+            return value;
         }
-        if (value.pid_start_ticks !== undefined && !isValidStartTicks(value.pid_start_ticks))
-            return null;
-        if (value.pid_cmdline_hash !== undefined
-            && (typeof value.pid_cmdline_hash !== 'string' || !SHA256_PATTERN.test(value.pid_cmdline_hash))) {
-            return null;
+        if (value.version === 2) {
+            const processIdentity = value.process_identity;
+            if (!isValidProcessIdentity(processIdentity) || processIdentity.platform !== value.platform)
+                return null;
+            if (value.pid_start_ticks !== undefined && !isValidStartTicks(value.pid_start_ticks))
+                return null;
+            if (value.pid_cmdline_hash !== undefined
+                && (typeof value.pid_cmdline_hash !== 'string' || !SHA256_PATTERN.test(value.pid_cmdline_hash))) {
+                return null;
+            }
+            return value;
         }
-        return value;
+        return null;
     }
     catch {
         return null;
@@ -489,6 +822,17 @@ function parseLockOwner(raw) {
 function isValidToken(value) {
     return typeof value === 'string' && SESSION_POINTER_TOKEN_PATTERN.test(value);
 }
+function recordedIdentityForLockOwner(owner) {
+    if (owner.version === 2)
+        return owner.process_identity;
+    if (owner.platform !== 'linux' || !isValidStartTicks(owner.pid_start_ticks))
+        return null;
+    return {
+        platform: 'linux',
+        birth: String(owner.pid_start_ticks),
+        ...(owner.pid_cmdline_hash ? { cmdline_hash: owner.pid_cmdline_hash } : {}),
+    };
+}
 async function inspectLockOwnerFile(ownerPath, missingStatus = 'missing') {
     let raw;
     try {
@@ -500,38 +844,26 @@ async function inspectLockOwnerFile(ownerPath, missingStatus = 'missing') {
     const owner = parseLockOwner(raw);
     if (!owner)
         return { status: 'malformed' };
-    let pidStatus;
-    try {
-        pidStatus = transactionDependencies.probePid(owner.pid);
-    }
-    catch {
-        return { status: 'identity-indeterminate', owner };
-    }
-    if (pidStatus === 'dead')
-        return { status: 'dead', owner };
-    if (pidStatus !== 'alive')
-        return { status: 'identity-indeterminate', owner };
-    if (owner.platform !== 'linux' || !isValidStartTicks(owner.pid_start_ticks)) {
-        return { status: 'identity-indeterminate', owner };
-    }
-    let liveIdentity;
-    try {
-        liveIdentity = transactionDependencies.readProcessIdentity(owner.pid, owner.platform);
-    }
-    catch {
-        return { status: 'identity-indeterminate', owner };
-    }
-    if (!liveIdentity || !isValidStartTicks(liveIdentity.startTicks)) {
-        return { status: 'identity-indeterminate', owner };
+    const recorded = recordedIdentityForLockOwner(owner);
+    if (!recorded) {
+        let probe;
+        try {
+            probe = transactionDependencies.probePid(owner.pid);
+        }
+        catch {
+            return { status: 'identity-indeterminate', owner };
+        }
+        return probe === 'dead'
+            ? { status: 'dead', owner }
+            : { status: 'identity-indeterminate', owner };
     }
-    if (liveIdentity.startTicks !== owner.pid_start_ticks)
-        return { status: 'reused', owner };
-    if (liveIdentity.status !== 'matching')
-        return { status: 'identity-indeterminate', owner };
-    if (owner.pid_cmdline_hash && owner.pid_cmdline_hash !== liveIdentity.cmdlineHash) {
-        return { status: 'identity-indeterminate', owner };
+    const classification = classifyRecordedIdentity(recorded, transactionDependencies.runtimePlatform, transactionDependencies, owner.pid);
+    switch (classification.status) {
+        case 'match': return { status: 'live', owner };
+        case 'gone': return { status: 'dead', owner };
+        case 'birth-mismatch': return { status: 'reused', owner };
+        case 'identity-unavailable': return { status: 'identity-indeterminate', owner };
     }
-    return { status: 'live', owner };
 }
 async function inspectLockOwner(lockPath) {
     return await inspectLockOwnerFile(join(lockPath, 'owner.json'));
@@ -586,124 +918,292 @@ async function inspectSessionPointerLockAtContext(context) {
         status,
         lockPath: context.lockPath,
         evidenceSource,
-        safeToRecover: status === 'dead' && evidenceSource === 'owner-temp',
+        // Recoverable only on positively dead evidence (ESRCH), for canonical
+        // owner.json and pre-rename temp evidence alike; the atomic
+        // claim/quarantine protocol revalidates the exact entry, still-dead
+        // status, and owner token before quarantining. Live, reused,
+        // identity-indeterminate, ambiguous, symlink, malformed, unexpected,
+        // and io-error states stay fail-closed.
+        safeToRecover: status === 'dead',
     };
 }
 /** Inspect only exact, regular owner evidence in the selected pointer lock. */
 export async function inspectSessionPointerLock(cwd) {
     return await inspectSessionPointerLockAtContext(resolveSessionPointerContext(cwd));
 }
-/** Explicitly quarantine only a dead, atomically claimed pointer lock; never force recovery. */
-export async function recoverSessionPointerLock(cwd) {
-    const context = resolveSessionPointerContext(cwd);
-    const inspection = await inspectSessionPointerLockAtContext(context);
-    if (!inspection.safeToRecover) {
-        return { ...inspection, action: 'none', recovered: false, reason: inspection.status === 'absent' ? 'No session pointer lock exists.' : `Session pointer lock is not safe to recover (${inspection.status}).` };
-    }
-    let entries;
+function sameRecoveryIdentity(stat, identity, kind) {
+    return !stat.isSymbolicLink() && (kind === 'file' ? stat.isFile() : stat.isDirectory()) && stat.dev === identity.dev && stat.ino === identity.ino;
+}
+async function lstatRecoveryPath(path) {
     try {
-        entries = await transactionDependencies.fs.readdir(context.lockPath);
-    }
-    catch {
-        return { ...inspection, action: 'none', recovered: false, reason: 'Unable to re-read session pointer lock evidence.' };
-    }
-    const evidenceName = inspection.evidenceSource === 'owner.json' ? 'owner.json' : entries.find((entry) => /^owner\.([A-Za-z0-9_-]{16,128})\.tmp$/.test(entry));
-    if (!evidenceName || entries.length !== 1) {
-        return { ...inspection, action: 'none', recovered: false, reason: 'Session pointer lock evidence changed before recovery claim.' };
+        return await transactionDependencies.fs.lstat(path);
     }
-    const owner = await inspectLockOwnerFile(join(context.lockPath, evidenceName));
-    if (owner.status !== 'dead' || !owner.owner) {
-        return { ...inspection, action: 'none', recovered: false, reason: 'Session pointer lock evidence changed before recovery claim.' };
+    catch (error) {
+        if (isNotFound(error))
+            return undefined;
+        throw error;
     }
-    let claimToken;
+}
+async function probeRecoveryRenameCapability() {
+    let probeDir;
     try {
-        claimToken = transactionDependencies.token();
+        probeDir = await nodeMkdtemp(join(tmpdir(), 'omx-session-recovery-probe-'));
+        const from = join(probeDir, 'from');
+        const to = join(probeDir, 'to');
+        await nodeWriteFile(from, 'omx-recovery-capability-probe', { flag: 'wx' });
+        const outcome = await transactionDependencies.atomicRenameNoReplace(from, to);
+        return outcome === 'moved' || outcome === 'not-moved' || outcome === 'unsupported'
+            ? outcome
+            : 'unsupported';
     }
     catch {
-        return { ...inspection, action: 'none', recovered: false, reason: 'Unable to create recovery claim token.' };
+        return 'unsupported';
     }
-    if (!isValidToken(claimToken))
-        return { ...inspection, action: 'none', recovered: false, reason: 'Recovery claim token is invalid.' };
-    const claimName = `owner.${owner.owner.token}.${claimToken}.recovery`;
-    const claimPath = join(context.lockPath, claimName);
+    finally {
+        if (probeDir) {
+            try {
+                await rm(probeDir, { recursive: true, force: true });
+            }
+            catch { /* best effort */ }
+        }
+    }
+}
+async function moveRecoveryPathNoReplace(from, to, identity, kind) {
     try {
-        await transactionDependencies.fs.lstat(claimPath);
-        return { ...inspection, action: 'none', recovered: false, reason: 'Recovery claim path already exists.' };
+        const outcome = await transactionDependencies.atomicRenameNoReplace(from, to);
+        if (outcome === 'unsupported')
+            return { moved: false, unsupported: true, reason: 'Atomic no-replace recovery rename is unsupported on this platform.' };
+        if (outcome === 'not-moved')
+            return { moved: false, reason: 'Atomic recovery move left its source pathname in place.' };
     }
     catch (error) {
-        if (!isNotFound(error))
-            return { ...inspection, action: 'none', recovered: false, reason: 'Unable to inspect recovery claim path.' };
-    }
-    try {
-        await transactionDependencies.fs.rename(join(context.lockPath, evidenceName), claimPath);
+        return { moved: false, reason: `Atomic no-replace recovery rename failed (${errorCode(error) ?? 'unknown'}).` };
+    }
+    const destination = await lstatRecoveryPath(to);
+    const source = await lstatRecoveryPath(from);
+    if (destination && sameRecoveryIdentity(destination, identity, kind) && !source)
+        return { moved: true };
+    // A successor may have appeared at the canonical pathname after our move.
+    // Attempt a no-replace rollback only for the captured object; an occupied or
+    // foreign destination makes the rollback fail closed and leaves both residues.
+    if (destination && sameRecoveryIdentity(destination, identity, kind)) {
+        try {
+            await transactionDependencies.atomicRenameNoReplace(to, from);
+        }
+        catch { /* durable residue is safer than cleanup */ }
     }
-    catch {
-        return { ...inspection, action: 'none', recovered: false, reason: 'Session pointer lock evidence changed before recovery claim.' };
+    return { moved: false, reason: 'Atomic recovery move did not leave the captured object at its token-bound destination.' };
+}
+async function completeRecoveryCheckpoint(checkpointPath, checkpointBytes, checkpointIdentity) {
+    const completedPath = checkpointPath.replace(/\.json$/, '.completed');
+    const current = await lstatRecoveryPath(checkpointPath);
+    if (!current || !sameRecoveryIdentity(current, checkpointIdentity, 'file') || await transactionDependencies.fs.readFile(checkpointPath, 'utf8') !== checkpointBytes) {
+        return { completed: false, reason: 'Recovery checkpoint was replaced before completion; it was preserved as residue.' };
     }
-    const claimed = await inspectSessionPointerLockAtContext(context);
-    let claimedEntries;
+    const moved = await moveRecoveryPathNoReplace(checkpointPath, completedPath, checkpointIdentity, 'file');
+    if (!moved.moved)
+        return { completed: false, reason: moved.reason };
+    const completedBytes = await transactionDependencies.fs.readFile(completedPath, 'utf8');
+    return completedBytes === checkpointBytes ? { completed: true } : { completed: false, reason: 'Completed recovery receipt bytes changed and were preserved as residue.' };
+}
+async function resumeRecoveryCheckpoint(context, checkpointPath, checkpointName) {
+    const match = new RegExp(`^${basename(context.lockPath).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\.recovery\\.([A-Za-z0-9_-]{16,128})\\.([A-Za-z0-9_-]{16,128})\\.json$`).exec(checkpointName);
     try {
-        claimedEntries = await transactionDependencies.fs.readdir(context.lockPath);
-    }
-    catch {
-        return { ...claimed, action: 'none', recovered: false, reason: 'Unable to revalidate recovery claim.' };
+        const checkpointBytes = await transactionDependencies.fs.readFile(checkpointPath, 'utf8');
+        const checkpointStat = await transactionDependencies.fs.lstat(checkpointPath);
+        const checkpoint = JSON.parse(checkpointBytes);
+        const ownerToken = match?.[1];
+        const recoveryToken = match?.[2];
+        const expectedSource = ownerToken && (checkpoint.sourcePath === join(context.lockPath, 'owner.json') || checkpoint.sourcePath === join(context.lockPath, `owner.${ownerToken}.tmp`));
+        const expectedPark = `${context.lockPath}.parked-lock-${recoveryToken}`;
+        const isLegacyV1 = checkpoint.version === 1 && checkpoint.lockIdentity === undefined && checkpoint.lockParkPath === undefined;
+        if (!match || !expectedSource || !checkpoint.identity || !['evidence-pending', 'evidence-quarantined', 'directory-pending'].includes(checkpoint.phase) || ![1, 2, 3].includes(checkpoint.version) || !isLegacyV1 && checkpoint.lockParkPath !== expectedPark || !sameRecoveryIdentity(checkpointStat, { dev: checkpointStat.dev, ino: checkpointStat.ino }, 'file'))
+            throw new Error('invalid checkpoint');
+        const lockParkPath = checkpoint.lockParkPath ?? expectedPark;
+        const evidenceIdentity = checkpoint.evidenceIdentity ?? checkpoint.identity;
+        const claimPath = join(context.lockPath, `owner.${ownerToken}.${recoveryToken}.recovery`);
+        const lock = await lstatRecoveryPath(context.lockPath);
+        const parkedLock = await lstatRecoveryPath(lockParkPath);
+        if (lock && parkedLock)
+            throw new Error('checkpoint lock paths are both present');
+        if (parkedLock) {
+            if (!checkpoint.lockIdentity || !sameRecoveryIdentity(parkedLock, checkpoint.lockIdentity, 'directory'))
+                throw new Error('checkpoint parked lock identity mismatch');
+            const quarantinePath = `${context.lockPath}.quarantine.${ownerToken}.${recoveryToken}`;
+            const completed = await completeRecoveryCheckpoint(checkpointPath, checkpointBytes, { dev: checkpointStat.dev, ino: checkpointStat.ino });
+            if (!completed.completed)
+                throw new Error(completed.reason);
+            return { status: 'dead', lockPath: context.lockPath, evidenceSource: 'owner.json', safeToRecover: true, action: 'quarantined', recovered: true, reason: 'Dead session pointer lock recovery checkpoint resumed.', quarantinePath };
+        }
+        if (!lock || lock.isSymbolicLink() || !lock.isDirectory())
+            throw new Error('checkpoint lock is missing or foreign');
+        const source = await lstatRecoveryPath(checkpoint.sourcePath);
+        const claim = await lstatRecoveryPath(claimPath);
+        const evidencePath = source && sameRecoveryIdentity(source, evidenceIdentity, 'file') ? checkpoint.sourcePath
+            : claim && sameRecoveryIdentity(claim, evidenceIdentity, 'file') ? claimPath : undefined;
+        if (!evidencePath)
+            throw new Error('checkpoint evidence is missing or foreign');
+        if (claim && !sameRecoveryIdentity(claim, evidenceIdentity, 'file'))
+            throw new Error('checkpoint claim is foreign');
+        // v1/v2 did not persist the directory identity. It is safe to derive only
+        // while the original directory still contains the exact recorded evidence.
+        const lockIdentity = checkpoint.lockIdentity ?? { dev: lock.dev, ino: lock.ino };
+        if (!sameRecoveryIdentity(lock, lockIdentity, 'directory'))
+            throw new Error('checkpoint lock identity mismatch');
+        const ownerBytes = await transactionDependencies.fs.readFile(evidencePath, 'utf8');
+        const owner = await inspectLockOwnerFile(evidencePath);
+        if (owner.status !== 'dead' || owner.owner?.token !== ownerToken || checkpoint.evidenceBytes !== undefined && checkpoint.evidenceBytes !== ownerBytes)
+            throw new Error('checkpoint owner evidence changed');
+        const quarantinePath = `${context.lockPath}.quarantine.${ownerToken}.${recoveryToken}`;
+        const quarantine = await lstatRecoveryPath(quarantinePath);
+        if (quarantine) {
+            if (!sameRecoveryIdentity(quarantine, evidenceIdentity, 'file'))
+                throw new Error('checkpoint quarantine is foreign');
+        }
+        else {
+            await transactionDependencies.fs.link(evidencePath, quarantinePath);
+            const linked = await lstatRecoveryPath(quarantinePath);
+            if (!linked || !sameRecoveryIdentity(linked, evidenceIdentity, 'file'))
+                throw new Error('checkpoint quarantine link mismatch');
+        }
+        // Revalidate the bytes, dead owner and identities immediately before moving
+        // the entire directory incarnation out of the canonical lock pathname.
+        const currentLock = await lstatRecoveryPath(context.lockPath);
+        const currentEvidence = await lstatRecoveryPath(evidencePath);
+        const currentBytes = currentEvidence && sameRecoveryIdentity(currentEvidence, evidenceIdentity, 'file') ? await transactionDependencies.fs.readFile(evidencePath, 'utf8') : undefined;
+        const currentOwner = currentBytes === undefined ? undefined : await inspectLockOwnerFile(evidencePath);
+        if (!currentLock || !sameRecoveryIdentity(currentLock, lockIdentity, 'directory') || currentBytes !== ownerBytes || currentOwner?.status !== 'dead' || currentOwner.owner?.token !== ownerToken)
+            throw new Error('checkpoint owner evidence changed before directory quarantine');
+        const lockEntries = await transactionDependencies.fs.readdir(context.lockPath);
+        const allowedEntries = new Set([basename(checkpoint.sourcePath), basename(claimPath)]);
+        if (lockEntries.some((entry) => !allowedEntries.has(entry)))
+            throw new Error('checkpoint lock contains foreign recovery evidence');
+        const moved = await moveRecoveryPathNoReplace(context.lockPath, lockParkPath, lockIdentity, 'directory');
+        if (!moved.moved)
+            throw new Error(moved.reason);
+        const completed = await completeRecoveryCheckpoint(checkpointPath, checkpointBytes, { dev: checkpointStat.dev, ino: checkpointStat.ino });
+        if (!completed.completed)
+            throw new Error(completed.reason);
+        return { status: 'dead', lockPath: context.lockPath, evidenceSource: 'owner.json', safeToRecover: true, action: 'quarantined', recovered: true, reason: 'Dead session pointer lock recovered into durable quarantine residues.', quarantinePath };
     }
-    const claimOwner = await inspectLockOwnerFile(claimPath);
-    if (claimedEntries.length !== 1 || claimedEntries[0] !== claimName || claimOwner.status !== 'dead' || claimOwner.owner?.token !== owner.owner.token || claimed.status !== 'unexpected') {
-        return { ...claimed, action: 'none', recovered: false, reason: 'Recovery claim revalidation failed.' };
+    catch (error) {
+        const detail = error instanceof Error ? error.message : 'unknown';
+        return { status: 'unexpected', lockPath: context.lockPath, evidenceSource: 'none', safeToRecover: false, action: 'none', recovered: false, reason: `Recovery checkpoint is malformed or no longer identifies its recorded recovery state (${detail}).` };
     }
-    const quarantinePath = `${context.lockPath}.quarantine.${owner.owner.token}.${claimToken}`;
+}
+/** Explicitly quarantine only a dead lock by moving its entire directory incarnation. */
+export async function recoverSessionPointerLock(cwd) {
+    const context = resolveSessionPointerContext(cwd);
+    const checkpointPrefix = `${basename(context.lockPath)}.recovery.`;
+    let checkpointNames;
     try {
-        await transactionDependencies.fs.lstat(quarantinePath);
-        return { ...claimed, action: 'none', recovered: false, reason: 'Recovery quarantine path already exists.' };
+        checkpointNames = (await transactionDependencies.fs.readdir(dirname(context.lockPath))).filter((name) => name.startsWith(checkpointPrefix) && name.endsWith('.json'));
     }
     catch (error) {
         if (!isNotFound(error))
-            return { ...claimed, action: 'none', recovered: false, reason: 'Unable to inspect recovery quarantine path.' };
-    }
-    try {
-        await transactionDependencies.fs.rename(claimPath, quarantinePath);
-    }
-    catch {
-        return { ...claimed, action: 'none', recovered: false, reason: 'Unable to quarantine the exact session pointer recovery claim.' };
+            return { status: 'io-error', lockPath: context.lockPath, evidenceSource: 'none', safeToRecover: false, action: 'none', recovered: false, reason: 'Unable to enumerate session pointer recovery checkpoints.' };
+        checkpointNames = [];
     }
+    if (checkpointNames.length > 1)
+        return { status: 'unexpected', lockPath: context.lockPath, evidenceSource: 'none', safeToRecover: false, action: 'none', recovered: false, reason: 'Multiple recovery checkpoints exist.' };
+    if (checkpointNames.length === 1)
+        return await resumeRecoveryCheckpoint(context, join(dirname(context.lockPath), checkpointNames[0]), checkpointNames[0]);
+    const inspection = await inspectSessionPointerLockAtContext(context);
+    if (!inspection.safeToRecover)
+        return { ...inspection, action: 'none', recovered: false, reason: inspection.status === 'absent' ? 'No session pointer lock exists.' : `Session pointer lock is not safe to recover (${inspection.status}).` };
     try {
-        await transactionDependencies.fs.rmdir(context.lockPath);
-    }
-    catch (error) {
-        if (!isNotFound(error)) {
+        const evidenceName = inspection.evidenceSource === 'owner.json'
+            ? 'owner.json'
+            : (await transactionDependencies.fs.readdir(context.lockPath)).find((entry) => /^owner\.([A-Za-z0-9_-]{16,128})\.tmp$/.test(entry));
+        if (!evidenceName)
+            return { ...inspection, action: 'none', recovered: false, reason: 'Session pointer lock evidence changed before recovery claim.' };
+        const evidencePath = join(context.lockPath, evidenceName);
+        const evidence = await lstatRecoveryPath(evidencePath);
+        const lock = await lstatRecoveryPath(context.lockPath);
+        const ownerBytes = evidence && sameRecoveryIdentity(evidence, { dev: evidence.dev, ino: evidence.ino }, 'file')
+            ? await transactionDependencies.fs.readFile(evidencePath, 'utf8')
+            : undefined;
+        const owner = ownerBytes === undefined ? undefined : await inspectLockOwnerFile(evidencePath);
+        if (!lock || lock.isSymbolicLink() || !lock.isDirectory() || !evidence
+            || !sameRecoveryIdentity(evidence, { dev: evidence.dev, ino: evidence.ino }, 'file')
+            || owner?.status !== 'dead' || !owner.owner) {
+            return { ...inspection, action: 'none', recovered: false, reason: 'Session pointer lock evidence changed before recovery claim.' };
+        }
+        // Fresh recovery probes before checkpoint creation; an unsupported host leaves the
+        // canonical lock and owner evidence untouched. Existing checkpoints are resumed
+        // independently and may remain as durable recovery residue.
+        const capability = await probeRecoveryRenameCapability();
+        if (capability === 'unsupported') {
             return {
-                ...claimed,
+                ...inspection,
                 action: 'none',
                 recovered: false,
-                reason: 'The exact recovery claim was quarantined, but the canonical lock directory was not empty.',
-                quarantinePath,
+                reason: 'Atomic no-replace recovery rename is unsupported on this platform.',
             };
         }
+        const recoveryToken = transactionDependencies.token();
+        if (!isValidToken(recoveryToken))
+            return { ...inspection, action: 'none', recovered: false, reason: 'Recovery claim token is invalid.' };
+        const checkpointPath = `${context.lockPath}.recovery.${owner.owner.token}.${recoveryToken}.json`;
+        const checkpoint = {
+            version: 3,
+            sourcePath: evidencePath,
+            identity: { dev: evidence.dev, ino: evidence.ino },
+            evidenceIdentity: { dev: evidence.dev, ino: evidence.ino },
+            evidenceBytes: ownerBytes,
+            lockIdentity: { dev: lock.dev, ino: lock.ino },
+            lockParkPath: `${context.lockPath}.parked-lock-${recoveryToken}`,
+            phase: 'evidence-pending',
+        };
+        try {
+            await transactionDependencies.fs.writeFile(checkpointPath, JSON.stringify(checkpoint), { flag: 'wx' });
+        }
+        catch (error) {
+            return { ...inspection, action: 'none', recovered: false, reason: `Unable to create recovery checkpoint (${errorCode(error) ?? 'unknown'}).` };
+        }
+        return await resumeRecoveryCheckpoint(context, checkpointPath, basename(checkpointPath));
+    }
+    catch (error) {
+        return {
+            ...inspection,
+            status: 'io-error',
+            safeToRecover: false,
+            action: 'none',
+            recovered: false,
+            reason: `Unable to inspect session pointer lock recovery state (${errorCode(error) ?? errorMessage(error)}).`,
+        };
     }
-    return { ...inspection, action: 'quarantined', recovered: true, reason: 'Dead session pointer lock was atomically claimed and quarantined.', quarantinePath };
 }
 function buildLockOwner(token) {
-    let identity;
+    const runtimePlatform = transactionDependencies.runtimePlatform;
+    let observation;
     try {
-        identity = transactionDependencies.readProcessIdentity(process.pid, process.platform);
+        observation = transactionDependencies.observeProcess(process.pid, runtimePlatform);
     }
     catch {
         // Publication remains valid with optional identity metadata omitted.
     }
-    return {
-        version: 1,
+    const identity = observation?.kind === 'identity' && isValidProcessIdentity(observation.identity)
+        && observation.identity.platform === runtimePlatform
+        ? observation.identity
+        : undefined;
+    const legacyStartTicks = identity?.platform === 'linux' && Number.isSafeInteger(Number(identity.birth))
+        ? Number(identity.birth)
+        : undefined;
+    const legacyHash = identity?.cmdline_hash && SHA256_PATTERN.test(identity.cmdline_hash)
+        ? identity.cmdline_hash
+        : undefined;
+    const common = {
         token,
         pid: process.pid,
-        platform: process.platform,
-        ...(identity?.status === 'matching' && isValidStartTicks(identity.startTicks)
-            ? { pid_start_ticks: identity.startTicks }
-            : {}),
-        ...(identity?.status === 'matching' && identity.cmdlineHash && SHA256_PATTERN.test(identity.cmdlineHash)
-            ? { pid_cmdline_hash: identity.cmdlineHash }
-            : {}),
+        platform: runtimePlatform,
+        ...(legacyStartTicks !== undefined ? { pid_start_ticks: legacyStartTicks } : {}),
+        ...(legacyHash ? { pid_cmdline_hash: legacyHash } : {}),
         created_at: new Date(transactionDependencies.nowMs()).toISOString(),
     };
+    return identity
+        ? { version: 2, ...common, process_identity: identity }
+        : { version: 1, ...common };
 }
 async function removeOwnedPath(path) {
     try {
@@ -942,7 +1442,7 @@ async function releasePointerLock(lock) {
         if (!isNotFound(error)) {
             return [{
                     operation: 'lock-release',
-                    phase: 'remove-release-dir',
+                    phase: 'remove-release-owner',
                     ownership: 'released',
                     message: `Unable to remove released session pointer lock owner: ${errorMessage(error)}`,
                     cause: error,
@@ -965,6 +1465,10 @@ async function releasePointerLock(lock) {
             }];
     }
 }
+/** @internal Test-only release of a held pointer lock; do not use outside session tests. */
+export async function __releasePointerLockForTests(cwd, token) {
+    return await releasePointerLock({ context: resolveSessionPointerContext(cwd), token });
+}
 function recoveryAbort(context, primary, failures, operation) {
     return resolvedAbort(context, {
         code: 'session_pointer_lock_recovery_required',
@@ -979,9 +1483,12 @@ function recoveryAbort(context, primary, failures, operation) {
         secondaryFailures: failures,
     });
 }
-function releaseFailureError(failures) {
-    const error = new Error('Session pointer committed, but lock release left recovery evidence.');
-    Object.assign(error, { secondaryFailures: failures });
+function releaseFailureError(failures, context, value) {
+    const error = new CommittedLaunchBlockedError(failures);
+    if (context)
+        error.context = context;
+    if (value !== undefined)
+        error.value = value;
     return error;
 }
 async function finalizePrecommitAbort(lock, primary, pointerTempPath) {
@@ -1023,7 +1530,7 @@ function ownerConflictAbort(context, candidateSessionId, state, cause) {
         ...(cause ? { cause } : {}),
     });
 }
-async function writePointerTransaction(cwd, candidateSessionId, options, timeoutMs, transition, pointerState) {
+async function writePointerTransaction(cwd, candidateSessionId, options, timeoutMs, transition, pointerState, beforeCommit, afterCommit) {
     let context;
     try {
         context = options.context ?? resolveSessionPointerContext(cwd);
@@ -1059,6 +1566,7 @@ async function writePointerTransaction(cwd, candidateSessionId, options, timeout
     const lock = await acquirePointerLock(context, candidateSessionId, timeoutMs, platform, tracker, options.regularFileSync);
     const pointerTempPath = `${context.sessionPath}.tmp-${lock.token}`;
     let pointerCommitted = false;
+    let pointerTempWritten = false;
     try {
         let pointer;
         try {
@@ -1076,7 +1584,7 @@ async function writePointerTransaction(cwd, candidateSessionId, options, timeout
         }
         let next;
         try {
-            next = transition(pointer, context);
+            next = await transition(pointer, context);
         }
         catch (error) {
             if (isSessionPointerLaunchAbort(error))
@@ -1091,6 +1599,7 @@ async function writePointerTransaction(cwd, candidateSessionId, options, timeout
         }
         const serialized = JSON.stringify(pointerState(next), null, 2);
         try {
+            pointerTempWritten = true;
             await transactionDependencies.fs.writeFile(pointerTempPath, serialized, { mode: 0o600, flag: 'wx' });
         }
         catch (error) {
@@ -1116,11 +1625,31 @@ async function writePointerTransaction(cwd, candidateSessionId, options, timeout
                 cause: error,
             });
         }
+        if (beforeCommit)
+            await beforeCommit(context);
         try {
             await transactionDependencies.fs.rename(pointerTempPath, context.sessionPath);
             pointerCommitted = true;
+            if (afterCommit) {
+                try {
+                    await afterCommit(context);
+                }
+                catch (error) {
+                    const releaseFailures = await releasePointerLock(lock);
+                    throw releaseFailureError([
+                        {
+                            operation: 'lock-release', phase: 'rename', ownership: 'uncertain',
+                            message: `Selected state root identity changed after pointer publication: ${errorMessage(error)}`,
+                            cause: error, evidencePath: context.sessionPath,
+                        },
+                        ...releaseFailures,
+                    ], context, next);
+                }
+            }
         }
         catch (error) {
+            if (error instanceof CommittedLaunchBlockedError)
+                throw error;
             throw resolvedAbort(context, {
                 code: 'session_pointer_io_failure',
                 operation: 'pointer-rename',
@@ -1132,7 +1661,7 @@ async function writePointerTransaction(cwd, candidateSessionId, options, timeout
         }
         const releaseFailures = await releasePointerLock(lock);
         if (releaseFailures.length > 0)
-            throw releaseFailureError(releaseFailures);
+            throw releaseFailureError(releaseFailures, context, next);
         emitDegradedDurabilityWarning('session pointer start/reconcile', tracker);
         return { context, value: next };
     }
@@ -1149,14 +1678,18 @@ async function writePointerTransaction(cwd, candidateSessionId, options, timeout
                 reason: `Session pointer transition failed before commit: ${errorMessage(error)}`,
                 cause: error,
             });
-        const ownsPointerTemp = primary.operation === 'pointer-temp-write'
-            || primary.operation === 'pointer-fsync'
-            || primary.operation === 'pointer-rename';
+        const ownsPointerTemp = pointerTempWritten;
         throw await finalizePrecommitAbort(lock, primary, ownsPointerTemp ? pointerTempPath : undefined);
     }
 }
-function startPointerTransition(requestedSessionId, options) {
+function startPointerTransition(requestedSessionId, options, requireLaunchLineageToken = false, requireAbsent = false) {
     return (pointer, context) => {
+        if (requireAbsent && pointer.status !== 'absent') {
+            if (pointer.status === 'usable' && pointer.state) {
+                throw ownerConflictAbort(context, requestedSessionId, pointer.state);
+            }
+            throw unusablePointerAbort(context, requestedSessionId, pointer);
+        }
         if (pointer.status !== 'absent' && pointer.status !== 'stale-dead' && pointer.status !== 'usable') {
             throw unusablePointerAbort(context, requestedSessionId, pointer);
         }
@@ -1164,6 +1697,9 @@ function startPointerTransition(requestedSessionId, options) {
         if (existing && !isStartCompatible(existing, requestedSessionId)) {
             throw ownerConflictAbort(context, requestedSessionId, existing);
         }
+        if (requireLaunchLineageToken && existing && !isValidToken(existing.launch_lineage_token)) {
+            throw ownerConflictAbort(context, requestedSessionId, existing);
+        }
         const canonicalSessionId = existing?.session_id ?? requestedSessionId;
         const pid = resolvePid(options);
         const platform = options.platform ?? process.platform;
@@ -1180,20 +1716,51 @@ function startPointerTransition(requestedSessionId, options) {
                 pid,
             }, error);
         }
-        return createSessionState(context.cwd, canonicalSessionId, pid, platform, sessionIdentityFor(pid, platform), {
+        const state = createSessionState(context.cwd, context.baseStateDir, canonicalSessionId, pid, platform, sessionIdentityFor(pid, platform), {
             nativeSessionId: options.nativeSessionId ?? existing?.native_session_id,
             previousNativeSessionId: options.previousNativeSessionId ?? existing?.previous_native_session_id,
             nativeSessionSwitchedAt: options.nativeSessionSwitchedAt ?? existing?.native_session_switched_at,
             ...(ownerOmxSessionId ? { ownerOmxSessionId } : {}),
+            launchLineageToken: existing
+                ? (isValidToken(existing.launch_lineage_token) ? existing.launch_lineage_token : undefined)
+                : transactionDependencies.token(),
             tmuxSessionName: options.tmuxSessionName ?? existing?.tmux_session_name,
             tmuxPaneId: options.tmuxPaneId ?? existing?.tmux_pane_id,
         });
+        return preserveExistingLaunchLineageToken(existing, state);
     };
 }
-/** Write or merge a wrapper-owned canonical pointer through the exact-root transaction. */
+/** Create a wrapper-owned canonical pointer only when the selected pointer is absent. */
 export async function writeSessionStart(cwd, sessionId, options = {}) {
+    const candidateSessionId = normalizeSessionId(sessionId);
+    let context;
+    try {
+        context = options.context ?? resolveSessionPointerContext(cwd);
+    }
+    catch (error) {
+        throw contextAbort(cwd, candidateSessionId, error);
+    }
+    let pointer;
+    try {
+        pointer = await readSessionPointer(context);
+    }
+    catch (error) {
+        throw resolvedAbort(context, {
+            code: 'session_pointer_io_failure', operation: 'pointer-read', candidateSessionId,
+            lockPath: context.lockPath, reason: `Unable to read selected session pointer: ${errorMessage(error)}`, cause: error,
+        });
+    }
+    if (pointer.status !== 'absent') {
+        if (pointer.status === 'usable' && pointer.state) {
+            throw ownerConflictAbort(context, candidateSessionId ?? sessionId, pointer.state);
+        }
+        throw unusablePointerAbort(context, candidateSessionId ?? sessionId, pointer);
+    }
+    return await writeSessionStartTransition(cwd, sessionId, { ...options, context });
+}
+async function writeSessionStartTransition(cwd, sessionId, options, requireLaunchLineageToken = false, requireAbsent = false, beforeCommit, afterCommit) {
     const requestedSessionId = normalizeSessionId(sessionId);
-    const result = await writePointerTransaction(cwd, requestedSessionId, options, DEFAULT_POINTER_TIMEOUT_MS, startPointerTransition(requestedSessionId ?? sessionId, options), (state) => state);
+    const result = await writePointerTransaction(cwd, requestedSessionId, options, DEFAULT_POINTER_TIMEOUT_MS, startPointerTransition(requestedSessionId ?? sessionId, options, requireLaunchLineageToken, requireAbsent), (state) => state, beforeCommit, afterCommit);
     await appendToLogAtContext(result.context, {
         event: 'session_start',
         session_id: result.value.session_id,
@@ -1203,6 +1770,551 @@ export async function writeSessionStart(cwd, sessionId, options = {}) {
     }).catch(() => { });
     return result.value;
 }
+const DIRECTORY_CAPABILITY_PLATFORMS = new Set([
+    'linux', 'darwin', 'freebsd', 'openbsd', 'netbsd', 'sunos',
+]);
+export class LaunchContextResolutionError extends Error {
+    cleanup;
+    name = 'LaunchContextResolutionError';
+    constructor(cleanup, cause) {
+        super(`Unable to establish launch directory capability: ${errorMessage(cause)}`, { cause });
+        this.cleanup = cleanup;
+    }
+}
+const bindingLeases = new WeakMap();
+const bindingFinalizations = new WeakMap();
+function safeError(error) {
+    return {
+        name: error instanceof Error ? error.name : 'Error',
+        message: errorMessage(error),
+        ...(errorCode(error) ? { code: errorCode(error) } : {}),
+    };
+}
+function lockDisposition(failures) {
+    if (failures.some((failure) => failure.ownership === 'uncertain'))
+        return 'uncertain';
+    return failures.some((failure) => failure.ownership === 'held') ? 'held' : 'released-with-residue';
+}
+async function acquireDirectoryCapability(cwd, platform) {
+    const cleanup = [];
+    let canonicalRealpath;
+    try {
+        canonicalRealpath = await realpath(cwd);
+    }
+    catch (error) {
+        throw new LaunchContextResolutionError({ capability: cleanup }, error);
+    }
+    if (!DIRECTORY_CAPABILITY_PLATFORMS.has(platform)) {
+        return { canonicalRealpath, identity: { kind: 'unsupported', reason: 'platform' }, lease: { closed: false }, cleanup };
+    }
+    let handle;
+    try {
+        handle = await open(canonicalRealpath, 'r');
+    }
+    catch (error) {
+        throw new LaunchContextResolutionError({ capability: cleanup }, error);
+    }
+    let statFailure;
+    try {
+        const stats = await handle.stat({ bigint: true });
+        if (!stats.isDirectory() || typeof stats.dev !== 'bigint' || typeof stats.ino !== 'bigint' || stats.dev <= 0n || stats.ino <= 0n) {
+            try {
+                await handle.close();
+                cleanup.push({ role: 'acquisition', phase: 'before-authorization', status: 'closed' });
+            }
+            catch (closeError) {
+                cleanup.push({ role: 'acquisition', phase: 'before-authorization', status: 'failed', error: safeError(closeError) });
+                throw new LaunchContextResolutionError({ capability: cleanup }, closeError);
+            }
+            return { canonicalRealpath, identity: { kind: 'unsupported', reason: 'inadequate-identity' }, lease: { closed: false }, cleanup };
+        }
+        return { canonicalRealpath, identity: { kind: 'supported', dev: stats.dev, ino: stats.ino }, lease: { handle, closed: false }, cleanup };
+    }
+    catch (error) {
+        if (error instanceof LaunchContextResolutionError)
+            throw error;
+        statFailure = error;
+    }
+    try {
+        await handle.close();
+        cleanup.push({ role: 'acquisition', phase: 'before-authorization', status: 'closed' });
+    }
+    catch (closeError) {
+        cleanup.push({ role: 'acquisition', phase: 'before-authorization', status: 'failed', error: safeError(closeError) });
+        throw new LaunchContextResolutionError({ capability: cleanup }, closeError);
+    }
+    const code = errorCode(statFailure);
+    if (code === 'ENOSYS' || code === 'ENOTSUP' || code === 'EOPNOTSUPP' || code === 'EINVAL') {
+        return { canonicalRealpath, identity: { kind: 'unsupported', reason: 'stat-feature' }, lease: { closed: false }, cleanup };
+    }
+    throw new LaunchContextResolutionError({ capability: cleanup }, statFailure);
+}
+export async function closeLaunchSessionBindingOnce(binding, phase = 'post-finalization') {
+    const lease = bindingLeases.get(binding);
+    if (!lease || lease.closed)
+        return lease?.closeEvidence ?? { role: 'original-retained', phase, status: 'not-needed' };
+    lease.closed = true;
+    try {
+        await lease.handle?.close();
+        return lease.closeEvidence = { role: 'original-retained', phase, status: 'closed' };
+    }
+    catch (error) {
+        return lease.closeEvidence = { role: 'original-retained', phase, status: 'failed', error: safeError(error) };
+    }
+}
+export async function establishLaunchSessionBinding(cwd, requestedSessionId, options = {}) {
+    const platform = options.platform ?? process.platform;
+    let context;
+    try {
+        context = options.context ?? resolveSessionPointerContext(cwd);
+        await transactionDependencies.fs.mkdir(context.baseStateDir, { recursive: true });
+    }
+    catch (error) {
+        throw new LaunchContextResolutionError({ capability: [] }, error);
+    }
+    const acquired = await acquireDirectoryCapability(context.baseStateDir, platform);
+    const cleanup = () => ({ capability: acquired.cleanup });
+    const revalidateSelectedRoot = async (lockedContext) => {
+        if (acquired.identity.kind !== 'supported')
+            return;
+        const retained = await acquired.lease.handle?.stat({ bigint: true });
+        if (!retained || !retained.isDirectory() || retained.dev !== acquired.identity.dev || retained.ino !== acquired.identity.ino) {
+            throw resolvedAbort(lockedContext, {
+                code: 'session_pointer_io_failure', operation: 'pointer-classify', candidateSessionId: normalizeSessionId(requestedSessionId),
+                lockPath: lockedContext.lockPath, reason: 'Selected state root identity changed during pointer publication.',
+            });
+        }
+        const canonical = await realpath(lockedContext.baseStateDir);
+        const fresh = await open(canonical, 'r');
+        try {
+            const stats = await fresh.stat({ bigint: true });
+            if (canonical !== acquired.canonicalRealpath || !stats.isDirectory() || stats.dev !== acquired.identity.dev || stats.ino !== acquired.identity.ino) {
+                throw resolvedAbort(lockedContext, {
+                    code: 'session_pointer_io_failure', operation: 'pointer-classify', candidateSessionId: normalizeSessionId(requestedSessionId),
+                    lockPath: lockedContext.lockPath, reason: 'Selected state root was replaced during pointer publication.',
+                });
+            }
+        }
+        finally {
+            await fresh.close();
+        }
+    };
+    try {
+        const state = await writeSessionStartTransition(context.cwd, requestedSessionId, { ...options, context }, true, true, revalidateSelectedRoot, revalidateSelectedRoot);
+        const token = state.launch_lineage_token;
+        if (!isValidToken(token)) {
+            const close = await closeLease(acquired.lease, 'before-authorization');
+            if (close)
+                acquired.cleanup.push(close);
+            throw new LaunchContextResolutionError(cleanup(), new Error('Committed session pointer lacks a valid lineage token.'));
+        }
+        const binding = Object.freeze({
+            context: Object.freeze({ ...context }), canonicalRealpath: acquired.canonicalRealpath,
+            directoryIdentity: acquired.identity, canonicalSessionId: state.session_id,
+            ...(state.owner_omx_session_id ? { ownerOmxSessionId: state.owner_omx_session_id } : {}),
+            ...(state.native_session_id ? { nativeSessionId: state.native_session_id } : {}),
+            startedAt: state.started_at, launchLineageToken: token,
+        });
+        bindingLeases.set(binding, acquired.lease);
+        return { kind: 'committed-released', binding, cleanup: cleanup() };
+    }
+    catch (error) {
+        if (error instanceof CommittedLaunchBlockedError) {
+            const state = error.value;
+            const errorContext = error.context ?? context;
+            const close = await closeLease(acquired.lease, 'before-authorization');
+            if (close)
+                acquired.cleanup.push(close);
+            return {
+                kind: 'committed-release-failed', evidence: { context: errorContext, canonicalSessionId: state?.session_id ?? requestedSessionId },
+                error, lockDisposition: lockDisposition(error.secondaryFailures), secondaryFailures: error.secondaryFailures, cleanup: cleanup(),
+            };
+        }
+        const close = await closeLease(acquired.lease, 'before-authorization');
+        if (close)
+            acquired.cleanup.push(close);
+        if (isSessionPointerLaunchAbort(error))
+            return { kind: 'precommit-aborted', abort: error, cleanup: cleanup() };
+        throw error;
+    }
+}
+async function closeLease(lease, phase) {
+    if (lease.closed)
+        return undefined;
+    lease.closed = true;
+    try {
+        await lease.handle?.close();
+        return { role: 'acquisition', phase, status: 'closed' };
+    }
+    catch (error) {
+        return { role: 'acquisition', phase, status: 'failed', error: safeError(error) };
+    }
+}
+export async function updateDetachedSessionMetadata(binding, patch) {
+    const capability = [];
+    const cleanup = { capability };
+    try {
+        let pointerBeforeTransaction;
+        try {
+            pointerBeforeTransaction = await readSessionPointer(binding.context);
+        }
+        catch (error) {
+            throw resolvedAbort(binding.context, {
+                code: 'session_pointer_io_failure', operation: 'pointer-read', candidateSessionId: binding.canonicalSessionId,
+                lockPath: binding.context.lockPath, reason: `Unable to read selected session pointer: ${errorMessage(error)}`, cause: error,
+            });
+        }
+        if (pointerBeforeTransaction.status !== 'usable'
+            || !isAuthorizedBoundPointer(binding, binding.context, binding.canonicalSessionId, pointerBeforeTransaction.state)) {
+            throw unusablePointerAbort(binding.context, binding.canonicalSessionId, pointerBeforeTransaction);
+        }
+        const authorization = await authorizeBoundDirectoryBeforeTransaction(binding, pointerBeforeTransaction, binding.context.cwd);
+        capability.push(...authorization.capability);
+        const result = await writePointerTransaction(binding.context.cwd, binding.canonicalSessionId, { context: binding.context }, DEFAULT_POINTER_TIMEOUT_MS, async (pointer, context) => {
+            const state = pointer.status === 'usable' ? pointer.state : undefined;
+            if (!state || !isAuthorizedBoundPointer(binding, context, binding.canonicalSessionId, state)) {
+                throw unusablePointerAbort(context, binding.canonicalSessionId, pointer);
+            }
+            await consumeBoundDirectoryAuthorizationUnderLock(binding, authorization, pointer);
+            return {
+                ...state,
+                ...(patch.tmuxSessionName !== undefined ? { tmux_session_name: patch.tmuxSessionName } : {}),
+                ...(patch.tmuxPaneId !== undefined ? { tmux_pane_id: patch.tmuxPaneId } : {}),
+            };
+        }, (state) => state);
+        return { kind: 'committed-released', evidence: { context: result.context, canonicalSessionId: binding.canonicalSessionId }, cleanup };
+    }
+    catch (error) {
+        if (error instanceof CommittedLaunchBlockedError) {
+            const context = error.context ?? binding.context;
+            return { kind: 'committed-release-failed', evidence: { context, canonicalSessionId: binding.canonicalSessionId }, error,
+                lockDisposition: lockDisposition(error.secondaryFailures), secondaryFailures: error.secondaryFailures, cleanup };
+        }
+        if (isSessionPointerLaunchAbort(error))
+            return { kind: 'precommit-aborted', abort: error, cleanup };
+        throw error;
+    }
+}
+function isAuthorizedBoundPointer(binding, context, candidateSessionId, state) {
+    traceSessionFinalizationOperation('auth-function-enter');
+    traceSessionFinalizationOperation('lease-lookup-start');
+    const lease = bindingLeases.get(binding);
+    traceSessionFinalizationOperation('lease-lookup-done');
+    traceSessionFinalizationOperation(`state-present:${state ? 'true' : 'false'}`);
+    if (!lease || (binding.directoryIdentity.kind === 'supported' && lease.closed) || !state) {
+        traceSessionFinalizationOperation('bound-auth-fail:lease-or-state');
+        return false;
+    }
+    if (!isValidToken(binding.launchLineageToken) || !isValidToken(state.launch_lineage_token)) {
+        traceSessionFinalizationOperation('bound-auth-fail:token-shape');
+        return false;
+    }
+    if (candidateSessionId !== binding.canonicalSessionId) {
+        traceSessionFinalizationOperation('bound-auth-fail:candidate-session');
+        return false;
+    }
+    if (state.launch_lineage_token !== binding.launchLineageToken) {
+        traceSessionFinalizationOperation('bound-auth-fail:lineage-token');
+        return false;
+    }
+    if (state.started_at !== binding.startedAt) {
+        traceSessionFinalizationOperation('bound-auth-fail:started-at');
+        return false;
+    }
+    const directCanonicalIdentity = state.session_id === binding.canonicalSessionId
+        && ((state.owner_omx_session_id ?? undefined) === binding.ownerOmxSessionId
+            || (binding.ownerOmxSessionId === undefined && state.owner_omx_session_id === binding.canonicalSessionId))
+        && (binding.nativeSessionId === undefined || state.native_session_id === binding.nativeSessionId);
+    const replacedNativeIdentity = state.owner_omx_session_id === binding.canonicalSessionId
+        && normalizeSessionId(state.session_id) !== undefined
+        && state.native_session_id === state.session_id;
+    if (!directCanonicalIdentity && !replacedNativeIdentity) {
+        traceSessionFinalizationOperation('bound-auth-fail:session-identity');
+        return false;
+    }
+    if (context.rootSource !== binding.context.rootSource)
+        traceSessionFinalizationOperation('bound-auth-fail:root-source');
+    else if (context.baseStateDir !== binding.context.baseStateDir)
+        traceSessionFinalizationOperation('bound-auth-fail:base-state-dir');
+    else if (context.sessionPath !== binding.context.sessionPath)
+        traceSessionFinalizationOperation('bound-auth-fail:session-path');
+    else if (context.cwd !== binding.context.cwd)
+        traceSessionFinalizationOperation('bound-auth-fail:context-cwd');
+    else if (state.cwd !== binding.context.cwd)
+        traceSessionFinalizationOperation('bound-auth-fail:state-cwd');
+    else {
+        traceSessionFinalizationOperation('bound-auth-success');
+        return true;
+    }
+    return false;
+}
+function isAuthorizedBoundStaleDeadPointer(binding, context, candidateSessionId, state) {
+    return isAuthorizedBoundPointer(binding, context, candidateSessionId, state)
+        && Boolean(normalizeSessionId(state?.native_session_id));
+}
+class BoundDirectoryComparisonDenied extends Error {
+    comparison;
+    capability;
+    constructor(comparison, capability) {
+        super(comparison.reason);
+        this.comparison = comparison;
+        this.capability = capability;
+    }
+}
+function isAuthorizedBoundPointerForFinalization(binding, context, candidateSessionId, pointer, phase) {
+    traceSessionFinalizationOperation(`${phase}-status:${pointer.status}`);
+    if (pointer.status === 'usable') {
+        traceSessionFinalizationOperation(`${phase}-usable-branch-enter`);
+        return isAuthorizedBoundPointer(binding, context, candidateSessionId, pointer.state);
+    }
+    if (pointer.status === 'stale-dead') {
+        traceSessionFinalizationOperation(`${phase}-stale-dead-branch-enter`);
+        return isAuthorizedBoundStaleDeadPointer(binding, context, candidateSessionId, pointer.state);
+    }
+    if (pointer.status === 'identity-indeterminate') {
+        traceSessionFinalizationOperation(`${phase}-identity-indeterminate-branch-enter`);
+        const sameProcess = pointer.state?.pid === process.pid;
+        traceSessionFinalizationOperation(`${phase}-identity-indeterminate-current-pid:${sameProcess ? 'true' : 'false'}`);
+        return sameProcess && isAuthorizedBoundPointer(binding, context, candidateSessionId, pointer.state);
+    }
+    traceSessionFinalizationOperation(`${phase}-unsupported-status`);
+    return false;
+}
+async function authorizeBoundDirectoryBeforeTransaction(binding, pointer, postLaunchCwd) {
+    const capability = [];
+    const lease = bindingLeases.get(binding);
+    if (!lease || lease.closed) {
+        throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: 'binding-lease-closed' }, capability);
+    }
+    try {
+        if (!sameFilePath(binding.context.cwd, postLaunchCwd)
+            || !pointer.state?.cwd
+            || !sameFilePath(binding.context.cwd, pointer.state.cwd)) {
+            throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: 'cwd-identity-mismatch' }, capability);
+        }
+        if (binding.directoryIdentity.kind !== 'supported') {
+            return {
+                comparison: { status: 'matched', reason: `unsupported-directory-capability:${binding.directoryIdentity.reason}` },
+                capability,
+                pointerStatus: pointer.status,
+                pointerRaw: pointer.raw,
+            };
+        }
+        const retained = fstatSync(lease.handle.fd, { bigint: true });
+        if (!retained || !retained.isDirectory() || retained.dev !== binding.directoryIdentity.dev || retained.ino !== binding.directoryIdentity.ino) {
+            throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: 'retained-directory-identity-mismatch' }, capability);
+        }
+        const canonical = await realpath(binding.context.baseStateDir);
+        const fd = openSync(canonical, 'r');
+        let matched = false;
+        try {
+            const stats = fstatSync(fd, { bigint: true });
+            matched = canonical === binding.canonicalRealpath
+                && stats.isDirectory()
+                && stats.dev === binding.directoryIdentity.dev
+                && stats.ino === binding.directoryIdentity.ino;
+        }
+        finally {
+            try {
+                closeSync(fd);
+                capability.push({ role: 'fresh-comparison', phase: 'before-authorization', status: 'closed' });
+            }
+            catch (error) {
+                capability.push({ role: 'fresh-comparison', phase: 'before-authorization', status: 'failed', error: safeError(error) });
+                throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: 'fresh-comparison-close-failed' }, capability);
+            }
+        }
+        if (!matched)
+            throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: 'directory-identity-mismatch' }, capability);
+        return { comparison: { status: 'matched' }, capability, pointerStatus: pointer.status, pointerRaw: pointer.raw };
+    }
+    catch (error) {
+        if (error instanceof BoundDirectoryComparisonDenied)
+            throw error;
+        throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: errorMessage(error) }, capability);
+    }
+}
+async function consumeBoundDirectoryAuthorizationUnderLock(binding, authorization, pointer) {
+    if (authorization.comparison?.status !== 'matched' || binding.directoryIdentity.kind !== 'supported')
+        return authorization;
+    const lease = bindingLeases.get(binding);
+    try {
+        const retained = lease?.handle ? fstatSync(lease.handle.fd, { bigint: true }) : undefined;
+        if (!retained || !retained.isDirectory() || retained.dev !== binding.directoryIdentity.dev || retained.ino !== binding.directoryIdentity.ino) {
+            throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: 'retained-directory-identity-mismatch' }, authorization.capability);
+        }
+        if (!pointer.state?.cwd || !sameFilePath(binding.context.cwd, pointer.state.cwd)) {
+            throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: 'cwd-identity-mismatch-under-lock' }, authorization.capability);
+        }
+        const canonical = await realpath(binding.context.baseStateDir);
+        const fd = openSync(canonical, 'r');
+        let matched = false;
+        try {
+            const stats = fstatSync(fd, { bigint: true });
+            matched = canonical === binding.canonicalRealpath
+                && stats.isDirectory()
+                && stats.dev === binding.directoryIdentity.dev
+                && stats.ino === binding.directoryIdentity.ino;
+        }
+        finally {
+            try {
+                closeSync(fd);
+                authorization.capability.push({ role: 'fresh-comparison', phase: 'before-authorization', status: 'closed' });
+            }
+            catch (error) {
+                authorization.capability.push({ role: 'fresh-comparison', phase: 'before-authorization', status: 'failed', error: safeError(error) });
+                throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: 'fresh-comparison-close-failed-under-lock' }, authorization.capability);
+            }
+        }
+        if (!matched)
+            throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: 'directory-identity-mismatch-under-lock' }, authorization.capability);
+        if (pointer.status !== authorization.pointerStatus || pointer.raw !== authorization.pointerRaw) {
+            throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: 'pointer-changed-before-consume' }, authorization.capability);
+        }
+        return authorization;
+    }
+    catch (error) {
+        if (error instanceof BoundDirectoryComparisonDenied)
+            throw error;
+        throw new BoundDirectoryComparisonDenied({ status: 'denied', reason: errorMessage(error) }, authorization.capability);
+    }
+}
+export function finalizeBoundOnce(binding, _reason, postLaunchCwd = binding.context.cwd) {
+    const existing = bindingFinalizations.get(binding);
+    if (existing)
+        return existing;
+    const finalization = (async () => {
+        try {
+            const revalidation = await writeSessionEnd(binding.context.cwd, binding.canonicalSessionId, {
+                context: binding.context, binding, postLaunchCwd,
+            });
+            return { finalized: true, cleanup: { capability: revalidation.capability, comparison: revalidation.comparison } };
+        }
+        catch (error) {
+            if (error instanceof BoundDirectoryComparisonDenied) {
+                return { finalized: false, cleanup: { capability: error.capability, comparison: error.comparison } };
+            }
+            if (isSessionPointerLaunchAbort(error)) {
+                return { finalized: false, cleanup: { capability: [], comparison: { status: 'denied', reason: error.code } } };
+            }
+            throw error;
+        }
+    })();
+    bindingFinalizations.set(binding, finalization);
+    return finalization;
+}
+function nativeSessionOwnerTransition(nativeSessionId, options) {
+    return (pointer, context) => {
+        if (pointer.status !== 'absent' && pointer.status !== 'stale-dead' && pointer.status !== 'usable') {
+            throw unusablePointerAbort(context, nativeSessionId, pointer);
+        }
+        const pid = resolvePid(options);
+        const platform = options.platform ?? process.platform;
+        const linuxIdentity = sessionIdentityFor(pid, platform);
+        const existing = pointer.status === 'usable' ? pointer.state : undefined;
+        if (existing && (normalizeSessionId(existing.session_id) !== nativeSessionId
+            || normalizeSessionId(existing.native_session_id) !== nativeSessionId
+            || existing.platform !== platform
+            || !isSessionStateAuthoritativeForCwd(existing, context.cwd)
+            || existing.pid !== pid)) {
+            throw ownerConflictAbort(context, nativeSessionId, existing);
+        }
+        return createSessionState(context.cwd, context.baseStateDir, nativeSessionId, pid, platform, linuxIdentity, {
+            nativeSessionId,
+            startedAt: existing?.started_at,
+            tmuxSessionName: options.tmuxSessionName ?? existing?.tmux_session_name,
+            tmuxPaneId: options.tmuxPaneId ?? existing?.tmux_pane_id,
+        });
+    };
+}
+export async function writeNativeSessionOwner(cwd, nativeSessionId, options = {}) {
+    const normalized = normalizeSessionId(nativeSessionId);
+    const context = resolveNativeSessionOwnerContext(cwd, nativeSessionId);
+    const result = await writePointerTransaction(cwd, normalized, { context }, NATIVE_POINTER_TIMEOUT_MS, nativeSessionOwnerTransition(normalized ?? nativeSessionId, options), (state) => state);
+    return result.value;
+}
+/** Read and classify the exact native session-owner sidecar without consulting alternate roots. */
+export async function readNativeSessionOwnerEvidence(cwd, nativeSessionId) {
+    const normalized = normalizeSessionId(nativeSessionId);
+    if (!normalized)
+        return { status: 'malformed' };
+    const context = resolveNativeSessionOwnerContext(cwd, normalized);
+    const nativeOwnerDir = dirname(context.sessionPath);
+    const sessionsDir = dirname(nativeOwnerDir);
+    const stateRootDir = dirname(sessionsDir);
+    const directoryPaths = [stateRootDir, sessionsDir, nativeOwnerDir];
+    const directoryIdentities = [];
+    try {
+        for (const directoryPath of directoryPaths) {
+            const stat = await transactionDependencies.fs.lstat(directoryPath);
+            if (stat.isSymbolicLink() || !stat.isDirectory())
+                return { status: 'malformed' };
+            directoryIdentities.push({ path: directoryPath, dev: stat.dev, ino: stat.ino });
+        }
+        const pathStat = await transactionDependencies.fs.lstat(context.sessionPath);
+        if (pathStat.isSymbolicLink() || !pathStat.isFile())
+            return { status: 'malformed' };
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return { status: 'absent' };
+        throw error;
+    }
+    const handle = await open(context.sessionPath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
+    let raw;
+    try {
+        const openedStat = await handle.stat();
+        if (!openedStat.isFile())
+            return { status: 'malformed' };
+        raw = await handle.readFile({ encoding: 'utf8' });
+        const finalPathStat = await transactionDependencies.fs.lstat(context.sessionPath);
+        if (finalPathStat.isSymbolicLink()
+            || finalPathStat.dev !== openedStat.dev
+            || finalPathStat.ino !== openedStat.ino) {
+            return { status: 'malformed', raw };
+        }
+        for (const identity of directoryIdentities) {
+            const finalDirectoryStat = await transactionDependencies.fs.lstat(identity.path);
+            if (finalDirectoryStat.isSymbolicLink()
+                || !finalDirectoryStat.isDirectory()
+                || finalDirectoryStat.dev !== identity.dev
+                || finalDirectoryStat.ino !== identity.ino) {
+                return { status: 'malformed', raw };
+            }
+        }
+    }
+    finally {
+        await handle.close();
+    }
+    let pointer;
+    try {
+        pointer = classifyParsedSessionPointer(context, JSON.parse(raw), raw);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return { status: 'malformed', raw };
+        throw error;
+    }
+    if (pointer.status === 'absent' || pointer.status === 'foreign-cwd' || pointer.status === 'malformed' || pointer.status === 'identity-indeterminate') {
+        return pointer;
+    }
+    const state = pointer.state;
+    return state?.session_id === normalized
+        && state.native_session_id === normalized
+        && state.platform === transactionDependencies.runtimePlatform
+        && isSessionStateAuthoritativeForCwd(state, context.cwd)
+        ? pointer
+        : { status: 'malformed', state, raw: pointer.raw };
+}
+export async function readNativeSessionOwner(cwd, nativeSessionId) {
+    try {
+        const evidence = await readNativeSessionOwnerEvidence(cwd, nativeSessionId);
+        return evidence.status === 'usable' ? evidence.state ?? null : null;
+    }
+    catch {
+        return null;
+    }
+}
 function reconcileNativeTransition(nativeSessionId, options) {
     return (pointer, context) => {
         if (pointer.status !== 'absent' && pointer.status !== 'stale-dead' && pointer.status !== 'usable') {
@@ -1212,42 +2324,19 @@ function reconcileNativeTransition(nativeSessionId, options) {
         const platform = options.platform ?? process.platform;
         const linuxIdentity = sessionIdentityFor(pid, platform);
         const existing = pointer.status === 'usable' ? pointer.state : undefined;
-        const nowIso = new Date().toISOString();
         if (!existing) {
             const ownerCandidate = verifiedOwnerCandidate(context, options);
             const ownerOmxSessionId = ownerCandidate;
-            return {
-                state: createSessionState(context.cwd, nativeSessionId, pid, platform, linuxIdentity, {
-                    nativeSessionId,
-                    ...(ownerOmxSessionId ? { ownerOmxSessionId } : {}),
-                }),
-            };
+            return createSessionState(context.cwd, context.baseStateDir, nativeSessionId, pid, platform, linuxIdentity, {
+                nativeSessionId,
+                ...(ownerOmxSessionId ? { ownerOmxSessionId } : {}),
+            });
         }
         const existingNativeSessionId = normalizeSessionId(existing.native_session_id);
         if (existingNativeSessionId && existingNativeSessionId !== nativeSessionId) {
-            const ownerOmxSessionId = getOmxLaunchSessionId(existing);
-            return {
-                state: createSessionState(context.cwd, nativeSessionId, pid, platform, linuxIdentity, {
-                    nativeSessionId,
-                    ...(ownerOmxSessionId ? {
-                        previousNativeSessionId: existingNativeSessionId,
-                        nativeSessionSwitchedAt: nowIso,
-                        ownerOmxSessionId,
-                    } : {}),
-                }),
-                ...(ownerOmxSessionId ? {
-                    replacementLog: {
-                        event: 'native_session_replaced',
-                        session_id: ownerOmxSessionId,
-                        ...(existing.session_id !== ownerOmxSessionId ? { active_session_id: existing.session_id } : {}),
-                        previous_native_session_id: existingNativeSessionId,
-                        replaced_by_native_session_id: nativeSessionId,
-                        pid,
-                        timestamp: nowIso,
-                    },
-                } : {}),
-            };
+            throw ownerConflictAbort(context, nativeSessionId, existing);
         }
+        const nowIso = new Date().toISOString();
         const ownerCandidate = verifiedOwnerCandidate(context, options);
         let ownerOmxSessionId;
         try {
@@ -1256,39 +2345,37 @@ function reconcileNativeTransition(nativeSessionId, options) {
         catch (error) {
             throw ownerConflictAbort(context, nativeSessionId, existing, error);
         }
-        return {
-            state: createSessionState(context.cwd, existing.session_id, pid, platform, linuxIdentity, {
-                nowIso,
-                nativeSessionId,
-                previousNativeSessionId: existing.previous_native_session_id,
-                nativeSessionSwitchedAt: existing.native_session_switched_at,
-                ...(ownerOmxSessionId ? { ownerOmxSessionId } : {}),
-                startedAt: existing.started_at,
-                tmuxSessionName: existing.tmux_session_name,
-                tmuxPaneId: existing.tmux_pane_id,
-            }),
-        };
+        return preserveExistingLaunchLineageToken(existing, createSessionState(context.cwd, context.baseStateDir, existing.session_id, pid, platform, linuxIdentity, {
+            nowIso,
+            nativeSessionId,
+            previousNativeSessionId: existing.previous_native_session_id,
+            nativeSessionSwitchedAt: existing.native_session_switched_at,
+            ...(ownerOmxSessionId ? { ownerOmxSessionId } : {}),
+            startedAt: existing.started_at,
+            tmuxSessionName: existing.tmux_session_name,
+            tmuxPaneId: existing.tmux_pane_id,
+            launchLineageToken: isValidToken(existing.launch_lineage_token)
+                ? existing.launch_lineage_token
+                : undefined,
+        }));
     };
 }
 /**
- * Reconcile a native SessionStart without borrowing another root's pointer.
- * A different native ID retains the existing OMX owner chain, but never binds a
- * new owner alias during that replacement transition.
+ * Reconcile native SessionStart only when the selected pointer is absent, stale,
+ * or already belongs to that native session. A different live native ID is
+ * authoritative owner evidence and must never be replaced.
  */
 export async function reconcileNativeSessionStart(cwd, nativeSessionId, options = {}) {
     const normalizedNativeSessionId = normalizeSessionId(nativeSessionId);
-    const result = await writePointerTransaction(cwd, normalizedNativeSessionId, options, NATIVE_POINTER_TIMEOUT_MS, reconcileNativeTransition(normalizedNativeSessionId ?? nativeSessionId, options), (transition) => transition.state);
-    if (result.value.replacementLog) {
-        await appendToLogAtContext(result.context, result.value.replacementLog).catch(() => { });
-    }
+    const result = await writePointerTransaction(cwd, normalizedNativeSessionId, options, NATIVE_POINTER_TIMEOUT_MS, reconcileNativeTransition(normalizedNativeSessionId ?? nativeSessionId, options), (state) => state);
     await appendToLogAtContext(result.context, {
-        event: result.value.replacementLog ? 'session_start' : 'session_start_reconciled',
-        session_id: result.value.state.session_id,
+        event: 'session_start_reconciled',
+        session_id: result.value.session_id,
         native_session_id: normalizedNativeSessionId ?? nativeSessionId,
-        pid: result.value.state.pid,
-        timestamp: result.value.state.native_session_switched_at ?? new Date().toISOString(),
+        pid: result.value.pid,
+        timestamp: new Date().toISOString(),
     }).catch(() => { });
-    return result.value.state;
+    return result.value;
 }
 function historyDirectory(context) {
     return join(dirname(context.baseStateDir), 'logs');
@@ -1334,27 +2421,45 @@ export async function writeSessionEnd(cwd, sessionId, options = {}) {
             cause,
         });
     }
+    if (!options.binding) {
+        throw resolvedAbort(context, {
+            code: 'session_pointer_io_failure', operation: 'pointer-classify', candidateSessionId,
+            lockPath: context.lockPath, reason: 'A live launch binding is required to end a session pointer.',
+        });
+    }
+    let preLockPointer;
+    traceSessionFinalizationOperation('preLock-read-start');
     try {
-        await transactionDependencies.fs.mkdir(context.baseStateDir, { recursive: true });
+        preLockPointer = await readSessionPointer(context);
+        traceSessionFinalizationOperation(`preLock-read-done:${preLockPointer.status}`);
     }
     catch (error) {
         throw resolvedAbort(context, {
-            code: 'session_pointer_io_failure',
-            operation: 'state-dir-create',
-            candidateSessionId,
-            lockPath: context.lockPath,
-            reason: `Unable to create selected session state directory: ${errorMessage(error)}`,
-            cause: error,
+            code: 'session_pointer_io_failure', operation: 'pointer-read', candidateSessionId,
+            lockPath: context.lockPath, reason: `Unable to read selected session pointer: ${errorMessage(error)}`, cause: error,
         });
     }
+    const preLockAuthorized = isAuthorizedBoundPointerForFinalization(options.binding, context, candidateSessionId, preLockPointer, 'preLock');
+    if (!preLockAuthorized)
+        throw unusablePointerAbort(context, candidateSessionId, preLockPointer);
+    traceSessionFinalizationOperation('pre-transaction-auth-start');
+    await authorizeBoundDirectoryBeforeTransaction(options.binding, preLockPointer, options.postLaunchCwd ?? options.binding.context.cwd);
+    traceSessionFinalizationOperation('pre-transaction-auth-done');
     const platform = options.platform ?? process.platform;
     const tracker = { degraded: false };
+    traceSessionFinalizationOperation('acquirePointerLock-start');
     const lock = await acquirePointerLock(context, candidateSessionId, DEFAULT_POINTER_TIMEOUT_MS, platform, tracker, options.regularFileSync);
+    traceSessionFinalizationOperation('acquirePointerLock-done');
     let primary;
+    let revalidation = {
+        comparison: { status: 'not-run' }, capability: [],
+    };
     try {
         let pointer;
+        traceSessionFinalizationOperation('under-lock-read-start');
         try {
             pointer = await readSessionPointer(context);
+            traceSessionFinalizationOperation(`under-lock-read-done:${pointer.status}`);
         }
         catch (error) {
             throw resolvedAbort(context, {
@@ -1366,14 +2471,17 @@ export async function writeSessionEnd(cwd, sessionId, options = {}) {
                 cause: error,
             });
         }
-        if (pointer.status !== 'absent' && pointer.status !== 'usable') {
+        const authorized = isAuthorizedBoundPointerForFinalization(options.binding, context, candidateSessionId, pointer, 'under-lock');
+        if (!authorized)
             throw unusablePointerAbort(context, candidateSessionId, pointer);
-        }
+        traceSessionFinalizationOperation('under-lock-auth-start');
+        const authorization = await authorizeBoundDirectoryBeforeTransaction(options.binding, pointer, options.postLaunchCwd ?? options.binding.context.cwd);
+        traceSessionFinalizationOperation('under-lock-auth-done');
+        traceSessionFinalizationOperation('under-lock-consume-start');
+        revalidation = await consumeBoundDirectoryAuthorizationUnderLock(options.binding, authorization, pointer);
+        traceSessionFinalizationOperation('under-lock-consume-done');
         const state = pointer.state;
-        const ownsCurrentSessionFile = state == null
-            || state.session_id === candidateSessionId
-            || state.native_session_id === candidateSessionId
-            || state.owner_omx_session_id === candidateSessionId;
+        const ownsCurrentSessionFile = true;
         const endTime = new Date().toISOString();
         const historyEntry = {
             session_id: ownsCurrentSessionFile
@@ -1389,12 +2497,19 @@ export async function writeSessionEnd(cwd, sessionId, options = {}) {
                 : {}),
             ...(!ownsCurrentSessionFile && state?.session_id ? { preserved_active_session_id: state.session_id } : {}),
         };
+        traceSessionFinalizationOperation('history-mkdir-start');
         await nodeMkdir(historyDirectory(context), { recursive: true });
+        traceSessionFinalizationOperation('history-mkdir-done');
+        traceSessionFinalizationOperation('history-append-start');
         await appendFile(historyPath(context), `${JSON.stringify(historyEntry)}\n`);
+        traceSessionFinalizationOperation('history-append-done');
+        traceSessionFinalizationOperation('hud-cleanup-start');
         await removeDeadSessionHudState(context, [
             ...(ownsCurrentSessionFile ? [state?.session_id, state?.native_session_id] : []),
             candidateSessionId,
         ]);
+        traceSessionFinalizationOperation('hud-cleanup-done');
+        traceSessionFinalizationOperation('session-unlink-start');
         if (ownsCurrentSessionFile) {
             try {
                 await transactionDependencies.fs.unlink(context.sessionPath);
@@ -1404,6 +2519,8 @@ export async function writeSessionEnd(cwd, sessionId, options = {}) {
                     throw error;
             }
         }
+        traceSessionFinalizationOperation('session-unlink-done');
+        traceSessionFinalizationOperation('session-end-log-start');
         await appendToLogAtContext(context, {
             event: 'session_end',
             session_id: historyEntry.session_id,
@@ -1412,11 +2529,14 @@ export async function writeSessionEnd(cwd, sessionId, options = {}) {
             ...(historyEntry.preserved_active_session_id ? { preserved_active_session_id: historyEntry.preserved_active_session_id } : {}),
             timestamp: endTime,
         }).catch(() => { });
+        traceSessionFinalizationOperation('session-end-log-done');
     }
     catch (error) {
         primary = error;
     }
+    traceSessionFinalizationOperation('lock-release-start');
     const releaseFailures = await releasePointerLock(lock);
+    traceSessionFinalizationOperation('lock-release-done');
     if (primary) {
         if (isSessionPointerLaunchAbort(primary) && releaseFailures.length > 0) {
             throw recoveryAbort(context, primary, releaseFailures, 'lock-release');
@@ -1426,6 +2546,7 @@ export async function writeSessionEnd(cwd, sessionId, options = {}) {
     if (releaseFailures.length > 0)
         throw releaseFailureError(releaseFailures);
     emitDegradedDurabilityWarning('session pointer end', tracker);
+    return revalidation;
 }
 /** Reset session-scoped HUD/metrics files at launch. */
 export async function resetSessionMetrics(cwd, sessionId) {