@fitlab-ai/agent-infra 0.11.11 → 0.11.13

package/dist/lib/sandbox/commands/create.js

@@ -23,7 +23,7 @@ import { inspectSandboxControlContainer } from '../control/container-identity.js
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.js';
 import { sandboxCoreBindMounts } from '../mounts.js';
 import { materializeSandboxGitMetadata } from '../git-metadata.js';
-import { assertSandboxTaskSource, finalizeSandboxControlManifest, materializeSandboxControl, materializeSandboxWorkspaceView, prepareSandboxWorkspaceMountTargets, sandboxControlPaths, } from '../workspace-view.js';
+import { assertSandboxTaskSource, finalizeSandboxControlManifest, materializeSandboxControl, materializeSandboxWorkspaceView, prepareSandboxWorkspaceMountTargets, prepareSandboxCompletedTaskMountSource, sandboxControlPaths, } from '../workspace-view.js';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.js';
 import { validateSelinuxDisableEnv } from '../engines/selinux.js';
 import { captureSandboxAuthority, commandForSandboxAuthority, verifySandboxAuthority } from '../engines/authority.js';
@@ -741,6 +741,7 @@ export async function create(args, { runProjectInitCommand = true, workspace: wo
     const container = containerName(effectiveConfig, branch);
     const controlPaths = sandboxControlPaths({
         base: effectiveConfig.controlBase,
+        repoRoot: effectiveConfig.repoRoot,
         project: effectiveConfig.project,
         container,
         identity: target.workspace
@@ -1037,7 +1038,10 @@ export async function create(args, { runProjectInitCommand = true, workspace: wo
                             const taskSource = target.workspace.mode === 'task-bound'
                                 ? assertSandboxTaskSource(effectiveConfig.repoRoot, target.workspace.taskId)
                                 : null;
-                            prepareSandboxWorkspaceMountTargets(worktree);
+                            const completedTaskSource = target.workspace.mode === 'task-bound'
+                                ? prepareSandboxCompletedTaskMountSource(effectiveConfig.repoRoot, target.workspace.taskId)
+                                : null;
+                            prepareSandboxWorkspaceMountTargets(worktree, target.workspace.mode === 'task-bound' ? target.workspace.taskId : undefined);
                             if (previousCutoverSnapshot) {
                                 assertSandboxControlCutoverSnapshot(previousCutoverSnapshot);
                                 if (previousManifest) {
@@ -1080,6 +1084,7 @@ export async function create(args, { runProjectInitCommand = true, workspace: wo
                                 ...(target.workspace.mode === 'task-bound'
                                     ? {
                                         taskSources: [taskSource],
+                                        completedTaskSource: completedTaskSource,
                                         taskId: target.workspace.taskId
                                     }
                                     : {})

package/dist/lib/sandbox/commands/ls.js

@@ -11,11 +11,10 @@ export { containerListFormat, parseLabels } from './list-running.js';
 const USAGE = `Usage: ai sandbox ls
 
 Lists all containers for the current project. The '#' column is a
-display-only row number; the 'SHORT' column shows the active task short
-id bound to each container's branch (via
-.agents/workspace/active/.short-ids.json), or '-' if no active task is
-bound. Pass the SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').
-A SHORT value of '-' means this container has no active task short id and may
+display-only row number; the 'SHORT' column shows the task short id bound to
+each task-bound container, or '-' if no short id is registered. Pass the
+SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').
+A SHORT value of '-' means this container has no task short id and may
 be eligible for "ai sandbox rm --unbound" cleanup. Use a full TASK-id to
 remove a specific task-bound sandbox.
 

package/dist/lib/sandbox/commands/rm.js

@@ -7,7 +7,7 @@ import { sandboxBranchLabel, sandboxLabel, sandboxTaskIdLabel, sandboxWorkspaceM
 import { fetchSandboxRows } from './list-running.js';
 import { rmOne, rmPurge, rmUnbound } from '../removal.js';
 const USAGE = `Usage:
-  ai sandbox rm <branch | TASK-id | short id> Remove one sandbox; use a full TASK-id for a task-bound sandbox and a branch for branch-only sandboxes
+  ai sandbox rm <branch | TASK-id | short id> Remove one sandbox; use a retained short id or full TASK-id for a task-bound sandbox and a branch for branch-only sandboxes
   ai sandbox rm --unbound [--dry-run] [--yes] Remove sandboxes not bound to an active task short id
   ai sandbox rm --purge                     Tear down ALL sandboxes for the project (containers, worktrees, image, VM)`;
 function resolveMissingTaskSandboxBranch(taskId, config) {

package/dist/lib/sandbox/control/agent-operation.js

@@ -0,0 +1,34 @@
+import { getAgentClientAdapter } from '../../agent-clients/registry.js';
+function operationFor(request) {
+    const adapter = getAgentClientAdapter(request.agentClient);
+    const operation = adapter.sandboxControlOperation;
+    if (!operation)
+        throw new Error('SANDBOX_CONTROL_AGENT_OPERATION_UNSUPPORTED');
+    return operation;
+}
+function validateAgentClientOperation(request, manifest) {
+    operationFor(request).validate({
+        operation: request.operation,
+        payload: request.payload,
+        manifest
+    });
+}
+function executeAgentClientOperation(request, manifest, manifestPath, override) {
+    return (override ?? operationFor(request)).execute({
+        operation: request.operation,
+        payload: request.payload,
+        manifest,
+        manifestPath
+    });
+}
+function recoverAgentClientOperation(params) {
+    const operation = operationFor(params.request);
+    return operation.recover?.({
+        operation: params.request.operation,
+        manifest: params.manifest,
+        manifestPath: params.manifestPath,
+        stdout: params.stdout
+    }) ?? { consistent: false };
+}
+export { executeAgentClientOperation, recoverAgentClientOperation, validateAgentClientOperation };
+//# sourceMappingURL=agent-operation.js.map

package/dist/lib/sandbox/control/client.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { SANDBOX_CONTROL_ADMISSION_WINDOW_MS, SANDBOX_CONTROL_MAX_BYTES, SANDBOX_CONTROL_STATUS_STALE_MS, isSandboxControlFamily } from './protocol.js';
-import { normalizeAgentToken } from '../../agent-clients/tokens.js';
+import { isAgentClientId } from '../../agent-clients/types.js';
 import { readSandboxControlPayload, readSandboxControlStatus } from './state.js';
 import { accessSandboxTaskView, taskViewFromStatus } from './task-view.js';
 import { readSandboxControlIdentitySentinel } from './identity-sentinel.js';
@@ -11,7 +11,6 @@ import { hasTaskBoundMarker, isSandbox } from '../environment.js';
 import { loadConfig } from '../config.js';
 import { recoverSandboxControlFromHost } from './host-recovery.js';
 const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
-const SANDBOX_TASK_FINALIZATION_RECOVERY_BUDGET_MS = 5 * 60_000;
 export class SandboxControlClientError extends Error {
     detail;
     accepted;
@@ -84,8 +83,6 @@ function preflight(statusDir, generation, taskViewEffect = null, now = Date.now(
 function taskViewEffectForRequest(request) {
     if (request.family === 'task-lifecycle')
         return 'progress';
-    if (request.family === 'task-finalization')
-        return 'recovery';
     return null;
 }
 function parseResponse(raw, id, accepted = false) {
@@ -179,9 +176,6 @@ function exchangeSandboxControl(request, params) {
                 || (requestTask.kind === 'task' && requestTask.taskId !== identity.taskId))) {
             clientError('SANDBOX_CONTROL_IDENTITY_TOPOLOGY_MISMATCH', 'request task does not match the sandbox identity', false);
         }
-        if (identity.mode === 'branch-only' && request.family === 'task-finalization') {
-            clientError('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot finalize tasks', false);
-        }
     }
     const encoded = `${JSON.stringify(request)}\n`;
     if (Buffer.byteLength(encoded, 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
@@ -368,173 +362,25 @@ function authority(params) {
 export function requestSandboxControl(params) {
     if (!isSandboxControlFamily(params.family))
         clientError('SANDBOX_CONTROL_COMMAND_DENIED', `'${params.family}' is not allowed`, false);
-    if (params.family === 'task-create' || params.family === 'codex-controller' || params.family === 'task-finalization') {
+    if (params.family === 'task-create' || params.family === 'agent-client') {
         clientError('SANDBOX_CONTROL_COMMAND_DENIED', `'${params.family}' requires a typed request`, false);
     }
+    if (params.args[1] === 'complete') {
+        clientError('SANDBOX_CONTROL_COMMAND_DENIED', 'complete must use task-finalization', false);
+    }
     const auth = authority(params);
     const issuedAt = Date.now();
     const request = {
         version: 4, id: randomUUID(), ...auth, issuedAt,
         expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
-        family: params.family, args: params.args,
-        controllerProcess: null,
-        controllerProof: null
+        family: params.family, args: params.args
     };
     return exchangeSandboxControl(request, params);
 }
-export function requestSandboxTaskFinalization(params) {
-    const agent = normalizeAgentToken(params.agent);
-    if (!agent)
-        clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'task-finalization agent is invalid', false);
-    const auth = authority(params);
-    const issuedAt = Date.now();
-    const id = randomUUID();
-    const request = {
-        version: 4,
-        id,
-        ...auth,
-        issuedAt,
-        expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
-        family: 'task-finalization',
-        operation: 'complete',
-        agent,
-        args: [],
-        controllerProcess: null,
-        controllerProof: null
-    };
-    let response;
-    try {
-        response = exchangeSandboxControl(request, params);
-    }
-    catch (error) {
-        if (!(error instanceof SandboxControlClientError)
-            || error.detail.code !== 'SANDBOX_CONTROL_RESULT_UNKNOWN'
-            || !error.accepted || !error.requestId)
-            throw error;
-        return recoverAcceptedTaskFinalization(error.requestId, params);
-    }
-    if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') {
-        return recoverAcceptedTaskFinalization(response.id, params);
-    }
-    return response;
-}
-export function recoverAcceptedTaskFinalization(requestId, params, recover = recoverSandboxControl) {
-    const deadline = Date.now() + (params.recoveryBudgetMs ?? SANDBOX_TASK_FINALIZATION_RECOVERY_BUDGET_MS);
-    while (Date.now() < deadline) {
-        const timeoutMs = Math.min(30_000, deadline - Date.now());
-        if (timeoutMs <= 0)
-            break;
-        try {
-            const response = recover(requestId, { timeoutMs });
-            if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN')
-                continue;
-            return response;
-        }
-        catch (error) {
-            if (error instanceof SandboxControlClientError
-                && error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN'
-                && error.requestId === requestId)
-                continue;
-            throw error;
-        }
-    }
-    clientError('SANDBOX_CONTROL_RESULT_UNKNOWN', 'accepted finalization request remained unknown after the automatic recovery budget; inspect the receipt and resume by request id', false, true, requestId);
-}
-function exactKeys(value, keys) {
-    return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
-}
-function validProcess(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return false;
-    const identity = value;
-    return exactKeys(identity, ['pid', 'startTime'])
-        && Number.isSafeInteger(identity.pid) && identity.pid > 0
-        && Number.isSafeInteger(identity.startTime) && identity.startTime >= 0;
-}
-function validBuild(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return false;
-    const build = value;
-    return exactKeys(build, ['internalExecutableBuildHash', 'lifecycleContractHash', 'packageVersion', 'protocolVersion'])
-        && build.protocolVersion === 3
-        && typeof build.packageVersion === 'string' && build.packageVersion.length > 0
-        && typeof build.internalExecutableBuildHash === 'string' && /^[a-f0-9]{64}$/u.test(build.internalExecutableBuildHash)
-        && typeof build.lifecycleContractHash === 'string' && /^[a-f0-9]{64}$/u.test(build.lifecycleContractHash);
-}
-export function parseCodexControllerResult(response) {
-    if (response.phase !== 'completed' || response.error !== null || response.stderr !== '') {
-        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result outer response is invalid', false, true);
-    }
-    let value;
-    try {
-        if (!response.stdout.endsWith('\n') || response.stdout.slice(0, -1).includes('\n'))
-            throw new Error('not canonical');
-        value = JSON.parse(response.stdout);
-    }
-    catch {
-        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result payload is invalid', false, true);
-    }
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result payload is invalid', false, true);
-    }
-    const result = value;
-    const resultKeys = result.status === 'verified'
-        ? ['binding', 'changed', 'error', 'lease', 'status', 'version']
-        : ['changed', 'error', 'lease', 'status', 'version'];
-    if (!exactKeys(result, resultKeys)
-        || result.version !== 1 || !['opened', 'closed', 'failed', 'verified'].includes(result.status)) {
-        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result schema is invalid', false, true);
-    }
-    if (result.status === 'failed') {
-        const error = result.error;
-        if (response.exitCode !== 1 || result.changed !== false || result.lease !== null
-            || !error || !exactKeys(error, ['code', 'message', 'retryable'])
-            || typeof error.code !== 'string' || !/^[A-Z][A-Z0-9_]+$/u.test(error.code)
-            || typeof error.message !== 'string' || error.retryable !== false) {
-            clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller failure result is invalid', false, true);
-        }
-        clientError(error.code, error.message, false, true);
+export function requestSandboxAgentOperation(params) {
+    if (!isAgentClientId(params.agentClient)) {
+        clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'agent-client id is invalid', false);
     }
-    if (response.exitCode !== 0 || result.error !== null) {
-        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller success result is invalid', false, true);
-    }
-    if (result.status === 'closed') {
-        if (typeof result.changed !== 'boolean' || result.lease !== null) {
-            clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller close result is invalid', false, true);
-        }
-        return result;
-    }
-    if (result.status === 'verified') {
-        const binding = result.binding;
-        if (result.changed !== false || result.lease !== null || !binding
-            || !exactKeys(binding, ['controllerInstanceDigest', 'controlGeneration', 'taskId'])
-            || typeof binding.taskId !== 'string' || binding.taskId.length === 0
-            || typeof binding.controlGeneration !== 'string' || binding.controlGeneration.length === 0
-            || typeof binding.controllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(binding.controllerInstanceDigest)) {
-            clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller verify result is invalid', false, true);
-        }
-        return result;
-    }
-    const lease = result.lease;
-    if (result.changed !== true || !lease
-        || !exactKeys(lease, [
-            'buildIdentity', 'controlGeneration', 'controllerInstanceDigest', 'controllerProcess',
-            'expiresAt', 'issuedAt', 'leaseId', 'leaseSecret', 'taskId', 'version'
-        ])
-        || lease.version !== 1
-        || typeof lease.leaseId !== 'string' || !/^[a-f0-9]{64}$/u.test(lease.leaseId)
-        || typeof lease.leaseSecret !== 'string' || !/^[a-f0-9]{64}$/u.test(lease.leaseSecret)
-        || typeof lease.taskId !== 'string' || lease.taskId.length === 0
-        || typeof lease.controlGeneration !== 'string' || lease.controlGeneration.length === 0
-        || typeof lease.controllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(lease.controllerInstanceDigest)
-        || !validProcess(lease.controllerProcess) || !validBuild(lease.buildIdentity)
-        || !Number.isSafeInteger(lease.issuedAt) || !Number.isSafeInteger(lease.expiresAt)
-        || lease.expiresAt <= lease.issuedAt) {
-        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller open result is invalid', false, true);
-    }
-    return result;
-}
-function requestCodexController(params) {
     const auth = authority(params);
     const issuedAt = Date.now();
     const request = {
@@ -543,43 +389,12 @@ function requestCodexController(params) {
         ...auth,
         issuedAt,
         expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
-        family: 'codex-controller',
-        command: params.command,
-        args: [],
-        controllerProcess: params.controllerProcess,
-        controllerProof: params.controllerProof
+        family: 'agent-client',
+        agentClient: params.agentClient,
+        operation: params.operation,
+        payload: params.payload
     };
-    const result = parseCodexControllerResult(exchangeSandboxControl(request, params));
-    if (result.status === 'opened'
-        && (result.lease.controlGeneration !== auth.generation
-            || result.lease.controllerProcess.pid !== params.controllerProcess.pid
-            || result.lease.controllerProcess.startTime !== params.controllerProcess.startTime)) {
-        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result does not match the request', false, true);
-    }
-    return result;
-}
-export function requestCodexControllerOpen(params) {
-    const result = requestCodexController({ ...params, command: 'open', controllerProof: null });
-    if (result.status !== 'opened')
-        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller open returned the wrong result', false, true);
-    return result;
-}
-export function requestCodexControllerClose(params) {
-    const result = requestCodexController({ ...params, command: 'close' });
-    if (result.status !== 'closed')
-        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller close returned the wrong result', false, true);
-    return result;
-}
-export function requestCodexControllerVerify(params) {
-    const result = requestCodexController({
-        ...params,
-        controllerProcess: params.controllerProof.controllerProcess,
-        command: 'verify'
-    });
-    if (result.status !== 'verified') {
-        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller verify returned the wrong result', false, true);
-    }
-    return result;
+    return exchangeSandboxControl(request, params);
 }
 export function requestSandboxTaskCreate(params) {
     const auth = authority(params);
@@ -588,8 +403,6 @@ export function requestSandboxTaskCreate(params) {
         version: 4, id: randomUUID(), ...auth, issuedAt,
         expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
         family: 'task-create', candidate: params.candidate,
-        controllerProcess: null,
-        controllerProof: null
     };
     return exchangeSandboxControl(request, { ...params, timeoutMs: params.timeoutMs ?? 120_000 });
 }

package/dist/lib/sandbox/control/executor.js

@@ -4,16 +4,13 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { getProcessStartTime } from '../../server/process-state.js';
 import { createTask, projectTaskCreateResult, taskCreateExitCode, taskCreateFailure } from '../../task/create-service.js';
-import { applyTaskFinalization } from '../../task/finalization.js';
-import { serializeTaskFinalizationEnvelope } from '../../task/finalization-envelope.js';
 import { bindSandboxControlTask, validateSandboxControlRequest } from './protocol.js';
 import { atomicWriteJson, executionPath, readActiveLease, terminateSandboxControlExecution } from './state.js';
 import { requestAuditFields, resultAuditFields, appendDiagnosticAudit, createSandboxControlAuditContext, appendCriticalAudit, writeSandboxControlTransition } from './audit.js';
 import { validateSandboxControlIdentity } from './identity-sentinel.js';
 import { createSandboxExecutorExecutionContext, dispatchTaskControlOperation, parseTaskControlOperation } from '../../task/control-authority.js';
 import { assertSandboxControlBrokerOwner, readSandboxControlManifest } from './lifecycle.js';
-import { computeLifecycleBuildIdentity } from '../../agent-clients/adapters/codex-lifecycle/build-identity.js';
-import { closeCodexControllerRegistration, CodexControllerRegistrationError, openCodexControllerRegistration, resolveCodexControllerBinding } from './controller-registration.js';
+import { executeAgentClientOperation, validateAgentClientOperation } from './agent-operation.js';
 function sameBrokerOwner(left, right) {
     return left.version === right.version
         && left.pid === right.pid
@@ -169,23 +166,6 @@ function waitForGate(nonce, timeoutMs = 2_000) {
         });
     });
 }
-function controllerFailure(error) {
-    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 lifecycleFailure(code, message) {
     return {
         exitCode: 1,
@@ -210,21 +190,6 @@ function taskCreateExecutionFailure(requestId, code, message) {
         recovery: 'inspect-domain-state'
     }));
 }
-function finalizationResult(result) {
-    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: ''
-    };
-}
 async function executeRequestInner(manifest, manifestPath, request, options = {}) {
     if (request.family === 'task-create') {
         try {
@@ -241,75 +206,9 @@ async function executeRequestInner(manifest, manifestPath, request, options = {}
             return taskCreateExecutionFailure(request.id, code, detail);
         }
     }
-    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) {
-            const errorCode = error instanceof CodexControllerRegistrationError
-                ? error.code
-                : /^([A-Z][A-Z0-9_]+)/u.exec(error instanceof Error ? error.message : String(error))?.[1]
-                    ?? 'CODEX_SANDBOX_CONTROLLER_FAILED';
-            appendExecutorAudit(manifest, 'controller-operation-failed', {
-                ...requestAuditFields(manifest, request),
-                controllerCommand: request.command,
-                errorCode,
-                errorType: error instanceof Error ? error.name : typeof error,
-            });
-            return controllerFailure(error);
-        }
-    }
-    if (request.family === 'task-finalization') {
-        const parsed = parseTaskControlOperation('task-finalization', [manifest.taskId, 'complete', '--agent', request.agent]);
-        if (parsed.family !== 'task-finalization')
-            throw new Error('SANDBOX_CONTROL_FINALIZATION_OPERATION_INVALID');
-        const operation = parsed;
-        const result = dispatchTaskControlOperation(createSandboxExecutorExecutionContext({
-            repoRoot: manifest.repoRoot,
-            worktreeRoot: manifest.worktreeRoot,
-            runtimeDir: manifest.runtimeDir,
-            taskId: manifest.taskId,
-            generation: manifest.generation,
-            manifestPath,
-            requestId: request.id
-        }), operation);
-        return finalizationResult(await result);
+    if (request.family === 'agent-client') {
+        validateAgentClientOperation(request, manifest);
+        return executeAgentClientOperation(request, manifest, manifestPath, options.agentClientOperation);
     }
     const boundArgs = bindSandboxControlTask(request, manifest.taskId);
     let operation;
@@ -346,7 +245,8 @@ export async function executeRequest(manifest, manifestPath, request, options =
     const fields = requestAuditFields(manifest, request);
     appendExecutorAudit(manifest, 'executor-request-start', fields);
     try {
-        const result = await executeRequestInner(manifest, manifestPath, request, options);
+        let result;
+        result = await executeRequestInner(manifest, manifestPath, request, options);
         appendExecutorAudit(manifest, 'executor-request-finished', {
             requestId: request.id,
             requestFamily: request.family,
@@ -424,13 +324,13 @@ export async function runSandboxControlExecutor(requestPath, nonce) {
                     return null;
                 }
             })()
-            : null;
+            : request.family === 'agent-client' ? request.operation : null;
         const context = createSandboxControlAuditContext(manifest, {
             requestId: request.id,
             family: request.family,
-            operation: operation?.family === 'task-lifecycle'
+            operation: operation && typeof operation === 'object' && 'family' in operation && operation.family === 'task-lifecycle'
                 ? operation.request.intent
-                : request.family === 'task-finalization' ? request.operation : null,
+                : request.family === 'agent-client' ? request.operation : null,
             phase: 'started-committed',
             outcome: 'in-progress'
         });
@@ -447,22 +347,9 @@ export async function runSandboxControlExecutor(requestPath, nonce) {
         });
         const detail = error instanceof Error ? error.message : String(error);
         const code = /^([A-Z][A-Z0-9_]+)/u.exec(detail)?.[1] ?? 'SANDBOX_CONTROL_EXECUTOR_FAILED';
-        result = request.family === 'task-finalization'
-            ? {
-                exitCode: 1,
-                stdout: serializeTaskFinalizationEnvelope({
-                    status: code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 'unknown' : 'failed',
-                    changed: code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? null : false,
-                    accepted: true,
-                    requestId: request.id,
-                    result: null,
-                    error: { code, message: detail, retryable: false }
-                }),
-                stderr: ''
-            }
-            : request.family === 'task-create'
-                ? taskCreateExecutionFailure(request.id, code, detail)
-                : lifecycleFailure(code, detail);
+        result = request.family === 'task-create'
+            ? taskCreateExecutionFailure(request.id, code, detail)
+            : lifecycleFailure(code, detail);
     }
     process.stdout.write(result.stdout);
     process.stderr.write(result.stderr);

package/dist/lib/sandbox/control/lifecycle.js

@@ -9,6 +9,7 @@ import { DEFAULT_SANDBOX_CONTROL_TIMING } from './protocol.js';
 import { inspectSandboxControlContainer } from './container-identity.js';
 import { acquireSandboxResourceLock, resolveSandboxLockNamespace } from './native-file-lock.js';
 import { isSandboxAuthorityEvidence } from '../engines/authority.js';
+import { validateSandboxControlIdentity } from './identity-sentinel.js';
 import { parseSandboxControlStatus, readExecution, terminateSandboxControlExecution } from './state.js';
 const DEFAULT_QUIESCE_TIMEOUT_MS = DEFAULT_SANDBOX_CONTROL_TIMING.quiesceDeadlineMs;
 const QUIESCING_FILE = 'quiescing.json';
@@ -500,6 +501,45 @@ function markSandboxControlRootQuiescing(root) {
             throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
     }
 }
+function readTaskCompletionManifest(root, binding) {
+    const manifest = readSandboxControlManifest(path.join(root, 'manifest.json'));
+    const identity = validateSandboxControlIdentity({
+        publicStatusDir: binding.statusDir,
+        root,
+        mode: manifest.mode,
+        taskId: manifest.taskId,
+        generation: manifest.generation,
+        controlRootId: manifest.controlRootId
+    });
+    if (identity.state !== 'valid' || manifest.mode !== 'task-bound'
+        || manifest.taskId !== binding.taskId || manifest.generation !== binding.generation
+        || manifest.controlRootId !== binding.controlRootId) {
+        throw new Error('SANDBOX_CONTROL_IDENTITY_MISMATCH');
+    }
+    return manifest;
+}
+export async function quiesceSandboxControlForTaskCompletion(root, binding, timeoutMs = DEFAULT_QUIESCE_TIMEOUT_MS) {
+    const resolvedRoot = path.resolve(root);
+    const manifest = readTaskCompletionManifest(resolvedRoot, binding);
+    markSandboxControlRootQuiescing(resolvedRoot);
+    const deadline = Date.now() + timeoutMs;
+    const startupPath = path.join(resolvedRoot, BROKER_STARTING_FILE);
+    const brokerPath = path.join(resolvedRoot, 'broker.json');
+    while (true) {
+        const startup = readStartupOwner(startupPath);
+        if (fs.existsSync(startupPath) && !startup)
+            throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
+        const broker = readBrokerOwner(brokerPath);
+        if (broker && (broker.token !== manifest.token || broker.generation !== manifest.generation)) {
+            throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+        }
+        if (!startup && !broker)
+            return;
+        if (Date.now() >= deadline)
+            throw new Error('SANDBOX_CONTROL_BROKER_DRAIN_TIMEOUT');
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+}
 function recordSandboxRemovalPending(root, manifest, phase, journal) {
     const pendingPath = path.join(root, 'removal-pending.json');
     const temporary = `${pendingPath}.${process.pid}.${randomUUID()}.tmp`;
@@ -934,12 +974,34 @@ function readSandboxControlManifestValue(manifestPath) {
         || !isSandboxAuthorityEvidence(candidate.authorityEvidence))
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     const root = path.dirname(path.resolve(manifestPath));
-    if (path.resolve(candidate.channelDir) !== path.join(root, 'channel')
-        || path.resolve(candidate.publicStatusDir) !== path.join(root, 'public')
-        || path.resolve(candidate.processingDir) !== path.join(root, 'processing')) {
+    const canonicalRoot = fs.realpathSync.native(root);
+    const matchesControlChildPath = (candidatePath, name) => {
+        const resolved = path.resolve(candidatePath);
+        if (path.basename(resolved) !== name)
+            return false;
+        const expected = path.join(canonicalRoot, name);
+        try {
+            return fs.realpathSync.native(resolved) === expected;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+            try {
+                return fs.realpathSync.native(path.dirname(resolved)) === canonicalRoot;
+            }
+            catch (parentError) {
+                if (parentError.code !== 'ENOENT')
+                    throw parentError;
+                return false;
+            }
+        }
+    };
+    if (!matchesControlChildPath(candidate.channelDir, 'channel')
+        || !matchesControlChildPath(candidate.publicStatusDir, 'public')
+        || !matchesControlChildPath(candidate.processingDir, 'processing')) {
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     }
-    if (path.resolve(candidate.runtimeDir) !== path.join(root, 'runtime')) {
+    if (!matchesControlChildPath(candidate.runtimeDir, 'runtime')) {
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     }
     const normalized = {