@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/sandbox/engines/authority.ts

@@ -0,0 +1,365 @@
+import { createHash } from 'node:crypto';
+import type { SpawnSyncReturns } from 'node:child_process';
+import { runProbe } from '../shell.ts';
+import { getAdapter } from './index.ts';
+
+export type SandboxAuthorityEvidenceV1 = Readonly<{
+  version: 1;
+  provider: string;
+  lockDomain: string;
+  routeKind: 'default' | 'context' | 'endpoint' | 'wsl2';
+  routeSelector: Readonly<Record<string, string>>;
+  normalizedEndpoint: string;
+  endpointFingerprint: string;
+  daemonIdentity: Readonly<{
+    kind: 'docker-server-id';
+    fingerprint: string;
+  }>;
+  apiVersion: Readonly<{ major: number; minor: number }>;
+  authorityFingerprint: string;
+}>;
+
+export type AuthorityProbe = (cmd: string, args: string[], options?: { timeout?: number }) => SpawnSyncReturns<string | Buffer>;
+
+export type AuthorityCaptureOptions = Readonly<{
+  probe?: AuthorityProbe;
+  timeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
+  lockDomain?: string;
+  route?: SandboxAuthorityEvidenceV1;
+}>;
+
+export type AuthorityVerification = Readonly<{
+  state: 'verified' | 'unknown' | 'conflict';
+  reason?: string;
+}>;
+
+function digest(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (!value || typeof value !== 'object') return JSON.stringify(value) ?? 'null';
+  return `{${Object.entries(value as Record<string, unknown>)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`)
+    .join(',')}}`;
+}
+
+function text(value: string | Buffer | null | undefined): string {
+  return typeof value === 'string' ? value : value?.toString('utf8') ?? '';
+}
+
+function safeEndpoint(value: string): string {
+  if (!value) return 'docker-default';
+  try {
+    const parsed = new URL(value);
+    const hasUnreplayableParts = Boolean(parsed.username || parsed.password || parsed.search || parsed.hash);
+    parsed.username = '';
+    parsed.password = '';
+    parsed.search = '';
+    parsed.hash = '';
+    const normalized = parsed.toString().replace(/\/$/u, '');
+    return hasUnreplayableParts
+      ? `${normalized}#<redacted>`
+      : normalized;
+  } catch {
+    const normalized = value
+      .replace(/\/\/[^/@]+@/u, '//<redacted>@')
+      .replace(/[?&](?:token|password|secret|key)=[^&]*/giu, '');
+    return /[@?#]/u.test(value) ? `${normalized.replace(/[?#].*$/u, '')}#<redacted>` : normalized;
+  }
+}
+
+function lockDomainFor(engine: string, endpoint: string): string {
+  return digest(`${process.platform}\0${process.arch}\0${engine}\0${endpoint}`);
+}
+
+type SandboxAuthorityRoute = Readonly<{
+  kind: SandboxAuthorityEvidenceV1['routeKind'];
+  selector: Readonly<Record<string, string>>;
+  endpoint: string;
+  command: (args: string[]) => { cmd: string; args: string[] };
+}>;
+
+function contextRoute(context: string): SandboxAuthorityRoute {
+  return {
+    kind: 'context',
+    selector: { context },
+    endpoint: `docker-context://${context}`,
+    command: (args) => ({ cmd: 'docker', args: ['--context', context, ...args] })
+  };
+}
+
+function endpointRoute(endpoint: string, rawEndpoint: string, unreplayable?: string): SandboxAuthorityRoute {
+  return {
+    kind: 'endpoint',
+    selector: {
+      source: 'DOCKER_HOST',
+      endpoint,
+      ...(unreplayable ? { unreplayable } : {})
+    },
+    endpoint,
+    command: (args) => ({ cmd: 'docker', args: ['--host', rawEndpoint, ...args] })
+  };
+}
+
+function tlsEnvironmentReason(env: NodeJS.ProcessEnv): string | undefined {
+  return env.DOCKER_TLS_VERIFY || env.DOCKER_CERT_PATH || env.DOCKER_TLS
+    ? 'tls-environment'
+    : undefined;
+}
+
+function routeFor(engine: string, env: NodeJS.ProcessEnv): SandboxAuthorityRoute {
+  const context = getAdapter(engine).dockerContext;
+  if (context) {
+    return contextRoute(context);
+  }
+  if (env.DOCKER_CONTEXT) {
+    return contextRoute(env.DOCKER_CONTEXT);
+  }
+  if (env.DOCKER_HOST) {
+    return endpointRoute(safeEndpoint(env.DOCKER_HOST), env.DOCKER_HOST, tlsEnvironmentReason(env));
+  }
+  return contextRoute('default');
+}
+
+function validRouteName(value: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9_.@/-]*$/u.test(value);
+}
+
+function resolveWslDistro(probe: AuthorityProbe, timeoutMs?: number, explicit?: string): string {
+  if (explicit) {
+    if (!validRouteName(explicit)) throw new Error('SANDBOX_AUTHORITY_ROUTE_CAPTURE_FAILED');
+    return explicit;
+  }
+  const result = probe(
+    'wsl.exe',
+    ['--list', '--verbose'],
+    timeoutMs === undefined ? {} : { timeout: timeoutMs }
+  );
+  if (result.status !== 0) throw new Error('SANDBOX_AUTHORITY_ROUTE_CAPTURE_FAILED');
+  const output = text(result.stdout).replace(/\0/gu, '').replace(/\r/gu, '');
+  const defaultLine = output.split('\n').find((line) => /^\s*\*\s+/u.test(line));
+  const distro = defaultLine?.replace(/^\s*\*\s+/u, '').replace(/\s+(?:Running|Stopped)\s+\d+\s*$/iu, '').trim();
+  if (!distro || !validRouteName(distro)) throw new Error('SANDBOX_AUTHORITY_ROUTE_CAPTURE_FAILED');
+  return distro;
+}
+
+function wslRoute(
+  distro: string,
+  context: string | undefined,
+  env: NodeJS.ProcessEnv
+): SandboxAuthorityRoute {
+  const endpoint = env.DOCKER_HOST
+    ? safeEndpoint(env.DOCKER_HOST)
+    : `wsl://${distro}/${context ?? 'default'}`;
+  const unreplayable = tlsEnvironmentReason(env)
+    ?? (endpoint.includes('<redacted>') ? 'ambient-endpoint-secret' : undefined);
+  return {
+    kind: 'wsl2',
+    selector: {
+      distro,
+      ...(context ? { context } : {}),
+      ...(unreplayable ? { unreplayable } : {}),
+      ...(env.DOCKER_HOST ? { endpoint } : {})
+    },
+    endpoint,
+    command: (args) => ({
+      cmd: 'wsl.exe',
+      args: [
+        '--distribution', distro,
+        '--exec', 'docker',
+        ...(context ? ['--context', context] : []),
+        ...(env.DOCKER_HOST ? ['--host', env.DOCKER_HOST] : []),
+        ...args
+      ]
+    })
+  };
+}
+
+function currentWslRoute(
+  env: NodeJS.ProcessEnv,
+  probe: AuthorityProbe,
+  timeoutMs?: number
+): SandboxAuthorityRoute {
+  const distro = resolveWslDistro(probe, timeoutMs, env.WSL_DISTRO_NAME);
+  let context = env.DOCKER_CONTEXT;
+  if (!context && !env.DOCKER_HOST) {
+    const result = probe(
+      'wsl.exe',
+      ['--distribution', distro, '--exec', 'docker', 'context', 'show'],
+      timeoutMs === undefined ? {} : { timeout: timeoutMs }
+    );
+    context = text(result.stdout).trim();
+    if (result.status !== 0 || !validRouteName(context)) {
+      throw new Error('SANDBOX_AUTHORITY_ROUTE_CAPTURE_FAILED');
+    }
+  }
+  return wslRoute(distro, context, env);
+}
+
+function routeFromEvidence(evidence: SandboxAuthorityEvidenceV1): SandboxAuthorityRoute {
+  return {
+    kind: evidence.routeKind,
+    selector: evidence.routeSelector,
+    endpoint: evidence.normalizedEndpoint,
+    command: (args) => commandForSandboxAuthority(evidence, 'docker', args)
+  };
+}
+
+function currentContextRoute(
+  engine: string,
+  env: NodeJS.ProcessEnv,
+  probe: AuthorityProbe,
+  timeoutMs?: number
+): SandboxAuthorityRoute {
+  const configured = routeFor(engine, env);
+  if (configured.kind !== 'context' || configured.selector.context !== 'default') return configured;
+  if (env.DOCKER_CONTEXT || env.DOCKER_HOST || getAdapter(engine).dockerContext) return configured;
+  const result = probe('docker', ['context', 'show'], timeoutMs === undefined ? {} : { timeout: timeoutMs });
+  const context = text(result.stdout).trim();
+  if (result.status !== 0 || !/^[A-Za-z0-9][A-Za-z0-9_.@/-]*$/u.test(context)) {
+    throw new Error('SANDBOX_AUTHORITY_ROUTE_CAPTURE_FAILED');
+  }
+  return contextRoute(context);
+}
+
+/** Build a command using only the route persisted with the sandbox authority. */
+export function commandForSandboxAuthority(
+  evidence: SandboxAuthorityEvidenceV1,
+  cmd: string,
+  args: string[] = []
+): { cmd: string; args: string[] } {
+  if (cmd !== 'docker') {
+    throw new Error('SANDBOX_AUTHORITY_ROUTE_UNSUPPORTED');
+  }
+  if (evidence.routeKind === 'context') {
+    const context = evidence.routeSelector.context;
+    if (!context) throw new Error('SANDBOX_AUTHORITY_ROUTE_INVALID');
+    return { cmd, args: ['--context', context, ...args] };
+  }
+  if (evidence.routeKind === 'endpoint') {
+    const endpoint = evidence.routeSelector.endpoint;
+    if (!endpoint || endpoint.includes('<redacted>') || evidence.routeSelector.unreplayable) {
+      throw new Error('SANDBOX_AUTHORITY_ROUTE_UNREPLAYABLE');
+    }
+    return { cmd, args: ['--host', endpoint, ...args] };
+  }
+  if (evidence.routeKind === 'wsl2') {
+    const distro = evidence.routeSelector.distro;
+    const context = evidence.routeSelector.context;
+    const endpoint = evidence.routeSelector.endpoint;
+    if (!distro || evidence.routeSelector.unreplayable || endpoint?.includes('<redacted>')) {
+      throw new Error('SANDBOX_AUTHORITY_ROUTE_UNREPLAYABLE');
+    }
+    return {
+      cmd: 'wsl.exe',
+      args: [
+        '--distribution', distro,
+        '--exec', cmd,
+        ...(context ? ['--context', context] : []),
+        ...(endpoint && !endpoint.startsWith('wsl://') ? ['--host', endpoint] : []),
+        ...args
+      ]
+    };
+  }
+  return { cmd, args: ['--context', 'default', ...args] };
+}
+
+export function authorityVersionArgs(): string[] {
+  return ['version', '--format', '{{json .Server}}'];
+}
+
+export function captureSandboxAuthority(
+  engine: string,
+  options: AuthorityCaptureOptions = {}
+): SandboxAuthorityEvidenceV1 {
+  const env = options.env ?? process.env;
+  const probe = options.probe ?? runProbe;
+  const route = options.route
+    ? routeFromEvidence(options.route)
+    : engine === 'wsl2'
+      ? currentWslRoute(env, probe, options.timeoutMs)
+      : currentContextRoute(engine, env, probe, options.timeoutMs);
+  function probeJson(args: string[]): unknown {
+    const command = options.route
+      ? commandForSandboxAuthority(options.route, 'docker', args)
+      : route.command(args);
+    try {
+      const response = probe(
+        command.cmd,
+        command.args,
+        options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs }
+      );
+      if (response.status !== 0) throw new Error('SANDBOX_AUTHORITY_CAPTURE_FAILED');
+      return JSON.parse(text(response.stdout).trim());
+    } catch {
+      throw new Error('SANDBOX_AUTHORITY_CAPTURE_FAILED');
+    }
+  }
+  const server = probeJson(authorityVersionArgs());
+  if (!server || typeof server !== 'object' || Array.isArray(server)) {
+    throw new Error('SANDBOX_AUTHORITY_CAPTURE_FAILED');
+  }
+  const record = server as Record<string, unknown>;
+  const api = typeof record.ApiVersion === 'string' ? /^(\d+)\.(\d+)$/u.exec(record.ApiVersion) : null;
+  if (!api) throw new Error('SANDBOX_AUTHORITY_CAPTURE_FAILED');
+  // Docker version exposes API metadata; the daemon ID belongs to Docker info.
+  const serverId = probeJson(['info', '--format', '{{json .ID}}']);
+  if (typeof serverId !== 'string' || !serverId.trim()) throw new Error('SANDBOX_AUTHORITY_CAPTURE_FAILED');
+  const normalizedEndpoint = route.endpoint;
+  const evidenceWithoutFingerprint = {
+    version: 1 as const,
+    provider: engine,
+    lockDomain: options.lockDomain ?? options.route?.lockDomain ?? lockDomainFor(engine, normalizedEndpoint),
+    routeKind: route.kind,
+    routeSelector: route.selector,
+    normalizedEndpoint,
+    endpointFingerprint: digest(normalizedEndpoint),
+    daemonIdentity: { kind: 'docker-server-id' as const, fingerprint: digest(serverId) },
+    apiVersion: { major: Number(api[1]), minor: Number(api[2]) }
+  };
+  return {
+    ...evidenceWithoutFingerprint,
+    authorityFingerprint: digest(canonical(evidenceWithoutFingerprint))
+  };
+}
+
+export function verifySandboxAuthority(
+  expected: SandboxAuthorityEvidenceV1 | null | undefined,
+  actual: SandboxAuthorityEvidenceV1 | null
+): AuthorityVerification {
+  if (!expected) return { state: 'unknown', reason: 'SANDBOX_AUTHORITY_EVIDENCE_MISSING' };
+  if (!actual) return { state: 'unknown', reason: 'SANDBOX_AUTHORITY_UNAVAILABLE' };
+  if (expected.authorityFingerprint !== actual.authorityFingerprint
+    || expected.lockDomain !== actual.lockDomain
+    || expected.routeKind !== actual.routeKind
+    || expected.endpointFingerprint !== actual.endpointFingerprint
+    || expected.daemonIdentity.fingerprint !== actual.daemonIdentity.fingerprint) {
+    return { state: 'conflict', reason: 'SANDBOX_AUTHORITY_DRIFT' };
+  }
+  return { state: 'verified' };
+}
+
+export function isSandboxAuthorityEvidence(value: unknown): value is SandboxAuthorityEvidenceV1 {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const evidence = value as Record<string, unknown>;
+  const selector = evidence.routeSelector as Record<string, unknown> | null;
+  const daemon = evidence.daemonIdentity as Record<string, unknown> | null;
+  const api = evidence.apiVersion as Record<string, unknown> | null;
+  return evidence.version === 1
+    && typeof evidence.provider === 'string'
+    && /^[a-f0-9]{64}$/u.test(evidence.lockDomain as string)
+    && ['default', 'context', 'endpoint', 'wsl2'].includes(evidence.routeKind as string)
+    && !!selector && typeof selector === 'object' && !Array.isArray(selector)
+    && Object.values(selector).every((entry) => typeof entry === 'string')
+    && typeof evidence.normalizedEndpoint === 'string'
+    && /^[a-f0-9]{64}$/u.test(evidence.endpointFingerprint as string)
+    && !!daemon && daemon.kind === 'docker-server-id'
+    && /^[a-f0-9]{64}$/u.test(daemon.fingerprint as string)
+    && !!api && Number.isSafeInteger(api.major) && (api.major as number) >= 0
+    && Number.isSafeInteger(api.minor) && (api.minor as number) >= 0
+    && /^[a-f0-9]{64}$/u.test(evidence.authorityFingerprint as string);
+}

package/lib/sandbox/engines/docker-exact-discovery.ts

@@ -0,0 +1,132 @@
+import type { SpawnSyncReturns } from 'node:child_process';
+import { commandForEngine, runProbe } from '../shell.ts';
+import { commandForSandboxAuthority, type SandboxAuthorityEvidenceV1 } from './authority.ts';
+
+type ProbeResult = SpawnSyncReturns<string | Buffer>;
+type Probe = (cmd: string, args: string[], options?: { timeout?: number }) => ProbeResult;
+
+export type ExactContainerDiscovery =
+  | Readonly<{ state: 'absent'; id: string; evidence: 'exact-empty' }>
+  | Readonly<{
+    state: 'found';
+    id: string;
+    running: boolean;
+    labels: Readonly<Record<string, string>>;
+    evidence: 'exact-present';
+  }>
+  | Readonly<{ state: 'conflict'; reason: string }>
+  | Readonly<{ state: 'unknown'; reason: string }>;
+
+export type ExactContainerDiscoveryOptions = Readonly<{
+  probe?: Probe;
+  timeoutMs?: number;
+  authority?: SandboxAuthorityEvidenceV1;
+}>;
+
+const FULL_CONTAINER_ID = /^[a-f0-9]{64}$/u;
+
+function outputText(value: string | Buffer | null | undefined): string {
+  return typeof value === 'string' ? value : value?.toString('utf8') ?? '';
+}
+
+function unknown(reason: string): ExactContainerDiscovery {
+  return { state: 'unknown', reason };
+}
+
+export function buildExactContainerListArgs(id: string): string[] {
+  if (!FULL_CONTAINER_ID.test(id)) throw new Error('SANDBOX_CONTAINER_ID_NOT_FULL');
+  return ['container', 'ls', '--all', '--no-trunc', '--filter', `id=${id}`, '--format', '{{.ID}}'];
+}
+
+function buildExactContainerInspectArgs(id: string): string[] {
+  return ['container', 'inspect', '--format', '{{json .}}', id];
+}
+
+function runDockerProbe(
+  engine: string,
+  args: string[],
+  options: ExactContainerDiscoveryOptions
+): ProbeResult {
+  const command = options.authority
+    ? commandForSandboxAuthority(options.authority, 'docker', args)
+    : commandForEngine(engine, 'docker', args);
+  return (options.probe ?? runProbe)(
+    command.cmd,
+    command.args,
+    options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs }
+  );
+}
+
+function parseExactList(stdout: string, expectedId: string): 'empty' | 'present' | 'conflict' | string {
+  const rows = stdout.split(/\r?\n/u).map((row) => row.trim()).filter(Boolean);
+  if (rows.length === 0) return 'empty';
+  if (rows.length !== 1) return 'exact container query returned multiple rows';
+  if (!FULL_CONTAINER_ID.test(rows[0]!)) return 'exact container query returned a malformed ID';
+  if (rows[0] !== expectedId) return 'conflict';
+  return 'present';
+}
+
+function parseExactInspect(stdout: string, expectedId: string): ExactContainerDiscovery {
+  let value: unknown;
+  try {
+    value = JSON.parse(stdout);
+  } catch {
+    return unknown('exact container inspection returned malformed JSON');
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return unknown('exact container inspection returned an incomplete object');
+  }
+  const inspected = value as {
+    Id?: unknown;
+    State?: { Running?: unknown };
+    Config?: { Labels?: unknown };
+  };
+  if (inspected.Id !== expectedId || typeof inspected.State?.Running !== 'boolean'
+    || !inspected.Config?.Labels || typeof inspected.Config.Labels !== 'object'
+    || Array.isArray(inspected.Config.Labels)) {
+    return unknown('exact container inspection identity is incomplete');
+  }
+  const rawLabels = inspected.Config.Labels as Record<string, unknown>;
+  if (Object.values(rawLabels).some((value) => typeof value !== 'string')) {
+    return unknown('exact container inspection labels are malformed');
+  }
+  return {
+    state: 'found',
+    id: expectedId,
+    running: inspected.State.Running,
+    labels: { ...rawLabels as Record<string, string> },
+    evidence: 'exact-present'
+  };
+}
+
+export function discoverExactContainer(
+  engine: string,
+  id: string,
+  options: ExactContainerDiscoveryOptions = {}
+): ExactContainerDiscovery {
+  if (!FULL_CONTAINER_ID.test(id)) return unknown('container identity is not a full 64-character ID');
+  let listed: ProbeResult;
+  try {
+    listed = runDockerProbe(engine, buildExactContainerListArgs(id), options);
+  } catch {
+    return unknown('exact container query failed before producing a result');
+  }
+  if (listed.status !== 0) {
+    return unknown(`exact container query exited with ${listed.status ?? 'unknown status'}`);
+  }
+  const listState = parseExactList(outputText(listed.stdout), id);
+  if (listState === 'empty') return { state: 'absent', id, evidence: 'exact-empty' };
+  if (listState === 'conflict') return { state: 'conflict', reason: 'exact container query returned a different ID' };
+  if (listState !== 'present') return unknown(listState);
+
+  let inspected: ProbeResult;
+  try {
+    inspected = runDockerProbe(engine, buildExactContainerInspectArgs(id), options);
+  } catch {
+    return unknown('exact container inspection failed before producing a result');
+  }
+  if (inspected.status !== 0) {
+    return unknown(`exact container inspection exited with ${inspected.status ?? 'unknown status'}`);
+  }
+  return parseExactInspect(outputText(inspected.stdout).trim(), id);
+}

package/lib/sandbox/index.ts

@@ -1,3 +1,5 @@
+import { PUBLIC_CLI_ROUTE_SELECTORS } from '../internal/cli-route-inventory.ts';
+
 const USAGE = `Usage: ai sandbox <command> [options]
 
 Commands:
@@ -18,14 +20,15 @@ Commands:
   rm <branch | TASK-id> | --unbound | --purge
                                Remove one sandbox; use a full TASK-id for task-bound
                                cleanup and a branch for branch-only cleanup. --unbound
-                               removes completed task-bound and branch-only sandboxes;
-                               active, blocked, and archive tasks are protected.
+                               removes completed task-bound and branch-only sandboxes
+                               plus verified auxiliary state; active, blocked, and archive tasks are protected.
   start [--recreate] <branch | TASK-id | N>
                                Verify or recover an existing sandbox container;
                                optionally replace only the container on failure
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
 
 Run 'ai sandbox <command> --help' for details.`;
+const SANDBOX_OPERATIONS = PUBLIC_CLI_ROUTE_SELECTORS.sandbox;
 
 export async function runSandbox(args: string[]): Promise<void> {
   const [subcommand, ...rest] = args;
@@ -41,6 +44,10 @@ export async function runSandbox(args: string[]): Promise<void> {
     return;
   }
 
+  if (!SANDBOX_OPERATIONS.includes(subcommand as typeof SANDBOX_OPERATIONS[number])) {
+    throw new Error(`Unknown sandbox command: ${subcommand}`);
+  }
+
   switch (subcommand) {
     case 'create': {
       const { create } = await import('./commands/create.ts');

package/lib/sandbox/recovery.ts

@@ -1,3 +1,4 @@
+import { prepareCompletedReentry, publishCompletedReentry, waitForCompletedReentry } from './control/completed-reentry.ts';
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
@@ -59,9 +60,10 @@ import {
   type BrokerOwner
 } from './control/lifecycle.ts';
 import {
-  appendSandboxControlAudit,
   readSandboxControlStatus
 } from './control/state.ts';
+import { validateSandboxControlIdentity } from './control/identity-sentinel.ts';
+import { appendDiagnosticAudit as appendControlDiagnosticAudit } from './control/audit.ts';
 import { inspectSandboxControlContainer } from './control/container-identity.ts';
 import {
   SANDBOX_CONTROL_FUTURE_SKEW_MS,
@@ -223,6 +225,17 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
   const internalCli = path.resolve(directory, '..', '..', 'bin', `internal-cli${extension}`);
   const manifest = readSandboxControlManifest(manifestPath);
   const root = path.dirname(manifestPath);
+  const identity = validateSandboxControlIdentity({
+    publicStatusDir: manifest.publicStatusDir,
+    root,
+    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()}`);
+  }
   if (isSandboxControlRootQuiescing(root)) throw new Error('SANDBOX_CONTROL_QUIESCING');
   const brokerPath = path.join(root, 'broker.json');
   let brokerSnapshot: string | null = null;
@@ -295,8 +308,8 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
       }
     }
     if (replacedBrokerRecord) {
-      appendSandboxControlAudit(manifest, 'broker-observed-crash');
-      appendSandboxControlAudit(manifest, 'broker-restart');
+      appendControlDiagnosticAudit(manifest, 'broker-observed-crash');
+      appendControlDiagnosticAudit(manifest, 'broker-restart');
     }
     child = spawn(
       process.execPath,
@@ -337,6 +350,17 @@ async function ensureSandboxControlBroker(params: {
   });
   if (!fs.existsSync(control.manifestPath)) return;
   const validatedManifest = readSandboxControlManifest(control.manifestPath);
+  const identity = validateSandboxControlIdentity({
+    publicStatusDir: validatedManifest.publicStatusDir,
+    root: control.root,
+    mode: validatedManifest.mode,
+    taskId: validatedManifest.taskId,
+    generation: validatedManifest.generation,
+    controlRootId: validatedManifest.controlRootId
+  });
+  if (identity.state !== 'valid') {
+    throw new Error(`SANDBOX_CONTROL_IDENTITY_${identity.state.replaceAll('-', '_').toUpperCase()}`);
+  }
   const containerObservation = await inspectSandboxControlContainer(validatedManifest);
   if (containerObservation.state === 'unknown') {
     throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${containerObservation.reason}`);
@@ -653,7 +677,7 @@ function recoveryTaskSources(repoRoot: string, taskId: string): {
   return { mountPaths, accessiblePaths: [completedSource] };
 }
 
-function startCompletedSandboxContainer(params: {
+export function startCompletedSandboxContainer(params: {
   config: SandboxConfig;
   engine: string;
   container: string;
@@ -748,7 +772,7 @@ function expectedMounts(params: {
       ? {}
       : {
         runtimeDir: control.runtimeDir,
-        taskSources: taskSources.mountPaths,
+        taskSources: taskSources!.accessiblePaths,
         taskId: taskId!
       })
   }).map((mount) => ({
@@ -757,7 +781,7 @@ function expectedMounts(params: {
     hostPaths: mount.hostPaths,
     ...(taskSources !== null && taskId !== null
       && mount.containerPath === `/workspace/.agents/workspace/active/${taskId}`
-      ? { sourceAccessiblePaths: taskSources.accessiblePaths }
+      ? { sourceAccessiblePaths: taskSources!.accessiblePaths }
       : {}),
     expectedRW: !mount.readOnly
   }));
@@ -1250,7 +1274,17 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
       throw new Error('Explicit container recreation requested.');
     }
     if (!params.row.running) {
+      let completedReentry: { manifest: SandboxControlManifest; evidence: Awaited<ReturnType<typeof prepareCompletedReentry>> } | null = null;
       if (params.reentry === 'completed' && params.workspace?.mode === 'task-bound') {
+        const control = sandboxControlPaths({
+          base: params.config.controlBase, project: params.config.project,
+          container: params.row.name, identity: params.workspace
+        });
+        const manifest = readSandboxControlManifest(control.manifestPath);
+        if (manifest.taskId !== params.workspace.taskId || manifest.branch !== params.branch) {
+          throw new Error('SANDBOX_COMPLETED_REENTRY_EVIDENCE_INVALID');
+        }
+        completedReentry = { manifest, evidence: await prepareCompletedReentry(manifest) };
         startCompletedSandboxContainer({
           config: params.config,
           engine: params.engine,
@@ -1315,6 +1349,15 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
       if (final.findings.length > 0) {
         throw new Error(describeFindings(final.findings));
       }
+      if (completedReentry) {
+        const { manifest, evidence } = completedReentry;
+        const current = await prepareCompletedReentry(manifest);
+        if (JSON.stringify(current) !== JSON.stringify(evidence)) {
+          throw new Error('SANDBOX_COMPLETED_REENTRY_EVIDENCE_INVALID');
+        }
+        publishCompletedReentry(manifest, evidence);
+        await waitForCompletedReentry(manifest, evidence);
+      }
       return { container: params.row.name, path: 'recovered', warnings };
     }