@fitlab-ai/agent-infra 0.9.4 → 0.9.6

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

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { run, runSafe } from './shell.js';
 import { removeDirRecursive } from '../remove-dir.js';
+import { verifyWorktreePermit } from './worktree-safety.js';
 export function assertManagedPath(root, target) {
     const resolvedRoot = path.resolve(root);
     const resolvedTarget = path.resolve(target);
@@ -14,15 +15,26 @@ export function removeManagedDir(root, dir) {
     assertManagedPath(root, dir);
     removeDirRecursive(dir);
 }
-export function removeWorktreeDir(repoRoot, worktreeBase, dir, { runFn = run, runSafeFn = runSafe } = {}) {
+export function removeWorktreeDir(repoRoot, worktreeBase, dir, permit, { runFn = run, runSafeFn = runSafe, allowRegisteredPathFallback = false } = {}) {
+    assertManagedPath(worktreeBase, dir);
+    if (path.resolve(permit.snapshot.worktree) !== path.resolve(dir)) {
+        throw new Error(`Worktree permit target mismatch: ${dir}`);
+    }
+    verifyWorktreePermit(permit);
     try {
         runFn('git', ['-C', repoRoot, 'worktree', 'remove', dir, '--force']);
     }
-    catch {
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const registeredPathMismatch = /(?:is not|not a valid) working tree|not a working tree/i.test(message);
+        if (!allowRegisteredPathFallback || !registeredPathMismatch) {
+            throw error;
+        }
         // On WSL2 the worktree is registered under its `/mnt/<drive>/...` path, so
         // `git worktree remove <windows-path>` cannot match it. Delete the managed
         // directory directly, then prune the now-dangling worktree metadata so the
         // branch is no longer reported as checked out.
+        verifyWorktreePermit(permit);
         removeManagedDir(worktreeBase, dir);
         runSafeFn('git', ['-C', repoRoot, 'worktree', 'prune']);
     }

package/dist/lib/sandbox/mounts.js

@@ -1,6 +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
@@ -9,37 +22,35 @@ export function sandboxCoreBindMounts(config, branch, overrides) {
             containerPath: '/workspace',
             readOnly: false
         },
-        {
-            hostPaths: [overrides.workspaceViewRoot],
-            containerPath: '/workspace/.agents/workspace',
-            readOnly: true
-        },
-        {
-            hostPaths: [shareCommonDir(config)],
-            containerPath: '/share/common',
-            readOnly: false
-        },
-        {
-            hostPaths: [shareBranchDir(config, branch)],
-            containerPath: '/share/branch',
-            readOnly: false
-        },
-        {
-            hostPaths: overrides.shellConfigHostDir
-                ? [overrides.shellConfigHostDir]
-                : shellConfigDirCandidates(config, branch),
-            containerPath: '/home/devuser/.host-shell-config',
-            readOnly: true
-        }
+        ...workspaceMounts,
     ];
-    if (overrides.taskSource && overrides.taskId) {
-        mounts.splice(2, 0, {
+    if (taskBound) {
+        mounts.push({
             hostPaths: [overrides.taskSource],
             containerPath: path.posix.join('/workspace/.agents/workspace/active', overrides.taskId),
             readOnly: false
         });
     }
     mounts.push({
+        hostPaths: [shareCommonDir(config)],
+        containerPath: '/share/common',
+        readOnly: false
+    }, {
+        hostPaths: [shareBranchDir(config, branch)],
+        containerPath: '/share/branch',
+        readOnly: false
+    }, {
+        hostPaths: overrides.shellConfigHostDir
+            ? [overrides.shellConfigHostDir]
+            : shellConfigDirCandidates(config, branch),
+        containerPath: '/home/devuser/.host-shell-config',
+        readOnly: true
+    });
+    mounts.push({
+        hostPaths: [overrides.controlStatusDir],
+        containerPath: '/run/agent-infra/control-status',
+        readOnly: true
+    }, {
         hostPaths: [overrides.controlDir],
         containerPath: '/run/agent-infra/control',
         readOnly: false

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 { inspectWorktree } from './worktree-safety.js';
 import { runEngine, runOkEngine, 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, isSandboxControlRootQuiescing } from './control/lifecycle.js';
+import { appendSandboxControlAudit, readSandboxControlStatus } from './control/state.js';
+import { SANDBOX_CONTROL_FUTURE_SKEW_MS, SANDBOX_CONTROL_STATUS_STALE_MS } from './control/protocol.js';
+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 = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    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 && typeof broker.pid === 'number' && typeof broker.startTime === 'string'
+            ? { version: 1, pid: broker.pid, startTime: broker.startTime }
+            : null;
+        const live = owner !== null && processIdentityMatches(owner);
+        if (live
+            && owner !== null
+            && broker !== null
+            && broker.version === 2
+            && broker.token === manifest.token
+            && broker.generation === manifest.generation) {
+            await waitForSandboxControlBrokerStatus({
+                root,
+                statusDir: manifest.publicStatusDir,
+                generation: manifest.generation,
+                pid: owner.pid,
+                startTime: owner.startTime
+            });
+            return;
+        }
+        if (live && owner) {
+            const deadline = Date.now() + 5_000;
+            while (Date.now() < deadline) {
+                await new Promise((resolve) => setTimeout(resolve, 25));
+                try {
+                    if (fs.readFileSync(brokerPath, 'utf8') !== brokerSnapshot) {
+                        return startSandboxControlBroker(repoRoot, manifestPath);
+                    }
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT') {
+                        return startSandboxControlBroker(repoRoot, manifestPath);
+                    }
+                    throw error;
+                }
+                if (!processIdentityMatches(owner)) {
+                    removePidFileIfMatches(brokerPath, brokerSnapshot);
+                    return startSandboxControlBroker(repoRoot, manifestPath);
+                }
+            }
+            throw new Error('SANDBOX_CONTROL_BROKER_OWNER_ACTIVE');
+        }
+    }
+    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,
@@ -23,30 +163,43 @@ function ensureSandboxControlBroker(params) {
     if (!fs.existsSync(control.manifestPath))
         return;
     const manifest = JSON.parse(fs.readFileSync(control.manifestPath, 'utf8'));
+    if (manifest.version !== 3) {
+        throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 3; container-only recreation is required');
+    }
     const brokerPath = path.join(control.root, 'broker.json');
     try {
         const broker = JSON.parse(fs.readFileSync(brokerPath, 'utf8'));
-        if (broker.version === 1
+        if (broker.version === 2
             && typeof broker.pid === 'number'
             && typeof broker.startTime === 'string'
             && broker.token === manifest.token
-            && processIdentityMatches({ version: 1, pid: broker.pid, startTime: broker.startTime }))
+            && broker.generation === manifest.generation
+            && processIdentityMatches({ version: 1, pid: broker.pid, startTime: broker.startTime })) {
+            try {
+                const status = readSandboxControlStatus(control.statusDir);
+                if (status.generation === manifest.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: manifest.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 +207,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 +377,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 +546,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 +658,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 +718,17 @@ 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.row.running) {
             startFn(params.engine, params.row.name);
             const initial = assess({
@@ -668,34 +844,75 @@ 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 beforeInspection = inspectWorktree(existingWorktrees[0]);
+    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 = `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);
+    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);
@@ -32,6 +50,44 @@ function assertSafeDirectory(directory, expectedBase) {
         throw new Error(`Sandbox workspace view must not be a symbolic link: ${directory}`);
     }
 }
+function assertSafeMountTargetPath(target, worktreeRoot, canonicalWorktreeRoot) {
+    const relative = path.relative(worktreeRoot, target);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`Sandbox workspace mount target escapes its worktree: ${target}`);
+    }
+    let current = worktreeRoot;
+    for (const segment of ['', ...relative.split(path.sep).filter(Boolean)]) {
+        current = segment ? path.join(current, segment) : current;
+        try {
+            if (fs.lstatSync(current).isSymbolicLink()) {
+                throw new Error(`Sandbox workspace mount target must not contain a symbolic link: ${current}`);
+            }
+            const canonicalRelative = path.relative(canonicalWorktreeRoot, fs.realpathSync.native(current));
+            if (canonicalRelative.startsWith('..') || path.isAbsolute(canonicalRelative)) {
+                throw new Error(`Sandbox workspace mount target escapes its real worktree: ${current}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+export function prepareSandboxWorkspaceMountTargets(worktreeRoot) {
+    const resolvedWorktreeRoot = path.resolve(worktreeRoot);
+    const canonicalWorktreeRoot = fs.realpathSync.native(resolvedWorktreeRoot);
+    const workspaceRoot = path.resolve(resolvedWorktreeRoot, '.agents', 'workspace');
+    const statePaths = sandboxWorkspaceViewStatePaths(workspaceRoot);
+    const registryTarget = path.join(workspaceRoot, 'active', '.short-ids.json');
+    for (const target of [workspaceRoot, ...statePaths.map(({ hostPath }) => hostPath), registryTarget]) {
+        assertSafeMountTargetPath(target, resolvedWorktreeRoot, canonicalWorktreeRoot);
+    }
+    fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 });
+    for (const { hostPath } of statePaths) {
+        fs.mkdirSync(hostPath, { recursive: true, mode: 0o700 });
+    }
+    fs.closeSync(fs.openSync(registryTarget, 'a', 0o600));
+}
 export function assertSandboxTaskSource(repoRoot, taskId) {
     if (!/^TASK-\d{8}-\d{6}$/.test(taskId))
         throw new Error('SANDBOX_TASK_SOURCE_INVALID');
@@ -53,11 +109,10 @@ export function materializeSandboxWorkspaceView(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,8 +132,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);
@@ -86,18 +149,24 @@ 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: 1,
-        repoRoot: fs.realpathSync.native(params.repoRoot),
+        version: 3,
+        repoRoot,
+        worktreeRoot: fs.realpathSync.native(params.worktreeRoot),
         project: params.project,
         container: params.container,
         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 { channelDir, statusDir, manifestPath, token, generation };
 }
 //# sourceMappingURL=workspace-view.js.map