@fitlab-ai/agent-infra 0.9.8 → 0.9.9

package/dist/lib/task/short-id.js

@@ -343,6 +343,64 @@ function loadShortIdByTaskId(repoRoot) {
     }
     return map;
 }
+function inspectShortIdRegistry(repoRoot) {
+    const registryPath = path.join(repoRoot, '.agents', 'workspace', 'active', REGISTRY_NAME);
+    if (!fs.existsSync(registryPath)) {
+        return {
+            status: 'missing',
+            error: {
+                code: 'SHORT_ID_REGISTRY_NOT_FOUND',
+                message: 'canonical short-id registry is missing'
+            }
+        };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(registryPath, 'utf8');
+    }
+    catch {
+        return {
+            status: 'invalid',
+            error: {
+                code: 'SHORT_ID_REGISTRY_READ_FAILED',
+                message: 'canonical short-id registry is unreadable'
+            }
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return {
+            status: 'invalid',
+            error: {
+                code: 'SHORT_ID_REGISTRY_INVALID_JSON',
+                message: 'canonical short-id registry contains invalid JSON'
+            }
+        };
+    }
+    try {
+        const registry = validateRegistry(parsed, registryPath, configuredShortIdLength(repoRoot));
+        const shortIds = new Map();
+        for (const [key, taskId] of Object.entries(registry.ids))
+            shortIds.set(taskId, key);
+        return { status: 'valid', shortIds };
+    }
+    catch (error) {
+        return {
+            status: 'invalid',
+            error: {
+                code: typeof error.code === 'string'
+                    ? error.code
+                    : 'SHORT_ID_REGISTRY_INVALID_SCHEMA',
+                message: error.code === 'SHORT_ID_REGISTRY_DUPLICATE_TASK'
+                    ? 'canonical short-id registry contains duplicate task entries'
+                    : 'canonical short-id registry has invalid schema'
+            }
+        };
+    }
+}
 /**
  * Resolve a branch to its active-task short id (`NN`), or `null` when no
  * active task is bound to that branch.
@@ -371,5 +429,5 @@ function lookupShortIdByBranch(branch, repoRoot, _opts) {
     }
     return matches[0];
 }
-export { normalizeShortIdInput, isRemovedHashShortIdInput, resolveShortIdReadOnly, lookupShortIdByBranch, loadShortIdByTaskId, configuredShortIdLength, mutateShortIdRegistry, executeShortIdCommand };
+export { normalizeShortIdInput, isRemovedHashShortIdInput, resolveShortIdReadOnly, lookupShortIdByBranch, loadShortIdByTaskId, inspectShortIdRegistry, configuredShortIdLength, mutateShortIdRegistry, executeShortIdCommand };
 //# sourceMappingURL=short-id.js.map

package/dist/lib/task/task-execution-lock.js

@@ -207,6 +207,8 @@ function withTaskExecutionLock(repoRoot, taskId, ownerName, callback, options =
     catch (error) {
         if (error instanceof TaskExecutionLockError)
             throw error;
+        if (error instanceof Error && error.name === 'OrchestrationStateError')
+            throw error;
         throw new TaskExecutionLockError('ORCHESTRATION_LOCK_FAILED', 'lifecycle task lock operation failed', { operation: ownsFixed ? 'callback' : 'acquire', errno: errno(error), key });
     }
     finally {
@@ -228,5 +230,8 @@ function withTaskExecutionLock(repoRoot, taskId, ownerName, callback, options =
         }
     }
 }
-export { TaskExecutionLockError, lockKey, mapLinkError, withTaskExecutionLock };
+function withRepositoryMutationLock(repoRoot, callback, options = {}) {
+    return withTaskExecutionLock(repoRoot, '__repository_mutation__', 'repository-mutation', callback, options);
+}
+export { TaskExecutionLockError, lockKey, mapLinkError, withRepositoryMutationLock, withTaskExecutionLock };
 //# sourceMappingURL=task-execution-lock.js.map

package/dist/lib/task/verification-engine.js

@@ -16,6 +16,7 @@ import { parseLedger, summarizeLedgerStage, validateLedgerRows } from "./ledger.
 import { equalCounts, parseReviewSummary } from "./review-artifacts.js";
 import { loadVerificationConfig } from "./verification-config.js";
 import { snapshotReview } from "../git/review-snapshot.js";
+import { OrchestrationStateError, readRun } from "./orchestration.js";
 const TASK_ENUMS = {
     type: ["feature", "bugfix", "refactor", "docs", "chore"],
     workflow: ["feature-development", "bug-fix", "refactoring"],
@@ -104,6 +105,8 @@ function runCheck(type, context, shared) {
             return checkReviewFact(context);
         case "post-review-commit":
             return checkPostReviewCommit(context);
+        case "required-pr-delivery":
+            return checkRequiredPrDelivery(context);
         case "orchestration-state":
             return checkOrchestrationState(context);
         case "orchestration-evidence":
@@ -120,22 +123,6 @@ function runCheck(type, context, shared) {
         }
     }
 }
-function isFailClosedLegacyPause(run) {
-    if (run.schemaVersion !== 1
-        || run.status !== 'paused'
-        || run.pause?.recoverable !== false
-        || !exactText(run.pause?.message)
-        || !Array.isArray(run.receipts)) {
-        return false;
-    }
-    if (run.pause.code === 'ORCHESTRATION_HISTORICAL_EFFORT_UNVERIFIED') {
-        return run.receipts.length > 0 && run.pendingDelegation === null;
-    }
-    if (run.pause.code === 'ORCHESTRATION_DELEGATION_BUSY') {
-        return run.pendingDelegation != null && run.pendingDelegation.status !== 'sealed';
-    }
-    return false;
-}
 function checkOrchestrationState({ taskDir }) {
     const file = path.join(taskDir, 'orchestration.json');
     const stat = safeStat(file);
@@ -143,16 +130,14 @@ function checkOrchestrationState({ taskDir }) {
         return failResult('orchestration-state', 'orchestration.json is missing');
     let run;
     try {
-        run = JSON.parse(fs.readFileSync(file, 'utf8'));
+        run = readRun(taskDir);
     }
     catch (error) {
-        return failResult('orchestration-state', `Invalid orchestration.json: ${String(error)}`);
+        const message = error instanceof OrchestrationStateError ? error.message : String(error);
+        return failResult('orchestration-state', `Invalid orchestration.json: ${message}`);
     }
-    if (isFailClosedLegacyPause(run)) {
-        return passResult('orchestration-state', 'Legacy orchestration run is safely paused');
-    }
-    if (![2, 3].includes(run.schemaVersion) || !['paused', 'completed'].includes(run.status)) {
-        return failResult('orchestration-state', `Expected paused or completed run, received '${run.status}'`);
+    if (!run || !['paused', 'completed'].includes(run.status)) {
+        return failResult('orchestration-state', `Expected paused or completed run, received '${run?.status ?? 'missing'}'`);
     }
     if (run.status === 'paused' && (!run.pause?.code || !run.pause?.message)) {
         return failResult('orchestration-state', 'Paused run requires a stable pause code and message');
@@ -215,13 +200,11 @@ function checkOrchestrationEvidence({ taskDir }) {
         return failResult('orchestration-evidence', 'orchestration.json is missing');
     let run;
     try {
-        run = JSON.parse(fs.readFileSync(file, 'utf8'));
+        run = readRun(taskDir);
     }
     catch (error) {
-        return failResult('orchestration-evidence', `Invalid orchestration.json: ${String(error)}`);
-    }
-    if (isFailClosedLegacyPause(run)) {
-        return passResult('orchestration-evidence', 'Legacy orchestration evidence is preserved in a fail-closed pause');
+        const message = error instanceof OrchestrationStateError ? error.message : String(error);
+        return failResult('orchestration-evidence', `Invalid orchestration.json: ${message}`);
     }
     const policy = run.modelPolicy;
     if (!policy
@@ -239,30 +222,8 @@ function checkOrchestrationEvidence({ taskDir }) {
         return failResult('orchestration-evidence', 'Run model policy source or recovery history is invalid');
     }
     for (const recovery of run.recoveryHistory) {
-        const validModelRecovery = recovery.code === 'MODEL_POLICY_SUPPLEMENTED'
-            && recovery.previousSchemaVersion === 1
-            && recovery.receiptCount === 0
-            && recovery.pendingDelegation === false
-            && exactText(recovery.recoveredAt)
-            && recovery.policySource;
         const guards = recovery.guards;
-        const validCapabilityRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED'
-            && recovery.previousSchemaVersion === 2
-            && recovery.previousStatus === 'paused'
-            && recovery.previousPause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
-            && recovery.client === 'codex'
-            && recovery.resultingStatus === 'running'
-            && exactText(recovery.recoveredAt)
-            && guards?.stepCount === 0
-            && guards?.nextStage === null
-            && guards?.baselineEmpty === true
-            && guards?.receiptCount === 0
-            && guards?.pendingDelegation === false
-            && guards?.commitAuthorizationUnused === true
-            && guards?.completionEvidenceAbsent === true
-            && guards?.commitIntentAbsent === true;
-        const validClaudeCodeRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED_NO_MIGRATION'
-            && recovery.previousSchemaVersion === 3
+        const validClaudeCodeRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED'
             && recovery.previousStatus === 'paused'
             && recovery.previousPause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
             && recovery.client === 'claude-code'
@@ -274,9 +235,8 @@ function checkOrchestrationEvidence({ taskDir }) {
             && guards?.receiptCount === 0
             && guards?.pendingDelegation === false
             && guards?.commitAuthorizationUnused === true
-            && guards?.completionEvidenceAbsent === true
-            && guards?.commitIntentAbsent === true;
-        if (!validModelRecovery && !validCapabilityRecovery && !validClaudeCodeRecovery) {
+            && guards?.completionEvidenceAbsent === true;
+        if (!validClaudeCodeRecovery) {
             return failResult('orchestration-evidence', 'Run recovery history contains invalid provenance');
         }
     }
@@ -342,11 +302,34 @@ function checkOrchestrationEvidence({ taskDir }) {
                 return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated reasoning-effort fallback reason`);
             }
             if (receipt.client === 'codex') {
+                const activatedCodex = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
                 const host = receipt.hostEvidence;
-                if (host?.kind !== 'codex-lifecycle-v1'
-                    || !exactText(host.hookDefinitionHash)
-                    || !Number.isSafeInteger(host.startRevision)
-                    || host.startRevision < 1) {
+                const provenance = receipt.lifecycleProvenance;
+                if (!provenance
+                    || (activatedCodex && (host?.kind !== 'codex-lifecycle-v2'
+                        || host.protocolVersion !== provenance.protocolVersion
+                        || host.packageVersion !== provenance.packageVersion
+                        || host.internalExecutableBuildHash !== provenance.internalExecutableBuildHash
+                        || host.lifecycleContractHash !== provenance.lifecycleContractHash
+                        || host.hookDefinitionHash !== provenance.hookDefinitionHash
+                        || host.hookSource !== provenance.hookSource
+                        || host.hookSourcePathDigest !== provenance.hookSourcePathDigest
+                        || host.hookSourceHash !== provenance.hookSourceHash
+                        || host.capabilitySessionId !== provenance.capabilitySessionId
+                        || receipt.parentId !== provenance.capabilitySessionId
+                        || host.capabilityTurnId !== provenance.capabilityTurnId
+                        || host.controllerInstanceDigest !== provenance.controllerInstanceDigest
+                        || host.controlGeneration !== provenance.controlGeneration
+                        || host.spawnToolUseId === provenance.capabilityToolUseId
+                        || !exactText(host.spawnToolUseId)
+                        || !Number.isFinite(Date.parse(host.spawnObservedAt ?? ''))
+                        || !Number.isFinite(Date.parse(receipt.spawnDispatchedAt ?? ''))
+                        || !Number.isFinite(Date.parse(receipt.activationDeadlineAt ?? ''))
+                        || Date.parse(host.spawnObservedAt ?? '') < Date.parse(receipt.spawnDispatchedAt ?? '')
+                        || Date.parse(host.spawnObservedAt ?? '') > Date.parse(receipt.activationDeadlineAt ?? '')
+                        || !exactText(host.hookDefinitionHash)
+                        || !Number.isSafeInteger(host.startRevision)
+                        || host.startRevision < 1))) {
                     return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid Codex start evidence`);
                 }
                 if (['sealed', 'consumed'].includes(receipt.status) && (!Number.isSafeInteger(host.stopRevision)
@@ -438,6 +421,60 @@ function checkTaskMeta({ taskDir, config }) {
     const warningSuffix = warnings.length > 0 ? `; warnings: ${warnings.join("; ")}` : "";
     return passResult("task-meta", `Task metadata valid (${requiredFields.length} required fields checked${warningSuffix})`, warnings);
 }
+function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }) {
+    const task = loadTask(taskDir);
+    if (!task.ok)
+        return failResult('required-pr-delivery', task.message);
+    let projectConfig = {};
+    try {
+        const file = path.join(repositoryRoot, '.agents', '.airc.json');
+        if (safeStat(file)?.isFile())
+            projectConfig = JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch {
+        return failResult('required-pr-delivery', 'Project configuration is invalid');
+    }
+    const flow = projectConfig.prFlow;
+    const status = String(task.metadata.pr_status || 'pending');
+    const prNumber = parsePrNumber(task.metadata.pr_number);
+    if (flow === 'disabled')
+        return passResult('required-pr-delivery', 'Pull request delivery is disabled by project policy');
+    if (flow === 'required' && (status !== 'created' || prNumber === null)) {
+        return failResult('required-pr-delivery', 'Project policy requires a bound pull request before completion');
+    }
+    if (flow !== 'required' && status === 'pending') {
+        return failResult('required-pr-delivery', 'Pull request delivery is pending; create a PR or explicitly skip it');
+    }
+    if (status === 'created' && prNumber === null) {
+        return failResult('required-pr-delivery', 'Task claims a created pull request without a valid pr_number');
+    }
+    if (flow === 'required') {
+        if (mode === 'gate') {
+            return passResult('required-pr-delivery', 'Bound pull request shape is valid; merged-state inspection is reserved for hard preflight');
+        }
+        const inspected = inspectPlatformPullRequest(task.metadata.id, { cwd: repositoryRoot });
+        if (inspected.status === 'blocked') {
+            return blockedResult('required-pr-delivery', inspected.error?.message || 'Unable to inspect the required pull request', inspected.error?.code || 'PR_INSPECTION_BLOCKED');
+        }
+        const pullRequest = inspected.pullRequest;
+        const repository = inspected.platform.repository?.toLowerCase() || '';
+        const taskBranch = String(task.metadata.branch || '').trim();
+        if (inspected.status !== 'no-op' || !pullRequest || pullRequest.number !== prNumber) {
+            return failResult('required-pr-delivery', 'Bound pull request identity could not be verified');
+        }
+        if (!repository
+            || pullRequest.repository.toLowerCase() !== repository
+            || pullRequest.base.repository.toLowerCase() !== repository
+            || (taskBranch && pullRequest.head.ref !== taskBranch)) {
+            return failResult('required-pr-delivery', 'Bound pull request identity does not match the task');
+        }
+        if (pullRequest.state !== 'closed' || !pullRequest.mergedAt || !pullRequest.mergeCommitSha) {
+            return failResult('required-pr-delivery', 'Project policy requires the bound pull request to be merged');
+        }
+        return passResult('required-pr-delivery', `Pull request delivery policy satisfied (merged PR #${prNumber})`);
+    }
+    return passResult('required-pr-delivery', `Pull request delivery policy satisfied (${status})`);
+}
 function validateTaskBranch(metadata) {
     if (isBlank(metadata.branch)) {
         return null;
@@ -1337,7 +1374,14 @@ function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks: reque
         for (const [type, checkConfig] of Object.entries(verifyConfig.checks || {})) {
             if (checkConfig === null)
                 continue;
-            const result = runCheck(type, { skillName, taskDir: path.resolve(taskDir), artifactFile, config: checkConfig }, shared);
+            const result = runCheck(type, {
+                mode,
+                skillName,
+                taskDir: path.resolve(taskDir),
+                artifactFile,
+                repositoryRoot: repoRoot,
+                config: checkConfig
+            }, shared);
             checks.push(result);
             if (result.status === "blocked")
                 break;
@@ -1351,7 +1395,16 @@ function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks: reque
         return { skill: skillName, ...failResult(type, `Unknown check type '${type}' for skill '${skillName}'.`) };
     if (config === null)
         return { skill: skillName, ...passResult(type, `Check '${type}' is disabled for skill '${skillName}'.`) };
-    return { skill: skillName, ...runCheck(type, { skillName, taskDir: path.resolve(taskDir), artifactFile, config }, shared) };
+    return {
+        skill: skillName,
+        ...runCheck(type, {
+            skillName,
+            taskDir: path.resolve(taskDir),
+            artifactFile,
+            repositoryRoot: repoRoot,
+            config
+        }, shared)
+    };
 }
 export { verifyInProcess };
 //# sourceMappingURL=verification-engine.js.map

package/dist/lib/task/verification.js

@@ -21,7 +21,8 @@ const VERIFICATION_CATALOG = {
     'block-task.completed': gate('block-task', 'blocked'),
     'cancel-task.completed': gate('cancel-task', 'completed'),
     'commit.completed': gate('commit', 'active'),
-    'complete-task.preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['review-ledger', 'manual-validation', 'post-review-commit', 'platform-sync-preflight'] },
+    'complete-task.preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
+    'complete-task.hard-preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
     'complete-task.completed': gate('complete-task', 'completed'),
     'create-pr.completed': gate('create-pr', 'active'),
     'create-task.completed': gate('create-task', 'active'),

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

@@ -3,6 +3,7 @@ import { resolveTaskRef } from './resolve-ref.js';
 import { WORKFLOW_WARNING_COLUMNS, WORKFLOW_WARNING_HEADINGS, WORKFLOW_WARNING_SEVERITIES, WORKFLOW_WARNING_STATUSES, parseWorkflowWarnings } from './workflow-warnings.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
 import { allowsManualOverride } from './guard-override.js';
+import { retryHintForWarning } from './operation-outcome.js';
 function failed(intent, code, message, taskId = null, entityId = null) {
     return { status: 'failed', changed: false, intent: intent.kind, taskId, entityId, before: null, after: null, warnings: [], operations: [], error: { code, message } };
 }
@@ -129,5 +130,53 @@ function applyWorkflowWarningIntent(intent, options = {}) {
         entityId: after.id, before, after, warnings: [], operations: writeResult.operations, error: null
     };
 }
-export { applyWorkflowWarningIntent };
+function projectFinalizationWarning(taskRef, warning, options = {}) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok)
+        return { status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } };
+    if (resolved.state !== 'completed')
+        return { status: 'failed', changed: false, error: { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected completed` } };
+    let content;
+    let rows;
+    try {
+        content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+        rows = parseWorkflowWarnings(content);
+    }
+    catch (error) {
+        return { status: 'failed', changed: false, error: { code: 'WARNING_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) } };
+    }
+    const metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+    const existing = rows.find((row) => row.step === warning.step && row.code === warning.code && row.target === warning.target);
+    const after = existing
+        ? {
+            ...existing,
+            severity: warning.severity,
+            status: warning.status,
+            message: warning.message,
+            action: retryHintForWarning(warning),
+            resolvedAt: warning.resolvedAt || (warning.status === 'resolved' ? metadata.timestamp : ''),
+            resolution: warning.status === 'resolved' ? 'Resolved by a successful finalization retry' : ''
+        }
+        : {
+            id: nextWarningId(rows), time: metadata.timestamp, step: warning.step,
+            severity: warning.severity, code: warning.code, status: warning.status,
+            target: warning.target, message: warning.message, action: retryHintForWarning(warning),
+            resolvedAt: warning.resolvedAt || '', resolution: warning.status === 'resolved' ? 'Resolved by a successful finalization retry' : ''
+        };
+    if (existing && JSON.stringify(existing) === JSON.stringify(after))
+        return { status: 'no-op', changed: false, error: null };
+    const written = writeTask({
+        taskRef: resolved.taskId,
+        expectedState: 'completed',
+        mutations: [...sectionMutation(content), rowMutation(after)]
+    }, {
+        ...options,
+        taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: 'completed' },
+        metadataProvider: () => metadata
+    });
+    if (written.status === 'failed')
+        return { status: 'failed', changed: false, error: { code: written.error.code, message: written.error.message } };
+    return { status: written.status === 'applied' ? 'applied' : 'no-op', changed: written.changed, error: null };
+}
+export { applyWorkflowWarningIntent, projectFinalizationWarning };
 //# sourceMappingURL=workflow-warning-intents.js.map

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.9.8",
-  "sourceInputHash": "fb481e6579519b3fd10c9ca9bf284d65498f935c034a14c047d023345abeb87c",
-  "internalExecutableBuildHash": "d8dcdf602b61001ba9829aa2027cccadcc9c371ccf9e29c3d681fd02d5a3a5af"
+  "packageVersion": "0.9.9",
+  "sourceInputHash": "2f2db695db557531b3139eccd1bd530fbeb7b99409e2d49338f3b4646aac9ef6",
+  "internalExecutableBuildHash": "1391ebe2614f3071e7a60920325046a47f1473e7fb23c821327072f947f639d3"
 }

package/lib/agent-clients/adapters/codex-lifecycle/app-server.ts

@@ -36,6 +36,10 @@ type AppServerTransportOptions = Readonly<{
   timeoutMs?: number;
   rolloutReadAttempts?: number;
   rolloutRetryMs?: number;
+  threadReadAttempts?: number;
+  threadRetryMs?: number;
+  terminalReadAttempts?: number;
+  terminalRetryMs?: number;
 }>;
 
 type CodexRuntimeIdentity = Readonly<{
@@ -52,6 +56,10 @@ const LIFECYCLE_HOOKS = Object.freeze([
 ]);
 const DEFAULT_ROLLOUT_READ_ATTEMPTS = 81;
 const DEFAULT_ROLLOUT_RETRY_MS = 100;
+const DEFAULT_THREAD_READ_ATTEMPTS = 21;
+const DEFAULT_THREAD_RETRY_MS = 100;
+const DEFAULT_TERMINAL_READ_ATTEMPTS = 21;
+const DEFAULT_TERMINAL_RETRY_MS = 100;
 
 function object(value: unknown): JsonObject | null {
   return value && typeof value === 'object' && !Array.isArray(value)
@@ -67,6 +75,7 @@ function resolveCodexSpawnedChild(
   transcriptPath: string,
   expected: Readonly<{
     sessionId: string;
+    turnId: string;
     toolUseId: string;
     nativeAgent: string;
     taskName: string;
@@ -111,15 +120,19 @@ function resolveCodexSpawnedChild(
   ) throw new Error('Codex parent rollout spawn identity does not match the hook event');
   const activities = records.filter((record) => {
     const payload = object(record?.payload);
+    const item = object(payload?.item);
     return record?.type === 'event_msg'
-      && payload?.type === 'sub_agent_activity'
-      && payload.event_id === expected.toolUseId
-      && payload.kind === 'started'
-      && payload.agent_path === `/root/${expected.taskName}`
-      && nonEmpty(payload.agent_thread_id);
+      && payload?.type === 'item_completed'
+      && payload.thread_id === expected.sessionId
+      && payload.turn_id === expected.turnId
+      && item?.type === 'SubAgentActivity'
+      && item.id === expected.toolUseId
+      && item.kind === 'started'
+      && item.agent_path === `/root/${expected.taskName}`
+      && nonEmpty(item.agent_thread_id);
   });
   if (activities.length !== 1) throw new Error('Codex parent rollout child activity was not found uniquely');
-  return nonEmpty(object(activities[0]?.payload)?.agent_thread_id)!;
+  return nonEmpty(object(object(activities[0]?.payload)?.item)?.agent_thread_id)!;
 }
 
 function validateCodexLifecycleHookConfig(value: unknown): void {
@@ -133,7 +146,7 @@ function validateCodexLifecycleHookConfig(value: unknown): void {
       return entry.hooks.some((hookValue) => {
         const hook = object(hookValue);
         return hook?.type === 'command'
-          && hook.timeout === 15
+          && hook.timeout === 30
           && hook.command === `node "$(git rev-parse --show-toplevel)/.agents/hooks/lifecycle-delegation.js" --client codex --event ${phase}`;
       });
     });
@@ -478,18 +491,30 @@ async function resolveCodexThread(
     const readResult = object(await transport.request('thread/read', { threadId: childThreadId, includeTurns: false }));
     const readThread = object(readResult?.thread);
     if (nonEmpty(readThread?.id) !== childThreadId) throw new Error('Codex App Server returned the wrong child thread');
-    let resolution: ThreadResolution;
+    let rolloutRecords: readonly unknown[];
     try {
-      const rolloutRecords = await resolveCodexRolloutRecords(
+      rolloutRecords = await resolveCodexRolloutRecords(
         readResult,
         childThreadId,
         options.rolloutReadAttempts ?? DEFAULT_ROLLOUT_READ_ATTEMPTS,
         options.rolloutRetryMs ?? DEFAULT_ROLLOUT_RETRY_MS
       );
-      resolution = parseCodexThreadResolution(readResult, rolloutRecords);
     } catch {
       throw new Error('Codex App Server rollout metadata is unavailable');
     }
+    let resolution = parseCodexThreadResolution(readResult, rolloutRecords);
+    const threadReadAttempts = options.threadReadAttempts ?? DEFAULT_THREAD_READ_ATTEMPTS;
+    for (let attempt = 1; resolution.thread.forkedFromId !== null && attempt < threadReadAttempts; attempt += 1) {
+      await new Promise((resolve) => setTimeout(resolve, options.threadRetryMs ?? DEFAULT_THREAD_RETRY_MS));
+      const refreshed = object(await transport.request('thread/read', { threadId: childThreadId, includeTurns: false }));
+      if (nonEmpty(object(refreshed?.thread)?.id) !== childThreadId) {
+        throw new Error('Codex App Server returned the wrong child thread');
+      }
+      resolution = parseCodexThreadResolution(refreshed, rolloutRecords);
+    }
+    if (resolution.thread.forkedFromId !== null) {
+      throw new Error('Codex App Server fresh thread metadata is unavailable');
+    }
     const reroutes = transport.notifications
       .filter((entry) => entry.method === 'model/rerouted')
       .map((entry) => parseCodexModelReroute(entry.params))
@@ -507,20 +532,37 @@ async function resolveCodexThread(
 
 async function resolveCodexTerminal(
   childThreadId: string,
-  options: AppServerTransportOptions = {}
+  expectedTurnIdOrOptions: string | AppServerTransportOptions = {},
+  terminalOptions: AppServerTransportOptions = {}
 ): Promise<Extract<CodexLifecycleEvent, { type: 'app-terminal' }>> {
+  const expectedTurnId = typeof expectedTurnIdOrOptions === 'string' ? expectedTurnIdOrOptions : null;
+  const options = typeof expectedTurnIdOrOptions === 'string' ? terminalOptions : expectedTurnIdOrOptions;
   const transport = new CodexAppServerTransport(options);
   transport.start();
   try {
     await transport.initialize();
-    const result = object(await transport.request('thread/read', { threadId: childThreadId, includeTurns: true }));
-    const thread = object(result?.thread);
-    if (nonEmpty(thread?.id) !== childThreadId) throw new Error('Codex App Server returned the wrong child thread');
-    const turns = Array.isArray(thread?.turns) ? thread.turns : [];
-    const turn = turns.at(-1);
-    const turnValue = object(turn);
-    if (!turnValue || turnValue.status === 'inProgress') throw new Error('CODEX_TURN_NOT_TERMINAL');
-    return parseCodexTurnCompleted({ threadId: childThreadId, turn });
+    const attempts = expectedTurnId ? options.terminalReadAttempts ?? DEFAULT_TERMINAL_READ_ATTEMPTS : 1;
+    let abnormal: Extract<CodexLifecycleEvent, { type: 'app-terminal' }> | null = null;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+      const result = object(await transport.request('thread/read', { threadId: childThreadId, includeTurns: true }));
+      const thread = object(result?.thread);
+      if (nonEmpty(thread?.id) !== childThreadId) throw new Error('Codex App Server returned the wrong child thread');
+      const turns = Array.isArray(thread?.turns) ? thread.turns : [];
+      const turn = expectedTurnId
+        ? turns.find((candidate) => object(candidate)?.id === expectedTurnId)
+        : turns.at(-1);
+      const turnValue = object(turn);
+      if (turnValue && turnValue.status !== 'inProgress') {
+        const terminal = parseCodexTurnCompleted({ threadId: childThreadId, turn });
+        if (terminal.status === 'completed') return terminal;
+        abnormal = terminal;
+      }
+      if (attempt + 1 < attempts) {
+        await new Promise((resolve) => setTimeout(resolve, options.terminalRetryMs ?? DEFAULT_TERMINAL_RETRY_MS));
+      }
+    }
+    if (abnormal) return abnormal;
+    throw new Error('CODEX_TURN_NOT_TERMINAL');
   } finally {
     transport.close();
   }

package/lib/agent-clients/adapters/codex-lifecycle/build-identity.ts

@@ -3,6 +3,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import semver from 'semver';
+
 const LIFECYCLE_PROTOCOL_VERSION = 3;
 
 type LifecycleBuildIdentity = Readonly<{
@@ -32,6 +34,14 @@ function exactText(value: unknown): value is string {
   return typeof value === 'string' && value.trim() === value && value.length > 0;
 }
 
+function isCanonicalLifecyclePackageVersion(value: unknown): value is string {
+  return typeof value === 'string' && semver.valid(value) === value;
+}
+
+function isLifecycleProtocolVersion(value: unknown): value is typeof LIFECYCLE_PROTOCOL_VERSION {
+  return value === LIFECYCLE_PROTOCOL_VERSION;
+}
+
 function normalizeRelativePath(value: string): string {
   return value.replaceAll('\\', '/');
 }
@@ -215,6 +225,8 @@ function verifyLifecycleBuildIdentity(
 export {
   LIFECYCLE_PROTOCOL_VERSION,
   computeLifecycleBuildIdentity,
+  isCanonicalLifecyclePackageVersion,
+  isLifecycleProtocolVersion,
   readLifecycleManifestFiles,
   resolveLifecycleExecutableFiles,
   verifyLifecycleBuildIdentity