@fitlab-ai/agent-infra 0.9.13 → 0.9.14

package/lib/sandbox/control/task-view.ts

@@ -0,0 +1,240 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const SANDBOX_TASK_VIEW_STATES = ['not-applicable', 'current', 'finalized-stale', 'unknown'] as const;
+export const SANDBOX_TASK_VIEW_SOURCES = ['active', 'completed', 'unknown'] as const;
+
+export type SandboxTaskViewState = typeof SANDBOX_TASK_VIEW_STATES[number];
+export type SandboxTaskViewSource = typeof SANDBOX_TASK_VIEW_SOURCES[number];
+export type SandboxTaskViewReceipt = Readonly<{
+  receiptId: string;
+  revision: number;
+  generation: string;
+  requestId: string;
+}>;
+export type SandboxTaskView = Readonly<{
+  state: SandboxTaskViewState;
+  taskId: string | null;
+  observedSource: SandboxTaskViewSource | null;
+  receipt: SandboxTaskViewReceipt | null;
+  reasonCode: string | null;
+}>;
+
+export type TaskViewProjectionInput = Readonly<{
+  mode: 'task-bound' | 'branch-only';
+  taskId: string | null;
+  generation: string;
+  source: SandboxTaskViewSource;
+  sourceMatches: boolean;
+  receipt?: unknown;
+  requestId?: string;
+}>;
+
+export type TaskViewAccessEffect =
+  | 'diagnostic'
+  | 'progress'
+  | 'artifact-write'
+  | 'terminal-verdict'
+  | 'recovery'
+  | 'cleanup'
+  | 'remote-write';
+
+export type TaskViewAccess = Readonly<{
+  allowed: boolean;
+  state: SandboxTaskViewState;
+  reasonCode: string | null;
+  message: string | null;
+}>;
+
+function invalidView(message: string): Error {
+  return new Error(`SANDBOX_TASK_VIEW_INVALID: ${message}`);
+}
+
+function receiptIdentity(value: unknown, generation: string, requestId?: string): SandboxTaskViewReceipt | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const receipt = value as Record<string, unknown>;
+  const binding = receipt.controlBinding;
+  if (!binding || typeof binding !== 'object' || Array.isArray(binding)) return null;
+  const controlBinding = binding as Record<string, unknown>;
+  if (receipt.version !== 2 || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
+    || !Number.isSafeInteger(receipt.revision) || (receipt.revision as number) < 0
+    || receipt.lifecycle !== 'done'
+    || controlBinding.generation !== generation
+    || typeof controlBinding.requestId !== 'string'
+    || !/^[a-f0-9-]{16,64}$/u.test(controlBinding.requestId)
+    || (requestId !== undefined && controlBinding.requestId !== requestId)) return null;
+  return {
+    receiptId: receipt.receiptId,
+    revision: receipt.revision as number,
+    generation,
+    requestId: controlBinding.requestId
+  };
+}
+
+export function parseSandboxTaskView(value: unknown): SandboxTaskView {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalidView('taskView must be an object');
+  const view = value as Record<string, unknown>;
+  const receipt = view.receipt === null ? null : parseSandboxTaskViewReceipt(view.receipt);
+  if (!SANDBOX_TASK_VIEW_STATES.includes(view.state as SandboxTaskViewState)
+    || (view.taskId !== null && typeof view.taskId !== 'string')
+    || (view.observedSource !== null && !SANDBOX_TASK_VIEW_SOURCES.includes(view.observedSource as SandboxTaskViewSource))
+    || (view.reasonCode !== null && typeof view.reasonCode !== 'string')
+    || (view.receipt !== null && receipt === null)) {
+    throw invalidView('taskView schema is invalid');
+  }
+  if (view.state === 'not-applicable' && (view.taskId !== null || view.observedSource !== null || view.receipt !== null)) {
+    throw invalidView('not-applicable taskView cannot carry task evidence');
+  }
+  if (view.state === 'current' && (view.taskId === null || view.observedSource === null)) {
+    throw invalidView('current taskView requires taskId and observedSource');
+  }
+  if (view.state === 'current' && view.observedSource === 'completed' && view.receipt === null) {
+    throw invalidView('completed current taskView requires receipt');
+  }
+  if (view.state === 'finalized-stale' && (view.taskId === null || view.receipt === null)) {
+    throw invalidView('finalized-stale taskView requires taskId and receipt');
+  }
+  return view as SandboxTaskView;
+}
+
+function parseSandboxTaskViewReceipt(value: unknown): SandboxTaskViewReceipt | null {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const receipt = value as Record<string, unknown>;
+  if (Object.keys(receipt).sort().join(',') !== 'generation,receiptId,requestId,revision'
+    || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
+    || !Number.isSafeInteger(receipt.revision) || (receipt.revision as number) < 0
+    || typeof receipt.generation !== 'string' || receipt.generation.length === 0
+    || typeof receipt.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(receipt.requestId)) return null;
+  return receipt as SandboxTaskViewReceipt;
+}
+
+export function taskViewForManifest(params: Readonly<{
+  repoRoot: string;
+  mode: 'task-bound' | 'branch-only';
+  taskId: string | null;
+  generation: string;
+  receipt?: unknown;
+}>): SandboxTaskView {
+  if (params.mode !== 'task-bound' || !params.taskId) {
+    return { state: 'not-applicable', taskId: null, observedSource: null, receipt: null, reasonCode: null };
+  }
+  const active = path.join(params.repoRoot, '.agents', 'workspace', 'active', params.taskId, 'task.md');
+  const completed = path.join(params.repoRoot, '.agents', 'workspace', 'completed', params.taskId, 'task.md');
+  const activeExists = fs.existsSync(active);
+  const completedExists = fs.existsSync(completed);
+  if (activeExists === completedExists) {
+    return {
+      state: 'unknown', taskId: params.taskId,
+      observedSource: activeExists ? 'unknown' : null,
+      receipt: null, reasonCode: activeExists ? 'SANDBOX_TASK_VIEW_SOURCE_CONFLICT' : 'SANDBOX_TASK_VIEW_SOURCE_MISSING'
+    };
+  }
+  const source = completedExists ? 'completed' : 'active';
+  const receipt = receiptIdentity(params.receipt, params.generation);
+  const receiptProvided = params.receipt !== undefined && params.receipt !== null;
+  if (source === 'completed' && receipt) {
+    return { state: 'current', taskId: params.taskId, observedSource: source, receipt, reasonCode: null };
+  }
+  if (source === 'active' && receipt) {
+    return {
+      state: 'finalized-stale', taskId: params.taskId, observedSource: source, receipt,
+      reasonCode: 'SANDBOX_TASK_VIEW_SOURCE_STALE'
+    };
+  }
+  if (receiptProvided) {
+    return {
+      state: 'unknown', taskId: params.taskId, observedSource: source, receipt: null,
+      reasonCode: 'SANDBOX_TASK_VIEW_RECEIPT_INVALID'
+    };
+  }
+  if (source === 'active') {
+    return { state: 'current', taskId: params.taskId, observedSource: source, receipt: null, reasonCode: null };
+  }
+  return {
+    state: 'unknown', taskId: params.taskId, observedSource: source, receipt: null,
+    reasonCode: 'SANDBOX_TASK_VIEW_EVIDENCE_UNAVAILABLE'
+  };
+}
+
+export function projectSandboxTaskView(input: TaskViewProjectionInput): SandboxTaskView {
+  if (input.mode !== 'task-bound' || !input.taskId) {
+    return { state: 'not-applicable', taskId: null, observedSource: null, receipt: null, reasonCode: null };
+  }
+  const receipt = receiptIdentity(input.receipt, input.generation, input.requestId);
+  if (input.source === 'completed' && receipt && input.sourceMatches) {
+    return { state: 'current', taskId: input.taskId, observedSource: 'completed', receipt, reasonCode: null };
+  }
+  if (receipt && input.source === 'active' && !input.sourceMatches) {
+    return { state: 'finalized-stale', taskId: input.taskId, observedSource: 'active', receipt, reasonCode: 'SANDBOX_TASK_VIEW_SOURCE_STALE' };
+  }
+  if (!receipt && input.source === 'active' && input.sourceMatches) {
+    return { state: 'current', taskId: input.taskId, observedSource: 'active', receipt: null, reasonCode: null };
+  }
+  return {
+    state: 'unknown',
+    taskId: input.taskId,
+    observedSource: input.source,
+    receipt,
+    reasonCode: receipt ? 'SANDBOX_TASK_VIEW_SOURCE_UNCONFIRMED' : 'SANDBOX_TASK_VIEW_EVIDENCE_UNAVAILABLE'
+  };
+}
+
+export function taskViewAfterFinalization(params: Readonly<{
+  taskId: string;
+  generation: string;
+  requestId: string;
+  receipt: unknown;
+}>): SandboxTaskView {
+  const receipt = receiptIdentity(params.receipt, params.generation, params.requestId);
+  if (!receipt) {
+    return {
+      state: 'unknown', taskId: params.taskId, observedSource: 'unknown', receipt: null,
+      reasonCode: 'SANDBOX_TASK_VIEW_RECEIPT_INVALID'
+    };
+  }
+  return {
+    state: 'finalized-stale', taskId: params.taskId, observedSource: 'active', receipt,
+    reasonCode: 'SANDBOX_TASK_VIEW_FINALIZED'
+  };
+}
+
+export function mergeSandboxTaskView(
+  canonical: SandboxTaskView,
+  previous: SandboxTaskView
+): SandboxTaskView {
+  if (previous.state !== 'finalized-stale' && previous.state !== 'unknown') return canonical;
+  return previous;
+}
+
+export function accessSandboxTaskView(view: SandboxTaskView, effect: TaskViewAccessEffect): TaskViewAccess {
+  if (effect === 'diagnostic' || effect === 'cleanup' || effect === 'recovery') {
+    return { allowed: true, state: view.state, reasonCode: view.reasonCode, message: null };
+  }
+  if (view.state === 'current' && view.observedSource === 'active') {
+    return { allowed: true, state: view.state, reasonCode: null, message: null };
+  }
+  const reasonCode = view.state === 'current'
+    ? 'SANDBOX_TASK_VIEW_COMPLETED_READ_ONLY'
+    : view.reasonCode ?? `SANDBOX_TASK_VIEW_${view.state.toUpperCase().replaceAll('-', '_')}`;
+  return {
+    allowed: false,
+    state: view.state,
+    reasonCode,
+    message: view.state === 'unknown'
+      ? 'task view cannot be confirmed; inspect status, recover the original request, or explicitly clean up the sandbox'
+      : view.state === 'finalized-stale'
+        ? 'task view is finalized/stale; exit or clean up the sandbox, or use a validated re-entry'
+        : 'completed task views are read-only'
+  };
+}
+
+export function taskViewFromStatus(value: unknown): SandboxTaskView {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw invalidView('status must be an object');
+  const status = value as Record<string, unknown>;
+  if (status.version !== 3) throw invalidView('status version is unsupported');
+  const taskView = parseSandboxTaskView(status.taskView);
+  if (taskView.receipt && taskView.receipt.generation !== status.generation) {
+    throw invalidView('taskView receipt generation does not match status generation');
+  }
+  return taskView;
+}

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);
+}