@fitlab-ai/agent-infra 0.9.4 → 0.9.6

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

@@ -1,44 +1,174 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { SANDBOX_CONTROL_MAX_BYTES, isSandboxControlFamily } from './protocol.js';
+import { SANDBOX_CONTROL_ADMISSION_WINDOW_MS, SANDBOX_CONTROL_MAX_BYTES, SANDBOX_CONTROL_STATUS_STALE_MS, isSandboxControlFamily } from './protocol.js';
+import { readSandboxControlStatus } from './state.js';
+const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
+export class SandboxControlClientError extends Error {
+    detail;
+    accepted;
+    constructor(detail, accepted = false) {
+        super(detail.message);
+        this.name = 'SandboxControlClientError';
+        this.detail = detail;
+        this.accepted = accepted;
+    }
+}
 function sleep(milliseconds) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
 }
-export function requestSandboxControl(params) {
-    if (!isSandboxControlFamily(params.family)) {
-        throw new Error(`SANDBOX_CONTROL_COMMAND_DENIED: '${params.family}' is not allowed`);
+function clientError(code, message, retryable, accepted = false) {
+    throw new SandboxControlClientError({ code, message: `${code}: ${message}`, retryable }, accepted);
+}
+function preflight(statusDir, generation, now = Date.now()) {
+    let status;
+    try {
+        status = readSandboxControlStatus(statusDir);
+    }
+    catch {
+        clientError('SANDBOX_CONTROL_BROKER_UNAVAILABLE', 'broker status is missing or invalid', true);
     }
+    if (status.generation !== generation) {
+        clientError('SANDBOX_CONTROL_GENERATION_INVALID', 'broker status generation does not match this sandbox', false);
+    }
+    if (now - status.updatedAt > SANDBOX_CONTROL_STATUS_STALE_MS || status.updatedAt > now + 1_000) {
+        clientError('SANDBOX_CONTROL_BROKER_UNAVAILABLE', 'broker status heartbeat is stale', true);
+    }
+    if (status.state === 'busy')
+        clientError('SANDBOX_CONTROL_BUSY', 'broker is executing another request', true);
+    if (status.state === 'parked') {
+        const code = status.reasonCode ?? 'SANDBOX_CONTROL_BROKER_UNAVAILABLE';
+        clientError(code, 'broker is parked until the host restores a valid binding', true);
+    }
+    if (status.state !== 'healthy')
+        clientError('SANDBOX_CONTROL_BROKER_UNAVAILABLE', 'broker is not ready', true);
+}
+function parseResponse(raw, id) {
+    const response = JSON.parse(raw);
+    if (response.version !== 2 || response.id !== id
+        || !['accepted', 'completed', 'rejected'].includes(response.phase)
+        || (response.phase === 'completed' && !Number.isInteger(response.exitCode))) {
+        clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response is invalid', false);
+    }
+    return response;
+}
+function cancelPendingRequest(requestPath) {
+    try {
+        fs.unlinkSync(requestPath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function exchangeSandboxControl(request, params) {
     const channelDir = params.channelDir ?? process.env.AGENT_INFRA_CONTROL_DIR ?? '/run/agent-infra/control';
-    const token = params.token ?? process.env.AGENT_INFRA_CONTROL_TOKEN;
-    if (!token)
-        throw new Error('SANDBOX_CONTROL_UNAVAILABLE: control token is missing');
-    const requestsDir = path.join(channelDir, 'requests');
-    const responsesDir = path.join(channelDir, 'responses');
-    const id = randomUUID();
-    const request = { version: 1, id, token, family: params.family, args: params.args };
+    const statusDir = params.statusDir ?? process.env.AGENT_INFRA_CONTROL_STATUS_DIR ?? '/run/agent-infra/control-status';
+    preflight(statusDir, request.generation);
     const encoded = `${JSON.stringify(request)}\n`;
     if (Buffer.byteLength(encoded, 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
-        throw new Error('SANDBOX_CONTROL_REQUEST_TOO_LARGE: request exceeds the control limit');
+        clientError('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit', false);
     }
-    const temporary = path.join(requestsDir, `.${id}.tmp`);
-    const requestPath = path.join(requestsDir, `${id}.json`);
-    const responsePath = path.join(responsesDir, `${id}.json`);
+    const requestsDir = path.join(channelDir, 'requests');
+    const responsesDir = path.join(channelDir, 'responses');
+    const temporary = path.join(requestsDir, `.${request.id}.tmp`);
+    const requestPath = path.join(requestsDir, `${request.id}.json`);
+    const responsePath = path.join(responsesDir, `${request.id}.json`);
     fs.writeFileSync(temporary, encoded, { mode: 0o600, flag: 'wx' });
     fs.renameSync(temporary, requestPath);
     const deadline = Date.now() + (params.timeoutMs ?? 30_000);
+    let accepted = false;
+    let malformedResponseRaw = null;
+    let malformedResponseObservedAt = 0;
     while (Date.now() < deadline) {
         if (fs.existsSync(responsePath)) {
-            const raw = fs.readFileSync(responsePath, 'utf8');
-            fs.unlinkSync(responsePath);
-            const response = JSON.parse(raw);
-            if (response.version !== 1 || response.id !== id || !Number.isInteger(response.exitCode)) {
-                throw new Error('SANDBOX_CONTROL_RESPONSE_INVALID: broker response is invalid');
+            let raw;
+            try {
+                raw = fs.readFileSync(responsePath, 'utf8');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            let response;
+            try {
+                response = parseResponse(raw, request.id);
+                malformedResponseRaw = null;
+            }
+            catch (error) {
+                if (!(error instanceof SyntaxError))
+                    throw error;
+                const now = Date.now();
+                if (malformedResponseRaw !== raw) {
+                    malformedResponseRaw = raw;
+                    malformedResponseObservedAt = now;
+                }
+                else if (now - malformedResponseObservedAt >= SANDBOX_CONTROL_RESPONSE_SETTLE_MS) {
+                    clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response remained malformed', false, accepted);
+                }
+                sleep(25);
+                continue;
+            }
+            if (response.phase === 'accepted') {
+                accepted = true;
+            }
+            else {
+                fs.rmSync(responsePath, { force: true });
+                return response;
+            }
+        }
+        if (!accepted) {
+            try {
+                preflight(statusDir, request.generation);
+            }
+            catch (error) {
+                if (cancelPendingRequest(requestPath))
+                    throw error;
+                clientError('SANDBOX_CONTROL_RESULT_UNKNOWN', 'request was claimed before broker availability was lost; inspect domain state before retrying', false, true);
             }
-            return response;
         }
         sleep(25);
     }
-    throw new Error(`SANDBOX_CONTROL_TIMEOUT: broker did not respond within ${params.timeoutMs ?? 30_000}ms`);
+    if (accepted) {
+        clientError('SANDBOX_CONTROL_RESULT_UNKNOWN', 'accepted request did not produce a final result; inspect domain state before retrying', false, true);
+    }
+    if (!cancelPendingRequest(requestPath)) {
+        clientError('SANDBOX_CONTROL_RESULT_UNKNOWN', 'request was claimed but no acceptance result was observed; inspect domain state before retrying', false, true);
+    }
+    clientError('SANDBOX_CONTROL_BROKER_UNAVAILABLE', `broker did not accept the request within ${params.timeoutMs ?? 30_000}ms`, true);
+}
+function authority(params) {
+    const token = params.token ?? process.env.AGENT_INFRA_CONTROL_TOKEN;
+    const generation = params.generation ?? process.env.AGENT_INFRA_CONTROL_GENERATION;
+    if (!token || !generation)
+        clientError('SANDBOX_CONTROL_UNAVAILABLE', 'control authority is missing', false);
+    return { token, generation };
+}
+export function requestSandboxControl(params) {
+    if (!isSandboxControlFamily(params.family))
+        clientError('SANDBOX_CONTROL_COMMAND_DENIED', `'${params.family}' is not allowed`, false);
+    if (params.family === 'task-create')
+        clientError('SANDBOX_CONTROL_COMMAND_DENIED', "'task-create' requires a typed candidate", false);
+    const auth = authority(params);
+    const issuedAt = Date.now();
+    const request = {
+        version: 2, id: randomUUID(), ...auth, issuedAt,
+        expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
+        family: params.family, args: params.args
+    };
+    return exchangeSandboxControl(request, params);
+}
+export function requestSandboxTaskCreate(params) {
+    const auth = authority(params);
+    const issuedAt = Date.now();
+    const request = {
+        version: 2, id: randomUUID(), ...auth, issuedAt,
+        expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
+        family: 'task-create', candidate: params.candidate
+    };
+    return exchangeSandboxControl(request, { ...params, timeoutMs: params.timeoutMs ?? 120_000 });
 }
 //# sourceMappingURL=client.js.map

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

@@ -0,0 +1,136 @@
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { getProcessStartTime } from '../../server/process-state.js';
+import { createTask } from '../../task/create-service.js';
+import { bindSandboxControlTask } from './protocol.js';
+import { atomicWriteJson, executionPath, terminateSandboxControlExecution } from './state.js';
+function safeEnv(env) {
+    return Object.fromEntries(Object.entries(env).filter(([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')));
+}
+export function nodeEntryArgs(entry, args) {
+    return path.extname(entry) === '.ts'
+        ? ['--experimental-strip-types', '--no-warnings', entry, ...args]
+        : [entry, ...args];
+}
+async function waitForStartTime(pid, timeoutMs = 2_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const startTime = getProcessStartTime(pid);
+        if (startTime)
+            return startTime;
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    throw new Error('SANDBOX_CONTROL_EXECUTOR_IDENTITY_UNAVAILABLE');
+}
+export async function prepareSandboxControlExecution(params) {
+    const nonce = randomUUID();
+    const child = spawn(process.execPath, nodeEntryArgs(params.internalCliPath, [
+        'sandbox-control', 'execute', '--request', params.requestPath, '--nonce', nonce
+    ]), {
+        cwd: params.manifest.repoRoot,
+        detached: process.platform !== 'win32',
+        stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+        env: { ...safeEnv(process.env), AGENT_INFRA_EXECUTOR_MANIFEST: params.manifestPath }
+    });
+    if (typeof child.pid !== 'number')
+        throw new Error('SANDBOX_CONTROL_EXECUTOR_SPAWN_FAILED');
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.setEncoding('utf8');
+    child.stderr?.setEncoding('utf8');
+    child.stdout?.on('data', (chunk) => { stdout += chunk; });
+    child.stderr?.on('data', (chunk) => { stderr += chunk; });
+    const completion = new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('close', (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
+    });
+    const startTime = await waitForStartTime(child.pid);
+    const execution = {
+        version: 1,
+        generation: params.manifest.generation,
+        requestId: params.request.id,
+        nonce,
+        child: {
+            pid: child.pid,
+            startTime,
+            processGroupId: process.platform === 'win32' ? null : child.pid
+        },
+        phase: 'prepared',
+        updatedAt: Date.now()
+    };
+    atomicWriteJson(executionPath(params.manifest, params.request.id), execution);
+    return {
+        execution,
+        start() {
+            if (!child.connected)
+                throw new Error('SANDBOX_CONTROL_EXECUTOR_GATE_CLOSED');
+            atomicWriteJson(executionPath(params.manifest, params.request.id), { ...execution, phase: 'running', updatedAt: Date.now() });
+            child.send({ version: 1, nonce });
+        },
+        completion,
+        terminate() {
+            atomicWriteJson(executionPath(params.manifest, params.request.id), {
+                ...execution, phase: 'terminating', updatedAt: Date.now()
+            });
+            return terminateSandboxControlExecution(execution);
+        }
+    };
+}
+function waitForGate(nonce, timeoutMs = 2_000) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('SANDBOX_CONTROL_EXECUTOR_GATE_TIMEOUT')), timeoutMs);
+        const onDisconnect = () => {
+            clearTimeout(timer);
+            reject(new Error('SANDBOX_CONTROL_EXECUTOR_GATE_CLOSED'));
+        };
+        process.once('disconnect', onDisconnect);
+        process.once('message', (message) => {
+            clearTimeout(timer);
+            process.off('disconnect', onDisconnect);
+            const value = message;
+            if (!value || value.version !== 1 || value.nonce !== nonce) {
+                reject(new Error('SANDBOX_CONTROL_EXECUTOR_GATE_INVALID'));
+                return;
+            }
+            resolve();
+        });
+    });
+}
+function executeRequest(manifest, request) {
+    if (request.family === 'task-create') {
+        const result = createTask(request.candidate, { repoRoot: manifest.repoRoot });
+        return {
+            exitCode: result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0,
+            stdout: `${JSON.stringify(result)}\n`,
+            stderr: ''
+        };
+    }
+    const boundArgs = bindSandboxControlTask(request, manifest.taskId);
+    if (request.family === 'task-orchestration')
+        boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
+    const result = spawnSync(process.execPath, nodeEntryArgs(process.argv[1], [request.family, ...boundArgs]), { cwd: manifest.repoRoot, encoding: 'utf8', env: safeEnv(process.env) });
+    return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}
+export async function runSandboxControlExecutor(requestPath, nonce) {
+    await waitForGate(nonce);
+    process.disconnect?.();
+    const root = fs.realpathSync.native(process.cwd());
+    const request = JSON.parse(fs.readFileSync(requestPath, 'utf8'));
+    const manifestPath = process.env.AGENT_INFRA_EXECUTOR_MANIFEST;
+    if (!manifestPath)
+        throw new Error('SANDBOX_CONTROL_EXECUTOR_MANIFEST_MISSING');
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    if (fs.realpathSync.native(manifest.repoRoot) !== root)
+        throw new Error('SANDBOX_CONTROL_EXECUTOR_ROOT_INVALID');
+    const result = executeRequest(manifest, request);
+    process.stdout.write(result.stdout);
+    process.stderr.write(result.stderr);
+    process.exitCode = result.exitCode;
+}
+export function disconnectExecutor(child) {
+    if (child.connected)
+        child.disconnect();
+}
+//# sourceMappingURL=executor.js.map

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

@@ -0,0 +1,348 @@
+import { execFileSync } from 'node:child_process';
+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 { parseSandboxControlStatus, readExecution, terminateSandboxControlExecution } from './state.js';
+const DEFAULT_QUIESCE_TIMEOUT_MS = 7_000;
+const QUIESCING_FILE = 'quiescing.json';
+const BROKER_STARTING_FILE = 'broker-starting.json';
+function regularFile(filePath) {
+    try {
+        const stat = fs.lstatSync(filePath);
+        return stat.isFile() && !stat.isSymbolicLink();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+export function isSandboxControlRootQuiescing(root) {
+    return fs.existsSync(path.join(path.resolve(root), QUIESCING_FILE));
+}
+function markSandboxControlRootQuiescing(root) {
+    const markerPath = path.join(root, QUIESCING_FILE);
+    try {
+        fs.writeFileSync(markerPath, `${JSON.stringify({ version: 1, startedAt: Date.now() })}\n`, {
+            mode: 0o600,
+            flag: 'wx'
+        });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        if (!regularFile(markerPath))
+            throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+    }
+}
+function readStartupOwner(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    if (!regularFile(filePath))
+        throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
+    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')
+            return null;
+        return { raw, owner: { pid: record.pid, startTime: record.startTime } };
+    }
+    catch {
+        return null;
+    }
+}
+async function waitForStartupTransition(root, timeoutMs) {
+    const transitionPath = path.join(root, BROKER_STARTING_FILE);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const transition = readStartupOwner(transitionPath);
+        if (!fs.existsSync(transitionPath))
+            return;
+        if (transition && !ownerLive(transition.owner)) {
+            try {
+                if (fs.readFileSync(transitionPath, 'utf8') === transition.raw)
+                    fs.unlinkSync(transitionPath);
+            }
+            catch {
+                // A concurrent startup transition changed or removed the record.
+            }
+            continue;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
+}
+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 deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (isSandboxControlRootQuiescing(resolvedRoot))
+            throw new Error('SANDBOX_CONTROL_QUIESCING');
+        try {
+            fs.writeFileSync(transitionPath, record, { mode: 0o600, flag: 'wx' });
+            if (isSandboxControlRootQuiescing(resolvedRoot)) {
+                try {
+                    if (fs.readFileSync(transitionPath, 'utf8') === record)
+                        fs.unlinkSync(transitionPath);
+                }
+                catch {
+                    // The deletion side owns the transition now.
+                }
+                throw new Error('SANDBOX_CONTROL_QUIESCING');
+            }
+            return () => {
+                try {
+                    if (fs.readFileSync(transitionPath, 'utf8') === record)
+                        fs.unlinkSync(transitionPath);
+                }
+                catch {
+                    // A newer transition or deletion owns the path.
+                }
+            };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const transition = readStartupOwner(transitionPath);
+            if (transition && !ownerLive(transition.owner)) {
+                try {
+                    if (fs.readFileSync(transitionPath, 'utf8') === transition.raw)
+                        fs.unlinkSync(transitionPath);
+                }
+                catch {
+                    // A concurrent transition changed the record.
+                }
+                continue;
+            }
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+    }
+    throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
+}
+export function readSandboxControlManifest(manifestPath) {
+    if (!regularFile(manifestPath))
+        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    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 (typeof manifest.repoRoot !== 'string' || typeof manifest.worktreeRoot !== 'string'
+        || typeof manifest.project !== 'string' || typeof manifest.container !== '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'
+        || typeof manifest.processingDir !== 'string' || typeof manifest.token !== 'string'
+        || typeof manifest.generation !== 'string')
+        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+    const root = path.dirname(path.resolve(manifestPath));
+    if (path.resolve(manifest.channelDir) !== path.join(root, 'channel')
+        || path.resolve(manifest.publicStatusDir) !== path.join(root, 'public')
+        || path.resolve(manifest.processingDir) !== path.join(root, 'processing')) {
+        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+    }
+    return manifest;
+}
+function readBrokerOwner(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    if (!regularFile(filePath))
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    let owner;
+    try {
+        owner = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    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')
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    return owner;
+}
+function readStatusOwner(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    if (!regularFile(filePath))
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    try {
+        return parseSandboxControlStatus(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+    }
+    catch {
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    }
+}
+function sameOwner(left, right) {
+    return left.pid === right.pid && left.startTime === right.startTime;
+}
+function ownerLive(owner) {
+    return processIdentityMatches({ version: 1, pid: owner.pid, startTime: owner.startTime });
+}
+function readExecutions(manifest) {
+    if (!fs.existsSync(manifest.processingDir))
+        return [];
+    const stat = fs.lstatSync(manifest.processingDir);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
+    const executions = [];
+    for (const entry of fs.readdirSync(manifest.processingDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.isSymbolicLink())
+            continue;
+        const descriptor = path.join(manifest.processingDir, entry.name, 'execution.json');
+        if (!fs.existsSync(descriptor))
+            continue;
+        let execution;
+        try {
+            execution = readExecution(descriptor);
+        }
+        catch {
+            throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${entry.name}`);
+        }
+        if (execution.generation !== manifest.generation || execution.requestId !== entry.name) {
+            throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${entry.name}`);
+        }
+        if (execution.child.pid <= 0 || (execution.child.processGroupId !== null
+            && (!Number.isSafeInteger(execution.child.processGroupId) || execution.child.processGroupId <= 0))) {
+            throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${entry.name}`);
+        }
+        executions.push(execution);
+    }
+    return executions;
+}
+function 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';
+        }
+    }
+}
+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 });
+}
+async function waitForExit(owner, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!ownerLive(owner))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    return !ownerLive(owner);
+}
+function signalOwner(owner, platform, force) {
+    try {
+        if (platform === 'win32') {
+            const command = buildProcessTreeStopCommand(owner.pid, platform);
+            if (command.kind === 'exec')
+                execFileSync(command.command, command.args, { stdio: 'ignore' });
+            return;
+        }
+        process.kill(owner.pid, force ? 'SIGKILL' : 'SIGTERM');
+    }
+    catch {
+        // The identity checks decide whether the owner actually exited.
+    }
+}
+function mergeExecutions(...groups) {
+    const merged = new Map();
+    for (const execution of groups.flat())
+        merged.set(`${execution.requestId}:${execution.nonce}`, execution);
+    return [...merged.values()];
+}
+export async function quiesceSandboxControlRoot(root, options = {}) {
+    const resolvedRoot = path.resolve(root);
+    if (!fs.existsSync(resolvedRoot))
+        return 'missing';
+    const rootStat = fs.lstatSync(resolvedRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+    for (const directory of [path.join(resolvedRoot, 'public'), path.join(resolvedRoot, 'processing')]) {
+        if (!fs.existsSync(directory))
+            continue;
+        const stat = fs.lstatSync(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+    }
+    markSandboxControlRootQuiescing(resolvedRoot);
+    await waitForStartupTransition(resolvedRoot, options.timeoutMs ?? DEFAULT_QUIESCE_TIMEOUT_MS);
+    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 brokerLive = broker ? ownerLive(broker) : false;
+    const statusLive = statusOwner ? ownerLive(statusOwner) : false;
+    if (manifest && broker && (broker.token !== manifest.token || broker.generation !== manifest.generation)) {
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    }
+    if (manifest && status && status.generation !== manifest.generation) {
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    }
+    if (broker && statusOwner && !sameOwner(broker, statusOwner) && (brokerLive || statusLive)) {
+        throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+    }
+    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 })) {
+                throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
+            }
+        }
+        if (executions.some((execution) => executionAlive(execution, platform))) {
+            throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
+        }
+        return broker || status ? 'stale' : 'missing';
+    }
+    signalOwner(owner, platform, false);
+    if (await waitForExit(owner, timeoutMs)) {
+        if (executions.some((execution) => executionAlive(execution, platform))) {
+            throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
+        }
+        return 'stopped';
+    }
+    if (manifest)
+        executions = mergeExecutions(executions, readExecutions(manifest));
+    for (const execution of executions) {
+        if (!terminateSandboxControlExecution(execution, { platform, timeoutMs })) {
+            throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
+        }
+    }
+    signalOwner(owner, platform, true);
+    if (!await waitForExit(owner, timeoutMs))
+        throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
+    if (executions.some((execution) => executionAlive(execution, platform))) {
+        throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
+    }
+    return 'stopped';
+}
+//# sourceMappingURL=lifecycle.js.map