@kbediako/codex-orchestrator 0.1.38 → 0.2.1

package/dist/orchestrator/src/cli/services/commandRunner.js

@@ -1,4 +1,5 @@
 import { createWriteStream } from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { ToolInvocationFailedError } from '../../../../packages/orchestrator/src/index.js';
 import { getCliExecRunner, getPrivacyGuard, getExecHandleService } from './execRuntime.js';
@@ -6,15 +7,30 @@ import { logger } from '../../logger.js';
 import { relativeToRepo } from '../run/runPaths.js';
 import { appendCommandError, updateCommandStatus } from '../run/manifest.js';
 import { persistManifest } from '../run/manifestPersister.js';
+import { PROVIDER_LINEAR_WORKER_PROOF_FILENAME } from '../providerLinearWorkerRunner.js';
 import { slugify } from '../utils/strings.js';
 import { isoTimestamp } from '../utils/time.js';
+import { buildCommandPreview } from '../utils/commandPreview.js';
 import { EnvUtils } from '../../../../packages/shared/config/index.js';
+import { deriveReviewOutcomeDisposition } from '../../../../scripts/lib/review-execution-telemetry.js';
 import { findPackageRoot } from '../utils/packageInfo.js';
+import { applyResolvedProgramInvocationEnvOverrides, resolvePackageProgramInvocation, resolveProviderLinearWorkerProgramInvocation } from '../utils/packageProgramResolver.js';
+import { buildProviderLinearWorkerTerminalSummary, deriveDeterministicProviderMutationSuppressions, formatDeterministicProviderMutationDegradationSummary, isProviderLinearWorkerProofFreshForStage, resolveProviderLinearWorkerAttemptStartedAt, resolveProviderLinearWorkerTerminalReason, resolveProviderLinearWorkerTerminalStatus } from '../control/providerLinearWorkerTruth.js';
 const MAX_BUFFERED_OUTPUT_BYTES = 64 * 1024;
 const EMIT_COMMAND_STREAM_MIRRORS = EnvUtils.getBoolean('CODEX_ORCHESTRATOR_EMIT_COMMAND_STREAMS', false);
 export const MAX_CAPTURED_CHUNK_EVENTS = EnvUtils.getInt('CODEX_ORCHESTRATOR_EXEC_EVENT_MAX_CHUNKS', 500);
 const MAX_COLLAB_TOOL_CALLS = EnvUtils.getInt('CODEX_ORCHESTRATOR_COLLAB_MAX_EVENTS', 200);
 const PACKAGE_ROOT = findPackageRoot();
+const REVIEW_EVIDENCE_CONSISTENCY_ENV_KEY = 'CODEX_REVIEW_ENFORCE_EVIDENCE_CONSISTENCY';
+const REVIEW_EVIDENCE_WAIVER_REASON_ENV_KEY = 'CODEX_REVIEW_EVIDENCE_WAIVER_REASON';
+const REVIEW_TELEMETRY_POLL_INTERVAL_MS = 50;
+const REVIEW_TELEMETRY_WAIT_TIMEOUT_MS = 2_000;
+const REVIEW_OUTCOME_BOUNDARY_PRESENCE_SENTINEL = {
+    kind: 'timeout',
+    provenance: 'review-timeout',
+    reason: '',
+    sample: null
+};
 export async function runCommandStage(context, hooks = {}) {
     const { env, paths, manifest, stage, index, events, persister, envOverrides } = context;
     const entryIndex = index - 1;
@@ -44,8 +60,8 @@ export async function runCommandStage(context, hooks = {}) {
         runnerLog.write(payload);
         commandLog.write(payload);
     };
-    writeEvent({ type: 'command:start', command: stage.command });
     const runner = getCliExecRunner();
+    let invocationPreview = stage.command;
     let activeCorrelationId = null;
     let stdoutBytes = 0;
     let stderrBytes = 0;
@@ -111,7 +127,7 @@ export async function runCommandStage(context, hooks = {}) {
                     stageIndex: index,
                     toolName: 'exec',
                     status: 'started',
-                    message: stage.command,
+                    message: invocationPreview,
                     attempt: event.attempt
                 });
                 break;
@@ -175,17 +191,32 @@ export async function runCommandStage(context, hooks = {}) {
             CODEX_ORCHESTRATOR_ROOT: env.repoRoot,
             CODEX_ORCHESTRATOR_PACKAGE_ROOT: PACKAGE_ROOT
         };
+        baseEnv.CODEX_ORCHESTRATOR_NODE_BIN = process.execPath;
         baseEnv.CODEX_ORCHESTRATOR_RUNTIME_MODE_ACTIVE =
             context.runtimeMode ?? (manifest.runtime_mode === 'appserver' ? 'appserver' : 'cli');
         // Keep both keys during migration because downstream tools still read either name.
         baseEnv.CODEX_ORCHESTRATOR_RUNTIME_MODE = baseEnv.CODEX_ORCHESTRATOR_RUNTIME_MODE_ACTIVE;
         const execEnv = { ...baseEnv, ...stage.env };
+        execEnv.CODEX_ORCHESTRATOR_NODE_BIN = process.execPath;
+        const invocation = resolveStageInvocation(stage, execEnv);
+        applyResolvedProgramInvocationEnvOverrides(execEnv, invocation.envOverrides);
+        if (invocation.warning) {
+            logger.warn(invocation.warning);
+            writeEvent({ type: 'command:warning', warning: invocation.warning });
+        }
+        invocationPreview = invocation.preview;
+        writeEvent({ type: 'command:start', command: invocationPreview });
+        const timeoutMs = resolveStageTimeoutMs(stage, execEnv);
         const invocationId = `cli-command:${manifest.run_id}:${stage.id}:${Date.now()}`;
+        if (timeoutMs !== null) {
+            writeEvent({ type: 'command:config', timeout_ms: timeoutMs });
+        }
         let result;
         const eventCapture = MAX_CAPTURED_CHUNK_EVENTS > 0 ? { maxChunkEvents: MAX_CAPTURED_CHUNK_EVENTS } : undefined;
         try {
             result = await runner.run({
-                command: stage.command,
+                command: invocation.command,
+                args: invocation.args,
                 cwd: stage.cwd ?? env.repoRoot,
                 env: execEnv,
                 sessionId: effectiveSessionId ?? undefined,
@@ -194,6 +225,7 @@ export async function runCommandStage(context, hooks = {}) {
                 invocationId,
                 toolId: 'cli:command',
                 description: stage.title,
+                ...(timeoutMs !== null ? { timeoutMs } : {}),
                 eventCapture,
                 metadata: {
                     stageId: stage.id,
@@ -233,11 +265,163 @@ export async function runCommandStage(context, hooks = {}) {
         const normalizedExitCode = result.exitCode ?? (result.signal ? 128 : 0);
         const stdoutText = result.stdout.trim();
         const stderrText = result.stderr.trim();
-        const summary = buildSummary(stage, normalizedExitCode, stdoutText, stderrText, result.signal);
+        const timeoutBoundMs = typeof result.timeoutMs === 'number' && Number.isFinite(result.timeoutMs) && result.timeoutMs > 0
+            ? Math.trunc(result.timeoutMs)
+            : timeoutMs;
+        const timedOut = result.timedOut === true;
+        const summary = buildSummary(stage, normalizedExitCode, stdoutText, stderrText, result.signal, {
+            timedOut,
+            timeoutMs: timeoutBoundMs
+        });
+        const enforceReviewEvidenceConsistency = shouldEnforceReviewEvidenceConsistency(stage);
+        const providerLinearWorkerStage = isProviderLinearWorkerCommandStage(stage);
+        const reviewTelemetryPath = join(paths.runDir, 'review', 'telemetry.json');
+        const shouldAwaitReviewTelemetry = (isReviewCommandStage(stage) || providerLinearWorkerStage) &&
+            shouldAwaitReviewTelemetryEvidence(execEnv, enforceReviewEvidenceConsistency);
+        const reviewTelemetry = isReviewCommandStage(stage) || providerLinearWorkerStage
+            ? await loadReviewTelemetryEvidence(reviewTelemetryPath, {
+                waitForEvidence: shouldAwaitReviewTelemetry
+            })
+            : null;
+        const reviewEvidenceMismatch = isReviewCommandStage(stage) && (enforceReviewEvidenceConsistency || reviewTelemetry !== null)
+            ? await verifyReviewEvidenceConsistency({
+                env,
+                paths,
+                expectedStatus: result.status === 'succeeded' ? 'succeeded' : 'failed',
+                startedAt: entry.started_at,
+                telemetry: reviewTelemetry,
+                telemetryPreloaded: shouldAwaitReviewTelemetry,
+                telemetryPath: reviewTelemetryPath
+            })
+            : null;
+        const providerReviewTelemetryMismatch = providerLinearWorkerStage && reviewTelemetry !== null
+            ? verifyReviewTelemetryFreshness({
+                env,
+                paths,
+                startedAt: entry.started_at,
+                telemetry: reviewTelemetry,
+                telemetryPath: reviewTelemetryPath
+            })
+            : null;
+        const providerReviewTelemetry = providerReviewTelemetryMismatch === null
+            ? reviewTelemetry
+            : null;
+        const reviewEvidenceWaiverReason = resolveReviewEvidenceWaiverReason(stage.env);
+        let effectiveSummary = summary;
+        let forceReviewEvidenceFailure = false;
+        let forceProviderLinearWorkerFailure = false;
+        let providerLinearWorkerFailureReason = null;
+        let providerLinearWorkerTerminalStatus = null;
+        let providerLinearWorkerTerminalReason = null;
+        let providerLinearWorkerReviewOutcomeSummary = null;
+        if (reviewEvidenceMismatch && enforceReviewEvidenceConsistency) {
+            if (reviewEvidenceWaiverReason) {
+                effectiveSummary = `${summary} (review evidence waiver: ${reviewEvidenceWaiverReason}; ${reviewEvidenceMismatch.message})`;
+                writeEvent({
+                    type: 'command:waiver',
+                    waiver: 'review-evidence-consistency',
+                    reason: reviewEvidenceWaiverReason,
+                    telemetry_path: relativeToRepo(env, reviewEvidenceMismatch.telemetryPath),
+                    detail: reviewEvidenceMismatch.message
+                });
+                events?.log({
+                    stageId: stage.id,
+                    stageIndex: index,
+                    level: 'warn',
+                    source: 'system',
+                    message: `Review evidence waiver applied: ${reviewEvidenceMismatch.message}`
+                });
+            }
+            else {
+                effectiveSummary =
+                    result.status === 'succeeded'
+                        ? `Review evidence mismatch: ${reviewEvidenceMismatch.message}`
+                        : `Review evidence mismatch after command failure: ${reviewEvidenceMismatch.message} Command result: ${summary}`;
+                forceReviewEvidenceFailure = true;
+            }
+        }
+        if (!reviewEvidenceMismatch) {
+            const reviewOutcomeSummary = formatReviewTelemetryOutcomeSummary(providerLinearWorkerStage ? providerReviewTelemetry : reviewTelemetry);
+            if (reviewOutcomeSummary) {
+                effectiveSummary = `${effectiveSummary} (${reviewOutcomeSummary})`;
+            }
+        }
+        if (providerLinearWorkerStage) {
+            let providerLinearWorkerProof = await loadProviderLinearWorkerProof(join(paths.runDir, PROVIDER_LINEAR_WORKER_PROOF_FILENAME));
+            let providerLinearWorkerProofRecord = providerLinearWorkerProof;
+            if (providerLinearWorkerProofRecord &&
+                !isProviderLinearWorkerProofFreshForStage(providerLinearWorkerProofRecord, entry.started_at ?? null)) {
+                providerLinearWorkerProof = null;
+                providerLinearWorkerProofRecord = null;
+            }
+            manifest.provider_linear_worker_tokens =
+                buildProviderLinearWorkerManifestTokenUsage(providerLinearWorkerProof?.tokens) ?? null;
+            if (result.status === 'succeeded' && providerLinearWorkerProofRecord === null) {
+                providerLinearWorkerFailureReason = 'provider_linear_worker_proof_missing_or_unreadable';
+                effectiveSummary = buildProviderLinearWorkerTerminalSummary({
+                    status: 'failed',
+                    endReason: 'provider_linear_worker_proof_missing_or_unreadable'
+                });
+                forceProviderLinearWorkerFailure = true;
+            }
+            const proofTerminalStatus = resolveProviderLinearWorkerTerminalStatus(providerLinearWorkerProofRecord);
+            const proofTerminalReason = resolveProviderLinearWorkerTerminalReason(providerLinearWorkerProofRecord);
+            providerLinearWorkerTerminalStatus = proofTerminalStatus;
+            providerLinearWorkerTerminalReason = proofTerminalReason;
+            const proofAttemptStartedAt = resolveProviderLinearWorkerAttemptStartedAt(providerLinearWorkerProofRecord) ?? entry.started_at ?? null;
+            const reviewTelemetryStatus = coerceTelemetryStatusValue(providerReviewTelemetry?.status);
+            const reviewOutcomeSummary = formatReviewTelemetryOutcomeSummary(providerReviewTelemetry);
+            providerLinearWorkerReviewOutcomeSummary = reviewOutcomeSummary;
+            const mutationSuppressions = deriveDeterministicProviderMutationSuppressions(providerLinearWorkerProof?.linear_audit ?? null, {
+                recordedAtNotBefore: proofAttemptStartedAt,
+                issueId: providerLinearWorkerProof?.issue_id ?? null
+            });
+            const degradationSummary = formatDeterministicProviderMutationDegradationSummary(mutationSuppressions);
+            if (proofTerminalStatus === 'failed') {
+                providerLinearWorkerFailureReason = 'provider_linear_worker_terminal_failed';
+                effectiveSummary = buildProviderLinearWorkerTerminalSummary({
+                    status: 'failed',
+                    endReason: proofTerminalReason,
+                    reviewOutcomeSummary,
+                    degradationSummary
+                });
+                forceProviderLinearWorkerFailure = true;
+            }
+            else if (providerLinearWorkerFailureReason === null && reviewTelemetryStatus === 'failed') {
+                providerLinearWorkerFailureReason = 'provider_linear_worker_review_failed';
+                effectiveSummary = buildProviderLinearWorkerTerminalSummary({
+                    status: 'failed',
+                    endReason: null,
+                    reviewOutcomeSummary: reviewOutcomeSummary ?? 'review telemetry reported terminal failure',
+                    degradationSummary
+                });
+                forceProviderLinearWorkerFailure = true;
+            }
+            else if (proofTerminalStatus === 'succeeded' && result.status === 'succeeded') {
+                effectiveSummary = buildProviderLinearWorkerTerminalSummary({
+                    status: 'succeeded',
+                    endReason: proofTerminalReason,
+                    reviewOutcomeSummary,
+                    degradationSummary
+                });
+            }
+            else if (degradationSummary) {
+                effectiveSummary = `${effectiveSummary} (${degradationSummary})`;
+            }
+        }
+        const effectiveExitCode = (forceReviewEvidenceFailure || forceProviderLinearWorkerFailure) && normalizedExitCode === 0
+            ? 1
+            : normalizedExitCode;
         entry.completed_at = isoTimestamp();
-        entry.exit_code = normalizedExitCode;
-        entry.summary = summary;
-        entry.status = result.status === 'succeeded' ? 'succeeded' : stage.allowFailure ? 'skipped' : 'failed';
+        entry.exit_code = effectiveExitCode;
+        entry.summary = effectiveSummary;
+        entry.status = forceReviewEvidenceFailure || forceProviderLinearWorkerFailure
+            ? 'failed'
+            : result.status === 'succeeded'
+                ? 'succeeded'
+                : stage.allowFailure
+                    ? 'skipped'
+                    : 'failed';
         if (collabBuffer.trim()) {
             const record = parseCollabToolCallLine(collabBuffer, stage.id, entry.index);
             if (record) {
@@ -245,22 +429,113 @@ export async function runCommandStage(context, hooks = {}) {
             }
             collabBuffer = '';
         }
-        if (entry.status === 'failed') {
-            const errorDetails = {
+        if (result.status !== 'succeeded' && entry.status === 'skipped') {
+            const fallbackReason = timedOut ? 'timed_out' : 'command_failed';
+            writeEvent({
+                type: 'command:fallback',
+                fallback: 'allow_failure',
+                reason: fallbackReason,
                 exit_code: normalizedExitCode,
+                signal: result.signal,
+                timeout_ms: timeoutBoundMs
+            });
+            events?.log({
+                stageId: stage.id,
+                stageIndex: index,
+                level: 'warn',
+                source: 'system',
+                message: timedOut
+                    ? `Non-fatal fallback applied after timeout (${timeoutBoundMs !== null ? `${timeoutBoundMs}ms` : 'configured timeout'}).`
+                    : 'Non-fatal fallback applied after command failure.'
+            });
+        }
+        if (result.status !== 'succeeded') {
+            const failureReason = timedOut ? 'timed_out' : 'command_failed';
+            const errorDetails = {
+                exit_code: effectiveExitCode,
                 sandbox_state: result.sandboxState,
-                stderr: stderrText
+                stderr: stderrText,
+                failure_reason: failureReason
             };
+            if (effectiveExitCode !== normalizedExitCode) {
+                errorDetails.command_exit_code = normalizedExitCode;
+            }
             if (result.signal) {
                 errorDetails.signal = result.signal;
             }
+            if (timeoutBoundMs !== null) {
+                errorDetails.timeout_ms = timeoutBoundMs;
+            }
+            if (timedOut) {
+                errorDetails.timed_out = true;
+            }
+            if (entry.status === 'skipped') {
+                errorDetails.non_fatal_fallback = true;
+            }
+            if (stdoutTruncated) {
+                errorDetails.stdout_truncated = true;
+            }
+            if (stderrTruncated) {
+                errorDetails.stderr_truncated = true;
+            }
+            entry.error_file = await appendCommandError(env, paths, manifest, entry, entry.status === 'skipped' ? 'command-allow-failure' : 'command-failed', errorDetails);
+        }
+        if (forceProviderLinearWorkerFailure && result.status === 'succeeded' && !entry.error_file) {
+            const errorDetails = {
+                exit_code: effectiveExitCode,
+                command_exit_code: normalizedExitCode,
+                sandbox_state: result.sandboxState,
+                failure_reason: providerLinearWorkerFailureReason ?? 'provider_linear_worker_authoritative_failure',
+                detail: effectiveSummary
+            };
+            if (providerLinearWorkerTerminalStatus) {
+                errorDetails.provider_linear_worker_terminal_status = providerLinearWorkerTerminalStatus;
+            }
+            if (providerLinearWorkerTerminalReason) {
+                errorDetails.provider_linear_worker_end_reason = providerLinearWorkerTerminalReason;
+            }
+            if (providerLinearWorkerReviewOutcomeSummary) {
+                errorDetails.review_outcome_summary = providerLinearWorkerReviewOutcomeSummary;
+            }
             if (stdoutTruncated) {
                 errorDetails.stdout_truncated = true;
             }
             if (stderrTruncated) {
                 errorDetails.stderr_truncated = true;
             }
-            entry.error_file = await appendCommandError(env, paths, manifest, entry, 'command-failed', errorDetails);
+            entry.error_file = await appendCommandError(env, paths, manifest, entry, 'provider-linear-worker-authoritative-failed', errorDetails);
+        }
+        if (forceReviewEvidenceFailure && reviewEvidenceMismatch) {
+            if (entry.error_file) {
+                writeEvent({
+                    type: 'command:warning',
+                    warning: 'review-evidence-inconsistent',
+                    preserved_error_file: entry.error_file,
+                    telemetry_path: relativeToRepo(env, reviewEvidenceMismatch.telemetryPath),
+                    detail: reviewEvidenceMismatch.message
+                });
+                events?.log({
+                    stageId: stage.id,
+                    stageIndex: index,
+                    level: 'warn',
+                    source: 'system',
+                    message: `Review evidence mismatch preserved alongside the original command failure: ${reviewEvidenceMismatch.message}`
+                });
+            }
+            else {
+                entry.error_file = await appendCommandError(env, paths, manifest, entry, 'review-evidence-inconsistent', {
+                    exit_code: effectiveExitCode,
+                    command_exit_code: normalizedExitCode,
+                    sandbox_state: result.sandboxState,
+                    expected_review_status: result.status === 'succeeded' ? 'succeeded' : 'failed',
+                    telemetry_status: reviewEvidenceMismatch.telemetryStatus,
+                    telemetry_generated_at: reviewEvidenceMismatch.telemetryGeneratedAt,
+                    telemetry_output_log_path: reviewEvidenceMismatch.telemetryOutputLogPath,
+                    telemetry_path: relativeToRepo(env, reviewEvidenceMismatch.telemetryPath),
+                    failure_reason: 'review_evidence_inconsistent',
+                    detail: reviewEvidenceMismatch.message
+                });
+            }
         }
         await persistManifest(paths, manifest, persister, { force: true });
         events?.stageCompleted({
@@ -273,7 +548,7 @@ export async function runCommandStage(context, hooks = {}) {
             summary: entry.summary,
             logPath: entry.log_path
         });
-        return { exitCode: normalizedExitCode, summary };
+        return { exitCode: effectiveExitCode, summary: effectiveSummary };
     }
     finally {
         unsubscribe();
@@ -282,6 +557,331 @@ export async function runCommandStage(context, hooks = {}) {
         privacyLog.end();
     }
 }
+function shouldEnforceReviewEvidenceConsistency(stage) {
+    return (parseBooleanEnvFlag(stage.env?.[REVIEW_EVIDENCE_CONSISTENCY_ENV_KEY]) &&
+        isReviewCommandStage(stage));
+}
+function shouldAwaitReviewTelemetryEvidence(execEnv, enforceReviewEvidenceConsistency) {
+    if (enforceReviewEvidenceConsistency) {
+        return true;
+    }
+    const forced = parseBooleanEnvFlag(execEnv.FORCE_CODEX_REVIEW);
+    const nonInteractive = process.stdin.isTTY !== true ||
+        parseBooleanEnvFlag(execEnv.CODEX_REVIEW_NON_INTERACTIVE) ||
+        parseBooleanEnvFlag(execEnv.CODEX_NON_INTERACTIVE) ||
+        parseBooleanEnvFlag(execEnv.CODEX_NO_INTERACTIVE);
+    return forced || !nonInteractive;
+}
+function isReviewCommandStage(stage) {
+    const stageId = stage.id.trim().toLowerCase();
+    if (stageId === 'review') {
+        return true;
+    }
+    const haystack = `${stage.title} ${stage.command}`.toLowerCase();
+    return (haystack.includes('npm run review') ||
+        haystack.includes('codex review') ||
+        haystack.includes('codex-orchestrator review') ||
+        haystack.includes('run-review.ts') ||
+        haystack.includes('run-review.js'));
+}
+function isProviderLinearWorkerCommandStage(stage) {
+    const stageId = stage.id.trim().toLowerCase();
+    if (stageId === 'provider-linear-worker') {
+        return true;
+    }
+    const haystack = `${stage.title} ${stage.command}`.toLowerCase();
+    return haystack.includes('providerlinearworkerrunner');
+}
+function resolveStageInvocation(stage, env) {
+    if (isProviderLinearWorkerCommandStage(stage)) {
+        const providerWorkerPackageRoot = normalizeOptionalString(env.CODEX_ORCHESTRATOR_PACKAGE_ROOT) ?? PACKAGE_ROOT;
+        const invocation = resolveProviderLinearWorkerProgramInvocation({
+            allowConfiguredForeignPackageRoot: true,
+            env,
+            execPath: normalizeOptionalString(env.CODEX_ORCHESTRATOR_NODE_BIN) ?? process.execPath,
+            packageRoot: providerWorkerPackageRoot
+        });
+        return {
+            command: invocation.command,
+            args: invocation.args,
+            preview: buildCommandPreview(invocation.command, invocation.args),
+            warning: invocation.warning,
+            envOverrides: invocation.envOverrides
+        };
+    }
+    const packageRootInvocation = resolvePackageRootDistStageInvocation(stage.command, env);
+    if (packageRootInvocation) {
+        return packageRootInvocation;
+    }
+    return {
+        command: stage.command,
+        preview: stage.command
+    };
+}
+function resolvePackageRootDistStageInvocation(commandLine, env) {
+    const match = commandLine.match(/^\s*node\s+["']?\$CODEX_ORCHESTRATOR_PACKAGE_ROOT\/dist\/([^"'\s]+?\.js)["']?(.*)$/u);
+    if (!match) {
+        return null;
+    }
+    const [, distRelativePath, trailingArgsRaw] = match;
+    const invocation = resolvePackageProgramInvocation({
+        allowConfiguredForeignPackageRoot: true,
+        env,
+        packageRoot: PACKAGE_ROOT,
+        execPath: normalizeOptionalString(env.CODEX_ORCHESTRATOR_NODE_BIN) ?? process.execPath,
+        distRelativePath
+    });
+    const command = `${buildCommandPreview(invocation.command, invocation.args)}${trailingArgsRaw}`;
+    return {
+        command,
+        preview: command,
+        warning: invocation.warning,
+        envOverrides: invocation.envOverrides
+    };
+}
+function resolveReviewEvidenceWaiverReason(env) {
+    const reason = env?.[REVIEW_EVIDENCE_WAIVER_REASON_ENV_KEY]?.trim();
+    return reason && reason.length > 0 ? reason : null;
+}
+function parseBooleanEnvFlag(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+}
+async function verifyReviewEvidenceConsistency(options) {
+    const telemetryPath = options.telemetryPath ?? join(options.paths.runDir, 'review', 'telemetry.json');
+    const telemetry = options.telemetryPreloaded === true
+        ? options.telemetry ?? null
+        : options.telemetry ?? (await waitForReviewTelemetryEvidence(telemetryPath));
+    if (!telemetry) {
+        return {
+            message: 'review telemetry is missing, unreadable, or incomplete at terminal stage closeout.',
+            telemetryPath,
+            telemetryStatus: null,
+            telemetryGeneratedAt: null,
+            telemetryOutputLogPath: null
+        };
+    }
+    const freshnessMismatch = verifyReviewTelemetryFreshness({
+        env: options.env,
+        paths: options.paths,
+        startedAt: options.startedAt,
+        telemetry,
+        telemetryPath
+    });
+    if (freshnessMismatch) {
+        return freshnessMismatch;
+    }
+    const generatedAt = coerceTelemetryString(telemetry.generated_at);
+    const telemetryStatus = coerceTelemetryString(telemetry.status);
+    const telemetryOutputLogPath = coerceTelemetryString(telemetry.output_log_path);
+    if (telemetryStatus !== options.expectedStatus) {
+        return {
+            message: `review telemetry status ${telemetryStatus ?? '<missing>'} does not match terminal stage result ${options.expectedStatus}.`,
+            telemetryPath,
+            telemetryStatus,
+            telemetryGeneratedAt: generatedAt,
+            telemetryOutputLogPath
+        };
+    }
+    return null;
+}
+function verifyReviewTelemetryFreshness(options) {
+    const { env, paths, startedAt, telemetry, telemetryPath } = options;
+    const generatedAt = typeof telemetry.generated_at === 'string' && telemetry.generated_at.trim().length > 0
+        ? telemetry.generated_at
+        : null;
+    if (!generatedAt) {
+        return {
+            message: 'review telemetry is missing generated_at, so terminal evidence freshness cannot be verified.',
+            telemetryPath,
+            telemetryStatus: coerceTelemetryString(telemetry.status),
+            telemetryGeneratedAt: null,
+            telemetryOutputLogPath: coerceTelemetryString(telemetry.output_log_path)
+        };
+    }
+    const generatedAtMs = Date.parse(generatedAt);
+    if (!Number.isFinite(generatedAtMs)) {
+        return {
+            message: `review telemetry generated_at is invalid (${generatedAt}).`,
+            telemetryPath,
+            telemetryStatus: coerceTelemetryString(telemetry.status),
+            telemetryGeneratedAt: generatedAt,
+            telemetryOutputLogPath: coerceTelemetryString(telemetry.output_log_path)
+        };
+    }
+    const startedAtMs = typeof startedAt === 'string' ? Date.parse(startedAt) : Number.NaN;
+    if (Number.isFinite(startedAtMs) && generatedAtMs < startedAtMs) {
+        return {
+            message: `review telemetry is stale (generated_at ${generatedAt} precedes stage start ${startedAt}).`,
+            telemetryPath,
+            telemetryStatus: coerceTelemetryString(telemetry.status),
+            telemetryGeneratedAt: generatedAt,
+            telemetryOutputLogPath: coerceTelemetryString(telemetry.output_log_path)
+        };
+    }
+    const expectedOutputLogPath = relativeToRepo(env, join(paths.runDir, 'review', 'output.log'));
+    const telemetryStatus = coerceTelemetryString(telemetry.status);
+    const telemetryOutputLogPath = coerceTelemetryString(telemetry.output_log_path);
+    if (telemetryOutputLogPath !== expectedOutputLogPath) {
+        return {
+            message: `review telemetry output_log_path ${telemetryOutputLogPath ?? '<missing>'} does not match the active run artifact ${expectedOutputLogPath}.`,
+            telemetryPath,
+            telemetryStatus,
+            telemetryGeneratedAt: generatedAt,
+            telemetryOutputLogPath
+        };
+    }
+    return null;
+}
+async function loadReviewTelemetryEvidence(telemetryPath, options) {
+    if (options.waitForEvidence) {
+        return await waitForReviewTelemetryEvidence(telemetryPath);
+    }
+    return await readReviewTelemetryEvidence(telemetryPath);
+}
+async function waitForReviewTelemetryEvidence(telemetryPath) {
+    const deadline = Date.now() + REVIEW_TELEMETRY_WAIT_TIMEOUT_MS;
+    for (;;) {
+        const telemetry = await readReviewTelemetryEvidence(telemetryPath);
+        if (telemetry) {
+            return telemetry;
+        }
+        if (Date.now() >= deadline) {
+            return null;
+        }
+        await delay(REVIEW_TELEMETRY_POLL_INTERVAL_MS);
+    }
+}
+async function readReviewTelemetryEvidence(telemetryPath) {
+    try {
+        const raw = await readFile(telemetryPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function loadProviderLinearWorkerProof(proofPath) {
+    try {
+        const raw = await readFile(proofPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function buildProviderLinearWorkerManifestTokenUsage(tokens) {
+    if (!tokens || typeof tokens !== 'object') {
+        return null;
+    }
+    const inputTokens = normalizeManifestTokenCount(tokens.input_tokens);
+    const outputTokens = normalizeManifestTokenCount(tokens.output_tokens);
+    const totalTokens = normalizeManifestTokenCount(tokens.total_tokens);
+    const reasoningOutputTokens = normalizeManifestTokenCount(tokens.reasoning_output_tokens);
+    if (inputTokens === null &&
+        outputTokens === null &&
+        totalTokens === null &&
+        reasoningOutputTokens === null) {
+        return null;
+    }
+    const usage = {
+        input_tokens: inputTokens,
+        output_tokens: outputTokens,
+        total_tokens: totalTokens
+    };
+    if (reasoningOutputTokens !== null) {
+        usage.reasoning_output_tokens = reasoningOutputTokens;
+    }
+    return usage;
+}
+function normalizeManifestTokenCount(value) {
+    return typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(0, Math.trunc(value))
+        : null;
+}
+function coerceTelemetryString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function coerceTelemetryStatusValue(value) {
+    if (value === 'succeeded' || value === 'failed') {
+        return value;
+    }
+    return null;
+}
+function coerceReviewOutcomeDisposition(value) {
+    switch (value) {
+        case 'clean-success':
+        case 'bounded-success':
+        case 'failed-boundary':
+        case 'failed-other':
+            return value;
+        default:
+            return null;
+    }
+}
+function hasTelemetryTerminationBoundary(telemetry) {
+    return coerceTelemetryTerminationBoundaryKind(telemetry) !== null;
+}
+function coerceTelemetryTerminationBoundaryKind(telemetry) {
+    if (!telemetry) {
+        return null;
+    }
+    const boundary = telemetry.termination_boundary;
+    if (boundary === null || typeof boundary !== 'object' || Array.isArray(boundary)) {
+        return null;
+    }
+    return coerceTelemetryString(boundary.kind);
+}
+function resolveReviewTelemetryOutcomeDisposition(telemetry) {
+    if (!telemetry) {
+        return null;
+    }
+    const explicitDisposition = coerceReviewOutcomeDisposition(telemetry.review_outcome);
+    const telemetryStatus = coerceTelemetryStatusValue(telemetry.status);
+    if (!telemetryStatus) {
+        return null;
+    }
+    const derivedDisposition = deriveReviewOutcomeDisposition({
+        status: telemetryStatus,
+        terminationBoundary: hasTelemetryTerminationBoundary(telemetry)
+            ? REVIEW_OUTCOME_BOUNDARY_PRESENCE_SENTINEL
+            : null
+    });
+    return explicitDisposition === derivedDisposition ? explicitDisposition : derivedDisposition;
+}
+function formatReviewTelemetryOutcomeSummary(telemetry) {
+    const disposition = resolveReviewTelemetryOutcomeDisposition(telemetry);
+    if (!disposition) {
+        return null;
+    }
+    const boundaryKind = coerceTelemetryTerminationBoundaryKind(telemetry);
+    switch (disposition) {
+        case 'clean-success':
+            return 'review outcome: clean success';
+        case 'bounded-success':
+            return boundaryKind
+                ? `review outcome: bounded success via ${boundaryKind}; not a wrapper failure`
+                : 'review outcome: bounded success with preserved termination boundary; not a wrapper failure';
+        case 'failed-boundary':
+            return boundaryKind
+                ? `review outcome: review-wrapper failure via ${boundaryKind}`
+                : 'review outcome: review-wrapper failure via explicit termination boundary';
+        case 'failed-other':
+            return 'review outcome: review command failed without termination-boundary classification; not an explicit wrapper-boundary failure';
+    }
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function runtimeSessionIdOrNull(value) {
     if (typeof value !== 'string') {
         return null;
@@ -454,9 +1054,12 @@ function streamEvent(writeEvent, event, hooks) {
             break;
     }
 }
-function buildSummary(stage, exitCode, stdout, stderr, signal) {
-    if (stage.summaryHint) {
-        return stage.summaryHint;
+function buildSummary(stage, exitCode, stdout, stderr, signal, options = {}) {
+    if (options.timedOut) {
+        const timeoutLabel = typeof options.timeoutMs === 'number' && Number.isFinite(options.timeoutMs) && options.timeoutMs > 0
+            ? `${Math.trunc(options.timeoutMs)}ms`
+            : 'configured timeout';
+        return `Timed out after ${timeoutLabel}${stderr ? ` — ${truncate(stderr)}` : ''}`;
     }
     if (signal) {
         return `Terminated with signal ${signal}${stderr ? ` — ${truncate(stderr)}` : ''}`;
@@ -464,6 +1067,9 @@ function buildSummary(stage, exitCode, stdout, stderr, signal) {
     if (exitCode !== 0) {
         return `Exited with code ${exitCode}${stderr ? ` — ${truncate(stderr)}` : ''}`;
     }
+    if (stage.summaryHint) {
+        return stage.summaryHint;
+    }
     if (stdout) {
         return truncate(stdout);
     }
@@ -502,9 +1108,15 @@ function parseCollabToolCallLine(line, stageId, commandIndex) {
     if (!item || item.type !== 'collab_tool_call') {
         return null;
     }
-    const receiverThreadIds = Array.isArray(item.receiver_thread_ids)
-        ? item.receiver_thread_ids.filter((entry) => typeof entry === 'string')
-        : [];
+    const receiverThreadIdSlots = parseStringSlots(item.receiver_thread_ids);
+    const receiverThreadIds = receiverThreadIdSlots.filter((entry) => entry !== null);
+    const senderAgentPath = normalizeOptionalString(item.sender_agent_path);
+    const receiverAgentPathSlots = parseStringSlots(item.receiver_agent_paths);
+    const receiverAgentPaths = receiverAgentPathSlots.filter((entry) => entry !== null);
+    const receiverAgents = parseCollabReceiverAgents(item.receiver_agents, {
+        receiverThreadIdSlots,
+        receiverAgentPathSlots
+    });
     return {
         observed_at: isoTimestamp(),
         stage_id: stageId,
@@ -515,6 +1127,13 @@ function parseCollabToolCallLine(line, stageId, commandIndex) {
         status: normalizeCollabStatus(item.status),
         sender_thread_id: typeof item.sender_thread_id === 'string' ? item.sender_thread_id : 'unknown',
         receiver_thread_ids: receiverThreadIds,
+        sender_agent_path: senderAgentPath,
+        receiver_agent_paths: receiverAgentPaths.length > 0
+            ? receiverAgentPaths
+            : receiverAgents
+                ?.map((entry) => entry.agent_path)
+                .filter((entry) => typeof entry === 'string' && entry.length > 0) ?? null,
+        receiver_agents: receiverAgents,
         prompt: typeof item.prompt === 'string' ? item.prompt : null,
         fork_context: typeof item.fork_context === 'boolean' ? item.fork_context : null,
         agents_states: item.agents_states && typeof item.agents_states === 'object'
@@ -522,9 +1141,70 @@ function parseCollabToolCallLine(line, stageId, commandIndex) {
             : null
     };
 }
+function parseStringSlots(value) {
+    return Array.isArray(value) ? value.map((entry) => normalizeOptionalString(entry)) : [];
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function parseCollabReceiverAgents(value, slots = {}) {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    const { receiverThreadIdSlots = [], receiverAgentPathSlots = [] } = slots;
+    const parsed = [];
+    for (const [index, entry] of value.entries()) {
+        if (!entry || typeof entry !== 'object') {
+            continue;
+        }
+        const record = entry;
+        const threadId = normalizeOptionalString(record.thread_id) ?? receiverThreadIdSlots[index] ?? null;
+        const agentNickname = normalizeOptionalString(record.agent_nickname);
+        const agentRole = normalizeOptionalString(record.agent_role);
+        const agentPath = normalizeOptionalString(record.agent_path) ?? receiverAgentPathSlots[index] ?? null;
+        if (!threadId && !agentNickname && !agentRole && !agentPath) {
+            continue;
+        }
+        parsed.push({
+            thread_id: threadId,
+            agent_nickname: agentNickname,
+            agent_role: agentRole,
+            agent_path: agentPath
+        });
+    }
+    return parsed.length > 0 ? parsed : null;
+}
 function normalizeCollabStatus(value) {
     if (value === 'completed' || value === 'failed' || value === 'in_progress') {
         return value;
     }
     return 'in_progress';
 }
+function resolveStageTimeoutMs(stage, env) {
+    const stageTimeout = normalizeTimeoutMs(stage.timeoutMs);
+    if (stageTimeout !== null) {
+        return stageTimeout;
+    }
+    return normalizeTimeoutMs(parseNumber(env.CODEX_ORCHESTRATOR_STAGE_TIMEOUT_MS));
+}
+function parseNumber(value) {
+    if (!value || !value.trim()) {
+        return undefined;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+function normalizeTimeoutMs(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return null;
+    }
+    const normalized = Math.trunc(value);
+    if (normalized <= 0) {
+        return null;
+    }
+    return normalized;
+}