@fitlab-ai/agent-infra 0.9.6 → 0.9.7

package/dist/lib/sandbox/commands/rm.js

@@ -11,7 +11,8 @@ import { assertManagedPath, removeManagedDir, removeWorktreeDir } from '../manag
 import { runEngine, runOk, runOkEngine, runSafe, runSafeEngine } from '../shell.js';
 import { resolveSandboxTarget } from '../workspace-identity.js';
 import { sandboxControlPaths, sandboxWorkspaceViewPaths } from '../workspace-view.js';
-import { quiesceSandboxControlRoot, readSandboxControlManifest } from '../control/lifecycle.js';
+import { removeSandboxControlRoot, readSandboxControlManifest } from '../control/lifecycle.js';
+import { inspectSandboxControlContainer } from '../control/container-identity.js';
 import { toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.js';
 import { createSandboxCapabilityPlan } from '../agent-client-reconciler.js';
 import { fetchSandboxRows } from './list-running.js';
@@ -118,10 +119,39 @@ function removeEmptyManagedParent(base, directory) {
     }
     assertRemoved(parent, 'Empty sandbox container directory');
 }
-async function quiesceProjectControlRoots(config) {
+async function removeExactSandboxContainer(engine, manifest, timeoutMs) {
+    const deadlineAt = Date.now() + timeoutMs;
+    const remaining = () => Math.max(1, deadlineAt - Date.now());
+    const inspect = () => inspectSandboxControlContainer(manifest, { timeoutMs: remaining() });
+    const before = await inspect();
+    if (before.state === 'unknown')
+        throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${before.reason}`);
+    if (before.state === 'absent')
+        return;
+    if (before.running && !runOkEngine(engine, 'docker', ['stop', manifest.containerIdentity.id], { timeout: remaining() })) {
+        const afterStop = await inspect();
+        if (afterStop.state !== 'absent' && afterStop.state !== 'found') {
+            throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${afterStop.reason}`);
+        }
+        if (afterStop.state === 'found' && afterStop.running) {
+            throw new Error(`Failed to stop sandbox container: ${manifest.containerIdentity.id}`);
+        }
+    }
+    const afterStop = await inspect();
+    if (afterStop.state === 'unknown')
+        throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${afterStop.reason}`);
+    if (afterStop.state === 'found' && !runOkEngine(engine, 'docker', ['rm', manifest.containerIdentity.id], { timeout: remaining() })) {
+        const afterRemove = await inspect();
+        if (afterRemove.state !== 'absent') {
+            throw new Error(`Failed to remove sandbox container: ${manifest.containerIdentity.id}`);
+        }
+    }
+}
+async function removeProjectControlRoots(config, engine) {
+    const containers = new Set();
     const projectRoot = path.join(config.controlBase, config.project);
     if (!fs.existsSync(projectRoot))
-        return;
+        return containers;
     assertManagedPath(config.controlBase, projectRoot);
     const projectStat = fs.lstatSync(projectRoot);
     if (!projectStat.isDirectory() || projectStat.isSymbolicLink())
@@ -133,9 +163,19 @@ async function quiesceProjectControlRoots(config) {
         for (const identity of fs.readdirSync(containerRoot, { withFileTypes: true })) {
             if (!identity.isDirectory() || identity.isSymbolicLink())
                 continue;
-            await quiesceSandboxControlRoot(path.join(containerRoot, identity.name));
+            const root = path.join(containerRoot, identity.name);
+            const manifestPath = path.join(root, 'manifest.json');
+            if (!fs.existsSync(manifestPath))
+                throw new Error(`SANDBOX_CONTROL_TARGET_EVIDENCE_MISSING: ${root}`);
+            const manifest = readSandboxControlManifest(manifestPath);
+            containers.add(manifest.container);
+            await removeSandboxControlRoot(root, {
+                inspectContainer: (timeoutMs) => inspectSandboxControlContainer(manifest, { timeoutMs }),
+                removeContainer: (timeoutMs) => removeExactSandboxContainer(engine, manifest, timeoutMs)
+            });
         }
     }
+    return containers;
 }
 function inspectionBlockers(inspections) {
     return inspections.filter((inspection) => inspection.status !== 'clean');
@@ -211,25 +251,32 @@ async function rmOne(config, tools, branch, options = {}) {
         p.outro('Cancelled');
         return;
     }
+    const coordinatedContainers = new Set();
     for (const root of controlRoots.filter((candidate) => fs.existsSync(candidate))) {
         assertLegacyCandidateEvidence(root, config.controlBase, config, effectiveBranch, matchedContainers);
         assertControlRootMatchesTarget(root, effectiveBranch, workspace);
-        await quiesceSandboxControlRoot(root);
+        const manifest = readSandboxControlManifest(path.join(root, 'manifest.json'));
+        coordinatedContainers.add(manifest.container);
+        await removeSandboxControlRoot(root, {
+            inspectContainer: (timeoutMs) => inspectSandboxControlContainer(manifest, { timeoutMs }),
+            removeContainer: (timeoutMs) => removeExactSandboxContainer(engine, manifest, timeoutMs)
+        });
     }
-    if (matchedContainers.length > 0) {
+    const uncoordinatedContainers = matchedContainers.filter((name) => !coordinatedContainers.has(name));
+    if (uncoordinatedContainers.length > 0) {
         const spinner = p.spinner();
-        spinner.start(`Stopping container(s): ${matchedContainers.join(', ')}`);
-        for (const name of matchedContainers) {
+        spinner.start(`Stopping container(s): ${uncoordinatedContainers.join(', ')}`);
+        for (const name of uncoordinatedContainers) {
             if (!runOkEngine(engine, 'docker', ['stop', name]))
                 throw new Error(`Failed to stop sandbox container: ${name}`);
             if (!runOkEngine(engine, 'docker', ['rm', name]))
                 throw new Error(`Failed to remove sandbox container: ${name}`);
         }
         const remaining = runEngine(engine, 'docker', ['ps', '-a', '--format', '{{.Names}}']).split('\n').filter(Boolean);
-        const leftovers = matchedContainers.filter((name) => remaining.includes(name));
+        const leftovers = uncoordinatedContainers.filter((name) => remaining.includes(name));
         if (leftovers.length > 0)
             throw new Error(`Sandbox container(s) still exist after removal: ${leftovers.join(', ')}`);
-        spinner.stop(pc.green(`Removed container(s): ${matchedContainers.join(', ')}`));
+        spinner.stop(pc.green(`Removed container(s): ${uncoordinatedContainers.join(', ')}`));
     }
     else {
         p.log.warn(`No sandbox container found for '${branch}'`);
@@ -330,7 +377,7 @@ async function rmPurge(config, tools, prompt = {}) {
         throw new Error(`Refusing to purge because worktree preflight found blocker(s):\n${blockerMessage(blockers)}`);
     }
     const permits = cleanPermits(inspections);
-    await quiesceProjectControlRoots(config);
+    const coordinatedContainers = await removeProjectControlRoots(config, engine);
     const containers = runEngine(engine, 'docker', [
         'ps',
         '-a',
@@ -339,10 +386,11 @@ async function rmPurge(config, tools, prompt = {}) {
         '--format',
         '{{.Names}}'
     ]);
-    if (containers) {
+    const uncoordinatedContainers = containers.split('\n').filter((name) => name && !coordinatedContainers.has(name));
+    if (uncoordinatedContainers.length > 0) {
         const spinner = p.spinner();
         spinner.start('Stopping project sandbox containers...');
-        for (const name of containers.split('\n').filter(Boolean)) {
+        for (const name of uncoordinatedContainers) {
             if (!runOkEngine(engine, 'docker', ['stop', name]))
                 throw new Error(`Failed to stop sandbox container: ${name}`);
             if (!runOkEngine(engine, 'docker', ['rm', name]))
@@ -351,8 +399,9 @@ async function rmPurge(config, tools, prompt = {}) {
         const remaining = runEngine(engine, 'docker', [
             'ps', '-a', '--filter', `label=${sandboxLabel(config)}`, '--format', '{{.Names}}'
         ]);
-        if (remaining)
-            throw new Error(`Project sandbox container(s) still exist after removal: ${remaining.replaceAll('\n', ', ')}`);
+        const leftovers = remaining.split('\n').filter((name) => name && !coordinatedContainers.has(name));
+        if (leftovers.length > 0)
+            throw new Error(`Project sandbox container(s) still exist after removal: ${leftovers.join(', ')}`);
         spinner.stop(pc.green('Project sandbox containers removed'));
     }
     else {

package/dist/lib/sandbox/commands/start.js

@@ -8,9 +8,9 @@ const USAGE = `Usage: ai sandbox start [--recreate] <branch | TASK-id | N>
 
 Start an existing sandbox container that has stopped (for example after the
 Docker daemon was restarted or replaced). The container must already exist:
-if none is found, run 'ai sandbox create <branch>' first. A container that is
-already running is checked without modifying healthy runtime state. --recreate
-allows container-only replacement after in-place recovery fails.`;
+if none is found, run 'ai sandbox create <branch>' first. Without --recreate, a
+container that is already running is checked without modifying healthy runtime
+state. --recreate replaces the existing container even when it is healthy.`;
 export function parseStartArgs(args) {
     let recreate = false;
     let help = false;
@@ -62,6 +62,7 @@ export async function start(args) {
         workspace: target.workspace,
         row: found,
         allowRecreate: parsed.recreate,
+        forceRecreate: parsed.recreate,
         recreate: async () => {
             const { create } = await import('./create.js');
             await create([target.requestedRef, '--no-refresh']);

package/dist/lib/sandbox/control/container-identity.js

@@ -0,0 +1,64 @@
+import { commandForEngine, runEngine, runProbe } from '../shell.js';
+function isAuthoritativeNotFound(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /(?:no such container|container .* not found|cannot find container)/i.test(message);
+}
+export function classifySandboxContainerInspection(expected, inspection) {
+    if ('notFound' in inspection)
+        return { state: 'absent', id: expected.id };
+    if ('error' in inspection) {
+        return isAuthoritativeNotFound(inspection.error)
+            ? { state: 'absent', id: expected.id }
+            : { state: 'unknown', reason: `container inspection failed: ${inspection.error instanceof Error ? inspection.error.message : String(inspection.error)}` };
+    }
+    const response = inspection;
+    if (typeof response.id !== 'string' || response.id !== expected.id
+        || typeof response.running !== 'boolean' || !response.labels
+        || typeof response.labels !== 'object' || Array.isArray(response.labels)) {
+        return { state: 'unknown', reason: 'container inspection response is incomplete' };
+    }
+    const labels = response.labels;
+    for (const [key, value] of Object.entries(expected.labels)) {
+        if (labels[key] !== value)
+            return { state: 'unknown', reason: 'container labels do not match the manifest' };
+    }
+    return {
+        state: 'found',
+        id: response.id,
+        running: response.running,
+        labels: Object.fromEntries(Object.entries(labels).flatMap(([key, value]) => typeof value === 'string' ? [[key, value]] : []))
+    };
+}
+export async function inspectSandboxControlContainer(manifest, options = {}) {
+    try {
+        const args = ['inspect', '--format', '{{json .}}', manifest.containerIdentity.id];
+        let raw;
+        if (options.run) {
+            raw = options.run(manifest.engine, 'docker', args, options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs });
+        }
+        else {
+            const command = commandForEngine(manifest.engine, 'docker', args);
+            const result = (options.probe ?? runProbe)(command.cmd, command.args, options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs });
+            if (result.status !== 0) {
+                const stderr = typeof result.stderr === 'string' ? result.stderr : result.stderr?.toString('utf8') ?? '';
+                return classifySandboxContainerInspection(manifest.containerIdentity, {
+                    error: new Error(stderr || `container inspection exited with ${result.status ?? 'unknown'}`)
+                });
+            }
+            raw = typeof result.stdout === 'string' ? result.stdout : result.stdout?.toString('utf8') ?? '';
+        }
+        const parsed = JSON.parse(raw);
+        const value = Array.isArray(parsed) && parsed.length === 1 ? parsed[0] : parsed;
+        if (!value || Array.isArray(value))
+            return { state: 'unknown', reason: 'container inspection response is incomplete' };
+        return classifySandboxContainerInspection(manifest.containerIdentity, {
+            id: value.Id,
+            running: value.State?.Running,
+            labels: value.Config?.Labels
+        });
+    }
+    catch (error) {
+        return classifySandboxContainerInspection(manifest.containerIdentity, { error });
+    }
+}
+//# sourceMappingURL=container-identity.js.map

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

@@ -18,7 +18,7 @@ async function waitForStartTime(pid, timeoutMs = 2_000) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         const startTime = getProcessStartTime(pid);
-        if (startTime)
+        if (startTime !== null)
             return startTime;
         await new Promise((resolve) => setTimeout(resolve, 10));
     }
@@ -48,7 +48,7 @@ export async function prepareSandboxControlExecution(params) {
     });
     const startTime = await waitForStartTime(child.pid);
     const execution = {
-        version: 1,
+        version: 2,
         generation: params.manifest.generation,
         requestId: params.request.id,
         nonce,
@@ -63,17 +63,23 @@ export async function prepareSandboxControlExecution(params) {
     atomicWriteJson(executionPath(params.manifest, params.request.id), execution);
     return {
         execution,
-        start() {
+        start(canWrite = () => true) {
             if (!child.connected)
                 throw new Error('SANDBOX_CONTROL_EXECUTOR_GATE_CLOSED');
+            if (!canWrite())
+                throw new Error('SANDBOX_CONTROL_OWNER_LOST');
             atomicWriteJson(executionPath(params.manifest, params.request.id), { ...execution, phase: 'running', updatedAt: Date.now() });
+            if (!canWrite())
+                throw new Error('SANDBOX_CONTROL_OWNER_LOST');
             child.send({ version: 1, nonce });
         },
         completion,
-        terminate() {
-            atomicWriteJson(executionPath(params.manifest, params.request.id), {
-                ...execution, phase: 'terminating', updatedAt: Date.now()
-            });
+        terminate(updateState = true) {
+            if (updateState) {
+                atomicWriteJson(executionPath(params.manifest, params.request.id), {
+                    ...execution, phase: 'terminating', updatedAt: Date.now()
+                });
+            }
             return terminateSandboxControlExecution(execution);
         }
     };

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

@@ -3,10 +3,33 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { buildProcessTreeStopCommand } from '../../server/process-control.js';
 import { processIdentityMatches } from '../../server/process-state.js';
+import { DEFAULT_SANDBOX_CONTROL_TIMING } from './protocol.js';
+import { inspectSandboxControlContainer } from './container-identity.js';
 import { parseSandboxControlStatus, readExecution, terminateSandboxControlExecution } from './state.js';
-const DEFAULT_QUIESCE_TIMEOUT_MS = 7_000;
+const DEFAULT_QUIESCE_TIMEOUT_MS = DEFAULT_SANDBOX_CONTROL_TIMING.quiesceDeadlineMs;
 const QUIESCING_FILE = 'quiescing.json';
 const BROKER_STARTING_FILE = 'broker-starting.json';
+async function awaitWithDeadline(operation, deadlineAt, errorCode) {
+    const remaining = deadlineAt - Date.now();
+    if (remaining <= 0)
+        throw new Error(errorCode);
+    let timer;
+    try {
+        return await Promise.race([
+            operation(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(errorCode)), remaining);
+            })
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+function forceDeadline(deadlineAt, timeoutMs) {
+    return Math.max(Date.now(), deadlineAt - Math.max(1, Math.floor(timeoutMs / 2)));
+}
 function regularFile(filePath) {
     try {
         const stat = fs.lstatSync(filePath);
@@ -44,8 +67,8 @@ function readStartupOwner(filePath) {
     const raw = fs.readFileSync(filePath, 'utf8');
     try {
         const record = JSON.parse(raw);
-        if (record.version !== 1 || !Number.isSafeInteger(record.pid) || (record.pid ?? 0) <= 0
-            || typeof record.startTime !== 'string')
+        if (record.version !== 2 || !Number.isSafeInteger(record.pid) || (record.pid ?? 0) <= 0
+            || typeof record.startTime !== 'number' || !Number.isSafeInteger(record.startTime))
             return null;
         return { raw, owner: { pid: record.pid, startTime: record.startTime } };
     }
@@ -77,7 +100,7 @@ async function waitForStartupTransition(root, timeoutMs) {
 export async function acquireSandboxControlBrokerStartup(root, owner, timeoutMs = 5_000) {
     const resolvedRoot = path.resolve(root);
     const transitionPath = path.join(resolvedRoot, BROKER_STARTING_FILE);
-    const record = `${JSON.stringify({ version: 1, ...owner })}\n`;
+    const record = `${JSON.stringify({ version: 2, ...owner })}\n`;
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         if (isSandboxControlRootQuiescing(resolvedRoot))
@@ -133,11 +156,17 @@ export function readSandboxControlManifest(manifestPath) {
     catch {
         throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
     }
-    if (manifest.version !== 3) {
-        throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 3; container-only recreation is required');
+    if (manifest.version !== 4) {
+        throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 4; container-only recreation is required');
     }
-    if (typeof manifest.repoRoot !== 'string' || typeof manifest.worktreeRoot !== 'string'
+    if (typeof manifest.engine !== 'string' || manifest.engine.length === 0
+        || typeof manifest.repoRoot !== 'string' || typeof manifest.worktreeRoot !== 'string'
         || typeof manifest.project !== 'string' || typeof manifest.container !== 'string'
+        || !manifest.containerIdentity || typeof manifest.containerIdentity.id !== 'string'
+        || manifest.containerIdentity.id.length === 0 || !manifest.containerIdentity.labels
+        || typeof manifest.containerIdentity.labels !== 'object'
+        || Array.isArray(manifest.containerIdentity.labels)
+        || Object.values(manifest.containerIdentity.labels).some((value) => typeof value !== 'string')
         || typeof manifest.branch !== 'string' || !['task-bound', 'branch-only'].includes(manifest.mode ?? '')
         || (manifest.taskId !== null && typeof manifest.taskId !== 'string')
         || typeof manifest.channelDir !== 'string' || typeof manifest.publicStatusDir !== 'string'
@@ -164,9 +193,10 @@ function readBrokerOwner(filePath) {
     catch {
         throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
     }
-    if (!owner || owner.version !== 2 || !Number.isSafeInteger(owner.pid) || (owner.pid ?? 0) <= 0
-        || typeof owner.startTime !== 'string' || typeof owner.token !== 'string'
-        || typeof owner.generation !== 'string')
+    if (!owner || owner.version !== 3 || !Number.isSafeInteger(owner.pid) || (owner.pid ?? 0) <= 0
+        || typeof owner.startTime !== 'number' || !Number.isSafeInteger(owner.startTime)
+        || typeof owner.brokerId !== 'string' || owner.brokerId.length === 0
+        || typeof owner.token !== 'string' || typeof owner.generation !== 'string')
         throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
     return owner;
 }
@@ -183,10 +213,11 @@ function readStatusOwner(filePath) {
     }
 }
 function sameOwner(left, right) {
-    return left.pid === right.pid && left.startTime === right.startTime;
+    return left.pid === right.pid && left.startTime === right.startTime
+        && (!left.brokerId || !right.brokerId || left.brokerId === right.brokerId);
 }
 function ownerLive(owner) {
-    return processIdentityMatches({ version: 1, pid: owner.pid, startTime: owner.startTime });
+    return processIdentityMatches({ pid: owner.pid, startTime: owner.startTime });
 }
 function readExecutions(manifest) {
     if (!fs.existsSync(manifest.processingDir))
@@ -241,10 +272,10 @@ function executionAlive(execution, platform) {
     if (platform !== 'win32' && execution.child.processGroupId) {
         return processGroupAlive(execution.child.processGroupId);
     }
-    return processIdentityMatches({ version: 1, pid: execution.child.pid, startTime: execution.child.startTime });
+    return processIdentityMatches({ pid: execution.child.pid, startTime: execution.child.startTime });
 }
-async function waitForExit(owner, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
+async function waitForExit(owner, timeoutMs, deadlineAt) {
+    const deadline = deadlineAt ?? (Date.now() + timeoutMs);
     while (Date.now() < deadline) {
         if (!ownerLive(owner))
             return true;
@@ -286,13 +317,16 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
         if (!stat.isDirectory() || stat.isSymbolicLink())
             throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
     }
+    const timeoutMs = options.timeoutMs ?? options.timing?.quiesceDeadlineMs ?? DEFAULT_QUIESCE_TIMEOUT_MS;
+    const deadlineAt = Date.now() + timeoutMs;
+    const forceAt = forceDeadline(deadlineAt, timeoutMs);
     markSandboxControlRootQuiescing(resolvedRoot);
-    await waitForStartupTransition(resolvedRoot, options.timeoutMs ?? DEFAULT_QUIESCE_TIMEOUT_MS);
+    await waitForStartupTransition(resolvedRoot, Math.max(0, forceAt - Date.now()));
     const manifestPath = path.join(resolvedRoot, 'manifest.json');
     const manifest = fs.existsSync(manifestPath) ? readSandboxControlManifest(manifestPath) : null;
     const broker = readBrokerOwner(path.join(resolvedRoot, 'broker.json'));
     const status = readStatusOwner(path.join(resolvedRoot, 'public', 'status.json'));
-    const statusOwner = status ? { version: 1, ...status.broker } : null;
+    const statusOwner = status ? status.broker : null;
     const brokerLive = broker ? ownerLive(broker) : false;
     const statusLive = statusOwner ? ownerLive(statusOwner) : false;
     if (manifest && broker && (broker.token !== manifest.token || broker.generation !== manifest.generation)) {
@@ -307,14 +341,28 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
     if (!manifest && brokerLive)
         throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
     const platform = options.platform ?? process.platform;
-    const timeoutMs = options.timeoutMs ?? DEFAULT_QUIESCE_TIMEOUT_MS;
     let executions = manifest ? readExecutions(manifest) : [];
     const owner = brokerLive ? broker : statusLive ? statusOwner : null;
     if (!owner) {
         if (manifest && !broker && !status)
             throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
         for (const execution of executions) {
-            if (!terminateSandboxControlExecution(execution, { platform, timeoutMs })) {
+            terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false });
+        }
+        const softDeadlineAt = Math.min(forceAt, Date.now() + Math.floor(Math.max(0, forceAt - Date.now()) / 2));
+        while (Date.now() < softDeadlineAt) {
+            if (!executions.some((execution) => executionAlive(execution, platform)))
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        if (manifest)
+            executions = mergeExecutions(executions, readExecutions(manifest));
+        if (Date.now() >= deadlineAt)
+            throw new Error('SANDBOX_CONTROL_QUIESCE_DEADLINE_EXCEEDED');
+        for (const execution of executions) {
+            if (!terminateSandboxControlExecution(execution, {
+                platform, timeoutMs: Math.max(0, deadlineAt - Date.now()), deadlineAt, forceAt: Date.now()
+            })) {
                 throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
             }
         }
@@ -323,26 +371,187 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
         }
         return broker || status ? 'stale' : 'missing';
     }
+    const remaining = () => Math.max(0, deadlineAt - Date.now());
     signalOwner(owner, platform, false);
-    if (await waitForExit(owner, timeoutMs)) {
-        if (executions.some((execution) => executionAlive(execution, platform))) {
-            throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
-        }
+    for (const execution of executions) {
+        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false });
+    }
+    const softDeadlineAt = Math.min(forceAt, Date.now() + Math.floor(Math.max(0, forceAt - Date.now()) / 2));
+    while (Date.now() < softDeadlineAt) {
+        if (!ownerLive(owner) && !executions.some((execution) => executionAlive(execution, platform)))
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    if (!ownerLive(owner) && !executions.some((execution) => executionAlive(execution, platform))) {
         return 'stopped';
     }
     if (manifest)
         executions = mergeExecutions(executions, readExecutions(manifest));
+    if (Date.now() >= deadlineAt)
+        throw new Error('SANDBOX_CONTROL_QUIESCE_DEADLINE_EXCEEDED');
     for (const execution of executions) {
-        if (!terminateSandboxControlExecution(execution, { platform, timeoutMs })) {
-            throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
-        }
+        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, deadlineAt, forceAt: Date.now() });
     }
     signalOwner(owner, platform, true);
-    if (!await waitForExit(owner, timeoutMs))
+    while (Date.now() < deadlineAt) {
+        if (!ownerLive(owner) && !executions.some((execution) => executionAlive(execution, platform)))
+            return 'stopped';
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    if (ownerLive(owner))
         throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
-    if (executions.some((execution) => executionAlive(execution, platform))) {
+    if (executions.some((execution) => executionAlive(execution, platform)))
         throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
-    }
     return 'stopped';
 }
+export async function removeSandboxControlRoot(root, options) {
+    const resolvedRoot = path.resolve(root);
+    if (!fs.existsSync(resolvedRoot))
+        return;
+    const stat = fs.lstatSync(resolvedRoot);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+    const manifestPath = path.join(resolvedRoot, 'manifest.json');
+    const manifest = readSandboxControlManifest(manifestPath);
+    const inspectContainer = options.inspectContainer
+        ?? ((timeoutMs) => inspectSandboxControlContainer(manifest, { timeoutMs }));
+    const timeoutMs = options.timeoutMs ?? options.timing?.quiesceDeadlineMs ?? DEFAULT_QUIESCE_TIMEOUT_MS;
+    const deadlineAt = Date.now() + timeoutMs;
+    const forceAt = forceDeadline(deadlineAt, timeoutMs);
+    const remaining = () => Math.max(0, deadlineAt - Date.now());
+    const observation = await awaitWithDeadline(() => inspectContainer(remaining()), deadlineAt, 'SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
+    if (observation.state === 'unknown')
+        throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${observation.reason}`);
+    if (options.requireAbsent && observation.state !== 'absent') {
+        throw new Error('SANDBOX_CONTROL_CONTAINER_REAPPEARED');
+    }
+    markSandboxControlRootQuiescing(resolvedRoot);
+    await waitForStartupTransition(resolvedRoot, Math.max(0, forceAt - Date.now()));
+    const brokerPath = path.join(resolvedRoot, 'broker.json');
+    const statusPath = path.join(resolvedRoot, 'public', 'status.json');
+    const broker = readBrokerOwner(brokerPath);
+    const status = readStatusOwner(statusPath);
+    if (broker && (broker.token !== manifest.token || broker.generation !== manifest.generation)) {
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    }
+    if (status && status.generation !== manifest.generation) {
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    }
+    if (broker && status && !sameOwner(broker, status.broker)
+        && (ownerLive(broker) || ownerLive(status.broker))) {
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    }
+    const platform = options.platform ?? process.platform;
+    const owner = broker && ownerLive(broker) ? broker
+        : status && ownerLive(status.broker) ? status.broker : null;
+    const selfOwner = options.selfOwner;
+    const selfOwned = Boolean(selfOwner && broker && sameOwner(broker, selfOwner));
+    if (selfOwner && (!broker || !selfOwned || broker.token !== manifest.token || broker.generation !== manifest.generation)) {
+        throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+    }
+    let executions = readExecutions(manifest);
+    if (owner && !selfOwned)
+        signalOwner(owner, platform, false);
+    for (const execution of executions) {
+        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false });
+    }
+    const softDeadlineAt = Math.min(forceAt, Date.now() + Math.floor(Math.max(0, forceAt - Date.now()) / 2));
+    while (Date.now() < softDeadlineAt) {
+        if ((!owner || selfOwned || !ownerLive(owner)) && !executions.some((execution) => executionAlive(execution, platform)))
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    if (observation.state === 'found') {
+        if (Date.now() >= deadlineAt)
+            throw new Error('SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
+        await awaitWithDeadline(() => options.removeContainer(remaining()), deadlineAt, 'SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
+        const afterRemoval = await awaitWithDeadline(() => inspectContainer(remaining()), deadlineAt, 'SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
+        if (afterRemoval.state !== 'absent') {
+            throw new Error(afterRemoval.state === 'unknown'
+                ? `SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${afterRemoval.reason}`
+                : 'SANDBOX_CONTROL_CONTAINER_STILL_EXISTS');
+        }
+    }
+    const currentManifest = readSandboxControlManifest(manifestPath);
+    if (currentManifest.token !== manifest.token || currentManifest.generation !== manifest.generation
+        || !isSandboxControlRootQuiescing(resolvedRoot)) {
+        throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+    }
+    const currentBroker = readBrokerOwner(brokerPath);
+    if (selfOwned && (!currentBroker || !selfOwner || !sameOwner(selfOwner, currentBroker)
+        || currentBroker.token !== manifest.token || currentBroker.generation !== manifest.generation)) {
+        throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
+    }
+    if (owner && currentBroker && !sameOwner(owner, currentBroker)) {
+        throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
+    }
+    if (!owner && currentBroker && ownerLive(currentBroker)) {
+        throw new Error('SANDBOX_CONTROL_OWNER_REPLACED');
+    }
+    if (owner && ownerLive(owner) && !currentBroker) {
+        throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
+    }
+    executions = mergeExecutions(executions, readExecutions(manifest));
+    if (Date.now() >= deadlineAt)
+        throw new Error('SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
+    for (const execution of executions) {
+        if (!terminateSandboxControlExecution(execution, {
+            platform, timeoutMs: remaining(), deadlineAt, forceAt: Date.now()
+        })) {
+            throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
+        }
+    }
+    if (owner && currentBroker && ownerLive(currentBroker) && !selfOwned) {
+        if (remaining() <= 0)
+            throw new Error('SANDBOX_CONTROL_REMOVE_DEADLINE_EXCEEDED');
+        signalOwner(currentBroker, platform, true);
+        if (remaining() <= 0 || !await waitForExit(currentBroker, remaining(), deadlineAt)) {
+            throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
+        }
+    }
+    const finalExecutions = mergeExecutions(executions, readExecutions(manifest));
+    if (finalExecutions.some((execution) => executionAlive(execution, platform))) {
+        throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
+    }
+    const finalBrokerRaw = fs.existsSync(brokerPath) ? fs.readFileSync(brokerPath, 'utf8') : null;
+    if (finalBrokerRaw !== null) {
+        const finalBroker = readBrokerOwner(brokerPath);
+        if (!finalBroker)
+            throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+        const finalSelfOwner = Boolean(selfOwner && sameOwner(finalBroker, selfOwner)
+            && finalBroker.token === manifest.token && finalBroker.generation === manifest.generation);
+        if (ownerLive(finalBroker) && !finalSelfOwner)
+            throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
+        if (fs.readFileSync(brokerPath, 'utf8') !== finalBrokerRaw) {
+            throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+        }
+        fs.unlinkSync(brokerPath);
+    }
+    const finalStatusRaw = fs.existsSync(statusPath) ? fs.readFileSync(statusPath, 'utf8') : null;
+    if (finalStatusRaw !== null) {
+        const finalStatus = readStatusOwner(statusPath);
+        if (!finalStatus)
+            throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+        if (ownerLive(finalStatus.broker) && !(selfOwner && sameOwner(finalStatus.broker, selfOwner))) {
+            throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
+        }
+        if (fs.readFileSync(statusPath, 'utf8') !== finalStatusRaw) {
+            throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');
+        }
+        fs.unlinkSync(statusPath);
+    }
+    if (fs.existsSync(brokerPath) || fs.existsSync(statusPath)) {
+        throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_REMAINS');
+    }
+    fs.rmSync(resolvedRoot, { recursive: true, force: true });
+}
+export async function garbageCollectSandboxControlRoot(root, options = {}) {
+    await removeSandboxControlRoot(path.resolve(root), {
+        ...options,
+        requireAbsent: true,
+        removeContainer: async () => {
+            throw new Error('SANDBOX_CONTROL_CONTAINER_REAPPEARED');
+        }
+    });
+}
 //# sourceMappingURL=lifecycle.js.map

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

@@ -5,6 +5,13 @@ 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 DEFAULT_SANDBOX_CONTROL_TIMING = Object.freeze({
+    controlTickMs: 250,
+    parkedBindingInitialMs: 1_000,
+    slowCheckMs: 5_000,
+    containerHeartbeatMs: 5_000,
+    quiesceDeadlineMs: 7_000
+});
 export class SandboxControlProtocolError extends Error {
     code;
     retryable;