@fitlab-ai/agent-infra 0.9.14 → 0.9.15

package/dist/lib/task/verification.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 // Verification runs in-process; configuration, review parsing and platform
 // checks are provided by typed domain modules without a stdout protocol.
 import { verifyInProcess } from './verification-engine.js';
-import { parseArtifactName } from './artifact-lifecycle.js';
+import { parseArtifactName } from './artifact-name.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { allowsManualOverride } from './guard-override.js';
 const gate = (skill, expectedState, artifactFamily) => ({

package/dist/lib/task/workflow-command.js

@@ -0,0 +1,17 @@
+export const TASK_WORKFLOW_COMMANDS = Object.freeze({
+    'artifact-inspect': ['task-artifact', 'inspect'],
+    'artifact-init': ['task-artifact', 'init'],
+    'artifact-repair': ['task-artifact', 'repair'],
+    'artifact-finalize-local': ['task-artifact', 'finalize-local'],
+    'review-finalize-summary': ['task-review', 'finalize-summary'],
+    event: ['task-event', null],
+    'ledger-finding-response': ['task-ledger', 'finding-respond'],
+    'ledger-finding-review': ['task-ledger', 'finding-review'],
+    'ledger-finding-upsert': ['task-ledger', 'finding-upsert'],
+    'decision-next-id': ['task-ledger', 'decision-next-id'],
+    'decision-upsert': ['task-ledger', 'decision-upsert'],
+    'invalidation-reconcile': ['task-invalidation', 'reconcile'],
+    'warning-add': ['task-warning', 'add']
+});
+export const TASK_WORKFLOW_OPERATIONS = Object.freeze(Object.keys(TASK_WORKFLOW_COMMANDS));
+//# sourceMappingURL=workflow-command.js.map

package/dist/lib/task/workflow-warning-intents.js

@@ -19,19 +19,6 @@ function nextWarningId(rows) {
     }
     return `WW-${max + 1}`;
 }
-function validateRows(rows) {
-    const ids = new Set();
-    for (const row of rows) {
-        if (!/^WW-[1-9]\d*$/.test(row.id))
-            return { code: 'WARNING_ID_INVALID', message: `warning id '${row.id}' is invalid` };
-        if (ids.has(row.id))
-            return { code: 'WARNING_DUPLICATE_ID', message: `duplicate warning id '${row.id}'` };
-        ids.add(row.id);
-        if (!WORKFLOW_WARNING_SEVERITIES.has(row.severity) || !WORKFLOW_WARNING_STATUSES.has(row.status))
-            return { code: 'WARNING_DOCUMENT_INVALID', message: `warning '${row.id}' has invalid severity or status` };
-    }
-    return null;
-}
 function sectionMutation(content) {
     if (/^##\s+(工作流告警|Workflow Warnings)\s*$/m.test(content))
         return [];
@@ -69,9 +56,6 @@ function applyWorkflowWarningIntent(intent, options = {}) {
         const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : 'WARNING_DOCUMENT_INVALID';
         return failed(intent, code, error instanceof Error ? error.message : String(error), resolved.taskId);
     }
-    const invalid = validateRows(rows);
-    if (invalid)
-        return failed(intent, invalid.code, invalid.message, resolved.taskId);
     if (intent.kind === 'list') {
         if (intent.status && !WORKFLOW_WARNING_STATUSES.has(intent.status))
             return failed(intent, 'WARNING_PAYLOAD_INVALID', 'warning status is invalid', resolved.taskId);

package/dist/lib/task/workflow-warnings.js

@@ -3,14 +3,40 @@ const WORKFLOW_WARNING_HEADINGS = ['工作流告警', 'Workflow Warnings'];
 const WORKFLOW_WARNING_STATUSES = new Set(['open', 'resolved', 'ignored']);
 const WORKFLOW_WARNING_SEVERITIES = new Set(['IMPORTANT', 'ACTION_REQUIRED']);
 const WORKFLOW_WARNING_COLUMNS = ['id', 'time', 'step', 'severity', 'code', 'status', 'target', 'message', 'action', 'resolved_at', 'resolution'];
-/** Parses workflow warning rows and fails closed on malformed table structure. */
+const WARNING_TIME_PATTERN = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[+-]\d{2}:\d{2})?$/;
+/** Parses warning structure and lifecycle fields using one contract for all readers. */
 function parseWorkflowWarnings(content) {
     const table = parseTable(content, { sectionAliases: WORKFLOW_WARNING_HEADINGS, columns: WORKFLOW_WARNING_COLUMNS });
-    return table?.rows.map(({ values }) => ({
+    const warnings = table?.rows.map(({ values }) => ({
         id: values.id, time: values.time, step: values.step, severity: values.severity,
         code: values.code, status: values.status, target: values.target, message: values.message,
         action: values.action, resolvedAt: values.resolved_at, resolution: values.resolution
     })) ?? [];
+    const errors = [];
+    const invalid = (message, code = 'WARNING_DOCUMENT_INVALID') => errors.push({ code, message });
+    for (const warning of warnings) {
+        const { id, time, severity, status, action, resolvedAt, resolution } = warning;
+        if (!/^WW-[1-9]\d*$/.test(id))
+            invalid(`${id || '(empty id)'}: invalid id`, 'WARNING_ID_INVALID');
+        if (!WARNING_TIME_PATTERN.test(time))
+            invalid(`${id}: invalid time '${time}'`);
+        for (const field of ['step', 'code', 'target', 'message']) {
+            if (!warning[field].trim())
+                invalid(`${id}: ${field} is required`);
+        }
+        if (!WORKFLOW_WARNING_SEVERITIES.has(severity))
+            invalid(`${id}: illegal severity '${severity}'`);
+        if (!WORKFLOW_WARNING_STATUSES.has(status))
+            invalid(`${id}: illegal status '${status}'`);
+        if (status === 'open' && !action.trim())
+            invalid(`${id}: open warning requires action`);
+        if ((status === 'resolved' || status === 'ignored') && (!resolvedAt.trim() || !resolution.trim())) {
+            invalid(`${id}: ${status} warning requires resolved_at and resolution`);
+        }
+    }
+    if (errors.length)
+        throw Object.assign(new Error(errors.map((error) => error.message).join('; ')), { code: errors[0].code });
+    return warnings;
 }
 function getOpenWorkflowWarnings(content) {
     return parseWorkflowWarnings(content).filter((warning) => warning.status === 'open');

package/dist/lib/update.js

@@ -69,6 +69,8 @@ async function cmdSync() {
     ok('Updated .agents/skills/update-agent-infra/');
     renderFile(path.join(templateDir, '.agents', 'scripts', 'lib', 'agent-infra-package.js'), path.join('.agents', 'scripts', 'lib', 'agent-infra-package.js'), replacements);
     ok('Updated .agents/scripts/lib/agent-infra-package.js');
+    renderFile(path.join(templateDir, '.agents', 'scripts', 'package.json'), path.join('.agents', 'scripts', 'package.json'), replacements);
+    ok('Updated .agents/scripts/package.json');
     const added = {
         managed: workflowPlan.projectAssets.registry.managed.filter((entry) => !currentRegistry.managed.includes(entry)),
         merged: workflowPlan.projectAssets.registry.merged.filter((entry) => !currentRegistry.merged.includes(entry))

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.9.14",
-  "sourceInputHash": "a3cf306ad6576904e6ef7d962e51245c6684540bd41358beaebf8209c00f3cfc",
-  "internalExecutableBuildHash": "14773c26aea5022af695f2e3ca4a39bed3c87c1eab04347aeded028745d8ded1"
+  "packageVersion": "0.9.15",
+  "sourceInputHash": "d6521519c8d772a6d81c177d8c6e6795c080b04d9f8afcec19bca45c486a70df",
+  "internalExecutableBuildHash": "f0ab80c423acc4def5130e075a209a64349296985701506e7d9e73f8151bcb2a"
 }

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

@@ -12,6 +12,14 @@ import type { LifecycleBuildIdentity } from './build-identity.ts';
 import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.ts';
 
 type CapabilityStatus = 'armed' | 'attested' | 'consumed' | 'expired';
+type RecoveryState = 'unreserved' | 'reserved' | 'consumed';
+type RecoveryPhase = 'orchestration.prepare' | 'artifact.finalize-local' | 'task-event.completed';
+type RecoveryPhaseState = 'issued' | 'consumed';
+type CodexCapabilityRecoveryPhase = Readonly<{
+  phase: RecoveryPhase;
+  requestId: string;
+  state: RecoveryPhaseState;
+}>;
 type CodexControllerBinding = Readonly<{
   instanceDigest: string;
   controlGeneration: string;
@@ -47,11 +55,15 @@ type CodexCapabilityProvenanceDetail = Readonly<{
   }>;
 }>;
 type CodexCapabilityRecord = Readonly<{
-  schemaVersion: 1;
+  schemaVersion: 2;
   revision: number;
-  tokenDigest: string;
+  capabilityRefDigest: string;
   taskId: string;
   status: CapabilityStatus;
+  recoveryOperationId: string | null;
+  recoveryState: RecoveryState;
+  reservedAt: number | null;
+  recoveryPhases: readonly CodexCapabilityRecoveryPhase[];
   buildIdentity: LifecycleBuildIdentity;
   controller: CodexControllerBinding | null;
   sessionId: string | null;
@@ -67,7 +79,7 @@ type CodexCapabilityRecord = Readonly<{
 type CodexCapabilityStoreOptions = Readonly<{
   root?: string;
   now?: () => number;
-  token?: () => string;
+  reference?: () => string;
   ttlMs?: number;
   tombstoneMs?: number;
   maxRecords?: number;
@@ -212,6 +224,22 @@ function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boo
   return Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
 }
 
+function isRecoveryPhase(value: unknown): value is RecoveryPhase {
+  return value === 'orchestration.prepare'
+    || value === 'artifact.finalize-local'
+    || value === 'task-event.completed';
+}
+
+function isRecoveryPhaseRecord(value: unknown): value is CodexCapabilityRecoveryPhase {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const phase = value as Record<string, unknown>;
+  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: unknown): value is CodexControllerBinding {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
   const record = value as Record<string, unknown>;
@@ -302,20 +330,28 @@ function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
   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: string): string {
-    return path.join(root, `${digest(token)}.json`);
+  function fileFor(capabilityRef: string): string {
+    return path.join(root, `${digest(capabilityRef)}.json`);
   }
 
   function read(file: string): CodexCapabilityRecord {
     const value = JSON.parse(fs.readFileSync(file, 'utf8')) as CodexCapabilityRecord;
-    if (value.schemaVersion !== 1 || !Number.isSafeInteger(value.revision) || value.revision < 1) {
+    const keys = Object.keys(value as unknown as Record<string, unknown>).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;
@@ -426,18 +462,22 @@ function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
     taskId: string;
     buildIdentity: LifecycleBuildIdentity;
     controller?: CodexControllerBinding;
-  }>): CodexCapabilityRecord & Readonly<{ token: string; path: string; marker: string }> {
+  }>): CodexCapabilityRecord & Readonly<{ capabilityRef: string; path: string; marker: string }> {
     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: CodexCapabilityRecord = 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,
@@ -450,28 +490,32 @@ function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
       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) as CodexCapabilityRecord & Readonly<{ capabilityRef: string; path: string; marker: string }>;
   }
 
-  function loadActive(token: string): Readonly<{ file: string; record: CodexCapabilityRecord }> {
-    const file = fileFor(token);
+  function loadActive(
+    capabilityRef: string,
+    options: Readonly<{ allowExpiredReserved?: boolean }> = {}
+  ): Readonly<{ file: string; record: CodexCapabilityRecord }> {
+    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: Readonly<{
-    token: string;
+  function attestByReference(input: Readonly<{
+    capabilityRef: string;
     sessionId: string;
     turnId: string;
     toolUseId: string;
@@ -479,7 +523,7 @@ function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
     buildIdentity: LifecycleBuildIdentity;
     controller?: CodexControllerBinding;
   }>): CodexCapabilityRecord {
-    const { file, record } = loadActive(input.token);
+    const { file, record } = loadActive(input.capabilityRef);
     if (record.status !== 'armed') {
       throw capabilityError(
         record.status === 'consumed' ? 'CODEX_CAPABILITY_REPLAY' : 'CODEX_CAPABILITY_STATE_INVALID',
@@ -514,11 +558,14 @@ function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
     hookDefinitionHash: string;
     buildIdentity: LifecycleBuildIdentity;
     controller?: CodexControllerBinding;
-  }>): CodexCapabilityRecord {
+  }>, options: Readonly<{ allowExpiredReserved?: boolean }> = {}): CodexCapabilityRecord {
     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'
@@ -537,49 +584,192 @@ function createCodexCapabilityStore(options: CodexCapabilityStoreOptions = {}) {
     return record;
   }
 
-  function validate(token: string, expected: Readonly<{
+  function validateReference(capabilityRef: string, expected: Readonly<{
     taskId: string;
     hookDefinitionHash: string;
     buildIdentity: LifecycleBuildIdentity;
     controller?: CodexControllerBinding;
   }>): CodexCapabilityRecord {
     sweep();
-    const { record } = loadActive(token);
+    const { record } = loadActive(capabilityRef);
     return validateRecord(record, expected);
   }
 
-  function consume(token: string, expected: Readonly<{
+  function consumeReference(capabilityRef: string, operationId: string, expected: Readonly<{
     taskId: string;
     hookDefinitionHash: string;
     buildIdentity: LifecycleBuildIdentity;
     controller?: CodexControllerBinding;
-  }>): CodexCapabilityRecord {
+  }>, options: Readonly<{ allowExpiredReserved?: boolean }> = {}): CodexCapabilityRecord {
     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: CodexCapabilityRecord = Object.freeze({
       ...record,
       revision: record.revision + 1,
       status: 'consumed',
+      recoveryState: 'consumed',
       consumedAt: now()
     });
     write(file, next, record.revision);
     return next;
   }
 
-  function inspect(token: string): CodexCapabilityRecord {
-    return loadActive(token).record;
+  function reserveRecoveryPhase(
+    capabilityRef: string,
+    operationId: string,
+    phase: RecoveryPhase,
+    requestId: string,
+    expected: Readonly<{
+      taskId: string;
+      hookDefinitionHash: string;
+      buildIdentity: LifecycleBuildIdentity;
+      controller?: CodexControllerBinding;
+    }>
+  ): CodexCapabilityRecord {
+    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: CodexCapabilityRecord = Object.freeze({
+      ...record,
+      revision: record.revision + 1,
+      recoveryPhases: Object.freeze([
+        ...record.recoveryPhases,
+        Object.freeze({ phase, requestId, state: 'issued' as const })
+      ])
+    });
+    write(file, next, record.revision);
+    return next;
+  }
+
+  function consumeRecoveryPhase(
+    capabilityRef: string,
+    operationId: string,
+    phase: RecoveryPhase,
+    requestId: string,
+    expected: Readonly<{
+      taskId: string;
+      hookDefinitionHash: string;
+      buildIdentity: LifecycleBuildIdentity;
+      controller?: CodexControllerBinding;
+    }>,
+    options: Readonly<{ allowExpiredReserved?: boolean }> = {}
+  ): CodexCapabilityRecord {
+    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: CodexCapabilityRecord = Object.freeze({
+      ...record,
+      revision: record.revision + 1,
+      recoveryPhases: Object.freeze(record.recoveryPhases.map((entry) =>
+        entry.phase === phase ? Object.freeze({ ...entry, state: 'consumed' as const }) : entry
+      ))
+    });
+    write(file, next, record.revision);
+    return next;
+  }
+
+  function reserveReference(
+    capabilityRef: string,
+    operationId: string,
+    expected: Readonly<{
+      taskId: string;
+      hookDefinitionHash: string;
+      buildIdentity: LifecycleBuildIdentity;
+      controller?: CodexControllerBinding;
+    }>
+  ): CodexCapabilityRecord {
+    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: CodexCapabilityRecord = Object.freeze({
+      ...record,
+      revision: record.revision + 1,
+      recoveryOperationId: operationId,
+      recoveryState: 'reserved',
+      reservedAt: now()
+    });
+    write(file, next, record.revision);
+    return next;
+  }
+
+  function inspectReference(capabilityRef: string): CodexCapabilityRecord {
+    return loadActive(capabilityRef).record;
+  }
+
+  function findByRecoveryOperation(operationId: string): readonly CodexCapabilityRecord[] {
+    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 type {
   CapabilityStatus,
+  RecoveryState,
   CodexCapabilityProjection,
   CodexCapabilityProvenanceDetail,
   CodexCapabilityRecord,
+  CodexCapabilityRecoveryPhase,
   CodexCapabilityStoreOptions,
   CodexControllerBinding
 };

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

@@ -351,9 +351,10 @@ function prepareCodexSandboxController(
     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 = [

package/lib/fs/durable-write.ts

@@ -0,0 +1,29 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export function fsyncDirectory(directory: string): void {
+  const descriptor = fs.openSync(directory, 'r');
+  try { fs.fsyncSync(descriptor); } finally { fs.closeSync(descriptor); }
+}
+
+/** The caller owns directory validation and the meaning of an existing target. */
+export function writeDurableFile(
+  target: string,
+  content: string,
+  options: Readonly<{ mode: number; replace: boolean }>
+): void {
+  const directory = path.dirname(target);
+  const temporary = path.join(directory, `.${path.basename(target)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    const descriptor = fs.openSync(temporary, 'wx', options.mode);
+    try {
+      fs.writeFileSync(descriptor, content, { encoding: 'utf8' });
+      fs.fchmodSync(descriptor, options.mode);
+      fs.fsyncSync(descriptor);
+    } finally { fs.closeSync(descriptor); }
+    if (options.replace) fs.renameSync(temporary, target);
+    else fs.linkSync(temporary, target);
+    fsyncDirectory(directory);
+  } finally { fs.rmSync(temporary, { force: true }); }
+}