@fitlab-ai/agent-infra 0.9.13 → 0.9.15

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/audit.ts

@@ -0,0 +1,253 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { SandboxControlManifest, SandboxControlFamily, SandboxControlRequest } from './protocol.ts';
+import { identityDigest as digestIdentity } from './identity-sentinel.ts';
+import { acquireSandboxResourceLock } from './native-file-lock.ts';
+import { fsyncDirectory, writeDurableFile } from '../../fs/durable-write.ts';
+
+export const SANDBOX_CONTROL_AUDIT_PHASES = Object.freeze([
+  'validated', 'gated', 'reserved', 'prepared', 'accepted-authorized', 'accepted-committed',
+  'start-authorized', 'started-committed', 'completed', 'evidence-written',
+  'publish-authorized', 'published-committed', 'rejected', 'recovered'
+] as const);
+export type SandboxControlAuditPhase = typeof SANDBOX_CONTROL_AUDIT_PHASES[number];
+export type SandboxControlAuditOutcome = 'not-executed' | 'in-progress' | 'success' | 'failure' | 'unknown' | 'rejected';
+
+export type SandboxControlAuditContext = Readonly<{
+  requestId: string;
+  taskId: string | null;
+  family: SandboxControlFamily | null;
+  operation: string | null;
+  phase: SandboxControlAuditPhase;
+  outcome: SandboxControlAuditOutcome;
+  generation: string;
+  identityDigest: string;
+}>;
+
+export type SandboxControlTransition = Readonly<{
+  version: 1;
+  requestId: string;
+  generation: string;
+  phase: SandboxControlAuditPhase;
+  at: number;
+  identityDigest: string;
+  reference: string | null;
+}>;
+
+const REQUEST_ID = /^[a-f0-9-]{16,64}$/u;
+const SAFE_OPERATION = /^[a-z][a-z0-9.-]{0,96}$/u;
+const AUDIT_MAX_BYTES = 1024 * 1024;
+
+export function requestAuditFields(manifest: SandboxControlManifest, request: SandboxControlRequest) {
+  return {
+    requestId: request.id, requestFamily: request.family, sandboxTaskId: manifest.taskId,
+    requestGeneration: request.generation, requestIssuedAt: request.issuedAt, requestExpiresAt: request.expiresAt
+  };
+}
+
+export function resultAuditFields(result: Readonly<{ exitCode: number; stdout: string; stderr: string }>) {
+  return {
+    exitCode: result.exitCode,
+    outputBytes: Buffer.byteLength(result.stdout, 'utf8'), errorBytes: Buffer.byteLength(result.stderr, 'utf8'),
+    outputDigest: createHash('sha256').update(result.stdout, 'utf8').digest('hex'),
+    errorDigest: createHash('sha256').update(result.stderr, 'utf8').digest('hex')
+  };
+}
+
+function auditRoot(manifest: SandboxControlManifest): string {
+  return path.dirname(path.resolve(manifest.publicStatusDir));
+}
+
+function auditPath(manifest: SandboxControlManifest): string {
+  return path.join(auditRoot(manifest), 'audit.ndjson');
+}
+
+function manifestIdentityDigest(manifest: SandboxControlManifest): string {
+  return digestIdentity({
+    version: 1,
+    mode: manifest.mode,
+    taskId: manifest.taskId,
+    generation: manifest.generation,
+    controlRootId: manifest.controlRootId
+  });
+}
+
+export function createSandboxControlAuditContext(
+  manifest: SandboxControlManifest,
+  params: Readonly<{
+    requestId: string;
+    family: SandboxControlFamily | null;
+    operation?: string | null;
+    phase: SandboxControlAuditPhase;
+    outcome: SandboxControlAuditOutcome;
+  }>
+): SandboxControlAuditContext {
+  if (!REQUEST_ID.test(params.requestId)) throw new Error('SANDBOX_CONTROL_AUDIT_REQUEST_INVALID');
+  if (params.operation !== null && params.operation !== undefined && !SAFE_OPERATION.test(params.operation)) {
+    throw new Error('SANDBOX_CONTROL_AUDIT_OPERATION_INVALID');
+  }
+  if (!SANDBOX_CONTROL_AUDIT_PHASES.includes(params.phase)) throw new Error('SANDBOX_CONTROL_AUDIT_PHASE_INVALID');
+  return {
+    requestId: params.requestId,
+    taskId: manifest.taskId,
+    family: params.family,
+    operation: params.operation ?? null,
+    phase: params.phase,
+    outcome: params.outcome,
+    generation: manifest.generation,
+    identityDigest: manifestIdentityDigest(manifest)
+  };
+}
+
+function safeFields(fields: Readonly<Record<string, string | number | boolean | null>>): Record<string, string | number | boolean | null> {
+  const result: Record<string, string | number | boolean | null> = {};
+  for (const [key, value] of Object.entries(fields)) {
+    if (!/^[a-z][a-zA-Z0-9]{0,63}$/u.test(key)) continue;
+    if (/(token|secret|credential|proof|password|path|root|cwd|stdout|stderr|args|command|taskref)/iu.test(key)) continue;
+    if (typeof value === 'string' && value.length > 256) continue;
+    result[key] = value;
+  }
+  return result;
+}
+
+function requestHasTerminalTransition(directory: string): boolean {
+  const transitions = path.join(directory, 'transitions');
+  if (!fs.existsSync(transitions)) return false;
+  return ['published-committed', 'recovered'].some((phase) => fs.existsSync(path.join(transitions, `${phase}.json`)));
+}
+
+function hasActiveRequest(manifest: SandboxControlManifest): boolean {
+  if (!fs.existsSync(manifest.processingDir)) return false;
+  return fs.readdirSync(manifest.processingDir, { withFileTypes: true })
+    .some((entry) => entry.isDirectory() && REQUEST_ID.test(entry.name)
+      && !requestHasTerminalTransition(path.join(manifest.processingDir, entry.name)));
+}
+
+function rotateAuditUnderLock(manifest: SandboxControlManifest, filePath: string): void {
+  if (!fs.existsSync(filePath) || fs.statSync(filePath).size < AUDIT_MAX_BYTES) return;
+  if (hasActiveRequest(manifest)) return;
+  fs.rmSync(`${filePath}.1`, { force: true });
+  fs.renameSync(filePath, `${filePath}.1`);
+  fsyncDirectory(auditRoot(manifest));
+  const descriptor = fs.openSync(filePath, 'a', 0o600);
+  try {
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function appendAuditRecord(
+  manifest: SandboxControlManifest,
+  record: Readonly<Record<string, unknown>>,
+  critical: boolean
+): void {
+  const root = auditRoot(manifest);
+  fs.mkdirSync(root, { recursive: true, mode: 0o700 });
+  const lock = acquireSandboxResourceLock(`sandbox-control-audit:${root}`);
+  try {
+    const filePath = auditPath(manifest);
+    rotateAuditUnderLock(manifest, filePath);
+    const descriptor = fs.openSync(filePath, 'a', 0o600);
+    try {
+      fs.writeSync(descriptor, `${JSON.stringify(record)}\n`, undefined, 'utf8');
+      if (critical) fs.fsyncSync(descriptor);
+    } finally {
+      fs.closeSync(descriptor);
+    }
+  } catch (error) {
+    if (critical) throw new Error(`SANDBOX_CONTROL_AUDIT_UNAVAILABLE: ${error instanceof Error ? error.message : String(error)}`);
+  } finally {
+    lock.release();
+  }
+}
+
+export function appendCriticalAudit(
+  manifest: SandboxControlManifest,
+  context: SandboxControlAuditContext,
+  fields: Readonly<Record<string, string | number | boolean | null>> = {},
+  now = Date.now()
+): void {
+  appendAuditRecord(manifest, {
+    version: 2,
+    at: now,
+    event: context.phase,
+    ...context,
+    ...safeFields(fields)
+  }, true);
+}
+
+export function appendDiagnosticAudit(
+  manifest: SandboxControlManifest,
+  event: string,
+  fields: Readonly<Record<string, string | number | boolean | null>> = {},
+  now = Date.now()
+): void {
+  try {
+    appendAuditRecord(manifest, {
+      version: 2,
+      at: now,
+      event,
+      generation: manifest.generation,
+      identityDigest: manifestIdentityDigest(manifest),
+      ...safeFields(fields)
+    }, false);
+  } catch {
+    // Diagnostics are deliberately best effort.
+  }
+}
+
+function transitionPath(manifest: SandboxControlManifest, requestId: string, phase: SandboxControlAuditPhase): string {
+  if (!REQUEST_ID.test(requestId)) throw new Error('SANDBOX_CONTROL_TRANSITION_REQUEST_INVALID');
+  return path.join(manifest.processingDir, requestId, 'transitions', `${phase}.json`);
+}
+
+export function writeSandboxControlTransition(
+  manifest: SandboxControlManifest,
+  params: Readonly<{
+    requestId: string;
+    phase: SandboxControlAuditPhase;
+    reference?: string | null;
+    now?: number;
+  }>
+): SandboxControlTransition {
+  const transition: SandboxControlTransition = {
+    version: 1,
+    requestId: params.requestId,
+    generation: manifest.generation,
+    phase: params.phase,
+    at: params.now ?? Date.now(),
+    identityDigest: manifestIdentityDigest(manifest),
+    reference: params.reference ?? null
+  };
+  const target = transitionPath(manifest, params.requestId, params.phase);
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  try {
+    writeDurableFile(target, `${JSON.stringify(transition)}\n`, { mode: 0o600, replace: false });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+    const existing = readSandboxControlTransition(manifest, params.requestId, params.phase);
+    if (JSON.stringify(existing) !== JSON.stringify(transition)) throw new Error('SANDBOX_CONTROL_TRANSITION_CONFLICT');
+  }
+  return transition;
+}
+
+export function readSandboxControlTransition(
+  manifest: SandboxControlManifest,
+  requestId: string,
+  phase: SandboxControlAuditPhase
+): SandboxControlTransition {
+  const filePath = transitionPath(manifest, requestId, phase);
+  if (!fs.existsSync(filePath)) throw new Error('SANDBOX_CONTROL_TRANSITION_MISSING');
+  let value: unknown;
+  try { value = JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch { throw new Error('SANDBOX_CONTROL_TRANSITION_INVALID'); }
+  const candidate = value as Partial<SandboxControlTransition> | null;
+  if (!candidate || candidate.version !== 1 || candidate.requestId !== requestId
+    || candidate.generation !== manifest.generation || candidate.phase !== phase
+    || !Number.isSafeInteger(candidate.at) || typeof candidate.identityDigest !== 'string'
+    || (candidate.reference !== null && typeof candidate.reference !== 'string')) {
+    throw new Error('SANDBOX_CONTROL_TRANSITION_INVALID');
+  }
+  return candidate as SandboxControlTransition;
+}

package/lib/sandbox/control/client.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { hasTaskBoundMarker } from '../../internal/task-operation-registry.ts';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import {
@@ -12,7 +13,8 @@ import {
   type SandboxTaskCreateRequest,
   type SandboxTaskCommandRequest,
   type SandboxTaskFinalizationRequest,
-  type SandboxCodexControllerRequest
+  type SandboxCodexControllerRequest,
+  type SandboxTaskWorkflowRequest
 } from './protocol.ts';
 import type {
   CodexControllerLeaseProofV1,
@@ -22,6 +24,11 @@ import type { ProcessIdentity } from '../../server/process-state.ts';
 import { normalizeAgentToken } from '../../agent-clients/tokens.ts';
 import { readSandboxControlPayload, readSandboxControlStatus } from './state.ts';
 import type { TaskCreateCandidateV1 } from '../../task/create.ts';
+import { accessSandboxTaskView, taskViewFromStatus, type TaskViewAccessEffect } from './task-view.ts';
+import { readSandboxControlIdentitySentinel } from './identity-sentinel.ts';
+import type { TaskWorkflowRequest } from './task-workflow.ts';
+import type { LifecycleAuthorityRequestV1 } from '../../task/control-authority.ts';
+import { configuredShortIdLength, resolveShortIdReadOnly } from '../../task/short-id.ts';
 
 const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
 
@@ -52,7 +59,30 @@ function clientError(
   throw new SandboxControlClientError({ code, message: `${code}: ${message}`, retryable }, accepted, requestId);
 }
 
-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 {
+  if (fs.existsSync(statusDir)) {
+    let identity;
+    try {
+      identity = readSandboxControlIdentitySentinel(statusDir);
+    } catch (error) {
+      const code = error instanceof Error && error.message.endsWith('MISSING')
+        ? 'SANDBOX_CONTROL_IDENTITY_MISSING'
+        : 'SANDBOX_CONTROL_IDENTITY_MALFORMED';
+      clientError(code, 'sandbox control identity is missing or invalid', false);
+    }
+    if (identity.generation !== generation) {
+      clientError('SANDBOX_CONTROL_IDENTITY_GENERATION_MISMATCH', 'sandbox control identity generation does not match the request', false);
+    }
+    if (env.AGENT_INFRA_CONTROL_ROOT_ID && identity.controlRootId !== env.AGENT_INFRA_CONTROL_ROOT_ID) {
+      clientError('SANDBOX_CONTROL_IDENTITY_ROOT_ID_MISMATCH', 'sandbox control identity root does not match the client configuration', false);
+    }
+  }
   let status;
   try {
     status = readSandboxControlStatus(statusDir);
@@ -71,9 +101,30 @@ 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';
+  if (request.family === 'task-workflow') return request.workflow.operation === 'artifact-inspect' || request.workflow.operation === 'decision-next-id' ? '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
     || !['completed', 'rejected'].includes(response.phase)
@@ -81,13 +132,13 @@ function parseResponse(raw: string, id: string): SandboxControlResponse {
     || (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, false, id);
+    clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response is invalid', false, accepted, id);
   }
   return response;
 }
 
-function readPublishedResponse(raw: string, id: string, channelDir: string): SandboxControlResponse {
-  const response = parseResponse(raw, id);
+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;
@@ -115,6 +166,44 @@ function cancelPendingRequest(requestPath: string): boolean {
   }
 }
 
+const CONTROL_TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+const CONTROL_SHORT_ID_RE = /^\d+$/;
+
+type CanonicalRequestTask =
+  | Readonly<{ kind: 'none' }>
+  | Readonly<{ kind: 'task'; taskId: string }>
+  | Readonly<{ kind: 'unresolved' }>;
+
+// Use the current short-id contract for the first visible active registry.
+export function resolveVisibleActiveShortId(ref: string): string | null {
+  let dir = process.cwd();
+  for (let depth = 0; depth < 64; depth += 1) {
+    const registryPath = path.join(dir, '.agents', 'workspace', 'active', '.short-ids.json');
+    if (fs.existsSync(registryPath)) {
+      const resolved = resolveShortIdReadOnly(ref, dir, { shortIdLength: configuredShortIdLength(dir) });
+      return resolved.ok ? resolved.taskId : null;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// A request's leading argument is only a task reference for some families and
+// may be a documented short id. Compare canonical ids so a bound sandbox keeps
+// refusing other tasks without rejecting its own task's short id.
+function canonicalRequestTask(request: SandboxControlRequest): CanonicalRequestTask {
+  const ref = request.family === 'task-workflow'
+    ? request.workflow.taskId
+    : 'args' in request ? request.args[0] ?? null : null;
+  if (!ref) return { kind: 'none' };
+  if (CONTROL_TASK_ID_RE.test(ref)) return { kind: 'task', taskId: ref };
+  if (!CONTROL_SHORT_ID_RE.test(ref)) return { kind: 'none' };
+  const resolved = resolveVisibleActiveShortId(ref);
+  return resolved ? { kind: 'task', taskId: resolved } : { kind: 'unresolved' };
+}
+
 function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly<{
   channelDir?: string;
   statusDir?: string;
@@ -122,7 +211,22 @@ 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 identityPath = path.join(statusDir, 'identity.json');
+  if (fs.existsSync(statusDir)) {
+    const identity = readSandboxControlIdentitySentinel(statusDir);
+    const requestTask = canonicalRequestTask(request);
+    if (identity.mode === 'task-bound'
+      && ((process.env.AGENT_INFRA_TASK_ID && process.env.AGENT_INFRA_TASK_ID !== identity.taskId)
+        || requestTask.kind === 'unresolved'
+        || (requestTask.kind === 'task' && requestTask.taskId !== identity.taskId))) {
+      clientError('SANDBOX_CONTROL_IDENTITY_TOPOLOGY_MISMATCH', 'request task does not match the sandbox identity', false);
+    }
+    if (identity.mode === 'branch-only' && (request.family === 'task-finalization' || request.family === 'task-workflow')) {
+      clientError('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot finalize tasks', false);
+    }
+  }
   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, false, request.id);
@@ -154,7 +258,9 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
       }
       let response: SandboxControlResponse;
       try {
-        response = readPublishedResponse(raw, request.id, channelDir);
+        // 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;
@@ -176,7 +282,7 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
     }
     if (!accepted) {
       try {
-        preflight(statusDir, request.generation);
+        preflight(statusDir, request.generation, taskViewEffect);
       } catch (error) {
         if (cancelPendingRequest(requestPath)) throw error;
         clientError(
@@ -236,7 +342,9 @@ export function recoverSandboxControl(requestId: string, params: Readonly<{
       }
       let response: SandboxControlResponse;
       try {
-        response = readPublishedResponse(raw, requestId, channelDir);
+        // 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;
@@ -276,7 +384,7 @@ export function requestSandboxControl(params: Readonly<{
   token?: string; generation?: string; timeoutMs?: number;
 }>): SandboxControlResponse {
   if (!isSandboxControlFamily(params.family)) clientError('SANDBOX_CONTROL_COMMAND_DENIED', `'${params.family}' is not allowed`, false);
-  if (params.family === 'task-create' || params.family === 'codex-controller' || params.family === 'task-finalization') {
+  if (params.family === 'task-create' || params.family === 'codex-controller' || params.family === 'task-finalization' || params.family === 'task-workflow') {
     clientError('SANDBOX_CONTROL_COMMAND_DENIED', `'${params.family}' requires a typed request`, false);
   }
   const auth = authority(params);
@@ -295,6 +403,7 @@ export function requestSandboxTaskControl(params: Readonly<{
   family: 'task-lifecycle' | 'task-orchestration';
   args: string[];
   controllerProof: CodexControllerLeaseProofV1 | null;
+  authority?: LifecycleAuthorityRequestV1;
   channelDir?: string;
   statusDir?: string;
   token?: string;
@@ -305,14 +414,15 @@ export function requestSandboxTaskControl(params: Readonly<{
   const issuedAt = Date.now();
   const request: SandboxTaskCommandRequest = {
     version: 3,
-    id: randomUUID(),
+    id: params.authority?.requestId ?? randomUUID(),
     ...auth,
     issuedAt,
     expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
     family: params.family,
     args: params.args,
     controllerProcess: null,
-    controllerProof: params.controllerProof
+    controllerProof: params.authority ? null : params.controllerProof,
+    ...(params.authority ? { authority: params.authority } : {})
   };
   return exchangeSandboxControl(request, params);
 }
@@ -345,6 +455,33 @@ export function requestSandboxTaskFinalization(params: Readonly<{
   return exchangeSandboxControl(request, params);
 }
 
+export function requestSandboxTaskWorkflow(params: Readonly<{
+  workflow: TaskWorkflowRequest;
+  channelDir?: string;
+  statusDir?: string;
+  token?: string;
+  generation?: string;
+  timeoutMs?: number;
+  authority?: LifecycleAuthorityRequestV1;
+}>): SandboxControlResponse {
+  const auth = authority(params);
+  const issuedAt = Date.now();
+  const request: SandboxTaskWorkflowRequest = {
+    version: 3,
+    id: params.workflow.id,
+    ...auth,
+    issuedAt,
+    expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
+    family: 'task-workflow',
+    args: [],
+    controllerProcess: null,
+    controllerProof: null,
+    workflow: params.workflow,
+    ...(params.authority ? { authority: params.authority } : {})
+  };
+  return exchangeSandboxControl(request, params);
+}
+
 type CodexControllerClosed = Readonly<{
   version: 1;
   status: 'closed';

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