@fitlab-ai/agent-infra 0.9.13 → 0.9.15

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

@@ -1,17 +1,455 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { buildProcessTreeStopCommand } from '../../server/process-control.js';
 import { getProcessIdentityState, getProcessStartTime } from '../../server/process-state.js';
 import { DEFAULT_SANDBOX_CONTROL_TIMING } from './protocol.js';
 import { inspectSandboxControlContainer } from './container-identity.js';
+import { acquireSandboxResourceLock, resolveSandboxLockNamespace } from './native-file-lock.js';
+import { isSandboxAuthorityEvidence } from '../engines/authority.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';
+const REMOVAL_JOURNAL_ROOT = path.join('.agent-infra', 'sandbox-removal-journal');
+export const SANDBOX_REMOVAL_JOURNAL_PHASES = [
+    'prepared', 'target-committed', 'container-removal', 'container-absent',
+    'carrier-finalizing', 'carrier-removed', 'workspace-finalizing', 'workspace-removed',
+    'branch-finalizing', 'branch-removed', 'tool-finalizing', 'tool-removed',
+    'shell-finalizing', 'shell-removed', 'share-finalizing', 'share-removed', 'completed'
+];
+function removalCarrierDigest(engine, containerId, generation) {
+    return createHash('sha256').update(`${engine}\0${containerId}\0${generation}`).digest('hex');
+}
+function assertPrivateDirectory(directory) {
+    const home = path.resolve(os.homedir());
+    const resolved = path.resolve(directory);
+    const relative = path.relative(home, resolved);
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_INVALID');
+    }
+    let current = home;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_INVALID');
+        }
+        if (process.platform !== 'win32' && typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+            throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_INVALID');
+        }
+    }
+}
+function removalJournalDomain(lockDomain, create = true) {
+    const namespace = resolveSandboxLockNamespace('sandbox-removal-journal', { lockDomain });
+    const root = path.join(path.dirname(namespace.lockRoot), REMOVAL_JOURNAL_ROOT.split(path.sep).at(-1));
+    if (create)
+        fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+    assertPrivateDirectory(root);
+    const domain = path.join(root, lockDomain);
+    if (create)
+        fs.mkdirSync(domain, { recursive: true, mode: 0o700 });
+    assertPrivateDirectory(domain);
+    return domain;
+}
+function removalJournalPath(manifest) {
+    return path.join(removalJournalDomain(manifest.authorityEvidence.lockDomain), `${removalCarrierDigest(manifest.engine, manifest.containerIdentity.id, manifest.generation)}.json`);
+}
+function removalJournalPathForRecord(record) {
+    return path.join(removalJournalDomain(record.lockDomain, false), `${record.carrierIdentityDigest}.json`);
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function hasExactKeys(value, keys) {
+    const actual = Object.keys(value).sort();
+    return actual.length === keys.length && actual.every((key, index) => key === keys[index]);
+}
+function isRemovalPermitCommit(value) {
+    if (!isRecord(value) || typeof value.path !== 'string' || !path.isAbsolute(value.path)
+        || (value.mode !== 'clean' && value.mode !== 'discard') || !isRecord(value.snapshot)
+        || typeof value.snapshot.worktree !== 'string' || !path.isAbsolute(value.snapshot.worktree)
+        || typeof value.snapshot.branch !== 'string' || typeof value.snapshot.head !== 'string'
+        || typeof value.snapshot.identity !== 'string' || !Array.isArray(value.snapshot.changes)
+        || value.snapshot.changes.some((change) => !isRecord(change)
+            || typeof change.indexStatus !== 'string' || typeof change.worktreeStatus !== 'string'
+            || typeof change.path !== 'string'
+            || (change.originalPath !== undefined && typeof change.originalPath !== 'string'))
+        || (value.snapshot.source !== undefined
+            && value.snapshot.source !== 'registered' && value.snapshot.source !== 'recovered'))
+        return false;
+    if (value.snapshot.recovery === undefined)
+        return true;
+    const recovery = value.snapshot.recovery;
+    return isRecord(recovery)
+        && typeof recovery.repoRoot === 'string' && path.isAbsolute(recovery.repoRoot)
+        && typeof recovery.worktreeBase === 'string' && path.isAbsolute(recovery.worktreeBase)
+        && typeof recovery.branch === 'string'
+        && (recovery.identitySource === 'branch-only' || recovery.identitySource === 'task-bound')
+        && (recovery.taskId === null || typeof recovery.taskId === 'string');
+}
+function parseRemovalJournal(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_INVALID');
+    }
+    if (!isRecord(value) || !hasExactKeys(value, [
+        'authorityFingerprint', 'carrierIdentityDigest', 'containerId', 'engine', 'expectedOldJournalRevision',
+        'generation', 'handoffId', 'lockDomain', 'newOperation', 'oldOperation', 'operation', 'owner', 'phase',
+        'recordedAt', 'revision', 'target', 'transitionId', 'version'
+    ]) || !isRecord(value.owner) || !hasExactKeys(value.owner, ['leaseNonce', 'pid', 'startTime'])
+        || !isRecord(value.target) || !hasExactKeys(value.target, [
+        'branch', 'controlRoot', 'permitDigest', 'permits', 'project', 'removeBranch', 'removeShare',
+        'removeWorktree', 'sharePath', 'shellPaths', 'targetDigest', 'toolPaths', 'workspaceViewPaths',
+        'worktreePaths'
+    ]) || value.version !== 2 || value.operation !== 'sandbox-rm'
+        || value.oldOperation !== 'sandbox-rm' || value.newOperation !== 'sandbox-rm'
+        || typeof value.handoffId !== 'string' || value.handoffId.length === 0
+        || typeof value.transitionId !== 'string' || value.transitionId.length === 0
+        || typeof value.engine !== 'string' || value.engine.length === 0
+        || typeof value.containerId !== 'string' || value.containerId.length === 0
+        || typeof value.generation !== 'string' || value.generation.length === 0
+        || typeof value.authorityFingerprint !== 'string' || !/^[a-f0-9]{64}$/u.test(value.authorityFingerprint)
+        || typeof value.carrierIdentityDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(value.carrierIdentityDigest)
+        || typeof value.lockDomain !== 'string' || !/^[a-f0-9]{64}$/u.test(value.lockDomain)
+        || !Number.isSafeInteger(value.owner.pid) || value.owner.pid <= 0
+        || !Number.isSafeInteger(value.owner.startTime) || typeof value.owner.leaseNonce !== 'string'
+        || value.owner.leaseNonce.length === 0
+        || !SANDBOX_REMOVAL_JOURNAL_PHASES.includes(value.phase)
+        || !(value.expectedOldJournalRevision === null
+            || (Number.isSafeInteger(value.expectedOldJournalRevision) && value.expectedOldJournalRevision >= 0))
+        || !Number.isSafeInteger(value.revision) || value.revision <= 0
+        || typeof value.target.branch !== 'string' || value.target.branch.length === 0
+        || typeof value.target.project !== 'string' || value.target.project.length === 0
+        || typeof value.target.controlRoot !== 'string' || path.isAbsolute(value.target.controlRoot) === false
+        || typeof value.target.targetDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(value.target.targetDigest)
+        || typeof value.target.permitDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(value.target.permitDigest)
+        || typeof value.target.removeWorktree !== 'boolean'
+        || typeof value.target.removeBranch !== 'boolean'
+        || typeof value.target.removeShare !== 'boolean'
+        || typeof value.target.sharePath !== 'string' || !path.isAbsolute(value.target.sharePath)
+        || !Array.isArray(value.target.worktreePaths) || value.target.worktreePaths.some((entry) => typeof entry !== 'string' || !path.isAbsolute(entry))
+        || !Array.isArray(value.target.workspaceViewPaths) || value.target.workspaceViewPaths.some((entry) => typeof entry !== 'string' || !path.isAbsolute(entry))
+        || !Array.isArray(value.target.toolPaths) || value.target.toolPaths.some((entry) => typeof entry !== 'string' || !path.isAbsolute(entry))
+        || !Array.isArray(value.target.shellPaths) || value.target.shellPaths.some((entry) => typeof entry !== 'string' || !path.isAbsolute(entry))
+        || !Array.isArray(value.target.permits)
+        || value.target.permits.some((permit) => !isRemovalPermitCommit(permit))
+        || !Number.isSafeInteger(value.recordedAt)) {
+        throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_INVALID');
+    }
+    const expected = value.expectedOldJournalRevision;
+    const revision = value.revision;
+    if ((expected === null && revision !== 1) || (expected !== null && revision !== expected + 1)) {
+        throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_INVALID');
+    }
+    return {
+        version: 2,
+        operation: 'sandbox-rm',
+        oldOperation: 'sandbox-rm',
+        newOperation: 'sandbox-rm',
+        handoffId: value.handoffId,
+        transitionId: value.transitionId,
+        engine: value.engine,
+        containerId: value.containerId,
+        generation: value.generation,
+        authorityFingerprint: value.authorityFingerprint,
+        carrierIdentityDigest: value.carrierIdentityDigest,
+        lockDomain: value.lockDomain,
+        owner: {
+            pid: value.owner.pid,
+            startTime: value.owner.startTime,
+            leaseNonce: value.owner.leaseNonce
+        },
+        phase: value.phase,
+        expectedOldJournalRevision: expected,
+        revision,
+        target: {
+            branch: value.target.branch,
+            project: value.target.project,
+            controlRoot: value.target.controlRoot,
+            targetDigest: value.target.targetDigest,
+            permitDigest: value.target.permitDigest,
+            removeWorktree: value.target.removeWorktree,
+            removeBranch: value.target.removeBranch,
+            removeShare: value.target.removeShare,
+            worktreePaths: value.target.worktreePaths,
+            workspaceViewPaths: value.target.workspaceViewPaths,
+            toolPaths: value.target.toolPaths,
+            shellPaths: value.target.shellPaths,
+            sharePath: value.target.sharePath,
+            permits: value.target.permits
+        },
+        recordedAt: value.recordedAt
+    };
+}
+function readRemovalJournalAt(target) {
+    if (!fs.existsSync(target))
+        return null;
+    const stat = fs.lstatSync(target);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_INVALID');
+    return parseRemovalJournal(fs.readFileSync(target, 'utf8'));
+}
+export function readSandboxRemovalJournal(manifest) {
+    return readRemovalJournalAt(removalJournalPath(manifest));
+}
+export function listSandboxRemovalJournals(filter = {}) {
+    const namespace = resolveSandboxLockNamespace('sandbox-removal-journal');
+    const root = path.join(path.dirname(namespace.lockRoot), REMOVAL_JOURNAL_ROOT.split(path.sep).at(-1));
+    if (!fs.existsSync(root))
+        return [];
+    assertPrivateDirectory(root);
+    const journals = [];
+    for (const domainEntry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (!domainEntry.isDirectory() || domainEntry.isSymbolicLink()) {
+            throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_INVALID');
+        }
+        const domain = path.join(root, domainEntry.name);
+        assertPrivateDirectory(domain);
+        for (const entry of fs.readdirSync(domain, { withFileTypes: true })) {
+            if (!entry.isFile() || entry.isSymbolicLink() || !entry.name.endsWith('.json')) {
+                throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_INVALID');
+            }
+            const record = readRemovalJournalAt(path.join(domain, entry.name));
+            if (!record || record.lockDomain !== domainEntry.name
+                || `${record.carrierIdentityDigest}.json` !== entry.name) {
+                throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_INVALID');
+            }
+            if ((!filter.branch || record.target.branch === filter.branch)
+                && (!filter.project || record.target.project === filter.project)
+                && (!filter.targetDigest || record.target.targetDigest === filter.targetDigest)) {
+                journals.push(record);
+            }
+        }
+    }
+    return journals;
+}
+export function clearSandboxRemovalJournalRecord(record) {
+    const target = removalJournalPathForRecord(record);
+    if (fs.existsSync(target)) {
+        const current = readRemovalJournalAt(target);
+        if (!current || current.revision !== record.revision || current.handoffId !== record.handoffId) {
+            throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_REVISION_MISMATCH');
+        }
+        fs.rmSync(target, { force: true });
+    }
+}
+export function clearSandboxRemovalJournal(manifest) {
+    const target = removalJournalPath(manifest);
+    if (fs.existsSync(target))
+        fs.rmSync(target, { force: true });
+}
+function defaultRemovalTarget(manifest) {
+    const targetDigest = createHash('sha256')
+        .update(`${manifest.project}\0${manifest.branch}\0${manifest.container}\0${manifest.channelDir}`)
+        .digest('hex');
+    return {
+        branch: manifest.branch,
+        project: manifest.project,
+        controlRoot: path.dirname(manifest.channelDir),
+        targetDigest,
+        permitDigest: createHash('sha256').update('none').digest('hex'),
+        removeWorktree: false,
+        removeBranch: false,
+        removeShare: false,
+        worktreePaths: [],
+        workspaceViewPaths: [],
+        toolPaths: [],
+        shellPaths: [],
+        sharePath: path.join(path.dirname(manifest.channelDir), 'share'),
+        permits: []
+    };
+}
+export function isDefaultSandboxRemovalJournal(journal) {
+    if (journal.phase !== 'carrier-removed' && journal.phase !== 'completed')
+        return false;
+    const { target } = journal;
+    const expected = defaultRemovalTarget({
+        project: target.project, branch: target.branch,
+        container: path.basename(path.dirname(target.controlRoot)),
+        channelDir: path.join(target.controlRoot, 'channel')
+    });
+    return Object.entries(expected).every(([key, value]) => JSON.stringify(target[key]) === JSON.stringify(value));
+}
+function sameRemovalTarget(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function phaseIndex(phase) {
+    return SANDBOX_REMOVAL_JOURNAL_PHASES.indexOf(phase);
+}
+export function sandboxRemovalPhaseIndex(phase) {
+    return phaseIndex(phase);
+}
+function assertNextRemovalPhase(current, next) {
+    const currentIndex = phaseIndex(current);
+    const nextIndex = phaseIndex(next);
+    if (nextIndex === currentIndex)
+        return false;
+    if (current === 'target-committed' && next === 'container-absent')
+        return true;
+    if (nextIndex !== currentIndex + 1) {
+        throw new Error('SANDBOX_CONTROL_REMOVAL_PHASE_TRANSITION_INVALID');
+    }
+    return true;
+}
+function assertRemovalJournalLock(record, resourceLock) {
+    const namespace = resolveSandboxLockNamespace(`${record.engine}:${record.containerId}`, {
+        lockDomain: record.lockDomain
+    });
+    if (resourceLock.lockDomain !== record.lockDomain || resourceLock.path !== namespace.lockPath) {
+        throw new Error('SANDBOX_CONTROL_REMOVAL_LOCK_MISMATCH');
+    }
+}
+function writeRemovalJournalAt(target, base, phase, expectedOldJournalRevision) {
+    const existing = readRemovalJournalAt(target);
+    if (expectedOldJournalRevision === null
+        ? existing !== null
+        : existing?.revision !== expectedOldJournalRevision) {
+        throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_REVISION_MISMATCH');
+    }
+    const record = {
+        ...base,
+        phase,
+        expectedOldJournalRevision,
+        revision: expectedOldJournalRevision === null ? 1 : expectedOldJournalRevision + 1,
+        recordedAt: Date.now()
+    };
+    const temporary = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: 0o600, flag: 'wx' });
+        if (expectedOldJournalRevision === null && fs.existsSync(target)) {
+            throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_REVISION_MISMATCH');
+        }
+        fs.renameSync(temporary, target);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+    return record;
+}
+function writeRemovalJournal(manifest, base, phase, expectedOldJournalRevision) {
+    return writeRemovalJournalAt(removalJournalPath(manifest), base, phase, expectedOldJournalRevision);
+}
+function startRemovalJournal(manifest, options) {
+    const target = removalJournalPath(manifest);
+    const existing = readRemovalJournalAt(target);
+    if (existing && (existing.engine !== manifest.engine || existing.containerId !== manifest.containerIdentity.id
+        || existing.generation !== manifest.generation
+        || existing.authorityFingerprint !== manifest.authorityEvidence.authorityFingerprint
+        || existing.lockDomain !== manifest.authorityEvidence.lockDomain)) {
+        throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_IDENTITY_MISMATCH');
+    }
+    const targetCommit = options.target ?? existing?.target ?? defaultRemovalTarget(manifest);
+    if (existing && options.target && !sameRemovalTarget(existing.target, options.target)) {
+        throw new Error('SANDBOX_CONTROL_REMOVAL_TARGET_MISMATCH');
+    }
+    if (existing) {
+        const state = options.identityProbe(existing.owner);
+        if (state === 'alive')
+            throw new Error('SANDBOX_CONTROL_REMOVE_RETRY_IN_PROGRESS');
+        if (state === 'unknown')
+            throw new Error('SANDBOX_CONTROL_REMOVE_OWNER_UNKNOWN');
+    }
+    const startTime = getProcessStartTime(process.pid);
+    if (startTime === null)
+        throw new Error('SANDBOX_CONTROL_REMOVE_OWNER_UNAVAILABLE');
+    const base = {
+        version: 2,
+        operation: 'sandbox-rm',
+        oldOperation: 'sandbox-rm',
+        newOperation: 'sandbox-rm',
+        handoffId: randomUUID(),
+        transitionId: randomUUID(),
+        engine: manifest.engine,
+        containerId: manifest.containerIdentity.id,
+        generation: manifest.generation,
+        authorityFingerprint: manifest.authorityEvidence.authorityFingerprint,
+        carrierIdentityDigest: removalCarrierDigest(manifest.engine, manifest.containerIdentity.id, manifest.generation),
+        lockDomain: manifest.authorityEvidence.lockDomain,
+        owner: { pid: process.pid, startTime, leaseNonce: randomUUID() },
+        target: targetCommit
+    };
+    const initialPhase = existing?.phase ?? 'prepared';
+    let record = writeRemovalJournal(manifest, base, initialPhase, existing?.revision ?? null);
+    return {
+        get record() { return record; },
+        write(phase) {
+            if (!assertNextRemovalPhase(record.phase, phase))
+                return record;
+            record = writeRemovalJournal(manifest, base, phase, record.revision);
+            return record;
+        }
+    };
+}
+export function claimSandboxRemovalJournal(journal, options = {}) {
+    const target = removalJournalPathForRecord(journal);
+    const resourceLock = options.resourceLock
+        ?? acquireSandboxResourceLock(`${journal.engine}:${journal.containerId}`, { lockDomain: journal.lockDomain });
+    const ownedLock = options.resourceLock ? null : resourceLock;
+    try {
+        assertRemovalJournalLock(journal, resourceLock);
+        const current = readRemovalJournalAt(target);
+        if (!current || current.revision !== journal.revision || current.handoffId !== journal.handoffId) {
+            throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_REVISION_MISMATCH');
+        }
+        const state = (options.identityProbe ?? getProcessIdentityState)(current.owner);
+        if (state === 'alive')
+            throw new Error('SANDBOX_CONTROL_REMOVE_RETRY_IN_PROGRESS');
+        if (state === 'unknown')
+            throw new Error('SANDBOX_CONTROL_REMOVE_OWNER_UNKNOWN');
+        const startTime = getProcessStartTime(process.pid);
+        if (startTime === null)
+            throw new Error('SANDBOX_CONTROL_REMOVE_OWNER_UNAVAILABLE');
+        const base = {
+            ...current,
+            handoffId: randomUUID(),
+            transitionId: randomUUID(),
+            owner: { pid: process.pid, startTime, leaseNonce: randomUUID() }
+        };
+        return writeRemovalJournalAt(target, base, current.phase, current.revision);
+    }
+    finally {
+        ownedLock?.release();
+    }
+}
+export function advanceSandboxRemovalJournalPhase(journal, phase, options = {}) {
+    const target = removalJournalPathForRecord(journal);
+    const resourceLock = options.resourceLock
+        ?? acquireSandboxResourceLock(`${journal.engine}:${journal.containerId}`, { lockDomain: journal.lockDomain });
+    const ownedLock = options.resourceLock ? null : resourceLock;
+    try {
+        assertRemovalJournalLock(journal, resourceLock);
+        const current = readRemovalJournalAt(target);
+        if (!current || current.revision !== journal.revision || current.handoffId !== journal.handoffId) {
+            throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_REVISION_MISMATCH');
+        }
+        if (!assertNextRemovalPhase(current.phase, phase))
+            return current;
+        const { phase: _phase, expectedOldJournalRevision: _expected, revision: _revision, recordedAt: _recordedAt, ...base } = current;
+        return writeRemovalJournalAt(target, base, phase, current.revision);
+    }
+    finally {
+        ownedLock?.release();
+    }
+}
+export function advanceSandboxRemovalJournalToPhase(journal, phase, resourceLock) {
+    let current = journal;
+    while (phaseIndex(current.phase) < phaseIndex(phase)) {
+        const next = current.phase === 'target-committed' && phase === 'container-absent'
+            ? phase : SANDBOX_REMOVAL_JOURNAL_PHASES[phaseIndex(current.phase) + 1];
+        if (!next)
+            throw new Error('SANDBOX_CONTROL_REMOVAL_PHASE_TRANSITION_INVALID');
+        current = advanceSandboxRemovalJournalPhase(current, next, { resourceLock });
+    }
+    return current;
+}
 async function awaitWithDeadline(operation, deadlineAt, errorCode) {
     const remaining = deadlineAt - Date.now();
     if (remaining <= 0)
@@ -62,6 +500,25 @@ function markSandboxControlRootQuiescing(root) {
             throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
     }
 }
+function recordSandboxRemovalPending(root, manifest, phase, journal) {
+    const pendingPath = path.join(root, 'removal-pending.json');
+    const temporary = `${pendingPath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify({
+            version: 1,
+            phase,
+            containerId: manifest.containerIdentity.id,
+            generation: manifest.generation,
+            authorityFingerprint: manifest.authorityEvidence.authorityFingerprint,
+            recordedAt: Date.now()
+        })}\n`, { mode: 0o600, flag: 'wx' });
+        fs.renameSync(temporary, pendingPath);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+    journal.write(phase === 'container-verification' ? 'container-absent' : 'container-removal');
+}
 function readStartupOwner(filePath) {
     if (!fs.existsSync(filePath))
         return null;
@@ -446,9 +903,10 @@ function readSandboxControlManifestValue(manifestPath) {
     const expectedKeys = [
         'branch', 'channelDir', 'container', 'containerIdentity', 'engine', 'generation',
         'mode', 'processingDir', 'project', 'publicStatusDir', 'repoRoot', 'runtimeDir',
-        'taskId', 'token', 'worktreeRoot'
+        'taskId', 'token', 'worktreeRoot', 'authorityEvidence', 'controlRootId',
     ];
-    if (Object.keys(manifest).sort().join(',') !== expectedKeys.sort().join(',')) {
+    const actualKeys = Object.keys(manifest).sort().join(',');
+    if (actualKeys !== expectedKeys.sort().join(',')) {
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     }
     if (typeof candidate.containerIdentity !== 'object' || candidate.containerIdentity === null
@@ -470,8 +928,10 @@ function readSandboxControlManifestValue(manifestPath) {
         || typeof candidate.processingDir !== 'string' || typeof candidate.runtimeDir !== 'string'
         || typeof candidate.token !== 'string'
         || typeof candidate.generation !== 'string'
+        || typeof candidate.controlRootId !== 'string' || !/^[a-f0-9]{64,128}$/u.test(candidate.controlRootId)
         || (candidate.mode === 'task-bound' && (typeof candidate.taskId !== 'string' || candidate.taskId.length === 0))
-        || (candidate.mode === 'branch-only' && candidate.taskId !== null))
+        || (candidate.mode === 'branch-only' && candidate.taskId !== null)
+        || !isSandboxAuthorityEvidence(candidate.authorityEvidence))
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     const root = path.dirname(path.resolve(manifestPath));
     if (path.resolve(candidate.channelDir) !== path.join(root, 'channel')
@@ -492,15 +952,17 @@ function readSandboxControlManifestValue(manifestPath) {
             id: containerIdentity.id,
             labels: { ...containerIdentity.labels }
         },
+        authorityEvidence: candidate.authorityEvidence,
         branch: candidate.branch,
         mode: candidate.mode,
         taskId: candidate.taskId,
         token: candidate.token,
         generation: candidate.generation,
+        controlRootId: candidate.controlRootId,
         channelDir: candidate.channelDir,
         publicStatusDir: candidate.publicStatusDir,
         processingDir: candidate.processingDir,
-        runtimeDir: candidate.runtimeDir
+        runtimeDir: candidate.runtimeDir,
     };
     return normalized;
 }
@@ -754,6 +1216,16 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
     return 'stopped';
 }
 export async function removeSandboxControlRoot(root, options) {
+    try {
+        await removeSandboxControlRootAttempt(root, options);
+    }
+    catch (error) {
+        if (!(error instanceof Error) || error.message !== 'SANDBOX_CONTROL_OWNER_UNAVAILABLE')
+            throw error;
+        await removeSandboxControlRootAttempt(root, options);
+    }
+}
+async function removeSandboxControlRootAttempt(root, options) {
     const resolvedRoot = path.resolve(root);
     if (!fs.existsSync(resolvedRoot))
         return;
@@ -761,142 +1233,198 @@ 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 manifestRawBeforeLock = fs.readFileSync(manifestPath, 'utf8');
     const manifest = readSandboxControlManifest(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());
-    const observation = await awaitWithDeadline(() => inspectContainer(remaining()), deadlineAt, 'SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
-    if (observation.state === 'unknown')
-        throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${observation.reason}`);
-    if (options.requireAbsent && observation.state !== 'absent') {
-        throw new Error('SANDBOX_CONTROL_CONTAINER_REAPPEARED');
-    }
-    markSandboxControlRootQuiescing(resolvedRoot);
-    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);
-    const status = readStatusOwner(statusPath);
-    if (broker && (broker.token !== manifest.token || broker.generation !== manifest.generation)) {
-        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
-    }
-    if (status && status.generation !== manifest.generation) {
-        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
-    }
-    if (broker && status && !sameOwner(broker, 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, 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)) {
-        throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
-    }
-    let executions = readExecutions(manifest);
-    if (owner && !selfOwned)
-        signalOwner(owner, platform, false);
-    for (const execution of executions) {
-        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, identityProbe))
-            && !executions.some((execution) => executionAlive(execution, platform, identityProbe)))
-            break;
-        await new Promise((resolve) => setTimeout(resolve, 25));
-    }
-    if (observation.state === 'found') {
-        if (Date.now() >= deadlineAt)
-            throw new Error('SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
-        await awaitWithDeadline(() => options.removeContainer(remaining()), deadlineAt, 'SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
-        const afterRemoval = await awaitWithDeadline(() => inspectContainer(remaining()), deadlineAt, 'SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
-        if (afterRemoval.state !== 'absent') {
-            throw new Error(afterRemoval.state === 'unknown'
-                ? `SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${afterRemoval.reason}`
-                : 'SANDBOX_CONTROL_CONTAINER_STILL_EXISTS');
+    const resourceLock = options.resourceLock ?? acquireSandboxResourceLock(`${manifest.engine}:${manifest.containerIdentity.id}`, { lockDomain: manifest.authorityEvidence.lockDomain });
+    try {
+        if (fs.readFileSync(manifestPath, 'utf8') !== manifestRawBeforeLock) {
+            throw new Error('SANDBOX_CONTROL_MANIFEST_CHANGED');
         }
-    }
-    const currentManifest = readSandboxControlManifest(manifestPath);
-    if (currentManifest.token !== manifest.token || currentManifest.generation !== manifest.generation
-        || !isSandboxControlRootQuiescing(resolvedRoot)) {
-        throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
-    }
-    const currentBroker = readBrokerOwner(brokerPath);
-    if (selfOwned && (!currentBroker || !selfOwner || !sameOwner(selfOwner, currentBroker)
-        || currentBroker.token !== manifest.token || currentBroker.generation !== manifest.generation)) {
-        throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
-    }
-    if (owner && currentBroker && !sameOwner(owner, currentBroker)) {
-        throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
-    }
-    if (!owner && currentBroker && ownerLive(currentBroker, identityProbe)) {
-        throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
-    }
-    if (owner && ownerLive(owner, identityProbe) && !currentBroker) {
-        throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
-    }
-    executions = mergeExecutions(executions, readExecutions(manifest));
-    if (Date.now() >= deadlineAt)
-        throw new Error('SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
-    for (const execution of executions) {
-        if (!terminateSandboxControlExecution(execution, {
-            platform, timeoutMs: remaining(), deadlineAt, forceAt: Date.now(), identityProbe
-        })) {
-            throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
+        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());
+        const journal = startRemovalJournal(manifest, {
+            target: options.removalTarget,
+            identityProbe
+        });
+        if (journal.record.phase === 'carrier-finalizing') {
+            if (fs.readFileSync(manifestPath, 'utf8') !== manifestRawBeforeLock
+                || !isSandboxControlRootQuiescing(resolvedRoot)) {
+                throw new Error('SANDBOX_CONTROL_MANIFEST_CHANGED');
+            }
+            fs.rmSync(resolvedRoot, { recursive: true, force: true });
+            if (fs.existsSync(resolvedRoot))
+                throw new Error('SANDBOX_CONTROL_TARGET_MISMATCH');
+            journal.write('carrier-removed');
+            if (!options.retainRemovalJournal)
+                clearSandboxRemovalJournal(manifest);
+            return;
         }
-    }
-    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, identityProbe)) {
-            throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
+        if (sandboxRemovalPhaseIndex(journal.record.phase) >= sandboxRemovalPhaseIndex('carrier-removed')) {
+            throw new Error('SANDBOX_CONTROL_TARGET_MISMATCH');
         }
-    }
-    const finalExecutions = mergeExecutions(executions, readExecutions(manifest));
-    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;
-    if (finalBrokerRaw !== null) {
-        const finalBroker = readBrokerOwner(brokerPath);
-        if (!finalBroker)
+        if (journal.record.phase === 'prepared')
+            journal.write('target-committed');
+        const observation = await awaitWithDeadline(() => inspectContainer(remaining()), deadlineAt, 'SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
+        if (observation.state === 'unknown')
+            throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${observation.reason}`);
+        journal.write(observation.state === 'absent' ? 'container-absent' : 'container-removal');
+        if (options.requireAbsent && observation.state !== 'absent') {
+            throw new Error('SANDBOX_CONTROL_CONTAINER_REAPPEARED');
+        }
+        markSandboxControlRootQuiescing(resolvedRoot);
+        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);
+        const status = readStatusOwner(statusPath);
+        if (broker && (broker.token !== manifest.token || broker.generation !== manifest.generation)) {
             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, identityProbe) && !finalSelfOwner) {
-            throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
         }
-        if (fs.readFileSync(brokerPath, 'utf8') !== finalBrokerRaw) {
-            throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+        if (status && status.generation !== manifest.generation) {
+            throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
         }
-        fs.unlinkSync(brokerPath);
-    }
-    const finalStatusRaw = fs.existsSync(statusPath) ? fs.readFileSync(statusPath, 'utf8') : null;
-    if (finalStatusRaw !== null) {
-        const finalStatus = readStatusOwner(statusPath);
-        if (!finalStatus)
+        if (broker && status && !sameOwner(broker, status.broker)
+            && (ownerLive(broker, identityProbe) || ownerLive(status.broker, identityProbe))) {
             throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
-        if (ownerLive(finalStatus.broker, identityProbe)
-            && !(selfOwner && sameOwner(finalStatus.broker, selfOwner))) {
-            throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
         }
-        if (fs.readFileSync(statusPath, 'utf8') !== finalStatusRaw) {
+        const platform = options.platform ?? process.platform;
+        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)) {
             throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
         }
-        fs.unlinkSync(statusPath);
+        let executions = readExecutions(manifest);
+        if (owner && !selfOwned)
+            signalOwner(owner, platform, false);
+        for (const execution of executions) {
+            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, identityProbe))
+                && !executions.some((execution) => executionAlive(execution, platform, identityProbe)))
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        if (observation.state === 'found') {
+            if (Date.now() >= deadlineAt) {
+                recordSandboxRemovalPending(resolvedRoot, manifest, 'container-removal', journal);
+                throw new Error('SANDBOX_CONTROL_REMOVE_PENDING');
+            }
+            let afterRemoval;
+            try {
+                await awaitWithDeadline(() => options.removeContainer(remaining()), deadlineAt, 'SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
+                afterRemoval = await awaitWithDeadline(() => inspectContainer(remaining()), deadlineAt, 'SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
+            }
+            catch (error) {
+                if (error instanceof Error && error.message === 'SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED') {
+                    recordSandboxRemovalPending(resolvedRoot, manifest, 'container-removal', journal);
+                    throw new Error('SANDBOX_CONTROL_REMOVE_PENDING');
+                }
+                throw error;
+            }
+            if (afterRemoval.state !== 'absent') {
+                throw new Error(afterRemoval.state === 'unknown'
+                    ? `SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${afterRemoval.reason}`
+                    : 'SANDBOX_CONTROL_CONTAINER_STILL_EXISTS');
+            }
+            journal.write('container-absent');
+        }
+        const currentManifestRaw = fs.readFileSync(manifestPath, 'utf8');
+        const currentManifest = readSandboxControlManifest(manifestPath);
+        if (currentManifestRaw !== manifestRawBeforeLock
+            || currentManifest.engine !== manifest.engine
+            || currentManifest.containerIdentity.id !== manifest.containerIdentity.id
+            || currentManifest.authorityEvidence.lockDomain !== manifest.authorityEvidence.lockDomain
+            || currentManifest.token !== manifest.token || currentManifest.generation !== manifest.generation
+            || !isSandboxControlRootQuiescing(resolvedRoot)) {
+            throw new Error('SANDBOX_CONTROL_MANIFEST_CHANGED');
+        }
+        const currentBroker = readBrokerOwner(brokerPath);
+        if (selfOwned && (!currentBroker || !selfOwner || !sameOwner(selfOwner, currentBroker)
+            || currentBroker.token !== manifest.token || currentBroker.generation !== manifest.generation)) {
+            throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
+        }
+        if (owner && currentBroker && !sameOwner(owner, currentBroker)) {
+            throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
+        }
+        if (!owner && currentBroker && ownerLive(currentBroker, identityProbe)) {
+            throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
+        }
+        if (owner && ownerLive(owner, identityProbe) && !currentBroker) {
+            throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
+        }
+        executions = mergeExecutions(executions, readExecutions(manifest));
+        if (Date.now() >= deadlineAt)
+            throw new Error('SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
+        for (const execution of executions) {
+            if (!terminateSandboxControlExecution(execution, {
+                platform, timeoutMs: remaining(), deadlineAt, forceAt: Date.now(), identityProbe
+            })) {
+                throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
+            }
+        }
+        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, identityProbe)) {
+                throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
+            }
+        }
+        const finalExecutions = mergeExecutions(executions, readExecutions(manifest));
+        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;
+        if (finalBrokerRaw !== null) {
+            const finalBroker = readBrokerOwner(brokerPath);
+            if (!finalBroker)
+                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, identityProbe) && !finalSelfOwner) {
+                throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
+            }
+            if (fs.readFileSync(brokerPath, 'utf8') !== finalBrokerRaw) {
+                throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+            }
+            fs.unlinkSync(brokerPath);
+        }
+        const finalStatusRaw = fs.existsSync(statusPath) ? fs.readFileSync(statusPath, 'utf8') : null;
+        if (finalStatusRaw !== null) {
+            const finalStatus = readStatusOwner(statusPath);
+            if (!finalStatus)
+                throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+            if (ownerLive(finalStatus.broker, identityProbe)
+                && !(selfOwner && sameOwner(finalStatus.broker, selfOwner))) {
+                throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
+            }
+            if (fs.readFileSync(statusPath, 'utf8') !== finalStatusRaw) {
+                throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+            }
+            fs.unlinkSync(statusPath);
+        }
+        if (fs.existsSync(brokerPath) || fs.existsSync(statusPath)) {
+            throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_REMAINS');
+        }
+        journal.write('carrier-finalizing');
+        fs.rmSync(resolvedRoot, { recursive: true, force: true });
+        journal.write('carrier-removed');
+        if (!options.retainRemovalJournal)
+            clearSandboxRemovalJournal(manifest);
     }
-    if (fs.existsSync(brokerPath) || fs.existsSync(statusPath)) {
-        throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_REMAINS');
+    finally {
+        if (!options.resourceLock)
+            resourceLock.release();
     }
-    fs.rmSync(resolvedRoot, { recursive: true, force: true });
 }
 export async function garbageCollectSandboxControlRoot(root, options = {}) {
     await removeSandboxControlRoot(path.resolve(root), {