@fitlab-ai/agent-infra 0.9.12 → 0.9.14

package/lib/sandbox/commands/show.ts

@@ -16,6 +16,7 @@ import { fetchSandboxRows, selectSandboxContainer } from './list-running.ts';
 import { resolveTools, toolConfigDirCandidates } from '../tools.ts';
 import { detectEngine } from '../engine.ts';
 import { resolveSandboxTarget } from '../workspace-identity.ts';
+import { readSandboxControlStatusForRow } from './control-status.ts';
 
 const USAGE = `Usage: ai sandbox show <branch | TASK-id | N>
 
@@ -93,6 +94,21 @@ export function show(args: string[] = []): void {
   process.stdout.write(`  Mode: ${container?.workspaceMode ?? 'legacy-invalid'}\n`);
   process.stdout.write(`  Task: ${container?.taskId ?? '-'}\n`);
 
+  p.log.step('Control status');
+  const controlStatus = container
+    ? readSandboxControlStatusForRow(config, container)
+    : null;
+  if (!controlStatus) {
+    p.log.warn('  Control status unavailable');
+  } else {
+    process.stdout.write(`  Health: ${controlStatus.state}\n`);
+    process.stdout.write(`  Task view: ${controlStatus.taskView.state}\n`);
+    process.stdout.write(`  Task source: ${controlStatus.taskView.observedSource ?? '-'}\n`);
+    if (controlStatus.taskView.reasonCode) {
+      process.stdout.write(`  Task view reason: ${controlStatus.taskView.reasonCode}\n`);
+    }
+  }
+
   for (const tool of detail.toolStates) {
     p.log.step(`${tool.name} state`);
     if (tool.entries.length === 0) {

package/lib/sandbox/control/client.ts

@@ -20,19 +20,78 @@ import type {
 } from './controller-registration.ts';
 import type { ProcessIdentity } from '../../server/process-state.ts';
 import { normalizeAgentToken } from '../../agent-clients/tokens.ts';
-import { readSandboxControlStatus } from './state.ts';
+import { readSandboxControlPayload, readSandboxControlStatus } from './state.ts';
 import type { TaskCreateCandidateV1 } from '../../task/create.ts';
+import { accessSandboxTaskView, taskViewFromStatus, type TaskViewAccessEffect } from './task-view.ts';
 
 const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
 
+type SandboxControlEnvironmentClassification = Readonly<{
+  kind: 'direct' | 'controlled' | 'invalid';
+  mode?: 'task-bound' | 'branch-only';
+  code?: 'TASK_CONTROL_TRANSPORT_INVALID';
+  message?: string;
+}>;
+
+export function classifySandboxControlEnvironment(
+  env: NodeJS.ProcessEnv = process.env
+): SandboxControlEnvironmentClassification {
+  const controlKeys = [
+    'AGENT_INFRA_CONTROL_TOKEN',
+    'AGENT_INFRA_CONTROL_GENERATION',
+    'AGENT_INFRA_CONTROL_DIR',
+    'AGENT_INFRA_CONTROL_STATUS_DIR'
+  ] as const;
+  const hasControlMarker = controlKeys.some((key) => Boolean(env[key]));
+  const hasTaskIdentity = Boolean(env.AGENT_INFRA_TASK_ID);
+  const hasRuntime = Boolean(env.AGENT_INFRA_RUNTIME_DIR);
+  const hasExecutorMarker = Boolean(env.AGENT_INFRA_EXECUTOR_MANIFEST);
+  const hasControllerBinding = Boolean(env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING);
+  const hasAnyMarker = hasControlMarker || hasTaskIdentity || hasRuntime || hasExecutorMarker || hasControllerBinding;
+  const hasCompleteControl = controlKeys.every((key) => Boolean(env[key]));
+
+  if (!hasAnyMarker) return { kind: 'direct' };
+  if (hasExecutorMarker) {
+    return {
+      kind: 'invalid',
+      code: 'TASK_CONTROL_TRANSPORT_INVALID',
+      message: 'executor context is only valid for sandbox-control execute'
+    };
+  }
+  if (hasControllerBinding) {
+    return {
+      kind: 'invalid',
+      code: 'TASK_CONTROL_TRANSPORT_INVALID',
+      message: 'sandbox client control configuration is incomplete or conflicting'
+    };
+  }
+  if (!hasCompleteControl) {
+    return {
+      kind: 'invalid',
+      code: 'TASK_CONTROL_TRANSPORT_INVALID',
+      message: 'sandbox client control configuration is incomplete or conflicting'
+    };
+  }
+  if (hasTaskIdentity !== hasRuntime) {
+    return {
+      kind: 'invalid',
+      code: 'TASK_CONTROL_TRANSPORT_INVALID',
+      message: 'sandbox task identity and runtime binding must be provided together'
+    };
+  }
+  return { kind: 'controlled', mode: hasTaskIdentity ? 'task-bound' : 'branch-only' };
+}
+
 export class SandboxControlClientError extends Error {
   readonly detail: SandboxControlError;
   readonly accepted: boolean;
-  constructor(detail: SandboxControlError, accepted = false) {
+  readonly requestId: string | null;
+  constructor(detail: SandboxControlError, accepted = false, requestId: string | null = null) {
     super(detail.message);
     this.name = 'SandboxControlClientError';
     this.detail = detail;
     this.accepted = accepted;
+    this.requestId = requestId;
   }
 }
 
@@ -40,11 +99,29 @@ function sleep(milliseconds: number): void {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
 }
 
-function clientError(code: string, message: string, retryable: boolean, accepted = false): never {
-  throw new SandboxControlClientError({ code, message: `${code}: ${message}`, retryable }, accepted);
+function clientError(
+  code: string,
+  message: string,
+  retryable: boolean,
+  accepted = false,
+  requestId: string | null = null
+): never {
+  throw new SandboxControlClientError({ code, message: `${code}: ${message}`, retryable }, accepted, requestId);
+}
+
+function hasTaskBoundMarker(env: NodeJS.ProcessEnv = process.env): boolean {
+  return Boolean(env.AGENT_INFRA_TASK_ID)
+    && Boolean(env.AGENT_INFRA_CONTROL_TOKEN || env.AGENT_INFRA_CONTROL_GENERATION
+      || env.AGENT_INFRA_CONTROL_STATUS_DIR || env.AGENT_INFRA_RUNTIME_DIR || env.AGENT_INFRA_CONTROL_DIR);
 }
 
-function preflight(statusDir: string, generation: string, now = Date.now()): void {
+function preflight(
+  statusDir: string,
+  generation: string,
+  taskViewEffect: TaskViewAccessEffect | null = null,
+  now = Date.now(),
+  env: NodeJS.ProcessEnv = process.env
+): void {
   let status;
   try {
     status = readSandboxControlStatus(statusDir);
@@ -63,18 +140,60 @@ function preflight(statusDir: string, generation: string, now = Date.now()): voi
     clientError(code, 'broker is parked until the host restores a valid binding', true);
   }
   if (status.state !== 'healthy') clientError('SANDBOX_CONTROL_BROKER_UNAVAILABLE', 'broker is not ready', true);
+  if (taskViewEffect && hasTaskBoundMarker(env)) {
+    const view = taskViewFromStatus(status);
+    if (view.taskId !== env.AGENT_INFRA_TASK_ID) {
+      clientError('SANDBOX_TASK_VIEW_TASK_ID_MISMATCH', 'task view task id does not match the sandbox task marker', false);
+    }
+    const access = accessSandboxTaskView(view, taskViewEffect);
+    if (!access.allowed) {
+      clientError(
+        access.reasonCode ?? 'SANDBOX_TASK_VIEW_DENIED',
+        access.message ?? 'task view denied',
+        false
+      );
+    }
+  }
+}
+
+function taskViewEffectForRequest(request: SandboxControlRequest): TaskViewAccessEffect | null {
+  if (request.family === 'task-lifecycle' || request.family === 'task-finalization') return 'progress';
+  if (request.family === 'task-orchestration') return request.args[1] === 'status' ? 'diagnostic' : 'progress';
+  return null;
 }
 
-function parseResponse(raw: string, id: string): SandboxControlResponse {
+function parseResponse(raw: string, id: string, accepted = false): SandboxControlResponse {
   const response = JSON.parse(raw) as SandboxControlResponse;
   if (response.version !== 2 || response.id !== id
-    || !['accepted', 'completed', 'rejected'].includes(response.phase)
-    || (response.phase === 'completed' && !Number.isInteger(response.exitCode))) {
-    clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response is invalid', false);
+    || !['completed', 'rejected'].includes(response.phase)
+    || (response.phase === 'completed' && !Number.isInteger(response.exitCode))
+    || (response.outputState !== undefined && response.outputState !== 'available' && response.outputState !== 'unavailable')
+    || (response.outputState === 'available' && !response.payload)
+    || (response.outputState === 'unavailable' && response.payload !== null && response.payload !== undefined)) {
+    clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response is invalid', false, accepted, id);
   }
   return response;
 }
 
+function readPublishedResponse(raw: string, id: string, channelDir: string, accepted = false): SandboxControlResponse {
+  const response = parseResponse(raw, id, accepted);
+  if (response.outputState !== 'available') return response;
+  const filePath = path.join(channelDir, 'responses', `${id}.payload.json`);
+  let payload;
+  try {
+    payload = readSandboxControlPayload(filePath);
+  } catch {
+    clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker payload is missing or invalid', false, true, id);
+  }
+  if (!response.payload || response.payload.version !== payload.version
+    || response.payload.id !== payload.id || response.payload.generation !== payload.generation
+    || response.payload.stdoutBytes !== payload.stdoutBytes || response.payload.stderrBytes !== payload.stderrBytes
+    || response.payload.stdoutSha256 !== payload.stdoutSha256 || response.payload.stderrSha256 !== payload.stderrSha256) {
+    clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker payload reference is invalid', false, true, id);
+  }
+  return { ...response, stdout: payload.stdout, stderr: payload.stderr };
+}
+
 function cancelPendingRequest(requestPath: string): boolean {
   try {
     fs.unlinkSync(requestPath);
@@ -92,16 +211,20 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
 }>): SandboxControlResponse {
   const channelDir = params.channelDir ?? process.env.AGENT_INFRA_CONTROL_DIR ?? '/run/agent-infra/control';
   const statusDir = params.statusDir ?? process.env.AGENT_INFRA_CONTROL_STATUS_DIR ?? '/run/agent-infra/control-status';
-  preflight(statusDir, request.generation);
+  const taskViewEffect = taskViewEffectForRequest(request);
+  preflight(statusDir, request.generation, taskViewEffect);
   const encoded = `${JSON.stringify(request)}\n`;
   if (Buffer.byteLength(encoded, 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
-    clientError('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit', false);
+    clientError('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit', false, false, request.id);
   }
   const requestsDir = path.join(channelDir, 'requests');
   const responsesDir = path.join(channelDir, 'responses');
   const temporary = path.join(requestsDir, `.${request.id}.tmp`);
   const requestPath = path.join(requestsDir, `${request.id}.json`);
   const responsePath = path.join(responsesDir, `${request.id}.json`);
+  if (fs.existsSync(responsePath)) {
+    clientError('SANDBOX_CONTROL_REQUEST_REPLAYED', 'request id already has a terminal response', false, false, request.id);
+  }
   fs.writeFileSync(temporary, encoded, { mode: 0o600, flag: 'wx' });
   fs.renameSync(temporary, requestPath);
   const deadline = Date.now() + (params.timeoutMs ?? 30_000);
@@ -109,6 +232,8 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
   let malformedResponseRaw: string | null = null;
   let malformedResponseObservedAt = 0;
   while (Date.now() < deadline) {
+    const acceptedPath = path.join(responsesDir, `${request.id}.accepted.json`);
+    if (fs.existsSync(acceptedPath)) accepted = true;
     if (fs.existsSync(responsePath)) {
       let raw: string;
       try {
@@ -119,7 +244,9 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
       }
       let response: SandboxControlResponse;
       try {
-        response = parseResponse(raw, request.id);
+        // The request-specific terminal proves the broker claimed the request; preserve recovery evidence if marker cleanup won the race.
+        accepted = true;
+        response = readPublishedResponse(raw, request.id, channelDir, accepted);
         malformedResponseRaw = null;
       } catch (error) {
         if (!(error instanceof SyntaxError)) throw error;
@@ -128,7 +255,7 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
           malformedResponseRaw = raw;
           malformedResponseObservedAt = now;
         } else if (now - malformedResponseObservedAt >= SANDBOX_CONTROL_RESPONSE_SETTLE_MS) {
-          clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response remained malformed', false, accepted);
+          clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response remained malformed', false, accepted, request.id);
         }
         sleep(25);
         continue;
@@ -136,20 +263,20 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
       if (response.phase === 'accepted') {
         accepted = true;
       } else {
-        fs.rmSync(responsePath, { force: true });
         return response;
       }
     }
     if (!accepted) {
       try {
-        preflight(statusDir, request.generation);
+        preflight(statusDir, request.generation, taskViewEffect);
       } catch (error) {
         if (cancelPendingRequest(requestPath)) throw error;
         clientError(
           'SANDBOX_CONTROL_RESULT_UNKNOWN',
           'request was claimed before broker availability was lost; inspect domain state before retrying',
           false,
-          true
+          true,
+          request.id
         );
       }
     }
@@ -160,7 +287,8 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
       'SANDBOX_CONTROL_RESULT_UNKNOWN',
       'accepted request did not produce a final result; inspect domain state before retrying',
       false,
-      true
+      true,
+      request.id
     );
   }
   if (!cancelPendingRequest(requestPath)) {
@@ -168,10 +296,66 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
       'SANDBOX_CONTROL_RESULT_UNKNOWN',
       'request was claimed but no acceptance result was observed; inspect domain state before retrying',
       false,
-      true
+      true,
+      request.id
     );
   }
-  clientError('SANDBOX_CONTROL_BROKER_UNAVAILABLE', `broker did not accept the request within ${params.timeoutMs ?? 30_000}ms`, true);
+  clientError('SANDBOX_CONTROL_BROKER_UNAVAILABLE', `broker did not accept the request within ${params.timeoutMs ?? 30_000}ms`, true, false, request.id);
+}
+
+export function recoverSandboxControl(requestId: string, params: Readonly<{
+  channelDir?: string;
+  timeoutMs?: number;
+}> = {}): SandboxControlResponse {
+  if (!/^[a-f0-9-]{16,64}$/u.test(requestId)) {
+    clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'request id is invalid', false, true);
+  }
+  const channelDir = params.channelDir ?? process.env.AGENT_INFRA_CONTROL_DIR ?? '/run/agent-infra/control';
+  const responsePath = path.join(channelDir, 'responses', `${requestId}.json`);
+  const deadline = Date.now() + (params.timeoutMs ?? 30_000);
+  let accepted = false;
+  let malformedResponseRaw: string | null = null;
+  let malformedResponseObservedAt = 0;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(path.join(channelDir, 'responses', `${requestId}.accepted.json`))) accepted = true;
+    if (fs.existsSync(responsePath)) {
+      let raw: string;
+      try {
+        raw = fs.readFileSync(responsePath, 'utf8');
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw error;
+      }
+      let response: SandboxControlResponse;
+      try {
+        // The request-specific terminal proves the broker claimed the request; preserve recovery evidence if marker cleanup won the race.
+        accepted = true;
+        response = readPublishedResponse(raw, requestId, channelDir, accepted);
+        malformedResponseRaw = null;
+      } catch (error) {
+        if (!(error instanceof SyntaxError)) throw error;
+        const now = Date.now();
+        if (malformedResponseRaw !== raw) {
+          malformedResponseRaw = raw;
+          malformedResponseObservedAt = now;
+        } else if (now - malformedResponseObservedAt >= SANDBOX_CONTROL_RESPONSE_SETTLE_MS) {
+          clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response remained malformed', false, accepted, requestId);
+        }
+        sleep(25);
+        continue;
+      }
+      if (response.phase === 'accepted') accepted = true;
+      else return response;
+    }
+    sleep(25);
+  }
+  clientError(
+    'SANDBOX_CONTROL_RESULT_UNKNOWN',
+    'request did not produce a final result; inspect domain state before retrying',
+    false,
+    accepted,
+    requestId
+  );
 }
 
 function authority(params: { token?: string; generation?: string }): { token: string; generation: string } {

package/lib/sandbox/control/completed-reentry.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveTaskWorkspace } from '../task-resolver.ts';
+import { assertGitWorktreeBinding } from '../../git/worktree-identity.ts';
+import { parseTypedTaskFrontmatter } from '../../task/frontmatter.ts';
+import { readTaskFinalizationReceipt } from '../../task/finalization.ts';
+import { inspectSandboxControlContainer } from './container-identity.ts';
+import type { SandboxControlManifest } from './protocol.ts';
+import { atomicWriteJson, readSandboxControlStatus } from './state.ts';
+import { taskViewForManifest, type SandboxTaskView } from './task-view.ts';
+
+type ReentryEvidence = Readonly<{
+  taskId: string;
+  generation: string;
+  containerId: string;
+  branch: string;
+  worktreeRoot: string;
+  source: string;
+  sourceDevice: string;
+  sourceInode: string;
+  receipt: NonNullable<SandboxTaskView['receipt']>;
+}>;
+
+function evidencePath(manifest: SandboxControlManifest): string {
+  return path.join(path.dirname(manifest.processingDir), 'completed-reentry.json');
+}
+
+function invalid(): Error {
+  return new Error('SANDBOX_COMPLETED_REENTRY_EVIDENCE_INVALID');
+}
+
+export async function prepareCompletedReentry(
+  manifest: SandboxControlManifest,
+  inspect: typeof inspectSandboxControlContainer = inspectSandboxControlContainer
+): Promise<ReentryEvidence> {
+  if (manifest.mode !== 'task-bound' || !manifest.taskId) throw invalid();
+  assertGitWorktreeBinding(manifest.repoRoot, manifest.worktreeRoot, manifest.branch);
+  const container = await inspect(manifest);
+  if (container.state !== 'found' || container.id !== manifest.containerIdentity.id) throw invalid();
+  const task = resolveTaskWorkspace(manifest.taskId, manifest.repoRoot);
+  const metadata = parseTypedTaskFrontmatter(fs.readFileSync(task.taskMd, 'utf8'));
+  if (task.state !== 'completed' || task.branch !== manifest.branch
+    || metadata.id !== manifest.taskId || metadata.status !== 'completed') throw invalid();
+  const receipt = readTaskFinalizationReceipt(manifest.repoRoot, manifest.taskId);
+  if (!receipt || receipt.taskId !== manifest.taskId) throw invalid();
+  const view = taskViewForManifest({ ...manifest, receipt });
+  if (view.state !== 'current' || view.observedSource !== 'completed' || !view.receipt) throw invalid();
+  const status = readSandboxControlStatus(manifest.publicStatusDir);
+  const previous = status.taskView;
+  if (status.generation !== manifest.generation || status.activeRequestId !== null
+    || previous.taskId !== manifest.taskId || !previous.receipt
+    || previous.receipt.receiptId !== view.receipt.receiptId
+    || previous.receipt.generation !== view.receipt.generation
+    || previous.receipt.requestId !== view.receipt.requestId
+    || previous.receipt.revision > view.receipt.revision) throw invalid();
+  const completedRoot = fs.realpathSync.native(path.join(manifest.repoRoot, '.agents', 'workspace', 'completed'));
+  const source = fs.realpathSync.native(path.join(completedRoot, manifest.taskId));
+  if (source !== path.join(completedRoot, manifest.taskId)) throw invalid();
+  const stat = fs.statSync(source, { bigint: true });
+  return {
+    taskId: manifest.taskId, generation: manifest.generation,
+    containerId: container.id, branch: manifest.branch,
+    worktreeRoot: fs.realpathSync.native(manifest.worktreeRoot),
+    source, sourceDevice: String(stat.dev), sourceInode: String(stat.ino), receipt: view.receipt
+  };
+}
+
+export function publishCompletedReentry(manifest: SandboxControlManifest, evidence: ReentryEvidence): void {
+  atomicWriteJson(evidencePath(manifest), evidence);
+}
+
+export async function completedReentryView(
+  manifest: SandboxControlManifest,
+  inspect: typeof inspectSandboxControlContainer = inspectSandboxControlContainer
+): Promise<SandboxTaskView | null> {
+  const file = evidencePath(manifest);
+  if (!fs.existsSync(file)) return null;
+  const evidence: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const current = await prepareCompletedReentry(manifest, inspect);
+  if (JSON.stringify(evidence) !== JSON.stringify(current)) throw invalid();
+  return {
+    state: 'current', taskId: current.taskId, observedSource: 'completed',
+    receipt: current.receipt, reasonCode: null
+  };
+}
+
+export async function waitForCompletedReentry(manifest: SandboxControlManifest, evidence: ReentryEvidence): Promise<void> {
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    const status = readSandboxControlStatus(manifest.publicStatusDir);
+    if (status.generation !== evidence.generation) throw invalid();
+    if (status.taskView.state === 'current' && status.taskView.observedSource === 'completed'
+      && status.taskView.taskId === evidence.taskId
+      && JSON.stringify(status.taskView.receipt) === JSON.stringify(evidence.receipt)) return;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error('SANDBOX_COMPLETED_REENTRY_STATUS_TIMEOUT');
+}

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

@@ -1,5 +1,7 @@
 import type { SandboxControlManifest } from './protocol.ts';
-import { commandForEngine, runEngine, runProbe } from '../shell.ts';
+import { runProbe } from '../shell.ts';
+import { captureSandboxAuthority, isSandboxAuthorityEvidence, verifySandboxAuthority } from '../engines/authority.ts';
+import { discoverExactContainer } from '../engines/docker-exact-discovery.ts';
 
 export type ContainerObservation =
   | Readonly<{ state: 'found'; id: string; running: boolean; labels: Readonly<Record<string, string>> }>
@@ -12,20 +14,13 @@ export type ContainerInspection = Readonly<{
   labels?: unknown;
 }>;
 
-function isAuthoritativeNotFound(error: unknown): boolean {
-  const message = error instanceof Error ? error.message : String(error);
-  return /(?:no such (?:container|object)|container .* not found|cannot find container)/i.test(message);
-}
-
 export function classifySandboxContainerInspection(
   expected: SandboxControlManifest['containerIdentity'],
   inspection: ContainerInspection | { notFound: true } | { error: unknown }
 ): ContainerObservation {
   if ('notFound' in inspection) return { state: 'absent', id: expected.id };
   if ('error' in inspection) {
-    return isAuthoritativeNotFound(inspection.error)
-      ? { state: 'absent', id: expected.id }
-      : { state: 'unknown', reason: `container inspection failed: ${inspection.error instanceof Error ? inspection.error.message : String(inspection.error)}` };
+    return { state: 'unknown', reason: `container inspection failed: ${inspection.error instanceof Error ? inspection.error.message : String(inspection.error)}` };
   }
   const response = inspection as ContainerInspection;
   if (typeof response.id !== 'string' || response.id !== expected.id
@@ -49,44 +44,33 @@ export function classifySandboxContainerInspection(
 
 export async function inspectSandboxControlContainer(
   manifest: SandboxControlManifest,
-  options: { run?: typeof runEngine; probe?: typeof runProbe; timeoutMs?: number } = {}
+  options: { probe?: typeof runProbe; timeoutMs?: number } = {}
 ): Promise<ContainerObservation> {
+  if (!isSandboxAuthorityEvidence(manifest.authorityEvidence)) {
+    return { state: 'unknown', reason: 'SANDBOX_AUTHORITY_EVIDENCE_MISSING' };
+  }
   try {
-    const args = ['inspect', '--format', '{{json .}}', manifest.containerIdentity.id];
-    let raw: string;
-    if (options.run) {
-      raw = options.run(manifest.engine, 'docker', args, options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs });
-    } else {
-      const command = commandForEngine(manifest.engine, 'docker', args);
-      const result = (options.probe ?? runProbe)(
-        command.cmd,
-        command.args,
-        options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs }
-      );
-      if (result.status !== 0) {
-        const stderr = typeof result.stderr === 'string' ? result.stderr : result.stderr?.toString('utf8') ?? '';
-        return classifySandboxContainerInspection(manifest.containerIdentity, {
-          error: new Error(stderr || `container inspection exited with ${result.status ?? 'unknown'}`)
-        });
-      }
-      raw = typeof result.stdout === 'string' ? result.stdout : result.stdout?.toString('utf8') ?? '';
+    const authority = captureSandboxAuthority(manifest.engine, {
+      probe: options.probe,
+      timeoutMs: options.timeoutMs,
+      lockDomain: manifest.authorityEvidence.lockDomain,
+      route: manifest.authorityEvidence
+    });
+    const authorityState = verifySandboxAuthority(manifest.authorityEvidence, authority);
+    if (authorityState.state !== 'verified') {
+      return { state: 'unknown', reason: authorityState.reason ?? 'SANDBOX_AUTHORITY_UNAVAILABLE' };
     }
-    const parsed = JSON.parse(raw) as {
-      Id?: unknown;
-      State?: { Running?: unknown };
-      Config?: { Labels?: unknown };
-    } | Array<{
-      Id?: unknown;
-      State?: { Running?: unknown };
-      Config?: { Labels?: unknown };
-    }>;
-    const value = Array.isArray(parsed) && parsed.length === 1 ? parsed[0] : parsed;
-    if (!value || Array.isArray(value)) return { state: 'unknown', reason: 'container inspection response is incomplete' };
-    return classifySandboxContainerInspection(manifest.containerIdentity, {
-      id: value.Id,
-      running: value.State?.Running,
-      labels: value.Config?.Labels
+    const discovered = discoverExactContainer(manifest.engine, manifest.containerIdentity.id, {
+      probe: options.probe,
+      timeoutMs: options.timeoutMs,
+      authority: manifest.authorityEvidence
     });
+    if (discovered.state === 'absent') return { state: 'absent', id: discovered.id };
+    if (discovered.state === 'conflict') {
+      return { state: 'unknown', reason: `SANDBOX_CONTROL_CONTAINER_CONFLICT: ${discovered.reason}` };
+    }
+    if (discovered.state === 'unknown') return discovered;
+    return classifySandboxContainerInspection(manifest.containerIdentity, discovered);
   } catch (error) {
     return classifySandboxContainerInspection(manifest.containerIdentity, { error });
   }