@fitlab-ai/agent-infra 0.9.4 → 0.9.6

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

@@ -1,35 +1,90 @@
+import { validateTaskCreateCandidate } from '../../task/create.js';
 export const SANDBOX_CONTROL_MAX_BYTES = 64 * 1024;
-export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration'];
+export const SANDBOX_CONTROL_ADMISSION_WINDOW_MS = 2_000;
+export const SANDBOX_CONTROL_STATUS_INTERVAL_MS = 250;
+export const SANDBOX_CONTROL_STATUS_STALE_MS = 1_500;
+export const SANDBOX_CONTROL_FUTURE_SKEW_MS = 1_000;
+export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-create'];
+export class SandboxControlProtocolError extends Error {
+    code;
+    retryable;
+    constructor(code, message, retryable = false) {
+        super(`${code}: ${message}`);
+        this.name = 'SandboxControlProtocolError';
+        this.code = code;
+        this.retryable = retryable;
+    }
+}
+function fail(code, message, retryable = false) {
+    throw new SandboxControlProtocolError(code, message, retryable);
+}
 export function isSandboxControlFamily(value) {
     return SANDBOX_CONTROL_FAMILIES.includes(value);
 }
-export function validateSandboxControlRequest(value, manifest) {
+export function validateSandboxControlRequest(value, manifest, options = {}) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request must be an object');
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request must be an object');
     }
     const request = value;
-    if (request.version !== 1
-        || typeof request.id !== 'string'
-        || !/^[a-f0-9-]{16,64}$/.test(request.id)
-        || request.token !== manifest.token
-        || typeof request.family !== 'string'
-        || !isSandboxControlFamily(request.family)
-        || !Array.isArray(request.args)
-        || !request.args.every((arg) => typeof arg === 'string')) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request schema or authorization is invalid');
+    if (request.version !== 2 || typeof request.id !== 'string'
+        || !/^[a-f0-9-]{16,64}$/.test(request.id) || request.token !== manifest.token
+        || typeof request.family !== 'string' || !isSandboxControlFamily(request.family)
+        || !Number.isSafeInteger(request.issuedAt) || !Number.isSafeInteger(request.expiresAt))
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
+    if (request.generation !== manifest.generation) {
+        fail('SANDBOX_CONTROL_GENERATION_INVALID', 'request generation does not match the broker');
     }
-    if (manifest.mode !== 'task-bound' || !manifest.taskId) {
-        throw new Error('SANDBOX_CONTROL_BRANCH_ONLY: branch-only sandboxes cannot coordinate tasks');
+    const issuedAt = request.issuedAt;
+    const expiresAt = request.expiresAt;
+    const now = options.now ?? Date.now();
+    if (expiresAt <= issuedAt || expiresAt - issuedAt > SANDBOX_CONTROL_ADMISSION_WINDOW_MS || issuedAt > now + SANDBOX_CONTROL_FUTURE_SKEW_MS) {
+        fail('SANDBOX_CONTROL_REQUEST_DEADLINE_INVALID', 'request admission deadline is invalid');
     }
+    if (now > expiresAt)
+        fail('SANDBOX_CONTROL_REQUEST_EXPIRED', 'request admission deadline has passed', true);
     if (Buffer.byteLength(JSON.stringify(request), 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_TOO_LARGE: request exceeds the control limit');
+        fail('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit');
+    }
+    if (request.family === 'task-create') {
+        const expected = ['candidate', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+        if (Object.keys(request).sort().join(',') !== expected.sort().join(',')) {
+            fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
+        }
+        return { ...request, candidate: validateTaskCreateCandidate(request.candidate) };
+    }
+    const expected = ['args', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+    if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
+        || !Array.isArray(request.args) || !request.args.every((arg) => typeof arg === 'string')) {
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
+    }
+    if (manifest.mode !== 'task-bound' || !manifest.taskId) {
+        fail('SANDBOX_CONTROL_BRANCH_ONLY', "branch-only sandboxes cannot coordinate tasks; return to the host and run 'ai sandbox start --recreate <task-ref-or-correct-branch>'");
+    }
+    if (request.family === 'task-orchestration'
+        && request.args.some((arg) => arg === '--git-worktree-root' || arg.startsWith('--git-worktree-root='))) {
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'worktree binding is reserved for the control broker');
     }
     return request;
 }
 export function bindSandboxControlTask(request, taskId) {
-    if (request.args.length === 0) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: command arguments are required');
-    }
+    if (request.family === 'task-create')
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-create requests do not bind a current task');
+    if (request.args.length === 0)
+        fail('SANDBOX_CONTROL_REQUEST_INVALID', 'command arguments are required');
     return [taskId, ...request.args.slice(1)];
 }
+export function controlError(error) {
+    if (error instanceof SandboxControlProtocolError) {
+        return { code: error.code, message: error.message, retryable: error.retryable };
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'SANDBOX_CONTROL_INTERNAL_ERROR';
+    const retryable = new Set([
+        'SANDBOX_CONTROL_BUSY',
+        'SANDBOX_CONTROL_HANDOFF_ACTIVE',
+        'SANDBOX_CONTROL_REQUEST_EXPIRED',
+        'SANDBOX_WORKTREE_BINDING_LOST'
+    ]).has(code);
+    return { code, message, retryable };
+}
 //# sourceMappingURL=protocol.js.map

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

@@ -1,23 +1,12 @@
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { getProcessStartTime } from '../../server/process-state.js';
-import { bindSandboxControlTask, validateSandboxControlRequest } from './protocol.js';
-function readManifest(manifestPath) {
-    const stat = fs.lstatSync(manifestPath);
-    if (!stat.isFile() || stat.isSymbolicLink())
-        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
-    if (manifest.version !== 1
-        || typeof manifest.repoRoot !== 'string'
-        || typeof manifest.channelDir !== 'string'
-        || typeof manifest.token !== 'string')
-        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
-    if (path.resolve(manifest.channelDir) !== path.join(path.dirname(path.resolve(manifestPath)), 'channel')) {
-        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
-    }
-    return manifest;
-}
+import { assertGitWorktreeBinding } from '../../git/worktree-identity.js';
+import { controlError, SANDBOX_CONTROL_STATUS_INTERVAL_MS } from './protocol.js';
+import { prepareSandboxControlExecution } from './executor.js';
+import { appendSandboxControlAudit, atomicWriteJson, cleanupStaleSandboxControlLease, executionPath, readActiveLease, readExecution, terminateSandboxControlExecution, writeSandboxControlStatus } from './state.js';
+import { validateSandboxControlRequest } from './protocol.js';
+import { acquireSandboxControlBrokerStartup, isSandboxControlRootQuiescing, readSandboxControlManifest } from './lifecycle.js';
 function assertRealDirectory(directory, parent) {
     const stat = fs.lstatSync(directory);
     if (!stat.isDirectory() || stat.isSymbolicLink())
@@ -26,84 +15,250 @@ function assertRealDirectory(directory, parent) {
         throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
     }
 }
-function writeResponse(directory, response) {
-    const temporary = path.join(directory, `.${response.id}.tmp`);
-    fs.writeFileSync(temporary, `${JSON.stringify(response)}\n`, { mode: 0o600, flag: 'wx' });
-    fs.renameSync(temporary, path.join(directory, `${response.id}.json`));
+function responsePath(manifest, id) {
+    return path.join(manifest.channelDir, 'responses', `${id}.json`);
+}
+function writeResponse(manifest, response) {
+    atomicWriteJson(responsePath(manifest, response.id), response);
+}
+function rejected(id, error) {
+    const detail = controlError(error);
+    return { version: 2, id, phase: 'rejected', exitCode: null, stdout: '', stderr: `${detail.message}\n`, error: detail };
+}
+function unknown(id) {
+    const error = {
+        code: 'SANDBOX_CONTROL_RESULT_UNKNOWN',
+        message: 'SANDBOX_CONTROL_RESULT_UNKNOWN: accepted execution ended without a provable result; inspect domain state before retrying',
+        retryable: false
+    };
+    return { version: 2, id, phase: 'rejected', exitCode: null, stdout: '', stderr: `${error.message}\n`, error };
 }
-export function serveSandboxControl(manifestPath, signal = new AbortController().signal) {
-    const manifest = readManifest(manifestPath);
-    const brokerPath = path.join(path.dirname(manifestPath), 'broker.json');
+function notExecuted(id) {
+    const error = {
+        code: 'SANDBOX_CONTROL_NOT_EXECUTED',
+        message: 'SANDBOX_CONTROL_NOT_EXECUTED: request was claimed but never accepted; retry with a new request id',
+        retryable: true
+    };
+    return { version: 2, id, phase: 'rejected', exitCode: null, stdout: '', stderr: `${error.message}\n`, error };
+}
+function consumeRequest(directory, id) {
+    try {
+        fs.writeFileSync(path.join(directory, id), '', { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error('SANDBOX_CONTROL_REQUEST_REPLAYED');
+        throw error;
+    }
+}
+function claimRequest(manifest, requestPath, id) {
+    const directory = path.join(manifest.processingDir, id);
+    fs.mkdirSync(directory, { mode: 0o700 });
+    const claimed = path.join(directory, 'request.json');
+    try {
+        fs.renameSync(requestPath, claimed);
+        return claimed;
+    }
+    catch (error) {
+        fs.rmSync(directory, { recursive: true, force: true });
+        throw error;
+    }
+}
+function bindingReason(manifest) {
+    try {
+        assertGitWorktreeBinding(manifest.repoRoot, manifest.worktreeRoot, manifest.branch);
+        return null;
+    }
+    catch {
+        return 'SANDBOX_WORKTREE_BINDING_LOST';
+    }
+}
+function recoverProcessing(manifest) {
+    for (const entry of fs.readdirSync(manifest.processingDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || !/^[a-f0-9-]{16,64}$/.test(entry.name))
+            continue;
+        const descriptor = executionPath(manifest, entry.name);
+        const existingResponse = responsePath(manifest, entry.name);
+        if (fs.existsSync(descriptor)) {
+            const execution = readExecution(descriptor);
+            if (!terminateSandboxControlExecution(execution)) {
+                throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${entry.name}`);
+            }
+            appendSandboxControlAudit(manifest, 'orphan-tree-terminated', { requestId: entry.name });
+            let terminal = false;
+            if (fs.existsSync(existingResponse)) {
+                try {
+                    const response = JSON.parse(fs.readFileSync(existingResponse, 'utf8'));
+                    terminal = response.version === 2 && response.id === entry.name
+                        && (response.phase === 'completed' || response.phase === 'rejected');
+                }
+                catch {
+                    terminal = false;
+                }
+            }
+            if (!terminal)
+                writeResponse(manifest, unknown(entry.name));
+        }
+        else {
+            writeResponse(manifest, notExecuted(entry.name));
+        }
+        fs.rmSync(path.join(manifest.processingDir, entry.name), { recursive: true, force: true });
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function sandboxControlSafeEnv(env = process.env) {
+    return Object.fromEntries(Object.entries(env).filter(([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')));
+}
+export async function serveSandboxControl(manifestPath, signal = new AbortController().signal) {
+    const manifest = readSandboxControlManifest(manifestPath);
+    const root = path.dirname(manifestPath);
     const startTime = getProcessStartTime(process.pid);
     if (!startTime)
         throw new Error('SANDBOX_CONTROL_BROKER_IDENTITY_UNAVAILABLE');
-    fs.writeFileSync(brokerPath, `${JSON.stringify({
-        version: 1,
-        pid: process.pid,
-        startTime,
-        token: manifest.token
-    })}\n`, { mode: 0o600, flag: 'wx' });
+    const releaseStartup = await acquireSandboxControlBrokerStartup(root, { pid: process.pid, startTime });
     const requestsDir = path.join(manifest.channelDir, 'requests');
     const responsesDir = path.join(manifest.channelDir, 'responses');
-    assertRealDirectory(manifest.channelDir);
-    fs.mkdirSync(requestsDir, { recursive: true, mode: 0o700 });
-    fs.mkdirSync(responsesDir, { recursive: true, mode: 0o700 });
-    assertRealDirectory(requestsDir, manifest.channelDir);
-    assertRealDirectory(responsesDir, manifest.channelDir);
-    const consumed = new Set();
-    while (!signal.aborted) {
-        const current = readManifest(manifestPath);
-        if (current.token !== manifest.token)
-            return;
+    const consumedDir = path.join(root, 'consumed');
+    const broker = { pid: process.pid, startTime };
+    const brokerPath = path.join(root, 'broker.json');
+    const brokerRecord = `${JSON.stringify({ version: 2, ...broker, token: manifest.token, generation: manifest.generation })}\n`;
+    try {
+        for (const directory of [manifest.channelDir, requestsDir, responsesDir, consumedDir, manifest.publicStatusDir, manifest.processingDir]) {
+            fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        }
+        assertRealDirectory(manifest.channelDir);
         assertRealDirectory(requestsDir, manifest.channelDir);
         assertRealDirectory(responsesDir, manifest.channelDir);
-        for (const name of fs.readdirSync(requestsDir).sort()) {
-            if (!/^[a-f0-9-]{16,64}\.json$/.test(name))
-                continue;
-            const requestPath = path.join(requestsDir, name);
-            let id = name.slice(0, -5);
-            let response;
+        assertRealDirectory(consumedDir, root);
+        assertRealDirectory(manifest.publicStatusDir, root);
+        assertRealDirectory(manifest.processingDir, root);
+        fs.writeFileSync(brokerPath, brokerRecord, { mode: 0o600, flag: 'wx' });
+        if (isSandboxControlRootQuiescing(root)) {
+            if (fs.readFileSync(brokerPath, 'utf8') === brokerRecord)
+                fs.unlinkSync(brokerPath);
+            return;
+        }
+    }
+    finally {
+        releaseStartup();
+    }
+    let active = null;
+    let lastState = '';
+    let lastStatusAt = 0;
+    try {
+        writeSandboxControlStatus(manifest, broker, 'starting', null, null);
+        appendSandboxControlAudit(manifest, 'broker-start', { pid: broker.pid });
+        recoverProcessing(manifest);
+        while (!signal.aborted) {
+            let current;
             try {
-                const stat = fs.lstatSync(requestPath);
-                if (!stat.isFile() || stat.isSymbolicLink())
-                    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID');
-                const request = validateSandboxControlRequest(JSON.parse(fs.readFileSync(requestPath, 'utf8')), manifest);
-                id = request.id;
-                if (consumed.has(id))
-                    throw new Error('SANDBOX_CONTROL_REQUEST_REPLAYED');
-                consumed.add(id);
-                const result = spawnSync(process.execPath, ['--experimental-strip-types', '--no-warnings', process.argv[1], request.family, ...bindSandboxControlTask(request, manifest.taskId)], {
-                    cwd: manifest.repoRoot,
-                    encoding: 'utf8',
-                    env: Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('AGENT_INFRA_CONTROL_')))
-                });
-                response = {
-                    version: 1,
-                    id,
-                    exitCode: result.status ?? 1,
-                    stdout: result.stdout ?? '',
-                    stderr: result.stderr ?? ''
-                };
+                current = readSandboxControlManifest(manifestPath);
+            }
+            catch {
+                break;
             }
-            catch (error) {
-                response = {
-                    version: 1,
-                    id,
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `${error instanceof Error ? error.message : String(error)}\n`
-                };
+            if (current.token !== manifest.token || current.generation !== manifest.generation)
+                break;
+            if (active?.settled) {
+                if (active.result) {
+                    writeResponse(manifest, {
+                        version: 2, id: active.request.id, phase: 'completed', exitCode: active.result.exitCode,
+                        stdout: active.result.stdout, stderr: active.result.stderr, error: null
+                    });
+                }
+                else {
+                    writeResponse(manifest, unknown(active.request.id));
+                }
+                fs.rmSync(path.join(manifest.processingDir, active.request.id), { recursive: true, force: true });
+                active = null;
             }
+            let reasonCode = null;
             try {
-                fs.unlinkSync(requestPath);
-                writeResponse(responsesDir, response);
+                if (cleanupStaleSandboxControlLease(manifest)) {
+                    appendSandboxControlAudit(manifest, 'lease-stale-cleanup');
+                }
+                if (readActiveLease(manifest))
+                    reasonCode = 'SANDBOX_CONTROL_HANDOFF_ACTIVE';
+            }
+            catch {
+                reasonCode = 'SANDBOX_CONTROL_HANDOFF_ACTIVE';
+            }
+            reasonCode ??= bindingReason(manifest);
+            const state = reasonCode ? 'parked' : active ? 'busy' : 'healthy';
+            const stateKey = `${state}:${reasonCode ?? ''}:${active?.request.id ?? ''}`;
+            const now = Date.now();
+            if (stateKey !== lastState || now - lastStatusAt >= SANDBOX_CONTROL_STATUS_INTERVAL_MS) {
+                writeSandboxControlStatus(manifest, broker, state, reasonCode, active?.request.id ?? null, now);
+                lastStatusAt = now;
+            }
+            if (stateKey !== lastState) {
+                appendSandboxControlAudit(manifest, 'broker-state', { state, reasonCode, requestId: active?.request.id ?? null });
+                lastState = stateKey;
             }
-            catch (error) {
-                if (error.code !== 'ENOENT')
-                    throw error;
+            for (const name of fs.readdirSync(requestsDir).sort()) {
+                if (!/^[a-f0-9-]{16,64}\.json$/.test(name))
+                    continue;
+                const id = name.slice(0, -5);
+                const source = path.join(requestsDir, name);
+                let claimed = null;
+                try {
+                    claimed = claimRequest(manifest, source, id);
+                    consumeRequest(consumedDir, id);
+                    if (reasonCode)
+                        throw new Error(reasonCode);
+                    if (active)
+                        throw new Error('SANDBOX_CONTROL_BUSY');
+                    const request = validateSandboxControlRequest(JSON.parse(fs.readFileSync(claimed, 'utf8')), manifest);
+                    if (bindingReason(manifest))
+                        throw new Error('SANDBOX_WORKTREE_BINDING_LOST');
+                    if (readActiveLease(manifest))
+                        throw new Error('SANDBOX_CONTROL_HANDOFF_ACTIVE');
+                    const prepared = await prepareSandboxControlExecution({
+                        manifest, manifestPath, request, requestPath: claimed, internalCliPath: process.argv[1]
+                    });
+                    const execution = { request, prepared, result: null, failure: null, settled: false };
+                    active = execution;
+                    prepared.completion.then((result) => { execution.result = result; execution.settled = true; }, (error) => { execution.failure = error; execution.settled = true; });
+                    writeResponse(manifest, {
+                        version: 2, id, phase: 'accepted', exitCode: null, stdout: '', stderr: '', error: null
+                    });
+                    try {
+                        prepared.start();
+                    }
+                    catch (error) {
+                        prepared.terminate();
+                        writeResponse(manifest, unknown(id));
+                        fs.rmSync(path.join(manifest.processingDir, id), { recursive: true, force: true });
+                        active = null;
+                        claimed = null;
+                        appendSandboxControlAudit(manifest, 'executor-gate-failed', { requestId: id });
+                        continue;
+                    }
+                }
+                catch (error) {
+                    writeResponse(manifest, rejected(id, error));
+                    if (claimed)
+                        fs.rmSync(path.dirname(claimed), { recursive: true, force: true });
+                }
             }
+            await delay(25);
+        }
+    }
+    finally {
+        if (active) {
+            active.prepared.terminate();
+            writeResponse(manifest, unknown(active.request.id));
+        }
+        appendSandboxControlAudit(manifest, 'broker-stop', { pid: broker.pid });
+        try {
+            if (fs.readFileSync(brokerPath, 'utf8') === brokerRecord)
+                fs.unlinkSync(brokerPath);
+        }
+        catch {
+            // A newer owner or recovery path owns the record.
         }
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
     }
 }
 //# sourceMappingURL=server.js.map

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

@@ -0,0 +1,181 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { buildProcessTreeStopCommand } from '../../server/process-control.js';
+import { processIdentityMatches } from '../../server/process-state.js';
+export const SANDBOX_CONTROL_AUDIT_MAX_BYTES = 1024 * 1024;
+export const SANDBOX_CONTROL_EXECUTION_STOP_MS = 2_000;
+function assertRegularFile(filePath) {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error('SANDBOX_CONTROL_STATE_INVALID');
+}
+export function atomicWriteJson(filePath, value, mode = 0o600, createParent = true) {
+    if (createParent)
+        fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode, flag: 'wx' });
+        fs.renameSync(temporary, filePath);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+export function readJsonFile(filePath) {
+    assertRegularFile(filePath);
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+export function statusPath(manifest) {
+    return path.join(manifest.publicStatusDir, 'status.json');
+}
+export function writeSandboxControlStatus(manifest, broker, state, reasonCode, activeRequestId, now = Date.now()) {
+    const status = {
+        version: 1, generation: manifest.generation, broker, state, reasonCode, activeRequestId, updatedAt: now
+    };
+    atomicWriteJson(statusPath(manifest), status, 0o600, false);
+    return status;
+}
+export function parseSandboxControlStatus(value) {
+    const status = value;
+    if (!status || status.version !== 1 || typeof status.generation !== 'string'
+        || !status.broker || !Number.isSafeInteger(status.broker.pid) || typeof status.broker.startTime !== 'string'
+        || !['starting', 'healthy', 'busy', 'parked'].includes(status.state ?? '')
+        || (status.reasonCode !== null && typeof status.reasonCode !== 'string')
+        || (status.activeRequestId !== null && typeof status.activeRequestId !== 'string')
+        || !Number.isSafeInteger(status.updatedAt))
+        throw new Error('SANDBOX_CONTROL_STATUS_INVALID');
+    return status;
+}
+export function readSandboxControlStatus(directory) {
+    return parseSandboxControlStatus(readJsonFile(path.join(directory, 'status.json')));
+}
+export function readActiveLease(manifest, now = Date.now()) {
+    const filePath = path.join(path.dirname(manifest.publicStatusDir), 'lease.json');
+    if (!fs.existsSync(filePath))
+        return null;
+    const lease = readJsonFile(filePath);
+    if (!lease || lease.version !== 1
+        || typeof lease.nonce !== 'string' || !lease.owner || !Number.isSafeInteger(lease.owner.pid)
+        || typeof lease.owner.startTime !== 'string' || !Number.isSafeInteger(lease.issuedAt)
+        || !Number.isSafeInteger(lease.expiresAt) || typeof lease.generation !== 'string'
+        || (lease.taskId !== null && typeof lease.taskId !== 'string')
+        || typeof lease.branch !== 'string' || typeof lease.reason !== 'string') {
+        throw new Error('SANDBOX_CONTROL_LEASE_INVALID');
+    }
+    if (lease.generation !== manifest.generation || lease.expiresAt <= now
+        || lease.taskId !== manifest.taskId || lease.branch !== manifest.branch)
+        return null;
+    return lease;
+}
+export function cleanupStaleSandboxControlLease(manifest, now = Date.now()) {
+    const filePath = path.join(path.dirname(manifest.publicStatusDir), 'lease.json');
+    if (!fs.existsSync(filePath))
+        return false;
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const lease = JSON.parse(raw);
+    if (!lease || lease.version !== 1
+        || typeof lease.nonce !== 'string' || !lease.owner || !Number.isSafeInteger(lease.owner.pid)
+        || typeof lease.owner.startTime !== 'string' || !Number.isSafeInteger(lease.issuedAt)
+        || !Number.isSafeInteger(lease.expiresAt) || typeof lease.generation !== 'string'
+        || (lease.taskId !== null && typeof lease.taskId !== 'string')
+        || typeof lease.branch !== 'string' || typeof lease.reason !== 'string') {
+        throw new Error('SANDBOX_CONTROL_LEASE_INVALID');
+    }
+    const stale = lease.generation !== manifest.generation || lease.taskId !== manifest.taskId
+        || lease.branch !== manifest.branch || lease.expiresAt <= now || !processIdentityMatches({
+        version: 1, pid: lease.owner.pid, startTime: lease.owner.startTime
+    });
+    if (!stale)
+        return false;
+    if (fs.readFileSync(filePath, 'utf8') !== raw)
+        throw new Error('SANDBOX_CONTROL_LEASE_OWNERSHIP_LOST');
+    fs.unlinkSync(filePath);
+    return true;
+}
+export function appendSandboxControlAudit(manifest, event, fields = {}, now = Date.now()) {
+    const auditPath = path.join(path.dirname(manifest.publicStatusDir), 'audit.ndjson');
+    if (fs.existsSync(auditPath) && fs.statSync(auditPath).size >= SANDBOX_CONTROL_AUDIT_MAX_BYTES) {
+        fs.rmSync(`${auditPath}.1`, { force: true });
+        fs.renameSync(auditPath, `${auditPath}.1`);
+    }
+    fs.appendFileSync(auditPath, `${JSON.stringify({ version: 1, event, generation: manifest.generation, at: now, ...fields })}\n`, {
+        encoding: 'utf8', mode: 0o600
+    });
+}
+export function executionPath(manifest, requestId) {
+    return path.join(manifest.processingDir, requestId, 'execution.json');
+}
+export function readExecution(filePath) {
+    const execution = readJsonFile(filePath);
+    if (!execution || execution.version !== 1 || typeof execution.generation !== 'string'
+        || typeof execution.requestId !== 'string' || typeof execution.nonce !== 'string'
+        || !execution.child || !Number.isSafeInteger(execution.child.pid) || typeof execution.child.startTime !== 'string'
+        || !['prepared', 'running', 'terminating'].includes(execution.phase ?? '')
+        || !Number.isSafeInteger(execution.updatedAt))
+        throw new Error('SANDBOX_CONTROL_EXECUTION_INVALID');
+    return execution;
+}
+export function terminateSandboxControlExecution(execution, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const processGroupId = execution.child.processGroupId;
+    const processGroupAlive = (groupId) => {
+        try {
+            const rows = execFileSync('ps', ['-axo', 'pgid=,stat='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+            return rows.split('\n').some((row) => {
+                const match = row.trim().match(/^(\d+)\s+(\S+)/);
+                return Number(match?.[1]) === groupId && !match?.[2]?.startsWith('Z');
+            });
+        }
+        catch {
+            try {
+                process.kill(-groupId, 0);
+                return true;
+            }
+            catch (error) {
+                return error.code === 'EPERM';
+            }
+        }
+    };
+    const treeAlive = () => {
+        if (platform === 'win32' || !processGroupId) {
+            return processIdentityMatches({ version: 1, pid: execution.child.pid, startTime: execution.child.startTime });
+        }
+        return processGroupAlive(processGroupId);
+    };
+    if (!treeAlive())
+        return true;
+    const command = buildProcessTreeStopCommand(processGroupId ?? execution.child.pid, platform);
+    try {
+        if (command.kind === 'exec')
+            execFileSync(command.command, command.args, { stdio: 'ignore' });
+        else
+            process.kill(command.pid, command.signal);
+    }
+    catch {
+        // The identity check below distinguishes an already-exited tree from a failed termination.
+    }
+    const deadline = Date.now() + (options.timeoutMs ?? SANDBOX_CONTROL_EXECUTION_STOP_MS);
+    while (Date.now() < deadline) {
+        if (!treeAlive())
+            return true;
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+    if (platform !== 'win32') {
+        try {
+            process.kill(processGroupId ? -processGroupId : execution.child.pid, 'SIGKILL');
+        }
+        catch {
+            // The final identity check handles an already-exited tree.
+        }
+        const killDeadline = Date.now() + (options.timeoutMs ?? SANDBOX_CONTROL_EXECUTION_STOP_MS);
+        while (Date.now() < killDeadline) {
+            if (!treeAlive())
+                return true;
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+        }
+    }
+    return !treeAlive();
+}
+//# sourceMappingURL=state.js.map

package/dist/lib/sandbox/index.js

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