codex-orchestrator 0.1.40 → 0.1.42

package/dist/src/runner/plan-auto-command.js

@@ -1,11 +1,11 @@
 import { mkdir, readFile } from 'node:fs/promises';
+import { hostname as osHostname } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { CodexCommandAdapter } from '../codex/command-adapter.js';
 import { resolveBaseBranch } from '../git/base-branch.js';
 import { GitMergeConflictError, GitWorktreeManager, renderBranchTemplate } from '../git/worktree.js';
 import { GhCliIssueAdapter } from '../github/gh-issue-adapter.js';
 import { GhCliPullRequestAdapter } from '../github/gh-pull-request-adapter.js';
-import { verifyPullRequestRefs } from '../github/pull-requests.js';
 import { defaultShellCommandExecutor } from '../process/command.js';
 import { formatSessionTimestamp, readRunnerConfig, runConfiguredChecks, } from './command-utils.js';
 import { buildChildBlockedReport, buildChildReviewReport, buildIssueTreePullRequestBody, buildIssueTreeReviewReport, buildParentBlockedReport, } from './handoff-evidence.js';
@@ -15,15 +15,16 @@ import { writeContextSnapshot } from './context-snapshot.js';
 import { readPlanAutoCompletionReport, } from './completion-report.js';
 import { claimIssue, discoverIssueWork } from './issue-state-machine.js';
 import { collectExecutableChildBatches, persistAutonomousChildNode, readAutonomousChildNodes, topologicalPlanNodes, } from './issue-tree.js';
-import { runImplementationPublishabilityCheck } from './local-execution-session.js';
 import { RunnerLifecycleEventStore } from './lifecycle-events.js';
 import { RunnerStateStore } from './local-state.js';
+import { classifyPlanAutoBlockedChildRecovery, classifyPlanAutoCompletedChildRecovery, classifyPlanAutoParentRecovery, } from './plan-auto-recovery.js';
 import { buildIssueTreeChildPrompt, buildPlanAutoPrompt, sessionPromptPath, sessionReportPath, writeDurablePrompt, } from './prompt.js';
-import { decideImplementationRework } from './rework-policy.js';
+import { runAgentAttemptLoop } from './agent-attempt.js';
 import { evaluateParentRiskRoutingGate } from './review-gates.js';
 import { buildBlockedHandoffEvidence, buildPromotionAsBlockedHandoffEvidence, buildReviewReadyHandoffEvidence, } from './runner-handoff-decision.js';
 import { sessionLogPath } from './run-log.js';
 import { cleanupSessionCodexHome, sessionCodexHomePath } from './session-home.js';
+import { finishBlockedTerminalOutcome, finishReviewReadyCommentTerminalOutcome, finishReviewReadyTerminalOutcome, } from './terminal-outcome.js';
 class ChildExecutionBlockedError extends Error {
     durableRunSummary;
     freshContextReview;
@@ -51,16 +52,36 @@ export async function runPlanAutoCommand(options) {
     if (!parentIssue) {
         throw new Error(`Issue #${options.issueNumber} was not found`);
     }
+    const branchName = renderBranchTemplate(config.branches.issueTree, { parentIssueNumber: options.issueNumber });
+    const worktreePath = join(targetRoot, config.runner.workspaceRoot, `tree-${options.issueNumber}`);
+    const store = new RunnerStateStore(targetRoot, config);
+    const parentRecovery = await classifyPlanAutoParentRecovery({
+        targetRoot,
+        config,
+        parentIssue,
+        branchName,
+        worktreePath,
+        baseSha: resolvedBase.sha,
+        state: await store.load(),
+        git,
+        now,
+        hostname: options.hostname,
+        processProbe: options.processProbe,
+    });
     const decision = discoverIssueWork([parentIssue], config)[0];
-    if (!decision || decision.kind !== 'eligible' || decision.mode !== 'plan-parent') {
+    const parentLabels = new Set(parentIssue.labels.map((label) => label.name));
+    const alreadyRunningPlanParent = decision?.kind === 'skipped'
+        && decision.reasonCode === 'already-running'
+        && parentIssue.state === 'OPEN'
+        && parentLabels.has(config.github.labels.planAuto.name)
+        && !parentLabels.has(config.github.labels.child.name);
+    if (!decision || !((decision.kind === 'eligible' && decision.mode === 'plan-parent') || alreadyRunningPlanParent)) {
         const reason = decision?.kind === 'skipped' ? decision.reason : 'not agent:plan-auto';
         throw new Error(`Issue #${options.issueNumber} is not eligible for agent:plan-auto planning: ${reason}`);
     }
     const workflowPrompts = await readPlanWorkflowPrompts(targetRoot, config);
     const issueTreeWorkflowPrompt = await readIssueTreeWorkflowPrompt(targetRoot, config);
     const acceptanceProofWorkflowPrompt = await readAcceptanceProofWorkflowPrompt(targetRoot, config);
-    const branchName = renderBranchTemplate(config.branches.issueTree, { parentIssueNumber: options.issueNumber });
-    const worktreePath = join(targetRoot, config.runner.workspaceRoot, `tree-${options.issueNumber}`);
     let promptPath = '';
     let reportPath = '';
     let logPath = '';
@@ -68,19 +89,38 @@ export async function runPlanAutoCommand(options) {
     let parentSnapshotPath = '';
     const childIssues = [];
     let pullRequest;
-    let store;
     const executionResults = [];
     const events = new RunnerLifecycleEventStore(targetRoot, config);
     const buildBase = () => baseResult(options.issueNumber, branchName, worktreePath, promptPath, reportPath, logPath, childIssues, sessionId, parentSnapshotPath);
-    await claimIssue(issueAdapter, config, options.issueNumber, 'plan-parent', now);
+    if (parentRecovery.kind === 'hard-block') {
+        return finishPlanBlocked(issueAdapter, config, events, buildBase(), [parentRecovery.reason], childIssues, parentRecovery.marker);
+    }
+    if (alreadyRunningPlanParent && parentRecovery.kind !== 'resume-parent') {
+        return finishPlanBlocked(issueAdapter, config, events, buildBase(), ['parent recovery requires runner-owned metadata for running parent'], childIssues, `plan-auto-recovery-blocked parent=${options.issueNumber} reason=missing-runner-owned-metadata`);
+    }
+    if (!alreadyRunningPlanParent) {
+        await claimIssue(issueAdapter, config, options.issueNumber, 'plan-parent', now);
+    }
     try {
-        await git.createIssueWorktree({
-            targetRoot,
-            workspacePath: worktreePath,
-            branchName,
-            baseBranch: resolvedBase.sha,
-            requiredBaseSha: resolvedBase.sha,
-        });
+        if (parentRecovery.kind === 'resume-parent') {
+            await git.ensureIssueWorktree({
+                targetRoot,
+                workspacePath: worktreePath,
+                branchName,
+                baseBranch: resolvedBase.sha,
+                requiredBaseSha: resolvedBase.sha,
+                allowResume: true,
+            });
+        }
+        else {
+            await git.createIssueWorktree({
+                targetRoot,
+                workspacePath: worktreePath,
+                branchName,
+                baseBranch: resolvedBase.sha,
+                requiredBaseSha: resolvedBase.sha,
+            });
+        }
         sessionId = `plan-${options.issueNumber}-${formatSessionTimestamp(now)}`;
         promptPath = sessionPromptPath({ targetRoot, config, issueNumber: options.issueNumber, sessionId });
         reportPath = sessionReportPath({ targetRoot, config, issueNumber: options.issueNumber, sessionId });
@@ -132,7 +172,6 @@ export async function runPlanAutoCommand(options) {
             summary: 'Starting parent planning Codex session.',
             artifacts: sessionArtifacts(promptPath, reportPath, logPath, snapshot.path),
         });
-        store = new RunnerStateStore(targetRoot, config);
         await store.upsertRun({
             issueNumber: options.issueNumber,
             mode: 'plan-parent',
@@ -145,6 +184,10 @@ export async function runPlanAutoCommand(options) {
             retryCount: 0,
             createdAt: now.toISOString(),
             updatedAt: now.toISOString(),
+            ownerPid: process.pid,
+            host: (options.hostname ?? osHostname)(),
+            leaseUpdatedAt: now.toISOString(),
+            baseSha: resolvedBase.sha,
         });
         const beforeHead = await git.getHead(worktreePath);
         let codexResult;
@@ -198,7 +241,60 @@ export async function runPlanAutoCommand(options) {
             childIssues.push(persisted);
         }
         const childNodes = await readAutonomousChildNodes(issueAdapter, config, options.issueNumber, childIssues);
-        const batches = collectExecutableChildBatches(childNodes, config);
+        const childRecoveryState = await store.load();
+        const childRecoveryDecisions = await Promise.all(childNodes.map(async (child) => {
+            const completed = await classifyPlanAutoCompletedChildRecovery({
+                targetRoot,
+                config,
+                parentIssueNumber: options.issueNumber,
+                parentBranchName: branchName,
+                child,
+                state: childRecoveryState,
+                git,
+            });
+            return completed.kind === 'execute-child'
+                ? classifyPlanAutoBlockedChildRecovery({
+                    targetRoot,
+                    config,
+                    parentIssueNumber: options.issueNumber,
+                    child,
+                    state: childRecoveryState,
+                    git,
+                })
+                : completed;
+        }));
+        const recoveredStableIds = [];
+        const resumableBlockedStableIds = [];
+        const childRecoveryByStableId = new Map();
+        for (const decision of childRecoveryDecisions) {
+            if (decision.kind === 'hard-block') {
+                return finishPlanBlocked(issueAdapter, config, events, buildBase(), [decision.reason], childIssues, decision.marker);
+            }
+            if (decision.kind === 'recovered-completed-child') {
+                recoveredStableIds.push(decision.child.metadata.stableId);
+                executionResults.push({
+                    child: decision.child,
+                    branchName: decision.branchName,
+                    worktreePath: decision.worktreePath,
+                    promptPath: decision.promptPath,
+                    reportPath: decision.reportPath,
+                    logPath: decision.logPath,
+                    changedFiles: decision.changedFiles,
+                    validation: decision.validation,
+                    artifacts: [],
+                    commits: [],
+                    skippedChecks: decision.skippedChecks,
+                    residualRisks: decision.residualRisks,
+                    durableRunSummary: decision.durableRunSummary,
+                    recovered: true,
+                });
+            }
+            else if (decision.kind === 'resume-child-rework') {
+                resumableBlockedStableIds.push(decision.child.metadata.stableId);
+                childRecoveryByStableId.set(decision.child.metadata.stableId, decision);
+            }
+        }
+        const batches = collectExecutableChildBatches(childNodes, config, recoveredStableIds, resumableBlockedStableIds);
         if (!batches.ok) {
             return finishPlanBlocked(issueAdapter, config, events, base, batches.errors, childIssues);
         }
@@ -218,6 +314,7 @@ export async function runPlanAutoCommand(options) {
                 acceptanceProofWorkflowPrompt,
                 now,
                 events,
+                recovery: childRecoveryByStableId.get(child.metadata.stableId),
             })));
             const failures = [];
             for (const [index, result] of settled.entries()) {
@@ -268,7 +365,7 @@ export async function runPlanAutoCommand(options) {
                 executionResults.push(childResult);
             }
         }
-        const finalValidation = await runConfiguredChecks(config, worktreePath, shellExecutor, []);
+        const finalValidation = await runConfiguredChecks(config, worktreePath, shellExecutor, [], { phase: 'parent-integration' });
         const failedFinalValidation = finalValidation.filter((line) => line.status === 'failed');
         if (failedFinalValidation.length > 0) {
             await blockCompletedChildren(issueAdapter, config, store, options.issueNumber, executionResults, 'Parent integration configured checks failed before publication.', worktreePath);
@@ -277,37 +374,44 @@ export async function runPlanAutoCommand(options) {
                 ...failedFinalValidation.map((line) => `${line.command}: ${line.status} - ${line.summary}`),
             ], childIssues);
         }
-        await git.pushBranch({ worktreePath, branchName });
-        pullRequest = await pullRequestAdapter.createDraftPullRequest({
-            title: renderParentTemplate(config.pullRequests.issueTreeTitle, options.issueNumber),
-            body: buildIssueTreePullRequestBody({
+        const handoff = await finishReviewReadyTerminalOutcome({
+            issueNumber: options.issueNumber,
+            config,
+            branchName,
+            baseBranch: resolvedBase.prBaseBranch,
+            worktreePath,
+            git,
+            pullRequestAdapter,
+            issueAdapter,
+            pullRequest: {
+                title: renderParentTemplate(config.pullRequests.issueTreeTitle, options.issueNumber),
+                body: buildIssueTreePullRequestBody({
+                    parentIssueNumber: options.issueNumber,
+                    childIssues,
+                    childResults: executionResults,
+                    finalValidation,
+                    sizeRisk: report.sizeRisk,
+                    parentReviewHandoff: report.parentReviewHandoff,
+                    riskRoutingWarnings,
+                }),
+            },
+            findExistingPullRequest: false,
+            reportComment: (verifiedPullRequest) => buildIssueTreeReviewReport({
                 parentIssueNumber: options.issueNumber,
-                childIssues,
+                pullRequest: verifiedPullRequest,
+                batches: batches.batches,
                 childResults: executionResults,
                 finalValidation,
                 sizeRisk: report.sizeRisk,
                 parentReviewHandoff: report.parentReviewHandoff,
                 riskRoutingWarnings,
             }),
-            headBranch: branchName,
-            baseBranch: resolvedBase.prBaseBranch,
-        });
-        pullRequest = await verifyPullRequestRefs(pullRequestAdapter, pullRequest, branchName, resolvedBase.prBaseBranch);
-        const reportComment = buildIssueTreeReviewReport({
-            parentIssueNumber: options.issueNumber,
-            pullRequest,
-            batches: batches.batches,
-            childResults: executionResults,
-            finalValidation,
-            sizeRisk: report.sizeRisk,
-            parentReviewHandoff: report.parentReviewHandoff,
-            riskRoutingWarnings,
+            onPullRequestReady: (verifiedPullRequest) => {
+                pullRequest = verifiedPullRequest;
+            },
+            beforeIssueMutation: () => markCompletedChildrenReviewReady(issueAdapter, config, store, options.issueNumber, executionResults),
+            afterComment: () => store.removeRun(options.issueNumber),
         });
-        await markCompletedChildrenReviewReady(issueAdapter, config, store, options.issueNumber, executionResults);
-        await issueAdapter.removeLabels(options.issueNumber, [config.github.labels.running.name]);
-        await issueAdapter.addLabels(options.issueNumber, [config.github.labels.review.name]);
-        await issueAdapter.postComment(options.issueNumber, reportComment);
-        await store.removeRun(options.issueNumber);
         await safeAppendEvent(events, {
             issueNumber: options.issueNumber,
             mode: 'plan-parent',
@@ -317,14 +421,14 @@ export async function runPlanAutoCommand(options) {
             summary: 'Issue-tree execution completed draft PR handoff.',
             artifacts: [
                 ...sessionArtifacts(promptPath, reportPath, logPath, parentSnapshotPath),
-                { kind: 'pr', url: pullRequest.url, description: 'Draft pull request' },
+                { kind: 'pr', url: handoff.pullRequest.url, description: 'Draft pull request' },
             ],
         });
         return {
             ...buildBase(),
             status: 'review-ready',
-            pullRequest,
-            reportComment,
+            pullRequest: handoff.pullRequest,
+            reportComment: handoff.reportComment,
             riskRoutingWarnings,
         };
     }
@@ -333,7 +437,7 @@ export async function runPlanAutoCommand(options) {
         if (pullRequest) {
             throw new Error(`Issue-tree execution failed after draft PR creation (${pullRequest.url}); not marking parent blocked: ${message}`);
         }
-        if (store && executionResults.length > 0) {
+        if (executionResults.length > 0) {
             await blockCompletedChildren(issueAdapter, config, store, options.issueNumber, executionResults, `Parent publication failed before review handoff: ${message}`, worktreePath);
         }
         return finishPlanBlocked(issueAdapter, config, events, buildBase(), [message], childIssues);
@@ -381,217 +485,95 @@ async function executeChild(input) {
     const childIssueNumber = input.child.issue.number;
     const branchName = `codex/tree-${input.parentIssue.number}-issue-${childIssueNumber}`;
     const worktreePath = join(input.targetRoot, input.config.runner.workspaceRoot, `tree-${input.parentIssue.number}-issue-${childIssueNumber}`);
-    const store = new RunnerStateStore(input.targetRoot, input.config);
     let sessionId = '';
     let promptPath = '';
     let reportPath = '';
     let logPath = '';
     let snapshotPath = '';
-    await input.git.createIssueWorktree({
-        targetRoot: input.targetRoot,
-        workspacePath: worktreePath,
-        branchName,
-        baseBranch: input.parentBranchName,
-    });
-    await input.issueAdapter.addLabels(childIssueNumber, [input.config.github.labels.running.name]);
-    await input.issueAdapter.postComment(childIssueNumber, `codex-orchestrator: claimed #${childIssueNumber} for tree-child autonomous work under #${input.parentIssue.number} at ${input.now.toISOString()}.`);
-    let publishability;
-    let rework;
-    const reworkAttempts = [];
-    const maxReworkAttempts = Math.max(input.config.loopPolicy.rework.maxAttempts, input.config.reviewGates.acceptanceProof.maxIterations - 1);
-    for (let attempt = 0; attempt <= maxReworkAttempts; attempt++) {
-        const attemptNow = new Date(input.now.getTime() + attempt);
-        sessionId = `tree-${input.parentIssue.number}-issue-${childIssueNumber}-${formatSessionTimestamp(attemptNow)}${attempt === 0 ? '' : `-attempt-${attempt}`}`;
-        promptPath = sessionPromptPath({
-            targetRoot: input.targetRoot,
-            config: input.config,
-            issueNumber: childIssueNumber,
-            sessionId,
-        });
-        reportPath = sessionReportPath({
-            targetRoot: input.targetRoot,
-            config: input.config,
-            issueNumber: childIssueNumber,
-            sessionId,
-        });
-        logPath = sessionLogPath({
-            targetRoot: input.targetRoot,
-            config: input.config,
-            issueNumber: childIssueNumber,
-            sessionId,
-        });
-        const isolatedHomePath = sessionCodexHomePath({ targetRoot: input.targetRoot, sessionId });
-        await mkdir(dirname(reportPath), { recursive: true });
-        await mkdir(isolatedHomePath, { recursive: true });
-        const promptText = buildIssueTreeChildPrompt({
-            parentIssue: input.parentIssue,
-            childIssue: input.child.issue,
-            config: input.config,
-            workflowPromptText: input.issueTreeWorkflowPrompt,
-            childMetadata: input.child.metadata,
-            dependencyIssues: input.dependencyIssues,
-            promptPath,
-            reportPath,
-            branchName,
-            worktreePath,
-        });
-        const attemptPromptText = rework
-            ? `${promptText}\n\n## Rework Request\nThis is an automatic rework attempt (#${rework.attempt}). Continue from the current worktree state; do not start over.\nThe previous attempt was blocked for these reasons:\n${rework.blockedReasons.map((reason) => `- ${reason}`).join('\n')}\n${rework.disableOptionalFigmaMcp ? 'Optional Figma MCP failed in the previous attempt. Continue without optional Figma MCP access unless the issue explicitly requires Figma.\n' : ''}Address the blockers, then produce a fresh completion report JSON for the runner.`
-            : promptText;
-        await writeDurablePrompt({
-            targetRoot: input.targetRoot,
-            config: input.config,
-            issueNumber: childIssueNumber,
-            sessionId,
-            promptText: attemptPromptText,
-        });
-        const snapshot = await writeContextSnapshot({
+    if (input.recovery) {
+        await input.git.ensureIssueWorktree({
             targetRoot: input.targetRoot,
-            config: input.config,
-            issue: input.child.issue,
-            mode: 'tree-child',
-            phase: 'tree-child',
-            decision: rework
-                ? `tree-child rework attempt #${rework.attempt} under parent #${input.parentIssue.number}`
-                : `child issue execution under parent #${input.parentIssue.number}`,
-            sessionId,
-            worktreePath,
-            promptPath,
-            reportPath,
-            logPath,
+            workspacePath: worktreePath,
             branchName,
             baseBranch: input.parentBranchName,
-            parentIssueNumber: input.parentIssue.number,
-            blockedBy: [],
-            createdAt: attemptNow,
+            allowResume: true,
         });
-        snapshotPath = snapshot.path;
-        await store.upsertRun({
-            issueNumber: childIssueNumber,
-            parentIssueNumber: input.parentIssue.number,
-            mode: 'tree-child',
+        await input.issueAdapter.removeLabels(childIssueNumber, [input.config.github.labels.blocked.name]);
+        await input.issueAdapter.addLabels(childIssueNumber, [input.config.github.labels.running.name]);
+    }
+    else {
+        await input.git.createIssueWorktree({
+            targetRoot: input.targetRoot,
             workspacePath: worktreePath,
-            sessionId,
             branchName,
-            promptPath,
-            reportPath,
-            logPath,
-            retryCount: attempt,
-            createdAt: input.now.toISOString(),
-            updatedAt: attemptNow.toISOString(),
-            attemptStartedAt: attemptNow.toISOString(),
-            snapshotPath,
-        });
-        await safeAppendEvent(input.events, {
-            timestamp: attemptNow,
-            issueNumber: childIssueNumber,
-            parentIssueNumber: input.parentIssue.number,
-            mode: 'tree-child',
-            sessionId,
-            phase: 'tree-child',
-            status: 'started',
-            summary: rework ? `Starting tree-child rework attempt #${rework.attempt}.` : 'Starting tree-child Codex session.',
-            artifacts: sessionArtifacts(promptPath, reportPath, logPath, snapshotPath),
+            baseBranch: input.parentBranchName,
         });
-        const beforeHead = await input.git.getHead(worktreePath);
-        let codexResult;
-        try {
-            codexResult = await input.codexAdapter.run({
-                targetRoot: input.targetRoot,
+        await input.issueAdapter.addLabels(childIssueNumber, [input.config.github.labels.running.name]);
+        await input.issueAdapter.postComment(childIssueNumber, `codex-orchestrator: claimed #${childIssueNumber} for tree-child autonomous work under #${input.parentIssue.number} at ${input.now.toISOString()}.`);
+    }
+    const attemptLoop = await runAgentAttemptLoop({
+        targetRoot: input.targetRoot,
+        config: input.config,
+        issue: input.child.issue,
+        issueNumber: childIssueNumber,
+        parentIssueNumber: input.parentIssue.number,
+        mode: 'tree-child',
+        phase: 'tree-child',
+        branchName,
+        worktreePath,
+        baseBranch: input.parentBranchName,
+        createdAt: input.now,
+        firstAttempt: input.recovery ? input.recovery.rework.attempt : 0,
+        initialRework: input.recovery?.rework,
+        buildSessionId: ({ attempt, attemptNow }) => `tree-${input.parentIssue.number}-issue-${childIssueNumber}-${formatSessionTimestamp(attemptNow)}${attempt === 0 ? '' : `-attempt-${attempt}`}`,
+        buildPrompt: ({ promptPath: attemptPromptPath, reportPath: attemptReportPath, rework }) => {
+            const promptText = buildIssueTreeChildPrompt({
+                parentIssue: input.parentIssue,
+                childIssue: input.child.issue,
                 config: input.config,
-                worktreePath,
-                promptPath,
-                promptText: attemptPromptText,
-                reportPath,
-                isolatedHomePath,
-                issueNumber: childIssueNumber,
-                sessionId,
+                workflowPromptText: input.issueTreeWorkflowPrompt,
+                childMetadata: input.child.metadata,
+                dependencyIssues: input.dependencyIssues,
+                promptPath: attemptPromptPath,
+                reportPath: attemptReportPath,
                 branchName,
-                phase: 'tree-child',
-                logPath,
-                disableOptionalFigmaMcp: rework?.disableOptionalFigmaMcp,
+                worktreePath,
             });
-        }
-        finally {
-            await cleanupSessionCodexHome(isolatedHomePath);
-        }
-        const afterHead = await input.git.getHead(worktreePath);
-        publishability = await runImplementationPublishabilityCheck({
-            config: input.config,
-            issue: input.child.issue,
+            return rework
+                ? `${promptText}\n\n## Rework Request\nThis is an automatic rework attempt (#${rework.attempt}). Continue from the current worktree state; do not start over.\nThe previous attempt was blocked for these reasons:\n${rework.blockedReasons.map((reason) => `- ${reason}`).join('\n')}\n${rework.disableOptionalFigmaMcp ? 'Optional Figma MCP failed in the previous attempt. Continue without optional Figma MCP access unless the issue explicitly requires Figma.\n' : ''}Address the blockers, then produce a fresh completion report JSON for the runner.`
+                : promptText;
+        },
+        buildSnapshotDecision: ({ rework }) => rework
+            ? `tree-child rework attempt #${rework.attempt} under parent #${input.parentIssue.number}`
+            : `child issue execution under parent #${input.parentIssue.number}`,
+        startedSummary: ({ rework }) => rework ? `Starting tree-child rework attempt #${rework.attempt}.` : 'Starting tree-child Codex session.',
+        reworkScheduledSummary: ({ nextAttempt }) => `Runner scheduled tree-child rework attempt #${nextAttempt}.`,
+        missingPublishabilityMessage: 'Runner internal error: missing child publishability result',
+        codexAdapter: input.codexAdapter,
+        git: input.git,
+        shellExecutor: input.shellExecutor,
+        commitMessage: `Codex: implement issue #${childIssueNumber} for parent #${input.parentIssue.number}`,
+        events: input.events,
+        acceptanceProof: {
             targetRoot: input.targetRoot,
-            worktreePath,
-            reportPath,
-            beforeHead,
-            afterHead,
-            codexResult,
-            git: input.git,
-            shellExecutor: input.shellExecutor,
-            commitMessage: `Codex: implement issue #${childIssueNumber} for parent #${input.parentIssue.number}`,
-            acceptanceProof: {
-                targetRoot: input.targetRoot,
-                sessionId,
-                branchName,
-                workflowPromptText: input.acceptanceProofWorkflowPrompt,
-                codexAdapter: input.codexAdapter,
-                onAttemptEvent: (event) => appendAcceptanceProofEvent({
-                    events: input.events,
-                    issueNumber: childIssueNumber,
-                    parentIssueNumber: input.parentIssue.number,
-                    sessionId,
-                    event,
-                }),
-            },
-        });
-        if (publishability.status === 'blocked') {
-            const reworkDecision = decideImplementationRework({
-                reasons: publishability.reasons,
-                config: input.config,
-                attempt,
-            });
-            reworkAttempts.push({
-                attempt,
-                maxAttempts: 'maxAttempts' in reworkDecision ? reworkDecision.maxAttempts : undefined,
-                decisionKind: reworkDecision.kind,
-                reasons: publishability.reasons,
-                promptPath,
-                reportPath,
-                logPath,
-                snapshotPath,
-            });
-            if (reworkDecision.kind === 'retry') {
-                rework = reworkDecision.rework;
-                await safeAppendEvent(input.events, {
-                    timestamp: attemptNow,
-                    issueNumber: childIssueNumber,
-                    parentIssueNumber: input.parentIssue.number,
-                    mode: 'tree-child',
-                    sessionId,
-                    phase: 'tree-child',
-                    status: 'needs-rework',
-                    summary: `Runner scheduled tree-child rework attempt #${reworkDecision.nextAttempt}.`,
-                    artifacts: sessionArtifacts(promptPath, reportPath, logPath, snapshotPath),
-                });
-                await mkdir(isolatedHomePath, { recursive: true });
-                continue;
-            }
-            await safeAppendEvent(input.events, {
-                timestamp: attemptNow,
-                issueNumber: childIssueNumber,
-                parentIssueNumber: input.parentIssue.number,
-                mode: 'tree-child',
-                sessionId,
-                phase: 'tree-child',
-                status: 'blocked',
-                summary: `Runner rework decision: ${reworkDecision.kind}.`,
-                artifacts: sessionArtifacts(promptPath, reportPath, logPath, snapshotPath),
-            });
-        }
-        break;
-    }
-    if (!publishability) {
-        throw new Error('Runner internal error: missing child publishability result');
-    }
+            workflowPromptText: input.acceptanceProofWorkflowPrompt,
+            codexAdapter: input.codexAdapter,
+        },
+        onAcceptanceProofAttemptEvent: ({ sessionId: attemptSessionId, event }) => appendAcceptanceProofEvent({
+            events: input.events,
+            issueNumber: childIssueNumber,
+            parentIssueNumber: input.parentIssue.number,
+            sessionId: attemptSessionId,
+            event,
+        }),
+    });
+    const publishability = attemptLoop.publishability;
+    sessionId = attemptLoop.sessionId;
+    promptPath = attemptLoop.promptPath;
+    reportPath = attemptLoop.reportPath;
+    logPath = attemptLoop.logPath;
+    snapshotPath = attemptLoop.snapshotPath;
+    const reworkAttempts = attemptLoop.reworkAttempts;
     if (publishability.status === 'promotion-requested') {
         const promotion = publishability.report.promotion;
         const evidence = buildPromotionAsBlockedHandoffEvidence({
@@ -730,31 +712,37 @@ async function blockFailedBatch(issueAdapter, config, parentIssueNumber, failure
         if (!failure.child) {
             continue;
         }
-        await issueAdapter.removeLabels(failure.child.issue.number, [config.github.labels.running.name]);
-        await issueAdapter.addLabels(failure.child.issue.number, [config.github.labels.blocked.name]);
-        await issueAdapter.postComment(failure.child.issue.number, buildChildBlockedReport({
-            parentIssueNumber,
-            childIssueNumber: failure.child.issue.number,
-            reasons: [failure.message],
-            details: ['Worktree preserved for maintainer inspection.'],
-            freshContextReview: failure.freshContextReview,
-            durableRunSummary: failure.durableRunSummary,
-            reworkAttempts: failure.reworkAttempts,
-            acceptanceProof: failure.acceptanceProof,
-        }));
+        await finishBlockedTerminalOutcome({
+            issueNumber: failure.child.issue.number,
+            config,
+            issueAdapter,
+            reportComment: buildChildBlockedReport({
+                parentIssueNumber,
+                childIssueNumber: failure.child.issue.number,
+                reasons: [failure.message],
+                details: ['Worktree preserved for maintainer inspection.'],
+                freshContextReview: failure.freshContextReview,
+                durableRunSummary: failure.durableRunSummary,
+                reworkAttempts: failure.reworkAttempts,
+                acceptanceProof: failure.acceptanceProof,
+            }),
+        });
     }
     for (const result of successfulUnmerged) {
-        await issueAdapter.removeLabels(result.child.issue.number, [config.github.labels.running.name]);
-        await issueAdapter.addLabels(result.child.issue.number, [config.github.labels.blocked.name]);
-        await issueAdapter.postComment(result.child.issue.number, buildChildBlockedReport({
-            parentIssueNumber,
-            childIssueNumber: result.child.issue.number,
-            reasons: ['A sibling child failed before the batch merge; this child branch was not merged.'],
-            branchName: result.branchName,
-            worktreePath: result.worktreePath,
-            durableRunSummary: result.durableRunSummary,
-            acceptanceProof: result.acceptanceProof,
-        }));
+        await finishBlockedTerminalOutcome({
+            issueNumber: result.child.issue.number,
+            config,
+            issueAdapter,
+            reportComment: buildChildBlockedReport({
+                parentIssueNumber,
+                childIssueNumber: result.child.issue.number,
+                reasons: ['A sibling child failed before the batch merge; this child branch was not merged.'],
+                branchName: result.branchName,
+                worktreePath: result.worktreePath,
+                durableRunSummary: result.durableRunSummary,
+                acceptanceProof: result.acceptanceProof,
+            }),
+        });
     }
 }
 async function handleMergeConflict(git, issueAdapter, config, parentIssueNumber, error, childResult, batchResults) {
@@ -766,68 +754,89 @@ async function handleMergeConflict(git, issueAdapter, config, parentIssueNumber,
         abortMessage = abortError instanceof Error ? abortError.message : 'merge abort failed';
     }
     for (const result of batchResults) {
-        await issueAdapter.removeLabels(result.child.issue.number, [config.github.labels.running.name]);
-        await issueAdapter.addLabels(result.child.issue.number, [config.github.labels.blocked.name]);
-        await issueAdapter.postComment(result.child.issue.number, buildChildBlockedReport({
-            parentIssueNumber,
-            childIssueNumber: result.child.issue.number,
-            reasons: [
-                result.child.issue.number === childResult.child.issue.number
-                    ? `Merge conflict from branch ${childResult.branchName}`
-                    : `A sibling merge conflict stopped the batch before publication: ${childResult.branchName}`,
-            ],
-            details: [
-                `- Parent worktree: ${error.worktreePath}`,
-                `- Child worktree: ${result.worktreePath}`,
-                `- Child branch preserved: ${result.branchName}`,
-                abortMessage ? `- Merge abort also failed: ${abortMessage}` : '- Merge abort completed.',
-            ],
-            batchChildren: batchResults.map((batchResult) => ({
-                issueNumber: batchResult.child.issue.number,
-                branchName: batchResult.branchName,
-            })),
-            gitOutput: error.stderr || error.stdout || 'no git output',
-            durableRunSummary: result.durableRunSummary,
-            acceptanceProof: result.acceptanceProof,
-        }));
+        await finishBlockedTerminalOutcome({
+            issueNumber: result.child.issue.number,
+            config,
+            issueAdapter,
+            reportComment: buildChildBlockedReport({
+                parentIssueNumber,
+                childIssueNumber: result.child.issue.number,
+                reasons: [
+                    result.child.issue.number === childResult.child.issue.number
+                        ? `Merge conflict from branch ${childResult.branchName}`
+                        : `A sibling merge conflict stopped the batch before publication: ${childResult.branchName}`,
+                ],
+                details: [
+                    `- Parent worktree: ${error.worktreePath}`,
+                    `- Child worktree: ${result.worktreePath}`,
+                    `- Child branch preserved: ${result.branchName}`,
+                    abortMessage ? `- Merge abort also failed: ${abortMessage}` : '- Merge abort completed.',
+                ],
+                batchChildren: batchResults.map((batchResult) => ({
+                    issueNumber: batchResult.child.issue.number,
+                    branchName: batchResult.branchName,
+                })),
+                gitOutput: error.stderr || error.stdout || 'no git output',
+                durableRunSummary: result.durableRunSummary,
+                acceptanceProof: result.acceptanceProof,
+            }),
+        });
     }
 }
 async function markCompletedChildrenReviewReady(issueAdapter, config, store, parentIssueNumber, childResults) {
     for (const childResult of childResults) {
-        await issueAdapter.removeLabels(childResult.child.issue.number, [config.github.labels.running.name]);
-        await issueAdapter.addLabels(childResult.child.issue.number, [config.github.labels.review.name]);
-        await issueAdapter.postComment(childResult.child.issue.number, buildChildReviewReport({ parentIssueNumber, result: childResult }));
-        await store.removeRun(childResult.child.issue.number);
+        if (childResult.recovered) {
+            await store.removeRun(childResult.child.issue.number);
+            continue;
+        }
+        await finishReviewReadyCommentTerminalOutcome({
+            issueNumber: childResult.child.issue.number,
+            config,
+            issueAdapter,
+            reportComment: buildChildReviewReport({ parentIssueNumber, result: childResult }),
+            afterTerminalMutation: () => store.removeRun(childResult.child.issue.number),
+        });
     }
 }
 async function blockCompletedChildren(issueAdapter, config, store, parentIssueNumber, childResults, reason, parentWorktreePath) {
     for (const result of childResults) {
-        await issueAdapter.removeLabels(result.child.issue.number, [config.github.labels.running.name]);
-        await issueAdapter.addLabels(result.child.issue.number, [config.github.labels.blocked.name]);
-        await issueAdapter.postComment(result.child.issue.number, buildChildBlockedReport({
-            parentIssueNumber,
-            childIssueNumber: result.child.issue.number,
-            reasons: [reason],
-            details: [
-                `- Merged child branch was not published: ${result.branchName}`,
-                `- Parent worktree preserved: ${parentWorktreePath}`,
-            ],
-            durableRunSummary: result.durableRunSummary,
-            acceptanceProof: result.acceptanceProof,
-        }));
-        await store.removeRun(result.child.issue.number);
+        if (result.recovered) {
+            continue;
+        }
+        await finishBlockedTerminalOutcome({
+            issueNumber: result.child.issue.number,
+            config,
+            issueAdapter,
+            reportComment: buildChildBlockedReport({
+                parentIssueNumber,
+                childIssueNumber: result.child.issue.number,
+                reasons: [reason],
+                details: [
+                    `- Merged child branch was not published: ${result.branchName}`,
+                    `- Parent worktree preserved: ${parentWorktreePath}`,
+                ],
+                durableRunSummary: result.durableRunSummary,
+                acceptanceProof: result.acceptanceProof,
+            }),
+            afterTerminalMutation: () => store.removeRun(result.child.issue.number),
+        });
     }
 }
-async function finishPlanBlocked(issueAdapter, config, events, result, reasons, mutatedChildren) {
-    const reportComment = buildParentBlockedReport({
+async function finishPlanBlocked(issueAdapter, config, events, result, reasons, mutatedChildren, commentMarker) {
+    const reportBody = buildParentBlockedReport({
         parentIssueNumber: result.parentIssueNumber,
         reasons,
         logPath: result.logPath,
         mutatedChildren,
     });
-    await issueAdapter.removeLabels(result.parentIssueNumber, [config.github.labels.running.name]);
-    await issueAdapter.addLabels(result.parentIssueNumber, [config.github.labels.blocked.name]);
-    await issueAdapter.postComment(result.parentIssueNumber, reportComment);
+    const reportComment = commentMarker ? `<!-- codex-orchestrator:${commentMarker} -->\n${reportBody}` : reportBody;
+    await finishBlockedTerminalOutcome({
+        issueNumber: result.parentIssueNumber,
+        config,
+        issueAdapter,
+        reportComment,
+        skipCommentIfIncludes: commentMarker,
+    });
     await safeAppendEvent(events, {
         issueNumber: result.parentIssueNumber,
         mode: 'plan-parent',