@fitlab-ai/agent-infra 0.9.10 → 0.9.11

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

@@ -1,15 +1,32 @@
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { getProcessStartTime } from '../../server/process-state.js';
 import { createTask } from '../../task/create-service.js';
 import { applyTaskFinalization } from '../../task/finalization.js';
-import { verifyTaskEvent } from '../../task/verification.js';
-import { bindSandboxControlTask } from './protocol.js';
-import { atomicWriteJson, executionPath, terminateSandboxControlExecution } from './state.js';
+import { bindSandboxControlTask, validateSandboxControlRequest } from './protocol.js';
+import { atomicWriteJson, executionPath, readActiveLease, terminateSandboxControlExecution } from './state.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';
+function sameBrokerOwner(left, right) {
+    return left.version === right.version
+        && left.pid === right.pid
+        && left.startTime === right.startTime
+        && left.brokerId === right.brokerId
+        && left.token === right.token
+        && left.generation === right.generation;
+}
+export function assertSandboxControlExecutorAuthority(manifest, gateOwner) {
+    const owner = assertSandboxControlBrokerOwner(manifest);
+    if (gateOwner && !sameBrokerOwner(owner, gateOwner)) {
+        throw new Error('SANDBOX_CONTROL_GATE_OWNER_MISMATCH');
+    }
+    if (readActiveLease(manifest))
+        throw new Error('SANDBOX_CONTROL_HANDOFF_ACTIVE');
+}
 function safeEnv(env) {
     return Object.fromEntries(Object.entries(env).filter(([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')));
 }
@@ -74,12 +91,15 @@ export async function prepareSandboxControlExecution(params) {
         start(canWrite = () => true) {
             if (!child.connected)
                 throw new Error('SANDBOX_CONTROL_EXECUTOR_GATE_CLOSED');
+            if (!canWrite())
+                throw new Error('SANDBOX_CONTROL_OWNER_LOST');
+            const gateOwner = assertSandboxControlBrokerOwner(params.manifest);
             if (!canWrite())
                 throw new Error('SANDBOX_CONTROL_OWNER_LOST');
             atomicWriteJson(executionPath(params.manifest, params.request.id), { ...execution, phase: 'running', updatedAt: Date.now() });
             if (!canWrite())
                 throw new Error('SANDBOX_CONTROL_OWNER_LOST');
-            child.send({ version: 1, nonce });
+            child.send({ version: 1, nonce, owner: gateOwner });
         },
         completion,
         terminate(updateState = true) {
@@ -104,11 +124,16 @@ function waitForGate(nonce, timeoutMs = 2_000) {
             clearTimeout(timer);
             process.off('disconnect', onDisconnect);
             const value = message;
-            if (!value || value.version !== 1 || value.nonce !== nonce) {
+            const owner = value?.owner;
+            if (!value || value.version !== 1 || value.nonce !== nonce
+                || !owner || owner.version !== 3 || !Number.isSafeInteger(owner.pid) || (owner.pid ?? 0) <= 0
+                || typeof owner.startTime !== 'number' || !Number.isSafeInteger(owner.startTime)
+                || typeof owner.brokerId !== 'string' || owner.brokerId.length === 0
+                || typeof owner.token !== 'string' || typeof owner.generation !== 'string') {
                 reject(new Error('SANDBOX_CONTROL_EXECUTOR_GATE_INVALID'));
                 return;
             }
-            resolve();
+            resolve(owner);
         });
     });
 }
@@ -139,6 +164,16 @@ function orchestrationFailure(code, message) {
         stderr: ''
     };
 }
+function lifecycleFailure(code, message) {
+    return {
+        exitCode: 1,
+        stdout: `${JSON.stringify({
+            status: 'failed', changed: false,
+            error: { code, message }
+        })}\n`,
+        stderr: ''
+    };
+}
 function finalizationResult(result) {
     const payload = {
         version: 1,
@@ -154,19 +189,7 @@ function finalizationResult(result) {
         stderr: ''
     };
 }
-function isCodexPrepare(args) {
-    if (args[1] !== 'prepare')
-        return false;
-    const values = [];
-    for (let index = 2; index < args.length; index += 1) {
-        if (args[index] === '--client')
-            values.push(args[index + 1] ?? '');
-        else if (args[index]?.startsWith('--client='))
-            values.push(args[index].slice('--client='.length));
-    }
-    return values.length === 1 && values[0] === 'codex';
-}
-export function executeRequest(manifest, manifestPath, request, options = {}) {
+export async function executeRequest(manifest, manifestPath, request, options = {}) {
     if (request.family === 'task-create') {
         const result = createTask(request.candidate, { repoRoot: manifest.repoRoot });
         return {
@@ -220,12 +243,41 @@ export function executeRequest(manifest, manifestPath, request, options = {}) {
         }
     }
     if (request.family === 'task-finalization') {
-        return finalizationResult(applyTaskFinalization({ taskRef: manifest.taskId, intent: 'complete', agent: request.agent }, { repoRoot: manifest.repoRoot, preflight: (input, options) => verifyTaskEvent({ ...input, event: 'complete-task.hard-preflight' }, options) }));
+        const operation = parseTaskControlOperation('task-finalization', [manifest.taskId, 'complete', '--agent', request.agent]);
+        if (operation.family !== 'task-finalization')
+            throw new Error('SANDBOX_CONTROL_FINALIZATION_OPERATION_INVALID');
+        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(result);
     }
     const boundArgs = bindSandboxControlTask(request, manifest.taskId);
+    if (request.family === 'task-orchestration') {
+        boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
+    }
+    let operation;
+    try {
+        operation = parseTaskControlOperation(request.family, boundArgs);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1] ?? 'TASK_CONTROL_OPERATION_INVALID';
+        return request.family === 'task-lifecycle'
+            ? lifecycleFailure('LIFECYCLE_PAYLOAD_INVALID', message)
+            : orchestrationFailure(code, message);
+    }
     let controllerBinding = null;
     if (request.family === 'task-orchestration') {
-        if (isCodexPrepare(request.args)) {
+        const codexPrepare = operation.family === 'task-orchestration'
+            && operation.intent === 'prepare'
+            && operation.input.client === 'codex';
+        if (codexPrepare) {
             if (!request.controllerProof) {
                 return orchestrationFailure('CODEX_SANDBOX_CONTROLLER_PROOF_REQUIRED', 'Codex prepare requires a current controller lease proof');
             }
@@ -247,33 +299,73 @@ export function executeRequest(manifest, manifestPath, request, options = {}) {
         else if (request.controllerProof !== null) {
             return orchestrationFailure('CODEX_SANDBOX_CONTROLLER_PROOF_INVALID', 'Controller proof is only accepted for canonical Codex prepare');
         }
-        boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
     }
-    const result = (options.spawnDomain ?? spawnSync)(process.execPath, nodeEntryArgs(process.argv[1], [request.family, ...boundArgs]), {
-        cwd: manifest.repoRoot,
-        encoding: 'utf8',
-        env: {
-            ...safeEnv(process.env),
-            AGENT_INFRA_RUNTIME_DIR: manifest.runtimeDir,
-            ...(controllerBinding
-                ? { AGENT_INFRA_CONTROL_CONTROLLER_BINDING: JSON.stringify(controllerBinding) }
-                : {})
-        }
+    const context = createSandboxExecutorExecutionContext({
+        repoRoot: manifest.repoRoot,
+        worktreeRoot: manifest.worktreeRoot,
+        runtimeDir: manifest.runtimeDir,
+        taskId: manifest.taskId,
+        generation: manifest.generation,
+        manifestPath,
+        requestId: request.id,
+        ...(controllerBinding ? { controllerBinding } : {})
     });
-    return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+    const format = (value) => {
+        const result = value;
+        return {
+            exitCode: result.status === 'failed' ? 1 : 0,
+            stdout: `${JSON.stringify(value)}\n`,
+            stderr: ''
+        };
+    };
+    if (request.family === 'task-orchestration') {
+        if (operation.family !== 'task-orchestration')
+            throw new Error('SANDBOX_CONTROL_ORCHESTRATION_OPERATION_INVALID');
+        return format(await dispatchTaskControlOperation(context, operation));
+    }
+    if (operation.family !== 'task-lifecycle')
+        throw new Error('SANDBOX_CONTROL_LIFECYCLE_OPERATION_INVALID');
+    return format(dispatchTaskControlOperation(context, operation));
 }
 export async function runSandboxControlExecutor(requestPath, nonce) {
-    await waitForGate(nonce);
+    const gateOwner = await waitForGate(nonce);
     process.disconnect?.();
-    const root = fs.realpathSync.native(process.cwd());
-    const request = JSON.parse(fs.readFileSync(requestPath, 'utf8'));
     const manifestPath = process.env.AGENT_INFRA_EXECUTOR_MANIFEST;
     if (!manifestPath)
         throw new Error('SANDBOX_CONTROL_EXECUTOR_MANIFEST_MISSING');
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const manifest = readSandboxControlManifest(manifestPath);
+    const root = fs.realpathSync.native(process.cwd());
     if (fs.realpathSync.native(manifest.repoRoot) !== root)
         throw new Error('SANDBOX_CONTROL_EXECUTOR_ROOT_INVALID');
-    const result = executeRequest(manifest, manifestPath, request);
+    const raw = JSON.parse(fs.readFileSync(requestPath, 'utf8'));
+    const request = validateSandboxControlRequest(raw, manifest);
+    const requestDirectory = path.resolve(path.dirname(requestPath));
+    const processingDirectory = path.resolve(path.join(manifest.processingDir, request.id));
+    const channelRequestDirectory = path.resolve(path.join(manifest.channelDir, 'requests'));
+    if (requestDirectory !== processingDirectory && requestDirectory !== channelRequestDirectory) {
+        throw new Error('SANDBOX_CONTROL_EXECUTOR_REQUEST_INVALID');
+    }
+    let result;
+    try {
+        assertSandboxControlExecutorAuthority(manifest, gateOwner);
+        result = await executeRequest(manifest, manifestPath, request);
+    }
+    catch (error) {
+        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: `${JSON.stringify({
+                    version: 1, status: 'failed', changed: false, accepted: true, result: null,
+                    error: { code, message: detail, retryable: false }
+                })}\n`,
+                stderr: ''
+            }
+            : request.family === 'task-lifecycle'
+                ? lifecycleFailure(code, detail)
+                : orchestrationFailure(code, detail);
+    }
     process.stdout.write(result.stdout);
     process.stderr.write(result.stderr);
     process.exitCode = result.exitCode;

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

@@ -414,8 +414,6 @@ function readProcessingSnapshot(root) {
 export function captureSandboxControlCutoverSnapshot(root) {
     const resolvedRoot = path.resolve(root);
     const manifestPath = path.join(resolvedRoot, 'manifest.json');
-    if (fs.existsSync(manifestPath))
-        readSandboxControlManifestForTransition(manifestPath);
     return {
         root: resolvedRoot,
         manifestRaw: readOptionalRaw(manifestPath),
@@ -430,7 +428,7 @@ export function assertSandboxControlCutoverSnapshot(snapshot) {
         throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
     }
 }
-function readSandboxControlManifestValue(manifestPath, allowLegacy) {
+function readSandboxControlManifestValue(manifestPath) {
     if (!regularFile(manifestPath))
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     let manifest;
@@ -445,8 +443,14 @@ function readSandboxControlManifestValue(manifestPath, allowLegacy) {
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     }
     const candidate = manifest;
-    if (candidate.version !== 4 && candidate.version !== 5) {
-        throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 5; container-only recreation is required');
+    const expectedKeys = [
+        'branch', 'channelDir', 'container', 'containerIdentity', 'engine', 'generation',
+        'mode', 'processingDir', 'project', 'publicStatusDir', 'repoRoot', 'runtimeDir',
+        'taskId', 'token', 'worktreeRoot'
+    ];
+    if ('version' in candidate || typeof candidate.runtimeDir !== 'string'
+        || Object.keys(manifest).sort().join(',') !== expectedKeys.sort().join(',')) {
+        throw new Error('SANDBOX_CONTROL_MANIFEST_REBUILD_REQUIRED: container-only recreation/rebuild is required');
     }
     if (typeof candidate.containerIdentity !== 'object' || candidate.containerIdentity === null
         || Array.isArray(candidate.containerIdentity))
@@ -463,7 +467,9 @@ function readSandboxControlManifestValue(manifestPath, allowLegacy) {
         || (candidate.taskId !== null && typeof candidate.taskId !== 'string')
         || typeof candidate.channelDir !== 'string' || typeof candidate.publicStatusDir !== 'string'
         || typeof candidate.processingDir !== 'string' || typeof candidate.token !== 'string'
-        || typeof candidate.generation !== 'string')
+        || typeof candidate.generation !== 'string'
+        || (candidate.mode === 'task-bound' && (typeof candidate.taskId !== 'string' || candidate.taskId.length === 0))
+        || (candidate.mode === 'branch-only' && candidate.taskId !== null))
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     const root = path.dirname(path.resolve(manifestPath));
     if (path.resolve(candidate.channelDir) !== path.join(root, 'channel')
@@ -471,22 +477,13 @@ function readSandboxControlManifestValue(manifestPath, allowLegacy) {
         || path.resolve(candidate.processingDir) !== path.join(root, 'processing')) {
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     }
-    if (candidate.version === 4) {
-        if (!allowLegacy) {
-            throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 5; container-only recreation is required');
-        }
-        return candidate;
-    }
-    if (typeof candidate.runtimeDir !== 'string' || path.resolve(candidate.runtimeDir) !== path.join(root, 'runtime')) {
+    if (path.resolve(candidate.runtimeDir) !== path.join(root, 'runtime')) {
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     }
     return candidate;
 }
 export function readSandboxControlManifest(manifestPath) {
-    return readSandboxControlManifestValue(manifestPath, false);
-}
-export function readSandboxControlManifestForTransition(manifestPath) {
-    return readSandboxControlManifestValue(manifestPath, true);
+    return readSandboxControlManifestValue(manifestPath);
 }
 function readBrokerOwner(filePath) {
     if (!fs.existsSync(filePath))
@@ -507,6 +504,18 @@ function readBrokerOwner(filePath) {
         throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
     return owner;
 }
+export function assertSandboxControlBrokerOwner(manifest, options = {}) {
+    const root = path.dirname(path.resolve(manifest.publicStatusDir));
+    const owner = readBrokerOwner(path.join(root, 'broker.json'));
+    if (!owner)
+        throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
+    if (owner.token !== manifest.token || owner.generation !== manifest.generation) {
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    }
+    if (!ownerLive(owner, options.identityProbe))
+        throw new Error('SANDBOX_CONTROL_OWNER_LOST');
+    return owner;
+}
 function readStatusOwner(filePath) {
     if (!fs.existsSync(filePath))
         return null;
@@ -641,7 +650,7 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
     markSandboxControlRootQuiescing(resolvedRoot);
     await waitForStartupTransition(resolvedRoot, Math.max(0, forceAt - Date.now()), identityProbe);
     const manifestPath = path.join(resolvedRoot, 'manifest.json');
-    const manifest = fs.existsSync(manifestPath) ? readSandboxControlManifestForTransition(manifestPath) : null;
+    const manifest = fs.existsSync(manifestPath) ? readSandboxControlManifest(manifestPath) : null;
     const broker = readBrokerOwner(path.join(resolvedRoot, 'broker.json'));
     const status = readStatusOwner(path.join(resolvedRoot, 'public', 'status.json'));
     const statusOwner = status ? status.broker : null;
@@ -730,7 +739,7 @@ export async function removeSandboxControlRoot(root, options) {
     if (!stat.isDirectory() || stat.isSymbolicLink())
         throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
     const manifestPath = path.join(resolvedRoot, 'manifest.json');
-    const manifest = readSandboxControlManifestForTransition(manifestPath);
+    const manifest = readSandboxControlManifest(manifestPath);
     const inspectContainer = options.inspectContainer
         ?? ((timeoutMs) => inspectSandboxControlContainer(manifest, { timeoutMs }));
     const timeoutMs = options.timeoutMs ?? options.timing?.quiesceDeadlineMs ?? DEFAULT_QUIESCE_TIMEOUT_MS;
@@ -792,7 +801,7 @@ export async function removeSandboxControlRoot(root, options) {
                 : 'SANDBOX_CONTROL_CONTAINER_STILL_EXISTS');
         }
     }
-    const currentManifest = readSandboxControlManifestForTransition(manifestPath);
+    const currentManifest = readSandboxControlManifest(manifestPath);
     if (currentManifest.token !== manifest.token || currentManifest.generation !== manifest.generation
         || !isSandboxControlRootQuiescing(resolvedRoot)) {
         throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');

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

@@ -197,6 +197,7 @@ export async function serveSandboxControl(manifestPath, signal = new AbortContro
         if (!recoverProcessing(manifest, brokerOwns))
             return;
         while (!signal.aborted) {
+            let settledExecution = null;
             if (!brokerOwns())
                 break;
             let current;
@@ -255,22 +256,7 @@ export async function serveSandboxControl(manifestPath, signal = new AbortContro
             if (active?.settled) {
                 if (!brokerOwns())
                     break;
-                if (active.result) {
-                    if (!brokerOwns())
-                        break;
-                    writeResponse(manifest, {
-                        version: 2, id: active.request.id, phase: 'completed', exitCode: active.result.exitCode,
-                        stdout: active.result.stdout, stderr: active.result.stderr, error: null
-                    });
-                }
-                else {
-                    if (!brokerOwns())
-                        break;
-                    writeResponse(manifest, unknown(active.request.id));
-                }
-                if (!brokerOwns())
-                    break;
-                fs.rmSync(path.join(manifest.processingDir, active.request.id), { recursive: true, force: true });
+                settledExecution = active;
                 active = null;
             }
             let reasonCode = null;
@@ -313,6 +299,22 @@ export async function serveSandboxControl(manifestPath, signal = new AbortContro
                 appendSandboxControlAudit(manifest, 'broker-state', { state, reasonCode, requestId: active?.request.id ?? null });
                 lastState = stateKey;
             }
+            if (settledExecution) {
+                if (!brokerOwns())
+                    break;
+                if (settledExecution.result) {
+                    writeResponse(manifest, {
+                        version: 2, id: settledExecution.request.id, phase: 'completed', exitCode: settledExecution.result.exitCode,
+                        stdout: settledExecution.result.stdout, stderr: settledExecution.result.stderr, error: null
+                    });
+                }
+                else {
+                    writeResponse(manifest, unknown(settledExecution.request.id));
+                }
+                if (!brokerOwns())
+                    break;
+                fs.rmSync(path.join(manifest.processingDir, settledExecution.request.id), { recursive: true, force: true });
+            }
             let retiring = false;
             for (const name of fs.readdirSync(requestsDir).sort()) {
                 if (!/^[a-f0-9-]{16,64}\.json$/.test(name))

package/dist/lib/sandbox/mounts.js

@@ -2,7 +2,8 @@ import path from 'node:path';
 import { shareBranchDir, shareCommonDir, shellConfigDirCandidates, worktreeDirCandidates } from './constants.js';
 import { sandboxWorkspaceViewStatePaths } from './workspace-view.js';
 export function sandboxCoreBindMounts(config, branch, overrides) {
-    const taskBound = Boolean(overrides.taskSource && overrides.taskId);
+    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')],
@@ -26,7 +27,7 @@ export function sandboxCoreBindMounts(config, branch, overrides) {
     ];
     if (taskBound) {
         mounts.push({
-            hostPaths: [overrides.taskSource],
+            hostPaths: taskSources,
             containerPath: path.posix.join('/workspace/.agents/workspace/active', overrides.taskId),
             readOnly: false
         });

package/dist/lib/sandbox/recovery.js

@@ -9,6 +9,7 @@ import { createSandboxCapabilityPlan } from './agent-client-reconciler.js';
 import { toEnginePath } from './engines/wsl2-paths.js';
 import { sandboxCoreBindMounts } from './mounts.js';
 import { assertSandboxTaskSource, sandboxControlPaths, sandboxWorkspaceViewPaths } from './workspace-view.js';
+import { resolveTaskWorkspace } from './task-resolver.js';
 import { parseSandboxWorkspaceIdentity, sameSandboxWorkspaceIdentity } from './workspace-identity.js';
 import { inspectWorktree } from './worktree-safety.js';
 import { commandForEngine, runEngine, runOkEngine, runProbe, runVerboseEngine } from './shell.js';
@@ -407,6 +408,66 @@ function sourceCandidates(engine, hostPath) {
     }
     return [...new Set(candidates.map((candidate) => normalizeMountSource(engine, candidate)))];
 }
+function recoveryTaskSources(repoRoot, taskId) {
+    const activePath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId);
+    const completedPath = path.join(repoRoot, '.agents', 'workspace', 'completed', taskId);
+    if (fs.existsSync(activePath) && !fs.existsSync(completedPath)) {
+        const source = assertSandboxTaskSource(repoRoot, taskId);
+        return { mountPaths: [source], accessiblePaths: [source] };
+    }
+    const task = resolveTaskWorkspace(taskId, repoRoot);
+    if (task.state === 'active') {
+        const source = assertSandboxTaskSource(repoRoot, taskId);
+        return { mountPaths: [source], accessiblePaths: [source] };
+    }
+    if (task.state !== 'completed') {
+        throw new Error(`SANDBOX_TASK_SOURCE_STATE_UNSUPPORTED: task ${taskId} is ${task.state}`);
+    }
+    const completedRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace', 'completed'));
+    const completedSource = fs.realpathSync.native(path.dirname(task.taskMd));
+    if (path.dirname(completedSource) !== completedRoot) {
+        throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${completedSource} is not under completed workspace`);
+    }
+    const historicalActivePath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId);
+    const mountPaths = [completedSource, historicalActivePath];
+    if (fs.existsSync(historicalActivePath)) {
+        try {
+            mountPaths[1] = fs.realpathSync.native(historicalActivePath);
+        }
+        catch {
+            // Keep the exact historical path as a candidate; the current completed
+            // source remains the only source that must still be accessible.
+        }
+    }
+    return { mountPaths, accessiblePaths: [completedSource] };
+}
+function startCompletedSandboxContainer(params) {
+    const taskSources = recoveryTaskSources(params.config.repoRoot, params.taskId);
+    const completedSource = taskSources.accessiblePaths[0];
+    const activeRoot = path.join(params.config.repoRoot, '.agents', 'workspace', 'active');
+    const historicalSource = path.join(activeRoot, params.taskId);
+    fs.mkdirSync(activeRoot, { recursive: true });
+    try {
+        fs.lstatSync(historicalSource);
+        throw new Error(`SANDBOX_COMPLETED_SOURCE_CONFLICT: historical task source already exists at ${historicalSource}`);
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    fs.symlinkSync(completedSource, historicalSource, process.platform === 'win32' ? 'junction' : 'dir');
+    try {
+        params.start(params.engine, params.container);
+    }
+    finally {
+        const temporarySource = fs.lstatSync(historicalSource);
+        const resolvedSource = fs.realpathSync.native(historicalSource);
+        if (!temporarySource.isSymbolicLink() || resolvedSource !== completedSource) {
+            throw new Error(`SANDBOX_COMPLETED_SOURCE_CHANGED: refusing to remove unexpected path at ${historicalSource}`);
+        }
+        fs.unlinkSync(historicalSource);
+    }
+}
 function sameHostSource(left, right) {
     try {
         const leftStat = fs.statSync(left, { bigint: true });
@@ -440,21 +501,29 @@ function expectedMounts(params) {
         container: params.container,
         identity: params.workspace
     });
+    const taskSources = params.workspace.mode === 'task-bound'
+        ? recoveryTaskSources(config.repoRoot, params.workspace.taskId)
+        : null;
+    const taskId = params.workspace.mode === 'task-bound' ? params.workspace.taskId : null;
     const core = sandboxCoreBindMounts(config, branch, {
         workspaceViewRoot: view.root,
         controlDir: control.channelDir,
         controlStatusDir: control.statusDir,
-        ...(params.workspace.mode === 'task-bound'
-            ? {
+        ...(taskSources === null
+            ? {}
+            : {
                 runtimeDir: control.runtimeDir,
-                taskSource: assertSandboxTaskSource(config.repoRoot, params.workspace.taskId),
-                taskId: params.workspace.taskId
-            }
-            : {})
+                taskSources: taskSources.mountPaths,
+                taskId: taskId
+            })
     }).map((mount) => ({
         path: mount.containerPath,
         expectedType: 'bind',
         hostPaths: mount.hostPaths,
+        ...(taskSources !== null && taskId !== null
+            && mount.containerPath === `/workspace/.agents/workspace/active/${taskId}`
+            ? { sourceAccessiblePaths: taskSources.accessiblePaths }
+            : {}),
         expectedRW: !mount.readOnly
     }));
     const live = tools.flatMap((tool) => (tool.hostLiveMounts ?? []).flatMap(({ hostPath, containerSubpath }) => {
@@ -469,9 +538,7 @@ function expectedMounts(params) {
             }];
     }));
     const persistentTools = tools
-        .filter((tool) => !tool.tmpfs
-        && (config.agentClientSource === 'canonical'
-            || actualMounts.has(tool.containerMount)))
+        .filter((tool) => !tool.tmpfs)
         .map((tool) => ({
         path: tool.containerMount,
         expectedType: 'bind',
@@ -577,13 +644,10 @@ export function collectSandboxRecoverySnapshot(params) {
         taskId: sandboxTaskIdLabel(params.config)
     });
     const selectedToolIds = new Set(tools.map((tool) => tool.id));
-    const enforceCanonicalPlan = params.config.agentClientSource === 'canonical';
-    const unexpectedCapabilityMounts = enforceCanonicalPlan
-        ? capabilityPlan.cleanupInventory
-            .filter((tool) => isAgentClientId(tool.id) && !selectedToolIds.has(tool.id))
-            .map((tool) => tool.containerMount)
-            .filter((mountPath) => mountsByDestination.has(mountPath))
-        : [];
+    const unexpectedCapabilityMounts = capabilityPlan.cleanupInventory
+        .filter((tool) => isAgentClientId(tool.id) && !selectedToolIds.has(tool.id))
+        .map((tool) => tool.containerMount)
+        .filter((mountPath) => mountsByDestination.has(mountPath));
     const mountSnapshots = expectedMounts({
         config: params.config,
         branch: params.branch,
@@ -616,7 +680,7 @@ export function collectSandboxRecoverySnapshot(params) {
             sourceAccessible: expected.expectedType === 'tmpfs'
                 ? true
                 : matchedHostPath !== undefined
-                    && hostSourceAccessible(matchedHostPath, expected.expectedRW)
+                    && (expected.sourceAccessiblePaths ?? [matchedHostPath]).some((hostPath) => hostSourceAccessible(hostPath, expected.expectedRW))
         };
     });
     return {
@@ -636,9 +700,7 @@ export function collectSandboxRecoverySnapshot(params) {
         identityOk: typeof inspection.Id === 'string' && inspection.Id.length > 0
             && branchLabel === params.branch
             && sameSandboxWorkspaceIdentity(containerWorkspace, workspace),
-        runtimeCapabilityOk: enforceCanonicalPlan
-            ? labels[sandboxRuntimeCapabilityLabel(params.config)] === capabilityPlan.runtimeSignature
-            : undefined,
+        runtimeCapabilityOk: labels[sandboxRuntimeCapabilityLabel(params.config)] === capabilityPlan.runtimeSignature,
         unexpectedCapabilityMounts,
         mounts: mountSnapshots,
         tmpfs,
@@ -813,11 +875,22 @@ export async function ensureSandboxReady(params) {
                 workspace: params.workspace ?? { mode: 'branch-only' }
             });
         }
-        if (params.forceRecreate) {
+        if (params.forceRecreate || (params.reentry === 'completed' && params.allowRecreate)) {
             throw new Error('Explicit container recreation requested.');
         }
         if (!params.row.running) {
-            startFn(params.engine, params.row.name);
+            if (params.reentry === 'completed' && params.workspace?.mode === 'task-bound') {
+                startCompletedSandboxContainer({
+                    config: params.config,
+                    engine: params.engine,
+                    container: params.row.name,
+                    taskId: params.workspace.taskId,
+                    start: startFn
+                });
+            }
+            else {
+                startFn(params.engine, params.row.name);
+            }
             const initial = assess({
                 config: params.config,
                 engine: params.engine,
@@ -930,6 +1003,34 @@ export async function ensureSandboxReady(params) {
     catch (error) {
         failure = error instanceof Error ? error : new Error(String(error));
     }
+    if (params.reentry === 'completed') {
+        if (params.workspace?.mode !== 'task-bound') {
+            throw new Error('SANDBOX_COMPLETED_REENTRY_INVALID: completed re-entry requires a task-bound workspace');
+        }
+        const taskId = params.workspace.taskId;
+        const commandChain = [
+            `docker exec -it ${params.row.name} bash /usr/local/bin/sandbox-tmux-entry`,
+            `ai sandbox rm ${taskId}`,
+            `ai sandbox create ${params.branch}`
+        ];
+        const code = params.allowRecreate || params.forceRecreate
+            ? 'SANDBOX_COMPLETED_RECREATE_UNSUPPORTED'
+            : 'SANDBOX_COMPLETED_REENTRY_FAILED';
+        const lead = code === 'SANDBOX_COMPLETED_RECREATE_UNSUPPORTED'
+            ? 'Completed sandbox replacement is unsupported; the existing container was not replaced.'
+            : 'Completed sandbox recovery failed; the existing container was not replaced.';
+        throw new Error([
+            `${code}: ${lead}`,
+            `Task: ${taskId}; container: ${params.row.name}; branch: ${params.branch}.`,
+            'To preserve the current container state, enter it manually with:',
+            `  ${commandChain[0]}`,
+            'If you intentionally want a replacement, the following is the full interactive sandbox cleanup, not a container-only delete.',
+            'It may remove the worktree, local branch, tool/shell state, and branch share:',
+            `  ${commandChain[1]}`,
+            `  ${commandChain[2]}`,
+            `Details: ${failure.message}`
+        ].join('\n'));
+    }
     const dataBoundary = 'The existing container writable layer, ordinary /tmp data, processes, tmux sessions, and RAM state may be lost by replacement; worktree and host-managed sandbox data are preserved.';
     const recoveryTarget = params.workspace?.mode === 'task-bound'
         ? params.workspace.taskId