patchrelay 0.7.10 → 0.8.1

package/dist/db/webhook-event-store.js

@@ -28,6 +28,19 @@ export class WebhookEventStore {
         const row = this.connection.prepare("SELECT * FROM webhook_events WHERE id = ?").get(id);
         return row ? mapWebhookEvent(row) : undefined;
     }
+    listWebhookEventsForIssueSince(issueId, receivedAfter) {
+        const rows = this.connection
+            .prepare(`
+        SELECT *
+        FROM webhook_events
+        WHERE issue_id = ?
+          AND dedupe_status = 'accepted'
+          AND received_at > ?
+        ORDER BY received_at ASC, id ASC
+        `)
+            .all(issueId, receivedAfter);
+        return rows.map((row) => mapWebhookEvent(row));
+    }
 }
 function mapWebhookEvent(row) {
     return {

package/dist/http.js

@@ -1,6 +1,7 @@
 import fastify from "fastify";
 import rawBody from "fastify-raw-body";
 import { getBuildInfo } from "./build-info.js";
+import { matchesOperatorFeedEvent } from "./operator-feed.js";
 export async function buildHttpServer(config, service, logger) {
     const buildInfo = getBuildInfo();
     const loopbackBind = isLoopbackBind(config.server.bind);
@@ -264,13 +265,9 @@ export async function buildHttpServer(config, service, logger) {
     }
     if (managementRoutesEnabled) {
         app.get("/api/feed", async (request, reply) => {
-            const limit = getPositiveIntegerQueryParam(request, "limit") ?? 50;
-            const issueKey = getQueryParam(request, "issue")?.trim() || undefined;
-            const projectId = getQueryParam(request, "project")?.trim() || undefined;
             const feedQuery = {
-                limit,
-                ...(issueKey ? { issueKey } : {}),
-                ...(projectId ? { projectId } : {}),
+                limit: getPositiveIntegerQueryParam(request, "limit") ?? 50,
+                ...readFeedQueryFilters(request),
             };
             if (getQueryParam(request, "follow") !== "1") {
                 return reply.send({ ok: true, events: service.listOperatorFeed(feedQuery) });
@@ -290,10 +287,7 @@ export async function buildHttpServer(config, service, logger) {
                 writeEvent(event);
             }
             const unsubscribe = service.subscribeOperatorFeed((event) => {
-                if (issueKey && event.issueKey !== issueKey) {
-                    return;
-                }
-                if (projectId && event.projectId !== projectId) {
+                if (!matchesOperatorFeedEvent(event, feedQuery)) {
                     return;
                 }
                 writeEvent(event);
@@ -385,6 +379,22 @@ function getQueryParam(request, key) {
     const value = request.query?.[key];
     return typeof value === "string" ? value : undefined;
 }
+function readFeedQueryFilters(request) {
+    const issueKey = getQueryParam(request, "issue")?.trim() || undefined;
+    const projectId = getQueryParam(request, "project")?.trim() || undefined;
+    const kind = (getQueryParam(request, "kind")?.trim() || undefined);
+    const stage = getQueryParam(request, "stage")?.trim() || undefined;
+    const status = getQueryParam(request, "status")?.trim() || undefined;
+    const workflowId = getQueryParam(request, "workflow")?.trim() || undefined;
+    return {
+        ...(issueKey ? { issueKey } : {}),
+        ...(projectId ? { projectId } : {}),
+        ...(kind ? { kind } : {}),
+        ...(stage ? { stage } : {}),
+        ...(status ? { status } : {}),
+        ...(workflowId ? { workflowId } : {}),
+    };
+}
 function getPositiveIntegerQueryParam(request, key) {
     const value = getQueryParam(request, key);
     if (!value || !/^\d+$/.test(value)) {

package/dist/install.js

@@ -39,6 +39,23 @@ function defaultProjectWorkflows() {
         },
     ];
 }
+function defaultRepoProjectSettings() {
+    return {
+        workflow_definitions: [
+            {
+                id: "default",
+                stages: defaultProjectWorkflows(),
+            },
+        ],
+        workflow_selection: {
+            default_workflow: "default",
+            by_label: [],
+        },
+    };
+}
+function getRepoProjectSettingsPath(repoPath) {
+    return `${repoPath}/.patchrelay/project.json`;
+}
 function renderTemplate(template, replacements) {
     const home = homedir();
     const user = basename(home);
@@ -200,9 +217,6 @@ export async function upsertProjectInConfig(options) {
         ...(existingProject ?? {}),
         id: resolvedProjectId,
         repo_path: repoPath,
-        workflows: Array.isArray(existingProject?.workflows) && existingProject.workflows.length > 0
-            ? existingProject.workflows
-            : defaultProjectWorkflows(),
     };
     if (issueKeyPrefixes.length > 0) {
         nextProject.issue_key_prefixes = issueKeyPrefixes;
@@ -281,6 +295,7 @@ export async function upsertProjectInConfig(options) {
         const next = stringifyConfig(document);
         await writeFile(configPath, next, "utf8");
     }
+    await writeTemplateFile(getRepoProjectSettingsPath(repoPath), stringifyConfig(defaultRepoProjectSettings()), false);
     try {
         loadConfig(configPath, { profile: "write_config" });
     }

package/dist/linear-workflow.js

@@ -1,10 +1,10 @@
-import { resolveWorkflowById } from "./workflow-policy.js";
+import { resolveWorkflowStageConfig } from "./workflow-policy.js";
 const STATUS_MARKER = "<!-- patchrelay:status-comment -->";
-export function resolveActiveLinearState(project, stage) {
-    return resolveWorkflowById(project, stage)?.activeState;
+export function resolveActiveLinearState(project, stage, workflowDefinitionId) {
+    return resolveWorkflowStageConfig(project, stage, workflowDefinitionId)?.activeState;
 }
-export function resolveFallbackLinearState(project, stage) {
-    return resolveWorkflowById(project, stage)?.fallbackState;
+export function resolveFallbackLinearState(project, stage, workflowDefinitionId) {
+    return resolveWorkflowStageConfig(project, stage, workflowDefinitionId)?.fallbackState;
 }
 export function buildRunningStatusComment(params) {
     return [
@@ -35,6 +35,21 @@ export function buildAwaitingHandoffComment(params) {
         "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 [

package/dist/operator-feed.js

@@ -39,6 +39,8 @@ export class OperatorEventFeed {
             ...(event.projectId ? { projectId: event.projectId } : {}),
             ...(event.stage ? { stage: event.stage } : {}),
             ...(event.status ? { status: event.status } : {}),
+            ...(event.workflowId ? { workflowId: event.workflowId } : {}),
+            ...(event.nextStage ? { nextStage: event.nextStage } : {}),
         };
         if (!this.store) {
             return this.pushFallbackEvent(normalizedEvent);
@@ -63,20 +65,36 @@ export class OperatorEventFeed {
         return fullEvent;
     }
     listFallback(options) {
-        return this.persistedFallbackEvents.filter((event) => {
-            if (options?.afterId !== undefined && event.id <= options.afterId) {
-                return false;
-            }
-            if (options?.issueKey && event.issueKey !== options.issueKey) {
-                return false;
-            }
-            if (options?.projectId && event.projectId !== options.projectId) {
-                return false;
-            }
-            return true;
-        });
+        return this.persistedFallbackEvents.filter((event) => matchesOperatorFeedEvent(event, options));
     }
 }
+export function matchesOperatorFeedEvent(event, options) {
+    if (!options) {
+        return true;
+    }
+    if (options.afterId !== undefined && event.id <= options.afterId) {
+        return false;
+    }
+    if (options.issueKey && event.issueKey !== options.issueKey) {
+        return false;
+    }
+    if (options.projectId && event.projectId !== options.projectId) {
+        return false;
+    }
+    if (options.kind && event.kind !== options.kind) {
+        return false;
+    }
+    if (options.stage && event.stage !== options.stage) {
+        return false;
+    }
+    if (options.status && event.status !== options.status) {
+        return false;
+    }
+    if (options.workflowId && event.workflowId !== options.workflowId) {
+        return false;
+    }
+    return true;
+}
 function compareFeedEvents(left, right) {
     if (left.at !== right.at) {
         return left.at.localeCompare(right.at);

package/dist/preflight.js

@@ -3,6 +3,7 @@ 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) {
@@ -72,8 +73,10 @@ 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 workflow of project.workflows) {
-            checks.push(...checkPath(`project:${project.id}:workflow:${workflow.id}`, workflow.workflowFile, "file", {}));
+        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", {}));
+            }
         }
     }
     checks.push(await checkExecutable("git", config.runner.gitBin));

package/dist/reconciliation-snapshot-builder.js

@@ -1,3 +1,4 @@
+import { resolveWorkflowStageConfig } from "./workflow-policy.js";
 import { safeJsonParse } from "./utils.js";
 export async function buildReconciliationSnapshot(params) {
     const runLease = params.stores.runLeases.getRunLease(params.runLeaseId);
@@ -10,7 +11,7 @@ export async function buildReconciliationSnapshot(params) {
     }
     const workspaceOwnership = params.stores.workspaceOwnership.getWorkspaceOwnership(runLease.workspaceOwnershipId);
     const project = params.config.projects.find((candidate) => candidate.id === runLease.projectId);
-    const workflowConfig = project?.workflows.find((workflow) => workflow.id === runLease.stage);
+    const workflowConfig = project ? resolveWorkflowStageConfig(project, runLease.stage, issueControl.selectedWorkflowId) : undefined;
     const liveLinear = project
         ? await params.linearProvider
             .forProject(runLease.projectId)

package/dist/service-runtime.js

@@ -1,5 +1,6 @@
 import { SerialWorkQueue } from "./service-queue.js";
 const ISSUE_KEY_DELIMITER = "::";
+const DEFAULT_RECONCILE_INTERVAL_MS = 5_000;
 function toReconciler(value) {
     if (typeof value === "function") {
         return {
@@ -40,13 +41,17 @@ function makeIssueQueueKey(item) {
 export class ServiceRuntime {
     codex;
     logger;
+    options;
     webhookQueue;
     issueQueue;
     ready = false;
     startupError;
-    constructor(codex, logger, stageRunReconciler, readyIssueSource, webhookProcessor, issueProcessor) {
+    reconcileTimer;
+    reconcileInProgress = false;
+    constructor(codex, logger, stageRunReconciler, readyIssueSource, webhookProcessor, issueProcessor, options = {}) {
         this.codex = codex;
         this.logger = logger;
+        this.options = options;
         this.stageRunReconciler = toReconciler(stageRunReconciler);
         this.readyIssueSource = toReadyIssueSource(readyIssueSource);
         this.webhookProcessor = toWebhookProcessor(webhookProcessor);
@@ -69,6 +74,7 @@ export class ServiceRuntime {
             }
             this.ready = true;
             this.startupError = undefined;
+            this.scheduleBackgroundReconcile();
         }
         catch (error) {
             this.ready = false;
@@ -78,6 +84,7 @@ export class ServiceRuntime {
     }
     stop() {
         this.ready = false;
+        this.clearBackgroundReconcile();
         void this.codex.stop();
     }
     enqueueWebhookEvent(eventId, options) {
@@ -93,4 +100,42 @@ export class ServiceRuntime {
             ...(this.startupError ? { startupError: this.startupError } : {}),
         };
     }
+    scheduleBackgroundReconcile() {
+        this.clearBackgroundReconcile();
+        const timer = setTimeout(() => {
+            void this.runBackgroundReconcile();
+        }, this.options.reconcileIntervalMs ?? DEFAULT_RECONCILE_INTERVAL_MS);
+        timer.unref?.();
+        this.reconcileTimer = timer;
+    }
+    clearBackgroundReconcile() {
+        if (this.reconcileTimer !== undefined) {
+            clearTimeout(this.reconcileTimer);
+            this.reconcileTimer = undefined;
+        }
+    }
+    async runBackgroundReconcile() {
+        if (!this.ready || !this.codex.isStarted()) {
+            return;
+        }
+        if (this.reconcileInProgress) {
+            this.scheduleBackgroundReconcile();
+            return;
+        }
+        this.reconcileInProgress = true;
+        try {
+            await this.stageRunReconciler.reconcileActiveStageRuns();
+        }
+        catch (error) {
+            this.logger.warn({
+                error: error instanceof Error ? error.message : String(error),
+            }, "Background active-stage reconciliation failed");
+        }
+        finally {
+            this.reconcileInProgress = false;
+            if (this.ready) {
+                this.scheduleBackgroundReconcile();
+            }
+        }
+    }
 }

package/dist/service-stage-finalizer.js

@@ -2,9 +2,15 @@ import { ReconciliationActionApplier } from "./reconciliation-action-applier.js"
 import { reconcileIssue } from "./reconciliation-engine.js";
 import { buildReconciliationSnapshot } from "./reconciliation-snapshot-builder.js";
 import { syncFailedStageToLinear } from "./stage-failure.js";
+import { parseStageHandoff } from "./stage-handoff.js";
+import { resolveActiveLinearState, resolveFallbackLinearState } from "./linear-workflow.js";
+import { resolveDefaultTransitionTarget, transitionTargetAllowed } from "./workflow-policy.js";
 import { buildFailedStageReport, buildPendingMaterializationThread, buildStageReport, countEventMethods, extractStageSummary, extractTurnId, resolveStageRunStatus, summarizeCurrentThread, } from "./stage-reporting.js";
 import { StageLifecyclePublisher } from "./stage-lifecycle-publisher.js";
 import { StageTurnInputDispatcher } from "./stage-turn-input-dispatcher.js";
+import { safeJsonParse } from "./utils.js";
+import { normalizeWebhook } from "./webhooks.js";
+const MAX_AUTOMATIC_TRANSITION_ATTEMPTS = 3;
 export class ServiceStageFinalizer {
     config;
     stores;
@@ -82,6 +88,7 @@ export class ServiceStageFinalizer {
                     issueKey: issue?.issueKey,
                     projectId: stageRun.projectId,
                     stage: stageRun.stage,
+                    ...(issue?.selectedWorkflowId ? { workflowId: issue.selectedWorkflowId } : {}),
                     status: "started",
                     summary: `Turn started for ${stageRun.stage}`,
                     detail: turnId ? `Turn ${turnId} is now live.` : undefined,
@@ -106,6 +113,7 @@ export class ServiceStageFinalizer {
                 issueKey: issue.issueKey,
                 projectId: stageRun.projectId,
                 stage: stageRun.stage,
+                ...(issue.selectedWorkflowId ? { workflowId: issue.selectedWorkflowId } : {}),
                 status: "failed",
                 summary: `Turn failed for ${stageRun.stage}`,
                 detail: completedTurnId ? `Turn ${completedTurnId} completed in a failed state.` : undefined,
@@ -121,6 +129,7 @@ export class ServiceStageFinalizer {
             issueKey: issue.issueKey,
             projectId: stageRun.projectId,
             stage: stageRun.stage,
+            ...(issue.selectedWorkflowId ? { workflowId: issue.selectedWorkflowId } : {}),
             status: "completed",
             summary: `Turn completed for ${stageRun.stage}`,
             detail: summarizeCurrentThread(thread).latestAgentMessage,
@@ -159,7 +168,7 @@ export class ServiceStageFinalizer {
                 reportJson: JSON.stringify(report),
             });
         });
-        void this.advanceAfterStageCompletion(stageRun);
+        void this.advanceAfterStageCompletion(stageRun, report);
     }
     failStageRun(stageRun, threadId, message, options) {
         this.runAtomically(() => {
@@ -227,9 +236,225 @@ export class ServiceStageFinalizer {
     async flushQueuedTurnInputs(stageRun) {
         await this.inputDispatcher.flush(stageRun);
     }
-    async advanceAfterStageCompletion(stageRun) {
+    async advanceAfterStageCompletion(stageRun, report) {
+        await this.maybeQueueAutomaticTransition(stageRun, report);
         await this.lifecyclePublisher.publishStageCompletion(stageRun, this.enqueueIssue);
     }
+    async maybeQueueAutomaticTransition(stageRun, report) {
+        const refreshedIssue = this.stores.issueWorkflows.getTrackedIssue(stageRun.projectId, stageRun.linearIssueId);
+        if (!refreshedIssue || refreshedIssue.desiredStage) {
+            return;
+        }
+        const project = this.config.projects.find((candidate) => candidate.id === stageRun.projectId);
+        if (!project) {
+            return;
+        }
+        const handoff = parseStageHandoff(project, report.assistantMessages, refreshedIssue.selectedWorkflowId);
+        if (!handoff) {
+            return;
+        }
+        const linear = await this.linearProvider.forProject(stageRun.projectId);
+        if (!linear) {
+            return;
+        }
+        const linearIssue = await linear.getIssue(stageRun.linearIssueId).catch(() => undefined);
+        if (!linearIssue) {
+            return;
+        }
+        const continuationPrecondition = await this.checkAutomaticContinuationPreconditions(project, stageRun, refreshedIssue, linear, linearIssue);
+        if (!continuationPrecondition.allowed) {
+            this.feed?.publish({
+                level: "info",
+                kind: "workflow",
+                issueKey: refreshedIssue.issueKey,
+                projectId: stageRun.projectId,
+                stage: stageRun.stage,
+                ...(refreshedIssue.selectedWorkflowId ? { workflowId: refreshedIssue.selectedWorkflowId } : {}),
+                status: "transition_suppressed",
+                summary: `Suppressed automatic continuation after ${stageRun.stage}`,
+                detail: continuationPrecondition.reason,
+            });
+            return;
+        }
+        const nextTarget = this.resolveTransitionTarget(project, stageRun, refreshedIssue.selectedWorkflowId, handoff);
+        if (nextTarget === "done") {
+            const doneState = resolveDoneLinearState(linearIssue);
+            if (!doneState) {
+                await this.routeStageToHumanNeeded(project, stageRun, linearIssue, "PatchRelay could not determine the repo's done state.");
+                return;
+            }
+            this.feed?.publish({
+                level: "info",
+                kind: "workflow",
+                issueKey: refreshedIssue.issueKey,
+                projectId: stageRun.projectId,
+                stage: stageRun.stage,
+                ...(refreshedIssue.selectedWorkflowId ? { workflowId: refreshedIssue.selectedWorkflowId } : {}),
+                status: "completed",
+                summary: `Completed workflow after ${stageRun.stage}`,
+            });
+            await linear.setIssueState(stageRun.linearIssueId, doneState);
+            this.stores.workflowCoordinator.setIssueDesiredStage(stageRun.projectId, stageRun.linearIssueId, undefined, {
+                lifecycleStatus: "completed",
+            });
+            this.stores.workflowCoordinator.upsertTrackedIssue({
+                projectId: stageRun.projectId,
+                linearIssueId: stageRun.linearIssueId,
+                currentLinearState: doneState,
+                lifecycleStatus: "completed",
+            });
+            return;
+        }
+        if (nextTarget === "human_needed") {
+            await this.routeStageToHumanNeeded(project, stageRun, linearIssue, handoff.nextLikelyStageText
+                ? `PatchRelay could not safely continue from "${handoff.nextLikelyStageText}".`
+                : handoff.suggestsHumanNeeded
+                    ? "PatchRelay needs human input before the next stage is clear."
+                    : `PatchRelay could not map the ${stageRun.stage} result to an allowed next transition.`);
+            return;
+        }
+        if (nextTarget === stageRun.stage) {
+            await this.routeStageToHumanNeeded(project, stageRun, linearIssue, `PatchRelay received ${nextTarget} as the next stage again and needs a human to confirm the intended loop.`);
+            return;
+        }
+        const priorAttempts = this.countPriorTransitionAttempts(stageRun.projectId, stageRun.linearIssueId, stageRun.stage, nextTarget);
+        if (priorAttempts >= MAX_AUTOMATIC_TRANSITION_ATTEMPTS) {
+            await this.routeStageToHumanNeeded(project, stageRun, linearIssue, `PatchRelay hit the automatic continuation limit for ${stageRun.stage} -> ${nextTarget}.`);
+            return;
+        }
+        this.feed?.publish({
+            level: "info",
+            kind: "workflow",
+            issueKey: refreshedIssue.issueKey,
+            projectId: stageRun.projectId,
+            stage: stageRun.stage,
+            ...(refreshedIssue.selectedWorkflowId ? { workflowId: refreshedIssue.selectedWorkflowId } : {}),
+            nextStage: nextTarget,
+            status: "transition_chosen",
+            summary: `Chose ${stageRun.stage} -> ${nextTarget}`,
+            detail: handoff.nextLikelyStageText ? `Stage result suggested "${handoff.nextLikelyStageText}".` : "PatchRelay used the workflow policy default.",
+        });
+        this.stores.workflowCoordinator.setIssueDesiredStage(stageRun.projectId, stageRun.linearIssueId, nextTarget, {
+            desiredWebhookId: `auto-transition:${stageRun.id}:${nextTarget}`,
+            lifecycleStatus: "queued",
+        });
+    }
+    async checkAutomaticContinuationPreconditions(project, stageRun, issue, linear, linearIssue) {
+        const activeState = resolveActiveLinearState(project, stageRun.stage, issue.selectedWorkflowId);
+        if (activeState && normalizeLinearState(linearIssue.stateName) !== normalizeLinearState(activeState)) {
+            return {
+                allowed: false,
+                reason: `Linear moved from ${activeState} to ${linearIssue.stateName ?? "an unknown state"} while the stage was running.`,
+            };
+        }
+        const actorProfile = await linear.getActorProfile().catch(() => undefined);
+        if (actorProfile?.actorId && linearIssue.delegateId && linearIssue.delegateId !== actorProfile.actorId) {
+            return {
+                allowed: false,
+                reason: "The issue is no longer delegated to PatchRelay.",
+            };
+        }
+        const stageSession = stageRun.threadId ? this.stores.issueSessions.getIssueSessionByThreadId(stageRun.threadId) : undefined;
+        if (stageSession?.linkedAgentSessionId && issue.activeAgentSessionId !== stageSession.linkedAgentSessionId) {
+            return {
+                allowed: false,
+                reason: "The active Linear agent session changed while the stage was running.",
+            };
+        }
+        const recentInterruptions = this.listInterruptingWebhooksSince(stageRun, actorProfile?.actorId);
+        if (recentInterruptions.length > 0) {
+            return {
+                allowed: false,
+                reason: `A newer human webhook (${recentInterruptions[0]}) arrived while the stage was running.`,
+            };
+        }
+        return { allowed: true };
+    }
+    listInterruptingWebhooksSince(stageRun, patchRelayActorId) {
+        const events = this.stores.webhookEvents.listWebhookEventsForIssueSince(stageRun.linearIssueId, stageRun.startedAt);
+        const interrupts = [];
+        for (const event of events) {
+            const payload = safeJsonParse(event.payloadJson);
+            if (!payload) {
+                continue;
+            }
+            const normalized = normalizeWebhook({
+                webhookId: event.webhookId,
+                payload: payload,
+            });
+            if (patchRelayActorId && normalized.actor?.id === patchRelayActorId) {
+                continue;
+            }
+            if (normalized.triggerEvent === "commentCreated" ||
+                normalized.triggerEvent === "commentUpdated" ||
+                normalized.triggerEvent === "agentPrompted" ||
+                normalized.triggerEvent === "agentSessionCreated" ||
+                normalized.triggerEvent === "delegateChanged" ||
+                normalized.triggerEvent === "statusChanged") {
+                interrupts.push(normalized.triggerEvent);
+            }
+        }
+        return interrupts;
+    }
+    resolveTransitionTarget(project, stageRun, workflowDefinitionId, handoff) {
+        if (!handoff) {
+            return "human_needed";
+        }
+        const requestedTarget = handoff.resolvedNextStage;
+        if (requestedTarget) {
+            return transitionTargetAllowed(project, stageRun.stage, requestedTarget, workflowDefinitionId) ? requestedTarget : "human_needed";
+        }
+        if (handoff.suggestsHumanNeeded) {
+            return "human_needed";
+        }
+        return resolveDefaultTransitionTarget(project, stageRun.stage, workflowDefinitionId) ?? "human_needed";
+    }
+    countPriorTransitionAttempts(projectId, linearIssueId, currentStage, nextTarget) {
+        const stageHistory = this.stores.issueWorkflows
+            .listStageRunsForIssue(projectId, linearIssueId)
+            .filter((stageRun) => stageRun.status === "completed");
+        let count = 0;
+        for (let index = 0; index < stageHistory.length - 1; index += 1) {
+            const current = stageHistory[index];
+            const next = stageHistory[index + 1];
+            if (current?.stage === currentStage && next?.stage === nextTarget) {
+                count += 1;
+            }
+        }
+        return count;
+    }
+    async routeStageToHumanNeeded(project, stageRun, linearIssue, reason) {
+        const linear = await this.linearProvider.forProject(stageRun.projectId);
+        if (!linear) {
+            return;
+        }
+        const trackedIssue = this.stores.issueWorkflows.getTrackedIssue(stageRun.projectId, stageRun.linearIssueId);
+        const fallbackState = resolveFallbackLinearState(project, stageRun.stage, trackedIssue?.selectedWorkflowId) ??
+            linearIssue.workflowStates.find((state) => normalizeLinearState(state.name) === "human needed")?.name;
+        if (fallbackState) {
+            await linear.setIssueState(stageRun.linearIssueId, fallbackState);
+        }
+        this.stores.workflowCoordinator.setIssueDesiredStage(stageRun.projectId, stageRun.linearIssueId, undefined, {
+            lifecycleStatus: "paused",
+        });
+        this.stores.workflowCoordinator.upsertTrackedIssue({
+            projectId: stageRun.projectId,
+            linearIssueId: stageRun.linearIssueId,
+            ...(fallbackState ? { currentLinearState: fallbackState } : linearIssue.stateName ? { currentLinearState: linearIssue.stateName } : {}),
+            lifecycleStatus: "paused",
+        });
+        this.feed?.publish({
+            level: "warn",
+            kind: "workflow",
+            issueKey: trackedIssue?.issueKey,
+            projectId: stageRun.projectId,
+            stage: stageRun.stage,
+            ...(trackedIssue?.selectedWorkflowId ? { workflowId: trackedIssue.selectedWorkflowId } : {}),
+            status: "transition_suppressed",
+            summary: `Paused after ${stageRun.stage}`,
+            detail: reason,
+        });
+    }
     finishLedgerRun(projectId, linearIssueId, status, params) {
         const issueControl = this.stores.issueControl.getIssueControl(projectId, linearIssueId);
         if (!issueControl?.activeRunLeaseId) {
@@ -360,6 +585,7 @@ export class ServiceStageFinalizer {
             issueKey: issue?.issueKey,
             projectId: stageRun.projectId,
             stage: stageRun.stage,
+            ...(issue?.selectedWorkflowId ? { workflowId: issue.selectedWorkflowId } : {}),
             status: "running",
             summary: `Recovered ${stageRun.stage} workflow after restart`,
             detail: `Turn ${turn.turnId} resumed on the existing thread.`,
@@ -450,3 +676,18 @@ function buildRestartRecoveryPrompt(stage) {
         "When the work is actually complete, finish the normal workflow handoff for this stage.",
     ].join("\n");
 }
+function normalizeLinearState(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed.toLowerCase() : undefined;
+}
+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;
+}