@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/sandbox/control/lifecycle.ts

@@ -1,7 +1,8 @@
 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.ts';
 import {
   getProcessIdentityState,
@@ -16,6 +17,12 @@ import type {
 } from './protocol.ts';
 import { DEFAULT_SANDBOX_CONTROL_TIMING } from './protocol.ts';
 import { inspectSandboxControlContainer, type ContainerObservation } from './container-identity.ts';
+import {
+  acquireSandboxResourceLock,
+  resolveSandboxLockNamespace,
+  type SandboxResourceLock
+} from './native-file-lock.ts';
+import { isSandboxAuthorityEvidence } from '../engines/authority.ts';
 import {
   parseSandboxControlStatus,
   readExecution,
@@ -30,6 +37,556 @@ 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'
+] as const;
+export type SandboxRemovalJournalPhase = typeof SANDBOX_REMOVAL_JOURNAL_PHASES[number];
+export type SandboxRemovalTargetCommit = Readonly<{
+  branch: string;
+  project: string;
+  controlRoot: string;
+  targetDigest: string;
+  permitDigest: string;
+  removeWorktree: boolean;
+  removeBranch: boolean;
+  removeShare: boolean;
+  worktreePaths: readonly string[];
+  workspaceViewPaths: readonly string[];
+  toolPaths: readonly string[];
+  shellPaths: readonly string[];
+  sharePath: string;
+  permits: readonly Readonly<{
+    path: string;
+    mode: 'clean' | 'discard';
+    snapshot: Readonly<{
+      worktree: string;
+      branch: string;
+      head: string;
+      changes: readonly Readonly<{
+        indexStatus: string;
+        worktreeStatus: string;
+        path: string;
+        originalPath?: string;
+      }>[];
+      identity: string;
+      source?: 'registered' | 'recovered';
+      recovery?: Readonly<{
+        repoRoot: string;
+        worktreeBase: string;
+        branch: string;
+        identitySource: 'branch-only' | 'task-bound';
+        taskId: string | null;
+      }>;
+    }>;
+  }>[];
+}>;
+
+export type SandboxRemovalJournal = Readonly<{
+  version: 2;
+  operation: 'sandbox-rm';
+  oldOperation: 'sandbox-rm';
+  newOperation: 'sandbox-rm';
+  handoffId: string;
+  transitionId: string;
+  engine: string;
+  containerId: string;
+  generation: string;
+  authorityFingerprint: string;
+  carrierIdentityDigest: string;
+  lockDomain: string;
+  owner: ProcessIdentity & Readonly<{ leaseNonce: string }>;
+  phase: SandboxRemovalJournalPhase;
+  expectedOldJournalRevision: number | null;
+  revision: number;
+  target: SandboxRemovalTargetCommit;
+  recordedAt: number;
+}>;
+
+function removalCarrierDigest(engine: string, containerId: string, generation: string): string {
+  return createHash('sha256').update(`${engine}\0${containerId}\0${generation}`).digest('hex');
+}
+
+function assertPrivateDirectory(directory: string): void {
+  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: string, create = true): string {
+  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: SandboxControlManifest): string {
+  return path.join(
+    removalJournalDomain(manifest.authorityEvidence.lockDomain),
+    `${removalCarrierDigest(manifest.engine, manifest.containerIdentity.id, manifest.generation)}.json`
+  );
+}
+
+function removalJournalPathForRecord(record: SandboxRemovalJournal): string {
+  return path.join(
+    removalJournalDomain(record.lockDomain, false),
+    `${record.carrierIdentityDigest}.json`
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function hasExactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+  const actual = Object.keys(value).sort();
+  return actual.length === keys.length && actual.every((key, index) => key === keys[index]);
+}
+
+function isRemovalPermitCommit(value: unknown): boolean {
+  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: string): SandboxRemovalJournal {
+  let value: unknown;
+  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 as number) <= 0
+    || !Number.isSafeInteger(value.owner.startTime) || typeof value.owner.leaseNonce !== 'string'
+    || value.owner.leaseNonce.length === 0
+    || !SANDBOX_REMOVAL_JOURNAL_PHASES.includes(value.phase as SandboxRemovalJournalPhase)
+    || !(value.expectedOldJournalRevision === null
+      || (Number.isSafeInteger(value.expectedOldJournalRevision) && (value.expectedOldJournalRevision as number) >= 0))
+    || !Number.isSafeInteger(value.revision) || (value.revision as number) <= 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 as number | null;
+  const revision = value.revision as number;
+  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 as string,
+    transitionId: value.transitionId as string,
+    engine: value.engine as string,
+    containerId: value.containerId as string,
+    generation: value.generation as string,
+    authorityFingerprint: value.authorityFingerprint as string,
+    carrierIdentityDigest: value.carrierIdentityDigest as string,
+    lockDomain: value.lockDomain as string,
+    owner: {
+      pid: value.owner.pid as number,
+      startTime: value.owner.startTime as number,
+      leaseNonce: value.owner.leaseNonce as string
+    },
+    phase: value.phase as SandboxRemovalJournalPhase,
+    expectedOldJournalRevision: expected,
+    revision,
+    target: {
+      branch: value.target.branch as string,
+      project: value.target.project as string,
+      controlRoot: value.target.controlRoot as string,
+      targetDigest: value.target.targetDigest as string,
+      permitDigest: value.target.permitDigest as string,
+      removeWorktree: value.target.removeWorktree as boolean,
+      removeBranch: value.target.removeBranch as boolean,
+      removeShare: value.target.removeShare as boolean,
+      worktreePaths: value.target.worktreePaths as string[],
+      workspaceViewPaths: value.target.workspaceViewPaths as string[],
+      toolPaths: value.target.toolPaths as string[],
+      shellPaths: value.target.shellPaths as string[],
+      sharePath: value.target.sharePath as string,
+      permits: value.target.permits as SandboxRemovalTargetCommit['permits']
+    },
+    recordedAt: value.recordedAt as number
+  };
+}
+
+function readRemovalJournalAt(target: string): SandboxRemovalJournal | null {
+  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: SandboxControlManifest): SandboxRemovalJournal | null {
+  return readRemovalJournalAt(removalJournalPath(manifest));
+}
+
+export function listSandboxRemovalJournals(
+  filter: Readonly<{ branch?: string; project?: string; targetDigest?: string }> = {}
+): SandboxRemovalJournal[] {
+  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: SandboxRemovalJournal[] = [];
+  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: SandboxRemovalJournal): void {
+  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: SandboxControlManifest): void {
+  const target = removalJournalPath(manifest);
+  if (fs.existsSync(target)) fs.rmSync(target, { force: true });
+}
+
+type RemovalJournalCursor = Readonly<{
+  record: SandboxRemovalJournal;
+  write(phase: SandboxRemovalJournalPhase): SandboxRemovalJournal;
+}>;
+
+function defaultRemovalTarget(manifest: Pick<SandboxControlManifest, 'project' | 'branch' | 'container' | 'channelDir'>): SandboxRemovalTargetCommit {
+  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: SandboxRemovalJournal): boolean {
+  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 as keyof SandboxRemovalTargetCommit]) === JSON.stringify(value));
+}
+
+function sameRemovalTarget(left: SandboxRemovalTargetCommit, right: SandboxRemovalTargetCommit): boolean {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function phaseIndex(phase: SandboxRemovalJournalPhase): number {
+  return SANDBOX_REMOVAL_JOURNAL_PHASES.indexOf(phase);
+}
+
+export function sandboxRemovalPhaseIndex(phase: SandboxRemovalJournalPhase): number {
+  return phaseIndex(phase);
+}
+
+function assertNextRemovalPhase(current: SandboxRemovalJournalPhase, next: SandboxRemovalJournalPhase): boolean {
+  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: SandboxRemovalJournal,
+  resourceLock: SandboxResourceLock
+): void {
+  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: string,
+  base: Omit<SandboxRemovalJournal, 'phase' | 'expectedOldJournalRevision' | 'revision' | 'recordedAt'>,
+  phase: SandboxRemovalJournalPhase,
+  expectedOldJournalRevision: number | null
+): SandboxRemovalJournal {
+  const existing = readRemovalJournalAt(target);
+  if (expectedOldJournalRevision === null
+    ? existing !== null
+    : existing?.revision !== expectedOldJournalRevision) {
+    throw new Error('SANDBOX_CONTROL_REMOVAL_JOURNAL_REVISION_MISMATCH');
+  }
+  const record: SandboxRemovalJournal = {
+    ...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: SandboxControlManifest,
+  base: Omit<SandboxRemovalJournal, 'phase' | 'expectedOldJournalRevision' | 'revision' | 'recordedAt'>,
+  phase: SandboxRemovalJournalPhase,
+  expectedOldJournalRevision: number | null
+): SandboxRemovalJournal {
+  return writeRemovalJournalAt(removalJournalPath(manifest), base, phase, expectedOldJournalRevision);
+}
+
+function startRemovalJournal(
+  manifest: SandboxControlManifest,
+  options: Readonly<{
+    target?: SandboxRemovalTargetCommit;
+    identityProbe: ProcessIdentityProbe;
+  }>
+): RemovalJournalCursor {
+  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 as const,
+    operation: 'sandbox-rm' as const,
+    oldOperation: 'sandbox-rm' as const,
+    newOperation: 'sandbox-rm' as const,
+    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: SandboxRemovalJournal,
+  options: Readonly<{ identityProbe?: ProcessIdentityProbe; resourceLock?: SandboxResourceLock }> = {}
+): SandboxRemovalJournal {
+  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: SandboxRemovalJournal,
+  phase: SandboxRemovalJournalPhase,
+  options: Readonly<{ resourceLock?: SandboxResourceLock }> = {}
+): SandboxRemovalJournal {
+  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: SandboxRemovalJournal,
+  phase: SandboxRemovalJournalPhase,
+  resourceLock: SandboxResourceLock
+): SandboxRemovalJournal {
+  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<T>(
   operation: () => Promise<T>,
@@ -82,6 +639,30 @@ function markSandboxControlRootQuiescing(root: string): void {
   }
 }
 
+function recordSandboxRemovalPending(
+  root: string,
+  manifest: SandboxControlManifest,
+  phase: 'container-removal' | 'container-verification',
+  journal: RemovalJournalCursor
+): void {
+  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: string): { raw: string; owner: OwnerIdentity } | null {
   if (!fs.existsSync(filePath)) return null;
   if (!regularFile(filePath)) throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
@@ -498,9 +1079,10 @@ function readSandboxControlManifestValue(manifestPath: string): SandboxControlMa
   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
@@ -521,8 +1103,10 @@ function readSandboxControlManifestValue(manifestPath: string): SandboxControlMa
     || 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)) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+    || (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')
     || path.resolve(candidate.publicStatusDir) !== path.join(root, 'public')
@@ -542,15 +1126,17 @@ function readSandboxControlManifestValue(manifestPath: string): SandboxControlMa
       id: containerIdentity.id as string,
       labels: { ...(containerIdentity.labels as Record<string, string>) }
     },
+    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;
 }
@@ -816,18 +1402,42 @@ export type RemoveSandboxControlOptions = Readonly<{
   removeContainer: (timeoutMs: number) => Promise<void>;
   requireAbsent?: boolean;
   selfOwner?: BrokerOwner;
+  resourceLock?: SandboxResourceLock;
+  retainRemovalJournal?: boolean;
+  removalTarget?: SandboxRemovalTargetCommit;
 }>;
 
 export async function removeSandboxControlRoot(
   root: string,
   options: RemoveSandboxControlOptions
+): Promise<void> {
+  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: string,
+  options: RemoveSandboxControlOptions
 ): Promise<void> {
   const resolvedRoot = path.resolve(root);
   if (!fs.existsSync(resolvedRoot)) return;
   const stat = fs.lstatSync(resolvedRoot);
   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 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 inspectContainer = options.inspectContainer
     ?? ((timeoutMs) => inspectSandboxControlContainer(manifest, { timeoutMs }));
   const timeoutMs = options.timeoutMs ?? options.timing?.quiesceDeadlineMs ?? DEFAULT_QUIESCE_TIMEOUT_MS;
@@ -835,10 +1445,30 @@ export async function removeSandboxControlRoot(
   const deadlineAt = Date.now() + timeoutMs;
   const forceAt = forceDeadline(deadlineAt, timeoutMs);
   const remaining = (): number => 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 (sandboxRemovalPhaseIndex(journal.record.phase) >= sandboxRemovalPhaseIndex('carrier-removed')) {
+    throw new Error('SANDBOX_CONTROL_TARGET_MISMATCH');
+  }
+  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');
   }
@@ -880,28 +1510,46 @@ export async function removeSandboxControlRoot(
   }
 
   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 (Date.now() >= deadlineAt) {
+      recordSandboxRemovalPending(resolvedRoot, manifest, 'container-removal', journal);
+      throw new Error('SANDBOX_CONTROL_REMOVE_PENDING');
+    }
+    let afterRemoval: ContainerObservation;
+    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 (currentManifest.token !== manifest.token || currentManifest.generation !== manifest.generation
+  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_OWNER_TRANSITION');
+    throw new Error('SANDBOX_CONTROL_MANIFEST_CHANGED');
   }
   const currentBroker = readBrokerOwner(brokerPath);
   if (selfOwned && (!currentBroker || !selfOwner || !sameOwner(selfOwner, currentBroker)
@@ -970,7 +1618,13 @@ export async function removeSandboxControlRoot(
   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);
+  } finally {
+    if (!options.resourceLock) resourceLock.release();
+  }
 }
 
 export type GarbageCollectSandboxControlOptions = Omit<RemoveSandboxControlOptions, 'removeContainer' | 'requireAbsent'>;