@fitlab-ai/agent-infra 0.9.7 → 0.9.9

package/dist/lib/sandbox/control/lifecycle.js

@@ -1,14 +1,17 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { buildProcessTreeStopCommand } from '../../server/process-control.js';
-import { processIdentityMatches } from '../../server/process-state.js';
+import { getProcessIdentityState, getProcessStartTime } from '../../server/process-state.js';
 import { DEFAULT_SANDBOX_CONTROL_TIMING } from './protocol.js';
 import { inspectSandboxControlContainer } from './container-identity.js';
 import { parseSandboxControlStatus, readExecution, terminateSandboxControlExecution } from './state.js';
 const DEFAULT_QUIESCE_TIMEOUT_MS = DEFAULT_SANDBOX_CONTROL_TIMING.quiesceDeadlineMs;
 const QUIESCING_FILE = 'quiescing.json';
 const BROKER_STARTING_FILE = 'broker-starting.json';
+const REPLACEMENT_FILE = 'replacement.json';
+const REPLACEMENT_STATE_SUFFIX = '.replacement-state.json';
 async function awaitWithDeadline(operation, deadlineAt, errorCode) {
     const remaining = deadlineAt - Date.now();
     if (remaining <= 0)
@@ -76,14 +79,14 @@ function readStartupOwner(filePath) {
         return null;
     }
 }
-async function waitForStartupTransition(root, timeoutMs) {
+async function waitForStartupTransition(root, timeoutMs, identityProbe = getProcessIdentityState) {
     const transitionPath = path.join(root, BROKER_STARTING_FILE);
     const deadline = Date.now() + timeoutMs;
-    while (Date.now() < deadline) {
+    while (true) {
         const transition = readStartupOwner(transitionPath);
         if (!fs.existsSync(transitionPath))
             return;
-        if (transition && !ownerLive(transition.owner)) {
+        if (transition && !ownerLive(transition.owner, identityProbe)) {
             try {
                 if (fs.readFileSync(transitionPath, 'utf8') === transition.raw)
                     fs.unlinkSync(transitionPath);
@@ -93,11 +96,13 @@ async function waitForStartupTransition(root, timeoutMs) {
             }
             continue;
         }
+        if (Date.now() >= deadline)
+            break;
         await new Promise((resolve) => setTimeout(resolve, 25));
     }
     throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
 }
-export async function acquireSandboxControlBrokerStartup(root, owner, timeoutMs = 5_000) {
+export async function acquireSandboxControlBrokerStartup(root, owner, timeoutMs = 5_000, options = {}) {
     const resolvedRoot = path.resolve(root);
     const transitionPath = path.join(resolvedRoot, BROKER_STARTING_FILE);
     const record = `${JSON.stringify({ version: 2, ...owner })}\n`;
@@ -131,7 +136,7 @@ export async function acquireSandboxControlBrokerStartup(root, owner, timeoutMs
             if (error.code !== 'EEXIST')
                 throw error;
             const transition = readStartupOwner(transitionPath);
-            if (transition && !ownerLive(transition.owner)) {
+            if (transition && !ownerLive(transition.owner, options.identityProbe)) {
                 try {
                     if (fs.readFileSync(transitionPath, 'utf8') === transition.raw)
                         fs.unlinkSync(transitionPath);
@@ -146,40 +151,342 @@ export async function acquireSandboxControlBrokerStartup(root, owner, timeoutMs
     }
     throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
 }
-export function readSandboxControlManifest(manifestPath) {
+function replacementPath(root) {
+    return path.join(root, REPLACEMENT_FILE);
+}
+function replacementStatePath(root) {
+    const resolvedRoot = path.resolve(root);
+    return path.join(path.dirname(resolvedRoot), `.${path.basename(resolvedRoot)}${REPLACEMENT_STATE_SUFFIX}`);
+}
+function replacementSnapshotPath(root, transitionId) {
+    const resolvedRoot = path.resolve(root);
+    return path.join(path.dirname(resolvedRoot), `.${path.basename(resolvedRoot)}.replacement-${transitionId}.snapshot`);
+}
+function writeAtomicText(filePath, content) {
+    const temporary = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        fs.renameSync(temporary, filePath);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+function readReplacementState(root) {
+    const filePath = replacementStatePath(root);
+    if (!fs.existsSync(filePath))
+        return null;
+    if (!regularFile(filePath))
+        throw new Error('SANDBOX_CONTROL_REPLACEMENT_RECOVERY_INVALID');
+    try {
+        const value = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        const resolvedRoot = path.resolve(root);
+        if (value.version !== 1 || (value.phase !== 'prepared' && value.phase !== 'committed')
+            || value.root !== resolvedRoot || typeof value.transitionId !== 'string' || value.transitionId.length === 0
+            || value.snapshotRoot !== replacementSnapshotPath(resolvedRoot, value.transitionId)) {
+            throw new Error('invalid replacement state');
+        }
+        return value;
+    }
+    catch {
+        throw new Error('SANDBOX_CONTROL_REPLACEMENT_RECOVERY_INVALID');
+    }
+}
+function writeReplacementState(state) {
+    writeAtomicText(replacementStatePath(state.root), `${JSON.stringify(state)}\n`);
+}
+function removeReplacementState(root) {
+    fs.rmSync(replacementStatePath(root), { force: true });
+}
+function readReplacementRecord(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    if (!regularFile(filePath))
+        throw new Error('SANDBOX_CONTROL_REPLACEMENT_INVALID');
+    const raw = fs.readFileSync(filePath, 'utf8');
+    try {
+        const value = JSON.parse(raw);
+        if (value.version !== 1 || typeof value.transitionId !== 'string' || value.transitionId.length === 0
+            || !Number.isSafeInteger(value.pid) || (value.pid ?? 0) <= 0
+            || !Number.isSafeInteger(value.startTime))
+            throw new Error('invalid replacement');
+        return { raw, record: value };
+    }
+    catch {
+        throw new Error('SANDBOX_CONTROL_REPLACEMENT_INVALID');
+    }
+}
+export function acquireSandboxControlReplacement(root, options = {}) {
+    const resolvedRoot = path.resolve(root);
+    if (fs.existsSync(resolvedRoot)) {
+        const stat = fs.lstatSync(resolvedRoot);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+    }
+    else {
+        fs.mkdirSync(resolvedRoot, { recursive: true, mode: 0o700 });
+    }
+    const startTime = options.owner?.startTime ?? getProcessStartTime(process.pid);
+    if (startTime === null || startTime === undefined)
+        throw new Error('SANDBOX_CONTROL_REPLACEMENT_OWNER_UNAVAILABLE');
+    const owner = options.owner ?? { pid: process.pid, startTime };
+    const transitionId = randomUUID();
+    const record = `${JSON.stringify({ version: 1, transitionId, ...owner })}\n`;
+    const filePath = replacementPath(resolvedRoot);
+    const existing = readReplacementRecord(filePath);
+    if (existing) {
+        const ownerState = (options.probeOwner ?? getProcessIdentityState)(existing.record);
+        if (ownerState === 'alive') {
+            throw new Error('SANDBOX_CONTROL_REPLACEMENT_BUSY');
+        }
+        if (ownerState === 'unknown') {
+            throw new Error('SANDBOX_CONTROL_REPLACEMENT_OWNER_UNAVAILABLE');
+        }
+        if (fs.readFileSync(filePath, 'utf8') !== existing.raw) {
+            throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+        }
+        fs.unlinkSync(filePath);
+    }
+    try {
+        fs.writeFileSync(filePath, record, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new Error('SANDBOX_CONTROL_REPLACEMENT_BUSY');
+        }
+        throw error;
+    }
+    let released = false;
+    const verifyOwnership = () => {
+        if (released)
+            throw new Error('SANDBOX_CONTROL_REPLACEMENT_RELEASED');
+        const current = readReplacementRecord(filePath);
+        if (!current || current.raw !== record || current.record.transitionId !== transitionId) {
+            throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+        }
+    };
+    return {
+        root: resolvedRoot,
+        transitionId,
+        owner,
+        assertOwned: verifyOwnership,
+        clearQuiescing() {
+            verifyOwnership();
+            const markerPath = path.join(resolvedRoot, QUIESCING_FILE);
+            if (fs.existsSync(markerPath)) {
+                if (!regularFile(markerPath))
+                    throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+                fs.unlinkSync(markerPath);
+            }
+        },
+        release() {
+            if (released)
+                return;
+            verifyOwnership();
+            fs.unlinkSync(filePath);
+            released = true;
+        }
+    };
+}
+function readReplacementRaw(root) {
+    const current = readReplacementRecord(replacementPath(root));
+    if (!current)
+        throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+    return current.raw;
+}
+export function beginSandboxControlReplacement(root, lease) {
+    const resolvedRoot = path.resolve(root);
+    if (path.resolve(lease.root) !== resolvedRoot)
+        throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+    lease.assertOwned();
+    if (!fs.existsSync(resolvedRoot))
+        throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+    const rootStat = fs.lstatSync(resolvedRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+    if (readReplacementState(resolvedRoot))
+        throw new Error('SANDBOX_CONTROL_REPLACEMENT_RECOVERY_REQUIRED');
+    const snapshotRoot = replacementSnapshotPath(resolvedRoot, lease.transitionId);
+    if (fs.existsSync(snapshotRoot))
+        throw new Error('SANDBOX_CONTROL_REPLACEMENT_RECOVERY_INVALID');
+    const replacementRaw = readReplacementRaw(resolvedRoot);
+    const state = {
+        version: 1,
+        phase: 'prepared',
+        root: resolvedRoot,
+        snapshotRoot,
+        transitionId: lease.transitionId
+    };
+    writeReplacementState(state);
+    let moved = false;
+    try {
+        fs.renameSync(resolvedRoot, snapshotRoot);
+        moved = true;
+        fs.mkdirSync(resolvedRoot, { recursive: true, mode: 0o700 });
+        fs.writeFileSync(replacementPath(resolvedRoot), replacementRaw, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        markSandboxControlRootQuiescing(resolvedRoot);
+        return { root: resolvedRoot, snapshotRoot, transitionId: lease.transitionId };
+    }
+    catch (error) {
+        if (moved) {
+            fs.rmSync(resolvedRoot, { recursive: true, force: true });
+            fs.renameSync(snapshotRoot, resolvedRoot);
+        }
+        removeReplacementState(resolvedRoot);
+        throw error;
+    }
+}
+function isRecoverableCutoverManifestError(error) {
+    return error instanceof Error
+        && (error.message.startsWith('SANDBOX_CONTROL_MANIFEST_')
+            || error.message === 'SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
+}
+export async function recoverSandboxControlReplacement(root, lease) {
+    const resolvedRoot = path.resolve(root);
+    if (path.resolve(lease.root) !== resolvedRoot)
+        throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+    const state = readReplacementState(resolvedRoot);
+    if (!state)
+        return 'none';
+    lease.assertOwned();
+    if (state.phase === 'committed') {
+        fs.rmSync(state.snapshotRoot, { recursive: true, force: true });
+        removeReplacementState(resolvedRoot);
+        return 'committed';
+    }
+    if (!fs.existsSync(state.snapshotRoot)) {
+        removeReplacementState(resolvedRoot);
+        return 'none';
+    }
+    if (fs.existsSync(resolvedRoot) && fs.existsSync(path.join(resolvedRoot, 'manifest.json'))) {
+        try {
+            await quiesceSandboxControlRoot(resolvedRoot);
+        }
+        catch (error) {
+            if (!isRecoverableCutoverManifestError(error))
+                throw error;
+        }
+    }
+    lease.assertOwned();
+    const replacementRaw = readReplacementRaw(resolvedRoot);
+    fs.rmSync(resolvedRoot, { recursive: true, force: true });
+    fs.renameSync(state.snapshotRoot, resolvedRoot);
+    writeAtomicText(replacementPath(resolvedRoot), replacementRaw);
+    removeReplacementState(resolvedRoot);
+    return 'restored';
+}
+export function commitSandboxControlReplacement(root, lease) {
+    const resolvedRoot = path.resolve(root);
+    if (path.resolve(lease.root) !== resolvedRoot)
+        throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+    const state = readReplacementState(resolvedRoot);
+    if (!state)
+        return;
+    lease.assertOwned();
+    writeReplacementState({ ...state, phase: 'committed' });
+    fs.rmSync(state.snapshotRoot, { recursive: true, force: true });
+    removeReplacementState(resolvedRoot);
+}
+function readOptionalRaw(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    if (!regularFile(filePath))
+        throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+    return fs.readFileSync(filePath, 'utf8');
+}
+function readProcessingSnapshot(root) {
+    const processingDir = path.join(root, 'processing');
+    if (!fs.existsSync(processingDir))
+        return [];
+    const stat = fs.lstatSync(processingDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
+    return fs.readdirSync(processingDir, { withFileTypes: true })
+        .map((entry) => ({
+        name: entry.name,
+        directory: entry.isDirectory() && !entry.isSymbolicLink(),
+        executionRaw: entry.isDirectory() && !entry.isSymbolicLink()
+            ? readOptionalRaw(path.join(processingDir, entry.name, 'execution.json'))
+            : null
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+export function captureSandboxControlCutoverSnapshot(root) {
+    const resolvedRoot = path.resolve(root);
+    const manifestPath = path.join(resolvedRoot, 'manifest.json');
+    if (fs.existsSync(manifestPath))
+        readSandboxControlManifestForTransition(manifestPath);
+    return {
+        root: resolvedRoot,
+        manifestRaw: readOptionalRaw(manifestPath),
+        brokerRaw: readOptionalRaw(path.join(resolvedRoot, 'broker.json')),
+        statusRaw: readOptionalRaw(path.join(resolvedRoot, 'public', 'status.json')),
+        processing: readProcessingSnapshot(resolvedRoot)
+    };
+}
+export function assertSandboxControlCutoverSnapshot(snapshot) {
+    const current = captureSandboxControlCutoverSnapshot(snapshot.root);
+    if (JSON.stringify(current) !== JSON.stringify(snapshot)) {
+        throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+    }
+}
+function readSandboxControlManifestValue(manifestPath, allowLegacy) {
     if (!regularFile(manifestPath))
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     let manifest;
     try {
-        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('invalid manifest');
+        }
+        manifest = parsed;
     }
     catch {
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     }
-    if (manifest.version !== 4) {
-        throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 4; container-only recreation is required');
-    }
-    if (typeof manifest.engine !== 'string' || manifest.engine.length === 0
-        || typeof manifest.repoRoot !== 'string' || typeof manifest.worktreeRoot !== 'string'
-        || typeof manifest.project !== 'string' || typeof manifest.container !== 'string'
-        || !manifest.containerIdentity || typeof manifest.containerIdentity.id !== 'string'
-        || manifest.containerIdentity.id.length === 0 || !manifest.containerIdentity.labels
-        || typeof manifest.containerIdentity.labels !== 'object'
-        || Array.isArray(manifest.containerIdentity.labels)
-        || Object.values(manifest.containerIdentity.labels).some((value) => typeof value !== 'string')
-        || typeof manifest.branch !== 'string' || !['task-bound', 'branch-only'].includes(manifest.mode ?? '')
-        || (manifest.taskId !== null && typeof manifest.taskId !== 'string')
-        || typeof manifest.channelDir !== 'string' || typeof manifest.publicStatusDir !== 'string'
-        || typeof manifest.processingDir !== 'string' || typeof manifest.token !== 'string'
-        || typeof manifest.generation !== 'string')
+    const candidate = manifest;
+    if (candidate.version !== 4 && candidate.version !== 5) {
+        throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 5; container-only recreation is required');
+    }
+    if (typeof candidate.containerIdentity !== 'object' || candidate.containerIdentity === null
+        || Array.isArray(candidate.containerIdentity))
+        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+    const containerIdentity = candidate.containerIdentity;
+    if (typeof candidate.engine !== 'string' || candidate.engine.length === 0
+        || typeof candidate.repoRoot !== 'string' || typeof candidate.worktreeRoot !== 'string'
+        || typeof candidate.project !== 'string' || typeof candidate.container !== 'string'
+        || typeof containerIdentity.id !== 'string' || containerIdentity.id.length === 0
+        || typeof containerIdentity.labels !== 'object' || containerIdentity.labels === null
+        || Array.isArray(containerIdentity.labels)
+        || Object.values(containerIdentity.labels).some((value) => typeof value !== 'string')
+        || typeof candidate.branch !== 'string' || !['task-bound', 'branch-only'].includes(candidate.mode ?? '')
+        || (candidate.taskId !== null && typeof candidate.taskId !== 'string')
+        || typeof candidate.channelDir !== 'string' || typeof candidate.publicStatusDir !== 'string'
+        || typeof candidate.processingDir !== 'string' || typeof candidate.token !== 'string'
+        || typeof candidate.generation !== 'string')
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     const root = path.dirname(path.resolve(manifestPath));
-    if (path.resolve(manifest.channelDir) !== path.join(root, 'channel')
-        || path.resolve(manifest.publicStatusDir) !== path.join(root, 'public')
-        || path.resolve(manifest.processingDir) !== path.join(root, 'processing')) {
+    if (path.resolve(candidate.channelDir) !== path.join(root, 'channel')
+        || path.resolve(candidate.publicStatusDir) !== path.join(root, 'public')
+        || path.resolve(candidate.processingDir) !== path.join(root, 'processing')) {
+        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+    }
+    if (candidate.version === 4) {
+        if (!allowLegacy) {
+            throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 5; container-only recreation is required');
+        }
+        return candidate;
+    }
+    if (typeof candidate.runtimeDir !== 'string' || path.resolve(candidate.runtimeDir) !== path.join(root, 'runtime')) {
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     }
-    return manifest;
+    return candidate;
+}
+export function readSandboxControlManifest(manifestPath) {
+    return readSandboxControlManifestValue(manifestPath, false);
+}
+export function readSandboxControlManifestForTransition(manifestPath) {
+    return readSandboxControlManifestValue(manifestPath, true);
 }
 function readBrokerOwner(filePath) {
     if (!fs.existsSync(filePath))
@@ -216,8 +523,11 @@ function sameOwner(left, right) {
     return left.pid === right.pid && left.startTime === right.startTime
         && (!left.brokerId || !right.brokerId || left.brokerId === right.brokerId);
 }
-function ownerLive(owner) {
-    return processIdentityMatches({ pid: owner.pid, startTime: owner.startTime });
+function ownerLive(owner, identityProbe = getProcessIdentityState) {
+    const state = identityProbe({ pid: owner.pid, startTime: owner.startTime });
+    if (state === 'unknown')
+        throw new Error('SANDBOX_CONTROL_OWNER_UNAVAILABLE');
+    return state === 'alive';
 }
 function readExecutions(manifest) {
     if (!fs.existsSync(manifest.processingDir))
@@ -250,38 +560,45 @@ function readExecutions(manifest) {
     }
     return executions;
 }
-function processGroupAlive(groupId) {
+function processGroupState(groupId) {
     try {
         const rows = execFileSync('ps', ['-axo', 'pgid=,stat='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
         return rows.split('\n').some((row) => {
             const match = row.trim().match(/^(\d+)\s+(\S+)/);
             return Number(match?.[1]) === groupId && !match?.[2]?.startsWith('Z');
-        });
+        }) ? 'alive' : 'dead';
     }
     catch {
         try {
             process.kill(-groupId, 0);
-            return true;
+            return 'alive';
         }
         catch (error) {
-            return error.code === 'EPERM';
+            const code = error.code;
+            if (code === 'ESRCH')
+                return 'dead';
+            if (code === 'EPERM')
+                return 'alive';
+            return 'unknown';
         }
     }
 }
-function executionAlive(execution, platform) {
-    if (platform !== 'win32' && execution.child.processGroupId) {
-        return processGroupAlive(execution.child.processGroupId);
-    }
-    return processIdentityMatches({ pid: execution.child.pid, startTime: execution.child.startTime });
+function executionAlive(execution, platform, identityProbe = getProcessIdentityState) {
+    const state = platform !== 'win32' && execution.child.processGroupId
+        ? processGroupState(execution.child.processGroupId)
+        : identityProbe({ pid: execution.child.pid, startTime: execution.child.startTime });
+    if (state === 'unknown')
+        throw new Error('SANDBOX_CONTROL_EXECUTION_OWNER_UNAVAILABLE');
+    return state === 'alive';
 }
-async function waitForExit(owner, timeoutMs, deadlineAt) {
+async function waitForExit(owner, timeoutMs, deadlineAt, identityProbe = getProcessIdentityState) {
     const deadline = deadlineAt ?? (Date.now() + timeoutMs);
     while (Date.now() < deadline) {
-        if (!ownerLive(owner))
+        if (!ownerLive(owner, identityProbe))
             return true;
         await new Promise((resolve) => setTimeout(resolve, 25));
     }
-    return !ownerLive(owner);
+    return !ownerLive(owner, identityProbe);
 }
 function signalOwner(owner, platform, force) {
     try {
@@ -318,17 +635,18 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
             throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
     }
     const timeoutMs = options.timeoutMs ?? options.timing?.quiesceDeadlineMs ?? DEFAULT_QUIESCE_TIMEOUT_MS;
+    const identityProbe = options.identityProbe ?? getProcessIdentityState;
     const deadlineAt = Date.now() + timeoutMs;
     const forceAt = forceDeadline(deadlineAt, timeoutMs);
     markSandboxControlRootQuiescing(resolvedRoot);
-    await waitForStartupTransition(resolvedRoot, Math.max(0, forceAt - Date.now()));
+    await waitForStartupTransition(resolvedRoot, Math.max(0, forceAt - Date.now()), identityProbe);
     const manifestPath = path.join(resolvedRoot, 'manifest.json');
-    const manifest = fs.existsSync(manifestPath) ? readSandboxControlManifest(manifestPath) : null;
+    const manifest = fs.existsSync(manifestPath) ? readSandboxControlManifestForTransition(manifestPath) : null;
     const broker = readBrokerOwner(path.join(resolvedRoot, 'broker.json'));
     const status = readStatusOwner(path.join(resolvedRoot, 'public', 'status.json'));
     const statusOwner = status ? status.broker : null;
-    const brokerLive = broker ? ownerLive(broker) : false;
-    const statusLive = statusOwner ? ownerLive(statusOwner) : false;
+    const brokerLive = broker ? ownerLive(broker, identityProbe) : false;
+    const statusLive = statusOwner ? ownerLive(statusOwner, identityProbe) : false;
     if (manifest && broker && (broker.token !== manifest.token || broker.generation !== manifest.generation)) {
         throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
     }
@@ -347,11 +665,11 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
         if (manifest && !broker && !status)
             throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
         for (const execution of executions) {
-            terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false });
+            terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false, identityProbe });
         }
         const softDeadlineAt = Math.min(forceAt, Date.now() + Math.floor(Math.max(0, forceAt - Date.now()) / 2));
         while (Date.now() < softDeadlineAt) {
-            if (!executions.some((execution) => executionAlive(execution, platform)))
+            if (!executions.some((execution) => executionAlive(execution, platform, identityProbe)))
                 break;
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
@@ -361,12 +679,12 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
             throw new Error('SANDBOX_CONTROL_QUIESCE_DEADLINE_EXCEEDED');
         for (const execution of executions) {
             if (!terminateSandboxControlExecution(execution, {
-                platform, timeoutMs: Math.max(0, deadlineAt - Date.now()), deadlineAt, forceAt: Date.now()
+                platform, timeoutMs: Math.max(0, deadlineAt - Date.now()), deadlineAt, forceAt: Date.now(), identityProbe
             })) {
                 throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
             }
         }
-        if (executions.some((execution) => executionAlive(execution, platform))) {
+        if (executions.some((execution) => executionAlive(execution, platform, identityProbe))) {
             throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
         }
         return broker || status ? 'stale' : 'missing';
@@ -374,15 +692,15 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
     const remaining = () => Math.max(0, deadlineAt - Date.now());
     signalOwner(owner, platform, false);
     for (const execution of executions) {
-        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false });
+        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false, identityProbe });
     }
     const softDeadlineAt = Math.min(forceAt, Date.now() + Math.floor(Math.max(0, forceAt - Date.now()) / 2));
     while (Date.now() < softDeadlineAt) {
-        if (!ownerLive(owner) && !executions.some((execution) => executionAlive(execution, platform)))
+        if (!ownerLive(owner, identityProbe) && !executions.some((execution) => executionAlive(execution, platform, identityProbe)))
             break;
         await new Promise((resolve) => setTimeout(resolve, 25));
     }
-    if (!ownerLive(owner) && !executions.some((execution) => executionAlive(execution, platform))) {
+    if (!ownerLive(owner, identityProbe) && !executions.some((execution) => executionAlive(execution, platform, identityProbe))) {
         return 'stopped';
     }
     if (manifest)
@@ -390,17 +708,17 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
     if (Date.now() >= deadlineAt)
         throw new Error('SANDBOX_CONTROL_QUIESCE_DEADLINE_EXCEEDED');
     for (const execution of executions) {
-        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, deadlineAt, forceAt: Date.now() });
+        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, deadlineAt, forceAt: Date.now(), identityProbe });
     }
     signalOwner(owner, platform, true);
     while (Date.now() < deadlineAt) {
-        if (!ownerLive(owner) && !executions.some((execution) => executionAlive(execution, platform)))
+        if (!ownerLive(owner, identityProbe) && !executions.some((execution) => executionAlive(execution, platform, identityProbe)))
             return 'stopped';
         await new Promise((resolve) => setTimeout(resolve, 25));
     }
-    if (ownerLive(owner))
+    if (ownerLive(owner, identityProbe))
         throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
-    if (executions.some((execution) => executionAlive(execution, platform)))
+    if (executions.some((execution) => executionAlive(execution, platform, identityProbe)))
         throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
     return 'stopped';
 }
@@ -412,10 +730,11 @@ export async function removeSandboxControlRoot(root, options) {
     if (!stat.isDirectory() || stat.isSymbolicLink())
         throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
     const manifestPath = path.join(resolvedRoot, 'manifest.json');
-    const manifest = readSandboxControlManifest(manifestPath);
+    const manifest = readSandboxControlManifestForTransition(manifestPath);
     const inspectContainer = options.inspectContainer
         ?? ((timeoutMs) => inspectSandboxControlContainer(manifest, { timeoutMs }));
     const timeoutMs = options.timeoutMs ?? options.timing?.quiesceDeadlineMs ?? DEFAULT_QUIESCE_TIMEOUT_MS;
+    const identityProbe = options.identityProbe ?? getProcessIdentityState;
     const deadlineAt = Date.now() + timeoutMs;
     const forceAt = forceDeadline(deadlineAt, timeoutMs);
     const remaining = () => Math.max(0, deadlineAt - Date.now());
@@ -426,7 +745,7 @@ export async function removeSandboxControlRoot(root, options) {
         throw new Error('SANDBOX_CONTROL_CONTAINER_REAPPEARED');
     }
     markSandboxControlRootQuiescing(resolvedRoot);
-    await waitForStartupTransition(resolvedRoot, Math.max(0, forceAt - Date.now()));
+    await waitForStartupTransition(resolvedRoot, Math.max(0, forceAt - Date.now()), identityProbe);
     const brokerPath = path.join(resolvedRoot, 'broker.json');
     const statusPath = path.join(resolvedRoot, 'public', 'status.json');
     const broker = readBrokerOwner(brokerPath);
@@ -438,12 +757,12 @@ export async function removeSandboxControlRoot(root, options) {
         throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
     }
     if (broker && status && !sameOwner(broker, status.broker)
-        && (ownerLive(broker) || ownerLive(status.broker))) {
+        && (ownerLive(broker, identityProbe) || ownerLive(status.broker, identityProbe))) {
         throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
     }
     const platform = options.platform ?? process.platform;
-    const owner = broker && ownerLive(broker) ? broker
-        : status && ownerLive(status.broker) ? status.broker : null;
+    const owner = broker && ownerLive(broker, identityProbe) ? broker
+        : status && ownerLive(status.broker, identityProbe) ? status.broker : null;
     const selfOwner = options.selfOwner;
     const selfOwned = Boolean(selfOwner && broker && sameOwner(broker, selfOwner));
     if (selfOwner && (!broker || !selfOwned || broker.token !== manifest.token || broker.generation !== manifest.generation)) {
@@ -453,11 +772,12 @@ export async function removeSandboxControlRoot(root, options) {
     if (owner && !selfOwned)
         signalOwner(owner, platform, false);
     for (const execution of executions) {
-        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false });
+        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false, identityProbe });
     }
     const softDeadlineAt = Math.min(forceAt, Date.now() + Math.floor(Math.max(0, forceAt - Date.now()) / 2));
     while (Date.now() < softDeadlineAt) {
-        if ((!owner || selfOwned || !ownerLive(owner)) && !executions.some((execution) => executionAlive(execution, platform)))
+        if ((!owner || selfOwned || !ownerLive(owner, identityProbe))
+            && !executions.some((execution) => executionAlive(execution, platform, identityProbe)))
             break;
         await new Promise((resolve) => setTimeout(resolve, 25));
     }
@@ -472,7 +792,7 @@ export async function removeSandboxControlRoot(root, options) {
                 : 'SANDBOX_CONTROL_CONTAINER_STILL_EXISTS');
         }
     }
-    const currentManifest = readSandboxControlManifest(manifestPath);
+    const currentManifest = readSandboxControlManifestForTransition(manifestPath);
     if (currentManifest.token !== manifest.token || currentManifest.generation !== manifest.generation
         || !isSandboxControlRootQuiescing(resolvedRoot)) {
         throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
@@ -485,10 +805,10 @@ export async function removeSandboxControlRoot(root, options) {
     if (owner && currentBroker && !sameOwner(owner, currentBroker)) {
         throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
     }
-    if (!owner && currentBroker && ownerLive(currentBroker)) {
+    if (!owner && currentBroker && ownerLive(currentBroker, identityProbe)) {
         throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
     }
-    if (owner && ownerLive(owner) && !currentBroker) {
+    if (owner && ownerLive(owner, identityProbe) && !currentBroker) {
         throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
     }
     executions = mergeExecutions(executions, readExecutions(manifest));
@@ -496,21 +816,21 @@ export async function removeSandboxControlRoot(root, options) {
         throw new Error('SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
     for (const execution of executions) {
         if (!terminateSandboxControlExecution(execution, {
-            platform, timeoutMs: remaining(), deadlineAt, forceAt: Date.now()
+            platform, timeoutMs: remaining(), deadlineAt, forceAt: Date.now(), identityProbe
         })) {
             throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
         }
     }
-    if (owner && currentBroker && ownerLive(currentBroker) && !selfOwned) {
+    if (owner && currentBroker && ownerLive(currentBroker, identityProbe) && !selfOwned) {
         if (remaining() <= 0)
             throw new Error('SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
         signalOwner(currentBroker, platform, true);
-        if (remaining() <= 0 || !await waitForExit(currentBroker, remaining(), deadlineAt)) {
+        if (remaining() <= 0 || !await waitForExit(currentBroker, remaining(), deadlineAt, identityProbe)) {
             throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
         }
     }
     const finalExecutions = mergeExecutions(executions, readExecutions(manifest));
-    if (finalExecutions.some((execution) => executionAlive(execution, platform))) {
+    if (finalExecutions.some((execution) => executionAlive(execution, platform, identityProbe))) {
         throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
     }
     const finalBrokerRaw = fs.existsSync(brokerPath) ? fs.readFileSync(brokerPath, 'utf8') : null;
@@ -520,8 +840,9 @@ export async function removeSandboxControlRoot(root, options) {
             throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
         const finalSelfOwner = Boolean(selfOwner && sameOwner(finalBroker, selfOwner)
             && finalBroker.token === manifest.token && finalBroker.generation === manifest.generation);
-        if (ownerLive(finalBroker) && !finalSelfOwner)
+        if (ownerLive(finalBroker, identityProbe) && !finalSelfOwner) {
             throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
+        }
         if (fs.readFileSync(brokerPath, 'utf8') !== finalBrokerRaw) {
             throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
         }
@@ -532,7 +853,8 @@ export async function removeSandboxControlRoot(root, options) {
         const finalStatus = readStatusOwner(statusPath);
         if (!finalStatus)
             throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
-        if (ownerLive(finalStatus.broker) && !(selfOwner && sameOwner(finalStatus.broker, selfOwner))) {
+        if (ownerLive(finalStatus.broker, identityProbe)
+            && !(selfOwner && sameOwner(finalStatus.broker, selfOwner))) {
             throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
         }
         if (fs.readFileSync(statusPath, 'utf8') !== finalStatusRaw) {