codex-orchestrator 2.0.2 → 2.0.3

package/dist/src/v2/runtime.js

@@ -1,24 +1,33 @@
 import { constants } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
-import { lstat, mkdir, open, readFile, readdir, readlink, realpath } from 'node:fs/promises';
+import { lstat, mkdir, open, readFile, readdir, readlink, realpath, rm } from 'node:fs/promises';
 import { homedir, hostname } from 'node:os';
-import { dirname, isAbsolute, join, posix, resolve } from 'node:path';
+import { dirname, isAbsolute, join, posix, relative, resolve } from 'node:path';
 import { writeDurableAtomicFile } from './adapters/durable-atomic-file.js';
 import { GitWorktreeManager } from './adapters/worktree.js';
 import { defaultProcessExecutor } from './adapters/command.js';
 import { AcceptanceProof, ProofQuiescenceError } from './acceptance-proof.js';
-import { acquireExclusiveJsonFileLock } from './atomic-store.js';
 import { createCheckedChangeCapabilities } from './checked-change.js';
+import { InjectedContainedReportOperation } from './contained-report-operation.js';
+import { ContainedImplementationReviewer } from './implementation-reviewer.js';
 import { parseAgentAutoConfig } from './config.js';
+import { WaitingHumanCoordinator } from './waiting-human-coordinator.js';
 import { canonicalJson, containmentArgvPolicySha256, containmentCertificatePath, parseJsonWithoutDuplicateKeys, readContainmentCertificate, sha256, } from './containment.js';
 import { FileProofRecordWriter } from './proof-store.js';
+import { acquireOwnerControlLock, OwnerControlLockBlockedError } from './owner-control-lock.js';
 import { decodeAgentReportForValidation } from './report-envelope.js';
 import { CodexProcess, ProcessQuiescenceError } from './codex-process.js';
 import { FileAndroidLeaseVerifier, FileIosLeaseVerifier } from './mobile-lease.js';
 import { publishRuntimeAssetSnapshot } from './runtime-assets.js';
-import { OwnerLockSafetyError, RunIssue } from './run-issue.js';
+import { RouteCoordinator } from './route-coordinator.js';
+import { SpecCoordinator } from './spec-coordinator.js';
+import { createSpecRevision } from './spec-delivery.js';
+import { validateCodeReviewDefects } from './code-review-report.js';
+import { hashRouteDecision, validateRouteReceipt } from './route-decision.js';
+import { OwnerLockContentionError, OwnerLockSafetyError, RunIssue } from './run-issue.js';
 import { FileRunRecordWriter } from './run-store.js';
+import { parseWorkflowExecutionProfile, verifyWorkflowGeneration, } from './workflow-assets.js';
 export class LocalGitRunIssueAdapter {
     executor;
     worktrees;
@@ -101,6 +110,14 @@ export class LocalGitRunIssueAdapter {
     listChangedFiles(worktreePath) {
         return this.worktrees.listChangedFiles(worktreePath);
     }
+    async fingerprintChangedFiles(worktreePath, changedFiles) {
+        const root = await realpath(worktreePath);
+        const entries = [];
+        for (const path of [...changedFiles].sort()) {
+            entries.push({ path, fingerprint: await fingerprintRepositoryPath(root, path) });
+        }
+        return sha256(canonicalJson(entries));
+    }
     async stageAll(worktreePath) {
         await this.git(['-C', worktreePath, 'add', '--all']);
     }
@@ -167,13 +184,13 @@ export class ContainedImplementationAgent {
         const canonicalRepository = `${config.github.owner.toLowerCase()}/${config.github.repo.toLowerCase()}`;
         const attemptId = (this.dependencies.createAttemptId ?? randomUUID)();
         const attempt = await prepareContainedAttempt({
-            packageRoot: this.dependencies.packageRoot,
             orchestratorHome: this.dependencies.orchestratorHome,
             canonicalRepository,
             runId: input.runId,
             attemptId,
-            skill: 'agent-auto',
-            expectedPackageVersion: this.dependencies.packageVersion,
+            operationId: 'implementation',
+            workflowGeneration: input.workflowGeneration,
+            bootId: this.dependencies.bootId,
         });
         const baseline = await this.dependencies.git.snapshot(input.worktreePath);
         try {
@@ -188,7 +205,9 @@ export class ContainedImplementationAgent {
                 parentCodexHome: this.dependencies.parentCodexHome,
                 parentEnv: process.env,
                 prompt: [
-                    `Follow the exact skill at ${attempt.skillPath}.`,
+                    `Package profile instructions: ${attempt.profile.developerInstructions}`,
+                    `Follow the exact operation at ${attempt.operationPath}.`,
+                    `The operation's immutable workflow root is ${attempt.workflowRoot}.`,
                     `Implement issue #${input.issue.number}: ${input.issue.title}`,
                     `Implementation cycle: ${input.cycle}.`,
                     `Frozen acceptance criteria: ${canonicalJson(input.frozenCriteria)}`,
@@ -198,6 +217,8 @@ export class ContainedImplementationAgent {
                 ].join('\n'),
                 timeoutMs: config.codex.timeoutMs,
                 idleTimeoutMs: config.codex.idleTimeoutMs,
+                operationPolicy: attempt.policy,
+                executionProfile: attempt.profile,
             }, input.signal);
             if (result.kind === 'cancelled')
                 return { kind: 'cancelled' };
@@ -208,6 +229,7 @@ export class ContainedImplementationAgent {
                 return { kind: 'internal-error' };
             return {
                 kind: 'completed',
+                attemptId,
                 report: decodeAgentReportForValidation(result.report.bytes),
             };
         }
@@ -233,20 +255,22 @@ export class ContainedProofAgent {
         this.dependencies = dependencies;
     }
     async run(input) {
+        if (!input.workflowGeneration)
+            throw new Error('proof workflow generation is required');
         const config = this.dependencies.config();
         const canonicalRepository = `${config.github.owner.toLowerCase()}/${config.github.repo.toLowerCase()}`;
         const worktreePath = resolve(this.dependencies.targetRoot, config.runner.workspaceRoot, `issue-${input.issue.number}`);
         const attempt = await prepareContainedAttempt({
-            packageRoot: this.dependencies.packageRoot,
             orchestratorHome: this.dependencies.orchestratorHome,
             canonicalRepository,
             runId: input.runId,
             attemptId: (this.dependencies.createAttemptId ?? randomUUID)(),
-            skill: 'acceptance-proof',
-            expectedPackageVersion: this.dependencies.packageVersion,
+            operationId: 'acceptance-proof',
+            workflowGeneration: input.workflowGeneration,
+            bootId: this.dependencies.bootId,
         });
         const artifactRoot = resolve(worktreePath, config.proof.artifactDir);
-        const snapshotRoot = dirname(attempt.skillPath);
+        const snapshotRoot = dirname(attempt.sourceSkillPath ?? attempt.operationPath);
         const androidLeaseRoot = join(resolve(this.dependencies.orchestratorHome), 'v2', sha256(canonicalRepository), 'leases');
         const androidLeaseArtifact = join(artifactRoot, input.proofId, 'android-lease.json');
         const iosLeaseRoot = join(resolve(this.dependencies.orchestratorHome), 'v2', sha256(canonicalRepository), 'leases');
@@ -265,7 +289,9 @@ export class ContainedProofAgent {
                 parentCodexHome: this.dependencies.parentCodexHome,
                 parentEnv: process.env,
                 prompt: [
-                    `Follow the exact skill at ${attempt.skillPath}.`,
+                    `Package profile instructions: ${attempt.profile.developerInstructions}`,
+                    `Follow the exact operation at ${attempt.operationPath}.`,
+                    `The operation's immutable workflow root is ${attempt.workflowRoot}.`,
                     `Independently prove issue #${input.issue.number}.`,
                     `Frozen acceptance criteria: ${canonicalJson(input.frozenCriteria)}`,
                     `Checked change digest: ${input.checkedChangeSha256}.`,
@@ -296,6 +322,8 @@ export class ContainedProofAgent {
                 ].join('\n'),
                 timeoutMs: config.codex.timeoutMs,
                 idleTimeoutMs: config.codex.idleTimeoutMs,
+                operationPolicy: attempt.policy,
+                executionProfile: attempt.profile,
             }, input.signal);
             if (result.kind === 'cancelled')
                 return { kind: 'cancelled' };
@@ -339,11 +367,10 @@ export function createV2Runtime(input) {
     const iosXcrunPath = resolve(input.iosXcrunPath ?? '/usr/bin/xcrun');
     const containedDependencies = () => ({
         config: () => requireConfig(currentConfig),
-        packageRoot: requireRuntimeString(input.packageRoot, 'packageRoot'),
         orchestratorHome,
         parentCodexHome: requireRuntimeString(input.parentCodexHome, 'parentCodexHome'),
         safePath: requireRuntimeString(input.safePath, 'safePath'),
-        packageVersion: input.packageVersion,
+        bootId: input.bootId,
         process: containedProcess,
         createAttemptId: input.createAttemptId,
     });
@@ -359,6 +386,292 @@ export function createV2Runtime(input) {
         iosXcrunPath,
         processExecutor: commandExecutor,
     });
+    const reportOperation = new InjectedContainedReportOperation({
+        prepare: async ({ operation, attemptId, runId, workflowGeneration }) => ({
+            operation,
+            generationHash: workflowGeneration.generationHash,
+            ...await prepareContainedAttempt({
+                orchestratorHome,
+                canonicalRepository: requireCanonicalRepository(currentConfig),
+                runId,
+                attemptId,
+                operationId: operation,
+                workflowGeneration,
+                bootId: input.bootId,
+            }),
+        }),
+        snapshot: (worktreePath) => git.snapshot(worktreePath),
+        launch: async ({ attempt, worktreePath, promptFacts, signal, onLaunched }) => {
+            const config = requireConfig(currentConfig);
+            if (!attempt.schemaPath || !attempt.reportPath || !attempt.toolHome || !attempt.tmpDir
+                || !attempt.profile || !attempt.operationPath || !attempt.workflowRoot) {
+                return { status: 'blocked', kind: 'safety', code: 'report-operation-attempt-incomplete' };
+            }
+            let readView;
+            try {
+                readView = await materializeReportReadView({
+                    worktreePath,
+                    destination: join(dirname(attempt.tmpDir), 'read-view'),
+                    deniedPaths: config.deny.readPaths,
+                });
+            }
+            catch {
+                return { status: 'blocked', kind: 'safety', code: 'report-operation-read-view-failed' };
+            }
+            let result;
+            let cleanupAfterSafeHalt = false;
+            try {
+                result = await containedProcess.run({
+                    codexPath: config.codex.command,
+                    cwd: readView,
+                    schemaPath: attempt.schemaPath,
+                    reportPath: attempt.reportPath,
+                    toolHome: attempt.toolHome,
+                    tmpDir: attempt.tmpDir,
+                    safePath: requireRuntimeString(input.safePath, 'safePath'),
+                    parentCodexHome: requireRuntimeString(input.parentCodexHome, 'parentCodexHome'),
+                    parentEnv: process.env,
+                    prompt: [
+                        `Package profile instructions: ${attempt.profile.developerInstructions}`,
+                        `Follow the exact operation at ${attempt.operationPath}.`,
+                        `The operation's immutable workflow root is ${attempt.workflowRoot}.`,
+                        `Runner-provided facts: ${canonicalJson(promptFacts)}`,
+                        'This is a read-only, report-only operation. Do not edit files or external state, use network or MCP tools, or request additional authority.',
+                        'Do not read .env or any .env* file. The runner has removed repository credential paths from this read view.',
+                    ].join('\n'),
+                    timeoutMs: config.codex.timeoutMs,
+                    idleTimeoutMs: config.codex.idleTimeoutMs,
+                    operationPolicy: attempt.policy,
+                    executionProfile: attempt.profile,
+                    ...(onLaunched ? { onSpawned: onLaunched } : {}),
+                }, signal);
+            }
+            catch (error) {
+                if (error instanceof ProcessQuiescenceError) {
+                    cleanupAfterSafeHalt = true;
+                    return {
+                        status: 'safe-halt',
+                        pid: error.pid,
+                        processGroupId: error.processGroupId,
+                        startedAt: now(),
+                        waitForAbsence: async () => {
+                            await waitForProcessGroupAbsent(error.processGroupId);
+                            await rm(readView, { recursive: true, force: true });
+                        },
+                    };
+                }
+                throw error;
+            }
+            finally {
+                if (!cleanupAfterSafeHalt)
+                    await rm(readView, { recursive: true, force: true });
+            }
+            if (result.kind === 'cancelled')
+                return { status: 'cancelled' };
+            if (result.kind === 'launch-gate-failed') {
+                return { status: 'blocked', kind: 'safety', code: 'review-operation-launch-persistence-failed' };
+            }
+            if (['spawn-failed', 'transport-failed', 'timeout', 'idle-timeout'].includes(result.kind)) {
+                return { status: 'retryable', code: `report-operation-${result.kind}` };
+            }
+            if (result.kind !== 'completed' || result.report.kind !== 'available') {
+                return { status: 'blocked', kind: 'external', code: 'report-operation-report-unavailable' };
+            }
+            return { status: 'completed', reportBytes: result.report.bytes };
+        },
+    });
+    const implementationReviewer = new ContainedImplementationReviewer({
+        operation: reportOperation,
+        createAttemptId: input.createAttemptId ?? randomUUID,
+    });
+    const createAttemptId = input.createAttemptId ?? randomUUID;
+    const specOperation = {
+        author: async ({ context, state, mode, signal, onPrepared, onLaunched }) => {
+            const attemptId = createAttemptId();
+            const sessionId = state.authorSessionId ?? randomUUID();
+            let attempt;
+            try {
+                attempt = await prepareContainedAttempt({
+                    orchestratorHome, canonicalRepository: requireCanonicalRepository(currentConfig), runId: context.runId,
+                    attemptId, operationId: 'spec-author', workflowGeneration: context.workflowGeneration, bootId: input.bootId,
+                });
+                const revisionPath = join(dirname(attempt.reportPath), `revision-${state.revisions.length + 1}.md`);
+                await onPrepared({ attemptId, sessionId, reportPath: attempt.reportPath, revisionPath });
+                const config = requireConfig(currentConfig);
+                const result = await containedProcess.run({
+                    codexPath: config.codex.command, cwd: dirname(attempt.reportPath), schemaPath: attempt.schemaPath,
+                    reportPath: attempt.reportPath, toolHome: attempt.toolHome, tmpDir: attempt.tmpDir,
+                    safePath: requireRuntimeString(input.safePath, 'safePath'), parentCodexHome: requireRuntimeString(input.parentCodexHome, 'parentCodexHome'),
+                    parentEnv: process.env, timeoutMs: config.codex.timeoutMs, idleTimeoutMs: config.codex.idleTimeoutMs,
+                    operationPolicy: attempt.policy, executionProfile: attempt.profile,
+                    onSpawned: ({ pid, processGroupId }) => onLaunched({ attemptId, sessionId, pid, processGroupId }),
+                    prompt: [
+                        `Package profile instructions: ${attempt.profile.developerInstructions}`,
+                        `Follow the exact operation at ${attempt.operationPath}.`,
+                        `The immutable workflow root is ${attempt.workflowRoot}.`,
+                        `Author mode: ${mode}. Issue authority: ${canonicalJson(context.issue)}.`,
+                        `Frozen criteria: ${canonicalJson(context.frozenCriteria)}.`,
+                        `Prior revisions and review state: ${canonicalJson({ revisions: state.revisions, review: state.review })}.`,
+                        `Write the complete new immutable revision only to ${revisionPath}. Return that exact absolute path and its SHA-256 in the report.`,
+                        'Do not modify the product worktree, prior revisions, external state, or any .env file.',
+                    ].join('\n'),
+                }, signal);
+                if (result.kind === 'cancelled')
+                    return { status: 'cancelled' };
+                if (['spawn-failed', 'transport-failed', 'timeout', 'idle-timeout'].includes(result.kind))
+                    return { status: 'retryable', code: `spec-author-${result.kind}` };
+                if (result.kind !== 'completed' || result.report.kind !== 'available')
+                    return { status: 'retryable', code: 'spec-author-report-invalid' };
+                const report = decodeAgentReportForValidation(result.report.bytes);
+                if (report.status !== 'ready' || report.specPath !== revisionPath || report.specSha256 === null)
+                    return { status: 'retryable', code: 'spec-author-report-invalid' };
+                const content = await readRegularFile(revisionPath);
+                if (report.specSha256 !== sha256(content))
+                    return { status: 'retryable', code: 'spec-author-report-invalid' };
+                const previous = state.revisions.at(-1) ?? null;
+                return { status: 'completed', value: createSpecRevision({
+                        revision: state.revisions.length + 1, path: revisionPath, content: content.toString('utf8'),
+                        evidence: [{ path: context.issue.url, sha256: sha256(canonicalJson(context.issue)), description: 'Frozen issue authority' }],
+                        author: { attemptId, sessionId }, previousRevision: previous,
+                    }) };
+            }
+            catch (error) {
+                if (error instanceof ProcessQuiescenceError) {
+                    try {
+                        await waitForProcessGroupAbsent(error.processGroupId);
+                        return { status: 'retryable', code: 'spec-author-process-quiescence' };
+                    }
+                    catch {
+                        return { status: 'blocked', kind: 'safety', code: 'spec-author-process-absence-unconfirmed' };
+                    }
+                }
+                return { status: 'retryable', code: 'spec-author-report-invalid' };
+            }
+        },
+        review: async ({ context, state, mode, signal, onPrepared, onLaunched }) => {
+            const attemptId = createAttemptId();
+            const sessionId = state.review.reviewer?.sessionId ?? randomUUID();
+            try {
+                const attempt = await prepareContainedAttempt({
+                    orchestratorHome, canonicalRepository: requireCanonicalRepository(currentConfig), runId: context.runId,
+                    attemptId, operationId: 'spec-review', workflowGeneration: context.workflowGeneration, bootId: input.bootId,
+                });
+                await onPrepared({ attemptId, sessionId, reportPath: attempt.reportPath });
+                const config = requireConfig(currentConfig);
+                const result = await containedProcess.run({
+                    codexPath: config.codex.command, cwd: context.worktreePath, schemaPath: attempt.schemaPath,
+                    reportPath: attempt.reportPath, toolHome: attempt.toolHome, tmpDir: attempt.tmpDir,
+                    safePath: requireRuntimeString(input.safePath, 'safePath'), parentCodexHome: requireRuntimeString(input.parentCodexHome, 'parentCodexHome'),
+                    parentEnv: process.env, timeoutMs: config.codex.timeoutMs, idleTimeoutMs: config.codex.idleTimeoutMs,
+                    operationPolicy: attempt.policy, executionProfile: attempt.profile,
+                    onSpawned: ({ pid, processGroupId }) => onLaunched({ attemptId, sessionId, pid, processGroupId }),
+                    prompt: [
+                        `Package profile instructions: ${attempt.profile.developerInstructions}`,
+                        `Follow the exact operation at ${attempt.operationPath}.`,
+                        `Reviewer session ID: ${sessionId}. Review mode: ${mode}.`,
+                        `Issue authority and frozen criteria: ${canonicalJson({ issue: context.issue, frozenCriteria: context.frozenCriteria })}.`,
+                        `Immutable spec delivery state: ${canonicalJson(state)}.`,
+                        'Return only the package spec-review report. Do not edit files or external state.',
+                    ].join('\n'),
+                }, signal);
+                if (result.kind === 'cancelled')
+                    return { status: 'cancelled' };
+                if (['spawn-failed', 'transport-failed', 'timeout', 'idle-timeout'].includes(result.kind))
+                    return { status: 'retryable', code: `spec-review-${result.kind}` };
+                if (result.kind !== 'completed' || result.report.kind !== 'available')
+                    return { status: 'retryable', code: 'spec-review-report-invalid' };
+                const raw = decodeAgentReportForValidation(result.report.bytes);
+                if (raw.mode !== mode || raw.reviewerSessionId !== sessionId || !Array.isArray(raw.coverage) || !Array.isArray(raw.defects)
+                    || !Array.isArray(raw.affectedDefectIds) || !Array.isArray(raw.affectedContracts) || !Array.isArray(raw.acceptedRisks)
+                    || typeof raw.coverageInvalidated !== 'boolean'
+                    || !['approved', 'needs-work', 'rejected'].includes(raw.verdict))
+                    return { status: 'retryable', code: 'spec-review-report-invalid' };
+                const target = state.revisions.at(-1);
+                const defects = validateCodeReviewDefects(raw.defects, target.revision);
+                const report = {
+                    version: 1, targetRevision: target.revision, targetSha256: target.revisionSha256, mode,
+                    verdict: raw.verdict, reviewer: { attemptId, sessionId },
+                    coverage: raw.coverage, defects,
+                    affectedDefectIds: raw.affectedDefectIds,
+                    affectedContracts: raw.affectedContracts,
+                    closureRequestSha256: mode === 'closure' ? state.review.closureRequestSha256 : null,
+                    acceptedRisks: [], coverageInvalidated: raw.coverageInvalidated,
+                };
+                return { status: 'completed', value: report, reportSha256: sha256(result.report.bytes) };
+            }
+            catch (error) {
+                if (error instanceof ProcessQuiescenceError) {
+                    try {
+                        await waitForProcessGroupAbsent(error.processGroupId);
+                        return { status: 'retryable', code: 'spec-review-process-quiescence' };
+                    }
+                    catch {
+                        return { status: 'blocked', kind: 'safety', code: 'spec-review-process-absence-unconfirmed' };
+                    }
+                }
+                return { status: 'retryable', code: 'spec-review-report-invalid' };
+            }
+        },
+        recover: async ({ context, state, signal }) => {
+            const invocation = state.invocation;
+            if (!invocation || signal.aborted)
+                return signal.aborted ? { status: 'cancelled' } : { status: 'blocked', kind: 'safety', code: 'spec-recovery-invocation-missing' };
+            if (invocation.status === 'launched') {
+                try {
+                    await waitForProcessGroupAbsent(invocation.processGroupId);
+                }
+                catch {
+                    return { status: 'blocked', kind: 'safety', code: 'spec-process-absence-unconfirmed' };
+                }
+            }
+            if (!invocation.reportPath)
+                return { status: 'retryable', code: `spec-${invocation.purpose}-transport-recovery` };
+            let reportBytes;
+            try {
+                reportBytes = await readRegularFile(invocation.reportPath);
+            }
+            catch {
+                return { status: 'retryable', code: `spec-${invocation.purpose}-transport-recovery` };
+            }
+            if (invocation.purpose === 'author') {
+                if (!invocation.revisionPath)
+                    return { status: 'retryable', code: 'spec-author-report-invalid' };
+                try {
+                    const raw = decodeAgentReportForValidation(reportBytes);
+                    const content = await readRegularFile(invocation.revisionPath);
+                    if (raw.status !== 'ready' || raw.specPath !== invocation.revisionPath || raw.specSha256 !== sha256(content))
+                        return { status: 'retryable', code: 'spec-author-report-invalid' };
+                    return { status: 'completed', value: createSpecRevision({
+                            revision: state.revisions.length + 1, path: invocation.revisionPath, content: content.toString('utf8'),
+                            evidence: [{ path: context.issue.url, sha256: sha256(canonicalJson(context.issue)), description: 'Frozen issue authority' }],
+                            author: { attemptId: invocation.attemptId, sessionId: invocation.sessionId }, previousRevision: state.revisions.at(-1) ?? null,
+                        }) };
+                }
+                catch {
+                    return { status: 'retryable', code: 'spec-author-report-invalid' };
+                }
+            }
+            try {
+                const raw = decodeAgentReportForValidation(reportBytes);
+                if (raw.mode !== invocation.mode || raw.reviewerSessionId !== invocation.sessionId || !Array.isArray(raw.coverage)
+                    || !Array.isArray(raw.defects) || !Array.isArray(raw.affectedDefectIds) || !Array.isArray(raw.affectedContracts)
+                    || typeof raw.coverageInvalidated !== 'boolean' || !['approved', 'needs-work', 'rejected'].includes(raw.verdict)) {
+                    return { status: 'retryable', code: 'spec-review-report-invalid' };
+                }
+                const defects = validateCodeReviewDefects(raw.defects, invocation.targetRevision);
+                return { status: 'completed', reportSha256: sha256(reportBytes), value: {
+                        version: 1, targetRevision: invocation.targetRevision, targetSha256: invocation.targetSha256,
+                        mode: invocation.mode, verdict: raw.verdict,
+                        reviewer: { attemptId: invocation.attemptId, sessionId: invocation.sessionId }, coverage: raw.coverage, defects,
+                        affectedDefectIds: raw.affectedDefectIds, affectedContracts: raw.affectedContracts,
+                        closureRequestSha256: invocation.closureRequestSha256, acceptedRisks: [], coverageInvalidated: raw.coverageInvalidated,
+                    } };
+            }
+            catch {
+                return { status: 'retryable', code: 'spec-review-report-invalid' };
+            }
+        },
+    };
     const readConfig = async (requestedRoot) => {
         if (resolve(requestedRoot) !== targetRoot)
             throw new Error('runtime target root mismatch');
@@ -475,7 +788,7 @@ export function createV2Runtime(input) {
                     removeLabels: current.filter((label) => !labels.includes(label)),
                 });
             },
-            postComment: (issueNumber, body) => input.issues.postComment(issueNumber, body),
+            postComment: async (issueNumber, body) => { await input.issues.postComment(issueNumber, body); },
         },
         pullRequests: {
             findOpen: async ({ headBranch, baseBranch }) => {
@@ -489,7 +802,51 @@ export function createV2Runtime(input) {
             createDraft: async ({ title, body, headBranch, baseBranch }) => input.pullRequests.createDraftPullRequest({ title, body, headBranch, baseBranch }),
         },
         git,
+        routeCoordinator: {
+            run: ({ state, ...routeInput }) => new RouteCoordinator({
+                state,
+                operation: reportOperation,
+                createAttemptId: input.createAttemptId ?? randomUUID,
+                now,
+                createReceipt: ({ artifact, triage, review, decidedAt }) => {
+                    if (artifact.status === 'blocked')
+                        throw new Error('blocked triage cannot create a route receipt');
+                    const receipt = {
+                        version: 1,
+                        route: artifact.status,
+                        triage,
+                        review,
+                        artifact,
+                        decisionSha256: '',
+                        decidedAt,
+                        assumptions: [...artifact.assumptions],
+                    };
+                    receipt.decisionSha256 = hashRouteDecision(receipt);
+                    return validateRouteReceipt(receipt, triage.generationHash);
+                },
+            }).run(routeInput),
+        },
+        routeContinuations: {
+            direct: async () => ({ status: 'completed' }),
+            specRequired: (context, state, signal) => new SpecCoordinator({ state, operation: specOperation }).run(context, signal),
+            awaitingUser: async (context, state, signal) => {
+                const config = requireConfig(currentConfig);
+                return new WaitingHumanCoordinator({
+                    issues: input.issues,
+                    labels: {
+                        auto: config.github.labels.auto.name,
+                        running: config.github.labels.running.name,
+                        blocked: config.github.labels.blocked.name,
+                        review: config.github.labels.review.name,
+                        waitingHuman: config.github.labels.waitingHuman.name,
+                    },
+                    now,
+                }).run(context, state, signal);
+            },
+        },
         implementationAgent,
+        implementationReviewer,
+        waitForReviewProcessAbsence: waitForProcessGroupAbsent,
         checks: {
             run: async ({ command, cwd, signal }) => runShellCheck(command, cwd, signal),
         },
@@ -503,9 +860,11 @@ export function createV2Runtime(input) {
             return { id: `evidence:${runId}:${code}`, path: relativePath };
         },
         packageVersion: input.packageVersion,
-        skillHashes: structuredClone(input.skillHashes),
+        createWorkflowGeneration: input.createWorkflowGeneration,
+        verifyWorkflowGeneration,
         createRunId: input.createRunId ?? randomUUID,
         createProofId: input.createProofId ?? randomUUID,
+        createReviewSessionId: input.createAttemptId ?? randomUUID,
         now,
         signal: controller.signal,
     });
@@ -522,48 +881,27 @@ export function createV2Runtime(input) {
     };
 }
 async function acquireOwnerLock(input) {
-    const token = randomUUID();
-    const host = hostname();
-    const record = {
-        version: 1,
-        token,
-        canonicalRepository: input.canonicalRepository,
-        host,
-        bootId: input.bootId,
-        pid: process.pid,
-        acquiredAt: input.now(),
-    };
-    const repoKey = sha256(input.canonicalRepository);
     try {
-        return await acquireExclusiveJsonFileLock({
-            path: join(input.orchestratorHome, 'v2', 'owners', `${repoKey}.lock`),
-            record,
-            token,
-            parse: parseOwnerLock,
-            tokenOf: (value) => value.token,
-            classifyExisting: (value) => value.host === host && value.bootId === input.bootId && input.processAlive(value.pid) ? 'wait' : 'block',
+        return await acquireOwnerControlLock({
+            orchestratorHome: input.orchestratorHome,
+            canonicalRepository: input.canonicalRepository,
+            bootId: input.bootId,
+            host: hostname(),
+            pid: process.pid,
+            now: input.now,
+            createToken: randomUUID,
+            processAlive: input.processAlive,
         });
     }
     catch (error) {
-        if (error instanceof Error && /lock (?:owner|record|wait)/u.test(error.message))
+        if (error instanceof OwnerControlLockBlockedError) {
+            if (error.kind === 'live-contention')
+                throw new OwnerLockContentionError(error.message);
             throw new OwnerLockSafetyError(error.message);
+        }
         throw error;
     }
 }
-function parseOwnerLock(value) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value))
-        throw new Error('owner lock is invalid');
-    const keys = Object.keys(value).sort();
-    const expected = ['version', 'token', 'canonicalRepository', 'host', 'bootId', 'pid', 'acquiredAt'].sort();
-    if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index]))
-        throw new Error('owner lock keys are invalid');
-    const record = value;
-    if (record.version !== 1 || !record.token || !record.canonicalRepository || !record.host || !record.bootId
-        || !Number.isSafeInteger(record.pid) || record.pid <= 0 || Number.isNaN(Date.parse(record.acquiredAt))) {
-        throw new Error('owner lock fields are invalid');
-    }
-    return record;
-}
 async function readRegularFile(path) {
     const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
@@ -647,6 +985,10 @@ function requireConfig(config) {
         throw new Error('runtime config is unavailable');
     return config;
 }
+function requireCanonicalRepository(config) {
+    const value = requireConfig(config);
+    return `${value.github.owner.toLowerCase()}/${value.github.repo.toLowerCase()}`;
+}
 function requireRuntimeString(value, field) {
     if (!value)
         throw new Error(`${field} is required for contained Codex agents`);
@@ -721,13 +1063,28 @@ async function prepareContainedAttempt(input) {
     const runtimeRoot = join(resolve(input.orchestratorHome), 'v2', sha256(input.canonicalRepository));
     const attemptRelativePath = `runs/${input.runId}/attempts/${input.attemptId}`;
     const snapshot = await publishRuntimeAssetSnapshot({
-        packageRoot: resolve(input.packageRoot),
+        workflowGeneration: input.workflowGeneration,
         runtimeRoot,
         snapshotRelativePath: `${attemptRelativePath}/snapshot`,
-        skill: input.skill,
+        operation: input.operationId,
+        bootId: input.bootId,
     });
-    if (snapshot.packageVersion !== input.expectedPackageVersion)
-        throw new Error('runtime asset package version mismatch');
+    const reportOnly = input.operationId === 'triage' || input.operationId === 'ambiguity-review'
+        || input.operationId === 'cleanup-review' || input.operationId === 'code-review' || input.operationId === 'spec-review';
+    if ((reportOnly
+        ? snapshot.policy.sandboxMode !== 'read-only'
+            || snapshot.policy.worktreeAccess !== 'read-only'
+            || snapshot.policy.runnerPostcondition !== 'report-only'
+            || snapshot.policy.writableRootClasses.length !== 0
+        : snapshot.policy.sandboxMode !== 'workspace-write')
+        || snapshot.policy.approvalCeiling !== 'never'
+        || snapshot.policy.network !== 'deny'
+        || snapshot.policy.networkHosts.length !== 0
+        || snapshot.policy.mcpTools.length !== 0
+        || snapshot.policy.externalWrite !== false) {
+        throw new Error(`workflow operation policy exceeds containment: ${input.operationId}`);
+    }
+    const profile = parseWorkflowExecutionProfile(await readFile(snapshot.profilePath, 'utf8'), snapshot.policy);
     const attemptRoot = join(runtimeRoot, attemptRelativePath);
     const toolHome = join(attemptRoot, 'tool-home');
     const tmpDir = join(attemptRoot, 'tmp');
@@ -740,11 +1097,15 @@ async function prepareContainedAttempt(input) {
             throw error;
     });
     return {
-        skillPath: snapshot.skillPath,
+        workflowRoot: snapshot.snapshotRoot,
+        operationPath: snapshot.operationPath,
+        sourceSkillPath: snapshot.sourceSkillPath,
         schemaPath: snapshot.schemaPath,
         reportPath: join(attemptRoot, 'report.json'),
         toolHome,
         tmpDir,
+        policy: structuredClone(snapshot.policy),
+        profile,
     };
 }
 async function artifactInventory(root, logicalRoot) {
@@ -832,6 +1193,67 @@ async function waitForProcessGroupAbsent(processGroupId) {
         await new Promise((resolveWait) => setTimeout(resolveWait, 1_000));
     }
 }
+export async function materializeReportReadView(input) {
+    await rm(input.destination, { recursive: true, force: true });
+    await mkdir(input.destination, { recursive: true, mode: 0o700 });
+    await extractHeadArchive(input.worktreePath, input.destination);
+    for (const relativePath of input.deniedPaths) {
+        if (isAbsolute(relativePath))
+            continue;
+        const deniedPath = resolve(input.destination, relativePath);
+        const contained = relative(input.destination, deniedPath);
+        if (contained === '' || contained === '..' || contained.startsWith('../') || isAbsolute(contained)) {
+            throw new Error('report read-view denied path escapes destination');
+        }
+        await rm(deniedPath, { recursive: true, force: true });
+    }
+    await scrubReportReadView(input.destination);
+    return input.destination;
+}
+async function extractHeadArchive(worktreePath, destination) {
+    await new Promise((resolveExtract, reject) => {
+        const archive = spawn('git', ['-C', worktreePath, 'archive', '--format=tar', 'HEAD'], { stdio: ['ignore', 'pipe', 'pipe'] });
+        const extract = spawn('tar', ['-xf', '-', '-C', destination], { stdio: ['pipe', 'ignore', 'pipe'] });
+        const failures = [];
+        archive.once('error', reject);
+        extract.once('error', reject);
+        archive.stderr.on('data', (chunk) => {
+            if (failures.join('').length < 8 * 1024)
+                failures.push(chunk.toString('utf8'));
+        });
+        extract.stderr.on('data', (chunk) => {
+            if (failures.join('').length < 8 * 1024)
+                failures.push(chunk.toString('utf8'));
+        });
+        archive.stdout.pipe(extract.stdin);
+        let archiveCode = null;
+        let extractCode = null;
+        const settle = () => {
+            if (archiveCode === null || extractCode === null)
+                return;
+            if (archiveCode !== 0 || extractCode !== 0)
+                reject(new Error(`report read-view archive failed: ${failures.join('').slice(0, 8 * 1024)}`));
+            else
+                resolveExtract();
+        };
+        archive.once('close', (code) => { archiveCode = code ?? 1; settle(); });
+        extract.once('close', (code) => { extractCode = code ?? 1; settle(); });
+    });
+}
+async function scrubReportReadView(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.name === '.env' || entry.name.startsWith('.env.') || entry.isSymbolicLink()) {
+            await rm(path, { recursive: true, force: true });
+        }
+        else if (entry.isDirectory()) {
+            await scrubReportReadView(path);
+        }
+        else if (!entry.isFile()) {
+            await rm(path, { recursive: true, force: true });
+        }
+    }
+}
 function isErrorCode(error, code) {
     return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
 }