@fitlab-ai/agent-infra 0.9.5 → 0.9.7

package/dist/lib/sandbox/recovery.js

@@ -2,18 +2,158 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { containerNameCandidates, sandboxBranchLabel, sandboxLabel, sandboxRuntimeCapabilityLabel, sandboxTaskIdLabel, sandboxWorkspaceModeLabel } from './constants.js';
+import { nodeEntryArgs } from './control/executor.js';
+import { containerNameCandidates, sandboxBranchLabel, sandboxLabel, sandboxRuntimeCapabilityLabel, sandboxTaskIdLabel, sandboxWorkspaceModeLabel, worktreeDirCandidates } from './constants.js';
 import { isAgentClientId } from '../agent-clients/types.js';
 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 { parseSandboxWorkspaceIdentity, sameSandboxWorkspaceIdentity } from './workspace-identity.js';
-import { runEngine, runOkEngine, runVerboseEngine } from './shell.js';
+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 { processIdentityMatches } from '../server/process-state.js';
-function ensureSandboxControlBroker(params) {
+import { getProcessStartTime, processIdentityMatches, 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';
+import { SANDBOX_CONTROL_FUTURE_SKEW_MS, SANDBOX_CONTROL_STATUS_STALE_MS } from './control/protocol.js';
+export function worktreeProbeForEngine(engine, probe = runProbe) {
+    return (cmd, args, opts = {}) => {
+        const engineArgs = [...args];
+        if (engine === 'wsl2' && cmd === 'git') {
+            for (let index = 0; index < engineArgs.length - 1; index += 1) {
+                if (engineArgs[index] === '-C') {
+                    engineArgs[index + 1] = toEnginePath(engine, engineArgs[index + 1]);
+                }
+            }
+        }
+        const command = commandForEngine(engine, cmd, engineArgs);
+        return probe(command.cmd, command.args, opts);
+    };
+}
+async function waitForSandboxControlBrokerStatus(params, timeoutMs = 5_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (isSandboxControlRootQuiescing(params.root))
+            throw new Error('SANDBOX_CONTROL_QUIESCING');
+        try {
+            const status = readSandboxControlStatus(params.statusDir);
+            if (status.generation === params.generation && status.broker.pid === params.pid
+                && (!params.startTime || status.broker.startTime === params.startTime)
+                && Date.now() - status.updatedAt <= SANDBOX_CONTROL_STATUS_STALE_MS
+                && status.updatedAt <= Date.now() + SANDBOX_CONTROL_FUTURE_SKEW_MS)
+                return;
+        }
+        catch {
+            // The broker may still be publishing its initial atomic status.
+        }
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    throw new Error('SANDBOX_CONTROL_BROKER_START_TIMEOUT');
+}
+export async function startSandboxControlBroker(repoRoot, manifestPath) {
+    const directory = path.dirname(fileURLToPath(import.meta.url));
+    const extension = path.extname(fileURLToPath(import.meta.url));
+    const internalCli = path.resolve(directory, '..', '..', 'bin', `internal-cli${extension}`);
+    const manifest = readSandboxControlManifest(manifestPath);
+    const root = path.dirname(manifestPath);
+    if (isSandboxControlRootQuiescing(root))
+        throw new Error('SANDBOX_CONTROL_QUIESCING');
+    const brokerPath = path.join(root, 'broker.json');
+    let brokerSnapshot = null;
+    let replacedBrokerRecord = false;
+    try {
+        brokerSnapshot = fs.readFileSync(brokerPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (brokerSnapshot !== null) {
+        let broker = null;
+        try {
+            broker = JSON.parse(brokerSnapshot);
+        }
+        catch {
+            // Malformed owner records are stale and replaced below.
+        }
+        const owner = broker !== null && broker.version === 3 && typeof broker.pid === 'number'
+            && Number.isSafeInteger(broker.pid) && broker.pid > 0 && typeof broker.startTime === 'number'
+            && Number.isSafeInteger(broker.startTime) && typeof broker.brokerId === 'string'
+            && broker.brokerId.length > 0 && typeof broker.token === 'string'
+            && typeof broker.generation === 'string'
+            ? broker
+            : null;
+        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 });
+        if (live
+            && owner !== null
+            && broker !== null
+            && broker.version === 3
+            && broker.token === manifest.token
+            && broker.generation === manifest.generation) {
+            await waitForSandboxControlBrokerStatus({
+                root,
+                statusDir: manifest.publicStatusDir,
+                generation: manifest.generation,
+                pid: owner.pid,
+                startTime: owner.startTime
+            });
+            return;
+        }
+    }
+    const startupStartTime = getProcessStartTime(process.pid);
+    if (!startupStartTime)
+        throw new Error('SANDBOX_CONTROL_BROKER_IDENTITY_UNAVAILABLE');
+    const releaseStartup = await acquireSandboxControlBrokerStartup(root, {
+        pid: process.pid,
+        startTime: startupStartTime
+    });
+    let child;
+    try {
+        const currentBroker = fs.existsSync(brokerPath) ? fs.readFileSync(brokerPath, 'utf8') : null;
+        if (currentBroker !== brokerSnapshot)
+            return startSandboxControlBroker(repoRoot, manifestPath);
+        if (brokerSnapshot !== null) {
+            replacedBrokerRecord = removePidFileIfMatches(brokerPath, brokerSnapshot);
+            if (!replacedBrokerRecord && fs.existsSync(brokerPath)) {
+                throw new Error('SANDBOX_CONTROL_BROKER_OWNER_TRANSITION');
+            }
+        }
+        if (replacedBrokerRecord) {
+            appendSandboxControlAudit(manifest, 'broker-observed-crash');
+            appendSandboxControlAudit(manifest, 'broker-restart');
+        }
+        child = spawn(process.execPath, nodeEntryArgs(internalCli, ['sandbox-control', 'serve', '--manifest', manifestPath]), { cwd: repoRoot, detached: true, stdio: 'ignore' });
+    }
+    finally {
+        releaseStartup();
+    }
+    let spawnError = null;
+    child.once('error', (error) => { spawnError = error; });
+    child.unref();
+    if (!child.pid)
+        throw new Error('SANDBOX_CONTROL_BROKER_START_FAILED');
+    try {
+        await waitForSandboxControlBrokerStatus({
+            root,
+            statusDir: manifest.publicStatusDir,
+            generation: manifest.generation,
+            pid: child.pid
+        });
+    }
+    catch (error) {
+        child.kill('SIGTERM');
+        if (spawnError)
+            throw spawnError;
+        throw error;
+    }
+}
+async function ensureSandboxControlBroker(params) {
     const control = sandboxControlPaths({
         base: params.config.controlBase ?? path.join(params.config.home, '.agent-infra', 'sandbox-control'),
         project: params.config.project,
@@ -22,31 +162,55 @@ function ensureSandboxControlBroker(params) {
     });
     if (!fs.existsSync(control.manifestPath))
         return;
-    const manifest = JSON.parse(fs.readFileSync(control.manifestPath, 'utf8'));
+    const validatedManifest = readSandboxControlManifest(control.manifestPath);
+    const containerObservation = await inspectSandboxControlContainer(validatedManifest);
+    if (containerObservation.state === 'unknown') {
+        throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${containerObservation.reason}`);
+    }
+    if (containerObservation.state === 'absent') {
+        await garbageCollectSandboxControlRoot(control.root, {
+            inspectContainer: (timeoutMs) => inspectSandboxControlContainer(validatedManifest, { timeoutMs })
+        });
+        throw new Error('SANDBOX_CONTROL_CONTAINER_ABSENT: recreate the sandbox container before broker recovery');
+    }
     const brokerPath = path.join(control.root, 'broker.json');
     try {
         const broker = JSON.parse(fs.readFileSync(brokerPath, 'utf8'));
-        if (broker.version === 1
+        if (broker.version === 3
             && typeof broker.pid === 'number'
-            && typeof broker.startTime === 'string'
-            && broker.token === manifest.token
-            && processIdentityMatches({ version: 1, pid: broker.pid, startTime: broker.startTime }))
+            && Number.isSafeInteger(broker.pid)
+            && typeof broker.startTime === 'number'
+            && Number.isSafeInteger(broker.startTime)
+            && typeof broker.brokerId === 'string'
+            && broker.brokerId.length > 0
+            && broker.token === validatedManifest.token
+            && broker.generation === validatedManifest.generation
+            && processIdentityMatches({ pid: broker.pid, startTime: broker.startTime })) {
+            try {
+                const status = readSandboxControlStatus(control.statusDir);
+                if (status.generation === validatedManifest.generation && status.broker.pid === broker.pid
+                    && status.broker.startTime === broker.startTime
+                    && Date.now() - status.updatedAt <= SANDBOX_CONTROL_STATUS_STALE_MS
+                    && status.updatedAt <= Date.now() + SANDBOX_CONTROL_FUTURE_SKEW_MS)
+                    return;
+            }
+            catch {
+                // A verified live owner may still be publishing its initial status.
+            }
+            await waitForSandboxControlBrokerStatus({
+                root: control.root,
+                statusDir: control.statusDir,
+                generation: validatedManifest.generation,
+                pid: broker.pid,
+                startTime: broker.startTime
+            });
             return;
+        }
     }
     catch {
         // A missing, stale, or malformed broker record is replaced below.
     }
-    fs.rmSync(brokerPath, { force: true });
-    const directory = path.dirname(fileURLToPath(import.meta.url));
-    const extension = path.extname(fileURLToPath(import.meta.url));
-    const internalCli = path.resolve(directory, '..', '..', 'bin', `internal-cli${extension}`);
-    const child = spawn(process.execPath, [internalCli, 'sandbox-control', 'serve', '--manifest', control.manifestPath], { cwd: params.config.repoRoot, detached: true, stdio: 'ignore' });
-    child.once('error', () => {
-        // Readiness remains fail-closed; a later control request reports the
-        // unavailable broker without turning this detached spawn into an
-        // unhandled process error.
-    });
-    child.unref();
+    await startSandboxControlBroker(params.config.repoRoot, control.manifestPath);
 }
 function findingKey(finding) {
     return `${finding.repairKind}:${finding.path ?? finding.seed?.targetPath ?? finding.message}`;
@@ -54,9 +218,22 @@ function findingKey(finding) {
 export function classifySandboxRecovery(snapshot) {
     const findings = [];
     if (!snapshot.identityOk) {
+        const branchOnly = snapshot.containerIdValid
+            && snapshot.actualBranch === snapshot.expectedBranch
+            && snapshot.expectedWorkspace.mode === 'task-bound'
+            && snapshot.actualWorkspace.mode === 'branch-only';
+        const expectedIdentity = snapshot.expectedWorkspace.mode === 'task-bound'
+            ? `task-bound:${snapshot.expectedWorkspace.taskId}`
+            : snapshot.expectedWorkspace.mode;
+        const actualIdentity = snapshot.actualWorkspace.mode === 'task-bound'
+            ? `task-bound:${snapshot.actualWorkspace.taskId}`
+            : snapshot.actualWorkspace.mode;
         findings.push({
             repairKind: 'hard-failure',
-            message: 'Container identity does not match the requested sandbox branch.'
+            code: branchOnly ? 'SANDBOX_CONTROL_BRANCH_ONLY' : 'SANDBOX_WORKSPACE_IDENTITY_CONFLICT',
+            message: branchOnly
+                ? `Container is branch-only but the requested sandbox is ${expectedIdentity}.`
+                : `Container identity ${actualIdentity} on branch ${snapshot.actualBranch ?? 'unknown'} does not match requested ${expectedIdentity} on branch ${snapshot.expectedBranch}.`
         });
     }
     if (snapshot.runtimeCapabilityOk === false) {
@@ -211,6 +388,7 @@ function expectedMounts(params) {
     const core = sandboxCoreBindMounts(config, branch, {
         workspaceViewRoot: view.root,
         controlDir: control.channelDir,
+        controlStatusDir: control.statusDir,
         ...(params.workspace.mode === 'task-bound'
             ? {
                 taskSource: assertSandboxTaskSource(config.repoRoot, params.workspace.taskId),
@@ -379,8 +557,12 @@ export function collectSandboxRecoverySnapshot(params) {
         };
     });
     return {
-        identityOk: typeof inspection.Id === 'string'
-            && inspection.Id.length > 0
+        containerIdValid: typeof inspection.Id === 'string' && inspection.Id.length > 0,
+        expectedBranch: params.branch,
+        actualBranch: typeof branchLabel === 'string' ? branchLabel : null,
+        expectedWorkspace: workspace,
+        actualWorkspace: containerWorkspace,
+        identityOk: typeof inspection.Id === 'string' && inspection.Id.length > 0
             && branchLabel === params.branch
             && sameSandboxWorkspaceIdentity(containerWorkspace, workspace),
         runtimeCapabilityOk: enforceCanonicalPlan
@@ -487,7 +669,7 @@ function repairFindings(params) {
     }
 }
 function describeFindings(findings) {
-    return findings.map((finding) => finding.message).join(' ');
+    return findings.map((finding) => finding.code ? `${finding.code}: ${finding.message}` : finding.message).join(' ');
 }
 function assess(params) {
     const snapshot = collectSandboxRecoverySnapshot(params);
@@ -547,12 +729,20 @@ export async function ensureSandboxReady(params) {
     const startFn = deps?.start ?? startSandboxContainer;
     const warnings = [];
     let failure = null;
-    ensureSandboxControlBroker({
-        config: params.config,
-        container: params.row.name,
-        workspace: params.workspace ?? { mode: 'branch-only' }
-    });
     try {
+        if (deps?.ensureControlBroker) {
+            await deps.ensureControlBroker();
+        }
+        else {
+            await ensureSandboxControlBroker({
+                config: params.config,
+                container: params.row.name,
+                workspace: params.workspace ?? { mode: 'branch-only' }
+            });
+        }
+        if (params.forceRecreate) {
+            throw new Error('Explicit container recreation requested.');
+        }
         if (!params.row.running) {
             startFn(params.engine, params.row.name);
             const initial = assess({
@@ -668,34 +858,78 @@ export async function ensureSandboxReady(params) {
         failure = error instanceof Error ? error : new Error(String(error));
     }
     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
+        : params.branch;
     if (!params.allowRecreate || !params.recreate) {
-        throw new Error(`Sandbox recovery failed: ${failure.message} ${dataBoundary} Re-run with --recreate to authorize container-only replacement.`);
+        throw new Error([
+            `Sandbox recovery failed. Run 'ai sandbox start --recreate ${recoveryTarget}' on the host to authorize container-only replacement.`,
+            dataBoundary,
+            `Details: ${failure.message}`
+        ].join('\n'));
+    }
+    const existingWorktrees = worktreeDirCandidates(params.config, params.branch).filter((candidate) => fs.existsSync(candidate));
+    if (existingWorktrees.length !== 1) {
+        const remediation = existingWorktrees.length === 0
+            ? `Restore the worktree for '${params.branch}' before recovering the container.`
+            : `Found ${existingWorktrees.map((candidate) => JSON.stringify(candidate)).join(', ')}; `
+                + 'keep the worktree in use, remove the stale directory, then retry.';
+        throw new Error(`SANDBOX_RECOVERY_WORKTREE_SNAPSHOT_INVALID: expected exactly one existing worktree for '${params.branch}', found ${existingWorktrees.length}. ${remediation}`);
     }
-    const warning = `Sandbox recovery failed in place. Replacing only the container. ${dataBoundary}`;
+    const worktreeProbe = worktreeProbeForEngine(params.engine, deps?.probe);
+    const beforeInspection = inspectWorktree(existingWorktrees[0], { probe: worktreeProbe });
+    if (beforeInspection.status === 'failed') {
+        throw new Error(`SANDBOX_RECOVERY_WORKTREE_SNAPSHOT_INVALID: ${beforeInspection.message}`);
+    }
+    const before = beforeInspection.snapshot;
+    if (before.branch !== params.branch) {
+        throw new Error(`SANDBOX_RECOVERY_WORKTREE_SNAPSHOT_INVALID: expected branch '${params.branch}', found '${before.branch}'. `
+            + `Run 'git -C ${JSON.stringify(before.worktree)} checkout ${params.branch}' to restore the expected branch, then retry.`);
+    }
+    const warning = params.forceRecreate
+        ? `Explicit sandbox recreation requested. Replacing only the container. ${dataBoundary}`
+        : `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;
-    if (params.row.running) {
-        runVerboseFn(params.engine, 'docker', ['stop', params.row.name]);
+    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));
+        if (!replacement?.running) {
+            throw new Error('Replacement sandbox container was not found in a running state.');
+        }
+        const final = assess({
+            config: params.config,
+            engine: params.engine,
+            branch: params.branch,
+            workspace: params.workspace,
+            container: replacement.name,
+            deps
+        });
+        if (final.findings.length > 0) {
+            throw new Error(`Replacement sandbox readiness check failed: ${describeFindings(final.findings)}`);
+        }
+        replacementResult = { container: replacement.name, path: 'recreated', warnings };
     }
-    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));
-    if (!replacement?.running) {
-        throw new Error('Replacement sandbox container was not found in a running state.');
+    catch (error) {
+        replacementFailure = error;
     }
-    const final = assess({
-        config: params.config,
-        engine: params.engine,
-        branch: params.branch,
-        workspace: params.workspace,
-        container: replacement.name,
-        deps
-    });
-    if (final.findings.length > 0) {
-        throw new Error(`Replacement sandbox readiness check failed: ${describeFindings(final.findings)}`);
+    const afterInspection = inspectWorktree(before.worktree, { probe: worktreeProbe });
+    if (afterInspection.status === 'failed' || afterInspection.snapshot.identity !== before.identity) {
+        const detail = afterInspection.status === 'failed'
+            ? afterInspection.message
+            : `snapshot changed from ${before.identity} to ${afterInspection.snapshot.identity}`;
+        throw new Error(`SANDBOX_RECOVERY_WORKTREE_CHANGED: ${detail}`, replacementFailure === null ? undefined : { cause: replacementFailure });
     }
-    return { container: replacement.name, path: 'recreated', warnings };
+    if (replacementFailure !== null)
+        throw replacementFailure;
+    return replacementResult;
 }
 //# sourceMappingURL=recovery.js.map

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

@@ -1,6 +1,18 @@
 import { createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+export const SANDBOX_WORKSPACE_VIEW_STATES = Object.freeze([
+    'active',
+    'completed',
+    'blocked',
+    'archive'
+]);
+export function sandboxWorkspaceViewStatePaths(root) {
+    return SANDBOX_WORKSPACE_VIEW_STATES.map((state) => ({
+        state,
+        hostPath: path.join(root, state)
+    }));
+}
 export function sandboxWorkspaceViewPaths(params) {
     const identityKey = params.identity.mode === 'task-bound'
         ? `task-bound:${params.identity.taskId}`
@@ -21,7 +33,13 @@ export function sandboxControlPaths(params) {
         : 'branch-only';
     const digest = createHash('sha256').update(identityKey).digest('hex').slice(0, 16);
     const root = path.resolve(params.base, params.project, params.container, digest);
-    return { root, channelDir: path.join(root, 'channel'), manifestPath: path.join(root, 'manifest.json') };
+    return {
+        root,
+        channelDir: path.join(root, 'channel'),
+        statusDir: path.join(root, 'public'),
+        processingDir: path.join(root, 'processing'),
+        manifestPath: path.join(root, 'manifest.json')
+    };
 }
 function assertSafeDirectory(directory, expectedBase) {
     const relative = path.relative(expectedBase, directory);
@@ -47,17 +65,53 @@ export function assertSandboxTaskSource(repoRoot, taskId) {
     }
     return canonical;
 }
+export function prepareSandboxWorkspaceMountTarget(worktreeRoot) {
+    const worktree = path.resolve(worktreeRoot);
+    const canonicalWorktree = fs.realpathSync.native(worktree);
+    const agentsRoot = path.join(worktree, '.agents');
+    if (fs.existsSync(agentsRoot)) {
+        const agentsStat = fs.lstatSync(agentsRoot);
+        if (!agentsStat.isDirectory() || agentsStat.isSymbolicLink()) {
+            throw new Error(`Sandbox workspace mount ancestor must be a real directory: ${agentsRoot}`);
+        }
+    }
+    else {
+        fs.mkdirSync(agentsRoot, { mode: 0o700 });
+    }
+    const canonicalAgents = fs.realpathSync.native(agentsRoot);
+    if (path.dirname(canonicalAgents) !== canonicalWorktree) {
+        throw new Error(`Sandbox workspace mount ancestor escapes the worktree: ${agentsRoot}`);
+    }
+    const target = path.join(agentsRoot, 'workspace');
+    if (fs.existsSync(target)) {
+        const stat = fs.lstatSync(target);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Sandbox workspace mount target must not be a symbolic link: ${target}`);
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`Sandbox workspace mount target must be a directory: ${target}`);
+        }
+        if (path.dirname(fs.realpathSync.native(target)) !== canonicalAgents) {
+            throw new Error(`Sandbox workspace mount target escapes the worktree: ${target}`);
+        }
+    }
+    else {
+        fs.mkdirSync(target, { mode: 0o700 });
+    }
+    fs.chmodSync(target, 0o700);
+    fs.accessSync(target, fs.constants.W_OK);
+    return target;
+}
 export function materializeSandboxWorkspaceView(params) {
     const projectRoot = path.resolve(params.base, params.project);
     const { root, taskMountPath } = sandboxWorkspaceViewPaths(params);
     assertSafeDirectory(projectRoot, path.resolve(params.base));
     assertSafeDirectory(root, projectRoot);
     fs.mkdirSync(root, { recursive: true, mode: 0o700 });
-    for (const state of ['active', 'completed', 'blocked', 'archive']) {
-        const stateDir = path.join(root, state);
-        assertSafeDirectory(stateDir, root);
-        fs.rmSync(stateDir, { recursive: true, force: true });
-        fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+    for (const { hostPath } of sandboxWorkspaceViewStatePaths(root)) {
+        assertSafeDirectory(hostPath, root);
+        fs.rmSync(hostPath, { recursive: true, force: true });
+        fs.mkdirSync(hostPath, { recursive: true, mode: 0o700 });
     }
     const active = path.join(root, 'active');
     const registry = {
@@ -77,12 +131,16 @@ export function materializeSandboxWorkspaceView(params) {
     return { root, taskMountPath };
 }
 export function materializeSandboxControl(params) {
-    const { root, channelDir, manifestPath } = sandboxControlPaths(params);
+    const { root, channelDir, statusDir, processingDir, manifestPath } = sandboxControlPaths(params);
     assertSafeDirectory(root, path.resolve(params.base));
     const consumedDir = path.join(root, 'consumed');
     assertSafeDirectory(consumedDir, root);
     fs.rmSync(consumedDir, { recursive: true, force: true });
     fs.mkdirSync(consumedDir, { recursive: true, mode: 0o700 });
+    for (const directory of [statusDir, processingDir]) {
+        assertSafeDirectory(directory, root);
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    }
     for (const queue of ['requests', 'responses']) {
         const directory = path.join(channelDir, queue);
         assertSafeDirectory(directory, root);
@@ -90,20 +148,42 @@ export function materializeSandboxControl(params) {
         fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
     }
     const token = randomBytes(32).toString('hex');
+    const generation = randomBytes(16).toString('hex');
     const repoRoot = fs.realpathSync.native(params.repoRoot);
     const manifest = {
-        version: 2,
+        version: 4,
+        engine: params.engine ?? 'docker',
         repoRoot,
         worktreeRoot: fs.realpathSync.native(params.worktreeRoot),
         project: params.project,
         container: params.container,
+        containerIdentity: { id: '', labels: {} },
         branch: params.branch,
         mode: params.identity.mode,
         taskId: params.identity.mode === 'task-bound' ? params.identity.taskId : null,
         token,
-        channelDir
+        generation,
+        channelDir,
+        publicStatusDir: statusDir,
+        processingDir
     };
     fs.writeFileSync(manifestPath, `${JSON.stringify(manifest)}\n`, { mode: 0o600 });
-    return { channelDir, manifestPath, token };
+    return { root, channelDir, statusDir, manifestPath, token, generation };
+}
+export function finalizeSandboxControlManifest(setup, identity) {
+    if (!identity.engine || !identity.id)
+        throw new Error('SANDBOX_CONTROL_CONTAINER_ID_INVALID');
+    const manifest = JSON.parse(fs.readFileSync(setup.manifestPath, 'utf8'));
+    manifest.version = 4;
+    manifest.engine = identity.engine;
+    manifest.containerIdentity = { id: identity.id, labels: { ...identity.labels } };
+    const temporary = `${setup.manifestPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(manifest)}\n`, { mode: 0o600, flag: 'wx' });
+        fs.renameSync(temporary, setup.manifestPath);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
 }
 //# sourceMappingURL=workspace-view.js.map