@fitlab-ai/agent-infra 0.11.13 → 0.11.15

package/lib/sandbox/mounts.ts

@@ -15,6 +15,89 @@ export type SandboxBindMountDeclaration = {
   readOnly: boolean;
 };
 
+function workspaceStateMounts(workspaceViewRoot: string, taskBound: boolean): SandboxBindMountDeclaration[] {
+  return sandboxWorkspaceViewStatePaths(workspaceViewRoot)
+    // The writable completed-task mount below is nested under this path. Keep
+    // the worktree target visible so Docker can mount it without creating a
+    // mountpoint inside a read-only parent bind mount.
+    .filter(({ state }) => !(taskBound && state === 'completed'))
+    .map(({ state, hostPath }) => taskBound && state === 'active'
+      ? {
+          hostPaths: [path.join(hostPath, '.short-ids.json')],
+          containerPath: '/workspace/.agents/workspace/active/.short-ids.json',
+          readOnly: true
+        }
+      : {
+          hostPaths: [hostPath],
+          containerPath: path.posix.join('/workspace/.agents/workspace', state),
+          readOnly: true
+        }
+    );
+}
+
+function assertGitMetadataPair(overrides: {
+  gitCommonDir?: string;
+  worktreeGitFile?: string;
+}): void {
+  if (Boolean(overrides.gitCommonDir) !== Boolean(overrides.worktreeGitFile)) {
+    throw new Error('SANDBOX_GIT_METADATA_INCOMPLETE');
+  }
+}
+
+function gitCommonMount(gitCommonDir?: string): SandboxBindMountDeclaration[] {
+  return gitCommonDir ? [{ hostPaths: [gitCommonDir], containerPath: SANDBOX_GIT_COMMON_DIR, readOnly: false }] : [];
+}
+
+function worktreeGitFileMount(worktreeGitFile?: string): SandboxBindMountDeclaration[] {
+  return worktreeGitFile ? [{ hostPaths: [worktreeGitFile], containerPath: '/workspace/.git', readOnly: true }] : [];
+}
+
+function taskWorkspaceMounts(taskSources: string[], taskBound: boolean, overrides: {
+  taskId?: string;
+  completedTaskSource?: string;
+}): SandboxBindMountDeclaration[] {
+  if (!taskBound) return [];
+  const taskId = overrides.taskId!;
+  const mounts: SandboxBindMountDeclaration[] = [{
+    hostPaths: taskSources,
+    containerPath: path.posix.join('/workspace/.agents/workspace/active', taskId),
+    readOnly: false
+  }];
+  if (overrides.completedTaskSource) mounts.push({
+    hostPaths: [overrides.completedTaskSource],
+    containerPath: path.posix.join('/workspace/.agents/workspace/completed', taskId),
+    readOnly: false
+  });
+  return mounts;
+}
+
+function sharedMounts(config: Pick<SandboxConfig, 'repoRoot' | 'worktreeBase' | 'shareBase' | 'shellConfigBase'>, branch: string,
+  shellConfigHostDir?: string): SandboxBindMountDeclaration[] {
+  return [{
+    hostPaths: [shareCommonDir(config)], containerPath: '/share/common', readOnly: false
+  }, {
+    hostPaths: [shareBranchDir(config, branch)], containerPath: '/share/branch', readOnly: false
+  }, {
+    hostPaths: shellConfigHostDir ? [shellConfigHostDir] : shellConfigDirCandidates(config, branch),
+    containerPath: '/home/devuser/.host-shell-config', readOnly: true
+  }];
+}
+
+function controlMounts(overrides: { controlDir: string; controlRootDir?: string; controlStatusDir: string; runtimeDir?: string }, taskBound: boolean): SandboxBindMountDeclaration[] {
+  const mounts: SandboxBindMountDeclaration[] = [{
+    hostPaths: [overrides.controlStatusDir], containerPath: '/run/agent-infra/control-status', readOnly: true
+  }, {
+    hostPaths: [overrides.controlDir], containerPath: '/run/agent-infra/control', readOnly: false
+  }];
+  if (taskBound && overrides.runtimeDir) mounts.push({
+    hostPaths: [overrides.runtimeDir], containerPath: '/run/agent-infra/runtime', readOnly: false
+  });
+  if (taskBound && overrides.controlRootDir) mounts.push({
+    hostPaths: [overrides.controlRootDir], containerPath: '/run/agent-infra/control-root', readOnly: false
+  });
+  return mounts;
+}
+
 export function sandboxCoreBindMounts(
   config: Pick<
     SandboxConfig,
@@ -26,6 +109,7 @@ export function sandboxCoreBindMounts(
     shellConfigHostDir?: string;
     workspaceViewRoot: string;
     controlDir: string;
+    controlRootDir?: string;
     controlStatusDir: string;
     gitCommonDir?: string;
     worktreeGitFile?: string;
@@ -37,30 +121,10 @@ export function sandboxCoreBindMounts(
 ): SandboxBindMountDeclaration[] {
   const taskSources = overrides.taskSources ?? [];
   const taskBound = Boolean(taskSources.length > 0 && overrides.taskId);
-  const workspaceMounts = sandboxWorkspaceViewStatePaths(overrides.workspaceViewRoot).map(
-    ({ state, hostPath }) => taskBound && state === 'active'
-      ? {
-          hostPaths: [path.join(hostPath, '.short-ids.json')],
-          containerPath: '/workspace/.agents/workspace/active/.short-ids.json',
-          readOnly: true
-        }
-      : {
-          hostPaths: [hostPath],
-          containerPath: path.posix.join('/workspace/.agents/workspace', state),
-          readOnly: true
-        }
-  );
-  if (Boolean(overrides.gitCommonDir) !== Boolean(overrides.worktreeGitFile)) {
-    throw new Error('SANDBOX_GIT_METADATA_INCOMPLETE');
-  }
-  const gitCommonMount = overrides.gitCommonDir
-    ? { hostPaths: [overrides.gitCommonDir], containerPath: SANDBOX_GIT_COMMON_DIR, readOnly: false }
-    : null;
-  const worktreeGitFileMount = overrides.worktreeGitFile
-    ? { hostPaths: [overrides.worktreeGitFile], containerPath: '/workspace/.git', readOnly: true }
-    : null;
+  assertGitMetadataPair(overrides);
+  if (taskBound && !overrides.controlRootDir) throw new Error('SANDBOX_CONTROL_ROOT_MISSING');
   const mounts: SandboxBindMountDeclaration[] = [
-    ...(gitCommonMount ? [gitCommonMount] : []),
+    ...gitCommonMount(overrides.gitCommonDir),
     {
       hostPaths: overrides.worktree
         ? [overrides.worktree]
@@ -68,58 +132,11 @@ export function sandboxCoreBindMounts(
       containerPath: '/workspace',
       readOnly: false
     },
-    ...(worktreeGitFileMount ? [worktreeGitFileMount] : []),
-    ...workspaceMounts,
+    ...worktreeGitFileMount(overrides.worktreeGitFile),
+    ...workspaceStateMounts(overrides.workspaceViewRoot, taskBound),
+    ...taskWorkspaceMounts(taskSources, taskBound, overrides),
+    ...sharedMounts(config, branch, overrides.shellConfigHostDir),
+    ...controlMounts(overrides, taskBound)
   ];
-  if (taskBound) {
-    const taskMountPath = path.posix.join('/workspace/.agents/workspace/active', overrides.taskId!);
-    mounts.push({
-      hostPaths: taskSources,
-      containerPath: taskMountPath,
-      readOnly: false
-    });
-    if (overrides.completedTaskSource) {
-      mounts.push({
-        hostPaths: [overrides.completedTaskSource],
-        containerPath: path.posix.join('/workspace/.agents/workspace/completed', overrides.taskId!),
-        readOnly: false
-      });
-    }
-  }
-  mounts.push(
-    {
-      hostPaths: [shareCommonDir(config)],
-      containerPath: '/share/common',
-      readOnly: false
-    },
-    {
-      hostPaths: [shareBranchDir(config, branch)],
-      containerPath: '/share/branch',
-      readOnly: false
-    },
-    {
-      hostPaths: overrides.shellConfigHostDir
-        ? [overrides.shellConfigHostDir]
-        : shellConfigDirCandidates(config, branch),
-      containerPath: '/home/devuser/.host-shell-config',
-      readOnly: true
-    }
-  );
-  mounts.push({
-    hostPaths: [overrides.controlStatusDir],
-    containerPath: '/run/agent-infra/control-status',
-    readOnly: true
-  }, {
-    hostPaths: [overrides.controlDir],
-    containerPath: '/run/agent-infra/control',
-    readOnly: false
-  });
-  if (taskBound && overrides.runtimeDir) {
-    mounts.push({
-      hostPaths: [overrides.runtimeDir],
-      containerPath: '/run/agent-infra/runtime',
-      readOnly: false
-    });
-  }
   return mounts;
 }

package/lib/sandbox/recovery.ts

@@ -342,7 +342,6 @@ async function ensureSandboxControlBroker(params: {
 }): Promise<void> {
   const control = sandboxControlPaths({
     base: params.config.controlBase ?? path.join(params.config.home, '.agent-infra', 'sandbox-control'),
-    repoRoot: params.config.repoRoot,
     project: params.config.project,
     container: params.container,
     identity: params.workspace
@@ -753,7 +752,6 @@ function expectedMounts(params: {
   });
   const control = sandboxControlPaths({
     base: config.controlBase ?? path.join(config.home, '.agent-infra', 'sandbox-control'),
-    repoRoot: config.repoRoot,
     project: config.project,
     container: params.container,
     identity: params.workspace
@@ -778,6 +776,7 @@ function expectedMounts(params: {
       }),
     workspaceViewRoot: view.root,
     controlDir: control.channelDir,
+    ...(params.workspace.mode === 'task-bound' ? { controlRootDir: control.root } : {}),
     controlStatusDir: control.statusDir,
     ...(taskSources === null
       ? {}
@@ -1296,7 +1295,7 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
       let completedReentry: { manifest: SandboxControlManifest; evidence: Awaited<ReturnType<typeof prepareCompletedReentry>> } | null = null;
       if (params.reentry === 'completed' && params.workspace?.mode === 'task-bound') {
         const control = sandboxControlPaths({
-          base: params.config.controlBase, repoRoot: params.config.repoRoot, project: params.config.project,
+          base: params.config.controlBase, project: params.config.project,
           container: params.row.name, identity: params.workspace
         });
         const manifest = readSandboxControlManifest(control.manifestPath);

package/lib/sandbox/removal.ts

@@ -829,7 +829,7 @@ function resolveRmTarget(
     ? matchedContainers
     : [...new Set([...containerNameCandidates(config, effectiveBranch), ...matchedContainers])];
   const controlRoots = containers.flatMap((container) => identities.map((identity) => sandboxControlPaths({
-    base: config.controlBase, repoRoot: config.repoRoot, project: config.project, container, identity
+    base: config.controlBase, project: config.project, container, identity
   }).root));
   const workspaceViewRoots = containers.flatMap((container) => identities.map((identity) => sandboxWorkspaceViewPaths({
     base: config.workspaceViewBase, project: config.project, container, identity
@@ -1083,6 +1083,19 @@ async function rmPurgeCore(
   const containers = runEngine(engine, 'docker', [
     'ps', '-a', '--filter', `label=${sandboxLabel(config)}`, '--format', '{{.Names}}'
   ]).split('\n').filter(Boolean);
+  const controlRoots = rows.flatMap((row) => {
+    if (!row.branch) return [];
+    const identity = row.workspaceMode === 'task-bound' && row.taskId
+      ? { mode: 'task-bound' as const, taskId: row.taskId }
+      : row.workspaceMode === 'branch-only'
+        ? { mode: 'branch-only' as const }
+        : null;
+    if (!identity) return [];
+    return [sandboxControlPaths({
+      base: config.controlBase, project: config.project,
+      container: row.name, identity
+    }).root];
+  });
   const completedTaskIds = [...new Set(rows
     .filter((row) => row.workspaceMode === 'task-bound' && row.taskId)
     .map((row) => row.taskId!))];
@@ -1115,9 +1128,8 @@ async function rmPurgeCore(
     if (!isCancel(selected) && selected) fs.rmSync(config.shareBase, { recursive: true, force: true });
     else cleanupCompleted = false;
   }
-  for (const base of [config.workspaceViewBase, config.controlBase]) {
-    fs.rmSync(path.join(base, config.project), { recursive: true, force: true });
-  }
+  fs.rmSync(path.join(config.workspaceViewBase, config.project), { recursive: true, force: true });
+  for (const root of new Set(controlRoots)) fs.rmSync(root, { recursive: true, force: true });
   if (cleanupCompleted) {
     for (const taskId of completedTaskIds) releaseStaleShortIdRegistry(config.repoRoot, taskId);
   }

package/lib/sandbox/workspace-identity.ts

@@ -1,8 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { isRemovedHashShortIdInput } from '../task/short-id.ts';
-import { resolveTaskRef } from '../task/resolve-ref.ts';
 import {
+  configuredShortIdLength,
+  inspectShortIdRegistry,
+  isRemovedHashShortIdInput,
+  normalizeShortIdInput
+} from '../task/short-id.ts';
+import {
+  TASK_WORKSPACE_STATES,
+  listTaskWorkspaces,
   resolveTaskWorkspace,
   type TaskWorkspaceState
 } from './task-resolver.ts';
@@ -79,10 +85,29 @@ function taskIdentity(repoRoot: string, taskId: string, registry: Record<string,
 
 function cleanupTaskId(requestedRef: string, repoRoot: string): string | null {
   if (TASK_ID_RE.test(requestedRef)) return requestedRef;
-  if (!SHORT_ID_RE.test(requestedRef)) return null;
-  const task = resolveTaskRef(requestedRef, { repoRoot });
-  if (!task.ok) throw new Error(task.message);
-  return task.taskId;
+  const shortIdLength = configuredShortIdLength(repoRoot);
+  const normalized = normalizeShortIdInput(requestedRef, { shortIdLength });
+  if (normalized.kind === 'error') throw new Error(normalized.message);
+  if (normalized.kind !== 'shortId') return null;
+
+  const registry = inspectShortIdRegistry(repoRoot, shortIdLength);
+  if (registry.status !== 'valid') throw new Error(registry.error.message);
+  const match = [...registry.shortIds].find(([, shortId]) => shortId === normalized.value);
+  if (!match) {
+    throw new Error(`Short id '${normalized.value}' not found in active task registry`);
+  }
+  return match[0];
+}
+
+function cleanupTaskIdByBranch(requestedRef: string, repoRoot: string): string | null {
+  const taskIds = new Set(TASK_WORKSPACE_STATES
+    .flatMap((state) => listTaskWorkspaces(repoRoot, state))
+    .filter((task) => task.branch === requestedRef)
+    .map((task) => task.taskId));
+  if (taskIds.size > 1) {
+    throw new Error(`SANDBOX_TASK_IDENTITY_AMBIGUOUS: branch '${requestedRef}' is bound to multiple tasks`);
+  }
+  return taskIds.values().next().value ?? null;
 }
 
 export function resolveSandboxTarget(requestedRef: string, repoRoot: string): SandboxTarget {
@@ -139,7 +164,8 @@ export function resolveSandboxCleanupTarget(
     throw new Error(`Invalid task short id '${requestedRef}': task short ids must use bare digits`);
   }
 
-  const taskId = cleanupTaskId(requestedRef, repoRoot);
+  const taskId = cleanupTaskId(requestedRef, repoRoot)
+    ?? cleanupTaskIdByBranch(requestedRef, repoRoot);
   if (taskId) {
     let task: ReturnType<typeof resolveTaskWorkspace>;
     try {
@@ -166,14 +192,11 @@ export function resolveSandboxCleanupTarget(
     };
   }
 
-  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'
+    branch: requestedRef,
+    workspace: { mode: 'branch-only' },
+    taskState: 'branch-only'
   };
 }
 

package/lib/sandbox/workspace-view.ts

@@ -4,7 +4,6 @@ import path from 'node:path';
 import type { SandboxWorkspaceIdentity, SandboxWorkspaceKey } from './workspace-identity.ts';
 import { resolveTaskWorkspace } from './task-resolver.ts';
 import type { SandboxControlManifest } from './control/protocol.ts';
-import { resolveTaskRuntimeRoot } from '../task/runtime-paths.ts';
 import {
   createSandboxControlIdentitySentinel,
   writeSandboxControlIdentitySentinel
@@ -64,13 +63,21 @@ export type SandboxControlManifestDraft = Readonly<Omit<SandboxControlManifest,
 
 export function sandboxControlPaths(params: Readonly<{
   base: string;
-  repoRoot?: string;
   project: string;
   container: string;
   identity: SandboxWorkspaceIdentity | SandboxWorkspaceKey;
 }>): Readonly<{ root: string; channelDir: string; statusDir: string; processingDir: string; runtimeDir: string; manifestPath: string }> {
   const root = params.identity.mode === 'task-bound'
-    ? path.join(resolveTaskRuntimeRoot(params.identity.taskId, { repoRoot: params.repoRoot }), 'sandbox-control')
+    ? (() => {
+      if (!/^TASK-\d{8}-\d{6}$/.test(params.identity.taskId)
+        || !params.project || path.basename(params.project) !== params.project || params.project === '.' || params.project === '..') {
+        throw new Error('SANDBOX_CONTROL_ROOT_INVALID');
+      }
+      const candidate = path.resolve(params.base, params.project, 'tasks', params.identity.taskId);
+      const relative = path.relative(path.resolve(params.base), candidate);
+      if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('SANDBOX_CONTROL_ROOT_INVALID');
+      return candidate;
+    })()
     : (() => {
       const digest = createHash('sha256').update('branch-only').digest('hex').slice(0, 16);
       return path.resolve(params.base, params.project, params.container, digest);
@@ -95,6 +102,23 @@ function assertSafeDirectory(directory: string, expectedBase: string): void {
   }
 }
 
+function assertSafeTaskBoundControlRoot(basePath: string, root: string): void {
+  const relative = path.relative(basePath, root);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error(`Sandbox control root escapes its configured base: ${root}`);
+  }
+  if (fs.existsSync(basePath) && fs.lstatSync(basePath).isSymbolicLink()) {
+    throw new Error(`Sandbox control base must not be a symbolic link: ${basePath}`);
+  }
+  let current = basePath;
+  for (const segment of relative.split(path.sep)) {
+    current = path.join(current, segment);
+    if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) {
+      throw new Error(`Sandbox control root must not contain a symbolic link: ${current}`);
+    }
+  }
+}
+
 function assertSafeMountTargetPath(
   target: string,
   worktreeRoot: string,
@@ -263,7 +287,11 @@ export function materializeSandboxControl(params: Readonly<{
   }>;
 }>): SandboxControlSetup {
   const { root, channelDir, statusDir, processingDir, runtimeDir, manifestPath } = sandboxControlPaths(params);
-  assertSafeDirectory(root, params.identity.mode === 'task-bound' ? path.dirname(root) : path.resolve(params.base));
+  if (params.identity.mode === 'task-bound') {
+    assertSafeTaskBoundControlRoot(path.resolve(params.base), root);
+  } else {
+    assertSafeDirectory(root, path.resolve(params.base));
+  }
   if (fs.existsSync(root)) {
     if (!params.replacementLease || path.resolve(params.replacementLease.root) !== root) {
       throw new Error('SANDBOX_CONTROL_REPLACEMENT_REQUIRED');
@@ -329,9 +357,16 @@ export function finalizeSandboxControlManifest(
     containerIdentity: { id: identity.id, labels: { ...identity.labels } },
     authorityEvidence: identity.authorityEvidence
   };
+  const persistedManifest = {
+    ...manifest,
+    channelDir: 'channel',
+    publicStatusDir: 'public',
+    processingDir: 'processing',
+    runtimeDir: 'runtime'
+  };
   const temporary = `${setup.manifestPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
   try {
-    fs.writeFileSync(temporary, `${JSON.stringify(manifest)}\n`, { mode: 0o600, flag: 'wx' });
+    fs.writeFileSync(temporary, `${JSON.stringify(persistedManifest)}\n`, { mode: 0o600, flag: 'wx' });
     fs.renameSync(temporary, setup.manifestPath);
   } finally {
     fs.rmSync(temporary, { force: true });

package/lib/task/control-authority.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { normalizeAgentToken } from '../agent-clients/tokens.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
 import type { AgentClientId } from '../agent-clients/types.ts';
+import { sandboxControlPaths } from '../sandbox/workspace-view.ts';
 import { getAgentClientAdapter } from '../agent-clients/registry.ts';
 import {
   activateMatchingOrchestrationDelegation,
@@ -41,18 +42,14 @@ import { resolveTaskContext, resolveTaskRef, TASK_ID_RE } from './resolve-ref.ts
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import { verifyTaskEvent } from './verification.ts';
 
-export type TaskControlControllerBinding = Readonly<{
-  instanceDigest: string;
-  controlGeneration: string;
-}>;
-
 export type TaskControlExecutionContext =
   | Readonly<{
       source: 'direct-host';
       mode: 'direct-host';
       repoRoot: string;
       runtimeDir?: string;
-      controllerBinding?: TaskControlControllerBinding | null;
+      controlBase?: string;
+      project?: string;
     }>
   | Readonly<{
       source: 'sandbox-executor';
@@ -64,7 +61,6 @@ export type TaskControlExecutionContext =
       generation: string;
       manifestPath: string;
       requestId: string;
-      controllerBinding?: TaskControlControllerBinding | null;
     }>;
 
 export type TaskControlOrchestrationIntent =
@@ -112,25 +108,19 @@ function absolute(name: string, value: string): string {
   return path.resolve(value);
 }
 
-function binding(value: TaskControlControllerBinding | null | undefined): TaskControlControllerBinding | null | undefined {
-  if (value === null || value === undefined) return value;
-  if (!/^[a-f0-9]{64}$/u.test(value.instanceDigest) || !value.controlGeneration) {
-    invalidContext('controller binding is invalid');
-  }
-  return value;
-}
-
 export function createDirectHostExecutionContext(params: Readonly<{
   repoRoot: string;
   runtimeDir?: string;
-  controllerBinding?: TaskControlControllerBinding | null;
+  controlBase?: string;
+  project?: string;
 }>): TaskControlExecutionContext {
   return {
     source: 'direct-host',
     mode: 'direct-host',
     repoRoot: absolute('repoRoot', params.repoRoot),
-    ...(params.runtimeDir === undefined ? {} : { runtimeDir: absolute('runtimeDir', params.runtimeDir) }),
-    ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) }),
+    ...(params.controlBase === undefined ? {} : { controlBase: absolute('controlBase', params.controlBase) }),
+    ...(params.project === undefined ? {} : { project: params.project }),
+    ...(params.runtimeDir === undefined ? {} : { runtimeDir: absolute('runtimeDir', params.runtimeDir) })
   };
 }
 
@@ -142,7 +132,6 @@ export function createSandboxExecutorExecutionContext(params: Readonly<{
   generation: string;
   manifestPath: string;
   requestId: string;
-  controllerBinding?: TaskControlControllerBinding | null;
 }>): TaskControlExecutionContext {
   if (!/^TASK-\d{8}-\d{6}$/u.test(params.taskId) || !params.generation || !params.requestId) {
     invalidContext('sandbox binding is incomplete');
@@ -160,8 +149,7 @@ export function createSandboxExecutorExecutionContext(params: Readonly<{
     taskId: params.taskId,
     generation: params.generation,
     manifestPath: absolute('manifestPath', params.manifestPath),
-    requestId: params.requestId,
-    ...(params.controllerBinding === undefined ? {} : { controllerBinding: binding(params.controllerBinding) }),
+    requestId: params.requestId
   };
 }
 
@@ -170,7 +158,8 @@ export function assertTaskControlExecutionContext(context: TaskControlExecutionC
     if (context.mode !== 'direct-host') invalidContext('direct-host mode is inconsistent');
     absolute('repoRoot', context.repoRoot);
     if (context.runtimeDir !== undefined) absolute('runtimeDir', context.runtimeDir);
-    binding(context.controllerBinding);
+    if (Boolean(context.controlBase) !== Boolean(context.project)) invalidContext('control configuration is incomplete');
+    if (context.controlBase !== undefined) absolute('controlBase', context.controlBase);
     return;
   }
   if (context.mode !== 'task-bound-sandbox' || !/^TASK-\d{8}-\d{6}$/u.test(context.taskId)
@@ -184,7 +173,6 @@ export function assertTaskControlExecutionContext(context: TaskControlExecutionC
   if (path.resolve(context.runtimeDir) !== path.join(path.dirname(path.resolve(context.manifestPath)), 'runtime')) {
     invalidContext('runtimeDir is not bound to the manifest control root');
   }
-  binding(context.controllerBinding);
 }
 
 function boundTaskRef(context: TaskControlExecutionContext, taskRef: string): string {
@@ -225,6 +213,8 @@ async function applyLifecycleWithAuthority(
   context: TaskControlExecutionContext,
   request: TaskLifecycleControlRequest
 ): Promise<TaskLifecycleResult | LifecycleRecoveryResult> {
+  const taskId = lifecycleTaskId(request, context.repoRoot);
+  const controlRoot = taskId ? controlRootForTask(context, taskId) : undefined;
   const execute = async (underTaskLock = false): Promise<TaskLifecycleResult | LifecycleRecoveryResult> => {
     if (request.intent === 'recover-started') {
       const adapter = isAgentClientId(request.agent)
@@ -240,10 +230,17 @@ async function applyLifecycleWithAuthority(
       return adapter.recoverStarted(request as LifecycleRecoveryRequest, { repoRoot: context.repoRoot });
     }
     return underTaskLock
-      ? applyTaskLifecycleWithinTaskLock(request, { repoRoot: context.repoRoot }, taskId!)
-      : applyTaskLifecycle(request, { repoRoot: context.repoRoot });
+      ? applyTaskLifecycleWithinTaskLock(request, {
+        repoRoot: context.repoRoot,
+        ...(controlRoot ? { controlRoot } : {}),
+        ...(context.source === 'direct-host' && context.project ? { controlProject: context.project } : {})
+      }, taskId!)
+      : applyTaskLifecycle(request, {
+        repoRoot: context.repoRoot,
+        ...(controlRoot ? { controlRoot } : {}),
+        ...(context.source === 'direct-host' && context.project ? { controlProject: context.project } : {})
+      });
   };
-  const taskId = lifecycleTaskId(request, context.repoRoot);
   if (!taskId) return await execute();
   try {
     return await withTaskExecutionLock(
@@ -266,6 +263,17 @@ async function applyLifecycleWithAuthority(
   }
 }
 
+function controlRootForTask(context: TaskControlExecutionContext, taskId: string): string | undefined {
+  if (context.source === 'sandbox-executor') return path.dirname(context.manifestPath);
+  if (!context.controlBase || !context.project) return undefined;
+  return sandboxControlPaths({
+    base: context.controlBase,
+    project: context.project,
+    container: '',
+    identity: { mode: 'task-bound', taskId }
+  }).root;
+}
+
 function orchestration(
   context: TaskControlExecutionContext,
   operation: Extract<TaskControlOperation, { family: 'task-orchestration' }>
@@ -367,6 +375,10 @@ export function dispatchTaskControlOperation(
     });
   }
   if (operation.family === 'task-finalization') {
+    const resolved = resolveTaskRef(boundTaskRef(context, operation.request.taskRef), { repoRoot: context.repoRoot });
+    const controlRoot = context.source === 'sandbox-executor'
+      ? path.dirname(context.manifestPath)
+      : resolved.ok ? controlRootForTask(context, resolved.taskId) : undefined;
     return applyTaskFinalization({
       ...operation.request,
       taskRef: boundTaskRef(context, operation.request.taskRef)
@@ -376,6 +388,8 @@ export function dispatchTaskControlOperation(
         controlBinding: { generation: context.generation, requestId: context.requestId },
         manifestPath: context.manifestPath
       } : {}),
+      ...(controlRoot ? { controlRoot } : {}),
+      ...(context.source === 'direct-host' && context.project ? { controlProject: context.project } : {}),
       preflight: (request, options) => verifyTaskEvent(
         { ...request, event: 'complete-task.hard-preflight' }, options
       )

package/lib/task/control-recovery.ts

@@ -13,7 +13,7 @@ export function parseControlOutput(output: string | null): Record<string, unknow
 }
 
 export type ControlRecoveryOperation = Readonly<{
-  family: 'task-lifecycle' | 'task-create' | 'agent-client';
+  family: 'task-lifecycle' | 'task-create';
   intent: string;
   class: string;
 }>;
@@ -54,8 +54,7 @@ export type ControlRecoveryDecision = Readonly<{
 const LIFECYCLE_INTENTS = ['block', 'activate', 'cancel', 'close-codescan', 'close-dependabot', 'restore', 'recover-started'] as const;
 export const SANDBOX_CONTROL_RECOVERY_OPERATIONS: readonly ControlRecoveryOperation[] = Object.freeze([
   ...LIFECYCLE_INTENTS.map((intent) => ({ family: 'task-lifecycle' as const, intent, class: 'lifecycle-mutation' })),
-  { family: 'task-create', intent: 'create', class: 'task-create' },
-  ...(['controller.close', 'controller.verify'] as const).map((intent) => ({ family: 'agent-client' as const, intent, class: 'agent-client-operation' }))
+  { family: 'task-create', intent: 'create', class: 'task-create' }
 ]);
 
 export function digestControlRecoveryIntent(family: string, intent: string): string {

package/lib/task/finalization.ts

@@ -70,6 +70,8 @@ type TaskFinalizationRequest = Readonly<{
 type TaskFinalizationOptions = Readonly<{
   repoRoot: string;
   controlBinding?: Readonly<{ generation: string; requestId: string }>;
+  controlRoot?: string;
+  controlProject?: string;
   manifestPath?: string;
   metadataProvider?: TaskLifecycleOptions['metadataProvider'];
   lifecycle?: typeof applyTaskLifecycle;
@@ -1068,7 +1070,13 @@ async function prepareUnderLock(
     } else {
       const result = lifecycle(
         { taskRef: taskId, intent: 'complete', agent: request.agent },
-        { repoRoot, prepareOnly: true, ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {}) }
+        {
+          repoRoot,
+          prepareOnly: true,
+          ...(options.controlRoot ? { controlRoot: options.controlRoot } : {}),
+          ...(options.controlProject ? { controlProject: options.controlProject } : {}),
+          ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {})
+        }
       );
       lifecycleResult = lifecycleStep(result);
       if (result.status !== 'applied' && result.status !== 'no-op') {
@@ -1207,7 +1215,12 @@ async function commitPreparedTaskFinalization(request: TaskFinalizationRequest,
       });
       receipt = updateReceipt(repoRoot, receipt, { verification: 'pending' });
       const lifecycleRequest = { taskRef: resolved.taskId, intent: 'complete' as const, agent: request.agent };
-      const lifecycleOptions = { repoRoot, ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {}) };
+      const lifecycleOptions = {
+        repoRoot,
+        ...(options.controlRoot ? { controlRoot: options.controlRoot } : {}),
+        ...(options.controlProject ? { controlProject: options.controlProject } : {}),
+        ...(options.metadataProvider ? { metadataProvider: options.metadataProvider } : {})
+      };
       const result = options.lifecycle
         ? options.lifecycle(lifecycleRequest, lifecycleOptions)
         : applyTaskLifecycleWithinTaskLock(lifecycleRequest, lifecycleOptions, resolved.taskId);