@fitlab-ai/agent-infra 0.9.7 → 0.9.9

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

@@ -1,10 +1,11 @@
 import { validateTaskCreateCandidate } from '../../task/create.js';
+import { normalizeAgentToken } from '../../agent-clients/tokens.js';
 export const SANDBOX_CONTROL_MAX_BYTES = 64 * 1024;
 export const SANDBOX_CONTROL_ADMISSION_WINDOW_MS = 2_000;
 export const SANDBOX_CONTROL_STATUS_INTERVAL_MS = 250;
 export const SANDBOX_CONTROL_STATUS_STALE_MS = 1_500;
 export const SANDBOX_CONTROL_FUTURE_SKEW_MS = 1_000;
-export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-create'];
+export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-finalization', 'task-create', 'codex-controller'];
 export const DEFAULT_SANDBOX_CONTROL_TIMING = Object.freeze({
     controlTickMs: 250,
     parkedBindingInitialMs: 1_000,
@@ -33,7 +34,7 @@ export function validateSandboxControlRequest(value, manifest, options = {}) {
         fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request must be an object');
     }
     const request = value;
-    if (request.version !== 2 || typeof request.id !== 'string'
+    if (request.version !== 3 || typeof request.id !== 'string'
         || !/^[a-f0-9-]{16,64}$/.test(request.id) || request.token !== manifest.token
         || typeof request.family !== 'string' || !isSandboxControlFamily(request.family)
         || !Number.isSafeInteger(request.issuedAt) || !Number.isSafeInteger(request.expiresAt))
@@ -53,13 +54,47 @@ export function validateSandboxControlRequest(value, manifest, options = {}) {
         fail('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit');
     }
     if (request.family === 'task-create') {
-        const expected = ['candidate', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+        const expected = ['candidate', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
         if (Object.keys(request).sort().join(',') !== expected.sort().join(',')) {
             fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
         }
+        if (request.controllerProcess !== null || request.controllerProof !== null) {
+            fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-create cannot carry controller authority');
+        }
         return { ...request, candidate: validateTaskCreateCandidate(request.candidate) };
     }
-    const expected = ['args', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+    if (request.family === 'codex-controller') {
+        const expected = ['args', 'command', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+        if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
+            || !Array.isArray(request.args) || request.args.length !== 0
+            || !['open', 'close', 'verify'].includes(request.command)
+            || !validControllerProcess(request.controllerProcess)
+            || (request.command === 'open' && request.controllerProof !== null)
+            || (request.command !== 'open' && !validControllerProof(request.controllerProof))
+            || (request.command === 'verify'
+                && JSON.stringify(request.controllerProcess) !== JSON.stringify(request.controllerProof.controllerProcess))) {
+            fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller request schema is invalid');
+        }
+        if (manifest.mode !== 'task-bound' || !manifest.taskId) {
+            fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot register a Codex controller');
+        }
+        return request;
+    }
+    if (request.family === 'task-finalization') {
+        const expected = ['agent', 'args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'operation', 'token', 'version'];
+        if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
+            || request.operation !== 'complete'
+            || !Array.isArray(request.args) || request.args.length !== 0
+            || typeof request.agent !== 'string' || normalizeAgentToken(request.agent) !== request.agent
+            || request.controllerProcess !== null || request.controllerProof !== null) {
+            fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-finalization request schema or authorization is invalid');
+        }
+        if (manifest.mode !== 'task-bound' || !manifest.taskId) {
+            fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot finalize tasks');
+        }
+        return request;
+    }
+    const expected = ['args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
     if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
         || !Array.isArray(request.args) || !request.args.every((arg) => typeof arg === 'string')) {
         fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
@@ -71,15 +106,41 @@ export function validateSandboxControlRequest(value, manifest, options = {}) {
         && request.args.some((arg) => arg === '--git-worktree-root' || arg.startsWith('--git-worktree-root='))) {
         fail('SANDBOX_CONTROL_REQUEST_INVALID', 'worktree binding is reserved for the control broker');
     }
+    if (request.controllerProcess !== null
+        || (request.controllerProof !== null && !validControllerProof(request.controllerProof))) {
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller authority is invalid');
+    }
+    if (request.family !== 'task-orchestration' && request.controllerProof !== null) {
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller proof is not allowed for this family');
+    }
     return request;
 }
 export function bindSandboxControlTask(request, taskId) {
-    if (request.family === 'task-create')
-        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-create requests do not bind a current task');
+    if (request.family === 'task-create' || request.family === 'codex-controller' || request.family === 'task-finalization') {
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', `${request.family} requests do not bind a current task`);
+    }
     if (request.args.length === 0)
         fail('SANDBOX_CONTROL_REQUEST_INVALID', 'command arguments are required');
     return [taskId, ...request.args.slice(1)];
 }
+function validControllerProcess(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const processValue = value;
+    return Object.keys(processValue).sort().join(',') === 'pid,startTime'
+        && Number.isSafeInteger(processValue.pid) && processValue.pid > 0
+        && Number.isSafeInteger(processValue.startTime) && processValue.startTime >= 0;
+}
+function validControllerProof(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const proof = value;
+    return Object.keys(proof).sort().join(',') === 'controllerProcess,leaseId,leaseSecret,version'
+        && proof.version === 1
+        && typeof proof.leaseId === 'string' && /^[a-f0-9]{64}$/u.test(proof.leaseId)
+        && typeof proof.leaseSecret === 'string' && /^[a-f0-9]{64}$/u.test(proof.leaseSecret)
+        && validControllerProcess(proof.controllerProcess);
+}
 export function controlError(error) {
     if (error instanceof SandboxControlProtocolError) {
         return { code: error.code, message: error.message, retryable: error.retryable };

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

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { buildProcessTreeStopCommand } from '../../server/process-control.js';
-import { processIdentityMatches } from '../../server/process-state.js';
+import { getProcessIdentityState } from '../../server/process-state.js';
 export const SANDBOX_CONTROL_AUDIT_MAX_BYTES = 1024 * 1024;
 export const SANDBOX_CONTROL_EXECUTION_STOP_MS = 2_000;
 function assertRegularFile(filePath) {
@@ -72,7 +72,7 @@ export function readActiveLease(manifest, now = Date.now()) {
         return null;
     return lease;
 }
-export function cleanupStaleSandboxControlLease(manifest, now = Date.now()) {
+export function cleanupStaleSandboxControlLease(manifest, now = Date.now(), options = {}) {
     const filePath = path.join(path.dirname(manifest.publicStatusDir), 'lease.json');
     if (!fs.existsSync(filePath))
         return false;
@@ -87,10 +87,13 @@ export function cleanupStaleSandboxControlLease(manifest, now = Date.now()) {
         || typeof lease.branch !== 'string' || typeof lease.reason !== 'string') {
         throw new Error('SANDBOX_CONTROL_LEASE_INVALID');
     }
-    const stale = lease.generation !== manifest.generation || lease.taskId !== manifest.taskId
-        || lease.branch !== manifest.branch || lease.expiresAt <= now || !processIdentityMatches({
+    const ownerState = (options.identityProbe ?? getProcessIdentityState)({
         pid: lease.owner.pid, startTime: lease.owner.startTime
     });
+    if (ownerState === 'unknown')
+        throw new Error('SANDBOX_CONTROL_LEASE_OWNER_UNAVAILABLE');
+    const stale = lease.generation !== manifest.generation || lease.taskId !== manifest.taskId
+        || lease.branch !== manifest.branch || lease.expiresAt <= now || ownerState === 'dead';
     if (!stale)
         return false;
     if (fs.readFileSync(filePath, 'utf8') !== raw)
@@ -125,29 +128,42 @@ export function readExecution(filePath) {
 export function terminateSandboxControlExecution(execution, options = {}) {
     const platform = options.platform ?? process.platform;
     const processGroupId = execution.child.processGroupId;
-    const processGroupAlive = (groupId) => {
+    const processGroupState = (groupId) => {
         try {
             const rows = execFileSync('ps', ['-axo', 'pgid=,stat='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
             return rows.split('\n').some((row) => {
                 const match = row.trim().match(/^(\d+)\s+(\S+)/);
                 return Number(match?.[1]) === groupId && !match?.[2]?.startsWith('Z');
-            });
+            }) ? 'alive' : 'dead';
         }
         catch {
             try {
                 process.kill(-groupId, 0);
-                return true;
+                return 'alive';
             }
             catch (error) {
-                return error.code === 'EPERM';
+                const code = error.code;
+                if (code === 'ESRCH')
+                    return 'dead';
+                if (code === 'EPERM')
+                    return 'alive';
+                return 'unknown';
             }
         }
     };
-    const treeAlive = () => {
+    const treeState = () => {
         if (platform === 'win32' || !processGroupId) {
-            return processIdentityMatches({ pid: execution.child.pid, startTime: execution.child.startTime });
+            return (options.identityProbe ?? getProcessIdentityState)({
+                pid: execution.child.pid, startTime: execution.child.startTime
+            });
         }
-        return processGroupAlive(processGroupId);
+        return processGroupState(processGroupId);
+    };
+    const treeAlive = () => {
+        const state = treeState();
+        if (state === 'unknown')
+            throw new Error('SANDBOX_CONTROL_EXECUTION_OWNER_UNAVAILABLE');
+        return state === 'alive';
     };
     if (!treeAlive())
         return true;

package/dist/lib/sandbox/engine.js

@@ -14,6 +14,12 @@ const PLATFORM_DEFAULTS = Object.freeze({
     darwin: ENGINES.COLIMA,
     win32: ENGINES.WSL2
 });
+function isPerPlatformEngine(engine) {
+    return typeof engine === 'object' && engine !== null;
+}
+function resolveEngineForPlatform(engine, os) {
+    return isPerPlatformEngine(engine) ? engine[os] : engine;
+}
 function runFns({ runFn = run, runOkFn = runOk, runSafeFn = runSafe, runVerboseFn = runVerbose } = {}) {
     return {
         run: runFn,
@@ -56,23 +62,24 @@ function ensureBuildKit(engine, runOkEngineFn) {
     }
 }
 export function validateSandboxEngine(engine, { platformFn = platform } = {}) {
-    if (engine === null || engine === undefined) {
+    const os = platformFn();
+    const resolved = resolveEngineForPlatform(engine, os);
+    if (resolved === null || resolved === undefined) {
         return null;
     }
-    const os = platformFn();
-    if (!(engine in ADAPTERS)) {
+    if (!(resolved in ADAPTERS)) {
         const known = Object.keys(ADAPTERS).join(', ');
-        throw new Error(`sandbox: invalid "sandbox.engine" value "${engine}" (unknown sandbox engine). `
+        throw new Error(`sandbox: invalid "sandbox.engine" value "${resolved}" (unknown sandbox engine). `
             + `Valid engines: ${known}.`);
     }
-    const adapter = ADAPTERS[engine];
+    const adapter = ADAPTERS[resolved];
     if (!adapter.supportedPlatforms.includes(os)) {
         const supported = enginesForPlatform(os);
         const supportedList = supported.length > 0 ? supported.join(', ') : 'none';
-        throw new Error(`sandbox: "sandbox.engine" value "${engine}" is not supported on ${os}. `
+        throw new Error(`sandbox: "sandbox.engine" value "${resolved}" is not supported on ${os}. `
             + `Supported engines on ${os}: ${supportedList}.`);
     }
-    return engine;
+    return resolved;
 }
 export function detectEngine(config = {}, { platformFn = platform } = {}) {
     const configured = validateSandboxEngine(config.engine, { platformFn });

package/dist/lib/sandbox/index.js

@@ -15,9 +15,11 @@ Commands:
   rebuild [--quiet] [--refresh]
                                Rebuild the sandbox image (--refresh pulls base + tools)
   refresh                      Sync host Claude Code credentials to all sandbox copies
-  rm <branch> | --unbound | --purge
-                               Remove one sandbox, all sandboxes not bound to an
-                               active task (--unbound), or tear down everything (--purge)
+  rm <branch | TASK-id> | --unbound | --purge
+                               Remove one sandbox; use a full TASK-id for task-bound
+                               cleanup and a branch for branch-only cleanup. --unbound
+                               removes completed task-bound and branch-only sandboxes;
+                               active, blocked, and archive tasks are protected.
   start [--recreate] <branch | TASK-id | N>
                                Verify or recover an existing sandbox container;
                                optionally replace only the container on failure

package/dist/lib/sandbox/managed-fs.js

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

package/dist/lib/sandbox/mounts.js

@@ -1,7 +1,19 @@
 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 workspaceMounts = sandboxWorkspaceViewStatePaths(overrides.workspaceViewRoot).map(({ state, hostPath }) => taskBound && state === 'active'
+        ? {
+            hostPaths: [path.join(hostPath, '.short-ids.json')],
+            containerPath: '/workspace/.agents/workspace/active/.short-ids.json',
+            readOnly: true
+        }
+        : {
+            hostPaths: [hostPath],
+            containerPath: path.posix.join('/workspace/.agents/workspace', state),
+            readOnly: true
+        });
     const mounts = [
         {
             hostPaths: overrides.worktree
@@ -10,11 +22,7 @@ export function sandboxCoreBindMounts(config, branch, overrides) {
             containerPath: '/workspace',
             readOnly: false
         },
-        {
-            hostPaths: [overrides.workspaceViewRoot],
-            containerPath: '/workspace/.agents/workspace',
-            readOnly: true
-        },
+        ...workspaceMounts,
     ];
     if (taskBound) {
         mounts.push({
@@ -47,6 +55,13 @@ export function sandboxCoreBindMounts(config, branch, overrides) {
         containerPath: '/run/agent-infra/control',
         readOnly: false
     });
+    if (taskBound && overrides.runtimeDir) {
+        mounts.push({
+            hostPaths: [overrides.runtimeDir],
+            containerPath: '/run/agent-infra/runtime',
+            readOnly: false
+        });
+    }
     return mounts;
 }
 //# sourceMappingURL=mounts.js.map

package/dist/lib/sandbox/recovery.js

@@ -14,7 +14,7 @@ import { inspectWorktree } from './worktree-safety.js';
 import { commandForEngine, runEngine, runOkEngine, runProbe, runVerboseEngine } from './shell.js';
 import { declaredTmpfsSeedEntries, resolveTools, toolConfigDirCandidates } from './tools.js';
 import { fetchSandboxRows, selectSandboxContainer, startSandboxContainer } from './commands/list-running.js';
-import { getProcessStartTime, processIdentityMatches, removePidFileIfMatches } from '../server/process-state.js';
+import { getProcessIdentityState, getProcessStartTime, removePidFileIfMatches } from '../server/process-state.js';
 import { acquireSandboxControlBrokerStartup, garbageCollectSandboxControlRoot, isSandboxControlRootQuiescing, readSandboxControlManifest } from './control/lifecycle.js';
 import { appendSandboxControlAudit, readSandboxControlStatus } from './control/state.js';
 import { inspectSandboxControlContainer } from './control/container-identity.js';
@@ -89,7 +89,10 @@ export async function startSandboxControlBroker(repoRoot, manifestPath) {
         if (broker === null || broker.version !== 3 || owner === null) {
             throw new Error('SANDBOX_CONTROL_BROKER_VERSION_INVALID: rebuild the sandbox container before starting a new broker');
         }
-        const live = owner !== null && processIdentityMatches({ pid: owner.pid, startTime: owner.startTime });
+        const ownerState = getProcessIdentityState({ pid: owner.pid, startTime: owner.startTime });
+        if (ownerState === 'unknown')
+            throw new Error('SANDBOX_CONTROL_BROKER_OWNER_UNAVAILABLE');
+        const live = ownerState === 'alive';
         if (live
             && owner !== null
             && broker !== null
@@ -176,6 +179,15 @@ async function ensureSandboxControlBroker(params) {
     const brokerPath = path.join(control.root, 'broker.json');
     try {
         const broker = JSON.parse(fs.readFileSync(brokerPath, 'utf8'));
+        const validIdentity = typeof broker.pid === 'number'
+            && Number.isSafeInteger(broker.pid)
+            && typeof broker.startTime === 'number'
+            && Number.isSafeInteger(broker.startTime);
+        const ownerState = validIdentity
+            ? getProcessIdentityState({ pid: broker.pid, startTime: broker.startTime })
+            : 'dead';
+        if (ownerState === 'unknown')
+            throw new Error('SANDBOX_CONTROL_BROKER_OWNER_UNAVAILABLE');
         if (broker.version === 3
             && typeof broker.pid === 'number'
             && Number.isSafeInteger(broker.pid)
@@ -185,7 +197,7 @@ async function ensureSandboxControlBroker(params) {
             && broker.brokerId.length > 0
             && broker.token === validatedManifest.token
             && broker.generation === validatedManifest.generation
-            && processIdentityMatches({ pid: broker.pid, startTime: broker.startTime })) {
+            && ownerState === 'alive') {
             try {
                 const status = readSandboxControlStatus(control.statusDir);
                 if (status.generation === validatedManifest.generation && status.broker.pid === broker.pid
@@ -207,7 +219,9 @@ async function ensureSandboxControlBroker(params) {
             return;
         }
     }
-    catch {
+    catch (error) {
+        if (error instanceof Error && error.message === 'SANDBOX_CONTROL_BROKER_OWNER_UNAVAILABLE')
+            throw error;
         // A missing, stale, or malformed broker record is replaced below.
     }
     await startSandboxControlBroker(params.config.repoRoot, control.manifestPath);
@@ -242,6 +256,30 @@ export function classifySandboxRecovery(snapshot) {
             message: 'Container runtime capability signature does not match the current sandbox plan.'
         });
     }
+    if (snapshot.workspaceTopology === 'legacy-parent') {
+        findings.push({
+            repairKind: 'hard-failure',
+            code: 'SANDBOX_WORKSPACE_TOPOLOGY_MISMATCH',
+            message: 'Sandbox uses the legacy workspace parent-mount topology; recreate the container explicitly to migrate it.',
+            path: '/workspace/.agents/workspace'
+        });
+    }
+    if (snapshot.taskView && !snapshot.taskView.readable) {
+        findings.push({
+            repairKind: 'hard-failure',
+            code: 'SANDBOX_TASK_VIEW_UNREADABLE',
+            message: `Bound task view is not readable at ${snapshot.taskView.path}.`,
+            path: snapshot.taskView.path
+        });
+    }
+    if (snapshot.runtimeStoreOk === false) {
+        findings.push({
+            repairKind: 'hard-failure',
+            code: 'SANDBOX_RUNTIME_STORE_UNAVAILABLE',
+            message: 'Task-bound runtime store is not writable and readable by devuser.',
+            path: '/run/agent-infra/runtime'
+        });
+    }
     for (const mountPath of snapshot.unexpectedCapabilityMounts ?? []) {
         findings.push({
             repairKind: 'hard-failure',
@@ -250,6 +288,9 @@ export function classifySandboxRecovery(snapshot) {
         });
     }
     for (const mount of snapshot.mounts) {
+        if (snapshot.workspaceTopology === 'legacy-parent'
+            && mount.path.startsWith('/workspace/.agents/workspace'))
+            continue;
         if (mount.actualType !== mount.expectedType
             || !mount.sourceMatches
             || mount.actualRW !== mount.expectedRW
@@ -331,6 +372,20 @@ function inspectContainer(engine, container, runFn) {
     }
     return parsed[0];
 }
+function workspaceTopology(mountsByDestination) {
+    if (mountsByDestination.has('/workspace/.agents/workspace'))
+        return 'legacy-parent';
+    const perState = [
+        '/workspace/.agents/workspace/active',
+        '/workspace/.agents/workspace/active/.short-ids.json',
+        '/workspace/.agents/workspace/completed',
+        '/workspace/.agents/workspace/blocked',
+        '/workspace/.agents/workspace/archive'
+    ];
+    return perState.some((destination) => mountsByDestination.has(destination))
+        ? 'per-state'
+        : 'unknown';
+}
 function probe(engine, container, script, args, runOkFn, user = 'devuser') {
     return runOkFn(engine, 'docker', [
         'exec', '--user', user, container, 'sh', '-c', script, 'agent-infra-recovery', ...args
@@ -391,6 +446,7 @@ function expectedMounts(params) {
         controlStatusDir: control.statusDir,
         ...(params.workspace.mode === 'task-bound'
             ? {
+                runtimeDir: control.runtimeDir,
                 taskSource: assertSandboxTaskSource(config.repoRoot, params.workspace.taskId),
                 taskId: params.workspace.taskId
             }
@@ -489,6 +545,10 @@ export function collectSandboxRecoverySnapshot(params) {
     const capabilityPlan = createSandboxCapabilityPlan(params.config);
     const workspace = params.workspace ?? { mode: 'branch-only' };
     const tools = [...capabilityPlan.tools];
+    const topology = workspaceTopology(mountsByDestination);
+    const taskViewPath = workspace.mode === 'task-bound'
+        ? `/workspace/.agents/workspace/active/${workspace.taskId}/task.md`
+        : null;
     const seeds = declaredTmpfsSeedEntries(tools).map((seed) => {
         const mounted = mountsByDestination.get(seed.stagingPath)?.Type === 'bind';
         return {
@@ -507,6 +567,9 @@ export function collectSandboxRecoverySnapshot(params) {
         permissionsOk: probe(params.engine, params.container, 'test "$(stat -c %u:%g:%a -- "$1")" = "$(id -u devuser):$(id -g devuser):700"', [tool.containerMount], runOkFn),
         writable: probe(params.engine, params.container, 'probe="$1/.agent-infra-ready-$$"; trap \'rm -f -- "$probe"\' EXIT; : > "$probe"', [tool.containerMount], runOkFn)
     }));
+    const runtimeStoreOk = workspace.mode === 'task-bound'
+        ? probe(params.engine, params.container, 'probe="$1/.agent-infra-runtime-$$"; trap \'rm -f -- "$probe"\' EXIT; printf runtime-probe > "$probe" && test "$(cat -- "$probe")" = runtime-probe', ['/run/agent-infra/runtime'], runOkFn)
+        : undefined;
     const labels = inspection.Config?.Labels ?? {};
     const branchLabel = labels[sandboxBranchLabel(params.config)];
     const containerWorkspace = parseSandboxWorkspaceIdentity(labels, {
@@ -562,6 +625,14 @@ export function collectSandboxRecoverySnapshot(params) {
         actualBranch: typeof branchLabel === 'string' ? branchLabel : null,
         expectedWorkspace: workspace,
         actualWorkspace: containerWorkspace,
+        workspaceTopology: topology,
+        ...(taskViewPath === null ? {} : {
+            taskView: {
+                path: taskViewPath,
+                readable: probe(params.engine, params.container, 'test -r "$1"', [taskViewPath], runOkFn)
+            }
+        }),
+        ...(runtimeStoreOk === undefined ? {} : { runtimeStoreOk }),
         identityOk: typeof inspection.Id === 'string' && inspection.Id.length > 0
             && branchLabel === params.branch
             && sameSandboxWorkspaceIdentity(containerWorkspace, workspace),
@@ -677,10 +748,12 @@ function assess(params) {
 }
 function canRetryFreshReadiness(findings) {
     return findings.length > 0 && findings.every((finding) => finding.repairKind === 'hard-failure'
+        && finding.code !== 'SANDBOX_WORKSPACE_TOPOLOGY_MISMATCH'
         && finding.path !== undefined
         && (finding.path.startsWith('/workspace/.agents/workspace')
             || finding.path === '/home/devuser/.host-shell-config'
-            || finding.path === '/home/devuser/.bash_aliases'));
+            || finding.path === '/home/devuser/.bash_aliases'
+            || finding.path === '/run/agent-infra/runtime'));
 }
 export async function assertFreshSandboxReady(params) {
     validateTmpfsSeedEntries({
@@ -891,14 +964,9 @@ export async function ensureSandboxReady(params) {
         : `Sandbox recovery failed in place. Replacing only the container. ${dataBoundary}`;
     warnings.push(warning);
     (params.writeWarning ?? ((message) => process.stderr.write(`${message}\n`)))(warning);
-    const runVerboseFn = deps?.runVerbose ?? runVerboseEngine;
     let replacementResult = null;
     let replacementFailure = null;
     try {
-        if (params.row.running) {
-            runVerboseFn(params.engine, 'docker', ['stop', params.row.name]);
-        }
-        runVerboseFn(params.engine, 'docker', ['rm', params.row.name]);
         await params.recreate(params.branch);
         const rows = (deps?.fetchRows ?? fetchSandboxRows)(params.engine, sandboxLabel(params.config), sandboxBranchLabel(params.config));
         const replacement = selectSandboxContainer([...rows.running, ...rows.nonRunning], containerNameCandidates(params.config, params.branch));

package/dist/lib/sandbox/task-resolver.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { isRemovedHashShortIdInput } from '../task/short-id.js';
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const SHORT_ID_RE = /^\d+$/;
-const WORKSPACE_DIRS = ['active', 'completed', 'blocked', 'archive'];
+export const TASK_WORKSPACE_STATES = ['active', 'completed', 'blocked', 'archive'];
 function resolveShortIdStrict(arg, repoRoot) {
     const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
     if (!fs.existsSync(scriptPath)) {
@@ -20,14 +20,28 @@ function stripQuotes(value) {
     return value.replace(/^(["'])(.*)\1$/, '$2');
 }
 function readTaskContent(repoRoot, taskId) {
-    for (const dir of WORKSPACE_DIRS) {
-        const taskPath = path.join(repoRoot, '.agents', 'workspace', dir, taskId, 'task.md');
+    for (const state of TASK_WORKSPACE_STATES) {
+        const taskPath = path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
         if (fs.existsSync(taskPath)) {
-            return fs.readFileSync(taskPath, 'utf8');
+            return { content: fs.readFileSync(taskPath, 'utf8'), state, taskMd: taskPath };
         }
     }
     throw new Error(`Task not found: ${taskId}`);
 }
+function taskWorkspaceCandidates(repoRoot, taskId) {
+    return TASK_WORKSPACE_STATES.flatMap((state) => {
+        const taskMd = path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
+        if (!fs.existsSync(taskMd))
+            return [];
+        const content = fs.readFileSync(taskMd, 'utf8');
+        return [{
+                taskId,
+                branch: resolveBranchFromTaskContent(content, taskId),
+                state,
+                taskMd
+            }];
+    });
+}
 function resolveBranchFromTaskContent(content, taskId) {
     const frontmatterBranch = content.match(/^branch:\s*(.+)$/m);
     if (frontmatterBranch?.[1]?.trim()) {
@@ -45,13 +59,43 @@ export function resolveTaskBranch(arg, repoRoot) {
     }
     if (SHORT_ID_RE.test(arg)) {
         const taskId = resolveShortIdStrict(arg, repoRoot);
-        const content = readTaskContent(repoRoot, taskId);
+        const { content } = readTaskContent(repoRoot, taskId);
         return resolveBranchFromTaskContent(content, taskId);
     }
     if (!TASK_ID_RE.test(arg)) {
         return arg;
     }
-    const content = readTaskContent(repoRoot, arg);
+    const { content } = readTaskContent(repoRoot, arg);
     return resolveBranchFromTaskContent(content, arg);
 }
+export function resolveTaskWorkspace(taskId, repoRoot) {
+    if (!TASK_ID_RE.test(taskId))
+        throw new Error(`Invalid task id: ${taskId}`);
+    const matches = taskWorkspaceCandidates(repoRoot, taskId);
+    if (matches.length === 0)
+        throw new Error(`Task not found: ${taskId}`);
+    if (matches.length !== 1) {
+        throw new Error(`SANDBOX_TASK_STATE_AMBIGUOUS: task ${taskId} exists in ${matches.map((match) => match.state).join(', ')}`);
+    }
+    return matches[0];
+}
+export function listTaskWorkspaces(repoRoot, state) {
+    const stateRoot = path.join(repoRoot, '.agents', 'workspace', state);
+    if (!fs.existsSync(stateRoot))
+        return [];
+    return fs.readdirSync(stateRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && TASK_ID_RE.test(entry.name))
+        .flatMap((entry) => {
+        const taskMd = path.join(stateRoot, entry.name, 'task.md');
+        if (!fs.existsSync(taskMd))
+            return [];
+        const content = fs.readFileSync(taskMd, 'utf8');
+        return [{
+                taskId: entry.name,
+                branch: resolveBranchFromTaskContent(content, entry.name),
+                state,
+                taskMd
+            }];
+    });
+}
 //# sourceMappingURL=task-resolver.js.map

package/dist/lib/sandbox/workspace-identity.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { isRemovedHashShortIdInput } from '../task/short-id.js';
+import { resolveTaskWorkspace } from './task-resolver.js';
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const SHORT_ID_RE = /^\d+$/;
 function stripQuotes(value) {
@@ -78,6 +79,32 @@ export function resolveSandboxTarget(requestedRef, repoRoot) {
     }
     return { requestedRef, branch: requestedRef, workspace: { mode: 'branch-only' } };
 }
+export function resolveSandboxCleanupTarget(requestedRef, repoRoot, options = {}) {
+    if (isRemovedHashShortIdInput(requestedRef)) {
+        throw new Error(`Invalid task short id '${requestedRef}': task short ids must use bare digits`);
+    }
+    if (TASK_ID_RE.test(requestedRef)) {
+        const task = resolveTaskWorkspace(requestedRef, repoRoot);
+        if (!options.allowProtected && (task.state === 'blocked' || task.state === 'archive')) {
+            throw new Error(`SANDBOX_CLEANUP_STATE_UNSUPPORTED: task ${requestedRef} is ${task.state}`);
+        }
+        return {
+            requestedRef,
+            branch: task.branch,
+            workspace: { mode: 'task-bound', taskId: task.taskId },
+            taskState: task.state
+        };
+    }
+    const target = resolveSandboxTarget(requestedRef, repoRoot);
+    return {
+        requestedRef,
+        branch: target.branch,
+        workspace: target.workspace.mode === 'task-bound'
+            ? { mode: 'task-bound', taskId: target.workspace.taskId }
+            : { mode: 'branch-only' },
+        taskState: target.workspace.mode === 'task-bound' ? 'active' : 'branch-only'
+    };
+}
 export function parseSandboxWorkspaceIdentity(labels, keys) {
     const mode = labels[keys.mode];
     const taskId = labels[keys.taskId];