@fitlab-ai/agent-infra 0.9.8 → 0.9.10

package/lib/sandbox/control/executor.ts

@@ -4,8 +4,17 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { getProcessStartTime } from '../../server/process-state.ts';
 import { createTask } from '../../task/create-service.ts';
+import { applyTaskFinalization } from '../../task/finalization.ts';
+import { verifyTaskEvent } from '../../task/verification.ts';
 import { bindSandboxControlTask, type SandboxControlExecution, type SandboxControlManifest, type SandboxControlRequest } from './protocol.ts';
 import { atomicWriteJson, executionPath, terminateSandboxControlExecution } from './state.ts';
+import { computeLifecycleBuildIdentity } from '../../agent-clients/adapters/codex-lifecycle/build-identity.ts';
+import {
+  closeCodexControllerRegistration,
+  CodexControllerRegistrationError,
+  openCodexControllerRegistration,
+  resolveCodexControllerBinding
+} from './controller-registration.ts';
 
 export type SandboxControlExecutionResult = {
   exitCode: number;
@@ -132,7 +141,73 @@ function waitForGate(nonce: string, timeoutMs = 2_000): Promise<void> {
   });
 }
 
-function executeRequest(manifest: SandboxControlManifest, request: SandboxControlRequest): SandboxControlExecutionResult {
+function controllerFailure(error: unknown): SandboxControlExecutionResult {
+  const code = error instanceof CodexControllerRegistrationError
+    ? error.code
+    : /^([A-Z][A-Z0-9_]+)/u.exec(error instanceof Error ? error.message : String(error))?.[1]
+      ?? 'CODEX_SANDBOX_CONTROLLER_FAILED';
+  const message = error instanceof CodexControllerRegistrationError
+    ? error.message
+    : `${code}: controller operation failed; inspect the sandbox controller and rebuild the sandbox if needed`;
+  const payload = {
+    version: 1,
+    status: 'failed',
+    changed: false,
+    lease: null,
+    error: { code, message, retryable: false }
+  };
+  return { exitCode: 1, stdout: `${JSON.stringify(payload)}\n`, stderr: '' };
+}
+
+function orchestrationFailure(code: string, message: string): SandboxControlExecutionResult {
+  return {
+    exitCode: 1,
+    stdout: `${JSON.stringify({
+      status: 'failed', changed: false, taskId: null, run: null, next: null,
+      error: { code, message }
+    })}\n`,
+    stderr: ''
+  };
+}
+
+function finalizationResult(result: ReturnType<typeof applyTaskFinalization>): SandboxControlExecutionResult {
+  const payload = {
+    version: 1,
+    status: result.status,
+    changed: result.changed,
+    accepted: true,
+    result,
+    error: result.error
+  };
+  return {
+    exitCode: result.status === 'completed' ? 0 : result.status === 'blocked' ? 2 : 1,
+    stdout: `${JSON.stringify(payload)}\n`,
+    stderr: ''
+  };
+}
+
+function isCodexPrepare(args: readonly string[]): boolean {
+  if (args[1] !== 'prepare') return false;
+  const values: string[] = [];
+  for (let index = 2; index < args.length; index += 1) {
+    if (args[index] === '--client') values.push(args[index + 1] ?? '');
+    else if (args[index]?.startsWith('--client=')) values.push(args[index]!.slice('--client='.length));
+  }
+  return values.length === 1 && values[0] === 'codex';
+}
+
+type ExecuteRequestOptions = Readonly<{
+  buildIdentity?: typeof computeLifecycleBuildIdentity;
+  resolveControllerBinding?: typeof resolveCodexControllerBinding;
+  spawnDomain?: typeof spawnSync;
+}>;
+
+export function executeRequest(
+  manifest: SandboxControlManifest,
+  manifestPath: string,
+  request: SandboxControlRequest,
+  options: ExecuteRequestOptions = {}
+): SandboxControlExecutionResult {
   if (request.family === 'task-create') {
     const result = createTask(request.candidate, { repoRoot: manifest.repoRoot });
     return {
@@ -141,15 +216,104 @@ function executeRequest(manifest: SandboxControlManifest, request: SandboxContro
       stderr: ''
     };
   }
+  if (request.family === 'codex-controller') {
+    try {
+      if (request.command === 'verify') {
+        const binding = (options.resolveControllerBinding ?? resolveCodexControllerBinding)({
+          manifest,
+          manifestPath,
+          proof: request.controllerProof!,
+          buildIdentity: (options.buildIdentity ?? computeLifecycleBuildIdentity)(manifest.repoRoot)
+        });
+        return {
+          exitCode: 0,
+          stdout: `${JSON.stringify({
+            version: 1,
+            status: 'verified',
+            changed: false,
+            lease: null,
+            binding: {
+              taskId: manifest.taskId,
+              controlGeneration: binding.controlGeneration,
+              controllerInstanceDigest: binding.instanceDigest
+            },
+            error: null
+          })}\n`,
+          stderr: ''
+        };
+      }
+      const result = request.command === 'open'
+        ? openCodexControllerRegistration({
+            manifest,
+            manifestPath,
+            controllerProcess: request.controllerProcess!,
+            buildIdentity: (options.buildIdentity ?? computeLifecycleBuildIdentity)(manifest.repoRoot)
+          })
+        : closeCodexControllerRegistration({
+            manifest,
+            manifestPath,
+            proof: request.controllerProof!
+          });
+      return { exitCode: 0, stdout: `${JSON.stringify(result)}\n`, stderr: '' };
+    } catch (error) {
+      return controllerFailure(error);
+    }
+  }
+  if (request.family === 'task-finalization') {
+    return finalizationResult(applyTaskFinalization(
+      { taskRef: manifest.taskId!, intent: 'complete', agent: request.agent },
+      { repoRoot: manifest.repoRoot, preflight: (input, options) => verifyTaskEvent(
+        { ...input, event: 'complete-task.hard-preflight' }, options
+      ) }
+    ));
+  }
   const boundArgs = bindSandboxControlTask(request, manifest.taskId!);
-  if (request.family === 'task-orchestration') boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
-  const result = spawnSync(
+  let controllerBinding: Readonly<{
+    instanceDigest: string;
+    controlGeneration: string;
+  }> | null = null;
+  if (request.family === 'task-orchestration') {
+    if (isCodexPrepare(request.args)) {
+      if (!request.controllerProof) {
+        return orchestrationFailure(
+          'CODEX_SANDBOX_CONTROLLER_PROOF_REQUIRED',
+          'Codex prepare requires a current controller lease proof'
+        );
+      }
+      try {
+        controllerBinding = (options.resolveControllerBinding ?? resolveCodexControllerBinding)({
+          manifest,
+          manifestPath,
+          proof: request.controllerProof,
+          buildIdentity: (options.buildIdentity ?? computeLifecycleBuildIdentity)(manifest.repoRoot)
+        });
+      } catch (error) {
+        const code = error instanceof CodexControllerRegistrationError
+          ? error.code
+          : 'CODEX_SANDBOX_CONTROLLER_PROOF_INVALID';
+        return orchestrationFailure(code, `${code}: Codex controller proof was rejected`);
+      }
+    } else if (request.controllerProof !== null) {
+      return orchestrationFailure(
+        'CODEX_SANDBOX_CONTROLLER_PROOF_INVALID',
+        'Controller proof is only accepted for canonical Codex prepare'
+      );
+    }
+    boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
+  }
+  const result = (options.spawnDomain ?? spawnSync)(
     process.execPath,
     nodeEntryArgs(process.argv[1]!, [request.family, ...boundArgs]),
     {
       cwd: manifest.repoRoot,
       encoding: 'utf8',
-      env: { ...safeEnv(process.env), AGENT_INFRA_RUNTIME_DIR: manifest.runtimeDir }
+      env: {
+        ...safeEnv(process.env),
+        AGENT_INFRA_RUNTIME_DIR: manifest.runtimeDir,
+        ...(controllerBinding
+          ? { AGENT_INFRA_CONTROL_CONTROLLER_BINDING: JSON.stringify(controllerBinding) }
+          : {})
+      }
     }
   );
   return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
@@ -164,7 +328,7 @@ export async function runSandboxControlExecutor(requestPath: string, nonce: stri
   if (!manifestPath) throw new Error('SANDBOX_CONTROL_EXECUTOR_MANIFEST_MISSING');
   const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as SandboxControlManifest;
   if (fs.realpathSync.native(manifest.repoRoot) !== root) throw new Error('SANDBOX_CONTROL_EXECUTOR_ROOT_INVALID');
-  const result = executeRequest(manifest, request);
+  const result = executeRequest(manifest, manifestPath, request);
   process.stdout.write(result.stdout);
   process.stderr.write(result.stderr);
   process.exitCode = result.exitCode;

package/lib/sandbox/control/lifecycle.ts

@@ -105,7 +105,7 @@ async function waitForStartupTransition(
 ): Promise<void> {
   const transitionPath = path.join(root, BROKER_STARTING_FILE);
   const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
+  while (true) {
     const transition = readStartupOwner(transitionPath);
     if (!fs.existsSync(transitionPath)) return;
     if (transition && !ownerLive(transition.owner, identityProbe)) {
@@ -116,6 +116,7 @@ async function waitForStartupTransition(
       }
       continue;
     }
+    if (Date.now() >= deadline) break;
     await new Promise((resolve) => setTimeout(resolve, 25));
   }
   throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');

package/lib/sandbox/control/protocol.ts

@@ -1,12 +1,14 @@
 import { validateTaskCreateCandidate, type TaskCreateCandidateV1 } from '../../task/create.ts';
+import { normalizeAgentToken } from '../../agent-clients/tokens.ts';
 import type { ProcessIdentity } from '../../server/process-state.ts';
+import type { CodexControllerLeaseProofV1 } from './controller-registration.ts';
 
 export const SANDBOX_CONTROL_MAX_BYTES = 64 * 1024;
 export const SANDBOX_CONTROL_ADMISSION_WINDOW_MS = 2_000;
 export const SANDBOX_CONTROL_STATUS_INTERVAL_MS = 250;
 export const SANDBOX_CONTROL_STATUS_STALE_MS = 1_500;
 export const SANDBOX_CONTROL_FUTURE_SKEW_MS = 1_000;
-export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-create'] as const;
+export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-finalization', 'task-create', 'codex-controller'] as const;
 export type SandboxControlTimingPolicy = Readonly<{
   controlTickMs: number;
   parkedBindingInitialMs: number;
@@ -43,15 +45,25 @@ export type SandboxControlBrokerOwner = ProcessIdentity & Readonly<{
   generation: string;
 }>;
 type RequestBase = Readonly<{
-  version: 2; id: string; token: string; generation: string; issuedAt: number; expiresAt: number;
+  version: 3; id: string; token: string; generation: string; issuedAt: number; expiresAt: number;
+  controllerProcess: ProcessIdentity | null;
+  controllerProof: CodexControllerLeaseProofV1 | null;
 }>;
 export type SandboxTaskCommandRequest = RequestBase & Readonly<{
   family: 'task-lifecycle' | 'task-orchestration'; args: string[];
 }>;
+export type SandboxTaskFinalizationRequest = RequestBase & Readonly<{
+  family: 'task-finalization'; operation: 'complete'; agent: string; args: [];
+}>;
 export type SandboxTaskCreateRequest = RequestBase & Readonly<{
   family: 'task-create'; candidate: TaskCreateCandidateV1;
 }>;
-export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskCreateRequest;
+export type SandboxCodexControllerRequest = RequestBase & Readonly<{
+  family: 'codex-controller';
+  command: 'open' | 'close' | 'verify';
+  args: [];
+}>;
+export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskFinalizationRequest | SandboxTaskCreateRequest | SandboxCodexControllerRequest;
 export type SandboxControlError = Readonly<{ code: string; message: string; retryable: boolean }>;
 export type SandboxControlResponse = Readonly<{
   version: 2; id: string; phase: 'accepted' | 'completed' | 'rejected'; exitCode: number | null;
@@ -101,7 +113,7 @@ export function validateSandboxControlRequest(
   }
   const request = value as Record<string, unknown>;
   if (
-    request.version !== 2 || typeof request.id !== 'string'
+    request.version !== 3 || typeof request.id !== 'string'
     || !/^[a-f0-9-]{16,64}$/.test(request.id) || request.token !== manifest.token
     || typeof request.family !== 'string' || !isSandboxControlFamily(request.family)
     || !Number.isSafeInteger(request.issuedAt) || !Number.isSafeInteger(request.expiresAt)
@@ -120,13 +132,47 @@ export function validateSandboxControlRequest(
     fail('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit');
   }
   if (request.family === 'task-create') {
-    const expected = ['candidate', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+    const expected = ['candidate', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
     if (Object.keys(request).sort().join(',') !== expected.sort().join(',')) {
       fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
     }
+    if (request.controllerProcess !== null || request.controllerProof !== null) {
+      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-create cannot carry controller authority');
+    }
     return { ...request, candidate: validateTaskCreateCandidate(request.candidate) } as SandboxTaskCreateRequest;
   }
-  const expected = ['args', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+  if (request.family === 'codex-controller') {
+    const expected = ['args', 'command', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+    if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
+      || !Array.isArray(request.args) || request.args.length !== 0
+      || !['open', 'close', 'verify'].includes(request.command as string)
+      || !validControllerProcess(request.controllerProcess)
+      || (request.command === 'open' && request.controllerProof !== null)
+      || (request.command !== 'open' && !validControllerProof(request.controllerProof))
+      || (request.command === 'verify'
+        && JSON.stringify(request.controllerProcess) !== JSON.stringify((request.controllerProof as CodexControllerLeaseProofV1).controllerProcess))) {
+      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller request schema is invalid');
+    }
+    if (manifest.mode !== 'task-bound' || !manifest.taskId) {
+      fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot register a Codex controller');
+    }
+    return request as SandboxCodexControllerRequest;
+  }
+  if (request.family === 'task-finalization') {
+    const expected = ['agent', 'args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'operation', 'token', 'version'];
+    if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
+      || request.operation !== 'complete'
+      || !Array.isArray(request.args) || request.args.length !== 0
+      || typeof request.agent !== 'string' || normalizeAgentToken(request.agent) !== request.agent
+      || request.controllerProcess !== null || request.controllerProof !== null) {
+      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-finalization request schema or authorization is invalid');
+    }
+    if (manifest.mode !== 'task-bound' || !manifest.taskId) {
+      fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot finalize tasks');
+    }
+    return request as SandboxTaskFinalizationRequest;
+  }
+  const expected = ['args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
   if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
     || !Array.isArray(request.args) || !request.args.every((arg) => typeof arg === 'string')) {
     fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
@@ -141,15 +187,42 @@ export function validateSandboxControlRequest(
     && request.args.some((arg) => arg === '--git-worktree-root' || arg.startsWith('--git-worktree-root='))) {
     fail('SANDBOX_CONTROL_REQUEST_INVALID', 'worktree binding is reserved for the control broker');
   }
+  if (request.controllerProcess !== null
+    || (request.controllerProof !== null && !validControllerProof(request.controllerProof))) {
+    fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller authority is invalid');
+  }
+  if (request.family !== 'task-orchestration' && request.controllerProof !== null) {
+    fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller proof is not allowed for this family');
+  }
   return request as SandboxTaskCommandRequest;
 }
 
 export function bindSandboxControlTask(request: SandboxControlRequest, taskId: string): string[] {
-  if (request.family === 'task-create') fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-create requests do not bind a current task');
+  if (request.family === 'task-create' || request.family === 'codex-controller' || request.family === 'task-finalization') {
+    fail('SANDBOX_CONTROL_REQUEST_INVALID', `${request.family} requests do not bind a current task`);
+  }
   if (request.args.length === 0) fail('SANDBOX_CONTROL_REQUEST_INVALID', 'command arguments are required');
   return [taskId, ...request.args.slice(1)];
 }
 
+function validControllerProcess(value: unknown): value is ProcessIdentity {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const processValue = value as Record<string, unknown>;
+  return Object.keys(processValue).sort().join(',') === 'pid,startTime'
+    && Number.isSafeInteger(processValue.pid) && (processValue.pid as number) > 0
+    && Number.isSafeInteger(processValue.startTime) && (processValue.startTime as number) >= 0;
+}
+
+function validControllerProof(value: unknown): value is CodexControllerLeaseProofV1 {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proof = value as Record<string, unknown>;
+  return Object.keys(proof).sort().join(',') === 'controllerProcess,leaseId,leaseSecret,version'
+    && proof.version === 1
+    && typeof proof.leaseId === 'string' && /^[a-f0-9]{64}$/u.test(proof.leaseId)
+    && typeof proof.leaseSecret === 'string' && /^[a-f0-9]{64}$/u.test(proof.leaseSecret)
+    && validControllerProcess(proof.controllerProcess);
+}
+
 export function controlError(error: unknown): SandboxControlError {
   if (error instanceof SandboxControlProtocolError) {
     return { code: error.code, message: error.message, retryable: error.retryable };

package/lib/sandbox/index.ts

@@ -15,9 +15,11 @@ Commands:
   rebuild [--quiet] [--refresh]
                                Rebuild the sandbox image (--refresh pulls base + tools)
   refresh                      Sync host Claude Code credentials to all sandbox copies
-  rm <branch> | --unbound | --purge
-                               Remove one sandbox, all sandboxes not bound to an
-                               active task (--unbound), or tear down everything (--purge)
+  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.
   start [--recreate] <branch | TASK-id | N>
                                Verify or recover an existing sandbox container;
                                optionally replace only the container on failure

package/lib/sandbox/managed-fs.ts

@@ -36,6 +36,11 @@ export function removeWorktreeDir(
     throw new Error(`Worktree permit target mismatch: ${dir}`);
   }
   verifyWorktreePermit(permit);
+  if (permit.snapshot.source === 'recovered') {
+    removeManagedDir(worktreeBase, dir);
+    runSafeFn('git', ['-C', repoRoot, 'worktree', 'prune']);
+    return;
+  }
   try {
     runFn('git', ['-C', repoRoot, 'worktree', 'remove', dir, '--force']);
   } catch (error) {

package/lib/sandbox/task-resolver.ts

@@ -5,7 +5,14 @@ import { isRemovedHashShortIdInput } from '../task/short-id.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const SHORT_ID_RE = /^\d+$/;
-const WORKSPACE_DIRS = ['active', 'completed', 'blocked', 'archive'];
+export const TASK_WORKSPACE_STATES = ['active', 'completed', 'blocked', 'archive'] as const;
+export type TaskWorkspaceState = typeof TASK_WORKSPACE_STATES[number];
+export type TaskWorkspace = Readonly<{
+  taskId: string;
+  branch: string;
+  state: TaskWorkspaceState;
+  taskMd: string;
+}>;
 
 function resolveShortIdStrict(arg: string, repoRoot: string): string {
   const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
@@ -27,16 +34,30 @@ function stripQuotes(value: string): string {
   return value.replace(/^(["'])(.*)\1$/, '$2');
 }
 
-function readTaskContent(repoRoot: string, taskId: string): string {
-  for (const dir of WORKSPACE_DIRS) {
-    const taskPath = path.join(repoRoot, '.agents', 'workspace', dir, taskId, 'task.md');
+function readTaskContent(repoRoot: string, taskId: string): { content: string; state: TaskWorkspaceState; taskMd: string } {
+  for (const state of TASK_WORKSPACE_STATES) {
+    const taskPath = path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
     if (fs.existsSync(taskPath)) {
-      return fs.readFileSync(taskPath, 'utf8');
+      return { content: fs.readFileSync(taskPath, 'utf8'), state, taskMd: taskPath };
     }
   }
   throw new Error(`Task not found: ${taskId}`);
 }
 
+function taskWorkspaceCandidates(repoRoot: string, taskId: string): TaskWorkspace[] {
+  return TASK_WORKSPACE_STATES.flatMap((state) => {
+    const taskMd = path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
+    if (!fs.existsSync(taskMd)) return [];
+    const content = fs.readFileSync(taskMd, 'utf8');
+    return [{
+      taskId,
+      branch: resolveBranchFromTaskContent(content, taskId),
+      state,
+      taskMd
+    }];
+  });
+}
+
 function resolveBranchFromTaskContent(content: string, taskId: string): string {
   const frontmatterBranch = content.match(/^branch:\s*(.+)$/m);
   if (frontmatterBranch?.[1]?.trim()) {
@@ -57,12 +78,42 @@ export function resolveTaskBranch(arg: string, repoRoot: string): string {
   }
   if (SHORT_ID_RE.test(arg)) {
     const taskId = resolveShortIdStrict(arg, repoRoot);
-    const content = readTaskContent(repoRoot, taskId);
+    const { content } = readTaskContent(repoRoot, taskId);
     return resolveBranchFromTaskContent(content, taskId);
   }
   if (!TASK_ID_RE.test(arg)) {
     return arg;
   }
-  const content = readTaskContent(repoRoot, arg);
+  const { content } = readTaskContent(repoRoot, arg);
   return resolveBranchFromTaskContent(content, arg);
 }
+
+export function resolveTaskWorkspace(taskId: string, repoRoot: string): TaskWorkspace {
+  if (!TASK_ID_RE.test(taskId)) throw new Error(`Invalid task id: ${taskId}`);
+  const matches = taskWorkspaceCandidates(repoRoot, taskId);
+  if (matches.length === 0) throw new Error(`Task not found: ${taskId}`);
+  if (matches.length !== 1) {
+    throw new Error(
+      `SANDBOX_TASK_STATE_AMBIGUOUS: task ${taskId} exists in ${matches.map((match) => match.state).join(', ')}`
+    );
+  }
+  return matches[0]!;
+}
+
+export function listTaskWorkspaces(repoRoot: string, state: TaskWorkspaceState): TaskWorkspace[] {
+  const stateRoot = path.join(repoRoot, '.agents', 'workspace', state);
+  if (!fs.existsSync(stateRoot)) return [];
+  return fs.readdirSync(stateRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && TASK_ID_RE.test(entry.name))
+    .flatMap((entry) => {
+      const taskMd = path.join(stateRoot, entry.name, 'task.md');
+      if (!fs.existsSync(taskMd)) return [];
+      const content = fs.readFileSync(taskMd, 'utf8');
+      return [{
+        taskId: entry.name,
+        branch: resolveBranchFromTaskContent(content, entry.name),
+        state,
+        taskMd
+      }];
+    });
+}

package/lib/sandbox/workspace-identity.ts

@@ -1,6 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { isRemovedHashShortIdInput } from '../task/short-id.ts';
+import {
+  resolveTaskWorkspace,
+  type TaskWorkspaceState
+} from './task-resolver.ts';
 
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const SHORT_ID_RE = /^\d+$/;
@@ -9,6 +13,17 @@ export type SandboxWorkspaceIdentity =
   | Readonly<{ mode: 'task-bound'; taskId: string; shortId: string }>
   | Readonly<{ mode: 'branch-only' }>;
 
+export type SandboxWorkspaceKey =
+  | Readonly<{ mode: 'task-bound'; taskId: string }>
+  | Readonly<{ mode: 'branch-only' }>;
+
+export type SandboxCleanupTarget = Readonly<{
+  requestedRef: string;
+  branch: string;
+  workspace: SandboxWorkspaceKey;
+  taskState: TaskWorkspaceState | 'branch-only';
+}>;
+
 export type SandboxContainerWorkspaceIdentity =
   | Readonly<{ mode: 'task-bound'; taskId: string }>
   | Readonly<{ mode: 'branch-only' }>
@@ -101,6 +116,39 @@ export function resolveSandboxTarget(requestedRef: string, repoRoot: string): Sa
   return { requestedRef, branch: requestedRef, workspace: { mode: 'branch-only' } };
 }
 
+export function resolveSandboxCleanupTarget(
+  requestedRef: string,
+  repoRoot: string,
+  options: Readonly<{ allowProtected?: boolean }> = {}
+): SandboxCleanupTarget {
+  if (isRemovedHashShortIdInput(requestedRef)) {
+    throw new Error(`Invalid task short id '${requestedRef}': task short ids must use bare digits`);
+  }
+
+  if (TASK_ID_RE.test(requestedRef)) {
+    const task = resolveTaskWorkspace(requestedRef, repoRoot);
+    if (!options.allowProtected && (task.state === 'blocked' || task.state === 'archive')) {
+      throw new Error(`SANDBOX_CLEANUP_STATE_UNSUPPORTED: task ${requestedRef} is ${task.state}`);
+    }
+    return {
+      requestedRef,
+      branch: task.branch,
+      workspace: { mode: 'task-bound', taskId: task.taskId },
+      taskState: task.state
+    };
+  }
+
+  const target = resolveSandboxTarget(requestedRef, repoRoot);
+  return {
+    requestedRef,
+    branch: target.branch,
+    workspace: target.workspace.mode === 'task-bound'
+      ? { mode: 'task-bound', taskId: target.workspace.taskId }
+      : { mode: 'branch-only' },
+    taskState: target.workspace.mode === 'task-bound' ? 'active' : 'branch-only'
+  };
+}
+
 export function parseSandboxWorkspaceIdentity(
   labels: Readonly<Record<string, string>>,
   keys: Readonly<{ mode: string; taskId: string }>
@@ -115,8 +163,8 @@ export function parseSandboxWorkspaceIdentity(
 }
 
 export function sameSandboxWorkspaceIdentity(
-  left: SandboxWorkspaceIdentity | SandboxContainerWorkspaceIdentity,
-  right: SandboxWorkspaceIdentity | SandboxContainerWorkspaceIdentity
+  left: SandboxWorkspaceIdentity | SandboxWorkspaceKey | SandboxContainerWorkspaceIdentity,
+  right: SandboxWorkspaceIdentity | SandboxWorkspaceKey | SandboxContainerWorkspaceIdentity
 ): boolean {
   return left.mode === right.mode
     && (left.mode !== 'task-bound' || (right.mode === 'task-bound' && left.taskId === right.taskId));

package/lib/sandbox/workspace-view.ts

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
-import type { SandboxWorkspaceIdentity } from './workspace-identity.ts';
+import type { SandboxWorkspaceIdentity, SandboxWorkspaceKey } from './workspace-identity.ts';
 import type { SandboxControlManifest } from './control/protocol.ts';
 
 export type SandboxWorkspaceView = Readonly<{
@@ -30,7 +30,7 @@ export function sandboxWorkspaceViewPaths(params: Readonly<{
   base: string;
   project: string;
   container: string;
-  identity: SandboxWorkspaceIdentity;
+  identity: SandboxWorkspaceIdentity | SandboxWorkspaceKey;
 }>): SandboxWorkspaceView {
   const identityKey = params.identity.mode === 'task-bound'
     ? `task-bound:${params.identity.taskId}`
@@ -60,7 +60,7 @@ export function sandboxControlPaths(params: Readonly<{
   base: string;
   project: string;
   container: string;
-  identity: SandboxWorkspaceIdentity;
+  identity: SandboxWorkspaceIdentity | SandboxWorkspaceKey;
 }>): Readonly<{ root: string; channelDir: string; statusDir: string; processingDir: string; runtimeDir: string; manifestPath: string }> {
   const identityKey = params.identity.mode === 'task-bound'
     ? `task-bound:${params.identity.taskId}`