oh-my-codex 0.20.0 → 0.20.2

package/dist/subagents/tracker.js

@@ -1,16 +1,47 @@
-import { existsSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { getBaseStateDir } from '../state/paths.js';
+import { randomUUID } from 'node:crypto';
+import { closeSync, existsSync, ftruncateSync, linkSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from 'node:fs';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { AGENT_DEFINITIONS } from '../agents/definitions.js';
+import { getBaseStateDir, getBaseStateDirWithSource } from '../state/paths.js';
+import { canonicalizeOriginCwd } from '../leader/contract.js';
+import { codexAgentsDir, projectCodexAgentsDir } from '../utils/paths.js';
 export const SUBAGENT_TRACKING_SCHEMA_VERSION = 1;
 export const DEFAULT_SUBAGENT_ACTIVE_WINDOW_MS = 120_000;
+export const OMX_ADAPTED_PROVENANCE = 'omx_adapted';
+export const NATIVE_SUBAGENT_PROVENANCE = 'native_subagent';
+const KNOWN_TYPED_AGENT_ROLES = new Set(Object.keys(AGENT_DEFINITIONS).map((role) => role.toLowerCase()));
 export function subagentTrackingPath(cwd) {
     return join(getBaseStateDir(cwd), 'subagent-tracking.json');
 }
+export function resolveInstalledRoleName(role, codexHomeOverride) {
+    const normalizedRole = role.trim().toLowerCase();
+    if (!normalizedRole)
+        return null;
+    if (KNOWN_TYPED_AGENT_ROLES.has(normalizedRole))
+        return normalizedRole;
+    for (const agentsDir of [codexAgentsDir(codexHomeOverride), projectCodexAgentsDir()]) {
+        try {
+            for (const entry of readdirSync(agentsDir, { withFileTypes: true })) {
+                if (!entry.isFile() || !entry.name.endsWith('.toml'))
+                    continue;
+                const installedRole = entry.name.slice(0, -'.toml'.length).trim().toLowerCase();
+                if (installedRole === normalizedRole)
+                    return installedRole;
+            }
+        }
+        catch {
+            // Missing or unreadable agent directories do not invalidate built-in roles.
+        }
+    }
+    return null;
+}
 export function createSubagentTrackingState() {
     return {
         schemaVersion: SUBAGENT_TRACKING_SCHEMA_VERSION,
         sessions: {},
+        pending_role_intents: [],
     };
 }
 function normalizeSubagentStatus(value) {
@@ -88,6 +119,40 @@ export function isTrustedSubagentThread(session, threadId) {
         return false;
     return session.threads[normalizedThreadId]?.kind === 'subagent';
 }
+function normalizePendingRoleIntent(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const candidate = value;
+    const role = readOptionalTrimmedString(candidate.role);
+    const sessionId = readOptionalTrimmedString(candidate.session_id);
+    const parentThreadId = readOptionalTrimmedString(candidate.parent_thread_id);
+    const createdAt = readOptionalTrimmedString(candidate.created_at);
+    const expiresAt = readOptionalTrimmedString(candidate.expires_at);
+    if (!role || !sessionId || !parentThreadId || !Object.hasOwn(candidate, 'correlation_token') || !createdAt || !expiresAt)
+        return null;
+    if (!Number.isFinite(Date.parse(createdAt)) || !Number.isFinite(Date.parse(expiresAt)))
+        return null;
+    const bindingState = candidate.binding_state === 'bound' ? 'bound' : undefined;
+    const boundAt = readOptionalTrimmedString(candidate.bound_at);
+    const hasValidBoundAt = Boolean(boundAt && Number.isFinite(Date.parse(boundAt)));
+    const originCwd = readOptionalTrimmedString(candidate.origin_cwd);
+    return {
+        role,
+        session_id: sessionId,
+        parent_thread_id: parentThreadId,
+        // Bound journals are durable security records. Retain malformed credentials verbatim so
+        // completion can reject them rather than silently converting them into claimant-less data.
+        correlation_token: candidate.correlation_token,
+        created_at: createdAt,
+        expires_at: expiresAt,
+        ...(bindingState ? { binding_state: bindingState } : {}),
+        ...(bindingState && Object.hasOwn(candidate, 'binding_claimant_token')
+            ? { binding_claimant_token: candidate.binding_claimant_token }
+            : {}),
+        ...(bindingState && hasValidBoundAt ? { bound_at: boundAt } : {}),
+        ...(originCwd ? { origin_cwd: originCwd } : {}),
+    };
+}
 export function normalizeSubagentTrackingState(input) {
     const base = createSubagentTrackingState();
     if (!input || typeof input !== 'object')
@@ -102,9 +167,7 @@ export function normalizeSubagentTrackingState(input) {
             if (!rawThread || typeof rawThread !== 'object')
                 continue;
             const candidate = rawThread;
-            const normalizedThreadId = typeof candidate.thread_id === 'string' && candidate.thread_id.trim().length > 0
-                ? candidate.thread_id.trim()
-                : threadId.trim();
+            const normalizedThreadId = typeof candidate.thread_id === 'string' && candidate.thread_id.trim().length > 0 ? candidate.thread_id.trim() : threadId.trim();
             if (!normalizedThreadId)
                 continue;
             const kind = candidate.kind === 'leader' ? 'leader' : 'subagent';
@@ -113,32 +176,31 @@ export function normalizeSubagentTrackingState(input) {
                 : typeof candidate.last_seen_at === 'string' && candidate.last_seen_at.trim().length > 0
                     ? candidate.last_seen_at
                     : new Date(0).toISOString();
-            const lastSeenAt = typeof candidate.last_seen_at === 'string' && candidate.last_seen_at.trim().length > 0
-                ? candidate.last_seen_at
-                : firstSeenAt;
+            const lastSeenAt = typeof candidate.last_seen_at === 'string' && candidate.last_seen_at.trim().length > 0 ? candidate.last_seen_at : firstSeenAt;
             threads[normalizedThreadId] = {
                 thread_id: normalizedThreadId,
                 kind,
                 first_seen_at: firstSeenAt,
                 last_seen_at: lastSeenAt,
-                ...(typeof candidate.last_turn_id === 'string' && candidate.last_turn_id.trim().length > 0
-                    ? { last_turn_id: candidate.last_turn_id }
-                    : {}),
-                ...(typeof candidate.completed_at === 'string' && candidate.completed_at.trim().length > 0
-                    ? { completed_at: candidate.completed_at }
-                    : {}),
+                ...(typeof candidate.last_turn_id === 'string' && candidate.last_turn_id.trim().length > 0 ? { last_turn_id: candidate.last_turn_id } : {}),
+                ...(typeof candidate.completed_at === 'string' && candidate.completed_at.trim().length > 0 ? { completed_at: candidate.completed_at } : {}),
                 ...(typeof candidate.last_completed_turn_id === 'string' && candidate.last_completed_turn_id.trim().length > 0
                     ? { last_completed_turn_id: candidate.last_completed_turn_id }
                     : {}),
-                turn_count: typeof candidate.turn_count === 'number' && Number.isFinite(candidate.turn_count) && candidate.turn_count > 0
-                    ? candidate.turn_count
-                    : 1,
+                turn_count: typeof candidate.turn_count === 'number' && Number.isFinite(candidate.turn_count) && candidate.turn_count > 0 ? candidate.turn_count : 1,
                 ...(typeof candidate.mode === 'string' && candidate.mode.trim().length > 0 ? { mode: candidate.mode } : {}),
                 ...(typeof candidate.role === 'string' && candidate.role.trim().length > 0 ? { role: candidate.role.trim() } : {}),
+                ...(typeof candidate.provenance_kind === 'string' && candidate.provenance_kind.trim().length > 0
+                    ? { provenance_kind: candidate.provenance_kind.trim() }
+                    : {}),
                 ...(typeof candidate.lane_id === 'string' && candidate.lane_id.trim().length > 0 ? { lane_id: candidate.lane_id.trim() } : {}),
                 ...(typeof candidate.scope === 'string' && candidate.scope.trim().length > 0 ? { scope: candidate.scope.trim() } : {}),
-                ...(typeof candidate.agent_nickname === 'string' && candidate.agent_nickname.trim().length > 0 ? { agent_nickname: candidate.agent_nickname.trim() } : {}),
-                ...(typeof candidate.completion_source === 'string' && candidate.completion_source.trim().length > 0 ? { completion_source: candidate.completion_source } : {}),
+                ...(typeof candidate.agent_nickname === 'string' && candidate.agent_nickname.trim().length > 0
+                    ? { agent_nickname: candidate.agent_nickname.trim() }
+                    : {}),
+                ...(typeof candidate.completion_source === 'string' && candidate.completion_source.trim().length > 0
+                    ? { completion_source: candidate.completion_source }
+                    : {}),
                 ...(normalizeSubagentStatus(candidate.status) ? { status: normalizeSubagentStatus(candidate.status) } : {}),
                 ...(typeof candidate.last_handoff_summary === 'string' && candidate.last_handoff_summary.trim().length > 0
                     ? { last_handoff_summary: candidate.last_handoff_summary.trim() }
@@ -158,8 +220,12 @@ export function normalizeSubagentTrackingState(input) {
             };
         }
         const sessionCandidate = rawSession;
-        const leaderThreadId = typeof sessionCandidate.leader_thread_id === 'string'
-            ? sessionCandidate.leader_thread_id.trim() || undefined
+        const leaderThreadId = typeof sessionCandidate.leader_thread_id === 'string' ? sessionCandidate.leader_thread_id.trim() || undefined : undefined;
+        const leaderAttestedAt = typeof sessionCandidate.leader_attested_at === 'string' && sessionCandidate.leader_attested_at.trim().length > 0
+            ? sessionCandidate.leader_attested_at.trim()
+            : undefined;
+        const leaderAttestSource = typeof sessionCandidate.leader_attest_source === 'string' && sessionCandidate.leader_attest_source.trim().length > 0
+            ? sessionCandidate.leader_attest_source.trim()
             : undefined;
         const updatedAt = typeof sessionCandidate.updated_at === 'string' && sessionCandidate.updated_at.trim().length > 0
             ? sessionCandidate.updated_at
@@ -167,15 +233,437 @@ export function normalizeSubagentTrackingState(input) {
         sessions[sessionId] = {
             session_id: sessionId,
             leader_thread_id: leaderThreadId,
+            ...(leaderAttestedAt ? { leader_attested_at: leaderAttestedAt } : {}),
+            ...(leaderAttestSource ? { leader_attest_source: leaderAttestSource } : {}),
             updated_at: updatedAt,
             threads,
         };
     }
+    const pendingRoleIntents = Array.isArray(parsed.pending_role_intents)
+        ? parsed.pending_role_intents.map((intent) => normalizePendingRoleIntent(intent)).filter((intent) => intent !== null)
+        : [];
     return {
         schemaVersion: SUBAGENT_TRACKING_SCHEMA_VERSION,
         sessions,
+        pending_role_intents: pendingRoleIntents,
     };
 }
+function atomicTrackingTempPath(path) {
+    return `${path}.${process.pid}.${randomUUID()}.tmp`;
+}
+export const DEFAULT_CROSS_PROCESS_LOCK_MAX_ATTEMPTS = 80;
+export const DEFAULT_CROSS_PROCESS_LOCK_RETRY_MS = 2;
+export const CROSS_PROCESS_LOCK_LEASE_MS = 60_000;
+const crossProcessLockWaitArray = new Int32Array(new SharedArrayBuffer(4));
+export class CrossProcessLockLostError extends Error {
+    constructor(lockPath) {
+        super(`Lost cross-process lock ownership at ${lockPath}`);
+        this.name = 'CrossProcessLockLostError';
+    }
+}
+export function crossProcessLockPath(resourcePath) {
+    return `${resourcePath}.lock`;
+}
+function sleepForCrossProcessLockSync(durationMs) {
+    Atomics.wait(crossProcessLockWaitArray, 0, 0, durationMs);
+}
+export function readProcessStartIdentity(pid) {
+    if (process.platform !== 'linux')
+        return undefined;
+    try {
+        const stat = readFileSync(`/proc/${pid}/stat`, 'utf-8');
+        const closingParenthesis = stat.lastIndexOf(')');
+        const fields = stat.slice(closingParenthesis + 1).trim().split(/\s+/);
+        const starttime = fields[19];
+        const bootId = readFileSync('/proc/sys/kernel/random/boot_id', 'utf-8').trim();
+        if (closingParenthesis < 0 || !starttime || !/^\d+$/.test(starttime) || !bootId)
+            return undefined;
+        return `${bootId}:${starttime}`;
+    }
+    catch {
+        return undefined;
+    }
+}
+function createCrossProcessLockClaim(token) {
+    const pidStartId = readProcessStartIdentity(process.pid);
+    return {
+        token,
+        pid: process.pid,
+        host: hostname(),
+        acquiredAtMs: Date.now(),
+        ...(pidStartId ? { pidStartId } : {}),
+    };
+}
+function serializeCrossProcessLockClaim(claim) {
+    return `${JSON.stringify({
+        token: claim.token,
+        pid: claim.pid,
+        host: claim.host,
+        acquired_at: new Date(claim.acquiredAtMs).toISOString(),
+        ...(claim.pidStartId ? { pid_start_id: claim.pidStartId } : {}),
+    })}\n`;
+}
+function readCrossProcessLockState(lockPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(lockPath, 'utf-8'));
+        const token = typeof parsed.token === 'string' && parsed.token === parsed.token.trim() && parsed.token ? parsed.token : undefined;
+        const pid = typeof parsed.pid === 'number' && Number.isSafeInteger(parsed.pid) && parsed.pid > 0 ? parsed.pid : undefined;
+        const host = typeof parsed.host === 'string' && parsed.host.trim() ? parsed.host : undefined;
+        const acquiredAtMs = typeof parsed.acquired_at === 'string' ? Date.parse(parsed.acquired_at) : Number.NaN;
+        const pidStartId = parsed.pid_start_id === undefined
+            ? undefined
+            : typeof parsed.pid_start_id === 'string' && parsed.pid_start_id.trim()
+                ? parsed.pid_start_id
+                : null;
+        if (!token || !pid || !host || !Number.isFinite(acquiredAtMs) || pidStartId === null)
+            return { kind: 'malformed' };
+        return {
+            kind: 'claim',
+            claim: { token, pid, host, acquiredAtMs, ...(pidStartId ? { pidStartId } : {}) },
+        };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { kind: 'missing' };
+        return { kind: 'malformed' };
+    }
+}
+function isCrossProcessLockOwnerDead(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === 'ESRCH';
+    }
+}
+function isCrossProcessLockOlderThanLease(acquiredAtMs, nowMs) {
+    return acquiredAtMs < nowMs - CROSS_PROCESS_LOCK_LEASE_MS;
+}
+function isCrossProcessLockReclaimable(claim) {
+    if (claim.host !== hostname())
+        return isCrossProcessLockOlderThanLease(claim.acquiredAtMs, Date.now());
+    if (isCrossProcessLockOwnerDead(claim.pid))
+        return true;
+    const currentPidStartId = readProcessStartIdentity(claim.pid);
+    if (claim.pidStartId && currentPidStartId)
+        return currentPidStartId !== claim.pidStartId;
+    return isCrossProcessLockOlderThanLease(claim.acquiredAtMs, Date.now());
+}
+function removeCrossProcessLockFile(path) {
+    try {
+        unlinkSync(path);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+function tryAcquireCrossProcessFileLock(lockPath, token) {
+    const temporaryPath = `${lockPath}.${process.pid}.${randomUUID()}.tmp`;
+    let acquired = false;
+    try {
+        writeFileSync(temporaryPath, serializeCrossProcessLockClaim(createCrossProcessLockClaim(token)));
+        try {
+            linkSync(temporaryPath, lockPath);
+            acquired = true;
+            return true;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+    }
+    finally {
+        try {
+            removeCrossProcessLockFile(temporaryPath);
+        }
+        catch (error) {
+            if (!acquired)
+                throw error;
+        }
+    }
+}
+function restoreQuarantinedCrossProcessLock(lockPath, quarantinedPath) {
+    try {
+        linkSync(quarantinedPath, lockPath);
+    }
+    catch (error) {
+        const code = error.code;
+        // EEXIST: a replacement claim already holds the lock; the displaced copy is redundant.
+        // ENOENT: the displaced artifact was already removed (e.g. by a concurrent bounded
+        // sweep) — a fenced clean terminal outcome, never a cleanup failure to throw on.
+        if (code === 'EEXIST') {
+            removeCrossProcessLockFile(quarantinedPath);
+            return;
+        }
+        if (code === 'ENOENT')
+            return;
+        throw error;
+    }
+    removeCrossProcessLockFile(quarantinedPath);
+}
+function recoverCrossProcessFileLock(lockPath, observed) {
+    if (observed.kind === 'missing')
+        return true;
+    if (observed.kind === 'claim' && !isCrossProcessLockReclaimable(observed.claim))
+        return false;
+    const quarantinedPath = `${lockPath}.${Date.now()}.${randomUUID()}.quarantine`;
+    try {
+        renameSync(lockPath, quarantinedPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return true;
+        throw error;
+    }
+    const barrier = crossProcessQuarantineBarrier;
+    crossProcessQuarantineBarrier = null;
+    barrier?.(lockPath, quarantinedPath);
+    const captured = readCrossProcessLockState(quarantinedPath);
+    const capturedExpectedClaim = observed.kind === 'claim'
+        && captured.kind === 'claim'
+        && captured.claim.token === observed.claim.token;
+    const capturedRecoverable = captured.kind === 'malformed'
+        || (capturedExpectedClaim && captured.kind === 'claim' && isCrossProcessLockReclaimable(captured.claim));
+    if (!capturedRecoverable) {
+        restoreQuarantinedCrossProcessLock(lockPath, quarantinedPath);
+        return true;
+    }
+    removeCrossProcessLockFile(quarantinedPath);
+    return true;
+}
+function assertCrossProcessFileLockOwnership(lockPath, token) {
+    const state = readCrossProcessLockState(lockPath);
+    if (state.kind === 'claim' && state.claim.token === token)
+        return;
+    throw new CrossProcessLockLostError(lockPath);
+}
+function releaseCrossProcessFileLock(lockPath, token) {
+    const observed = readCrossProcessLockState(lockPath);
+    if (observed.kind !== 'claim' || observed.claim.token !== token)
+        return;
+    const quarantinedPath = `${lockPath}.${Date.now()}.${randomUUID()}.release`;
+    try {
+        renameSync(lockPath, quarantinedPath);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const barrier = crossProcessQuarantineBarrier;
+    crossProcessQuarantineBarrier = null;
+    barrier?.(lockPath, quarantinedPath);
+    const captured = readCrossProcessLockState(quarantinedPath);
+    if (captured.kind === 'claim' && captured.claim.token === token) {
+        removeCrossProcessLockFile(quarantinedPath);
+        return;
+    }
+    restoreQuarantinedCrossProcessLock(lockPath, quarantinedPath);
+}
+function crossProcessLockStagePath(resourcePath, token) {
+    return `${resourcePath}.stage.${token}`;
+}
+function createCrossProcessLockStage(stagePath) {
+    const descriptor = openSync(stagePath, 'wx');
+    closeSync(descriptor);
+}
+function sweepForeignCrossProcessLockStages(resourcePath, token) {
+    const directory = dirname(resourcePath);
+    const stagePrefix = `${basename(resourcePath)}.stage.`;
+    for (const entry of readdirSync(directory)) {
+        if (!entry.startsWith(stagePrefix) || entry.slice(stagePrefix.length) === token)
+            continue;
+        removeCrossProcessLockFile(join(directory, entry));
+    }
+}
+export const CROSS_PROCESS_LOCK_ARTIFACT_SWEEP_CAP = 64;
+function sweepAbandonedCrossProcessLockArtifacts(resourcePath) {
+    const directory = dirname(resourcePath);
+    const lockName = basename(crossProcessLockPath(resourcePath));
+    const escapedLockName = lockName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const artifactPattern = new RegExp(`^${escapedLockName}\\.([^.]+)\\.[^.]+\\.(?:quarantine|release)$`);
+    const nowMs = Date.now();
+    const aged = [];
+    for (const entry of readdirSync(directory)) {
+        const match = artifactPattern.exec(entry);
+        if (!match)
+            continue;
+        const displacedAtMs = Number(match[1]);
+        // Only lease-aged, parseable-timestamp artifacts are eligible; fresh/live/malformed-ts
+        // artifacts are always preserved (never delete a live successor's in-flight evidence).
+        if (!Number.isFinite(displacedAtMs) || nowMs - displacedAtMs <= CROSS_PROCESS_LOCK_LEASE_MS)
+            continue;
+        aged.push({ displacedAtMs, entry });
+    }
+    // Bounded, deterministic cleanup: process oldest-first (tie-break by name) and remove at
+    // most CROSS_PROCESS_LOCK_ARTIFACT_SWEEP_CAP per acquisition, so a large backlog drains
+    // predictably across acquisitions instead of doing unbounded work in a single lock take.
+    aged.sort((a, b) => a.displacedAtMs - b.displacedAtMs || (a.entry < b.entry ? -1 : a.entry > b.entry ? 1 : 0));
+    for (const { entry } of aged.slice(0, CROSS_PROCESS_LOCK_ARTIFACT_SWEEP_CAP)) {
+        removeCrossProcessLockFile(join(directory, entry));
+    }
+}
+let crossProcessPublishBarrier = null;
+let crossProcessQuarantineBarrier = null;
+export function __setCrossProcessPublishBarrierForTest(barrier) {
+    crossProcessPublishBarrier = barrier;
+}
+export function __setCrossProcessQuarantineBarrierForTest(barrier) {
+    crossProcessQuarantineBarrier = barrier;
+}
+export function withCrossProcessFileLockSync(resourcePath, operation, options = {}) {
+    const lockPath = crossProcessLockPath(resourcePath);
+    const maxAttempts = typeof options.maxAttempts === 'number' && Number.isFinite(options.maxAttempts)
+        ? Math.max(1, Math.floor(options.maxAttempts))
+        : DEFAULT_CROSS_PROCESS_LOCK_MAX_ATTEMPTS;
+    const retryMs = typeof options.retryMs === 'number' && Number.isFinite(options.retryMs)
+        ? Math.max(1, Math.floor(options.retryMs))
+        : DEFAULT_CROSS_PROCESS_LOCK_RETRY_MS;
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const token = randomUUID();
+    const stagePath = crossProcessLockStagePath(resourcePath, token);
+    let acquired = false;
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        if (tryAcquireCrossProcessFileLock(lockPath, token)) {
+            acquired = true;
+            break;
+        }
+        const recovered = recoverCrossProcessFileLock(lockPath, readCrossProcessLockState(lockPath));
+        if (recovered && tryAcquireCrossProcessFileLock(lockPath, token)) {
+            acquired = true;
+            break;
+        }
+        if (attempt === maxAttempts - 1) {
+            throw new Error(`Timed out waiting for cross-process lock at ${lockPath}`);
+        }
+        sleepForCrossProcessLockSync(Math.min(25, retryMs * 2 ** Math.min(attempt, 4)));
+    }
+    if (!acquired) {
+        throw new Error(`Timed out waiting for cross-process lock at ${lockPath}`);
+    }
+    try {
+        sweepForeignCrossProcessLockStages(resourcePath, token);
+        sweepAbandonedCrossProcessLockArtifacts(resourcePath);
+        createCrossProcessLockStage(stagePath);
+        return operation({
+            assertOwnership: () => assertCrossProcessFileLockOwnership(lockPath, token),
+            publish: (contents) => {
+                let descriptor;
+                try {
+                    descriptor = openSync(stagePath, 'r+');
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        throw new CrossProcessLockLostError(lockPath);
+                    throw error;
+                }
+                try {
+                    ftruncateSync(descriptor, 0);
+                    writeSync(descriptor, contents);
+                }
+                finally {
+                    closeSync(descriptor);
+                }
+                const barrier = crossProcessPublishBarrier;
+                crossProcessPublishBarrier = null;
+                barrier?.();
+                try {
+                    renameSync(stagePath, resourcePath);
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        throw new CrossProcessLockLostError(lockPath);
+                    throw error;
+                }
+                createCrossProcessLockStage(stagePath);
+            },
+        });
+    }
+    finally {
+        removeCrossProcessLockFile(stagePath);
+        releaseCrossProcessFileLock(lockPath, token);
+    }
+}
+function readSubagentTrackingStateSync(cwd) {
+    const path = subagentTrackingPath(cwd);
+    if (!existsSync(path))
+        return createSubagentTrackingState();
+    try {
+        return normalizeSubagentTrackingState(JSON.parse(readFileSync(path, 'utf-8')));
+    }
+    catch {
+        return createSubagentTrackingState();
+    }
+}
+// #3181: strict readers for the leader-attestation security decision. A missing file is a
+// legitimate empty state (fresh turn), but an existing file that fails to read/parse must
+// NOT be silently treated as empty — that would let corrupt/unreadable subagent evidence
+// be bypassed. Callers making a security decision (attest vs deny) use these.
+function readSubagentTrackingStateSyncStrict(cwd) {
+    const path = subagentTrackingPath(cwd);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch (error) {
+        // Only a genuine ENOENT (no file) is a clean empty state. Any other read/access error
+        // (permissions, I/O, ELOOP, …) must fail closed rather than be treated as empty.
+        if (error?.code === 'ENOENT')
+            return { ok: true, state: createSubagentTrackingState() };
+        return { ok: false };
+    }
+    try {
+        return { ok: true, state: normalizeSubagentTrackingState(JSON.parse(raw)) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+export async function readSubagentTrackingStateStrict(cwd) {
+    const path = subagentTrackingPath(cwd);
+    let raw;
+    try {
+        raw = await readFile(path, 'utf-8');
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return { ok: true, state: createSubagentTrackingState() };
+        return { ok: false };
+    }
+    try {
+        return { ok: true, state: normalizeSubagentTrackingState(JSON.parse(raw)) };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function threadIsTrackedAsSubagent(state, threadId) {
+    const id = threadId.trim();
+    if (!id)
+        return false;
+    for (const session of Object.values(state.sessions)) {
+        if (session.threads[id]?.kind === 'subagent')
+            return true;
+    }
+    return false;
+}
+function writeSubagentTrackingStateSync(cwd, state, publish) {
+    const normalized = normalizeSubagentTrackingState(state);
+    const path = subagentTrackingPath(cwd);
+    mkdirSync(dirname(path), { recursive: true });
+    const contents = `${JSON.stringify(normalized, null, 2)}\n`;
+    if (publish) {
+        publish(contents);
+        return path;
+    }
+    const temporaryPath = atomicTrackingTempPath(path);
+    writeFileSync(temporaryPath, contents);
+    renameSync(temporaryPath, path);
+    return path;
+}
 export async function readSubagentTrackingState(cwd) {
     const path = subagentTrackingPath(cwd);
     if (!existsSync(path))
@@ -191,9 +679,525 @@ export async function writeSubagentTrackingState(cwd, state) {
     const normalized = normalizeSubagentTrackingState(state);
     const path = subagentTrackingPath(cwd);
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, `${JSON.stringify(normalized, null, 2)}\n`);
+    const temporaryPath = atomicTrackingTempPath(path);
+    await writeFile(temporaryPath, `${JSON.stringify(normalized, null, 2)}\n`);
+    await rename(temporaryPath, path);
     return path;
 }
+function normalizeNowMs(nowMs) {
+    return typeof nowMs === 'number' && Number.isFinite(nowMs) ? nowMs : Date.now();
+}
+function isExpiredPendingRoleIntent(intent, nowMs) {
+    if (intent.binding_state === 'bound')
+        return false;
+    const expiresAtMs = Date.parse(intent.expires_at);
+    return !Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs;
+}
+function pendingRoleIntentPredicates(cwd, canonicalOrigin, nowMs) {
+    const isCwdPartitionedStateRoot = getBaseStateDirWithSource(cwd).rootSource === 'cwd-default';
+    const isOwn = (intent) => (intent.origin_cwd
+        ? canonicalizeOriginCwd(intent.origin_cwd) === canonicalOrigin
+        : isCwdPartitionedStateRoot);
+    const shouldPruneExpired = (intent) => (isOwn(intent)
+        && intent.binding_state !== 'bound'
+        && isExpiredPendingRoleIntent(intent, nowMs));
+    return { isOwn, shouldPruneExpired };
+}
+export function isRoleIntentOwnedByCwd(cwd, intent) {
+    return pendingRoleIntentPredicates(cwd, canonicalizeOriginCwd(cwd), Date.now()).isOwn(intent);
+}
+function sameLogicalRoleIntent(intent, sessionId, parentThreadId, correlationToken) {
+    return (intent.session_id === sessionId
+        && intent.parent_thread_id === parentThreadId
+        && (correlationToken === undefined || intent.correlation_token === correlationToken));
+}
+export function isCanonicalCorrelationToken(value) {
+    return typeof value === 'string' && /^[0-9a-f]{32}$/.test(value);
+}
+export function isCanonicalClaimantToken(value) {
+    return typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(value);
+}
+function hasOwnBoundLogicalIntent(all, isOwn, sessionId, parentThreadId, correlationToken) {
+    return all.some((intent) => (isOwn(intent)
+        && intent.binding_state === 'bound'
+        && sameLogicalRoleIntent(intent, sessionId, parentThreadId, correlationToken)));
+}
+function selectDominantRoleIntent(candidates, canonicalOrigin) {
+    return [...candidates].sort((left, right) => {
+        const leftIsBound = left.binding_state === 'bound';
+        const rightIsBound = right.binding_state === 'bound';
+        if (leftIsBound !== rightIsBound)
+            return leftIsBound ? -1 : 1;
+        const leftIsExactOrigin = left.origin_cwd !== undefined
+            && canonicalizeOriginCwd(left.origin_cwd) === canonicalOrigin;
+        const rightIsExactOrigin = right.origin_cwd !== undefined
+            && canonicalizeOriginCwd(right.origin_cwd) === canonicalOrigin;
+        if (leftIsExactOrigin !== rightIsExactOrigin)
+            return leftIsExactOrigin ? -1 : 1;
+        const leftStableKey = [
+            left.role,
+            left.correlation_token,
+            left.created_at,
+            left.expires_at,
+            left.binding_state ?? '',
+            left.binding_claimant_token ?? '',
+            left.bound_at ?? '',
+            left.origin_cwd ?? '',
+        ].join('\u0000');
+        const rightStableKey = [
+            right.role,
+            right.correlation_token,
+            right.created_at,
+            right.expires_at,
+            right.binding_state ?? '',
+            right.binding_claimant_token ?? '',
+            right.bound_at ?? '',
+            right.origin_cwd ?? '',
+        ].join('\u0000');
+        return leftStableKey.localeCompare(rightStableKey);
+    })[0] ?? null;
+}
+export function recordPendingRoleIntent(cwd, input) {
+    const role = resolveInstalledRoleName(input.role);
+    if (!role)
+        return { ok: false, reason: 'unknown_role' };
+    const correlationToken = input.correlationToken;
+    if (!isCanonicalCorrelationToken(correlationToken)) {
+        return { ok: false, reason: 'invalid_correlation_token' };
+    }
+    const nowMs = normalizeNowMs(input.nowMs);
+    const sessionId = input.sessionId.trim();
+    const parentThreadId = input.parentThreadId.trim();
+    const canonicalOrigin = canonicalizeOriginCwd(cwd);
+    if (canonicalOrigin === null)
+        return { ok: false, reason: 'invalid_origin' };
+    const { isOwn, shouldPruneExpired } = pendingRoleIntentPredicates(cwd, canonicalOrigin, nowMs);
+    return withCrossProcessFileLockSync(subagentTrackingPath(cwd), (context) => {
+        const state = readSubagentTrackingStateSync(cwd);
+        const all = state.pending_role_intents;
+        if (all.some((intent) => (isOwn(intent)
+            && intent.session_id === sessionId
+            && intent.parent_thread_id === parentThreadId
+            && (intent.binding_state === 'bound' || !isExpiredPendingRoleIntent(intent, nowMs))))) {
+            return { ok: false, reason: 'single_flight_conflict' };
+        }
+        const ttlMs = typeof input.ttlMs === 'number' && Number.isFinite(input.ttlMs) ? input.ttlMs : 10 * 60_000;
+        const intent = {
+            role,
+            session_id: sessionId,
+            parent_thread_id: parentThreadId,
+            correlation_token: correlationToken,
+            created_at: new Date(nowMs).toISOString(),
+            expires_at: new Date(nowMs + ttlMs).toISOString(),
+            // Store the canonical origin workspace so it authenticates future bind/complete/recover.
+            ...(canonicalOrigin ? { origin_cwd: canonicalOrigin } : {}),
+        };
+        state.pending_role_intents = [...all.filter((candidate) => !shouldPruneExpired(candidate)), intent];
+        context.assertOwnership();
+        writeSubagentTrackingStateSync(cwd, state, context.publish);
+        return { ok: true, intent };
+    });
+}
+/**
+ * #3181 Phase 1 carrier write. Durably attest the authenticated leader thread for a
+ * session from native-hook-reconciled metadata. Idempotent and fail-closed: it seeds
+ * `leader_thread_id` + `leader_attested_at` + `leader_attest_source` only when the
+ * session has no conflicting leader already. A different existing leader is NEVER
+ * overwritten (returns `native_anchor_mismatch`) so a stale/foreign leader cannot be
+ * replaced from a later turn. Authority for `leaderThreadId` is the caller's native
+ * payload thread; it must never be derived from a native session id.
+ */
+export function attestLeaderThread(cwd, input) {
+    const sessionId = input.sessionId.trim();
+    const leaderThreadId = input.leaderThreadId.trim();
+    const source = input.source.trim() || 'native';
+    if (!sessionId || !leaderThreadId)
+        return { ok: false, reason: 'native_anchor_unavailable' };
+    const nowMs = normalizeNowMs(input.nowMs);
+    const nowIso = new Date(nowMs).toISOString();
+    return withCrossProcessFileLockSync(subagentTrackingPath(cwd), (context) => {
+        // Strict read under the lock: an unreadable/corrupt tracker denies attestation
+        // (fail closed) rather than silently reading empty.
+        const read = readSubagentTrackingStateSyncStrict(cwd);
+        if (!read.ok)
+            return { ok: false, reason: 'native_anchor_unavailable' };
+        const state = read.state;
+        // Atomic positive counter-evidence: a thread tracked as a subagent in ANY session is
+        // never attested as a leader. Checked under the same lock as the write so a concurrent
+        // child record cannot race in between a caller's pre-check and this attestation.
+        if (threadIsTrackedAsSubagent(state, leaderThreadId)) {
+            return { ok: false, reason: 'native_anchor_mismatch' };
+        }
+        const existing = state.sessions[sessionId];
+        const existingLeader = existing?.leader_thread_id?.trim();
+        if (existingLeader && existingLeader !== leaderThreadId) {
+            return { ok: false, reason: 'native_anchor_mismatch' };
+        }
+        if (existing && existingLeader === leaderThreadId && existing.leader_attested_at) {
+            return { ok: true, alreadyAttested: true };
+        }
+        const session = existing
+            ? { ...existing }
+            : { session_id: sessionId, updated_at: nowIso, threads: {} };
+        session.leader_thread_id = leaderThreadId;
+        session.leader_attested_at = nowIso;
+        session.leader_attest_source = source;
+        session.updated_at = nowIso;
+        state.sessions = { ...state.sessions, [sessionId]: session };
+        context.assertOwnership();
+        writeSubagentTrackingStateSync(cwd, state, context.publish);
+        return { ok: true, alreadyAttested: false };
+    });
+}
+/**
+ * #3181 Phase 2. Single tracker-locked publish that self-heals the leader thread record
+ * from a durable native attestation and records the pending role intent in the same
+ * operation, closing the previous verify-then-record TOCTOU window. Fail-closed:
+ * requires a durable attested leader for the session (`native_anchor_unavailable`
+ * otherwise) and requires `parentThreadId` to equal the attested `leader_thread_id`
+ * (`native_anchor_mismatch` otherwise). `leaderThreadId` is never inferred from a
+ * native session id. Duplicate same-identity intents reuse the original receipt
+ * (idempotent), never a second leader or a second intent.
+ */
+export function ensureLeaderAndRecordIntent(cwd, input) {
+    const role = resolveInstalledRoleName(input.role);
+    if (!role)
+        return { ok: false, reason: 'unknown_role' };
+    const correlationToken = input.correlationToken;
+    if (!isCanonicalCorrelationToken(correlationToken)) {
+        return { ok: false, reason: 'invalid_correlation_token' };
+    }
+    const nowMs = normalizeNowMs(input.nowMs);
+    const sessionId = input.sessionId.trim();
+    const parentThreadId = input.parentThreadId.trim();
+    const canonicalOrigin = canonicalizeOriginCwd(cwd);
+    if (canonicalOrigin === null)
+        return { ok: false, reason: 'invalid_origin' };
+    const { isOwn, shouldPruneExpired } = pendingRoleIntentPredicates(cwd, canonicalOrigin, nowMs);
+    return withCrossProcessFileLockSync(subagentTrackingPath(cwd), (context) => {
+        // Strict read under the lock: an unreadable/corrupt tracker fails closed rather than
+        // being treated as empty state.
+        const read = readSubagentTrackingStateSyncStrict(cwd);
+        if (!read.ok)
+            return { ok: false, reason: 'native_anchor_unavailable' };
+        const state = read.state;
+        const session = state.sessions[sessionId];
+        const attestedLeader = session?.leader_thread_id?.trim();
+        // Fail closed unless a durable native attestation established the leader anchor.
+        if (!session || !attestedLeader || !session.leader_attested_at) {
+            return { ok: false, reason: 'native_anchor_unavailable' };
+        }
+        if (parentThreadId !== attestedLeader) {
+            return { ok: false, reason: 'native_anchor_mismatch' };
+        }
+        // Symmetric subagent exclusion: independent of which writer won the tracker lock, a
+        // leader thread that is ALSO recorded as a subagent in ANY session (even a different
+        // one) must never receive an adapted role intent. Re-scanned here under the intent-write
+        // lock so a cross-session child record committed after attestation cannot slip through.
+        if (threadIsTrackedAsSubagent(state, attestedLeader)) {
+            return { ok: false, reason: 'native_anchor_mismatch' };
+        }
+        // Single-flight, role-agnostic (preserves recordPendingRoleIntent's invariant): a
+        // live/bound own intent for the same (session, parent) blocks a second live intent.
+        // Same-identity (same role) retries reuse the original receipt (idempotent); a
+        // different-role request for the same live parent returns single_flight_conflict
+        // rather than creating a second ambiguous intent.
+        const all = state.pending_role_intents;
+        const liveOwnIntent = all.find((intent) => (isOwn(intent)
+            && intent.session_id === sessionId
+            && intent.parent_thread_id === parentThreadId
+            && (intent.binding_state === 'bound' || !isExpiredPendingRoleIntent(intent, nowMs))));
+        if (liveOwnIntent) {
+            if (liveOwnIntent.role === role) {
+                return { ok: true, intent: liveOwnIntent, reused: true };
+            }
+            return { ok: false, reason: 'single_flight_conflict' };
+        }
+        // Self-heal the leader thread record so leader-anchor consumers see kind:"leader".
+        const nowIso = new Date(nowMs).toISOString();
+        const nextSession = { ...session, threads: { ...session.threads } };
+        const existingLeaderThread = nextSession.threads[attestedLeader];
+        if (!existingLeaderThread || existingLeaderThread.kind !== 'leader') {
+            nextSession.threads[attestedLeader] = {
+                ...(existingLeaderThread ?? {}),
+                thread_id: attestedLeader,
+                kind: 'leader',
+                first_seen_at: existingLeaderThread?.first_seen_at ?? nowIso,
+                last_seen_at: nowIso,
+                turn_count: existingLeaderThread?.turn_count ?? 0,
+            };
+        }
+        nextSession.updated_at = nowIso;
+        const ttlMs = typeof input.ttlMs === 'number' && Number.isFinite(input.ttlMs) ? input.ttlMs : 10 * 60_000;
+        const intent = {
+            role,
+            session_id: sessionId,
+            parent_thread_id: parentThreadId,
+            correlation_token: correlationToken,
+            created_at: nowIso,
+            expires_at: new Date(nowMs + ttlMs).toISOString(),
+            ...(canonicalOrigin ? { origin_cwd: canonicalOrigin } : {}),
+        };
+        state.sessions = { ...state.sessions, [sessionId]: nextSession };
+        state.pending_role_intents = [...all.filter((candidate) => !shouldPruneExpired(candidate)), intent];
+        context.assertOwnership();
+        writeSubagentTrackingStateSync(cwd, state, context.publish);
+        return { ok: true, intent, reused: false };
+    });
+}
+/**
+ * #3181 legacy/native fallback, made atomic and positive-provenance-only. When no durable
+ * attestation exists, an in-turn role intent may still be authorized ONLY against the
+ * tracker leader_thread_id — the positively-provenanced leader thread set by a real
+ * recorded leader turn (notify) or by PreToolUse attestation (gated when the caller has a
+ * usable current pointer). It deliberately does NOT trust the reconciled session.json
+ * native_session_id, which an ambiguous/malformed-child SessionStart can set. This is the
+ * strict tracker-locked replacement for the former CLI "activeLeaderThreadIds +
+ * recordPendingRoleIntent" fallback: it validates the leader anchor AND rejects any
+ * all-session subagent counter-evidence under the same lock as the intent write, so a
+ * subagent record landing after a pre-check (or a PreToolUse attestation that lost its
+ * race) can never be downgraded into an unvalidated legacy authorization. Fail-closed:
+ * unreadable/corrupt tracker → native_anchor_unavailable; parent not the tracker leader →
+ * parent_not_active_leader; parent tracked as a subagent anywhere → native_anchor_mismatch.
+ */
+export function recordNativeLeaderIntent(cwd, input) {
+    const role = resolveInstalledRoleName(input.role);
+    if (!role)
+        return { ok: false, reason: 'unknown_role' };
+    const correlationToken = input.correlationToken;
+    if (!isCanonicalCorrelationToken(correlationToken)) {
+        return { ok: false, reason: 'invalid_correlation_token' };
+    }
+    const nowMs = normalizeNowMs(input.nowMs);
+    const sessionId = input.sessionId.trim();
+    const parentThreadId = input.parentThreadId.trim();
+    const canonicalOrigin = canonicalizeOriginCwd(cwd);
+    if (canonicalOrigin === null)
+        return { ok: false, reason: 'invalid_origin' };
+    const { isOwn, shouldPruneExpired } = pendingRoleIntentPredicates(cwd, canonicalOrigin, nowMs);
+    return withCrossProcessFileLockSync(subagentTrackingPath(cwd), (context) => {
+        const read = readSubagentTrackingStateSyncStrict(cwd);
+        if (!read.ok)
+            return { ok: false, reason: 'native_anchor_unavailable' };
+        const state = read.state;
+        // Positive-provenance leader anchor ONLY: the tracker leader_thread_id is set by a real
+        // recorded leader turn (notify) or by PreToolUse attestation. It is intentionally NOT
+        // the reconciled session.json native_session_id, which an ambiguous/malformed-child
+        // SessionStart can set without positively classifying a root — trusting that pointer
+        // would re-open false-leader adoption. A malformed child never obtains a tracker leader
+        // thread, so it fails closed here.
+        const trackerLeader = input.allowTrackerLeader ? state.sessions[sessionId]?.leader_thread_id?.trim() : undefined;
+        if (!parentThreadId || !trackerLeader || parentThreadId !== trackerLeader) {
+            return { ok: false, reason: 'parent_not_active_leader' };
+        }
+        // Atomic all-session subagent exclusion: a parent thread recorded as a subagent in ANY
+        // session is never a valid leader, even if it matches the tracker leader anchor.
+        if (threadIsTrackedAsSubagent(state, parentThreadId)) {
+            return { ok: false, reason: 'native_anchor_mismatch' };
+        }
+        // Role-agnostic single-flight (same contract as recordPendingRoleIntent).
+        const all = state.pending_role_intents;
+        const liveOwnIntent = all.find((intent) => (isOwn(intent)
+            && intent.session_id === sessionId
+            && intent.parent_thread_id === parentThreadId
+            && (intent.binding_state === 'bound' || !isExpiredPendingRoleIntent(intent, nowMs))));
+        if (liveOwnIntent) {
+            if (liveOwnIntent.role === role) {
+                return { ok: true, intent: liveOwnIntent, reused: true };
+            }
+            return { ok: false, reason: 'single_flight_conflict' };
+        }
+        const nowIso = new Date(nowMs).toISOString();
+        const ttlMs = typeof input.ttlMs === 'number' && Number.isFinite(input.ttlMs) ? input.ttlMs : 10 * 60_000;
+        const intent = {
+            role,
+            session_id: sessionId,
+            parent_thread_id: parentThreadId,
+            correlation_token: correlationToken,
+            created_at: nowIso,
+            expires_at: new Date(nowMs + ttlMs).toISOString(),
+            ...(canonicalOrigin ? { origin_cwd: canonicalOrigin } : {}),
+        };
+        state.pending_role_intents = [...all.filter((candidate) => !shouldPruneExpired(candidate)), intent];
+        context.assertOwnership();
+        writeSubagentTrackingStateSync(cwd, state, context.publish);
+        return { ok: true, intent, reused: false };
+    });
+}
+export function bindPendingRoleIntentUnderLock(cwd, input, bind) {
+    const nowMs = normalizeNowMs(input.nowMs);
+    const sessionId = input.sessionId.trim();
+    const parentThreadId = input.parentThreadId.trim();
+    const correlationToken = input.correlationToken;
+    if (!isCanonicalCorrelationToken(correlationToken))
+        return null;
+    // Fail-closed origin authentication: establish the caller's canonical origin workspace up
+    // front. A malformed/unavailable origin can never disclose role/claimant, run the bind
+    // callback, mutate pending->bound, or acquire the lock.
+    const canonicalOrigin = canonicalizeOriginCwd(cwd);
+    if (canonicalOrigin === null)
+        return null;
+    return withCrossProcessFileLockSync(subagentTrackingPath(cwd), (context) => {
+        const state = readSubagentTrackingStateSync(cwd);
+        const all = state.pending_role_intents;
+        const { isOwn, shouldPruneExpired } = pendingRoleIntentPredicates(cwd, canonicalOrigin, nowMs);
+        const matchedIntent = selectDominantRoleIntent(all.filter((intent) => (isOwn(intent)
+            && correlationToken !== undefined
+            && sameLogicalRoleIntent(intent, sessionId, parentThreadId, correlationToken)
+            && (intent.binding_state === 'bound' || !isExpiredPendingRoleIntent(intent, nowMs)))), canonicalOrigin);
+        if (!matchedIntent) {
+            const retained = all.filter((intent) => !shouldPruneExpired(intent));
+            if (retained.length !== all.length) {
+                state.pending_role_intents = retained;
+                context.assertOwnership();
+                writeSubagentTrackingStateSync(cwd, state, context.publish);
+            }
+            return null;
+        }
+        const adaptedIntent = {
+            role: matchedIntent.role,
+            provenanceKind: OMX_ADAPTED_PROVENANCE,
+        };
+        if (matchedIntent.binding_state === 'bound') {
+            const next = all
+                .filter((intent) => (intent.binding_state === 'bound'
+                || !(isOwn(intent) && sameLogicalRoleIntent(intent, sessionId, parentThreadId, correlationToken))))
+                .map((intent) => (intent === matchedIntent && !intent.origin_cwd
+                ? { ...intent, origin_cwd: canonicalOrigin }
+                : intent));
+            if (next.length !== all.length || !matchedIntent.origin_cwd) {
+                state.pending_role_intents = next;
+                context.assertOwnership();
+                writeSubagentTrackingStateSync(cwd, state, context.publish);
+            }
+            return {
+                ...adaptedIntent,
+                claimantToken: undefined,
+                alreadyBound: true,
+            };
+        }
+        const claimantToken = randomUUID();
+        const boundState = bind(state, adaptedIntent);
+        boundState.pending_role_intents = all
+            .filter((intent) => !shouldPruneExpired(intent))
+            .filter((intent) => (intent === matchedIntent
+            || !(isOwn(intent) && sameLogicalRoleIntent(intent, sessionId, parentThreadId, correlationToken))))
+            .map((intent) => (intent === matchedIntent
+            ? {
+                ...matchedIntent,
+                binding_state: 'bound',
+                binding_claimant_token: claimantToken,
+                bound_at: new Date(nowMs).toISOString(),
+                origin_cwd: matchedIntent.origin_cwd ?? canonicalOrigin,
+            }
+            : intent));
+        context.assertOwnership();
+        writeSubagentTrackingStateSync(cwd, boundState, context.publish);
+        return { ...adaptedIntent, claimantToken, alreadyBound: false };
+    });
+}
+export function consumePendingRoleIntent(cwd, input) {
+    const nowMs = normalizeNowMs(input.nowMs);
+    const sessionId = input.sessionId.trim();
+    const parentThreadId = input.parentThreadId.trim();
+    const correlationToken = input.correlationToken;
+    if (!isCanonicalCorrelationToken(correlationToken))
+        return null;
+    const canonicalOrigin = canonicalizeOriginCwd(cwd);
+    if (canonicalOrigin === null)
+        return null;
+    return withCrossProcessFileLockSync(subagentTrackingPath(cwd), (context) => {
+        const state = readSubagentTrackingStateSync(cwd);
+        const all = state.pending_role_intents;
+        const { isOwn, shouldPruneExpired } = pendingRoleIntentPredicates(cwd, canonicalOrigin, nowMs);
+        if (hasOwnBoundLogicalIntent(all, isOwn, sessionId, parentThreadId, correlationToken))
+            return null;
+        const consumed = selectDominantRoleIntent(all.filter((intent) => (isOwn(intent)
+            && intent.binding_state !== 'bound'
+            && !isExpiredPendingRoleIntent(intent, nowMs)
+            && correlationToken !== undefined
+            && sameLogicalRoleIntent(intent, sessionId, parentThreadId, correlationToken))), canonicalOrigin);
+        if (!consumed) {
+            const retained = all.filter((intent) => !shouldPruneExpired(intent));
+            if (retained.length !== all.length) {
+                state.pending_role_intents = retained;
+                context.assertOwnership();
+                writeSubagentTrackingStateSync(cwd, state, context.publish);
+            }
+            return null;
+        }
+        state.pending_role_intents = all
+            .filter((intent) => !shouldPruneExpired(intent))
+            .filter((intent) => (intent.binding_state === 'bound'
+            || !(isOwn(intent) && sameLogicalRoleIntent(intent, sessionId, parentThreadId, correlationToken))));
+        context.assertOwnership();
+        writeSubagentTrackingStateSync(cwd, state, context.publish);
+        return { role: consumed.role, provenanceKind: OMX_ADAPTED_PROVENANCE };
+    });
+}
+export function completeAdaptedRoleBinding(cwd, input) {
+    const nowMs = normalizeNowMs(input.nowMs);
+    const sessionId = input.sessionId.trim();
+    const parentThreadId = input.parentThreadId.trim();
+    const correlationToken = input.correlationToken;
+    const claimantToken = input.claimantToken;
+    const canonicalOrigin = canonicalizeOriginCwd(cwd);
+    if (canonicalOrigin === null)
+        return 'not_found';
+    return withCrossProcessFileLockSync(subagentTrackingPath(cwd), (context) => {
+        const state = readSubagentTrackingStateSync(cwd);
+        const all = state.pending_role_intents;
+        const { isOwn, shouldPruneExpired } = pendingRoleIntentPredicates(cwd, canonicalOrigin, nowMs);
+        // Select the owned bound scope before authenticating it. Credentials are not a lookup key:
+        // otherwise an invalid dominant duplicate could be bypassed by a lower valid duplicate.
+        const boundIntent = selectDominantRoleIntent(all.filter((intent) => (isOwn(intent)
+            && intent.binding_state === 'bound'
+            && sameLogicalRoleIntent(intent, sessionId, parentThreadId))), canonicalOrigin);
+        if (!boundIntent) {
+            const retained = all.filter((intent) => !shouldPruneExpired(intent));
+            if (retained.length !== all.length) {
+                state.pending_role_intents = retained;
+                context.assertOwnership();
+                writeSubagentTrackingStateSync(cwd, state, context.publish);
+            }
+            return 'not_found';
+        }
+        const hasClaimant = Object.hasOwn(boundIntent, 'binding_claimant_token');
+        if (!isCanonicalCorrelationToken(boundIntent.correlation_token)
+            || !isCanonicalCorrelationToken(correlationToken)
+            || boundIntent.correlation_token !== correlationToken
+            || (hasClaimant && (!isCanonicalClaimantToken(boundIntent.binding_claimant_token)
+                || !isCanonicalClaimantToken(claimantToken)
+                || boundIntent.binding_claimant_token !== claimantToken)))
+            return 'claimant_mismatch';
+        state.pending_role_intents = all
+            .filter((intent) => !shouldPruneExpired(intent))
+            .filter((intent) => !(isOwn(intent) && sameLogicalRoleIntent(intent, sessionId, parentThreadId, boundIntent.correlation_token)));
+        context.assertOwnership();
+        writeSubagentTrackingStateSync(cwd, state, context.publish);
+        return 'completed';
+    });
+}
+export function listBoundAdaptedRoleIntents(cwd, _nowMs, ownedDominant = false) {
+    const allBound = readSubagentTrackingStateSync(cwd).pending_role_intents.filter((intent) => intent.binding_state === 'bound');
+    if (!ownedDominant)
+        return allBound;
+    const canonicalOrigin = canonicalizeOriginCwd(cwd);
+    if (canonicalOrigin === null)
+        return [];
+    const { isOwn } = pendingRoleIntentPredicates(cwd, canonicalOrigin, Date.now());
+    const scopes = new Map();
+    for (const intent of allBound) {
+        if (!isOwn(intent))
+            continue;
+        const key = `${intent.session_id}\u0000${intent.parent_thread_id}`;
+        scopes.set(key, [...(scopes.get(key) ?? []), intent]);
+    }
+    return [...scopes.values()].flatMap((candidates) => {
+        const dominant = selectDominantRoleIntent(candidates, canonicalOrigin);
+        return dominant ? [dominant] : [];
+    });
+}
 export function recordSubagentTurn(state, input) {
     const sessionId = input.sessionId.trim();
     const threadId = input.threadId.trim();
@@ -209,42 +1213,29 @@ export function recordSubagentTurn(state, input) {
     const requestedKind = input.kind === 'leader' || input.kind === 'subagent' ? input.kind : undefined;
     const requestedLeaderThreadId = input.leaderThreadId?.trim();
     const existingThread = existingSession.threads[threadId];
-    const existingKind = existingThread?.kind === 'leader' || existingThread?.kind === 'subagent'
-        ? existingThread.kind
-        : undefined;
+    const existingKind = existingThread?.kind === 'leader' || existingThread?.kind === 'subagent' ? existingThread.kind : undefined;
     const existingLeaderThreadId = existingSession.leader_thread_id?.trim();
     // `leader_thread_id` is the session's top-level leader boundary.  A native
     // subagent can itself be the immediate parent of a nested native role, but
     // that must not reclassify known subagent evidence as the session leader.
-    const requestedLeaderThread = requestedLeaderThreadId
-        ? existingSession.threads[requestedLeaderThreadId]
-        : undefined;
+    const requestedLeaderThread = requestedLeaderThreadId ? existingSession.threads[requestedLeaderThreadId] : undefined;
     const requestedLeaderWouldReclassifySubagent = requestedLeaderThread?.kind === 'subagent';
-    const requestedSessionLeaderThreadId = requestedLeaderWouldReclassifySubagent
-        ? undefined
-        : requestedLeaderThreadId;
+    const requestedSessionLeaderThreadId = requestedLeaderWouldReclassifySubagent ? undefined : requestedLeaderThreadId;
     const preserveExistingSubagent = existingKind === 'subagent' && requestedKind !== 'subagent';
-    const preserveKnownLeader = requestedKind === 'subagent'
-        && (existingKind === 'leader' || existingLeaderThreadId === threadId);
+    const preserveKnownLeader = requestedKind === 'subagent' && (existingKind === 'leader' || existingLeaderThreadId === threadId);
     const leaderThreadId = preserveKnownLeader
         ? existingLeaderThreadId || threadId
-        : existingLeaderThreadId
-            || requestedSessionLeaderThreadId
-            || (requestedKind === 'subagent' || preserveExistingSubagent ? undefined : threadId);
+        : existingLeaderThreadId || requestedSessionLeaderThreadId || (requestedKind === 'subagent' || preserveExistingSubagent ? undefined : threadId);
     const kind = preserveKnownLeader
         ? 'leader'
         : requestedKind === 'leader' && existingKind === 'subagent'
             ? 'subagent'
-            : requestedKind ?? (threadId === leaderThreadId ? 'leader' : existingKind ?? 'subagent');
+            : (requestedKind ?? (threadId === leaderThreadId ? 'leader' : (existingKind ?? 'subagent')));
     const requestedStatus = normalizeSubagentStatus(input.status);
     const preservedStatus = normalizeSubagentStatus(existingThread?.status);
     const preserveCompletionEvidence = input.preserveCompletionEvidence === true;
-    const clearsPriorCompletion = input.completed !== true
-        && preserveCompletionEvidence !== true
-        && Boolean(existingThread?.completed_at);
-    const status = requestedStatus
-        ?? (input.completed ? 'closed' : undefined)
-        ?? (clearsPriorCompletion ? undefined : preservedStatus);
+    const clearsPriorCompletion = input.completed !== true && preserveCompletionEvidence !== true && Boolean(existingThread?.completed_at);
+    const status = requestedStatus ?? (input.completed ? 'closed' : undefined) ?? (clearsPriorCompletion ? undefined : preservedStatus);
     const preservedCompletion = preserveCompletionEvidence && existingThread?.completed_at
         ? {
             completed_at: existingThread.completed_at,
@@ -258,7 +1249,11 @@ export function recordSubagentTurn(state, input) {
         first_seen_at: existingThread?.first_seen_at ?? timestamp,
         last_seen_at: timestamp,
         turn_count: (existingThread?.turn_count ?? 0) + 1,
-        ...(input.turnId?.trim() ? { last_turn_id: input.turnId.trim() } : existingThread?.last_turn_id ? { last_turn_id: existingThread.last_turn_id } : {}),
+        ...(input.turnId?.trim()
+            ? { last_turn_id: input.turnId.trim() }
+            : existingThread?.last_turn_id
+                ? { last_turn_id: existingThread.last_turn_id }
+                : {}),
         ...(input.completed
             ? {
                 completed_at: timestamp,
@@ -268,27 +1263,44 @@ export function recordSubagentTurn(state, input) {
             : preservedCompletion),
         ...(input.mode?.trim() ? { mode: input.mode.trim() } : existingThread?.mode ? { mode: existingThread.mode } : {}),
         ...(input.role?.trim() ? { role: input.role.trim() } : existingThread?.role ? { role: existingThread.role } : {}),
+        ...(input.provenanceKind?.trim()
+            ? { provenance_kind: input.provenanceKind.trim() }
+            : existingThread?.provenance_kind
+                ? { provenance_kind: existingThread.provenance_kind }
+                : {}),
         ...(input.laneId?.trim() ? { lane_id: input.laneId.trim() } : existingThread?.lane_id ? { lane_id: existingThread.lane_id } : {}),
         ...(input.scope?.trim() ? { scope: input.scope.trim() } : existingThread?.scope ? { scope: existingThread.scope } : {}),
         ...(input.agentNickname?.trim()
             ? { agent_nickname: input.agentNickname.trim() }
-            : existingThread?.agent_nickname ? { agent_nickname: existingThread.agent_nickname } : {}),
+            : existingThread?.agent_nickname
+                ? { agent_nickname: existingThread.agent_nickname }
+                : {}),
         ...(status ? { status } : {}),
         ...(input.lastHandoffSummary?.trim()
             ? { last_handoff_summary: input.lastHandoffSummary.trim() }
-            : existingThread?.last_handoff_summary ? { last_handoff_summary: existingThread.last_handoff_summary } : {}),
+            : existingThread?.last_handoff_summary
+                ? { last_handoff_summary: existingThread.last_handoff_summary }
+                : {}),
         ...(input.resumeRequestedAt?.trim()
             ? { resume_requested_at: input.resumeRequestedAt.trim() }
-            : existingThread?.resume_requested_at ? { resume_requested_at: existingThread.resume_requested_at } : {}),
+            : existingThread?.resume_requested_at
+                ? { resume_requested_at: existingThread.resume_requested_at }
+                : {}),
         ...(input.resumeCompletedAt?.trim()
             ? { resume_completed_at: input.resumeCompletedAt.trim() }
-            : existingThread?.resume_completed_at ? { resume_completed_at: existingThread.resume_completed_at } : {}),
+            : existingThread?.resume_completed_at
+                ? { resume_completed_at: existingThread.resume_completed_at }
+                : {}),
         ...(input.resumeFailedAt?.trim()
             ? { resume_failed_at: input.resumeFailedAt.trim() }
-            : existingThread?.resume_failed_at ? { resume_failed_at: existingThread.resume_failed_at } : {}),
+            : existingThread?.resume_failed_at
+                ? { resume_failed_at: existingThread.resume_failed_at }
+                : {}),
         ...(input.resumeFailureReason?.trim()
             ? { resume_failure_reason: input.resumeFailureReason.trim() }
-            : existingThread?.resume_failure_reason ? { resume_failure_reason: existingThread.resume_failure_reason } : {}),
+            : existingThread?.resume_failure_reason
+                ? { resume_failure_reason: existingThread.resume_failure_reason }
+                : {}),
     };
     const threads = {
         ...existingSession.threads,
@@ -303,16 +1315,24 @@ export function recordSubagentTurn(state, input) {
     normalized.sessions[sessionId] = {
         session_id: sessionId,
         ...(leaderThreadId ? { leader_thread_id: leaderThreadId } : {}),
+        // #3181: preserve the durable native leader attestation across ordinary turn writes.
+        // Dropping these would let a normal child SessionStart/bind erase authentication and
+        // silently downgrade later role-intent writes to the legacy (non-atomic) path.
+        ...(existingSession.leader_attested_at ? { leader_attested_at: existingSession.leader_attested_at } : {}),
+        ...(existingSession.leader_attest_source ? { leader_attest_source: existingSession.leader_attest_source } : {}),
         updated_at: timestamp,
         threads,
     };
     return normalized;
 }
 export async function recordSubagentTurnForSession(cwd, input) {
-    const current = await readSubagentTrackingState(cwd);
-    const next = recordSubagentTurn(current, input);
-    await writeSubagentTrackingState(cwd, next);
-    return next;
+    return withCrossProcessFileLockSync(subagentTrackingPath(cwd), (context) => {
+        const current = readSubagentTrackingStateSync(cwd);
+        const next = recordSubagentTurn(current, input);
+        context.assertOwnership();
+        writeSubagentTrackingStateSync(cwd, next, context.publish);
+        return next;
+    });
 }
 export function summarizeSubagentSession(state, sessionId, options = {}) {
     const normalized = normalizeSubagentTrackingState(state);
@@ -320,11 +1340,7 @@ export function summarizeSubagentSession(state, sessionId, options = {}) {
     if (!session)
         return null;
     const activeWindowMs = options.activeWindowMs ?? DEFAULT_SUBAGENT_ACTIVE_WINDOW_MS;
-    const nowMs = typeof options.now === 'string'
-        ? Date.parse(options.now)
-        : options.now instanceof Date
-            ? options.now.getTime()
-            : Date.now();
+    const nowMs = typeof options.now === 'string' ? Date.parse(options.now) : options.now instanceof Date ? options.now.getTime() : Date.now();
     const allThreadIds = Object.keys(session.threads).sort();
     const allSubagentThreadIds = allThreadIds.filter((threadId) => isTrustedSubagentThread(session, threadId));
     const activeSubagentThreadIds = allSubagentThreadIds.filter((threadId) => {