@fitlab-ai/agent-infra 0.9.8 → 0.9.10

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

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { SANDBOX_CONTROL_ADMISSION_WINDOW_MS, SANDBOX_CONTROL_MAX_BYTES, SANDBOX_CONTROL_STATUS_STALE_MS, isSandboxControlFamily } from './protocol.js';
+import { normalizeAgentToken } from '../../agent-clients/tokens.js';
 import { readSandboxControlStatus } from './state.js';
 const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
 export class SandboxControlClientError extends Error {
@@ -150,24 +151,207 @@ function authority(params) {
 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);
+    if (params.family === 'task-create' || params.family === 'codex-controller' || params.family === 'task-finalization') {
+        clientError('SANDBOX_CONTROL_COMMAND_DENIED', `'${params.family}' requires a typed request`, false);
+    }
+    const auth = authority(params);
+    const issuedAt = Date.now();
+    const request = {
+        version: 3, id: randomUUID(), ...auth, issuedAt,
+        expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
+        family: params.family, args: params.args,
+        controllerProcess: null,
+        controllerProof: null
+    };
+    return exchangeSandboxControl(request, params);
+}
+export function requestSandboxTaskControl(params) {
     const auth = authority(params);
     const issuedAt = Date.now();
     const request = {
-        version: 2, id: randomUUID(), ...auth, issuedAt,
+        version: 3,
+        id: randomUUID(),
+        ...auth,
+        issuedAt,
         expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
-        family: params.family, args: params.args
+        family: params.family,
+        args: params.args,
+        controllerProcess: null,
+        controllerProof: params.controllerProof
     };
     return exchangeSandboxControl(request, params);
 }
+export function requestSandboxTaskFinalization(params) {
+    const agent = normalizeAgentToken(params.agent);
+    if (!agent)
+        clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'task-finalization agent is invalid', false);
+    const auth = authority(params);
+    const issuedAt = Date.now();
+    const request = {
+        version: 3,
+        id: randomUUID(),
+        ...auth,
+        issuedAt,
+        expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
+        family: 'task-finalization',
+        operation: 'complete',
+        agent,
+        args: [],
+        controllerProcess: null,
+        controllerProof: null
+    };
+    return exchangeSandboxControl(request, params);
+}
+function exactKeys(value, keys) {
+    return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+function validProcess(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const identity = value;
+    return exactKeys(identity, ['pid', 'startTime'])
+        && Number.isSafeInteger(identity.pid) && identity.pid > 0
+        && Number.isSafeInteger(identity.startTime) && identity.startTime >= 0;
+}
+function validBuild(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const build = value;
+    return exactKeys(build, ['internalExecutableBuildHash', 'lifecycleContractHash', 'packageVersion', 'protocolVersion'])
+        && build.protocolVersion === 3
+        && typeof build.packageVersion === 'string' && build.packageVersion.length > 0
+        && typeof build.internalExecutableBuildHash === 'string' && /^[a-f0-9]{64}$/u.test(build.internalExecutableBuildHash)
+        && typeof build.lifecycleContractHash === 'string' && /^[a-f0-9]{64}$/u.test(build.lifecycleContractHash);
+}
+export function parseCodexControllerResult(response) {
+    if (response.phase !== 'completed' || response.error !== null || response.stderr !== '') {
+        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result outer response is invalid', false, true);
+    }
+    let value;
+    try {
+        if (!response.stdout.endsWith('\n') || response.stdout.slice(0, -1).includes('\n'))
+            throw new Error('not canonical');
+        value = JSON.parse(response.stdout);
+    }
+    catch {
+        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result payload is invalid', false, true);
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result payload is invalid', false, true);
+    }
+    const result = value;
+    const resultKeys = result.status === 'verified'
+        ? ['binding', 'changed', 'error', 'lease', 'status', 'version']
+        : ['changed', 'error', 'lease', 'status', 'version'];
+    if (!exactKeys(result, resultKeys)
+        || result.version !== 1 || !['opened', 'closed', 'failed', 'verified'].includes(result.status)) {
+        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result schema is invalid', false, true);
+    }
+    if (result.status === 'failed') {
+        const error = result.error;
+        if (response.exitCode !== 1 || result.changed !== false || result.lease !== null
+            || !error || !exactKeys(error, ['code', 'message', 'retryable'])
+            || typeof error.code !== 'string' || !/^[A-Z][A-Z0-9_]+$/u.test(error.code)
+            || typeof error.message !== 'string' || error.retryable !== false) {
+            clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller failure result is invalid', false, true);
+        }
+        clientError(error.code, error.message, false, true);
+    }
+    if (response.exitCode !== 0 || result.error !== null) {
+        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller success result is invalid', false, true);
+    }
+    if (result.status === 'closed') {
+        if (typeof result.changed !== 'boolean' || result.lease !== null) {
+            clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller close result is invalid', false, true);
+        }
+        return result;
+    }
+    if (result.status === 'verified') {
+        const binding = result.binding;
+        if (result.changed !== false || result.lease !== null || !binding
+            || !exactKeys(binding, ['controllerInstanceDigest', 'controlGeneration', 'taskId'])
+            || typeof binding.taskId !== 'string' || binding.taskId.length === 0
+            || typeof binding.controlGeneration !== 'string' || binding.controlGeneration.length === 0
+            || typeof binding.controllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(binding.controllerInstanceDigest)) {
+            clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller verify result is invalid', false, true);
+        }
+        return result;
+    }
+    const lease = result.lease;
+    if (result.changed !== true || !lease
+        || !exactKeys(lease, [
+            'buildIdentity', 'controlGeneration', 'controllerInstanceDigest', 'controllerProcess',
+            'expiresAt', 'issuedAt', 'leaseId', 'leaseSecret', 'taskId', 'version'
+        ])
+        || lease.version !== 1
+        || typeof lease.leaseId !== 'string' || !/^[a-f0-9]{64}$/u.test(lease.leaseId)
+        || typeof lease.leaseSecret !== 'string' || !/^[a-f0-9]{64}$/u.test(lease.leaseSecret)
+        || typeof lease.taskId !== 'string' || lease.taskId.length === 0
+        || typeof lease.controlGeneration !== 'string' || lease.controlGeneration.length === 0
+        || typeof lease.controllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(lease.controllerInstanceDigest)
+        || !validProcess(lease.controllerProcess) || !validBuild(lease.buildIdentity)
+        || !Number.isSafeInteger(lease.issuedAt) || !Number.isSafeInteger(lease.expiresAt)
+        || lease.expiresAt <= lease.issuedAt) {
+        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller open result is invalid', false, true);
+    }
+    return result;
+}
+function requestCodexController(params) {
+    const auth = authority(params);
+    const issuedAt = Date.now();
+    const request = {
+        version: 3,
+        id: randomUUID(),
+        ...auth,
+        issuedAt,
+        expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
+        family: 'codex-controller',
+        command: params.command,
+        args: [],
+        controllerProcess: params.controllerProcess,
+        controllerProof: params.controllerProof
+    };
+    const result = parseCodexControllerResult(exchangeSandboxControl(request, params));
+    if (result.status === 'opened'
+        && (result.lease.controlGeneration !== auth.generation
+            || result.lease.controllerProcess.pid !== params.controllerProcess.pid
+            || result.lease.controllerProcess.startTime !== params.controllerProcess.startTime)) {
+        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result does not match the request', false, true);
+    }
+    return result;
+}
+export function requestCodexControllerOpen(params) {
+    const result = requestCodexController({ ...params, command: 'open', controllerProof: null });
+    if (result.status !== 'opened')
+        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller open returned the wrong result', false, true);
+    return result;
+}
+export function requestCodexControllerClose(params) {
+    const result = requestCodexController({ ...params, command: 'close' });
+    if (result.status !== 'closed')
+        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller close returned the wrong result', false, true);
+    return result;
+}
+export function requestCodexControllerVerify(params) {
+    const result = requestCodexController({
+        ...params,
+        controllerProcess: params.controllerProof.controllerProcess,
+        command: 'verify'
+    });
+    if (result.status !== 'verified') {
+        clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller verify returned the wrong result', false, true);
+    }
+    return result;
+}
 export function requestSandboxTaskCreate(params) {
     const auth = authority(params);
     const issuedAt = Date.now();
     const request = {
-        version: 2, id: randomUUID(), ...auth, issuedAt,
+        version: 3, id: randomUUID(), ...auth, issuedAt,
         expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
-        family: 'task-create', candidate: params.candidate
+        family: 'task-create', candidate: params.candidate,
+        controllerProcess: null,
+        controllerProof: null
     };
     return exchangeSandboxControl(request, { ...params, timeoutMs: params.timeoutMs ?? 120_000 });
 }

package/dist/lib/sandbox/control/controller-registration.js

@@ -0,0 +1,275 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseLinuxProcessStat } from '../../server/process-state.js';
+import { commandForEngine, runProbe } from '../shell.js';
+const CONTROLLER_TTL_MS = 4 * 60 * 60 * 1_000;
+const HEX_256 = /^[a-f0-9]{64}$/u;
+const REGISTRATION_KEYS = [
+    'buildIdentity', 'containerId', 'controlGeneration', 'controllerInstanceDigest',
+    'controllerProcess', 'expiresAt', 'issuedAt', 'leaseId', 'leaseSecretHash',
+    'taskId', 'version'
+].sort().join(',');
+export class CodexControllerRegistrationError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.name = code;
+        this.code = code;
+    }
+}
+function fail(code, message) {
+    throw new CodexControllerRegistrationError(code, message);
+}
+function exactKeys(value, keys) {
+    return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+function validProcess(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const processValue = value;
+    return exactKeys(processValue, ['pid', 'startTime'])
+        && Number.isSafeInteger(processValue.pid) && processValue.pid > 0
+        && Number.isSafeInteger(processValue.startTime) && processValue.startTime >= 0;
+}
+function validBuild(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const build = value;
+    return exactKeys(build, [
+        'internalExecutableBuildHash', 'lifecycleContractHash', 'packageVersion', 'protocolVersion'
+    ])
+        && build.protocolVersion === 3
+        && typeof build.packageVersion === 'string' && build.packageVersion.length > 0
+        && typeof build.internalExecutableBuildHash === 'string' && HEX_256.test(build.internalExecutableBuildHash)
+        && typeof build.lifecycleContractHash === 'string' && HEX_256.test(build.lifecycleContractHash);
+}
+function parseRegistration(raw) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        fail('CODEX_SANDBOX_CONTROLLER_REGISTRATION_INVALID', 'controller registration is malformed');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        fail('CODEX_SANDBOX_CONTROLLER_REGISTRATION_INVALID', 'controller registration is invalid');
+    }
+    const registration = value;
+    if (Object.keys(registration).sort().join(',') !== REGISTRATION_KEYS
+        || registration.version !== 1
+        || typeof registration.taskId !== 'string'
+        || typeof registration.controlGeneration !== 'string'
+        || typeof registration.containerId !== 'string'
+        || typeof registration.leaseId !== 'string' || !HEX_256.test(registration.leaseId)
+        || typeof registration.leaseSecretHash !== 'string' || !HEX_256.test(registration.leaseSecretHash)
+        || typeof registration.controllerInstanceDigest !== 'string' || !HEX_256.test(registration.controllerInstanceDigest)
+        || !validProcess(registration.controllerProcess)
+        || !validBuild(registration.buildIdentity)
+        || !Number.isSafeInteger(registration.issuedAt)
+        || !Number.isSafeInteger(registration.expiresAt)
+        || registration.expiresAt <= registration.issuedAt) {
+        fail('CODEX_SANDBOX_CONTROLLER_REGISTRATION_INVALID', 'controller registration schema is invalid');
+    }
+    return registration;
+}
+function registrationPath(manifestPath) {
+    return path.join(path.dirname(path.resolve(manifestPath)), 'codex-controller.json');
+}
+function readRaw(file) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink()
+            || (process.platform !== 'win32' && (stat.mode & 0o777) !== 0o600)) {
+            fail('CODEX_SANDBOX_CONTROLLER_REGISTRATION_INVALID', 'controller registration file is unsafe');
+        }
+        return { raw: fs.readFileSync(file, 'utf8'), stat };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode
+        && left.size === right.size && left.mtimeMs === right.mtimeMs;
+}
+function secretHash(secret) {
+    return crypto.createHash('sha256')
+        .update('agent-infra/codex-controller-lease/v1\0')
+        .update(secret)
+        .digest('hex');
+}
+function safeEqual(left, right) {
+    if (!HEX_256.test(left) || !HEX_256.test(right))
+        return false;
+    return crypto.timingSafeEqual(Buffer.from(left, 'hex'), Buffer.from(right, 'hex'));
+}
+function defaultProbe(manifest, identity) {
+    const command = commandForEngine(manifest.engine, 'docker', [
+        'exec', manifest.containerIdentity.id, 'cat', `/proc/${identity.pid}/stat`
+    ]);
+    const result = runProbe(command.cmd, command.args, { timeout: 2_000 });
+    if (result.status !== 0) {
+        const stderr = typeof result.stderr === 'string' ? result.stderr : result.stderr?.toString('utf8') ?? '';
+        return /no such (?:file|container)|not found|does not exist/iu.test(stderr) ? 'dead' : 'unknown';
+    }
+    const stdout = typeof result.stdout === 'string' ? result.stdout : result.stdout?.toString('utf8') ?? '';
+    const stat = parseLinuxProcessStat(stdout);
+    if (!stat)
+        return 'unknown';
+    if (stat.state === 'Z' || stat.startTime !== identity.startTime)
+        return 'dead';
+    return 'alive';
+}
+function assertRegistrationBinding(registration, manifest, buildIdentity) {
+    if (registration.taskId !== manifest.taskId
+        || registration.controlGeneration !== manifest.generation
+        || registration.containerId !== manifest.containerIdentity.id) {
+        fail('CODEX_SANDBOX_CONTROLLER_REGISTRATION_INVALID', 'controller registration binding is invalid');
+    }
+    if (registration.buildIdentity.protocolVersion !== buildIdentity.protocolVersion) {
+        fail('CODEX_LIFECYCLE_PROTOCOL_MISMATCH', 'Codex lifecycle protocol version does not match');
+    }
+}
+function atomicWrite(file, value) {
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600, flag: 'wx' });
+        fs.chmodSync(temporary, 0o600);
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+export function readCodexControllerRegistration(manifestPath) {
+    const existing = readRaw(registrationPath(manifestPath));
+    if (!existing)
+        fail('CODEX_SANDBOX_CONTROLLER_REGISTRATION_MISSING', 'controller registration is missing');
+    return parseRegistration(existing.raw);
+}
+export function openCodexControllerRegistration(params, options = {}) {
+    if (params.manifest.mode !== 'task-bound' || !params.manifest.taskId) {
+        fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot register a Codex controller');
+    }
+    if (!validProcess(params.controllerProcess)) {
+        fail('CODEX_SANDBOX_CONTROLLER_PROCESS_INACTIVE', 'requested controller process is invalid');
+    }
+    const file = registrationPath(params.manifestPath);
+    const now = (options.now ?? Date.now)();
+    const initial = readRaw(file);
+    if (initial) {
+        const existing = parseRegistration(initial.raw);
+        assertRegistrationBinding(existing, params.manifest, params.buildIdentity);
+        if (existing.expiresAt > now) {
+            const oldState = (options.probeProcess ?? ((identity) => defaultProbe(params.manifest, identity)))(existing.controllerProcess);
+            if (oldState === 'alive')
+                fail('CODEX_SANDBOX_CONTROLLER_BUSY', 'an active controller registration already exists');
+            if (oldState === 'unknown')
+                fail('CODEX_SANDBOX_CONTROLLER_PROCESS_UNKNOWN', 'existing controller process state is unknown');
+        }
+    }
+    const requestedState = (options.probeProcess ?? ((identity) => defaultProbe(params.manifest, identity)))(params.controllerProcess);
+    if (requestedState === 'dead')
+        fail('CODEX_SANDBOX_CONTROLLER_PROCESS_INACTIVE', 'requested controller process is not alive');
+    if (requestedState === 'unknown')
+        fail('CODEX_SANDBOX_CONTROLLER_PROCESS_UNKNOWN', 'requested controller process state is unknown');
+    const randomHex = options.randomHex ?? (() => crypto.randomBytes(32).toString('hex'));
+    const leaseId = randomHex();
+    const leaseSecret = randomHex();
+    const controllerInstanceDigest = randomHex();
+    if (![leaseId, leaseSecret, controllerInstanceDigest].every((value) => HEX_256.test(value))) {
+        fail('CODEX_SANDBOX_CONTROLLER_CREDENTIAL_INVALID', 'generated controller credential is invalid');
+    }
+    const registration = Object.freeze({
+        version: 1,
+        taskId: params.manifest.taskId,
+        controlGeneration: params.manifest.generation,
+        containerId: params.manifest.containerIdentity.id,
+        leaseId,
+        leaseSecretHash: secretHash(leaseSecret),
+        controllerInstanceDigest,
+        controllerProcess: params.controllerProcess,
+        buildIdentity: params.buildIdentity,
+        issuedAt: now,
+        expiresAt: now + CONTROLLER_TTL_MS
+    });
+    options.beforeCommit?.();
+    const current = readRaw(file);
+    if ((!initial && current)
+        || (initial && (!current || current.raw !== initial.raw || !sameFile(current.stat, initial.stat)))) {
+        fail('CODEX_SANDBOX_CONTROLLER_OWNERSHIP_LOST', 'controller registration changed before commit');
+    }
+    atomicWrite(file, registration);
+    return Object.freeze({
+        version: 1,
+        status: 'opened',
+        changed: true,
+        lease: Object.freeze({
+            version: 1,
+            leaseId,
+            leaseSecret,
+            taskId: registration.taskId,
+            controlGeneration: registration.controlGeneration,
+            controllerInstanceDigest,
+            controllerProcess: registration.controllerProcess,
+            buildIdentity: registration.buildIdentity,
+            issuedAt: registration.issuedAt,
+            expiresAt: registration.expiresAt
+        }),
+        error: null
+    });
+}
+export function closeCodexControllerRegistration(params) {
+    if (params.manifest.mode !== 'task-bound' || !params.manifest.taskId) {
+        fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot close a Codex controller registration');
+    }
+    const file = registrationPath(params.manifestPath);
+    const existingRaw = readRaw(file);
+    if (!existingRaw)
+        return Object.freeze({ version: 1, status: 'closed', changed: false, lease: null, error: null });
+    const existing = parseRegistration(existingRaw.raw);
+    if (existing.taskId !== params.manifest.taskId
+        || existing.controlGeneration !== params.manifest.generation
+        || existing.containerId !== params.manifest.containerIdentity.id
+        || params.proof.version !== 1
+        || existing.leaseId !== params.proof.leaseId
+        || !safeEqual(existing.leaseSecretHash, secretHash(params.proof.leaseSecret))
+        || JSON.stringify(existing.controllerProcess) !== JSON.stringify(params.proof.controllerProcess)) {
+        fail('CODEX_SANDBOX_CONTROLLER_PROOF_INVALID', 'controller close proof is invalid');
+    }
+    const current = readRaw(file);
+    if (!current || current.raw !== existingRaw.raw || !sameFile(current.stat, existingRaw.stat)) {
+        fail('CODEX_SANDBOX_CONTROLLER_OWNERSHIP_LOST', 'controller registration changed before close');
+    }
+    fs.unlinkSync(file);
+    return Object.freeze({ version: 1, status: 'closed', changed: true, lease: null, error: null });
+}
+export function resolveCodexControllerBinding(params) {
+    if (params.manifest.mode !== 'task-bound' || !params.manifest.taskId) {
+        fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot resolve a Codex controller registration');
+    }
+    const registration = readCodexControllerRegistration(params.manifestPath);
+    assertRegistrationBinding(registration, params.manifest, params.buildIdentity);
+    if (registration.expiresAt <= (params.now ?? Date.now())) {
+        fail('CODEX_SANDBOX_CONTROLLER_LEASE_EXPIRED', 'controller lease is expired');
+    }
+    if (params.proof.version !== 1
+        || registration.leaseId !== params.proof.leaseId
+        || !safeEqual(registration.leaseSecretHash, secretHash(params.proof.leaseSecret))
+        || JSON.stringify(registration.controllerProcess) !== JSON.stringify(params.proof.controllerProcess)) {
+        fail('CODEX_SANDBOX_CONTROLLER_PROOF_INVALID', 'controller proof is invalid');
+    }
+    const state = (params.probeProcess ?? ((identity) => defaultProbe(params.manifest, identity)))(registration.controllerProcess);
+    if (state === 'dead')
+        fail('CODEX_SANDBOX_CONTROLLER_PROCESS_INACTIVE', 'controller process is not alive');
+    if (state === 'unknown')
+        fail('CODEX_SANDBOX_CONTROLLER_PROCESS_UNKNOWN', 'controller process state is unknown');
+    return Object.freeze({
+        instanceDigest: registration.controllerInstanceDigest,
+        controlGeneration: registration.controlGeneration
+    });
+}
+//# sourceMappingURL=controller-registration.js.map

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

@@ -4,8 +4,12 @@ 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 { applyTaskFinalization } from '../../task/finalization.js';
+import { verifyTaskEvent } from '../../task/verification.js';
 import { bindSandboxControlTask } from './protocol.js';
 import { atomicWriteJson, executionPath, terminateSandboxControlExecution } from './state.js';
+import { computeLifecycleBuildIdentity } from '../../agent-clients/adapters/codex-lifecycle/build-identity.js';
+import { closeCodexControllerRegistration, CodexControllerRegistrationError, openCodexControllerRegistration, resolveCodexControllerBinding } from './controller-registration.js';
 function safeEnv(env) {
     return Object.fromEntries(Object.entries(env).filter(([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')));
 }
@@ -108,7 +112,61 @@ function waitForGate(nonce, timeoutMs = 2_000) {
         });
     });
 }
-function executeRequest(manifest, request) {
+function controllerFailure(error) {
+    const code = error instanceof CodexControllerRegistrationError
+        ? error.code
+        : /^([A-Z][A-Z0-9_]+)/u.exec(error instanceof Error ? error.message : String(error))?.[1]
+            ?? 'CODEX_SANDBOX_CONTROLLER_FAILED';
+    const message = error instanceof CodexControllerRegistrationError
+        ? error.message
+        : `${code}: controller operation failed; inspect the sandbox controller and rebuild the sandbox if needed`;
+    const payload = {
+        version: 1,
+        status: 'failed',
+        changed: false,
+        lease: null,
+        error: { code, message, retryable: false }
+    };
+    return { exitCode: 1, stdout: `${JSON.stringify(payload)}\n`, stderr: '' };
+}
+function orchestrationFailure(code, message) {
+    return {
+        exitCode: 1,
+        stdout: `${JSON.stringify({
+            status: 'failed', changed: false, taskId: null, run: null, next: null,
+            error: { code, message }
+        })}\n`,
+        stderr: ''
+    };
+}
+function finalizationResult(result) {
+    const payload = {
+        version: 1,
+        status: result.status,
+        changed: result.changed,
+        accepted: true,
+        result,
+        error: result.error
+    };
+    return {
+        exitCode: result.status === 'completed' ? 0 : result.status === 'blocked' ? 2 : 1,
+        stdout: `${JSON.stringify(payload)}\n`,
+        stderr: ''
+    };
+}
+function isCodexPrepare(args) {
+    if (args[1] !== 'prepare')
+        return false;
+    const values = [];
+    for (let index = 2; index < args.length; index += 1) {
+        if (args[index] === '--client')
+            values.push(args[index + 1] ?? '');
+        else if (args[index]?.startsWith('--client='))
+            values.push(args[index].slice('--client='.length));
+    }
+    return values.length === 1 && values[0] === 'codex';
+}
+export function executeRequest(manifest, manifestPath, request, options = {}) {
     if (request.family === 'task-create') {
         const result = createTask(request.candidate, { repoRoot: manifest.repoRoot });
         return {
@@ -117,13 +175,90 @@ function executeRequest(manifest, request) {
             stderr: ''
         };
     }
+    if (request.family === 'codex-controller') {
+        try {
+            if (request.command === 'verify') {
+                const binding = (options.resolveControllerBinding ?? resolveCodexControllerBinding)({
+                    manifest,
+                    manifestPath,
+                    proof: request.controllerProof,
+                    buildIdentity: (options.buildIdentity ?? computeLifecycleBuildIdentity)(manifest.repoRoot)
+                });
+                return {
+                    exitCode: 0,
+                    stdout: `${JSON.stringify({
+                        version: 1,
+                        status: 'verified',
+                        changed: false,
+                        lease: null,
+                        binding: {
+                            taskId: manifest.taskId,
+                            controlGeneration: binding.controlGeneration,
+                            controllerInstanceDigest: binding.instanceDigest
+                        },
+                        error: null
+                    })}\n`,
+                    stderr: ''
+                };
+            }
+            const result = request.command === 'open'
+                ? openCodexControllerRegistration({
+                    manifest,
+                    manifestPath,
+                    controllerProcess: request.controllerProcess,
+                    buildIdentity: (options.buildIdentity ?? computeLifecycleBuildIdentity)(manifest.repoRoot)
+                })
+                : closeCodexControllerRegistration({
+                    manifest,
+                    manifestPath,
+                    proof: request.controllerProof
+                });
+            return { exitCode: 0, stdout: `${JSON.stringify(result)}\n`, stderr: '' };
+        }
+        catch (error) {
+            return controllerFailure(error);
+        }
+    }
+    if (request.family === 'task-finalization') {
+        return finalizationResult(applyTaskFinalization({ taskRef: manifest.taskId, intent: 'complete', agent: request.agent }, { repoRoot: manifest.repoRoot, preflight: (input, options) => verifyTaskEvent({ ...input, event: 'complete-task.hard-preflight' }, options) }));
+    }
     const boundArgs = bindSandboxControlTask(request, manifest.taskId);
-    if (request.family === 'task-orchestration')
+    let controllerBinding = null;
+    if (request.family === 'task-orchestration') {
+        if (isCodexPrepare(request.args)) {
+            if (!request.controllerProof) {
+                return orchestrationFailure('CODEX_SANDBOX_CONTROLLER_PROOF_REQUIRED', 'Codex prepare requires a current controller lease proof');
+            }
+            try {
+                controllerBinding = (options.resolveControllerBinding ?? resolveCodexControllerBinding)({
+                    manifest,
+                    manifestPath,
+                    proof: request.controllerProof,
+                    buildIdentity: (options.buildIdentity ?? computeLifecycleBuildIdentity)(manifest.repoRoot)
+                });
+            }
+            catch (error) {
+                const code = error instanceof CodexControllerRegistrationError
+                    ? error.code
+                    : 'CODEX_SANDBOX_CONTROLLER_PROOF_INVALID';
+                return orchestrationFailure(code, `${code}: Codex controller proof was rejected`);
+            }
+        }
+        else if (request.controllerProof !== null) {
+            return orchestrationFailure('CODEX_SANDBOX_CONTROLLER_PROOF_INVALID', 'Controller proof is only accepted for canonical Codex prepare');
+        }
         boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
-    const result = spawnSync(process.execPath, nodeEntryArgs(process.argv[1], [request.family, ...boundArgs]), {
+    }
+    const result = (options.spawnDomain ?? spawnSync)(process.execPath, nodeEntryArgs(process.argv[1], [request.family, ...boundArgs]), {
         cwd: manifest.repoRoot,
         encoding: 'utf8',
-        env: { ...safeEnv(process.env), AGENT_INFRA_RUNTIME_DIR: manifest.runtimeDir }
+        env: {
+            ...safeEnv(process.env),
+            AGENT_INFRA_RUNTIME_DIR: manifest.runtimeDir,
+            ...(controllerBinding
+                ? { AGENT_INFRA_CONTROL_CONTROLLER_BINDING: JSON.stringify(controllerBinding) }
+                : {})
+        }
     });
     return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
 }
@@ -138,7 +273,7 @@ export async function runSandboxControlExecutor(requestPath, nonce) {
     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);
+    const result = executeRequest(manifest, manifestPath, request);
     process.stdout.write(result.stdout);
     process.stderr.write(result.stderr);
     process.exitCode = result.exitCode;