@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/README.md

@@ -93,6 +93,16 @@ Every command above works the same way in Claude Code, Codex, Antigravity CLI, a
 - **AI-assisted updates**: template changes can be merged while preserving project-specific customization
 - **Auditable process-data archive**: preserve local tasks and GitHub evidence in append-only, verifiable snapshots
 
+### Sandbox control boundary
+
+Task-bound sandboxes use a host-only control service for lifecycle and workflow writes. On Linux its fixed endpoint is `/run/user/<uid>/agent-infra/host-control.sock`; on macOS it is `/Users/<login>/Library/Application Support/agent-infra/run/host-control.sock`, resolved from the account identity rather than `HOME` or `TMPDIR`. The service directory is private (`0700`) and the socket is private (`0600`). If the endpoint or sandbox identity is unavailable, task-control commands fail closed.
+
+The shell installer creates and starts the user-scoped service through systemd user units on Linux or launchd user agents on macOS. After a manual npm install, run `agent-infra-internal host-control install`, then enable the generated user service; `agent-infra-internal host-control status` reports endpoint health. No root or setuid service is required.
+
+On macOS, the installer retries service registration during reload. If registration or startup still fails, it exits with an error and a recovery command.
+
+The task directory exposed inside a task-bound sandbox is a writable projection. Artifact commands accept only typed workflow operations and canonical artifact basenames. The host opens candidates with `O_NOFOLLOW`, reads and hashes them through one file descriptor, checks observable metadata changes, and atomically lands validated bytes into the authoritative task directory. Changes to the projection's protected topology fail closed and never turn the projection into task state.
+
 ## Quick Start
 
 ### 1. Install agent-infra

package/README.zh-CN.md

@@ -92,6 +92,16 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 - **AI 辅助升级**：模板升级时可合并变更，同时尽量保留项目侧定制
 - **可审计的过程数据归档**：把本地任务与 GitHub 证据保存为只追加、可校验的快照
 
+### 沙箱控制边界
+
+任务沙箱的生命周期和工作流写操作由宿主专用控制服务执行。Linux 固定端点为 `/run/user/<uid>/agent-infra/host-control.sock`；macOS 固定端点为 `/Users/<login>/Library/Application Support/agent-infra/run/host-control.sock`，路径根据账户身份解析，不读取 `HOME` 或 `TMPDIR`。服务目录权限为 `0700`，socket 权限为 `0600`。端点或沙箱身份不可用时，task-control 命令会失败关闭。
+
+Shell 安装脚本会在 Linux 通过 systemd 用户单元、在 macOS 通过 launchd 用户代理创建并启动该服务。手动 npm 安装后，可运行 `agent-infra-internal host-control install` 创建服务配置，再启用对应的用户服务；`agent-infra-internal host-control status` 可检查端点健康状态。整个服务不需要 root 或 setuid。
+
+macOS 重载期间，安装脚本会重试服务注册；若最终仍无法注册或启动，则以错误退出并提供恢复命令。
+
+任务沙箱内的 task 目录是可写投影。产物命令只接受类型化 workflow 操作和规范的产物 basename。宿主使用 `O_NOFOLLOW` 打开候选文件，通过同一个文件描述符读取并计算摘要，检查可观察的元数据变化，再把已校验字节原子落入权威 task 目录。投影的受保护拓扑发生变化时会失败关闭，投影修改不会变成任务状态。
+
 ## 快速开始
 
 ### 1. 安装 agent-infra

package/bin/internal-cli.sh

@@ -0,0 +1,45 @@
+#!/bin/sh
+set -eu
+
+script_path=$0
+case "$script_path" in
+  [A-Za-z]:*)
+    drive=${script_path%"${script_path#?}"}
+    drive=$(printf '%s' "$drive" | tr '[:upper:]' '[:lower:]')
+    script_path="/${drive}${script_path#?:}"
+    script_path=$(printf '%s' "$script_path" | tr '\\' '/')
+    ;;
+  /*) ;;
+  *) script_path=$PWD/$script_path ;;
+esac
+while [ -L "$script_path" ]; do
+  link_target=$(readlink "$script_path")
+  case "$link_target" in
+    /*) script_path=$link_target ;;
+    *) script_path=$(dirname -- "$script_path")/$link_target ;;
+  esac
+done
+script_dir=$(CDPATH= cd -- "$(dirname -- "$script_path")" && pwd -P)
+if [ -f "$script_dir/internal-cli.js" ]; then
+  internal_cli="$script_dir/internal-cli.js"
+else
+  internal_cli="$script_dir/../dist/bin/internal-cli.js"
+fi
+
+command=${1-}
+task_control_command=false
+case "$command" in
+  task-lifecycle|task-orchestration|task-finalization) task_control_command=true ;;
+esac
+
+status_mount_present=false
+if [ -d /run/agent-infra/control-status ]; then status_mount_present=true; fi
+launch_config=${AGENT_INFRA_TASK_ID-}${AGENT_INFRA_CONTROL_TOKEN-}${AGENT_INFRA_CONTROL_GENERATION-}${AGENT_INFRA_CONTROL_DIR-}${AGENT_INFRA_CONTROL_STATUS_DIR-}${AGENT_INFRA_RUNTIME_DIR-}${AGENT_INFRA_EXECUTOR_MANIFEST-}
+if [ "$task_control_command" = true ] && [ "$status_mount_present" = true ] && [ -z "$launch_config" ] && [ -z "${AGENT_INFRA_TEST_HOST_CONTROL_ENDPOINT-}" ]; then
+  printf '%s\n' '{"status":"failed","changed":false,"error":{"code":"SANDBOX_CONTROL_IDENTITY_MISSING","message":"sandbox control identity is present but its launch configuration is missing"}}'
+  exit 1
+fi
+# The outer launcher owns the Node startup boundary. A task-bound process must
+# not pass preload, import, or loader injection into the control router.
+unset NODE_OPTIONS NODE_PATH
+exec node "$internal_cli" "$@"

package/dist/bin/internal-cli.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { classifySandboxControlEnvironment } from '../lib/sandbox/control/client.js';
-import { formatTaskViewDiagnostic, guardTaskOperation, TaskViewOperationError } from '../lib/internal/task-operation-registry.js';
+import { formatTaskViewDiagnostic, guardTaskOperation, resolveSandboxControlTransport, TaskViewOperationError } from '../lib/internal/task-operation-registry.js';
 import { INTERNAL_HANDLER_ROUTE_SELECTORS } from '../lib/internal/cli-route-inventory.js';
+import { hostControlRequestForCommand, requestHostControl, HostControlClientError, HOST_CONTROL_TEST_ENVIRONMENT_KEYS } from '../lib/host-control/client.js';
+import { resolveHostControlEndpoint, readHostControlWorkerToken } from '../lib/host-control/path.js';
 const [major = 0, minor = 0] = process.versions.node.split('.').map((part) => parseInt(part, 10));
 if (major < 22 || (major === 22 && minor < 9)) {
     process.stderr.write(`agent-infra-internal requires Node.js >= 22.9.0 (current: ${process.version})\n`);
@@ -10,6 +11,16 @@ if (major < 22 || (major === 22 && minor < 9)) {
 const command = process.argv[2] || '';
 const internalRouteRegistered = Object.hasOwn(INTERNAL_HANDLER_ROUTE_SELECTORS, command);
 const taskControlCommand = command === 'task-lifecycle' || command === 'task-orchestration' || command === 'task-finalization';
+const taskWorkflowCommand = command === 'task-artifact'
+    || command === 'task-review'
+    || command === 'task-event'
+    || command === 'task-ledger'
+    || command === 'task-invalidation'
+    || command === 'task-warning';
+const manualValidationWorkflowCommand = command === 'manual-validation';
+const localTaskControlHelp = taskControlCommand
+    && (process.argv[3] === '--help' || process.argv[3] === '-h')
+    && !process.env.AGENT_INFRA_TEST_HOST_CONTROL_ENDPOINT;
 let taskViewGuardFailed = false;
 try {
     const guard = guardTaskOperation('internal', command, process.argv.slice(3));
@@ -27,44 +38,86 @@ catch (error) {
         throw error;
     }
 }
-function taskControlTransportFailure(message) {
+function taskControlTransportFailure(message, code = 'TASK_CONTROL_TRANSPORT_INVALID', changed = false) {
     process.stdout.write(`${JSON.stringify({
-        status: 'failed', changed: false,
-        error: { code: 'TASK_CONTROL_TRANSPORT_INVALID', message }
+        status: 'failed', changed,
+        error: { code, message }
     })}\n`);
     process.exit(1);
 }
-if (!taskViewGuardFailed && taskControlCommand) {
-    const environment = classifySandboxControlEnvironment();
-    if (environment.kind === 'invalid') {
-        taskControlTransportFailure(environment.message ?? 'sandbox client control configuration is invalid');
+async function runHostControlCommand(commandName, args) {
+    let response;
+    try {
+        const testEndpoint = process.env.AGENT_INFRA_TEST_HOST_CONTROL_ENDPOINT;
+        const forwardedEnvironment = testEndpoint
+            ? Object.fromEntries(HOST_CONTROL_TEST_ENVIRONMENT_KEYS.flatMap((key) => process.env[key] === undefined ? [] : [[key, process.env[key]]]))
+            : {};
+        response = await requestHostControl({
+            request: hostControlRequestForCommand(commandName, args, process.cwd(), forwardedEnvironment),
+            endpoint: process.env.AGENT_INFRA_TEST_HOST_CONTROL_ENDPOINT ?? resolveHostControlEndpoint()
+        });
     }
-    if (environment.kind === 'controlled') {
-        const { sandboxControl } = await import('../lib/internal/sandbox-control.js');
-        await sandboxControl(['client', command, ...process.argv.slice(3)]);
+    catch (error) {
+        if (error instanceof HostControlClientError) {
+            taskControlTransportFailure(error.message, error.changed === false
+                ? 'SANDBOX_CONTROL_HOST_AUTHORITY_UNAVAILABLE' : error.code, error.changed);
+        }
+        throw error;
     }
-    else {
-        switch (command) {
-            case 'task-orchestration': {
-                const { taskOrchestration } = await import('../lib/internal/task-orchestration.js');
-                await taskOrchestration(process.argv.slice(3));
-                break;
-            }
-            case 'task-lifecycle': {
-                const { taskLifecycle } = await import('../lib/internal/task-lifecycle.js');
-                await taskLifecycle(process.argv.slice(3));
-                break;
-            }
-            case 'task-finalization': {
-                const { taskFinalization } = await import('../lib/internal/task-finalization.js');
-                await taskFinalization(process.argv.slice(3));
-                break;
-            }
+    process.stdout.write(response.stdout);
+    process.stderr.write(response.stderr);
+    process.exitCode = response.exitCode;
+}
+const hostWorkerRequested = process.env.AGENT_INFRA_HOST_CONTROL_WORKER === '1';
+const hostWorker = hostWorkerRequested && (() => {
+    try {
+        const endpoint = process.env.AGENT_INFRA_TEST_HOST_CONTROL_ENDPOINT ?? resolveHostControlEndpoint();
+        return process.env.AGENT_INFRA_HOST_CONTROL_WORKER_TOKEN === readHostControlWorkerToken(endpoint);
+    }
+    catch {
+        return false;
+    }
+})();
+if (hostWorkerRequested && !hostWorker && (taskControlCommand || taskWorkflowCommand || manualValidationWorkflowCommand)) {
+    taskControlTransportFailure('host-control worker authorization is invalid', 'SANDBOX_CONTROL_HOST_AUTHORITY_UNAVAILABLE');
+}
+let controlRouted = false;
+if (!taskViewGuardFailed && (taskControlCommand || taskWorkflowCommand || manualValidationWorkflowCommand) && !hostWorker && !localTaskControlHelp) {
+    const transport = resolveSandboxControlTransport(process.env);
+    switch (transport.kind) {
+        case 'fail-closed': {
+            const reason = transport.reasonCode ?? 'TASK_CONTROL_TRANSPORT_INVALID';
+            taskControlTransportFailure(reason, reason.startsWith('SANDBOX_CONTROL_IDENTITY_') ? reason : undefined);
+            break;
+        }
+        case 'direct-host':
+            await runHostControlCommand(command, process.argv.slice(3));
+            break;
+        case 'broker-client': {
+            const { sandboxControl } = await import('../lib/internal/sandbox-control.js');
+            await sandboxControl(['client', ...(taskControlCommand ? [command] : ['task-workflow', command]), ...process.argv.slice(3)]);
+            break;
         }
     }
+    controlRouted = true;
 }
-else if (!taskViewGuardFailed && internalRouteRegistered)
+if (!controlRouted && !taskViewGuardFailed && internalRouteRegistered)
     switch (command) {
+        case 'task-orchestration': {
+            const { taskOrchestration } = await import('../lib/internal/task-orchestration.js');
+            await taskOrchestration(process.argv.slice(3));
+            break;
+        }
+        case 'task-lifecycle': {
+            const { taskLifecycle } = await import('../lib/internal/task-lifecycle.js');
+            await taskLifecycle(process.argv.slice(3));
+            break;
+        }
+        case 'task-finalization': {
+            const { taskFinalization } = await import('../lib/internal/task-finalization.js');
+            await taskFinalization(process.argv.slice(3));
+            break;
+        }
         case 'task-create': {
             const { taskCreate } = await import('../lib/internal/task-create.js');
             await taskCreate(process.argv.slice(3));
@@ -75,6 +128,11 @@ else if (!taskViewGuardFailed && internalRouteRegistered)
             await sandboxControl(process.argv.slice(3));
             break;
         }
+        case 'host-control': {
+            const { hostControl } = await import('../lib/internal/host-control.js');
+            await hostControl(process.argv.slice(3));
+            break;
+        }
         case 'agent-client': {
             const { agentClient } = await import('../lib/internal/agent-client.js');
             agentClient(process.argv.slice(3));
@@ -240,6 +298,11 @@ else if (!taskViewGuardFailed && internalRouteRegistered)
             taskValidate(process.argv.slice(3));
             break;
         }
+        case 'manual-validation': {
+            const { manualValidation } = await import('../lib/internal/manual-validation.js');
+            await manualValidation(process.argv.slice(3));
+            break;
+        }
         default:
             process.stdout.write(`${JSON.stringify({
                 status: 'failed',

package/dist/lib/agent-clients/adapters/codex-lifecycle/capability-store.js

@@ -89,6 +89,21 @@ function provenanceDetail(record, expected) {
 function exactKeys(value, keys) {
     return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
 }
+function isRecoveryPhase(value) {
+    return value === 'orchestration.prepare'
+        || value === 'artifact.finalize-local'
+        || value === 'task-event.completed';
+}
+function isRecoveryPhaseRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const phase = value;
+    return exactKeys(phase, ['phase', 'requestId', 'state'])
+        && isRecoveryPhase(phase.phase)
+        && typeof phase.requestId === 'string'
+        && /^[a-f0-9-]{16,64}$/u.test(phase.requestId)
+        && (phase.state === 'issued' || phase.state === 'consumed');
+}
 function isCodexControllerBinding(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
@@ -176,18 +191,26 @@ function createCodexCapabilityStore(options = {}) {
     const root = options.root
         ?? resolveAgentRuntimeStoreRoot({ store: 'capabilities' });
     const now = options.now ?? Date.now;
-    const createToken = options.token ?? (() => crypto.randomBytes(32).toString('base64url'));
+    const createReference = options.reference ?? (() => crypto.randomBytes(32).toString('base64url'));
     const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
     const tombstoneMs = options.tombstoneMs ?? DEFAULT_TOMBSTONE_MS;
     const maxRecords = options.maxRecords ?? DEFAULT_MAX_RECORDS;
     fs.mkdirSync(root, { recursive: true, mode: 0o700 });
     fs.chmodSync(root, 0o700);
-    function fileFor(token) {
-        return path.join(root, `${digest(token)}.json`);
+    function fileFor(capabilityRef) {
+        return path.join(root, `${digest(capabilityRef)}.json`);
     }
     function read(file) {
         const value = JSON.parse(fs.readFileSync(file, 'utf8'));
-        if (value.schemaVersion !== 1 || !Number.isSafeInteger(value.revision) || value.revision < 1) {
+        const keys = Object.keys(value).sort().join(',');
+        if (keys !== 'armedAt,attestedAt,buildIdentity,capabilityRefDigest,consumedAt,controller,expiresAt,hookDefinitionHash,recoveryOperationId,recoveryPhases,recoveryState,reservedAt,revision,schemaVersion,sessionId,status,taskId,toolUseId,turnId'
+            || value.schemaVersion !== 2 || !Number.isSafeInteger(value.revision) || value.revision < 1
+            || typeof value.capabilityRefDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(value.capabilityRefDigest)
+            || !['unreserved', 'reserved', 'consumed'].includes(value.recoveryState)
+            || (value.recoveryOperationId !== null && typeof value.recoveryOperationId !== 'string')
+            || (value.reservedAt !== null && !Number.isSafeInteger(value.reservedAt))
+            || !Array.isArray(value.recoveryPhases)
+            || !value.recoveryPhases.every((phase) => isRecoveryPhaseRecord(phase))) {
             throw capabilityError('CODEX_CAPABILITY_STATE_INVALID', 'capability record schema is invalid');
         }
         return value;
@@ -294,17 +317,21 @@ function createCodexCapabilityStore(options = {}) {
     }
     function arm(input) {
         sweep();
-        const token = createToken();
-        const file = fileFor(token);
+        const capabilityRef = createReference();
+        const file = fileFor(capabilityRef);
         if (fs.existsSync(file))
             throw capabilityError('CODEX_CAPABILITY_TOKEN_COLLISION', 'capability token already exists');
         const timestamp = now();
         const record = Object.freeze({
-            schemaVersion: 1,
+            schemaVersion: 2,
             revision: 1,
-            tokenDigest: digest(token),
+            capabilityRefDigest: digest(capabilityRef),
             taskId: input.taskId,
             status: 'armed',
+            recoveryOperationId: null,
+            recoveryState: 'unreserved',
+            reservedAt: null,
+            recoveryPhases: Object.freeze([]),
             buildIdentity: input.buildIdentity,
             controller: input.controller ?? null,
             sessionId: null,
@@ -317,26 +344,27 @@ function createCodexCapabilityStore(options = {}) {
             consumedAt: null
         });
         write(file, record, 0);
-        return Object.freeze({
+        const result = {
             ...record,
-            token,
+            capabilityRef,
             path: file,
-            marker: `agent-infra-codex-capability:${token}`
-        });
+            marker: `agent-infra-codex-capability:${capabilityRef}`
+        };
+        return Object.freeze(result);
     }
-    function loadActive(token) {
-        const file = fileFor(token);
+    function loadActive(capabilityRef, options = {}) {
+        const file = fileFor(capabilityRef);
         if (!fs.existsSync(file)) {
             throw capabilityError('CODEX_CAPABILITY_MISSING', 'capability token was not found');
         }
         const record = expire(read(file), file, now());
-        if (record.status === 'expired') {
+        if (record.status === 'expired' && !options.allowExpiredReserved) {
             throw capabilityError('CODEX_CAPABILITY_EXPIRED', 'capability token expired');
         }
         return { file, record };
     }
-    function attest(input) {
-        const { file, record } = loadActive(input.token);
+    function attestByReference(input) {
+        const { file, record } = loadActive(input.capabilityRef);
         if (record.status !== 'armed') {
             throw capabilityError(record.status === 'consumed' ? 'CODEX_CAPABILITY_REPLAY' : 'CODEX_CAPABILITY_STATE_INVALID', `capability is ${record.status}, expected armed`);
         }
@@ -362,11 +390,14 @@ function createCodexCapabilityStore(options = {}) {
         write(file, next, record.revision);
         return next;
     }
-    function validateRecord(record, expected) {
+    function validateRecord(record, expected, options = {}) {
         if (record.status === 'consumed') {
             throw capabilityError('CODEX_CAPABILITY_REPLAY', 'capability token was already consumed');
         }
-        if (record.status !== 'attested') {
+        const expiredReserved = options.allowExpiredReserved
+            && record.status === 'expired'
+            && record.recoveryState === 'reserved';
+        if (record.status !== 'attested' && !expiredReserved) {
             throw capabilityError('CODEX_CAPABILITY_NOT_ATTESTED', 'capability token has no current-session hook attestation');
         }
         const identity = record.buildIdentity && typeof record.buildIdentity === 'object'
@@ -380,28 +411,135 @@ function createCodexCapabilityStore(options = {}) {
         }
         return record;
     }
-    function validate(token, expected) {
+    function validateReference(capabilityRef, expected) {
         sweep();
-        const { record } = loadActive(token);
+        const { record } = loadActive(capabilityRef);
         return validateRecord(record, expected);
     }
-    function consume(token, expected) {
+    function consumeReference(capabilityRef, operationId, expected, options = {}) {
         sweep();
-        const { file, record } = loadActive(token);
-        validateRecord(record, expected);
+        if (!operationId || /[\r\n]/u.test(operationId)) {
+            throw capabilityError('CODEX_CAPABILITY_RECOVERY_INVALID', 'recovery operation id is invalid');
+        }
+        const { file, record } = loadActive(capabilityRef, options);
+        if (record.status === 'consumed' && record.recoveryState === 'consumed' && record.recoveryOperationId === operationId) {
+            return record;
+        }
+        validateRecord(record, expected, options);
+        if (record.recoveryState === 'consumed') {
+            if (record.recoveryOperationId === operationId)
+                return record;
+            throw capabilityError('CODEX_CAPABILITY_REPLAY', 'capability recovery operation was already consumed');
+        }
+        if (record.recoveryState !== 'reserved' || record.recoveryOperationId !== operationId) {
+            throw capabilityError('CODEX_CAPABILITY_RECOVERY_INVALID', 'capability must be reserved by this operation before consumption');
+        }
         const next = Object.freeze({
             ...record,
             revision: record.revision + 1,
             status: 'consumed',
+            recoveryState: 'consumed',
             consumedAt: now()
         });
         write(file, next, record.revision);
         return next;
     }
-    function inspect(token) {
-        return loadActive(token).record;
+    function reserveRecoveryPhase(capabilityRef, operationId, phase, requestId, expected) {
+        if (!operationId || /[\r\n]/u.test(operationId) || !isRecoveryPhase(phase)
+            || !/^[a-f0-9-]{16,64}$/u.test(requestId)) {
+            throw capabilityError('CODEX_CAPABILITY_RECOVERY_INVALID', 'recovery phase identity is invalid');
+        }
+        sweep();
+        const { file, record } = loadActive(capabilityRef);
+        validateRecord(record, expected);
+        if (record.recoveryState !== 'reserved' || record.recoveryOperationId !== operationId) {
+            throw capabilityError('CODEX_CAPABILITY_RECOVERY_INVALID', 'capability must be reserved by this operation before phase reservation');
+        }
+        if (record.recoveryPhases.some((entry) => entry.phase === phase)) {
+            throw capabilityError('CODEX_CAPABILITY_PHASE_REPLAY', 'recovery phase was already reserved');
+        }
+        const next = Object.freeze({
+            ...record,
+            revision: record.revision + 1,
+            recoveryPhases: Object.freeze([
+                ...record.recoveryPhases,
+                Object.freeze({ phase, requestId, state: 'issued' })
+            ])
+        });
+        write(file, next, record.revision);
+        return next;
+    }
+    function consumeRecoveryPhase(capabilityRef, operationId, phase, requestId, expected, options = {}) {
+        if (!operationId || /[\r\n]/u.test(operationId) || !isRecoveryPhase(phase)
+            || !/^[a-f0-9-]{16,64}$/u.test(requestId)) {
+            throw capabilityError('CODEX_CAPABILITY_RECOVERY_INVALID', 'recovery phase identity is invalid');
+        }
+        sweep();
+        const { file, record } = loadActive(capabilityRef, options);
+        validateRecord(record, expected, options);
+        if (record.recoveryState !== 'reserved' && record.recoveryState !== 'consumed') {
+            throw capabilityError('CODEX_CAPABILITY_RECOVERY_INVALID', 'capability has no reserved recovery operation');
+        }
+        if (record.recoveryOperationId !== operationId) {
+            throw capabilityError('CODEX_CAPABILITY_REPLAY', 'capability recovery operation does not match');
+        }
+        const current = record.recoveryPhases.find((entry) => entry.phase === phase);
+        if (!current || current.requestId !== requestId) {
+            throw capabilityError('CODEX_CAPABILITY_PHASE_REPLAY', 'recovery phase identity does not match');
+        }
+        if (current.state === 'consumed')
+            return record;
+        const next = Object.freeze({
+            ...record,
+            revision: record.revision + 1,
+            recoveryPhases: Object.freeze(record.recoveryPhases.map((entry) => entry.phase === phase ? Object.freeze({ ...entry, state: 'consumed' }) : entry))
+        });
+        write(file, next, record.revision);
+        return next;
+    }
+    function reserveReference(capabilityRef, operationId, expected) {
+        if (!operationId || /[\r\n]/u.test(operationId)) {
+            throw capabilityError('CODEX_CAPABILITY_RECOVERY_INVALID', 'recovery operation id is invalid');
+        }
+        sweep();
+        const { file, record } = loadActive(capabilityRef);
+        validateRecord(record, expected);
+        if (record.recoveryState === 'reserved') {
+            if (record.recoveryOperationId === operationId)
+                return record;
+            throw capabilityError('CODEX_CAPABILITY_BUSY', 'capability is reserved by another recovery operation');
+        }
+        if (record.recoveryState === 'consumed') {
+            if (record.recoveryOperationId === operationId)
+                return record;
+            throw capabilityError('CODEX_CAPABILITY_REPLAY', 'capability recovery operation was already consumed');
+        }
+        const next = Object.freeze({
+            ...record,
+            revision: record.revision + 1,
+            recoveryOperationId: operationId,
+            recoveryState: 'reserved',
+            reservedAt: now()
+        });
+        write(file, next, record.revision);
+        return next;
+    }
+    function inspectReference(capabilityRef) {
+        return loadActive(capabilityRef).record;
+    }
+    function findByRecoveryOperation(operationId) {
+        if (!operationId || /[\r\n]/u.test(operationId)) {
+            throw capabilityError('CODEX_CAPABILITY_RECOVERY_INVALID', 'recovery operation id is invalid');
+        }
+        return Object.freeze(files()
+            .map((file) => read(file))
+            .filter((record) => record.recoveryOperationId === operationId));
     }
-    return Object.freeze({ arm, attest, consume, inspect, validate, sweep });
+    return Object.freeze({
+        arm, attestByReference, reserveReference, reserveRecoveryPhase, consumeRecoveryPhase,
+        consumeReference, inspectReference,
+        findByRecoveryOperation, validateReference, sweep
+    });
 }
 export { createCodexCapabilityStore };
 export { isCodexCapabilityProvenanceDetail };

package/dist/lib/agent-clients/adapters/codex-lifecycle/sandbox-controller.js

@@ -22,13 +22,14 @@ function copyRegular(source, destination, mode) {
 function controlFromEnvironment() {
     const token = process.env.AGENT_INFRA_CONTROL_TOKEN;
     const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
+    const rootId = process.env.AGENT_INFRA_CONTROL_ROOT_ID;
     const channelDir = process.env.AGENT_INFRA_CONTROL_DIR;
     const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
     const runtimeDir = process.env.AGENT_INFRA_RUNTIME_DIR;
-    if (!token || !generation || !channelDir || !statusDir || !runtimeDir) {
+    if (!token || !generation || !rootId || !channelDir || !statusDir || !runtimeDir) {
         throw new Error('CODEX_SANDBOX_CONTROLLER_CONTROL_MISSING');
     }
-    return { token, generation, channelDir, statusDir, runtimeDir };
+    return { token, generation, rootId, channelDir, statusDir, runtimeDir };
 }
 function verifyRuntime(runtimeDir) {
     let stat;
@@ -188,6 +189,9 @@ function isolatedEnvironment(home, shimDir, contextPath, taskId, control, provid
         AGENT_INFRA_TASK_ID: taskId,
         AGENT_INFRA_CONTROL_TOKEN: control.token,
         AGENT_INFRA_CONTROL_GENERATION: control.generation,
+        ...(control.rootId || sourceEnvironment.AGENT_INFRA_CONTROL_ROOT_ID
+            ? { AGENT_INFRA_CONTROL_ROOT_ID: control.rootId ?? sourceEnvironment.AGENT_INFRA_CONTROL_ROOT_ID }
+            : {}),
         AGENT_INFRA_CONTROL_DIR: control.channelDir,
         AGENT_INFRA_CONTROL_STATUS_DIR: control.statusDir,
         AGENT_INFRA_RUNTIME_DIR: control.runtimeDir,
@@ -274,9 +278,10 @@ function prepareCodexSandboxController(input, options = {}) {
         const shimDir = path.join(home, 'bin');
         fs.mkdirSync(shimDir, { mode: 0o700 });
         const internalCli = path.resolve(process.argv[1] ?? path.join(repoRoot, 'bin', 'internal-cli.ts'));
+        const launcherPrefix = ['#!/bin/sh', 'set -eu', 'unset NODE_OPTIONS NODE_PATH'].join('\n') + '\n';
         const source = internalCli.endsWith('.ts')
-            ? `#!/bin/sh\nexec ${shellQuote(process.execPath)} --experimental-strip-types ${shellQuote(internalCli)} "$@"\n`
-            : `#!/bin/sh\nexec ${shellQuote(process.execPath)} ${shellQuote(internalCli)} "$@"\n`;
+            ? `${launcherPrefix}exec ${shellQuote(process.execPath)} --experimental-strip-types ${shellQuote(internalCli)} "$@"\n`
+            : `${launcherPrefix}exec ${shellQuote(process.execPath)} ${shellQuote(internalCli)} "$@"\n`;
         fs.writeFileSync(path.join(shimDir, 'agent-infra-internal'), source, { mode: 0o700 });
         const policy = [
             input.executorModel ? `--executor-model ${input.executorModel}` : '',

package/dist/lib/agent-clients/adapters/codex-lifecycle/store.js

@@ -6,9 +6,19 @@ import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.js'
 const LOCK_RETRY_MS = 10;
 const LOCK_TIMEOUT_MS = 1_000;
 const LOCK_STALE_MS = 30_000;
+const RECOVERY_CONSUMER_RE = /^lifecycle-recovery:([^:\r\n]+):([^:\r\n]+)$/u;
 function digest(value) {
     return crypto.createHash('sha256').update(value).digest('hex');
 }
+function isRecoveryConsumer(value) {
+    return RECOVERY_CONSUMER_RE.test(value);
+}
+function recoveryConsumer(taskId, receiptId) {
+    if (!/^[^:\r\n]+$/u.test(taskId) || !/^[^:\r\n]+$/u.test(receiptId)) {
+        throw new Error('Codex lifecycle recovery claim identity is invalid');
+    }
+    return `lifecycle-recovery:${taskId}:${receiptId}`;
+}
 function readRecord(file) {
     const value = JSON.parse(fs.readFileSync(file, 'utf8'));
     if (value.schemaVersion !== 1
@@ -202,11 +212,13 @@ function createCodexLifecycleStore(options) {
     }
     function read(childThreadId) {
         const matches = findByChild(childThreadId);
-        if (matches.length !== 1)
+        if (matches.length === 0)
             throw new Error(`Codex lifecycle child '${childThreadId}' was not found uniquely`);
+        if (matches.length > 1)
+            throw new Error(`Codex lifecycle child '${childThreadId}' is ambiguous`);
         return readRecord(matches[0]);
     }
-    function consume(childThreadId, consumer, expectedHookDefinitionHash) {
+    function consumeInternal(childThreadId, consumer, expectedHookDefinitionHash) {
         if (!consumer.trim())
             throw new Error('Codex lifecycle consumer is required');
         return withWriteLock(() => {
@@ -240,6 +252,32 @@ function createCodexLifecycleStore(options) {
             return next;
         });
     }
+    function consume(childThreadId, consumer, expectedHookDefinitionHash) {
+        if (!consumer.trim())
+            throw new Error('Codex lifecycle consumer is required');
+        if (consumer.startsWith('lifecycle-recovery:')) {
+            throw new Error('Codex lifecycle recovery claims require claimRecovery');
+        }
+        return consumeInternal(childThreadId, consumer, expectedHookDefinitionHash);
+    }
+    function claimRecovery(childThreadId, taskId, receiptId, expectedHookDefinitionHash) {
+        return consumeInternal(childThreadId, recoveryConsumer(taskId, receiptId), expectedHookDefinitionHash);
+    }
+    function releaseRecovery(childThreadId, consumer) {
+        if (!/^lifecycle-recovery:[^:\r\n]+:[^:\r\n]+$/.test(consumer))
+            return false;
+        return withWriteLock(() => {
+            const matches = findByChild(childThreadId);
+            if (matches.length !== 1)
+                return false;
+            const file = matches[0];
+            const current = readRecord(file);
+            if (current.state.status !== 'stop-ready' || current.consumer !== consumer || !current.consumedAt)
+                return false;
+            fs.unlinkSync(file);
+            return true;
+        });
+    }
     function expireBefore(cutoff) {
         return withWriteLock(() => {
             let changed = 0;
@@ -247,6 +285,8 @@ function createCodexLifecycleStore(options) {
                 const current = readRecord(file);
                 if (current.updatedAt >= cutoff)
                     continue;
+                if (current.consumer && isRecoveryConsumer(current.consumer))
+                    continue;
                 if (current.consumer || ['invalid', 'expired', 'stop-ready'].includes(current.state.status)) {
                     fs.unlinkSync(file);
                     changed += 1;
@@ -266,7 +306,7 @@ function createCodexLifecycleStore(options) {
             return changed;
         });
     }
-    return Object.freeze({ root, apply, applyToSpawn, consume, expireBefore, findByParent, read });
+    return Object.freeze({ root, apply, applyToSpawn, consume, claimRecovery, releaseRecovery, expireBefore, findByParent, read });
 }
 export { createCodexLifecycleStore, hasActiveCodexLifecycleEvidence };
 //# sourceMappingURL=store.js.map