@fitlab-ai/agent-infra 0.9.14 → 0.9.15

package/lib/sandbox/control/executor.ts

@@ -1,7 +1,7 @@
 import { spawn, type ChildProcess } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { createHash, randomUUID } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 import { getProcessStartTime } from '../../server/process-state.ts';
 import {
   createTask,
@@ -11,20 +11,32 @@ import {
   type TaskCreateResult
 } from '../../task/create-service.ts';
 import { applyTaskFinalization } from '../../task/finalization.ts';
-import { bindSandboxControlTask, validateSandboxControlRequest, type SandboxControlExecution, type SandboxControlManifest, type SandboxControlRequest } from './protocol.ts';
 import {
-  appendSandboxControlAudit,
+  bindSandboxControlTask,
+  validateSandboxControlRequest,
+  type SandboxControlExecution,
+  type SandboxControlExecutorGateV2,
+  type SandboxControlManifest,
+  type SandboxControlRequest
+} from './protocol.ts';
+import {
   atomicWriteJson,
   executionPath,
   readActiveLease,
   terminateSandboxControlExecution
 } from './state.ts';
+import { requestAuditFields, resultAuditFields, appendDiagnosticAudit, createSandboxControlAuditContext, appendCriticalAudit, writeSandboxControlTransition } from './audit.ts';
+import { validateSandboxControlIdentity } from './identity-sentinel.ts';
 import {
   createSandboxExecutorExecutionContext,
   dispatchTaskControlOperation,
   parseTaskControlOperation,
+  validateLifecycleRecoveryAttestation,
+  type LifecycleAuthorityResponseV1,
+  type LifecycleRecoveryAttestationV1,
   type TaskControlOperation
 } from '../../task/control-authority.ts';
+import { executeTaskWorkflow } from './workflow-executor.ts';
 import { assertSandboxControlBrokerOwner, readSandboxControlManifest, type BrokerOwner } from './lifecycle.ts';
 import { computeLifecycleBuildIdentity } from '../../agent-clients/adapters/codex-lifecycle/build-identity.ts';
 import {
@@ -86,52 +98,12 @@ function appendExecutorAudit(
   fields: Record<string, string | number | boolean | null> = {}
 ): void {
   try {
-    appendSandboxControlAudit(manifest, event, { source: 'executor', ...fields });
+    appendDiagnosticAudit(manifest, event, { source: 'executor', ...fields });
   } catch {
     // Diagnostics must never change the control protocol.
   }
 }
 
-function requestAuditFields(
-  manifest: SandboxControlManifest,
-  manifestPath: string,
-  request: SandboxControlRequest
-): Record<string, string | number | boolean | null> {
-  const args = 'args' in request ? request.args : [];
-  const encodedArgs = JSON.stringify(args);
-  return {
-    requestId: request.id,
-    requestFamily: request.family,
-    sandboxTaskId: manifest.taskId,
-    requestGeneration: request.generation,
-    requestIssuedAt: request.issuedAt,
-    requestExpiresAt: request.expiresAt,
-    requestArgCount: args.length,
-    requestArgsSha256: createHash('sha256').update(encodedArgs, 'utf8').digest('hex'),
-    requestTaskRef: args[0] ?? null,
-    requestCommand: args[1] ?? null,
-    controllerProofPresent: request.controllerProof !== null,
-    hostCwd: process.cwd(),
-    manifestPath,
-    manifestPathRealpath: safeRealpath(manifestPath),
-    repoRoot: manifest.repoRoot,
-    repoRootRealpath: safeRealpath(manifest.repoRoot),
-    worktreeRoot: manifest.worktreeRoot,
-    worktreeRootRealpath: safeRealpath(manifest.worktreeRoot),
-    runtimeDir: manifest.runtimeDir,
-    runtimeDirRealpath: safeRealpath(manifest.runtimeDir)
-  };
-}
-
-function resultAuditFields(result: SandboxControlExecutionResult): Record<string, string | number | boolean | null> {
-  return {
-    exitCode: result.exitCode,
-    stdoutBytes: Buffer.byteLength(result.stdout, 'utf8'),
-    stderrBytes: Buffer.byteLength(result.stderr, 'utf8'),
-    stdoutSha256: createHash('sha256').update(result.stdout, 'utf8').digest('hex'),
-    stderrSha256: createHash('sha256').update(result.stderr, 'utf8').digest('hex')
-  };
-}
 
 export function nodeEntryArgs(entry: string, args: string[]): string[] {
   return path.extname(entry) === '.ts'
@@ -155,6 +127,7 @@ export async function prepareSandboxControlExecution(params: {
   request: SandboxControlRequest;
   requestPath: string;
   internalCliPath: string;
+  lifecycleAuthority?: LifecycleAuthorityResponseV1;
 }): Promise<PreparedSandboxControlExecution> {
   const nonce = randomUUID();
   const child = spawn(
@@ -208,7 +181,16 @@ export async function prepareSandboxControlExecution(params: {
       if (!canWrite()) throw new Error('SANDBOX_CONTROL_OWNER_LOST');
       atomicWriteJson(executionPath(params.manifest, params.request.id), { ...execution, phase: 'running', updatedAt: Date.now() });
       if (!canWrite()) throw new Error('SANDBOX_CONTROL_OWNER_LOST');
-      child.send({ version: 1, nonce, owner: gateOwner });
+      const authority = params.lifecycleAuthority?.attestation ?? null;
+      child.send({
+        version: 2,
+        nonce,
+        owner: gateOwner,
+        requestId: params.request.id,
+        operationId: authority?.operationId ?? params.request.id,
+        phase: authority?.phase ?? (params.request.family === 'task-workflow' ? 'artifact.finalize-local' : 'orchestration.prepare'),
+        authority
+      } satisfies SandboxControlExecutorGateV2);
     },
     completion,
     terminate(updateState = true) {
@@ -222,7 +204,7 @@ export async function prepareSandboxControlExecution(params: {
   };
 }
 
-function waitForGate(nonce: string, timeoutMs = 2_000): Promise<BrokerOwner> {
+function waitForGate(nonce: string, timeoutMs = 2_000): Promise<Readonly<{ owner: BrokerOwner; authority: LifecycleRecoveryAttestationV1 | null; requestId: string; operationId: string; phase: SandboxControlExecutorGateV2['phase'] }>> {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => reject(new Error('SANDBOX_CONTROL_EXECUTOR_GATE_TIMEOUT')), timeoutMs);
     const onDisconnect = () => {
@@ -237,9 +219,14 @@ function waitForGate(nonce: string, timeoutMs = 2_000): Promise<BrokerOwner> {
         version?: unknown;
         nonce?: unknown;
         owner?: Partial<BrokerOwner> | null;
+        requestId?: unknown;
+        operationId?: unknown;
+        phase?: unknown;
+        authority?: unknown;
       } | null;
       const owner = value?.owner;
-      if (!value || value.version !== 1 || value.nonce !== nonce
+      if (!value || Object.keys(value).sort().join(',') !== 'authority,nonce,operationId,owner,phase,requestId,version'
+        || value.version !== 2 || value.nonce !== nonce
         || !owner || owner.version !== 3 || !Number.isSafeInteger(owner.pid) || (owner.pid ?? 0) <= 0
         || typeof owner.startTime !== 'number' || !Number.isSafeInteger(owner.startTime)
         || typeof owner.brokerId !== 'string' || owner.brokerId.length === 0
@@ -247,7 +234,21 @@ function waitForGate(nonce: string, timeoutMs = 2_000): Promise<BrokerOwner> {
         reject(new Error('SANDBOX_CONTROL_EXECUTOR_GATE_INVALID'));
         return;
       }
-      resolve(owner as BrokerOwner);
+      if (typeof value.requestId !== 'string' || typeof value.operationId !== 'string'
+        || !['orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'].includes(value.phase as string)
+        || (value.authority !== null && value.authority !== undefined && (() => {
+          try { validateLifecycleRecoveryAttestation(value.authority); return false; } catch { return true; }
+        })())) {
+        reject(new Error('SANDBOX_CONTROL_EXECUTOR_GATE_INVALID'));
+        return;
+      }
+      resolve({
+        owner: owner as BrokerOwner,
+        authority: value.authority === null || value.authority === undefined ? null : value.authority as LifecycleRecoveryAttestationV1,
+        requestId: value.requestId,
+        operationId: value.operationId,
+        phase: value.phase as SandboxControlExecutorGateV2['phase']
+      });
     });
   });
 }
@@ -327,6 +328,7 @@ function finalizationResult(result: Awaited<ReturnType<typeof applyTaskFinalizat
 type ExecuteRequestOptions = Readonly<{
   buildIdentity?: typeof computeLifecycleBuildIdentity;
   resolveControllerBinding?: typeof resolveCodexControllerBinding;
+  lifecycleRecoveryAttestation?: LifecycleRecoveryAttestationV1 | null;
 }>;
 
 async function executeRequestInner(
@@ -394,7 +396,7 @@ async function executeRequestInner(
         : /^([A-Z][A-Z0-9_]+)/u.exec(error instanceof Error ? error.message : String(error))?.[1]
           ?? 'CODEX_SANDBOX_CONTROLLER_FAILED';
       appendExecutorAudit(manifest, 'controller-operation-failed', {
-        ...requestAuditFields(manifest, manifestPath, request),
+        ...requestAuditFields(manifest, request),
         controllerCommand: request.command,
         errorCode,
         errorType: error instanceof Error ? error.name : typeof error,
@@ -402,6 +404,7 @@ async function executeRequestInner(
       return controllerFailure(error);
     }
   }
+  if (request.family === 'task-workflow') return executeTaskWorkflow(manifest, request.workflow, options.lifecycleRecoveryAttestation ?? null);
   if (request.family === 'task-finalization') {
     const operation = parseTaskControlOperation(
       'task-finalization', [manifest.taskId!, 'complete', '--agent', request.agent]
@@ -415,7 +418,8 @@ async function executeRequestInner(
         taskId: manifest.taskId!,
         generation: manifest.generation,
         manifestPath,
-        requestId: request.id
+        requestId: request.id,
+        lifecycleRecoveryAttestation: options.lifecycleRecoveryAttestation ?? null
       }),
       operation
     );
@@ -445,23 +449,31 @@ async function executeRequestInner(
       && operation.input.client === 'codex';
     if (codexPrepare) {
       if (!request.controllerProof) {
-        return orchestrationFailure(
-          'CODEX_SANDBOX_CONTROLLER_PROOF_REQUIRED',
-          'Codex prepare requires a current controller lease proof'
-        );
-      }
-      try {
-        controllerBinding = (options.resolveControllerBinding ?? resolveCodexControllerBinding)({
-          manifest,
-          manifestPath,
-          proof: request.controllerProof,
-          buildIdentity: (options.buildIdentity ?? computeLifecycleBuildIdentity)(manifest.repoRoot)
-        });
-      } catch (error) {
-        const code = error instanceof CodexControllerRegistrationError
-          ? error.code
-          : 'CODEX_SANDBOX_CONTROLLER_PROOF_INVALID';
-        return orchestrationFailure(code, `${code}: Codex controller proof was rejected`);
+        const authority = options.lifecycleRecoveryAttestation;
+        if (!authority || authority.phase !== 'orchestration.prepare') {
+          return orchestrationFailure(
+            'CODEX_SANDBOX_CONTROLLER_PROOF_REQUIRED',
+            'Codex prepare requires a current controller lease proof'
+          );
+        }
+        controllerBinding = {
+          instanceDigest: authority.controllerInstanceDigest,
+          controlGeneration: authority.controlGeneration
+        };
+      } else {
+        try {
+          controllerBinding = (options.resolveControllerBinding ?? resolveCodexControllerBinding)({
+            manifest,
+            manifestPath,
+            proof: request.controllerProof,
+            buildIdentity: (options.buildIdentity ?? computeLifecycleBuildIdentity)(manifest.repoRoot)
+          });
+        } catch (error) {
+          const code = error instanceof CodexControllerRegistrationError
+            ? error.code
+            : 'CODEX_SANDBOX_CONTROLLER_PROOF_INVALID';
+          return orchestrationFailure(code, `${code}: Codex controller proof was rejected`);
+        }
       }
     } else if (request.controllerProof !== null) {
       return orchestrationFailure(
@@ -487,7 +499,8 @@ async function executeRequestInner(
     manifestPath,
     requestId: request.id,
     diagnosticLog,
-    ...(controllerBinding ? { controllerBinding } : {})
+    ...(controllerBinding ? { controllerBinding } : {}),
+    lifecycleRecoveryAttestation: options.lifecycleRecoveryAttestation ?? null
   });
   const format = (value: unknown): SandboxControlExecutionResult => {
     const result = value as { status?: string };
@@ -511,7 +524,7 @@ export async function executeRequest(
   request: SandboxControlRequest,
   options: ExecuteRequestOptions = {}
 ): Promise<SandboxControlExecutionResult> {
-  const fields = requestAuditFields(manifest, manifestPath, request);
+  const fields = requestAuditFields(manifest, request);
   appendExecutorAudit(manifest, 'executor-request-start', fields);
   try {
     const result = await executeRequestInner(manifest, manifestPath, request, options);
@@ -534,11 +547,23 @@ export async function executeRequest(
 }
 
 export async function runSandboxControlExecutor(requestPath: string, nonce: string): Promise<void> {
-  const gateOwner = await waitForGate(nonce);
+  const gate = await waitForGate(nonce);
+  const gateOwner = gate.owner;
   process.disconnect?.();
   const manifestPath = process.env.AGENT_INFRA_EXECUTOR_MANIFEST;
   if (!manifestPath) throw new Error('SANDBOX_CONTROL_EXECUTOR_MANIFEST_MISSING');
   const manifest = readSandboxControlManifest(manifestPath);
+  const identity = validateSandboxControlIdentity({
+    publicStatusDir: manifest.publicStatusDir,
+    root: path.dirname(path.resolve(manifestPath)),
+    mode: manifest.mode,
+    taskId: manifest.taskId,
+    generation: manifest.generation,
+    controlRootId: manifest.controlRootId
+  });
+  if (identity.state !== 'valid') {
+    throw new Error(`SANDBOX_CONTROL_IDENTITY_${identity.state.replaceAll('-', '_').toUpperCase()}`);
+  }
   const root = fs.realpathSync.native(process.cwd());
   const expectedRoot = safeRealpath(manifest.repoRoot);
   if (expectedRoot !== root) {
@@ -551,13 +576,20 @@ export async function runSandboxControlExecutor(requestPath: string, nonce: stri
   }
   const raw = JSON.parse(fs.readFileSync(requestPath, 'utf8')) as unknown;
   const request = validateSandboxControlRequest(raw, manifest);
-  appendExecutorAudit(manifest, 'executor-request-validated', requestAuditFields(manifest, manifestPath, request));
+  if (gate.requestId !== request.id) throw new Error('SANDBOX_CONTROL_EXECUTOR_GATE_REQUEST_MISMATCH');
+  if (gate.authority !== null
+    && (gate.authority.requestId !== request.id
+      || gate.authority.operationId !== gate.operationId
+      || gate.authority.phase !== gate.phase)) {
+    throw new Error('SANDBOX_CONTROL_EXECUTOR_GATE_AUTHORITY_MISMATCH');
+  }
+  appendExecutorAudit(manifest, 'executor-request-validated', requestAuditFields(manifest, request));
   const requestDirectory = path.resolve(path.dirname(requestPath));
   const processingDirectory = path.resolve(path.join(manifest.processingDir, request.id));
   const channelRequestDirectory = path.resolve(path.join(manifest.channelDir, 'requests'));
   if (requestDirectory !== processingDirectory && requestDirectory !== channelRequestDirectory) {
     appendExecutorAudit(manifest, 'executor-request-path-validation-failed', {
-      ...requestAuditFields(manifest, manifestPath, request),
+      ...requestAuditFields(manifest, request),
       requestPath,
       requestDirectory,
       processingDirectory,
@@ -568,10 +600,32 @@ export async function runSandboxControlExecutor(requestPath: string, nonce: stri
   let result: SandboxControlExecutionResult;
   try {
     assertSandboxControlExecutorAuthority(manifest, gateOwner);
-    result = await executeRequest(manifest, manifestPath, request);
+    const operation = request.family === 'task-lifecycle' || request.family === 'task-orchestration'
+      ? (() => {
+        try { return parseTaskControlOperation(request.family, request.args); } catch { return null; }
+      })()
+      : null;
+    const context = createSandboxControlAuditContext(manifest, {
+      requestId: request.id,
+      family: request.family,
+      operation: operation?.family === 'task-orchestration'
+        ? operation.intent
+        : operation?.family === 'task-lifecycle'
+          ? operation.request.intent
+          : request.family === 'task-finalization' ? request.operation : null,
+      phase: 'started-committed',
+      outcome: 'in-progress'
+    });
+    appendCriticalAudit(manifest, context, { transition: 'started-committed' });
+    writeSandboxControlTransition(manifest, { requestId: request.id, phase: 'started-committed' });
+    const execution = readJsonExecution(executionPath(manifest, request.id));
+    atomicWriteJson(executionPath(manifest, request.id), { ...execution, phase: 'running', updatedAt: Date.now() });
+    result = await executeRequest(manifest, manifestPath, request, {
+      lifecycleRecoveryAttestation: gate.authority
+    });
   } catch (error) {
     appendExecutorAudit(manifest, 'executor-authority-or-dispatch-failed', {
-      ...requestAuditFields(manifest, manifestPath, request),
+      ...requestAuditFields(manifest, request),
       errorType: error instanceof Error ? error.name : typeof error,
     });
     const detail = error instanceof Error ? error.message : String(error);
@@ -596,6 +650,12 @@ export async function runSandboxControlExecutor(requestPath: string, nonce: stri
   process.exitCode = result.exitCode;
 }
 
+function readJsonExecution(filePath: string): SandboxControlExecution {
+  const value = JSON.parse(fs.readFileSync(filePath, 'utf8')) as SandboxControlExecution;
+  if (!value || value.requestId.length === 0) throw new Error('SANDBOX_CONTROL_EXECUTION_INVALID');
+  return value;
+}
+
 export function disconnectExecutor(child: ChildProcess): void {
   if (child.connected) child.disconnect();
 }

package/lib/sandbox/control/finalization-response.ts

@@ -0,0 +1,29 @@
+import type { TaskFinalizationReceipt } from '../../task/finalization.ts';
+import type { SandboxControlResponse } from './protocol.ts';
+
+export function finalizationTerminalResponse(taskId: string, requestId: string, receipt: TaskFinalizationReceipt): SandboxControlResponse {
+  const pendingSteps = [
+    receipt.taskComment === 'pending' ? 'task-comment' : null,
+    receipt.verification === 'pending' ? 'verification' : null
+  ].filter((step): step is string => step !== null);
+  const completedSteps = ['lifecycle', receipt.taskComment === 'pending' ? null : 'task-comment', receipt.verification === 'pending' ? null : 'verification']
+    .filter((step): step is string => step !== null);
+  const warnings = receipt.warnings
+    .filter((warning) => warning.status === 'open')
+    .map(({ status: _status, resolvedAt: _resolvedAt, ...warning }) => warning);
+  const result = {
+    status: 'completed', changed: false, taskId,
+    lifecycle: { status: 'no-op', changed: false, error: null },
+    taskComment: receipt.taskComment === 'pending' ? null : { status: 'no-op', changed: false, error: null },
+    verification: receipt.verification === 'pending' ? null : { status: 'no-op', changed: false, error: null },
+    completedSteps, pendingSteps,
+    result: pendingSteps.length > 0 || receipt.warningProjection === 'pending' || warnings.length > 0
+      ? 'completed_with_warnings' : 'completed',
+    warnings, error: null
+  };
+  return {
+    version: 2, id: requestId, phase: 'completed', exitCode: 0,
+    stdout: `${JSON.stringify({ version: 1, status: 'completed', changed: false, accepted: true, result, error: null })}\n`,
+    stderr: '', error: null
+  };
+}

package/lib/sandbox/control/identity-sentinel.ts

@@ -0,0 +1,137 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeDurableFile } from '../../fs/durable-write.ts';
+
+export const SANDBOX_CONTROL_IDENTITY_FILE = 'identity.json';
+
+export type SandboxControlIdentitySentinel = Readonly<{
+  version: 1;
+  mode: 'task-bound' | 'branch-only';
+  taskId: string | null;
+  generation: string;
+  controlRootId: string;
+}>;
+
+export type SandboxControlIdentityValidation = Readonly<{
+  state: 'valid' | 'missing' | 'malformed' | 'generation-mismatch' | 'root-id-mismatch' | 'topology-mismatch';
+  sentinel: SandboxControlIdentitySentinel | null;
+}>;
+
+function identityError(code: SandboxControlIdentityValidation['state']): Error {
+  return new Error(`SANDBOX_CONTROL_IDENTITY_${code.replaceAll('-', '_').toUpperCase()}`);
+}
+
+function canonicalIdentity(value: SandboxControlIdentitySentinel): string {
+  return JSON.stringify({
+    version: value.version,
+    mode: value.mode,
+    taskId: value.taskId,
+    generation: value.generation,
+    controlRootId: value.controlRootId
+  });
+}
+
+export function identitySentinelPath(publicStatusDir: string): string {
+  return path.join(publicStatusDir, SANDBOX_CONTROL_IDENTITY_FILE);
+}
+
+export function createSandboxControlRootId(): string {
+  return `${randomBytes(32).toString('hex')}${randomUUID().replaceAll('-', '')}`;
+}
+
+export function createSandboxControlIdentitySentinel(params: Readonly<{
+  mode: 'task-bound' | 'branch-only';
+  taskId: string | null;
+  generation: string;
+  controlRootId?: string;
+}>): SandboxControlIdentitySentinel {
+  const sentinel: SandboxControlIdentitySentinel = {
+    version: 1,
+    mode: params.mode,
+    taskId: params.mode === 'task-bound' ? params.taskId : null,
+    generation: params.generation,
+    controlRootId: params.controlRootId ?? createSandboxControlRootId()
+  };
+  parseSandboxControlIdentitySentinel(sentinel);
+  return sentinel;
+}
+
+export function identityDigest(value: SandboxControlIdentitySentinel): string {
+  const normalized = parseSandboxControlIdentitySentinel(value);
+  return createHash('sha256').update(canonicalIdentity(normalized), 'utf8').digest('hex');
+}
+
+export function parseSandboxControlIdentitySentinel(value: unknown): SandboxControlIdentitySentinel {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw identityError('malformed');
+  const candidate = value as Partial<SandboxControlIdentitySentinel>;
+  if (Object.keys(candidate).sort().join(',') !== 'controlRootId,generation,mode,taskId,version'
+    || candidate.version !== 1
+    || (candidate.mode !== 'task-bound' && candidate.mode !== 'branch-only')
+    || (candidate.taskId !== null && typeof candidate.taskId !== 'string')
+    || (candidate.mode === 'task-bound' && !candidate.taskId)
+    || (candidate.mode === 'branch-only' && candidate.taskId !== null)
+    || typeof candidate.generation !== 'string' || candidate.generation.length === 0
+    || typeof candidate.controlRootId !== 'string' || !/^[a-f0-9]{64,128}$/u.test(candidate.controlRootId)) {
+    throw identityError('malformed');
+  }
+  return candidate as SandboxControlIdentitySentinel;
+}
+
+export function writeSandboxControlIdentitySentinel(
+  publicStatusDir: string,
+  value: SandboxControlIdentitySentinel
+): SandboxControlIdentitySentinel {
+  const sentinel = parseSandboxControlIdentitySentinel(value);
+  fs.mkdirSync(publicStatusDir, { recursive: true, mode: 0o700 });
+  const target = identitySentinelPath(publicStatusDir);
+  writeDurableFile(target, `${canonicalIdentity(sentinel)}\n`, { mode: 0o400, replace: true });
+  return sentinel;
+}
+
+export function readSandboxControlIdentitySentinel(publicStatusDir: string): SandboxControlIdentitySentinel {
+  const filePath = identitySentinelPath(publicStatusDir);
+  if (!fs.existsSync(filePath)) throw identityError('missing');
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw identityError('malformed');
+    return parseSandboxControlIdentitySentinel(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith('SANDBOX_CONTROL_IDENTITY_')) throw error;
+    throw identityError('malformed');
+  }
+}
+
+export function validateSandboxControlIdentity(params: Readonly<{
+  publicStatusDir: string;
+  root: string;
+  manifestRoot?: string;
+  mode: 'task-bound' | 'branch-only';
+  taskId: string | null;
+  generation: string;
+  controlRootId: string;
+}>): SandboxControlIdentityValidation {
+  let sentinel: SandboxControlIdentitySentinel;
+  try {
+    sentinel = readSandboxControlIdentitySentinel(params.publicStatusDir);
+  } catch (error) {
+    const code = error instanceof Error ? error.message : '';
+    if (code.endsWith('MISSING')) return { state: 'missing', sentinel: null };
+    return { state: 'malformed', sentinel: null };
+  }
+  if (sentinel.generation !== params.generation) return { state: 'generation-mismatch', sentinel };
+  if (sentinel.controlRootId !== params.controlRootId) return { state: 'root-id-mismatch', sentinel };
+  if (sentinel.mode !== params.mode || sentinel.taskId !== params.taskId) return { state: 'topology-mismatch', sentinel };
+  if (params.manifestRoot && path.resolve(params.manifestRoot) !== path.resolve(params.root)) {
+    return { state: 'topology-mismatch', sentinel };
+  }
+  return { state: 'valid', sentinel };
+}
+
+export function assertSandboxControlIdentity(params: Parameters<typeof validateSandboxControlIdentity>[0]): SandboxControlIdentitySentinel {
+  const result = validateSandboxControlIdentity(params);
+  if (result.state !== 'valid' || !result.sentinel) {
+    throw new Error(`SANDBOX_CONTROL_IDENTITY_${result.state.replaceAll('-', '_').toUpperCase()}`);
+  }
+  return result.sentinel;
+}

package/lib/sandbox/control/lifecycle.ts

@@ -85,6 +85,7 @@ export type SandboxRemovalTargetCommit = Readonly<{
     }>;
   }>[];
 }>;
+
 export type SandboxRemovalJournal = Readonly<{
   version: 2;
   operation: 'sandbox-rm';
@@ -348,7 +349,7 @@ type RemovalJournalCursor = Readonly<{
   write(phase: SandboxRemovalJournalPhase): SandboxRemovalJournal;
 }>;
 
-function defaultRemovalTarget(manifest: SandboxControlManifest): SandboxRemovalTargetCommit {
+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');
@@ -370,6 +371,18 @@ function defaultRemovalTarget(manifest: SandboxControlManifest): SandboxRemovalT
   };
 }
 
+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);
 }
@@ -560,6 +573,21 @@ export function advanceSandboxRemovalJournalPhase(
   }
 }
 
+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>,
   deadlineAt: number,
@@ -1051,7 +1079,7 @@ function readSandboxControlManifestValue(manifestPath: string): SandboxControlMa
   const expectedKeys = [
     'branch', 'channelDir', 'container', 'containerIdentity', 'engine', 'generation',
     'mode', 'processingDir', 'project', 'publicStatusDir', 'repoRoot', 'runtimeDir',
-    'taskId', 'token', 'worktreeRoot', 'authorityEvidence'
+    'taskId', 'token', 'worktreeRoot', 'authorityEvidence', 'controlRootId',
   ];
   const actualKeys = Object.keys(manifest).sort().join(',');
   if (actualKeys !== expectedKeys.sort().join(',')) {
@@ -1075,6 +1103,7 @@ 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)
     || !isSandboxAuthorityEvidence(candidate.authorityEvidence)) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
@@ -1103,10 +1132,11 @@ function readSandboxControlManifestValue(manifestPath: string): SandboxControlMa
     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;
 }
@@ -1380,6 +1410,18 @@ export type RemoveSandboxControlOptions = Readonly<{
 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;