oh-my-codex 0.20.3 → 0.21.0

package/dist/mcp/state-paths.js

@@ -1,7 +1,25 @@
 import { delimiter, isAbsolute, join, relative, resolve as resolvePath } from 'path';
-import { existsSync, realpathSync } from 'fs';
+import { existsSync, realpathSync, readFileSync } from 'fs';
 import { readFile, readdir } from 'fs/promises';
-import { isSessionStateUsable, readUsableSessionState, } from '../hooks/session.js';
+import { classifySessionStateLiveness, isSessionStateUsable, } from '../hooks/session.js';
+export const VERIFIED_SESSION_BINDING_FIELDS = [
+    'session_id',
+    'native_session_id',
+    'codex_session_id',
+    'previous_native_session_id',
+    'owner_omx_session_id',
+    'owner_codex_session_id',
+];
+function verifiedSessionAliases(state) {
+    const raw = state;
+    const aliases = {};
+    for (const field of VERIFIED_SESSION_BINDING_FIELDS) {
+        const normalized = normalizeSessionId(raw[field]);
+        if (normalized)
+            aliases[field] = normalized;
+    }
+    return aliases;
+}
 export const SESSION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
 export const STATE_MODE_SEGMENT_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
 const STATE_FILE_SUFFIX = '-state.json';
@@ -14,6 +32,8 @@ const OMX_SESSION_ID_ENV = 'OMX_SESSION_ID';
 export const WRITABLE_STATE_SCOPE_ERRORS = {
     unusableSession: 'Cannot resolve writable state scope: session.json is present but unusable.',
     unboundEnvironment: 'Cannot resolve writable state scope: OMX_SESSION_ID is not bound to session.json.',
+    sessionBindingMismatch: 'Cannot resolve writable state scope: OMX_SESSION_ID does not match the live session recorded in session.json.',
+    scopeChangedDuringWrite: 'Cannot commit the state write: the writable state scope changed while the write was in progress.',
 };
 export function normalizeSessionId(sessionId) {
     if (typeof sessionId !== 'string')
@@ -51,7 +71,7 @@ export function validateStateModeSegment(mode) {
     }
     return normalized;
 }
-function getStateFilename(mode) {
+export function getStateFilename(mode) {
     return `${validateStateModeSegment(mode)}${STATE_FILE_SUFFIX}`;
 }
 export function validateStateFileName(fileName) {
@@ -92,14 +112,14 @@ function convertWslToWindowsPath(raw) {
     const rest = String(m[2] || '').replace(/\//g, '\\');
     return rest ? `${drive}:\\${rest}` : `${drive}:\\`;
 }
-export function resolveWorkingDirectoryForState(workingDirectory) {
+export function resolveWorkingDirectoryForState(workingDirectory, env = process.env) {
     const raw = typeof workingDirectory === 'string' ? workingDirectory.trim() : '';
     if (raw.includes('\0')) {
         throw new Error('workingDirectory contains a NUL byte');
     }
     if (!raw) {
         const cwd = resolvePath(process.cwd());
-        return enforceWorkingDirectoryPolicy(cwd);
+        return enforceWorkingDirectoryPolicy(cwd, env);
     }
     let normalized = raw;
     if (process.platform === 'win32') {
@@ -118,7 +138,7 @@ export function resolveWorkingDirectoryForState(workingDirectory) {
         throw new Error('workingDirectory contains a NUL byte');
     }
     const resolved = resolvePath(normalized);
-    return enforceWorkingDirectoryPolicy(resolved);
+    return enforceWorkingDirectoryPolicy(resolved, env);
 }
 function canonicalizeExistingPath(path) {
     try {
@@ -147,8 +167,8 @@ function canonicalizeExistingPath(path) {
     }
     return path;
 }
-function parseAllowedWorkingDirectoryRoots() {
-    const raw = process.env[WORKDIR_ALLOWLIST_ENV];
+function parseAllowedWorkingDirectoryRoots(env = process.env) {
+    const raw = env[WORKDIR_ALLOWLIST_ENV];
     if (typeof raw !== 'string' || raw.trim() === '')
         return [];
     const roots = raw
@@ -172,8 +192,8 @@ function isWithinRoot(path, root) {
     const rel = relative(root, path);
     return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
 }
-function enforceWorkingDirectoryPolicy(resolvedWorkingDirectory) {
-    const roots = parseAllowedWorkingDirectoryRoots();
+function enforceWorkingDirectoryPolicy(resolvedWorkingDirectory, env = process.env) {
+    const roots = parseAllowedWorkingDirectoryRoots(env);
     if (roots.length === 0)
         return resolvedWorkingDirectory;
     const canonicalWorkingDirectory = canonicalizeExistingPath(resolvedWorkingDirectory);
@@ -183,23 +203,366 @@ function enforceWorkingDirectoryPolicy(resolvedWorkingDirectory) {
     }
     return canonicalWorkingDirectory;
 }
-export function getBaseStateDirWithSource(workingDirectory) {
-    const teamStateRootOverride = process.env[OMX_TEAM_STATE_ROOT_ENV]?.trim();
+function sessionPointerMatchesId(pointer, sessionId) {
+    return [
+        pointer.session_id,
+        pointer.native_session_id,
+        pointer.owner_omx_session_id,
+        pointer.owner_codex_session_id,
+        pointer.codex_session_id,
+    ].some((value) => normalizeSessionId(value) === sessionId);
+}
+function discoverSessionAuthorityBaseStateDir(workingDirectory, env = process.env, onMatch) {
+    const sessionId = normalizeSessionId(env[OMX_SESSION_ID_ENV]);
+    if (!sessionId)
+        return undefined;
+    let current = resolveWorkingDirectoryForState(workingDirectory, env);
+    const observedCwd = canonicalizeExistingPath(current);
+    const allowedRoots = parseAllowedWorkingDirectoryRoots(env);
+    const matches = [];
+    while (true) {
+        const canonicalCurrent = canonicalizeExistingPath(current);
+        if (allowedRoots.length > 0 && !allowedRoots.some((root) => isWithinRoot(canonicalCurrent, root)))
+            break;
+        const candidate = join(current, '.omx', 'state');
+        const canonicalCandidate = canonicalizeExistingPath(candidate);
+        if (allowedRoots.length > 0 && !allowedRoots.some((root) => isWithinRoot(canonicalCandidate, root))) {
+            const parent = resolvePath(current, '..');
+            if (parent === current)
+                break;
+            current = parent;
+            continue;
+        }
+        const pointerPath = join(canonicalCandidate, 'session.json');
+        if (existsSync(pointerPath)) {
+            try {
+                const raw = readFileSync(pointerPath, 'utf8');
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                    const state = parsed;
+                    const recordedCwd = typeof state.cwd === 'string'
+                        ? canonicalizeExistingPath(resolvePath(state.cwd))
+                        : '';
+                    const recordedStateRoot = typeof state.state_root === 'string'
+                        ? canonicalizeExistingPath(resolvePath(state.state_root))
+                        : recordedCwd
+                            ? canonicalizeExistingPath(join(recordedCwd, '.omx', 'state'))
+                            : '';
+                    if (sessionPointerMatchesId(state, sessionId)
+                        && recordedCwd
+                        && recordedStateRoot === canonicalCandidate
+                        && isWithinRoot(observedCwd, recordedCwd)
+                        && isSessionStateUsable(state, recordedCwd)) {
+                        matches.push(canonicalCandidate);
+                        onMatch?.({ baseStateDir: canonicalCandidate, raw, state, recordedCwd });
+                    }
+                }
+            }
+            catch {
+                // Malformed pointers are classified by the normal state-scope resolver.
+            }
+        }
+        const parent = resolvePath(current, '..');
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    const uniqueMatches = [...new Set(matches)];
+    if (uniqueMatches.length > 1) {
+        throw new Error(`Conflicting authoritative state roots for OMX_SESSION_ID ${sessionId}: ${uniqueMatches.join(', ')}`);
+    }
+    return uniqueMatches[0];
+}
+function validateResolvedBaseStateDir(baseStateDir, rootSource, env) {
+    const allowedRoots = parseAllowedWorkingDirectoryRoots(env);
+    if (allowedRoots.length > 0) {
+        const canonicalBaseStateDir = canonicalizeExistingPath(baseStateDir);
+        if (!allowedRoots.some((root) => isWithinRoot(canonicalBaseStateDir, root))) {
+            throw new Error(`State root "${canonicalBaseStateDir}" is outside allowed roots (${WORKDIR_ALLOWLIST_ENV})`);
+        }
+    }
+    return { baseStateDir, rootSource };
+}
+export function getBaseStateDirWithSource(workingDirectory, env = process.env) {
+    const teamStateRootOverride = env[OMX_TEAM_STATE_ROOT_ENV]?.trim();
     if (typeof teamStateRootOverride === 'string' && teamStateRootOverride !== '') {
-        return { baseStateDir: resolveWorkingDirectoryForState(teamStateRootOverride), rootSource: 'team-env' };
+        return validateResolvedBaseStateDir(resolveWorkingDirectoryForState(teamStateRootOverride, env), 'team-env', env);
     }
-    const omxRootOverride = process.env[OMX_ROOT_ENV]?.trim();
+    const omxRootOverride = env[OMX_ROOT_ENV]?.trim();
     if (typeof omxRootOverride === 'string' && omxRootOverride !== '') {
-        return { baseStateDir: join(resolveWorkingDirectoryForState(omxRootOverride), '.omx', 'state'), rootSource: 'omx-root-env' };
+        return validateResolvedBaseStateDir(join(resolveWorkingDirectoryForState(omxRootOverride, env), '.omx', 'state'), 'omx-root-env', env);
     }
-    const omxStateRootOverride = process.env[OMX_STATE_ROOT_ENV]?.trim();
+    const omxStateRootOverride = env[OMX_STATE_ROOT_ENV]?.trim();
     if (typeof omxStateRootOverride === 'string' && omxStateRootOverride !== '') {
-        return { baseStateDir: join(resolveWorkingDirectoryForState(omxStateRootOverride), '.omx', 'state'), rootSource: 'omx-state-root-env' };
+        return validateResolvedBaseStateDir(join(resolveWorkingDirectoryForState(omxStateRootOverride, env), '.omx', 'state'), 'omx-state-root-env', env);
     }
-    return { baseStateDir: join(resolveWorkingDirectoryForState(workingDirectory), '.omx', 'state'), rootSource: 'cwd-default' };
+    const sessionAuthority = discoverSessionAuthorityBaseStateDir(workingDirectory, env);
+    if (sessionAuthority) {
+        return validateResolvedBaseStateDir(sessionAuthority, 'session-authority', env);
+    }
+    return validateResolvedBaseStateDir(join(resolveWorkingDirectoryForState(workingDirectory, env), '.omx', 'state'), 'cwd-default', env);
+}
+export function getBaseStateDir(workingDirectory, env = process.env) {
+    return getBaseStateDirWithSource(workingDirectory, env).baseStateDir;
 }
-export function getBaseStateDir(workingDirectory) {
-    return getBaseStateDirWithSource(workingDirectory).baseStateDir;
+function bindingRootSelector(env) {
+    if (typeof env[OMX_TEAM_STATE_ROOT_ENV] === 'string' && env[OMX_TEAM_STATE_ROOT_ENV].trim() !== '') {
+        return { source: 'team-env', selector: OMX_TEAM_STATE_ROOT_ENV };
+    }
+    if (typeof env[OMX_ROOT_ENV] === 'string' && env[OMX_ROOT_ENV].trim() !== '') {
+        return { source: 'omx-root-env', selector: OMX_ROOT_ENV };
+    }
+    if (typeof env[OMX_STATE_ROOT_ENV] === 'string' && env[OMX_STATE_ROOT_ENV].trim() !== '') {
+        return { source: 'omx-state-root-env', selector: OMX_STATE_ROOT_ENV };
+    }
+    return undefined;
+}
+/**
+ * Read the selected session pointer once and classify its canonical binding.
+ * This is intentionally read-only: it never probes fallback roots, repairs
+ * pointers, touches tmux, or mutates the supplied environment.
+ */
+export async function readCanonicalSessionBindingSnapshot(workingDirectory, env = process.env) {
+    let cwd;
+    try {
+        cwd = resolveWorkingDirectoryForState(workingDirectory, env);
+    }
+    catch {
+        let fallbackCwd = process.cwd();
+        try {
+            if (typeof workingDirectory === 'string' && workingDirectory.trim())
+                fallbackCwd = resolvePath(workingDirectory);
+        }
+        catch {
+            // Keep the process cwd as a safe diagnostic anchor.
+        }
+        return {
+            cwd: fallbackCwd,
+            ...(bindingRootSelector(env) ? { rootSource: bindingRootSelector(env)?.source } : normalizeSessionId(env[OMX_SESSION_ID_ENV]) ? { rootSource: 'session-authority' } : {}),
+            status: 'resolution-error',
+            verifiedAliases: {},
+        };
+    }
+    let resolved;
+    let selectedObservation;
+    try {
+        const teamStateRootOverride = env[OMX_TEAM_STATE_ROOT_ENV]?.trim();
+        const omxRootOverride = env[OMX_ROOT_ENV]?.trim();
+        const omxStateRootOverride = env[OMX_STATE_ROOT_ENV]?.trim();
+        if (teamStateRootOverride) {
+            resolved = validateResolvedBaseStateDir(resolveWorkingDirectoryForState(teamStateRootOverride, env), 'team-env', env);
+        }
+        else if (omxRootOverride) {
+            resolved = validateResolvedBaseStateDir(join(resolveWorkingDirectoryForState(omxRootOverride, env), '.omx', 'state'), 'omx-root-env', env);
+        }
+        else if (omxStateRootOverride) {
+            resolved = validateResolvedBaseStateDir(join(resolveWorkingDirectoryForState(omxStateRootOverride, env), '.omx', 'state'), 'omx-state-root-env', env);
+        }
+        else {
+            const sessionAuthority = discoverSessionAuthorityBaseStateDir(cwd, env, (observation) => {
+                selectedObservation = observation;
+            });
+            if (sessionAuthority) {
+                resolved = validateResolvedBaseStateDir(sessionAuthority, 'session-authority', env);
+            }
+            else {
+                resolved = validateResolvedBaseStateDir(join(cwd, '.omx', 'state'), 'cwd-default', env);
+            }
+        }
+    }
+    catch {
+        const selector = bindingRootSelector(env);
+        return {
+            cwd,
+            ...(selector ? { rootSource: selector.source } : normalizeSessionId(env[OMX_SESSION_ID_ENV]) ? { rootSource: 'session-authority' } : {}),
+            status: 'resolution-error',
+            verifiedAliases: {},
+        };
+    }
+    const baseStateDir = resolved.baseStateDir;
+    const selectedSessionJson = join(baseStateDir, 'session.json');
+    let raw;
+    let parsed;
+    if (selectedObservation && selectedObservation.baseStateDir === baseStateDir) {
+        raw = selectedObservation.raw;
+        parsed = selectedObservation.state;
+    }
+    else {
+        try {
+            raw = await readFile(selectedSessionJson, 'utf-8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return {
+                    cwd,
+                    baseStateDir,
+                    rootSource: resolved.rootSource,
+                    selectedSessionJson,
+                    status: 'absent',
+                    verifiedAliases: {},
+                };
+            }
+            return {
+                cwd,
+                baseStateDir,
+                rootSource: resolved.rootSource,
+                selectedSessionJson,
+                status: 'read-error',
+                verifiedAliases: {},
+            };
+        }
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return {
+                cwd,
+                baseStateDir,
+                rootSource: resolved.rootSource,
+                selectedSessionJson,
+                raw,
+                status: 'malformed',
+                verifiedAliases: {},
+            };
+        }
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return {
+            cwd,
+            baseStateDir,
+            rootSource: resolved.rootSource,
+            selectedSessionJson,
+            raw,
+            status: 'malformed',
+            verifiedAliases: {},
+        };
+    }
+    const state = parsed;
+    const aliases = verifiedSessionAliases(state);
+    if (!aliases.session_id) {
+        return {
+            cwd,
+            baseStateDir,
+            rootSource: resolved.rootSource,
+            selectedSessionJson,
+            raw,
+            state,
+            status: 'malformed',
+            verifiedAliases: aliases,
+        };
+    }
+    const recordedCwdRaw = typeof state.cwd === 'string' ? state.cwd.trim() : '';
+    if (Object.prototype.hasOwnProperty.call(state, 'state_root') && typeof state.state_root === 'string' && state.state_root.trim() === '') {
+        return {
+            cwd,
+            baseStateDir,
+            rootSource: resolved.rootSource,
+            selectedSessionJson,
+            raw,
+            state,
+            status: 'malformed',
+            verifiedAliases: aliases,
+        };
+    }
+    if (!recordedCwdRaw) {
+        return {
+            cwd,
+            baseStateDir,
+            rootSource: resolved.rootSource,
+            selectedSessionJson,
+            raw,
+            state,
+            status: 'missing-recorded-cwd',
+            verifiedAliases: aliases,
+        };
+    }
+    let recordedCwd;
+    let canonicalBaseStateDir;
+    let canonicalObservedCwd;
+    try {
+        recordedCwd = canonicalizeExistingPath(resolvePath(recordedCwdRaw));
+        canonicalBaseStateDir = canonicalizeExistingPath(baseStateDir);
+        canonicalObservedCwd = canonicalizeExistingPath(resolvePath(cwd));
+    }
+    catch {
+        return {
+            cwd,
+            baseStateDir,
+            rootSource: resolved.rootSource,
+            selectedSessionJson,
+            raw,
+            state,
+            status: 'read-error',
+            verifiedAliases: aliases,
+        };
+    }
+    const explicitRoot = typeof state.state_root === 'string' && state.state_root.trim() !== ''
+        ? state.state_root.trim()
+        : undefined;
+    let recordedStateRoot;
+    try {
+        recordedStateRoot = explicitRoot
+            ? canonicalizeExistingPath(resolvePath(explicitRoot))
+            : canonicalizeExistingPath(join(recordedCwd, '.omx', 'state'));
+    }
+    catch {
+        return {
+            cwd,
+            baseStateDir,
+            rootSource: resolved.rootSource,
+            selectedSessionJson,
+            recordedCwd,
+            raw,
+            state,
+            status: 'root-mismatch',
+            verifiedAliases: aliases,
+        };
+    }
+    if (recordedStateRoot !== canonicalBaseStateDir) {
+        return {
+            cwd,
+            baseStateDir,
+            rootSource: resolved.rootSource,
+            selectedSessionJson,
+            recordedCwd,
+            raw,
+            state,
+            status: 'root-mismatch',
+            verifiedAliases: aliases,
+        };
+    }
+    if (!isWithinRoot(canonicalObservedCwd, recordedCwd)) {
+        return {
+            cwd,
+            baseStateDir,
+            rootSource: resolved.rootSource,
+            selectedSessionJson,
+            recordedCwd,
+            raw,
+            state,
+            status: 'foreign-cwd',
+            verifiedAliases: aliases,
+        };
+    }
+    let liveness;
+    try {
+        liveness = classifySessionStateLiveness(state);
+    }
+    catch {
+        liveness = 'identity-indeterminate';
+    }
+    return {
+        cwd,
+        baseStateDir,
+        rootSource: resolved.rootSource,
+        selectedSessionJson,
+        recordedCwd,
+        raw,
+        state,
+        liveness,
+        status: liveness,
+        verifiedAliases: aliases,
+    };
 }
 export function getStateDir(workingDirectory, sessionId) {
     const base = getBaseStateDir(workingDirectory);
@@ -225,22 +588,45 @@ function resolveCanonicalSessionId(candidate, metadata) {
         return undefined;
     if (!metadata)
         return candidate;
-    return metadata.nativeSessionAliases.includes(candidate) || metadata.ownerOmxSessionId === candidate
+    return metadata.nativeSessionAliases.includes(candidate)
+        || metadata.ownerOmxSessionId === candidate
+        || metadata.ownerCodexSessionId === candidate
         ? metadata.sessionId
         : candidate;
 }
-async function readUsableSessionStateFromBaseStateDir(cwd, baseStateDir = getBaseStateDir(cwd)) {
-    const sessionPath = join(baseStateDir, 'session.json');
-    if (!existsSync(sessionPath))
+/**
+ * Read the selected session.json once and return the parsed snapshot only
+ * when it holds full selected-root authority for this exact base state
+ * directory: a nonempty recorded cwd that contains the observed cwd, and a
+ * recorded state_root canonical-equal to the selected base (with the
+ * historical cwd-derived fallback when state_root is absent). Usability/
+ * liveness is deliberately NOT checked here so stale-dead recovery can
+ * evaluate authority AND liveness from the same immutable bytes. A malformed
+ * or non-authoritative pointer returns null (fail closed); unexpected read
+ * I/O errors propagate instead of being collapsed into a generic classification.
+ */
+async function readAuthoritativeSessionSnapshotFromBaseStateDir(cwd, baseStateDir, selectedSnapshot) {
+    const snapshot = selectedSnapshot ?? await readCanonicalSessionBindingSnapshot(cwd);
+    const selectedBaseStateDir = baseStateDir ?? snapshot.baseStateDir;
+    if (!selectedBaseStateDir)
         return null;
-    try {
-        const content = await readFile(sessionPath, 'utf-8');
-        const state = JSON.parse(content);
-        return isSessionStateUsable(state, cwd) ? state : null;
+    if (snapshot.status === 'read-error') {
+        throw new Error('selected session pointer read failed');
     }
-    catch {
+    if (!snapshot.raw
+        || !snapshot.state
+        || !snapshot.recordedCwd
+        || !snapshot.baseStateDir
+        || canonicalizeExistingPath(snapshot.baseStateDir) !== canonicalizeExistingPath(selectedBaseStateDir)
+        || !['usable', 'stale-dead', 'identity-indeterminate'].includes(snapshot.status)) {
         return null;
     }
+    return {
+        baseStateDir: selectedBaseStateDir,
+        raw: snapshot.raw,
+        state: snapshot.state,
+        recordedCwd: snapshot.recordedCwd,
+    };
 }
 function normalizeSessionMetadata(state, sourcePath) {
     const sessionId = normalizeSessionId(state?.session_id);
@@ -283,16 +669,33 @@ function normalizeSessionMetadata(state, sourcePath) {
         ...(sourcePath ? { sourcePath } : {}),
     };
 }
-async function readSessionMetadataFromBaseStateDir(cwd, baseStateDir = getBaseStateDir(cwd)) {
-    const sessionPath = join(baseStateDir, 'session.json');
-    const session = await readUsableSessionStateFromBaseStateDir(cwd, baseStateDir);
+export async function readSessionMetadataFromBaseStateDir(cwd, baseStateDir, options = {}) {
+    const selectedBaseStateDir = baseStateDir ?? getBaseStateDir(cwd);
+    const snapshot = await readCanonicalSessionBindingSnapshot(cwd, options.allowLegacyBoundHud
+        ? { ...process.env, [OMX_TEAM_STATE_ROOT_ENV]: selectedBaseStateDir, [OMX_ROOT_ENV]: '', [OMX_STATE_ROOT_ENV]: '' }
+        : process.env);
+    if (!selectedBaseStateDir)
+        return undefined;
+    const sessionPath = join(selectedBaseStateDir, 'session.json');
+    const authoritative = await readAuthoritativeSessionSnapshotFromBaseStateDir(cwd, selectedBaseStateDir, snapshot);
+    const session = authoritative && isSessionStateUsable(authoritative.state, authoritative.recordedCwd)
+        ? authoritative.state
+        : options.allowLegacyBoundHud
+            && snapshot.status === 'identity-indeterminate'
+            && snapshot.state
+            && snapshot.baseStateDir
+            && canonicalizeExistingPath(snapshot.baseStateDir) === canonicalizeExistingPath(selectedBaseStateDir)
+            ? snapshot.state
+            : null;
     return normalizeSessionMetadata(session, sessionPath);
 }
 export async function readCurrentSessionId(workingDirectory) {
     const cwd = resolveWorkingDirectoryForState(workingDirectory);
-    const baseStateDir = getBaseStateDir(cwd);
+    const snapshot = await readCanonicalSessionBindingSnapshot(cwd);
+    const baseStateDir = snapshot.baseStateDir ?? getBaseStateDir(cwd);
     const envSessionId = readSessionIdFromEnvironment();
-    const metadata = await readSessionMetadataFromBaseStateDir(cwd, baseStateDir);
+    const authoritative = await readAuthoritativeSessionSnapshotFromBaseStateDir(cwd, baseStateDir, snapshot);
+    const metadata = normalizeSessionMetadata(authoritative && isSessionStateUsable(authoritative.state, authoritative.recordedCwd) ? authoritative.state : null, join(baseStateDir, 'session.json'));
     if (envSessionId)
         return resolveCanonicalSessionId(envSessionId, metadata);
     if (metadata?.sessionId)
@@ -301,25 +704,59 @@ export async function readCurrentSessionId(workingDirectory) {
     if (resolvePath(baseStateDir) !== resolvePath(localStateDir)) {
         return undefined;
     }
-    return (await readUsableSessionState(cwd))?.session_id;
+    if (authoritative && isSessionStateUsable(authoritative.state, authoritative.recordedCwd)) {
+        return authoritative.state.session_id;
+    }
+    // Legacy HUD readers may carry only a local session_id pointer. This is never
+    // used for explicit, foreign, malformed, or otherwise contaminated roots.
+    if (snapshot.status !== 'missing-recorded-cwd')
+        return undefined;
+    try {
+        const raw = JSON.parse(await readFile(join(baseStateDir, 'session.json'), 'utf-8'));
+        return typeof raw.session_id === 'string' ? normalizeSessionId(raw.session_id) : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
 function isKnownSessionAlias(sessionId, metadata) {
     return metadata.nativeSessionAliases.includes(sessionId)
         || metadata.ownerOmxSessionId === sessionId
         || metadata.ownerCodexSessionId === sessionId;
 }
+let selectedPointerRecoveryHookForTests;
+let writableScopeRevalidationHookForTests;
+let selectedDecisionSnapshotReadHookForTests;
+let recoveryStabilityRereadHookForTests;
+export function __setWritableStateScopeTestHooksForTests(hooks) {
+    selectedPointerRecoveryHookForTests = hooks.beforeRecoveryReread;
+    writableScopeRevalidationHookForTests = hooks.beforeScopeRevalidation;
+    selectedDecisionSnapshotReadHookForTests = hooks.onSelectedDecisionSnapshotRead;
+    recoveryStabilityRereadHookForTests = hooks.onRecoveryStabilityReread;
+}
 /**
  * Writable scope precedence:
  * - explicit session_id preserves explicit fork writes;
  * - a usable session.json supplies the only implicit session scope;
  * - OMX_SESSION_ID may bind a known alias only when the live tmux pane proves
  *   the canonical session tag;
+ * - a stale-dead session.json yields to an explicit exact-current
+ *   OMX_SESSION_ID binding (the dead owner holds no authority; SessionStart
+ *   remains the only pointer writer);
+ * - an identity-indeterminate session.json may recover only when OMX_SESSION_ID
+ *   exactly matches the pointer's own session_id (the owner may still be alive,
+ *   so unlike stale-dead recovery, no looser validated binding is accepted);
  * - root writes are allowed only when session.json is absent.
  */
 export async function resolveWritableStateScope(workingDirectory, explicitSessionId) {
     const cwd = resolveWorkingDirectoryForState(workingDirectory);
-    const baseStateDir = getBaseStateDir(cwd);
-    const metadata = await readSessionMetadataFromBaseStateDir(cwd, baseStateDir);
+    const canonicalSnapshot = await readCanonicalSessionBindingSnapshot(cwd);
+    const baseStateDir = canonicalSnapshot.baseStateDir ?? getBaseStateDir(cwd);
+    let selectedDecisionSnapshotReadOrdinalForTests = 0;
+    let recoveryStabilityRereadOrdinalForTests = 0;
+    const snapshot = await readAuthoritativeSessionSnapshotFromBaseStateDir(cwd, baseStateDir, canonicalSnapshot);
+    const liveness = snapshot ? classifySessionStateLiveness(snapshot.state) : undefined;
+    const metadata = normalizeSessionMetadata(snapshot && liveness === 'usable' ? snapshot.state : null, join(baseStateDir, 'session.json'));
     const validatedExplicit = validateSessionId(explicitSessionId);
     if (validatedExplicit) {
         const sessionId = resolveCanonicalSessionId(validatedExplicit, metadata) ?? validatedExplicit;
@@ -330,7 +767,43 @@ export async function resolveWritableStateScope(workingDirectory, explicitSessio
         };
     }
     if (!metadata) {
-        if (existsSync(join(baseStateDir, 'session.json'))) {
+        const sessionPath = join(baseStateDir, 'session.json');
+        if (existsSync(sessionPath)) {
+            const envSessionId = normalizeSessionId(process.env[OMX_SESSION_ID_ENV]);
+            if (snapshot && selectedDecisionSnapshotReadHookForTests) {
+                selectedDecisionSnapshotReadHookForTests({
+                    ordinal: ++selectedDecisionSnapshotReadOrdinalForTests,
+                    raw: snapshot.raw,
+                });
+            }
+            if (snapshot && envSessionId) {
+                const canonicalPointerSessionId = normalizeSessionId(snapshot.state.session_id);
+                const recoveryEligible = Boolean(canonicalPointerSessionId
+                    && (liveness === 'stale-dead'
+                        || (liveness === 'identity-indeterminate' && envSessionId === canonicalPointerSessionId)));
+                if (recoveryEligible) {
+                    if (selectedPointerRecoveryHookForTests)
+                        await selectedPointerRecoveryHookForTests();
+                    const reread = await readFile(sessionPath, 'utf-8').catch((error) => {
+                        if (error.code === 'ENOENT')
+                            return undefined;
+                        throw error;
+                    });
+                    if (recoveryStabilityRereadHookForTests) {
+                        recoveryStabilityRereadHookForTests({
+                            ordinal: ++recoveryStabilityRereadOrdinalForTests,
+                            raw: reread,
+                        });
+                    }
+                    if (reread === snapshot.raw) {
+                        return {
+                            source: 'session',
+                            sessionId: envSessionId,
+                            stateDir: join(baseStateDir, 'sessions', envSessionId),
+                        };
+                    }
+                }
+            }
             throw new Error(WRITABLE_STATE_SCOPE_ERRORS.unusableSession);
         }
         if (normalizeSessionId(process.env[OMX_SESSION_ID_ENV])) {
@@ -350,7 +823,7 @@ export async function resolveWritableStateScope(workingDirectory, explicitSessio
         };
     }
     if (!isKnownSessionAlias(envSessionId, metadata)) {
-        throw new Error(WRITABLE_STATE_SCOPE_ERRORS.unboundEnvironment);
+        throw new Error(WRITABLE_STATE_SCOPE_ERRORS.sessionBindingMismatch);
     }
     return {
         source: 'session',
@@ -358,6 +831,36 @@ export async function resolveWritableStateScope(workingDirectory, explicitSessio
         stateDir: join(baseStateDir, 'sessions', metadata.sessionId),
     };
 }
+/**
+ * Point-in-time check performed immediately before the caller's commit. It
+ * reduces, but does not eliminate, the window for a pointer or root
+ * publication to move the selected target: one can still land after this
+ * check returns and before the caller's write, rename, or unlink. Multi-file
+ * sequences are not atomic.
+ */
+export async function assertWritableStateScopeUnchanged(workingDirectory, explicitSessionId, expected, expectedBaseStateDir, event) {
+    if (writableScopeRevalidationHookForTests)
+        await writableScopeRevalidationHookForTests(event);
+    const current = await resolveWritableStateScope(workingDirectory, explicitSessionId);
+    const currentBaseStateDir = getBaseStateDirWithSource(workingDirectory).baseStateDir;
+    if (current.source !== expected.source
+        || current.sessionId !== expected.sessionId
+        || current.stateDir !== expected.stateDir
+        || currentBaseStateDir !== expectedBaseStateDir) {
+        throw new Error(WRITABLE_STATE_SCOPE_ERRORS.scopeChangedDuringWrite);
+    }
+}
+export function createWritableCommitRevalidator(options) {
+    let commitOrdinal = 0;
+    return async (attempt) => {
+        const event = {
+            operation: options.operation,
+            commitOrdinal: ++commitOrdinal,
+            ...attempt,
+        };
+        await assertWritableStateScopeUnchanged(options.cwd, options.explicitSessionId, options.capturedScope, options.baseStateDir, event);
+    };
+}
 export async function resolveStateScope(workingDirectory, explicitSessionId) {
     const cwd = resolveWorkingDirectoryForState(workingDirectory);
     const baseStateDir = getBaseStateDir(cwd);
@@ -516,7 +1019,7 @@ export async function getAllScopedStateDirs(workingDirectory) {
     return [getBaseStateDir(workingDirectory), ...(await getAllSessionScopedStateDirs(workingDirectory))];
 }
 export function isModeStateFilename(filename) {
-    return filename.endsWith(STATE_FILE_SUFFIX) && filename !== 'session.json';
+    return filename.endsWith(STATE_FILE_SUFFIX) && filename !== 'session.json' && filename !== 'run-state.json';
 }
 async function listModeStateFilesInDir(dir, scope) {
     if (!existsSync(dir))