@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/sandbox/control/state.ts

@@ -1,3 +1,5 @@
+import { isCompletionEvidence, type CleanCompletionEvidence } from '../../task/orchestration.ts';
+import { parseControlOutput } from '../../task/control-recovery.ts';
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -23,6 +25,7 @@ import {
   SANDBOX_CONTROL_MAX_TERMINAL_RECORD_BYTES,
   SANDBOX_CONTROL_RESERVATION_BYTES
 } from './protocol.ts';
+import { parseSandboxTaskView, taskViewForManifest, type SandboxTaskView } from './task-view.ts';
 
 export const SANDBOX_CONTROL_AUDIT_MAX_BYTES = 1024 * 1024;
 export const SANDBOX_CONTROL_EXECUTION_STOP_MS = 2_000;
@@ -100,6 +103,82 @@ export function reservationPath(manifest: SandboxControlManifest, requestId: str
   return path.join(manifest.processingDir, requestId, 'reservation.json');
 }
 
+export type SandboxControlTerminalResult = Readonly<{
+  version: 1;
+  requestId: string;
+  generation: string;
+  taskId: string | null;
+  intentDigest: string;
+  targetState: string | null;
+  status: string;
+  changed: boolean | null;
+  completionEvidence: CleanCompletionEvidence | null;
+}>;
+
+export function terminalResultPath(manifest: SandboxControlManifest, requestId: string): string {
+  if (!/^[a-f0-9-]{16,64}$/u.test(requestId)) throw new Error('SANDBOX_CONTROL_TERMINAL_RESULT_INVALID');
+  return path.join(manifest.processingDir, requestId, 'terminal-result.json');
+}
+
+export function createSandboxControlTerminalResult(
+  manifest: SandboxControlManifest,
+  request: Readonly<{ id: string; family: string; operation?: string | null }>,
+  output: string
+): SandboxControlTerminalResult {
+  const nested = parseControlOutput(output) ?? {};
+  const run = nested.run && typeof nested.run === 'object' && !Array.isArray(nested.run)
+    ? nested.run as Record<string, unknown> : null;
+  const rawCompletion = nested.completionEvidence ?? run?.completionEvidence;
+  const operation = request.operation ?? (typeof nested.intent === 'string' ? nested.intent : null) ?? '';
+  return {
+    version: 1,
+    requestId: request.id,
+    generation: manifest.generation,
+    taskId: manifest.taskId,
+    intentDigest: createHash('sha256').update(`${request.family}\0${operation}`, 'utf8').digest('hex'),
+    targetState: typeof nested.targetState === 'string' ? nested.targetState : null,
+    status: typeof nested.status === 'string' ? nested.status : 'completed',
+    changed: typeof nested.changed === 'boolean' ? nested.changed : null,
+    completionEvidence: isCompletionEvidence(rawCompletion) ? rawCompletion : null
+  };
+}
+
+export function writeSandboxControlTerminalResult(
+  manifest: SandboxControlManifest,
+  request: Readonly<{ id: string; family: string; operation?: string | null }>,
+  output: string
+): SandboxControlTerminalResult {
+  const result = createSandboxControlTerminalResult(manifest, request, output);
+  const filePath = terminalResultPath(manifest, request.id);
+  try {
+    atomicWriteJsonNoReplace(filePath, result);
+  } catch (error) {
+    if (!(error instanceof Error) || error.message !== 'SANDBOX_CONTROL_TERMINAL_ALREADY_EXISTS') throw error;
+    const existing = readSandboxControlTerminalResult(filePath);
+    if (JSON.stringify(existing) !== JSON.stringify(result)) throw new Error('SANDBOX_CONTROL_TERMINAL_RESULT_CONFLICT');
+  }
+  return readSandboxControlTerminalResult(filePath);
+}
+
+export function readSandboxControlTerminalResult(filePath: string): SandboxControlTerminalResult {
+  const value = readJsonFile(filePath) as Partial<SandboxControlTerminalResult> | null;
+  if (!value || value.version !== 1 || typeof value.requestId !== 'string'
+    || typeof value.generation !== 'string' || (value.taskId !== null && typeof value.taskId !== 'string')
+    || typeof value.intentDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(value.intentDigest)
+    || (value.targetState !== null && typeof value.targetState !== 'string')
+    || typeof value.status !== 'string'
+    || (value.changed !== null && typeof value.changed !== 'boolean')) {
+    throw new Error('SANDBOX_CONTROL_TERMINAL_RESULT_INVALID');
+  }
+  if (value.completionEvidence !== null && !isCompletionEvidence(value.completionEvidence)) {
+    throw new Error('SANDBOX_CONTROL_TERMINAL_RESULT_INVALID');
+  }
+  if (value.changed === undefined) {
+    throw new Error('SANDBOX_CONTROL_TERMINAL_RESULT_INVALID');
+  }
+  return value as SandboxControlTerminalResult;
+}
+
 export function readSandboxControlResultEvidence(filePath: string): SandboxControlResultEvidence {
   assertRegularFile(filePath);
   const raw = fs.readFileSync(filePath, 'utf8');
@@ -296,10 +375,11 @@ export function writeSandboxControlStatus(
   state: SandboxControlStatus['state'],
   reasonCode: string | null,
   activeRequestId: string | null,
-  now = Date.now()
+  now = Date.now(),
+  taskView: SandboxTaskView = taskViewForManifest(manifest)
 ): SandboxControlStatus {
   const status: SandboxControlStatus = {
-    version: 2, generation: manifest.generation, broker, state, reasonCode, activeRequestId, updatedAt: now
+    version: 3, generation: manifest.generation, broker, state, reasonCode, activeRequestId, updatedAt: now, taskView
   };
   atomicWriteJson(statusPath(manifest), status, 0o600, false);
   return status;
@@ -307,7 +387,7 @@ export function writeSandboxControlStatus(
 
 export function parseSandboxControlStatus(value: unknown): SandboxControlStatus {
   const status = value as Partial<SandboxControlStatus> | null;
-  if (!status || status.version !== 2 || typeof status.generation !== 'string'
+  if (!status || status.version !== 3 || typeof status.generation !== 'string'
     || !status.broker || !Number.isSafeInteger(status.broker.pid) || typeof status.broker.startTime !== 'number'
     || !Number.isSafeInteger(status.broker.startTime) || typeof status.broker.brokerId !== 'string'
     || status.broker.brokerId.length === 0
@@ -315,6 +395,7 @@ export function parseSandboxControlStatus(value: unknown): SandboxControlStatus
     || (status.reasonCode !== null && typeof status.reasonCode !== 'string')
     || (status.activeRequestId !== null && typeof status.activeRequestId !== 'string')
     || !Number.isSafeInteger(status.updatedAt)) throw new Error('SANDBOX_CONTROL_STATUS_INVALID');
+  parseSandboxTaskView(status.taskView);
   return status as SandboxControlStatus;
 }
 

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/control/task-workflow.ts

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import { readStableFile, SecureFileError, writeAtomicFile } from '../../host-control/secure-fs.ts';
+
+import { TASK_WORKFLOW_COMMANDS, TASK_WORKFLOW_OPERATIONS, type TaskWorkflowOperation, type WorkflowCommand } from '../../task/workflow-command.ts';
+
+export type TaskWorkflowRequest = Readonly<{
+  version: 1;
+  id: string;
+  taskId: string;
+  generation: string;
+  operation: TaskWorkflowOperation;
+  args: readonly string[];
+}>;
+
+export function validateTaskWorkflowRequest(value: unknown): TaskWorkflowRequest {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('TASK_WORKFLOW_REQUEST_INVALID');
+  const request = value as TaskWorkflowRequest;
+  if (Object.keys(request).sort().join(',') !== 'args,generation,id,operation,taskId,version'
+    || request.version !== 1 || typeof request.id !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(request.id)
+    || typeof request.taskId !== 'string' || !/^TASK-\d{8}-\d{6}$/u.test(request.taskId)
+    || typeof request.generation !== 'string' || !request.generation
+    || !Object.hasOwn(TASK_WORKFLOW_COMMANDS, request.operation)
+    || !Array.isArray(request.args) || request.args.length < 2 || request.args.length > 128
+    || !request.args.every((arg) => typeof arg === 'string' && !/[\r\n]/u.test(arg))
+    || request.args[0] !== request.taskId) throw new Error('TASK_WORKFLOW_REQUEST_INVALID');
+  const [, selector] = TASK_WORKFLOW_COMMANDS[request.operation];
+  if (selector !== null && request.args[1] !== selector) throw new Error('TASK_WORKFLOW_REQUEST_INVALID');
+  return request;
+}
+
+/** Preserve argv verbatim; the domain command owns option parsing and validation. */
+export function createTaskWorkflowRequest(
+  command: WorkflowCommand | undefined,
+  args: readonly string[],
+  taskId: string,
+  generation: string
+): TaskWorkflowRequest {
+  const operation = TASK_WORKFLOW_OPERATIONS.find((key) => {
+    const [name, selector] = TASK_WORKFLOW_COMMANDS[key];
+    return name === command && (selector === null || selector === args[1]);
+  });
+  if (!operation) throw new Error('TASK_WORKFLOW_OPERATION_UNSUPPORTED');
+  return validateTaskWorkflowRequest({ version: 1, id: randomUUID(), taskId, generation, operation, args: [...args] });
+}
+
+export function canonicalArtifactName(value: string): boolean {
+  return /^(?:analysis|plan|code|review-analysis|review-plan|review-code)(?:-r[1-9]\d*)?\.md$/u.test(value)
+    && path.basename(value) === value;
+}
+
+function assertTaskArtifactDirectory(directory: string): string {
+  const resolved = path.resolve(directory);
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(resolved);
+  } catch {
+    throw new SecureFileError('TASK_ARTIFACT_WRITE_DENIED', 'task directory is unavailable');
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new SecureFileError('TASK_ARTIFACT_WRITE_DENIED', 'task directory must be a real directory');
+  }
+  return resolved;
+}
+
+export async function readTaskArtifact(
+  taskDir: string,
+  input: Readonly<{
+    artifact: string;
+    expectedSha256?: string;
+  }>
+): Promise<Readonly<{ artifact: string; bytes: Buffer; sha256: string }>> {
+  if (!canonicalArtifactName(input.artifact)) throw new SecureFileError('TASK_ARTIFACT_WRITE_DENIED', 'artifact must be a canonical top-level basename');
+  const root = assertTaskArtifactDirectory(taskDir);
+  const candidate = path.join(root, input.artifact);
+  if (path.dirname(candidate) !== root) throw new SecureFileError('TASK_ARTIFACT_WRITE_DENIED', 'artifact escapes task directory');
+  const stable = await readStableFile(candidate, {
+    maxBytes: 1024 * 1024,
+    ...(input.expectedSha256 ? { expectedSha256: input.expectedSha256 } : {})
+  });
+  return { artifact: input.artifact, bytes: stable.bytes, sha256: stable.sha256 };
+}
+
+export async function writeTaskArtifact(
+  taskDir: string,
+  artifact: Readonly<{ artifact: string; bytes: Buffer; expectedSha256?: string }>
+): Promise<void> {
+  if (!canonicalArtifactName(artifact.artifact)) throw new SecureFileError('TASK_ARTIFACT_WRITE_DENIED', 'artifact must be a canonical top-level basename');
+  const root = assertTaskArtifactDirectory(taskDir);
+  const target = path.join(root, artifact.artifact);
+  if (path.dirname(target) !== root) throw new SecureFileError('TASK_ARTIFACT_WRITE_DENIED', 'artifact escapes task directory');
+  await writeAtomicFile(target, artifact.bytes, 0o600, artifact.expectedSha256);
+}

package/lib/sandbox/control/workflow-executor.ts

@@ -0,0 +1,102 @@
+import { TASK_WORKFLOW_COMMANDS } from '../../task/workflow-command.ts';
+
+import { parseArtifactCommand, executeArtifactCommand } from '../../task/artifact-command.ts';
+import { parseReviewCommand } from '../../task/review-command.ts';
+import { prepareLocalArtifact, commitLocalArtifactProvenance } from '../../task/local-artifact-finalization.ts';
+import { prepareReviewSummaryCandidate, commitReviewSummaryProvenance } from '../../task/review-finalization.ts';
+import { withTaskExecutionLock } from '../../task/task-execution-lock.ts';
+import { dispatchHostControlCommand } from '../../host-control/command.ts';
+import { assertSandboxTaskSource } from '../workspace-view.ts';
+import { appendDiagnosticAudit } from './audit.ts';
+import {
+  readTaskArtifact, writeTaskArtifact, type TaskWorkflowRequest
+} from './task-workflow.ts';
+import type { SandboxControlManifest } from './protocol.ts';
+import type { SandboxControlExecutionResult } from './executor.ts';
+import type { LifecycleRecoveryAttestationV1 } from '../../task/control-authority.ts';
+import { applyTaskEvent } from '../../task/events.ts';
+import { parseTaskEventRequest } from '../../internal/task-event.ts';
+
+function executionResult(result: Record<string, unknown>): SandboxControlExecutionResult {
+  return { exitCode: result.status === 'failed' || result.status === 'refused' ? 1 : 0, stdout: `${JSON.stringify(result)}\n`, stderr: '' };
+}
+
+/** The broker already authorized this host executor; domain operations own validation. */
+export async function executeTaskWorkflow(
+  manifest: SandboxControlManifest,
+  request: TaskWorkflowRequest,
+  lifecycleRecoveryAttestation: LifecycleRecoveryAttestationV1 | null = null
+): Promise<SandboxControlExecutionResult> {
+  let publicationStarted = false;
+  try {
+    const taskDir = assertSandboxTaskSource(manifest.repoRoot, request.taskId);
+    const [command] = TASK_WORKFLOW_COMMANDS[request.operation];
+    if (request.operation === 'event') {
+      const eventRequest = parseTaskEventRequest(request.args);
+      const boundEventRequest = lifecycleRecoveryAttestation && eventRequest.requestId === undefined
+        ? { ...eventRequest, requestId: lifecycleRecoveryAttestation.lifecycleRequestId }
+        : eventRequest;
+      const result = applyTaskEvent(boundEventRequest, {
+        repoRoot: manifest.repoRoot,
+        lifecycleRecoveryAttestation,
+        deferLifecycleRecoveryConsumption: true
+      });
+      return executionResult(result);
+    }
+    if (command !== 'task-artifact' && command !== 'task-review') {
+      publicationStarted = true;
+      // Inherit this executor's process group so its existing recovery owns the worker too.
+      const result = await dispatchHostControlCommand({
+        operation: command, payload: { workingDirectory: manifest.repoRoot, args: request.args }
+      });
+      return result;
+    }
+    const input = command === 'task-artifact' ? parseArtifactCommand(request.args) : parseReviewCommand(request.args);
+    if (command === 'task-artifact' && 'operation' in input && input.operation === 'inspect') {
+      return executionResult(executeArtifactCommand(input, { repoRoot: manifest.repoRoot }));
+    }
+    if ('operation' in input && (input.operation === 'init' || input.operation === 'repair')) {
+      return executionResult(executeArtifactCommand(input, { repoRoot: manifest.repoRoot, artifactDir: taskDir }));
+    }
+    return await withTaskExecutionLock(manifest.repoRoot, request.taskId, `sandbox-control.${request.operation}`, async () => {
+      const artifact = await readTaskArtifact(taskDir, { artifact: input.artifact });
+      const content = artifact.bytes.toString('utf8');
+      let result: Record<string, unknown>;
+      if ('operation' in input) {
+        const { family } = input;
+        if (family !== 'analysis' && family !== 'plan' && family !== 'code') throw new Error('ARTIFACT_IDENTITY_INVALID');
+        const local = { taskRef: request.taskId, family, artifact: input.artifact, repoRoot: manifest.repoRoot } as const;
+        const prepared = prepareLocalArtifact(local, content, lifecycleRecoveryAttestation ?? undefined);
+        if (prepared.result.status === 'failed') return executionResult(commitLocalArtifactProvenance(prepared));
+        publicationStarted = true;
+        await writeTaskArtifact(taskDir, {
+          artifact: artifact.artifact,
+          bytes: artifact.bytes,
+          expectedSha256: artifact.sha256
+        });
+        result = commitLocalArtifactProvenance(prepared);
+      } else {
+        if (input.overrideTicket) throw new Error('TASK_WORKFLOW_OVERRIDE_UNSUPPORTED');
+        const prepared = prepareReviewSummaryCandidate(input, content, { repoRoot: manifest.repoRoot });
+        if (input.dryRun || prepared.result.status === 'planned') return executionResult(prepared.result);
+        if (prepared.result.status === 'failed') return executionResult(commitReviewSummaryProvenance(prepared, manifest.repoRoot));
+        publicationStarted = true;
+        await writeTaskArtifact(taskDir, {
+          artifact: input.artifact,
+          bytes: Buffer.from(prepared.content, 'utf8'),
+          expectedSha256: artifact.sha256
+        });
+        result = commitReviewSummaryProvenance(prepared, manifest.repoRoot);
+      }
+      if (result.status !== 'failed') appendDiagnosticAudit(manifest, 'task-workflow-artifact-finalized', {
+        requestId: request.id, sandboxTaskId: request.taskId, workflowOperation: request.operation,
+        artifact: input.artifact, sha256: result.artifactSha256 as string, semanticDigest: result.semanticDigest as string
+      });
+      return executionResult({ ...result, changed: true });
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = (error as { code?: string })?.code ?? /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1] ?? 'TASK_WORKFLOW_REQUEST_INVALID';
+    return executionResult({ status: 'failed', changed: publicationStarted ? null : false, error: { code, message } });
+  }
+}