@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/sandbox/control/state.ts

@@ -1,3 +1,6 @@
+import { isCompletionEvidence, type CleanCompletionEvidence } from '../../task/orchestration.ts';
+import { parseControlOutput } from '../../task/control-recovery.ts';
+import { isRecoveryWarning } from '../../task/recovery-warning.ts';
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -12,6 +15,7 @@ import type {
   SandboxControlPayload,
   SandboxControlReservation,
   SandboxControlResultEvidence,
+  SandboxControlRecoveryWarning,
   SandboxControlStatus
 } from './protocol.ts';
 import {
@@ -101,6 +105,88 @@ 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;
+  warning?: SandboxControlRecoveryWarning | 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) ?? '';
+  const warning = isRecoveryWarning(nested.warning) ? nested.warning : 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,
+    ...(warning ? { warning } : {})
+  };
+}
+
+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.warning !== undefined && value.warning !== null && !isRecoveryWarning(value.warning)) {
+    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');

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,92 @@
+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, 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') {
+      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, recoveryId: input.recoveryId, lockAlreadyHeld: true } as const;
+        const prepared = prepareLocalArtifact(local, content, lifecycleRecoveryAttestation ?? undefined);
+        if (prepared.result.status === 'failed') return executionResult(commitLocalArtifactProvenance(prepared));
+        publicationStarted = true;
+        result = commitLocalArtifactProvenance(prepared);
+      } else {
+        if (input.overrideTicket) throw new Error('TASK_WORKFLOW_OVERRIDE_UNSUPPORTED');
+        const prepared = prepareReviewSummaryCandidate(input, content, { repoRoot: manifest.repoRoot, lockAlreadyHeld: true, startRecovery: true });
+        if (input.dryRun || prepared.result.status === 'planned') return executionResult(prepared.result);
+        if (prepared.result.status === 'failed') return executionResult(commitReviewSummaryProvenance(prepared, manifest.repoRoot));
+        publicationStarted = true;
+        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 } });
+  }
+}

package/lib/sandbox/index.ts

@@ -20,8 +20,7 @@ Commands:
   rm <branch | TASK-id> | --unbound | --purge
                                Remove one sandbox; use a full TASK-id for task-bound
                                cleanup and a branch for branch-only cleanup. --unbound
-                               removes completed task-bound and branch-only sandboxes;
-                               active, blocked, and archive tasks are protected.
+                               removes discovered task-bound and branch-only sandboxes.
   start [--recreate] <branch | TASK-id | N>
                                Verify or recover an existing sandbox container;
                                optionally replace only the container on failure

package/lib/sandbox/recovery.ts

@@ -60,9 +60,10 @@ import {
   type BrokerOwner
 } from './control/lifecycle.ts';
 import {
-  appendSandboxControlAudit,
   readSandboxControlStatus
 } from './control/state.ts';
+import { validateSandboxControlIdentity } from './control/identity-sentinel.ts';
+import { appendDiagnosticAudit as appendControlDiagnosticAudit } from './control/audit.ts';
 import { inspectSandboxControlContainer } from './control/container-identity.ts';
 import {
   SANDBOX_CONTROL_FUTURE_SKEW_MS,
@@ -224,6 +225,17 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
   const internalCli = path.resolve(directory, '..', '..', 'bin', `internal-cli${extension}`);
   const manifest = readSandboxControlManifest(manifestPath);
   const root = path.dirname(manifestPath);
+  const identity = validateSandboxControlIdentity({
+    publicStatusDir: manifest.publicStatusDir,
+    root,
+    mode: manifest.mode,
+    taskId: manifest.taskId,
+    generation: manifest.generation,
+    controlRootId: manifest.controlRootId
+  });
+  if (identity.state !== 'valid') {
+    throw new Error(`SANDBOX_CONTROL_IDENTITY_${identity.state.replaceAll('-', '_').toUpperCase()}`);
+  }
   if (isSandboxControlRootQuiescing(root)) throw new Error('SANDBOX_CONTROL_QUIESCING');
   const brokerPath = path.join(root, 'broker.json');
   let brokerSnapshot: string | null = null;
@@ -296,8 +308,8 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
       }
     }
     if (replacedBrokerRecord) {
-      appendSandboxControlAudit(manifest, 'broker-observed-crash');
-      appendSandboxControlAudit(manifest, 'broker-restart');
+      appendControlDiagnosticAudit(manifest, 'broker-observed-crash');
+      appendControlDiagnosticAudit(manifest, 'broker-restart');
     }
     child = spawn(
       process.execPath,
@@ -338,6 +350,17 @@ async function ensureSandboxControlBroker(params: {
   });
   if (!fs.existsSync(control.manifestPath)) return;
   const validatedManifest = readSandboxControlManifest(control.manifestPath);
+  const identity = validateSandboxControlIdentity({
+    publicStatusDir: validatedManifest.publicStatusDir,
+    root: control.root,
+    mode: validatedManifest.mode,
+    taskId: validatedManifest.taskId,
+    generation: validatedManifest.generation,
+    controlRootId: validatedManifest.controlRootId
+  });
+  if (identity.state !== 'valid') {
+    throw new Error(`SANDBOX_CONTROL_IDENTITY_${identity.state.replaceAll('-', '_').toUpperCase()}`);
+  }
   const containerObservation = await inspectSandboxControlContainer(validatedManifest);
   if (containerObservation.state === 'unknown') {
     throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${containerObservation.reason}`);
@@ -749,7 +772,7 @@ function expectedMounts(params: {
       ? {}
       : {
         runtimeDir: control.runtimeDir,
-        taskSources: taskSources.mountPaths,
+        taskSources: taskSources!.accessiblePaths,
         taskId: taskId!
       })
   }).map((mount) => ({
@@ -758,7 +781,7 @@ function expectedMounts(params: {
     hostPaths: mount.hostPaths,
     ...(taskSources !== null && taskId !== null
       && mount.containerPath === `/workspace/.agents/workspace/active/${taskId}`
-      ? { sourceAccessiblePaths: taskSources.accessiblePaths }
+      ? { sourceAccessiblePaths: taskSources!.accessiblePaths }
       : {}),
     expectedRW: !mount.readOnly
   }));