patchrelay 0.8.9 → 0.9.0

package/dist/linear-workflow.js

@@ -1,26 +1,7 @@
-import { resolveWorkflowStageConfig } from "./workflow-policy.js";
-const STATUS_MARKER = "<!-- patchrelay:status-comment -->";
 function normalizeLinearState(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed.toLowerCase() : undefined;
 }
-export function resolveActiveLinearState(project, stage, workflowDefinitionId) {
-    return resolveWorkflowStageConfig(project, stage, workflowDefinitionId)?.activeState;
-}
-export function resolveFallbackLinearState(project, stage, workflowDefinitionId) {
-    return resolveWorkflowStageConfig(project, stage, workflowDefinitionId)?.fallbackState;
-}
-export function resolveDoneLinearState(issue) {
-    const typedMatch = issue.workflowStates.find((state) => normalizeLinearState(state.type) === "completed");
-    if (typedMatch?.name) {
-        return typedMatch.name;
-    }
-    const nameMatch = issue.workflowStates.find((state) => {
-        const normalized = normalizeLinearState(state.name);
-        return normalized === "done" || normalized === "completed" || normalized === "complete";
-    });
-    return nameMatch?.name;
-}
 export function resolveAuthoritativeLinearStopState(issue) {
     const currentStateName = issue.stateName?.trim();
     const normalizedCurrentState = normalizeLinearState(currentStateName);
@@ -29,107 +10,13 @@ export function resolveAuthoritativeLinearStopState(issue) {
     }
     const currentWorkflowState = issue.workflowStates.find((state) => normalizeLinearState(state.name) === normalizedCurrentState);
     if (normalizeLinearState(currentWorkflowState?.type) === "completed") {
-        return {
-            stateName: currentWorkflowState?.name ?? currentStateName,
-            lifecycleStatus: "completed",
-        };
-    }
-    if (normalizedCurrentState === "human needed") {
-        return {
-            stateName: currentStateName,
-            lifecycleStatus: "paused",
-        };
+        return { stateName: currentWorkflowState?.name ?? currentStateName, isFinal: true };
     }
     if (normalizedCurrentState === "done" || normalizedCurrentState === "completed" || normalizedCurrentState === "complete") {
-        return {
-            stateName: currentStateName,
-            lifecycleStatus: "completed",
-        };
+        return { stateName: currentStateName, isFinal: true };
     }
-    return undefined;
-}
-export function buildRunningStatusComment(params) {
-    return [
-        STATUS_MARKER,
-        `PatchRelay is running the ${params.stageRun.stage} workflow.`,
-        "",
-        `- Issue: \`${params.issue.issueKey ?? params.issue.linearIssueId}\``,
-        `- Workflow: \`${params.stageRun.stage}\``,
-        `- Branch: \`${params.branchName}\``,
-        `- Thread: \`${params.stageRun.threadId ?? "starting"}\``,
-        `- Turn: \`${params.stageRun.turnId ?? "starting"}\``,
-        `- Started: \`${params.stageRun.startedAt}\``,
-        "- Status: `working`",
-    ].join("\n");
-}
-export function buildAwaitingHandoffComment(params) {
-    return [
-        STATUS_MARKER,
-        `PatchRelay finished the ${params.stageRun.stage} workflow, but Linear is still in \`${params.activeState}\`.`,
-        "",
-        `- Issue: \`${params.issue.issueKey ?? params.issue.linearIssueId}\``,
-        `- Workflow: \`${params.stageRun.stage}\``,
-        `- Thread: \`${params.stageRun.threadId ?? "unknown"}\``,
-        `- Turn: \`${params.stageRun.turnId ?? "unknown"}\``,
-        `- Completed: \`${params.stageRun.endedAt ?? new Date().toISOString()}\``,
-        "- Status: `awaiting-final-state`",
-        "",
-        "The workflow likely finished without moving the issue to its next Linear state. Please review the thread report and update the issue state.",
-    ].join("\n");
-}
-export function buildHumanNeededComment(params) {
-    return [
-        STATUS_MARKER,
-        `PatchRelay finished the ${params.stageRun.stage} workflow and now needs human input.`,
-        "",
-        `- Issue: \`${params.issue.issueKey ?? params.issue.linearIssueId}\``,
-        `- Workflow: \`${params.stageRun.stage}\``,
-        `- Thread: \`${params.stageRun.threadId ?? "unknown"}\``,
-        `- Turn: \`${params.stageRun.turnId ?? "unknown"}\``,
-        `- Completed: \`${params.stageRun.endedAt ?? new Date().toISOString()}\``,
-        "- Status: `human-needed`",
-        "",
-        "Review the stage report, decide the right next workflow step, and move or re-prompt the issue when ready.",
-    ].join("\n");
-}
-export function buildStageFailedComment(params) {
-    const mode = params.mode ?? "launch";
-    return [
-        STATUS_MARKER,
-        mode === "launch"
-            ? `PatchRelay could not start the ${params.stageRun.stage} workflow.`
-            : `PatchRelay marked the ${params.stageRun.stage} workflow as failed.`,
-        "",
-        `- Issue: \`${params.issue.issueKey ?? params.issue.linearIssueId}\``,
-        `- Workflow: \`${params.stageRun.stage}\``,
-        `- Started: \`${params.stageRun.startedAt}\``,
-        `- Failure: \`${params.message}\``,
-        `- Recommended state: \`${params.fallbackState ?? "Human Needed"}\``,
-        mode === "launch" ? "- Status: `launch-failed`" : "- Status: `stage-failed`",
-    ].join("\n");
-}
-export function isPatchRelayStatusComment(commentId, body, trackedCommentId) {
-    if (trackedCommentId && commentId === trackedCommentId) {
-        return true;
-    }
-    return typeof body === "string" && body.includes(STATUS_MARKER);
-}
-export function resolveWorkflowLabelNames(project, mode) {
-    const working = project.workflowLabels?.working;
-    const awaitingHandoff = project.workflowLabels?.awaitingHandoff;
-    if (mode === "working") {
-        return {
-            add: working ? [working] : [],
-            remove: awaitingHandoff ? [awaitingHandoff] : [],
-        };
+    if (normalizedCurrentState === "human needed") {
+        return { stateName: currentStateName, isFinal: false };
     }
-    return {
-        add: awaitingHandoff ? [awaitingHandoff] : [],
-        remove: working ? [working] : [],
-    };
-}
-export function resolveWorkflowLabelCleanup(project) {
-    return {
-        remove: [project.workflowLabels?.working, project.workflowLabels?.awaitingHandoff].filter((value) => Boolean(value)),
-    };
+    return undefined;
 }

package/dist/preflight.js

@@ -3,7 +3,6 @@ import path from "node:path";
 import { runPatchRelayMigrations } from "./db/migrations.js";
 import { SqliteConnection } from "./db/shared.js";
 import { execCommand } from "./utils.js";
-import { listProjectWorkflowDefinitions } from "./workflow-policy.js";
 export async function runPreflight(config) {
     const checks = [];
     if (!config.linear.webhookSecret) {
@@ -79,11 +78,7 @@ export async function runPreflight(config) {
     for (const project of config.projects) {
         checks.push(...checkPath(`project:${project.id}:repo`, project.repoPath, "directory", { writable: true }));
         checks.push(...checkPath(`project:${project.id}:worktrees`, project.worktreeRoot, "directory", { createIfMissing: true, writable: true }));
-        for (const definition of listProjectWorkflowDefinitions(project)) {
-            for (const workflow of definition.stages) {
-                checks.push(...checkPath(`project:${project.id}:workflow:${definition.id}:${workflow.id}`, workflow.workflowFile, "file", {}));
-            }
-        }
+        // Workflow file checks removed — factory state machine replaces workflow definitions
     }
     checks.push(await checkExecutable("git", config.runner.gitBin));
     checks.push(await checkExecutable("codex", config.runner.codex.bin));

package/dist/project-resolution.js

@@ -1,4 +1,15 @@
-import { matchesProject } from "./workflow-policy.js";
+function matchesProject(issue, project) {
+    if (project.issueKeyPrefixes.length > 0 && issue.identifier) {
+        const prefix = issue.identifier.split("-")[0];
+        if (prefix && project.issueKeyPrefixes.includes(prefix))
+            return true;
+    }
+    if (project.linearTeamIds.length > 0 && issue.teamId) {
+        if (project.linearTeamIds.includes(issue.teamId))
+            return true;
+    }
+    return false;
+}
 export function resolveProject(config, issue) {
     const matches = config.projects.filter((project) => matchesProject(issue, project));
     if (matches.length === 1) {

package/dist/run-orchestrator.js

@@ -0,0 +1,446 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { buildHookEnv, runProjectHook } from "./hook-runner.js";
+import { buildRunningSessionPlan, buildCompletedSessionPlan, buildFailedSessionPlan, } from "./agent-session-plan.js";
+import { buildStageReport, countEventMethods, extractTurnId, resolveRunCompletionStatus, summarizeCurrentThread, } from "./run-reporting.js";
+import { WorktreeManager } from "./worktree-manager.js";
+import { resolveAuthoritativeLinearStopState } from "./linear-workflow.js";
+const DEFAULT_CI_REPAIR_BUDGET = 2;
+const DEFAULT_QUEUE_REPAIR_BUDGET = 2;
+function slugify(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+}
+function sanitizePathSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+const WORKFLOW_FILES = {
+    implementation: "IMPLEMENTATION_WORKFLOW.md",
+    review_fix: "REVIEW_WORKFLOW.md",
+    ci_repair: "IMPLEMENTATION_WORKFLOW.md",
+    queue_repair: "IMPLEMENTATION_WORKFLOW.md",
+};
+function readWorkflowFile(repoPath, runType) {
+    const filename = WORKFLOW_FILES[runType];
+    const filePath = path.join(repoPath, filename);
+    if (!existsSync(filePath))
+        return undefined;
+    return readFileSync(filePath, "utf8").trim();
+}
+function buildRunPrompt(issue, runType, repoPath, context) {
+    const lines = [
+        `Issue: ${issue.issueKey ?? issue.linearIssueId}`,
+        issue.title ? `Title: ${issue.title}` : undefined,
+        `Branch: ${issue.branchName}`,
+        issue.prNumber ? `PR: #${issue.prNumber}` : undefined,
+        "",
+    ].filter(Boolean);
+    // Add run-type-specific context for reactive runs
+    switch (runType) {
+        case "ci_repair":
+            lines.push("## CI Repair", "", "A CI check has failed on your PR. Fix the failure and push.", context?.checkName ? `Failed check: ${String(context.checkName)}` : "", context?.checkUrl ? `Check URL: ${String(context.checkUrl)}` : "", "", "Read the CI failure logs, fix the code issue, run verification, commit and push.", "Do not change test expectations unless the test is genuinely wrong.", "");
+            break;
+        case "review_fix":
+            lines.push("## Review Changes Requested", "", "A reviewer has requested changes on your PR. Address the feedback and push.", context?.reviewerName ? `Reviewer: ${String(context.reviewerName)}` : "", context?.reviewBody ? `\n## Review comment\n\n${String(context.reviewBody)}` : "", "", "Read the review feedback and PR comments (`gh pr view --comments`), address each point, run verification, commit and push.", "");
+            break;
+        case "queue_repair":
+            lines.push("## Merge Queue Failure", "", "The merge queue rejected this PR. Rebase onto latest main and fix conflicts.", context?.failureReason ? `Failure reason: ${String(context.failureReason)}` : "", "", "Fetch and rebase onto latest main, resolve conflicts, run verification, push.", "If the conflict is a semantic contradiction, explain and stop.", "");
+            break;
+    }
+    // Append the repo's workflow file
+    const workflowBody = readWorkflowFile(repoPath, runType);
+    if (workflowBody) {
+        lines.push(workflowBody);
+    }
+    else if (runType === "implementation") {
+        // Fallback if no workflow file exists
+        lines.push("Implement the Linear issue. Read the issue via MCP for details.", "Run verification before finishing. Commit, push, and open a PR.");
+    }
+    return lines.join("\n");
+}
+export class RunOrchestrator {
+    config;
+    db;
+    codex;
+    linearProvider;
+    enqueueIssue;
+    logger;
+    feed;
+    worktreeManager;
+    constructor(config, db, codex, linearProvider, enqueueIssue, logger, feed) {
+        this.config = config;
+        this.db = db;
+        this.codex = codex;
+        this.linearProvider = linearProvider;
+        this.enqueueIssue = enqueueIssue;
+        this.logger = logger;
+        this.feed = feed;
+        this.worktreeManager = new WorktreeManager(config);
+    }
+    // ─── Run ────────────────────────────────────────────────────────
+    async run(item) {
+        const project = this.config.projects.find((p) => p.id === item.projectId);
+        if (!project)
+            return;
+        const issue = this.db.getIssue(item.projectId, item.issueId);
+        if (!issue?.pendingRunType || issue.activeRunId !== undefined)
+            return;
+        const runType = issue.pendingRunType;
+        const contextJson = issue.pendingRunContextJson;
+        const context = contextJson ? JSON.parse(contextJson) : undefined;
+        // Check repair budgets
+        if (runType === "ci_repair" && issue.ciRepairAttempts >= DEFAULT_CI_REPAIR_BUDGET) {
+            this.escalate(issue, runType, `CI repair budget exhausted (${DEFAULT_CI_REPAIR_BUDGET} attempts)`);
+            return;
+        }
+        if (runType === "queue_repair" && issue.queueRepairAttempts >= DEFAULT_QUEUE_REPAIR_BUDGET) {
+            this.escalate(issue, runType, `Queue repair budget exhausted (${DEFAULT_QUEUE_REPAIR_BUDGET} attempts)`);
+            return;
+        }
+        // Increment repair counters
+        if (runType === "ci_repair") {
+            this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, ciRepairAttempts: issue.ciRepairAttempts + 1 });
+        }
+        if (runType === "queue_repair") {
+            this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, queueRepairAttempts: issue.queueRepairAttempts + 1 });
+        }
+        // Build prompt
+        const prompt = buildRunPrompt(issue, runType, project.repoPath, context);
+        // Resolve workspace
+        const issueRef = sanitizePathSegment(issue.issueKey ?? issue.linearIssueId);
+        const slug = issue.title ? slugify(issue.title) : "";
+        const branchSuffix = slug ? `${issueRef}-${slug}` : issueRef;
+        const branchName = issue.branchName ?? `${project.branchPrefix}/${branchSuffix}`;
+        const worktreePath = issue.worktreePath ?? `${project.worktreeRoot}/${issueRef}`;
+        // Claim the run atomically
+        const run = this.db.transaction(() => {
+            const fresh = this.db.getIssue(item.projectId, item.issueId);
+            if (!fresh?.pendingRunType || fresh.activeRunId !== undefined)
+                return undefined;
+            const created = this.db.createRun({
+                issueId: fresh.id,
+                projectId: item.projectId,
+                linearIssueId: item.issueId,
+                runType,
+                promptText: prompt,
+            });
+            this.db.upsertIssue({
+                projectId: item.projectId,
+                linearIssueId: item.issueId,
+                pendingRunType: null,
+                pendingRunContextJson: null,
+                activeRunId: created.id,
+                branchName,
+                worktreePath,
+                factoryState: runType === "implementation" ? "implementing"
+                    : runType === "ci_repair" ? "repairing_ci"
+                        : runType === "review_fix" ? "changes_requested"
+                            : runType === "queue_repair" ? "repairing_queue"
+                                : "implementing",
+            });
+            return created;
+        });
+        if (!run)
+            return;
+        this.feed?.publish({
+            level: "info",
+            kind: "stage",
+            issueKey: issue.issueKey,
+            projectId: item.projectId,
+            stage: runType,
+            status: "starting",
+            summary: `Starting ${runType} run`,
+        });
+        let threadId;
+        let turnId;
+        try {
+            // Ensure worktree
+            await this.worktreeManager.ensureIssueWorktree(project.repoPath, project.worktreeRoot, worktreePath, branchName, { allowExistingOutsideRoot: issue.branchName !== undefined });
+            // Run prepare-worktree hook
+            const hookEnv = buildHookEnv(issue.issueKey ?? issue.linearIssueId, branchName, runType, worktreePath);
+            const prepareResult = await runProjectHook(project.repoPath, "prepare-worktree", { cwd: worktreePath, env: hookEnv });
+            if (prepareResult.ran && prepareResult.exitCode !== 0) {
+                throw new Error(`prepare-worktree hook failed (exit ${prepareResult.exitCode}): ${prepareResult.stderr?.slice(0, 500) ?? ""}`);
+            }
+            // Start or reuse Codex thread
+            if (issue.threadId && runType !== "implementation") {
+                threadId = issue.threadId;
+            }
+            else {
+                const thread = await this.codex.startThread({ cwd: worktreePath });
+                threadId = thread.id;
+                this.db.upsertIssue({ projectId: item.projectId, linearIssueId: item.issueId, threadId });
+            }
+            const turn = await this.codex.startTurn({ threadId, cwd: worktreePath, input: prompt });
+            turnId = turn.turnId;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.db.finishRun(run.id, { status: "failed", failureReason: message });
+            this.db.upsertIssue({
+                projectId: item.projectId,
+                linearIssueId: item.issueId,
+                activeRunId: null,
+                factoryState: "failed",
+            });
+            this.logger.error({ issueKey: issue.issueKey, runType, error: message }, `Failed to launch ${runType} run`);
+            void this.emitLinearActivity(issue, "error", `Failed to start ${runType}: ${message}`);
+            void this.updateLinearPlan(issue, buildFailedSessionPlan(runType));
+            throw error;
+        }
+        this.db.updateRunThread(run.id, { threadId, turnId });
+        this.logger.info({ issueKey: issue.issueKey, runType, threadId, turnId }, `Started ${runType} run`);
+        // Emit Linear activity + plan
+        const freshIssue = this.db.getIssue(item.projectId, item.issueId) ?? issue;
+        void this.emitLinearActivity(freshIssue, "thought", `Started ${runType} run.`, { ephemeral: true });
+        void this.updateLinearPlan(freshIssue, buildRunningSessionPlan(runType));
+    }
+    // ─── Notification handler ─────────────────────────────────────────
+    async handleCodexNotification(notification) {
+        const threadId = typeof notification.params.threadId === "string" ? notification.params.threadId : undefined;
+        if (!threadId)
+            return;
+        const run = this.db.getRunByThreadId(threadId);
+        if (!run)
+            return;
+        const turnId = typeof notification.params.turnId === "string" ? notification.params.turnId : undefined;
+        if (this.config.runner.codex.persistExtendedHistory) {
+            this.db.saveThreadEvent({
+                runId: run.id,
+                threadId,
+                ...(turnId ? { turnId } : {}),
+                method: notification.method,
+                eventJson: JSON.stringify(notification.params),
+            });
+        }
+        if (notification.method !== "turn/completed")
+            return;
+        const thread = await this.readThreadWithRetry(threadId);
+        const issue = this.db.getIssue(run.projectId, run.linearIssueId);
+        if (!issue)
+            return;
+        const completedTurnId = extractTurnId(notification.params);
+        const status = resolveRunCompletionStatus(notification.params);
+        if (status === "failed") {
+            this.db.finishRun(run.id, {
+                status: "failed",
+                threadId,
+                ...(completedTurnId ? { turnId: completedTurnId } : {}),
+                failureReason: "Codex reported the turn completed in a failed state",
+            });
+            this.db.upsertIssue({
+                projectId: run.projectId,
+                linearIssueId: run.linearIssueId,
+                activeRunId: null,
+                factoryState: "failed",
+            });
+            this.feed?.publish({
+                level: "error",
+                kind: "turn",
+                issueKey: issue.issueKey,
+                projectId: run.projectId,
+                stage: run.runType,
+                status: "failed",
+                summary: `Turn failed for ${run.runType}`,
+            });
+            void this.emitLinearActivity(issue, "error", `${run.runType} run failed.`);
+            void this.updateLinearPlan(issue, buildFailedSessionPlan(run.runType, run));
+            return;
+        }
+        // Complete the run
+        const trackedIssue = this.db.issueToTrackedIssue(issue);
+        const report = buildStageReport(run, trackedIssue, thread, countEventMethods(this.db.listThreadEvents(run.id)));
+        this.db.transaction(() => {
+            this.db.finishRun(run.id, {
+                status: "completed",
+                threadId,
+                ...(completedTurnId ? { turnId: completedTurnId } : {}),
+                summaryJson: JSON.stringify({ latestAssistantMessage: report.assistantMessages.at(-1) ?? null }),
+                reportJson: JSON.stringify(report),
+            });
+            this.db.upsertIssue({
+                projectId: run.projectId,
+                linearIssueId: run.linearIssueId,
+                activeRunId: null,
+            });
+        });
+        this.feed?.publish({
+            level: "info",
+            kind: "turn",
+            issueKey: issue.issueKey,
+            projectId: run.projectId,
+            stage: run.runType,
+            status: "completed",
+            summary: `Turn completed for ${run.runType}`,
+            detail: summarizeCurrentThread(thread).latestAgentMessage,
+        });
+        // Emit Linear completion activity + plan
+        const completionSummary = report.assistantMessages.at(-1)?.slice(0, 300) ?? `${run.runType} completed.`;
+        const prInfo = issue.prNumber ? ` PR #${issue.prNumber}` : "";
+        void this.emitLinearActivity(issue, "response", `${run.runType} completed.${prInfo}\n\n${completionSummary}`);
+        void this.updateLinearPlan(issue, buildCompletedSessionPlan(run.runType));
+    }
+    // ─── Active status for query ──────────────────────────────────────
+    async getActiveRunStatus(issueKey) {
+        const issue = this.db.getIssueByKey(issueKey);
+        if (!issue?.activeRunId)
+            return undefined;
+        const run = this.db.getRun(issue.activeRunId);
+        if (!run?.threadId)
+            return undefined;
+        const trackedIssue = this.db.issueToTrackedIssue(issue);
+        const thread = await this.codex.readThread(run.threadId, true).catch(() => undefined);
+        return {
+            issue: trackedIssue,
+            run,
+            ...(thread ? { liveThread: summarizeCurrentThread(thread) } : {}),
+        };
+    }
+    // ─── Reconciliation ───────────────────────────────────────────────
+    async reconcileActiveRuns() {
+        for (const run of this.db.listRunningRuns()) {
+            await this.reconcileRun(run);
+        }
+    }
+    async reconcileRun(run) {
+        if (!run.threadId) {
+            this.failRunAndClear(run, "Run has no thread ID during reconciliation");
+            return;
+        }
+        const issue = this.db.getIssue(run.projectId, run.linearIssueId);
+        if (!issue)
+            return;
+        // Read Codex state
+        let thread;
+        try {
+            thread = await this.readThreadWithRetry(run.threadId);
+        }
+        catch {
+            this.failRunAndClear(run, "Codex thread not found during reconciliation");
+            return;
+        }
+        // Check Linear state
+        const linear = await this.linearProvider.forProject(run.projectId);
+        if (linear) {
+            const linearIssue = await linear.getIssue(run.linearIssueId).catch(() => undefined);
+            if (linearIssue) {
+                const stopState = resolveAuthoritativeLinearStopState(linearIssue);
+                if (stopState?.isFinal) {
+                    this.db.transaction(() => {
+                        this.db.finishRun(run.id, { status: "released" });
+                        this.db.upsertIssue({
+                            projectId: run.projectId,
+                            linearIssueId: run.linearIssueId,
+                            activeRunId: null,
+                            currentLinearState: stopState.stateName,
+                            factoryState: "done",
+                        });
+                    });
+                    return;
+                }
+            }
+        }
+        const latestTurn = thread.turns.at(-1);
+        // Handle interrupted turn — fail the run rather than retrying indefinitely.
+        // The agent may have partially completed work (commits, PR) before interruption.
+        // Reactive loops (CI repair, review fix) will handle follow-up if needed.
+        if (latestTurn?.status === "interrupted") {
+            this.logger.warn({ issueKey: issue.issueKey, runType: run.runType, threadId: run.threadId }, "Run has interrupted turn — marking as failed");
+            this.failRunAndClear(run, "Codex turn was interrupted");
+            void this.emitLinearActivity(issue, "error", `${run.runType} run was interrupted.`);
+            return;
+        }
+        // Handle completed turn discovered during reconciliation
+        if (latestTurn?.status === "completed") {
+            const trackedIssue = this.db.issueToTrackedIssue(issue);
+            const report = buildStageReport(run, trackedIssue, thread, countEventMethods(this.db.listThreadEvents(run.id)));
+            this.db.transaction(() => {
+                this.db.finishRun(run.id, {
+                    status: "completed",
+                    ...(run.threadId ? { threadId: run.threadId } : {}),
+                    ...(latestTurn.id ? { turnId: latestTurn.id } : {}),
+                    summaryJson: JSON.stringify({ latestAssistantMessage: report.assistantMessages.at(-1) ?? null }),
+                    reportJson: JSON.stringify(report),
+                });
+                this.db.upsertIssue({
+                    projectId: run.projectId,
+                    linearIssueId: run.linearIssueId,
+                    activeRunId: null,
+                });
+            });
+        }
+    }
+    // ─── Internal helpers ─────────────────────────────────────────────
+    escalate(issue, runType, reason) {
+        this.logger.warn({ issueKey: issue.issueKey, runType, reason }, "Escalating to human");
+        this.db.upsertIssue({
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            pendingRunType: null,
+            pendingRunContextJson: null,
+            factoryState: "escalated",
+        });
+        this.feed?.publish({
+            level: "error",
+            kind: "workflow",
+            issueKey: issue.issueKey,
+            projectId: issue.projectId,
+            stage: runType,
+            status: "escalated",
+            summary: `Escalated: ${reason}`,
+        });
+    }
+    failRunAndClear(run, message) {
+        this.db.transaction(() => {
+            this.db.finishRun(run.id, { status: "failed", failureReason: message });
+            this.db.upsertIssue({
+                projectId: run.projectId,
+                linearIssueId: run.linearIssueId,
+                activeRunId: null,
+                factoryState: "failed",
+            });
+        });
+    }
+    async emitLinearActivity(issue, type, body, options) {
+        if (!issue.agentSessionId)
+            return;
+        const linear = await this.linearProvider.forProject(issue.projectId);
+        if (!linear)
+            return;
+        try {
+            await linear.createAgentActivity({
+                agentSessionId: issue.agentSessionId,
+                content: { type, body },
+                ...(options?.ephemeral ? { ephemeral: true } : {}),
+            });
+        }
+        catch (error) {
+            this.logger.debug({ issueKey: issue.issueKey, type, error: error instanceof Error ? error.message : String(error) }, "Failed to emit Linear activity (non-blocking)");
+        }
+    }
+    async updateLinearPlan(issue, plan) {
+        if (!issue.agentSessionId)
+            return;
+        const linear = await this.linearProvider.forProject(issue.projectId);
+        if (!linear?.updateAgentSession)
+            return;
+        try {
+            await linear.updateAgentSession({ agentSessionId: issue.agentSessionId, plan });
+        }
+        catch (error) {
+            this.logger.debug({ issueKey: issue.issueKey, error: error instanceof Error ? error.message : String(error) }, "Failed to update Linear plan (non-blocking)");
+        }
+    }
+    async readThreadWithRetry(threadId, maxRetries = 3) {
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
+            try {
+                return await this.codex.readThread(threadId, true);
+            }
+            catch {
+                if (attempt === maxRetries - 1)
+                    throw new Error(`Failed to read thread ${threadId} after ${maxRetries} attempts`);
+                await new Promise((resolve) => setTimeout(resolve, 1000 * (attempt + 1)));
+            }
+        }
+        throw new Error(`Failed to read thread ${threadId}`);
+    }
+}

package/dist/{stage-reporting.js → run-reporting.js}

@@ -19,7 +19,7 @@ export function summarizeCurrentThread(thread) {
         ...(latestAgentMessage ? { latestAgentMessage } : {}),
     };
 }
-export function buildStageReport(stageRun, issue, thread, eventCounts) {
+export function buildStageReport(run, issue, thread, eventCounts) {
     const assistantMessages = [];
     const plans = [];
     const reasoning = [];
@@ -78,13 +78,12 @@ export function buildStageReport(stageRun, issue, thread, eventCounts) {
     }
     return {
         ...(issue.issueKey ? { issueKey: issue.issueKey } : {}),
-        stage: stageRun.stage,
-        status: stageRun.status,
-        ...(stageRun.threadId ? { threadId: stageRun.threadId } : {}),
-        ...(stageRun.parentThreadId ? { parentThreadId: stageRun.parentThreadId } : {}),
-        ...(stageRun.turnId ? { turnId: stageRun.turnId } : {}),
-        prompt: stageRun.promptText,
-        workflowFile: stageRun.workflowFile,
+        runType: run.runType,
+        status: run.status,
+        ...(run.threadId ? { threadId: run.threadId } : {}),
+        ...(run.parentThreadId ? { parentThreadId: run.parentThreadId } : {}),
+        ...(run.turnId ? { turnId: run.turnId } : {}),
+        prompt: run.promptText ?? "",
         assistantMessages,
         plans,
         reasoning,
@@ -94,14 +93,13 @@ export function buildStageReport(stageRun, issue, thread, eventCounts) {
         eventCounts,
     };
 }
-export function buildFailedStageReport(stageRun, status, options) {
+export function buildFailedStageReport(run, status, options) {
     return {
-        stage: stageRun.stage,
+        runType: run.runType,
         status,
         ...(options?.threadId ? { threadId: options.threadId } : {}),
         ...(options?.turnId ? { turnId: options.turnId } : {}),
-        prompt: stageRun.promptText,
-        workflowFile: stageRun.workflowFile,
+        prompt: run.promptText ?? "",
         assistantMessages: [],
         plans: [],
         reasoning: [],
@@ -117,7 +115,7 @@ export function countEventMethods(events) {
         return counts;
     }, {});
 }
-export function resolveStageRunStatus(params) {
+export function resolveRunCompletionStatus(params) {
     const turn = params.turn;
     if (!turn || typeof turn !== "object") {
         return "failed";