@fitlab-ai/agent-infra 0.11.12 → 0.11.13

package/dist/lib/agent-clients/adapters/codex-lifecycle/store.js

@@ -215,7 +215,7 @@ function createCodexLifecycleStore(options) {
             throw new Error(`Codex lifecycle child '${childThreadId}' was not found uniquely`);
         return matches[0];
     }
-    function consume(childThreadId, consumer, expectedHookDefinitionHash, expectedTaskBinding) {
+    function consumeWithLockMode(childThreadId, consumer, expectedHookDefinitionHash, expectedTaskBinding, taskLockHeld) {
         if (!consumer.trim())
             throw new Error('Codex lifecycle consumer is required');
         const current = read(childThreadId);
@@ -223,8 +223,11 @@ function createCodexLifecycleStore(options) {
         if (!binding)
             throw new Error('Codex lifecycle task receipt binding is missing');
         const spawn = current.state.spawn;
-        if (!spawn)
-            throw new Error('Codex lifecycle spawn evidence is missing');
+        if (!spawn) {
+            throw new Error(taskLockHeld
+                ? 'Codex lifecycle task receipt binding is missing'
+                : 'Codex lifecycle spawn evidence is missing');
+        }
         const key = recordKey(spawn.sessionId, spawn.turnId, spawn.toolUseId);
         return update(binding, key, (latest) => {
             if (!latest || expectedTaskBinding && JSON.stringify(latest.taskBinding) !== JSON.stringify(expectedTaskBinding)) {
@@ -241,30 +244,13 @@ function createCodexLifecycleStore(options) {
             if (latest.consumer)
                 return latest;
             return Object.freeze({ ...latest, revision: latest.revision + 1, consumer, consumedAt: now(), updatedAt: now() });
-        });
+        }, taskLockHeld);
+    }
+    function consume(childThreadId, consumer, expectedHookDefinitionHash, expectedTaskBinding) {
+        return consumeWithLockMode(childThreadId, consumer, expectedHookDefinitionHash, expectedTaskBinding, false);
     }
     function consumeWithinTaskLock(childThreadId, consumer, expectedHookDefinitionHash, expectedTaskBinding) {
-        if (!consumer.trim())
-            throw new Error('Codex lifecycle consumer is required');
-        const current = read(childThreadId);
-        const binding = expectedTaskBinding ?? current.taskBinding;
-        if (!binding || !current.state.spawn)
-            throw new Error('Codex lifecycle task receipt binding is missing');
-        const key = recordKey(current.state.spawn.sessionId, current.state.spawn.turnId, current.state.spawn.toolUseId);
-        return update(binding, key, (latest) => {
-            if (!latest || expectedTaskBinding && JSON.stringify(latest.taskBinding) !== JSON.stringify(expectedTaskBinding)) {
-                throw new Error('Codex lifecycle task binding does not match the expected receipt');
-            }
-            if (latest.consumer && latest.consumer !== consumer) {
-                throw new Error(`Codex lifecycle evidence was already consumed by '${latest.consumer}'`);
-            }
-            if (latest.state.status !== 'stop-ready')
-                throw new Error('Codex lifecycle evidence is not stop-ready');
-            if (expectedHookDefinitionHash && latest.state.startEvidence?.hookDefinitionHash !== expectedHookDefinitionHash) {
-                throw new Error('Codex lifecycle hook definition hash is stale');
-            }
-            return latest.consumer ? latest : Object.freeze({ ...latest, revision: latest.revision + 1, consumer, consumedAt: now(), updatedAt: now() });
-        }, true);
+        return consumeWithLockMode(childThreadId, consumer, expectedHookDefinitionHash, expectedTaskBinding, true);
     }
     function expireBefore(cutoff) {
         let changed = 0;

package/dist/lib/internal/sandbox-control.js

@@ -1,18 +1,8 @@
-import { recoverSandboxControl, requestSandboxControl, requestSandboxTaskFinalization, SandboxControlClientError } from '../sandbox/control/client.js';
-import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
+import { recoverSandboxControl, requestSandboxControl, SandboxControlClientError } from '../sandbox/control/client.js';
 import { serveSandboxControl } from '../sandbox/control/server.js';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 import { parseTaskCreateResult, taskCreateExitCode } from '../task/create-service.js';
-import { serializeTaskFinalizationEnvelope } from '../task/finalization-envelope.js';
-function writeFinalizationEnvelope(status, accepted, error, changed = false, result = null, requestId = null) {
-    process.stdout.write(serializeTaskFinalizationEnvelope({ status, changed, accepted, requestId, result, error }));
-}
-function finalizationErrorStatus(error) {
-    if (error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN')
-        return 'unknown';
-    return error.retryable ? 'blocked' : 'failed';
-}
 function writeClientError(error) {
     process.stderr.write(`${error.detail.message}\n`);
     if (error.requestId)
@@ -31,72 +21,6 @@ function recoveredExitCode(response) {
     }
     return response.exitCode ?? 1;
 }
-function finalizationResponseOutput(response) {
-    try {
-        const value = JSON.parse(response.stdout);
-        if (value.version === 2
-            && value.status
-            && ['completed', 'failed', 'blocked', 'unknown'].includes(value.status)
-            && (typeof value.changed === 'boolean' || value.changed === null)) {
-            return serializeTaskFinalizationEnvelope({
-                status: value.status,
-                changed: value.changed,
-                accepted: true,
-                requestId: response.id,
-                result: value.result ?? null,
-                error: value.error ?? null
-            });
-        }
-    }
-    catch {
-        // Preserve non-envelope output for diagnostics from the executor.
-    }
-    return response.stdout;
-}
-function sandboxFinalizationClient(args) {
-    if (args.length !== 4 || !args[0] || args[1] !== 'complete' || args[2] !== '--agent' || !args[3]) {
-        const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'task ref, complete intent, and --agent are required', retryable: false };
-        writeFinalizationEnvelope('failed', false, error);
-        process.stderr.write('Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n');
-        process.exitCode = 1;
-        return;
-    }
-    const agent = normalizeAgentToken(args[3]);
-    if (!agent) {
-        const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: `invalid --agent: ${AGENT_USAGE_HINT}`, retryable: false };
-        writeFinalizationEnvelope('failed', false, error);
-        process.exitCode = 1;
-        return;
-    }
-    let response;
-    try {
-        response = requestSandboxTaskFinalization({ agent });
-    }
-    catch (error) {
-        if (!(error instanceof SandboxControlClientError))
-            throw error;
-        const status = finalizationErrorStatus(error.detail);
-        writeFinalizationEnvelope(status, error.accepted, error.detail, status === 'unknown' ? null : false, null, error.requestId);
-        writeClientError(error);
-        process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.detail.retryable ? 2 : 1;
-        return;
-    }
-    if (response.phase === 'rejected') {
-        const error = response.error ?? {
-            code: 'SANDBOX_CONTROL_REJECTED',
-            message: 'sandbox control rejected the finalization request',
-            retryable: false
-        };
-        const status = finalizationErrorStatus(error);
-        writeFinalizationEnvelope(status, error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN', error, status === 'unknown' ? null : false, null, response.id);
-        process.stderr.write(`${error.message}\n`);
-        process.exitCode = error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.retryable ? 2 : 1;
-        return;
-    }
-    process.stdout.write(finalizationResponseOutput(response));
-    process.stderr.write(response.stderr);
-    process.exitCode = response.exitCode ?? 1;
-}
 async function sandboxControl(args) {
     if (!ensureInternalHandlerRoute('sandbox-control', args))
         return;
@@ -152,10 +76,6 @@ async function sandboxControl(args) {
     }
     if (internalHandlerRoute('sandbox-control', 'client', operation ?? '')) {
         const [family = '', ...commandArgs] = rest;
-        if (family === 'task-finalization') {
-            sandboxFinalizationClient(commandArgs);
-            return;
-        }
         let response;
         try {
             response = requestSandboxControl({ family, args: commandArgs });

package/dist/lib/internal/task-finalization.js

@@ -1,9 +1,12 @@
+import path from 'node:path';
 import { createDirectHostExecutionContext, dispatchTaskControlOperation, parseTaskControlOperation } from '../task/control-authority.js';
 import { applyTaskFinalization } from '../task/finalization.js';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.js';
 import { resolveSandboxControlTransport } from './task-operation-registry.js';
-import { requestSandboxTaskFinalization, SandboxControlClientError } from '../sandbox/control/client.js';
+import { quiesceSandboxControlForTaskCompletion } from '../sandbox/control/lifecycle.js';
+import { resolveTaskRuntimeRoot } from '../task/runtime-paths.js';
 import { serializeTaskFinalizationEnvelope } from '../task/finalization-envelope.js';
+import { verifyTaskEvent } from '../task/verification.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 const USAGE = 'Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n';
 function envelope(status, changed, accepted, result, error, requestId = null) {
@@ -64,26 +67,30 @@ async function taskFinalization(args = []) {
     };
     const transport = resolveSandboxControlTransport(process.env, { localWorkflow: true });
     if (transport.kind === 'sandbox-local') {
-        try {
-            const response = requestSandboxTaskFinalization({ agent: boundOperation.request.agent });
-            process.stdout.write(response.stdout);
-            process.stderr.write(response.stderr);
-            process.exitCode = response.exitCode ?? 1;
-            return;
-        }
-        catch (error) {
-            const clientError = error instanceof SandboxControlClientError ? error : null;
-            const detail = clientError
-                ? clientError.detail
-                : { code: 'SANDBOX_CONTROL_CLIENT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false };
-            const status = detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN'
-                ? 'unknown'
-                : detail.retryable ? 'blocked' : 'failed';
-            const changed = status === 'unknown' ? null : false;
-            process.stdout.write(envelope(status, changed, clientError?.accepted ?? false, null, detail, clientError?.requestId ?? null));
-            process.exitCode = exitCode(status);
+        const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
+        const taskId = process.env.AGENT_INFRA_TASK_ID;
+        const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
+        const controlRootId = process.env.AGENT_INFRA_CONTROL_ROOT_ID;
+        if (!statusDir || !taskId || !generation || !controlRootId || taskId !== resolved.taskId) {
+            const detail = { code: 'TASK_CONTROL_TRANSPORT_INVALID', message: 'sandbox task control identity is incomplete', retryable: false };
+            process.stdout.write(envelope('failed', false, true, null, detail));
+            process.exitCode = 1;
             return;
         }
+        const result = await applyTaskFinalization(boundOperation.request, {
+            repoRoot,
+            beforeLifecycle: async (currentTaskId) => {
+                if (currentTaskId !== taskId)
+                    throw new Error('SANDBOX_CONTROL_IDENTITY_MISMATCH');
+                await quiesceSandboxControlForTaskCompletion(path.join(resolveTaskRuntimeRoot(taskId, { repoRoot }), 'sandbox-control'), { taskId, generation, controlRootId, statusDir });
+            },
+            preflight: (request, options) => verifyTaskEvent({ ...request, event: 'complete-task.hard-preflight' }, options)
+        });
+        const status = result.status === 'prepared' ? 'failed' : result.status;
+        process.stdout.write(envelope(status, result.changed, true, result, result.error
+            ?? (result.status === 'prepared' ? { code: 'TASK_FINALIZATION_PREPARATION_INCOMPLETE', message: 'finalization did not commit', retryable: true } : null)));
+        process.exitCode = exitCode(status);
+        return;
     }
     const result = await dispatchTaskControlOperation(createDirectHostExecutionContext({ repoRoot }), boundOperation);
     if (result.status === 'prepared') {

package/dist/lib/internal/task-lifecycle.js

@@ -2,7 +2,7 @@ import { createDirectHostExecutionContext, dispatchTaskControlOperation, parseTa
 import { lifecycleIntentCatalog } from '../task/lifecycle.js';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
-const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nrecover-started: --auto\n`;
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.filter((intent) => intent !== 'complete').join(', ')}\nrecover-started: --auto\n`;
 function usageFailure(message) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);
     process.stderr.write(USAGE);

package/dist/lib/platform/github-client.js

@@ -18,6 +18,32 @@ function boundedFailureDetail(result) {
         ? diagnostic
         : `${diagnostic.slice(0, ERROR_DETAIL_LIMIT)}… [truncated]`;
 }
+function requestDiagnostics(args, request, attempt, errorMessage) {
+    if (process.env.AGENT_INFRA_GH_DIAGNOSTICS !== '1' && !/rate.?limit/iu.test(errorMessage))
+        return '';
+    const apiIndex = args.indexOf('api');
+    const endpoint = apiIndex < 0
+        ? args.slice(0, 2).filter((arg) => !arg.startsWith('-')).join(' ')
+        : args.slice(apiIndex + 1).find((arg) => !arg.startsWith('-') && !arg.includes('=')) || 'unknown';
+    const safeEndpoint = endpoint.startsWith('http')
+        ? (() => {
+            try {
+                const url = new URL(endpoint);
+                return `${url.host}${url.pathname}`;
+            }
+            catch {
+                return 'unknown';
+            }
+        })()
+        : endpoint.split('?')[0] || 'unknown';
+    const methodIndex = args.findIndex((arg) => arg === '-X' || arg === '--method');
+    const methodFromArgs = methodIndex >= 0 ? args[methodIndex + 1] : undefined;
+    const method = methodFromArgs || request.method || (safeEndpoint === 'graphql' ? 'POST' : 'GET');
+    const tokenEnvironment = ['GH_TOKEN', 'GITHUB_TOKEN', 'GH_ENTERPRISE_TOKEN', 'GITHUB_ENTERPRISE_TOKEN']
+        .filter((name) => Boolean(process.env[name]));
+    const configDirOverride = Boolean(process.env.GH_CONFIG_DIR);
+    return ` [gh-diagnostic endpoint=${safeEndpoint} method=${method} attempt=${attempt} tokenEnv=${tokenEnvironment.join(',') || 'none'} ghConfigDirOverride=${configDirOverride}]`;
+}
 function defaultRunner(args, options) {
     const command = process.env.AGENT_INFRA_GH_BIN || 'gh';
     let prefix = [];
@@ -135,14 +161,18 @@ function createGitHubClient(options = {}) {
             if (result.status === 0)
                 return { ok: true, value: result.stdout };
             const error = classifyGitHubFailure(result);
+            const requestDetail = requestDiagnostics(args, request, attempt + 1, error.message);
+            const contextualError = requestDetail
+                ? { ...error, message: `${error.message}${requestDetail}` }
+                : error;
             if (!retryableMethod || !error.requestRetryable)
-                return { ok: false, error: clientError(error) };
+                return { ok: false, error: clientError(contextualError) };
             if (attempt >= delays.length) {
                 return {
                     ok: false,
                     error: error.code === 'NETWORK_TRANSIENT'
-                        ? { ...clientError(error), code: 'NETWORK_RETRY_EXHAUSTED', message: `${error.message} (retry exhausted)` }
-                        : clientError(error)
+                        ? { ...clientError(contextualError), code: 'NETWORK_RETRY_EXHAUSTED', message: `${contextualError.message} (retry exhausted)` }
+                        : clientError(contextualError)
                 };
             }
             sleep(delays[attempt]);

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';
@@ -1038,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) {
@@ -1081,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/client.js

@@ -3,7 +3,6 @@ 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 { isAgentClientId } from '../../agent-clients/types.js';
-import { normalizeAgentToken } from '../../agent-clients/tokens.js';
 import { readSandboxControlPayload, readSandboxControlStatus } from './state.js';
 import { accessSandboxTaskView, taskViewFromStatus } from './task-view.js';
 import { readSandboxControlIdentitySentinel } from './identity-sentinel.js';
@@ -12,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;
@@ -85,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) {
@@ -180,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) {
@@ -369,9 +362,12 @@ 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 === 'agent-client' || 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 = {
@@ -400,62 +396,6 @@ export function requestSandboxAgentOperation(params) {
     };
     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: []
-    };
-    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);
-}
 export function requestSandboxTaskCreate(params) {
     const auth = authority(params);
     const issuedAt = Date.now();

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

@@ -4,8 +4,6 @@ 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';
@@ -192,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 {
@@ -227,22 +210,6 @@ async function executeRequestInner(manifest, manifestPath, request, options = {}
         validateAgentClientOperation(request, manifest);
         return executeAgentClientOperation(request, manifest, manifestPath, options.agentClientOperation);
     }
-    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);
-    }
     const boundArgs = bindSandboxControlTask(request, manifest.taskId);
     let operation;
     try {
@@ -363,7 +330,7 @@ export async function runSandboxControlExecutor(requestPath, nonce) {
             family: request.family,
             operation: operation && typeof operation === 'object' && 'family' in operation && operation.family === 'task-lifecycle'
                 ? operation.request.intent
-                : request.family === 'task-finalization' || request.family === 'agent-client' ? request.operation : null,
+                : request.family === 'agent-client' ? request.operation : null,
             phase: 'started-committed',
             outcome: 'in-progress'
         });
@@ -380,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 = {