patchrelay 0.7.9 → 0.8.0

package/dist/service-stage-runner.js

@@ -3,6 +3,7 @@ import { syncFailedStageToLinear } from "./stage-failure.js";
 import { buildFailedStageReport } 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 { WorktreeManager } from "./worktree-manager.js";
 export class ServiceStageRunner {
     config;
@@ -47,7 +48,20 @@ export class ServiceStageRunner {
             return;
         }
         const existingWorkspace = this.stores.workspaceOwnership.getWorkspaceOwnershipForIssue(item.projectId, item.issueId);
-        const defaultPlan = buildStageLaunchPlan(project, issue, desiredStage);
+        const stageHistory = this.stores.issueWorkflows.listStageRunsForIssue(item.projectId, item.issueId);
+        const previousStageRun = stageHistory.at(-1);
+        const defaultPlan = buildStageLaunchPlan(project, issue, desiredStage, {
+            ...(previousStageRun ? { previousStageRun } : {}),
+            ...(existingWorkspace
+                ? {
+                    workspace: {
+                        branchName: existingWorkspace.branchName,
+                        worktreePath: existingWorkspace.worktreePath,
+                    },
+                }
+                : {}),
+            stageHistory,
+        });
         const plan = existingWorkspace
             ? {
                 ...defaultPlan,
@@ -61,6 +75,7 @@ export class ServiceStageRunner {
             issueKey: issue.issueKey,
             projectId: item.projectId,
             stage: desiredStage,
+            ...(issue.selectedWorkflowId ? { workflowId: issue.selectedWorkflowId } : {}),
             status: "starting",
             summary: `Starting ${desiredStage} workflow`,
             detail: `Preparing ${plan.branchName}`,
@@ -85,12 +100,17 @@ export class ServiceStageRunner {
                 allowExistingOutsideRoot: existingWorkspace !== undefined,
             });
             await this.lifecyclePublisher.markStageActive(project, claim.issue, claim.stageRun);
-            threadLaunch = await this.launchStageThread(item.projectId, item.issueId, claim.stageRun.id, plan.worktreePath, issue.issueKey);
+            threadLaunch = await this.launchStageThread(item.projectId, item.issueId, claim.stageRun.id, plan.worktreePath);
+            const pendingLaunchInput = this.collectPendingLaunchInput(item.projectId, item.issueId);
+            const initialTurnInput = pendingLaunchInput.combinedInput
+                ? [plan.prompt, "", pendingLaunchInput.combinedInput].join("\n")
+                : plan.prompt;
             turn = await this.codex.startTurn({
                 threadId: threadLaunch.threadId,
                 cwd: plan.worktreePath,
-                input: plan.prompt,
+                input: initialTurnInput,
             });
+            this.completeDeliveredLaunchInput(pendingLaunchInput.obligationIds, claim.stageRun.id, threadLaunch.threadId, turn.turnId);
         }
         catch (error) {
             const err = error instanceof Error ? error : new Error(String(error));
@@ -122,19 +142,8 @@ export class ServiceStageRunner {
             turnId: turn.turnId,
         });
         this.inputDispatcher.routePendingInputs(claim.stageRun, threadLaunch.threadId, turn.turnId);
-        await this.inputDispatcher.flush({
-            id: claim.stageRun.id,
-            projectId: claim.stageRun.projectId,
-            linearIssueId: claim.stageRun.linearIssueId,
-            threadId: threadLaunch.threadId,
-            turnId: turn.turnId,
-        }, {
-            logFailures: true,
-            failureMessage: "Failed to deliver queued Linear comment during stage startup",
-            ...(claim.issue.issueKey ? { issueKey: claim.issue.issueKey } : {}),
-        });
         const deliveredToSession = await this.lifecyclePublisher.publishStageStarted(claim.issue, claim.stageRun.stage);
-        if (!deliveredToSession) {
+        if (!deliveredToSession && !claim.issue.activeAgentSessionId) {
             await this.lifecyclePublisher.refreshRunningStatusComment(item.projectId, item.issueId, claim.stageRun.id, issue.issueKey);
         }
         this.logger.info({
@@ -151,11 +160,45 @@ export class ServiceStageRunner {
             issueKey: issue.issueKey,
             projectId: item.projectId,
             stage: claim.stageRun.stage,
+            ...(claim.issue.selectedWorkflowId ? { workflowId: claim.issue.selectedWorkflowId } : {}),
             status: "running",
             summary: `Started ${claim.stageRun.stage} workflow`,
             detail: `Turn ${turn.turnId} is running in ${plan.branchName}.`,
         });
     }
+    collectPendingLaunchInput(projectId, issueId) {
+        const obligationIds = [];
+        const bodies = [];
+        for (const obligation of this.stores.obligations.listPendingObligations({ kind: "deliver_turn_input" })) {
+            if (obligation.projectId !== projectId ||
+                obligation.linearIssueId !== issueId ||
+                !obligation.source.startsWith("linear-agent-launch:")) {
+                continue;
+            }
+            const payload = safeJsonParse(obligation.payloadJson);
+            const body = payload?.body?.trim();
+            if (!body) {
+                this.stores.obligations.markObligationStatus(obligation.id, "failed", "obligation payload had no deliverable body");
+                continue;
+            }
+            obligationIds.push(obligation.id);
+            bodies.push(body);
+        }
+        return {
+            ...(bodies.length > 0 ? { combinedInput: bodies.join("\n\n") } : {}),
+            obligationIds,
+        };
+    }
+    completeDeliveredLaunchInput(obligationIds, runLeaseId, threadId, turnId) {
+        for (const obligationId of obligationIds) {
+            this.stores.obligations.updateObligationRouting(obligationId, {
+                runLeaseId,
+                threadId,
+                turnId,
+            });
+            this.stores.obligations.markObligationStatus(obligationId, "completed");
+        }
+    }
     async ensureLaunchIssueMirror(project, linearIssueId, _desiredStage, _desiredWebhookId) {
         const existing = this.stores.issueWorkflows.getTrackedIssue(project.id, linearIssueId);
         if (existing?.issueKey && existing.title && existing.issueUrl && existing.currentLinearState) {
@@ -179,7 +222,7 @@ export class ServiceStageRunner {
             lastWebhookAt: new Date().toISOString(),
         });
     }
-    async launchStageThread(projectId, issueId, stageRunId, worktreePath, issueKey) {
+    async launchStageThread(projectId, issueId, stageRunId, worktreePath) {
         const previousStageRun = this.stores.issueWorkflows
             .listStageRunsForIssue(projectId, issueId)
             .filter((stageRun) => stageRun.id !== stageRunId)
@@ -187,35 +230,10 @@ export class ServiceStageRunner {
         const parentThreadId = previousStageRun?.status === "completed" && isCodexThreadId(previousStageRun.threadId)
             ? previousStageRun.threadId
             : undefined;
-        if (parentThreadId) {
-            try {
-                const thread = await this.codex.forkThread(parentThreadId, worktreePath);
-                return {
-                    threadId: thread.id,
-                    parentThreadId,
-                };
-            }
-            catch (error) {
-                const err = error instanceof Error ? error : new Error(String(error));
-                this.logger.warn({
-                    issueKey,
-                    parentThreadId,
-                    error: err.message,
-                }, "Falling back to a fresh Codex thread after parent thread fork failed");
-                this.feed?.publish({
-                    level: "warn",
-                    kind: "turn",
-                    issueKey,
-                    projectId,
-                    status: "fallback",
-                    summary: "Could not fork the previous Codex thread",
-                    detail: "Starting a fresh thread instead.",
-                });
-            }
-        }
         const thread = await this.codex.startThread({ cwd: worktreePath });
         return {
             threadId: thread.id,
+            ...(parentThreadId ? { parentThreadId } : {}),
         };
     }
     async markLaunchFailed(project, issue, stageRun, message, threadId) {

package/dist/service-webhook-processor.js

@@ -45,7 +45,7 @@ export class ServiceWebhookProcessor {
                 this.markEventReceiptProcessed(event.webhookId, "failed");
                 throw new Error(`Stored webhook payload is invalid JSON: event ${webhookEventId}`);
             }
-            const normalized = normalizeWebhook({
+            let normalized = normalizeWebhook({
                 webhookId: event.webhookId,
                 payload,
             });
@@ -69,12 +69,25 @@ export class ServiceWebhookProcessor {
                 this.markEventReceiptProcessed(event.webhookId, "processed");
                 return;
             }
-            const project = resolveProject(this.config, normalized.issue);
+            let project = resolveProject(this.config, normalized.issue);
             if (!project) {
+                const routed = await this.tryHydrateProjectRoute(normalized);
+                if (routed) {
+                    normalized = routed.normalized;
+                    project = routed.project;
+                }
+            }
+            if (!project) {
+                const unresolvedIssue = normalized.issue;
+                if (!unresolvedIssue) {
+                    this.stores.webhookEvents.markWebhookProcessed(webhookEventId, "failed");
+                    this.markEventReceiptProcessed(event.webhookId, "failed");
+                    throw new Error(`Normalized issue context disappeared before routing webhook ${event.webhookId}`);
+                }
                 this.feed?.publish({
                     level: "warn",
                     kind: "webhook",
-                    issueKey: normalized.issue.identifier,
+                    issueKey: unresolvedIssue.identifier,
                     status: "ignored",
                     summary: "Ignored webhook with no matching project route",
                     detail: normalized.triggerEvent,
@@ -82,21 +95,27 @@ export class ServiceWebhookProcessor {
                 this.logger.info({
                     webhookEventId,
                     webhookId: event.webhookId,
-                    issueKey: normalized.issue.identifier,
-                    issueId: normalized.issue.id,
-                    teamId: normalized.issue.teamId,
-                    teamKey: normalized.issue.teamKey,
+                    issueKey: unresolvedIssue.identifier,
+                    issueId: unresolvedIssue.id,
+                    teamId: unresolvedIssue.teamId,
+                    teamKey: unresolvedIssue.teamKey,
                     triggerEvent: normalized.triggerEvent,
                 }, "Ignoring webhook because no project route matched the Linear issue");
                 this.stores.webhookEvents.markWebhookProcessed(webhookEventId, "processed");
                 this.markEventReceiptProcessed(event.webhookId, "processed");
                 return;
             }
+            const routedIssue = normalized.issue;
+            if (!routedIssue) {
+                this.stores.webhookEvents.markWebhookProcessed(webhookEventId, "failed");
+                this.markEventReceiptProcessed(event.webhookId, "failed");
+                throw new Error(`Normalized issue context disappeared while routing webhook ${event.webhookId}`);
+            }
             if (!trustedActorAllowed(project, normalized.actor)) {
                 this.feed?.publish({
                     level: "warn",
                     kind: "webhook",
-                    issueKey: normalized.issue.identifier,
+                    issueKey: routedIssue.identifier,
                     projectId: project.id,
                     status: "ignored",
                     summary: "Ignored webhook from an untrusted actor",
@@ -111,14 +130,15 @@ export class ServiceWebhookProcessor {
                     actorEmail: normalized.actor?.email,
                 }, "Ignoring webhook from untrusted Linear actor");
                 this.stores.webhookEvents.markWebhookProcessed(webhookEventId, "processed");
-                this.assignEventReceiptContext(event.webhookId, project.id, normalized.issue.id);
+                this.assignEventReceiptContext(event.webhookId, project.id, routedIssue.id);
                 this.markEventReceiptProcessed(event.webhookId, "processed");
                 return;
             }
             this.stores.webhookEvents.assignWebhookProject(webhookEventId, project.id);
-            const receipt = this.ensureEventReceipt(event, project.id, normalized.issue.id);
+            const receipt = this.ensureEventReceipt(event, project.id, routedIssue.id);
             const hydrated = await this.hydrateIssueContext(project.id, normalized);
-            const hydratedIssue = hydrated.issue ?? normalized.issue;
+            const hydratedIssue = hydrated.issue ?? routedIssue;
+            const priorIssue = this.stores.issueWorkflows.getTrackedIssue(project.id, hydratedIssue.id);
             const issueState = this.desiredStageRecorder.record(project, hydrated, receipt ? { eventReceiptId: receipt.id } : undefined);
             const observation = describeWebhookObservation(hydrated, issueState.delegatedToPatchRelay);
             if (observation) {
@@ -127,11 +147,29 @@ export class ServiceWebhookProcessor {
                     kind: observation.kind,
                     issueKey: hydratedIssue.identifier,
                     projectId: project.id,
+                    ...(issueState.issue?.selectedWorkflowId ? { workflowId: issueState.issue.selectedWorkflowId } : {}),
                     ...(observation.status ? { status: observation.status } : {}),
                     summary: observation.summary,
                     ...(observation.detail ? { detail: observation.detail } : {}),
                 });
             }
+            if (issueState.issue?.selectedWorkflowId &&
+                issueState.issue.selectedWorkflowId !== priorIssue?.selectedWorkflowId &&
+                (hydrated.triggerEvent === "agentSessionCreated" || hydrated.triggerEvent === "agentPrompted")) {
+                this.feed?.publish({
+                    level: "info",
+                    kind: "workflow",
+                    issueKey: hydratedIssue.identifier,
+                    projectId: project.id,
+                    workflowId: issueState.issue.selectedWorkflowId,
+                    ...(issueState.desiredStage ? { nextStage: issueState.desiredStage } : {}),
+                    status: "selected",
+                    summary: `Selected ${issueState.issue.selectedWorkflowId} workflow`,
+                    detail: issueState.desiredStage
+                        ? `PatchRelay will start with ${issueState.desiredStage} from ${hydratedIssue.stateName ?? "the current Linear state"}.`
+                        : undefined,
+                });
+            }
             await this.agentSessionHandler.handle({
                 normalized: hydrated,
                 project,
@@ -149,6 +187,7 @@ export class ServiceWebhookProcessor {
                     issueKey: hydratedIssue.identifier,
                     projectId: project.id,
                     stage: issueState.desiredStage,
+                    ...(issueState.issue?.selectedWorkflowId ? { workflowId: issueState.issue.selectedWorkflowId } : {}),
                     status: "queued",
                     summary: `Queued ${issueState.desiredStage} workflow`,
                     detail: `Triggered by ${hydrated.triggerEvent}${hydratedIssue.stateName ? ` from ${hydratedIssue.stateName}` : ""}.`,
@@ -229,6 +268,43 @@ export class ServiceWebhookProcessor {
             return normalized;
         }
     }
+    async tryHydrateProjectRoute(normalized) {
+        if (!normalized.issue) {
+            return undefined;
+        }
+        if (normalized.triggerEvent !== "agentSessionCreated" && normalized.triggerEvent !== "agentPrompted") {
+            return undefined;
+        }
+        for (const candidate of this.config.projects) {
+            const linear = await this.linearProvider.forProject(candidate.id);
+            if (!linear) {
+                continue;
+            }
+            try {
+                const liveIssue = await linear.getIssue(normalized.issue.id);
+                const hydrated = {
+                    ...normalized,
+                    issue: mergeIssueMetadata(normalized.issue, liveIssue),
+                };
+                const resolved = resolveProject(this.config, hydrated.issue);
+                if (resolved) {
+                    return {
+                        project: resolved,
+                        normalized: hydrated,
+                    };
+                }
+            }
+            catch (error) {
+                this.logger.debug({
+                    candidateProjectId: candidate.id,
+                    issueId: normalized.issue.id,
+                    triggerEvent: normalized.triggerEvent,
+                    error: sanitizeDiagnosticText(error instanceof Error ? error.message : String(error)),
+                }, "Failed to hydrate Linear issue context while resolving project route");
+            }
+        }
+        return undefined;
+    }
     assignEventReceiptContext(webhookId, projectId, linearIssueId) {
         const receipt = this.lookupEventReceipt(webhookId);
         if (!receipt) {

package/dist/service.js

@@ -12,6 +12,7 @@ function createServiceStores(db) {
         webhookEvents: db.webhookEvents,
         eventReceipts: db.eventReceipts,
         issueControl: db.issueControl,
+        issueSessions: db.issueSessions,
         workspaceOwnership: db.workspaceOwnership,
         runLeases: db.runLeases,
         obligations: db.obligations,

package/dist/stage-failure.js

@@ -9,10 +9,10 @@ export async function syncFailedStageToLinear(params) {
     if (!linear) {
         return;
     }
-    const fallbackState = resolveFallbackLinearState(params.project, params.stageRun.stage);
+    const fallbackState = resolveFallbackLinearState(params.project, params.stageRun.stage, params.issue.selectedWorkflowId);
     let shouldWriteFailureState = true;
     if (params.requireActiveLinearStateMatch) {
-        const activeState = resolveActiveLinearState(params.project, params.stageRun.stage);
+        const activeState = resolveActiveLinearState(params.project, params.stageRun.stage, params.issue.selectedWorkflowId);
         if (!activeState) {
             shouldWriteFailureState = false;
         }
@@ -71,7 +71,7 @@ export async function syncFailedStageToLinear(params) {
                 .then(() => true)
                 .catch(() => false)) || deliveredToSession;
     }
-    if (!deliveredToSession) {
+    if (!deliveredToSession && !params.issue.activeAgentSessionId) {
         const result = await linear
             .upsertIssueComment({
             issueId: params.stageRun.linearIssueId,

package/dist/stage-handoff.js

@@ -0,0 +1,107 @@
+import { safeJsonParse } from "./utils.js";
+import { listAllowedTransitionTargets, listWorkflowStageIds, resolveWorkflowStageCandidate } from "./workflow-policy.js";
+function normalize(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed.toLowerCase() : undefined;
+}
+function stripListPrefix(value) {
+    return value.replace(/^[-*•]\s+/, "").replace(/^\d+\.\s+/, "").trim();
+}
+function resolveTerminalTarget(value) {
+    const normalized = normalize(value)?.replace(/[\s_-]+/g, "");
+    if (!normalized) {
+        return undefined;
+    }
+    if (["done", "complete", "completed", "shipped", "ship"].includes(normalized)) {
+        return "done";
+    }
+    if (["humanneeded", "humaninput", "needsinput", "unclear", "unknown", "blocked", "ambiguous"].includes(normalized)) {
+        return "human_needed";
+    }
+    return undefined;
+}
+export function resolveWorkflowTarget(project, value) {
+    return resolveWorkflowTargetForDefinition(project, value);
+}
+export function resolveWorkflowTargetForDefinition(project, value, workflowDefinitionId) {
+    return resolveWorkflowStageCandidate(project, value, workflowDefinitionId) ?? resolveTerminalTarget(value);
+}
+function summarizeSignalsHumanNeeded(lines) {
+    const joined = normalize(lines.join(" "));
+    if (!joined) {
+        return false;
+    }
+    return ["blocked", "unclear", "ambiguous", "human input", "human needed", "need human", "cannot determine"].some((token) => joined.includes(token));
+}
+export function parseStageHandoff(project, assistantMessages, workflowDefinitionId) {
+    const latestMessage = [...assistantMessages].reverse().find((message) => typeof message === "string" && message.trim().length > 0);
+    if (!latestMessage) {
+        return undefined;
+    }
+    const lines = latestMessage
+        .split(/\r?\n/)
+        .map((line) => line.trimEnd());
+    const markerIndex = lines.findIndex((line) => /^stage result\s*:?\s*$/i.test(line.trim()));
+    const relevantLines = (markerIndex >= 0 ? lines.slice(markerIndex + 1) : lines)
+        .map((line) => stripListPrefix(line.trim()))
+        .filter(Boolean);
+    if (relevantLines.length === 0) {
+        return undefined;
+    }
+    const summaryLines = [];
+    let nextLikelyStageText;
+    let nextAttention;
+    for (const line of relevantLines) {
+        const nextStageMatch = line.match(/^next likely stage\s*:\s*(.+)$/i);
+        if (nextStageMatch) {
+            nextLikelyStageText = nextStageMatch[1]?.trim();
+            continue;
+        }
+        const attentionMatch = line.match(/^(next attention|what to watch|watch carefully|pay attention|human attention)\s*:\s*(.+)$/i);
+        if (attentionMatch) {
+            nextAttention = attentionMatch[2]?.trim();
+            continue;
+        }
+        summaryLines.push(line);
+    }
+    const resolvedNextStage = resolveWorkflowTargetForDefinition(project, nextLikelyStageText, workflowDefinitionId);
+    return {
+        sourceText: latestMessage,
+        summaryLines,
+        ...(nextLikelyStageText ? { nextLikelyStageText } : {}),
+        ...(nextAttention ? { nextAttention } : {}),
+        suggestsHumanNeeded: summarizeSignalsHumanNeeded(summaryLines),
+        ...(resolvedNextStage ? { resolvedNextStage } : {}),
+    };
+}
+export function extractPriorStageHandoff(project, stageRun, workflowDefinitionId) {
+    if (!stageRun?.reportJson) {
+        return undefined;
+    }
+    const report = safeJsonParse(stageRun.reportJson);
+    return report ? parseStageHandoff(project, report.assistantMessages, workflowDefinitionId) : undefined;
+}
+export function buildCarryForwardPrompt(params) {
+    const availableStages = listWorkflowStageIds(params.project, params.workflowDefinitionId);
+    const attemptNumber = params.stageHistory.filter((stageRun) => stageRun.stage === params.currentStage).length + 1;
+    const recentHistory = params.stageHistory.slice(-4).map((stageRun) => stageRun.stage);
+    const previousHandoff = extractPriorStageHandoff(params.project, params.previousStageRun, params.workflowDefinitionId);
+    const lines = [
+        `Workflow stage ids: ${availableStages.join(", ")}`,
+        `Allowed next targets from ${params.currentStage}: ${listAllowedTransitionTargets(params.project, params.currentStage, params.workflowDefinitionId).join(", ")}`,
+        `This is attempt ${attemptNumber} for the ${params.currentStage} stage.`,
+        recentHistory.length > 0 ? `Recent workflow history: ${recentHistory.join(" -> ")}` : undefined,
+        params.workspace?.branchName ? `Branch: ${params.workspace.branchName}` : undefined,
+        params.workspace?.worktreePath ? `Worktree: ${params.workspace.worktreePath}` : undefined,
+        params.previousStageRun ? "" : undefined,
+        params.previousStageRun ? "Carry-forward from the previous stage:" : undefined,
+        params.previousStageRun ? `- Prior stage: ${params.previousStageRun.stage}` : undefined,
+        previousHandoff?.summaryLines[0] ? `- Outcome: ${previousHandoff.summaryLines[0]}` : undefined,
+        previousHandoff && previousHandoff.summaryLines.length > 1
+            ? `- Key facts: ${previousHandoff.summaryLines.slice(1, 3).join(" ")}`
+            : undefined,
+        previousHandoff?.nextAttention ? `- Watch next: ${previousHandoff.nextAttention}` : undefined,
+        params.previousStageRun?.threadId ? `- Prior thread: ${params.previousStageRun.threadId}` : undefined,
+    ].filter((value) => Boolean(value));
+    return lines.length > 0 ? lines.join("\n") : undefined;
+}

package/dist/stage-launch.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { resolveWorkflowById } from "./workflow-policy.js";
+import { buildCarryForwardPrompt } from "./stage-handoff.js";
+import { listWorkflowStageIds, resolveWorkflowStageConfig } from "./workflow-policy.js";
 function slugify(value) {
     return value
         .toLowerCase()
@@ -17,8 +18,8 @@ export function isCodexThreadId(value) {
     }
     return !value.startsWith("missing-thread-") && !value.startsWith("launch-failed-");
 }
-export function buildStageLaunchPlan(project, issue, stage) {
-    const workflow = resolveWorkflowById(project, stage);
+export function buildStageLaunchPlan(project, issue, stage, options) {
+    const workflow = resolveWorkflowStageConfig(project, stage, issue.selectedWorkflowId);
     if (!workflow) {
         throw new Error(`Workflow "${stage}" is not configured for project ${project.id}`);
     }
@@ -26,15 +27,31 @@ export function buildStageLaunchPlan(project, issue, stage) {
     const slug = issue.title ? slugify(issue.title) : "";
     const branchSuffix = slug ? `${issueRef}-${slug}` : issueRef;
     return {
-        branchName: `${project.branchPrefix}/${branchSuffix}`,
-        worktreePath: path.join(project.worktreeRoot, issueRef),
+        branchName: options?.branchName ?? `${project.branchPrefix}/${branchSuffix}`,
+        worktreePath: options?.worktreePath ?? path.join(project.worktreeRoot, issueRef),
         workflowFile: workflow.workflowFile,
         stage,
-        prompt: buildStagePrompt(issue, workflow.id, workflow.whenState, workflow.workflowFile),
+        prompt: buildStagePrompt(project, issue, workflow.id, workflow.whenState, workflow.workflowFile, {
+            branchName: options?.branchName ?? `${project.branchPrefix}/${branchSuffix}`,
+            worktreePath: options?.worktreePath ?? path.join(project.worktreeRoot, issueRef),
+            ...(issue.selectedWorkflowId ? { workflowDefinitionId: issue.selectedWorkflowId } : {}),
+            ...(options?.previousStageRun ? { previousStageRun: options.previousStageRun } : {}),
+            ...(options?.workspace ? { workspace: options.workspace } : {}),
+            stageHistory: options?.stageHistory ?? [],
+        }),
     };
 }
-export function buildStagePrompt(issue, stage, triggerState, workflowFile) {
+export function buildStagePrompt(project, issue, stage, triggerState, workflowFile, options) {
     const workflowBody = existsSync(workflowFile) ? readFileSync(workflowFile, "utf8").trim() : "";
+    const carryForward = buildCarryForwardPrompt({
+        project,
+        currentStage: stage,
+        ...(options?.workflowDefinitionId ? { workflowDefinitionId: options.workflowDefinitionId } : {}),
+        ...(options?.previousStageRun ? { previousStageRun: options.previousStageRun } : {}),
+        ...(options?.workspace ? { workspace: options.workspace } : {}),
+        stageHistory: options?.stageHistory ?? [],
+    });
+    const availableStages = listWorkflowStageIds(project, options?.workflowDefinitionId).join(", ");
     return [
         `Issue: ${issue.issueKey ?? issue.linearIssueId}`,
         issue.title ? `Title: ${issue.title}` : undefined,
@@ -42,9 +59,22 @@ export function buildStagePrompt(issue, stage, triggerState, workflowFile) {
         issue.currentLinearState ? `Current Linear State: ${issue.currentLinearState}` : undefined,
         `Workflow: ${stage}`,
         `Triggered By State: ${triggerState}`,
+        options?.branchName ? `Branch: ${options.branchName}` : undefined,
+        options?.worktreePath ? `Worktree: ${options.worktreePath}` : undefined,
+        "",
+        "Complete only the current workflow stage. Do not invent a new workflow or skip directly to another stage.",
+        "If the correct next step is unclear, say so plainly and use `human_needed` as the next likely stage.",
+        "",
+        carryForward ? "Carry-forward Context:" : undefined,
+        carryForward,
         "",
         "Operate only inside the prepared worktree for this issue. Continue the issue lifecycle in this workspace.",
-        "Capture a crisp summary of what you did, what changed, and what remains blocked so PatchRelay can publish a read-only report.",
+        "Use the repo workflow instructions below for this stage.",
+        "End with a short `Stage result:` section in plain text with exactly four bullets:",
+        "- what happened",
+        "- key facts or artifacts",
+        `- Next likely stage: one of ${availableStages}, done, or human_needed`,
+        "- what the next stage or human should pay attention to",
         "",
         `Workflow File: ${path.basename(workflowFile)}`,
         workflowBody,