patchrelay 0.7.10 → 0.8.0

package/dist/service-webhook-processor.js

@@ -138,6 +138,7 @@ export class ServiceWebhookProcessor {
             const receipt = this.ensureEventReceipt(event, project.id, routedIssue.id);
             const hydrated = await this.hydrateIssueContext(project.id, normalized);
             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) {
@@ -146,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,
@@ -168,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}` : ""}.`,

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;
         }

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,

package/dist/stage-lifecycle-publisher.js

@@ -1,6 +1,6 @@
-import { buildAwaitingHandoffSessionPlan, buildCompletedSessionPlan, buildRunningSessionPlan, } from "./agent-session-plan.js";
+import { buildAwaitingHandoffSessionPlan, buildCompletedSessionPlan, buildPreparingSessionPlan, buildRunningSessionPlan, } from "./agent-session-plan.js";
 import { buildAgentSessionExternalUrls } from "./agent-session-presentation.js";
-import { buildAwaitingHandoffComment, buildRunningStatusComment, resolveActiveLinearState, resolveWorkflowLabelCleanup, resolveWorkflowLabelNames, } from "./linear-workflow.js";
+import { buildAwaitingHandoffComment, buildHumanNeededComment, buildRunningStatusComment, resolveActiveLinearState, resolveWorkflowLabelCleanup, resolveWorkflowLabelNames, } from "./linear-workflow.js";
 import { sanitizeDiagnosticText } from "./utils.js";
 export class StageLifecyclePublisher {
     config;
@@ -16,7 +16,7 @@ export class StageLifecyclePublisher {
         this.feed = feed;
     }
     async markStageActive(project, issue, stageRun) {
-        const activeState = resolveActiveLinearState(project, stageRun.stage);
+        const activeState = resolveActiveLinearState(project, stageRun.stage, issue.selectedWorkflowId);
         const linear = await this.linearProvider.forProject(stageRun.projectId);
         if (!activeState || !linear) {
             return;
@@ -103,24 +103,30 @@ export class StageLifecyclePublisher {
     async publishStageCompletion(stageRun, enqueueIssue) {
         const refreshedIssue = this.stores.issueWorkflows.getTrackedIssue(stageRun.projectId, stageRun.linearIssueId);
         if (refreshedIssue?.desiredStage) {
+            const linear = await this.linearProvider.forProject(stageRun.projectId);
+            if (refreshedIssue.activeAgentSessionId && linear) {
+                await this.updateAgentSession(linear, refreshedIssue, buildPreparingSessionPlan(refreshedIssue.desiredStage), refreshedIssue.desiredStage);
+            }
             this.feed?.publish({
                 level: "info",
                 kind: "stage",
                 issueKey: refreshedIssue.issueKey,
                 projectId: refreshedIssue.projectId,
                 stage: stageRun.stage,
+                ...(refreshedIssue.selectedWorkflowId ? { workflowId: refreshedIssue.selectedWorkflowId } : {}),
+                nextStage: refreshedIssue.desiredStage,
                 status: "queued",
                 summary: `Completed ${stageRun.stage} workflow and queued ${refreshedIssue.desiredStage}`,
             });
             await this.publishAgentCompletion(refreshedIssue, {
                 type: "thought",
-                body: `The ${stageRun.stage} workflow finished. PatchRelay is preparing the next requested workflow.`,
+                body: `The ${stageRun.stage} workflow finished. PatchRelay is preparing the ${refreshedIssue.desiredStage} workflow next.`,
             });
             enqueueIssue(stageRun.projectId, stageRun.linearIssueId);
             return;
         }
         const project = this.config.projects.find((candidate) => candidate.id === stageRun.projectId);
-        const activeState = project ? resolveActiveLinearState(project, stageRun.stage) : undefined;
+        const activeState = project ? resolveActiveLinearState(project, stageRun.stage, refreshedIssue?.selectedWorkflowId) : undefined;
         const linear = project ? await this.linearProvider.forProject(stageRun.projectId) : undefined;
         if (refreshedIssue && linear && project && activeState) {
             try {
@@ -146,6 +152,7 @@ export class StageLifecyclePublisher {
                         issueKey: refreshedIssue.issueKey,
                         projectId: refreshedIssue.projectId,
                         stage: stageRun.stage,
+                        ...(refreshedIssue.selectedWorkflowId ? { workflowId: refreshedIssue.selectedWorkflowId } : {}),
                         status: "handoff",
                         summary: `Completed ${stageRun.stage} workflow`,
                         detail: `Waiting for a Linear state change or follow-up input while the issue remains in ${activeState}.`,
@@ -188,8 +195,11 @@ export class StageLifecyclePublisher {
             }
         }
         if (refreshedIssue) {
+            let deliveredToSession = false;
             if (refreshedIssue.activeAgentSessionId && linear) {
-                await this.updateAgentSession(linear, refreshedIssue, buildCompletedSessionPlan(stageRun.stage));
+                deliveredToSession = await this.updateAgentSession(linear, refreshedIssue, refreshedIssue.lifecycleStatus === "paused"
+                    ? buildAwaitingHandoffSessionPlan(stageRun.stage)
+                    : buildCompletedSessionPlan(stageRun.stage));
             }
             this.feed?.publish({
                 level: "info",
@@ -197,13 +207,28 @@ export class StageLifecyclePublisher {
                 issueKey: refreshedIssue.issueKey,
                 projectId: refreshedIssue.projectId,
                 stage: stageRun.stage,
+                ...(refreshedIssue.selectedWorkflowId ? { workflowId: refreshedIssue.selectedWorkflowId } : {}),
                 status: "completed",
                 summary: `Completed ${stageRun.stage} workflow`,
             });
-            await this.publishAgentCompletion(refreshedIssue, {
-                type: "response",
-                body: `PatchRelay finished the ${stageRun.stage} workflow.`,
-            });
+            deliveredToSession =
+                (await this.publishAgentCompletion(refreshedIssue, {
+                    type: refreshedIssue.lifecycleStatus === "paused" ? "elicitation" : "response",
+                    body: refreshedIssue.lifecycleStatus === "paused"
+                        ? `PatchRelay finished the ${stageRun.stage} workflow and now needs human input before it can continue.`
+                        : `PatchRelay finished the ${stageRun.stage} workflow.`,
+                })) || deliveredToSession;
+            if (refreshedIssue.lifecycleStatus === "paused" && linear && !deliveredToSession) {
+                const result = await linear.upsertIssueComment({
+                    issueId: stageRun.linearIssueId,
+                    ...(refreshedIssue.statusCommentId ? { commentId: refreshedIssue.statusCommentId } : {}),
+                    body: buildHumanNeededComment({
+                        issue: refreshedIssue,
+                        stageRun: this.stores.issueWorkflows.getStageRun(stageRun.id) ?? stageRun,
+                    }),
+                });
+                this.stores.workflowCoordinator.setIssueStatusComment(stageRun.projectId, stageRun.linearIssueId, result.id);
+            }
         }
     }
     async updateAgentSession(linear, issue, plan, stage) {

package/dist/webhook-agent-session-handler.js

@@ -35,7 +35,15 @@ export class AgentSessionWebhookHandler {
         const issueControl = normalized.issue ? this.stores.issueControl.getIssueControl(project.id, normalized.issue.id) : undefined;
         const activeRunLease = issueControl?.activeRunLeaseId !== undefined ? this.stores.runLeases.getRunLease(issueControl.activeRunLeaseId) : undefined;
         const activeStage = activeRunLease?.stage;
-        const runnableWorkflow = normalized.issue?.stateName ? resolveWorkflowStage(project, normalized.issue.stateName) : undefined;
+        const runnableWorkflow = normalized.issue?.stateName
+            ? resolveWorkflowStage(project, normalized.issue.stateName, {
+                ...(issue?.selectedWorkflowId
+                    ? { workflowDefinitionId: issue.selectedWorkflowId }
+                    : normalized.issue
+                        ? { issue: normalized.issue }
+                        : {}),
+            })
+            : undefined;
         if (normalized.triggerEvent === "agentSessionCreated") {
             if (!delegatedToPatchRelay) {
                 if (activeStage) {

package/dist/webhook-desired-stage-recorder.js

@@ -1,5 +1,5 @@
 import { triggerEventAllowed } from "./project-resolution.js";
-import { resolveWorkflowStage } from "./workflow-policy.js";
+import { resolveWorkflowStage, selectWorkflowDefinition } from "./workflow-policy.js";
 function trimPrompt(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
@@ -25,7 +25,8 @@ export class WebhookDesiredStageRecorder {
         const activeStageRun = issueControl?.activeRunLeaseId !== undefined ? this.stores.issueWorkflows.getStageRun(issueControl.activeRunLeaseId) : undefined;
         const delegatedToPatchRelay = this.isDelegatedToPatchRelay(project, normalized);
         const stageAllowed = triggerEventAllowed(project, normalized.triggerEvent);
-        const desiredStage = this.resolveDesiredStage(project, normalized, issue, activeStageRun, delegatedToPatchRelay);
+        const selectedWorkflowId = this.resolveSelectedWorkflowId(project, normalized, issue, activeStageRun, delegatedToPatchRelay);
+        const desiredStage = this.resolveDesiredStage(project, normalized, issue, activeStageRun, delegatedToPatchRelay, selectedWorkflowId);
         const launchInput = this.resolveLaunchInput(normalized.agentSession);
         const activeAgentSessionId = normalized.agentSession?.id ??
             (!activeStageRun && (desiredStage || (normalized.triggerEvent === "delegateChanged" && !delegatedToPatchRelay)) ? null : undefined);
@@ -36,6 +37,7 @@ export class WebhookDesiredStageRecorder {
             ...(normalizedIssue.title ? { title: normalizedIssue.title } : {}),
             ...(normalizedIssue.url ? { issueUrl: normalizedIssue.url } : {}),
             ...(normalizedIssue.stateName ? { currentLinearState: normalizedIssue.stateName } : {}),
+            ...(selectedWorkflowId !== undefined ? { selectedWorkflowId } : {}),
             ...(desiredStage ? { desiredStage } : {}),
             ...(options?.eventReceiptId !== undefined ? { desiredReceiptId: options.eventReceiptId } : {}),
             ...(activeAgentSessionId !== undefined ? { activeAgentSessionId } : {}),
@@ -71,7 +73,7 @@ export class WebhookDesiredStageRecorder {
         }
         return normalizedIssue.delegateId === installation.actorId;
     }
-    resolveDesiredStage(project, normalized, issue, activeStageRun, delegatedToPatchRelay) {
+    resolveDesiredStage(project, normalized, issue, activeStageRun, delegatedToPatchRelay, selectedWorkflowId) {
         const normalizedIssue = normalized.issue;
         if (!normalizedIssue) {
             return undefined;
@@ -82,7 +84,9 @@ export class WebhookDesiredStageRecorder {
         if (!delegatedToPatchRelay || !triggerEventAllowed(project, normalized.triggerEvent)) {
             return undefined;
         }
-        const desiredStage = resolveWorkflowStage(project, normalizedIssue.stateName);
+        const desiredStage = resolveWorkflowStage(project, normalizedIssue.stateName, {
+            ...(selectedWorkflowId ? { workflowDefinitionId: selectedWorkflowId } : {}),
+        });
         if (!desiredStage) {
             return undefined;
         }
@@ -94,6 +98,22 @@ export class WebhookDesiredStageRecorder {
         }
         return desiredStage;
     }
+    resolveSelectedWorkflowId(project, normalized, issue, activeStageRun, delegatedToPatchRelay) {
+        if (activeStageRun) {
+            return issue?.selectedWorkflowId;
+        }
+        if (normalized.triggerEvent !== "agentSessionCreated" && normalized.triggerEvent !== "agentPrompted") {
+            return issue?.selectedWorkflowId;
+        }
+        if (!delegatedToPatchRelay || !triggerEventAllowed(project, normalized.triggerEvent) || !normalized.issue) {
+            return issue?.selectedWorkflowId;
+        }
+        const selectedWorkflow = selectWorkflowDefinition(project, normalized.issue);
+        if (selectedWorkflow) {
+            return selectedWorkflow.id;
+        }
+        return null;
+    }
     resolveLaunchInput(agentSession) {
         const promptBody = trimPrompt(agentSession?.promptBody);
         if (promptBody) {

package/dist/workflow-policy.js

@@ -2,6 +2,9 @@ function normalize(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed.toLowerCase() : undefined;
 }
+function normalizeWorkflowLabel(value) {
+    return normalize(value)?.replace(/[\s_-]+/g, "");
+}
 function extractIssuePrefix(identifier) {
     const value = identifier?.trim();
     if (!value) {
@@ -10,25 +13,129 @@ function extractIssuePrefix(identifier) {
     const [prefix] = value.split("-", 1);
     return prefix ? prefix.toUpperCase() : undefined;
 }
-export function resolveWorkflow(project, stateName) {
+function withWorkflowDefinitionId(workflowDefinitionId) {
+    return workflowDefinitionId ? { workflowDefinitionId } : undefined;
+}
+export function listProjectWorkflowDefinitions(project) {
+    if (project.workflowDefinitions && project.workflowDefinitions.length > 0) {
+        return project.workflowDefinitions;
+    }
+    return [
+        {
+            id: project.workflowSelection?.defaultWorkflowId ?? "default",
+            stages: project.workflows,
+        },
+    ];
+}
+export function resolveWorkflowDefinitionById(project, workflowDefinitionId) {
+    const normalized = normalize(workflowDefinitionId);
+    if (!normalized) {
+        return undefined;
+    }
+    return listProjectWorkflowDefinitions(project).find((definition) => normalize(definition.id) === normalized);
+}
+export function selectWorkflowDefinition(project, issue) {
+    const workflowDefinitions = listProjectWorkflowDefinitions(project);
+    if (workflowDefinitions.length === 0) {
+        return undefined;
+    }
+    const labelNames = new Set((issue?.labelNames ?? []).map((label) => label.trim().toLowerCase()).filter(Boolean));
+    const matchedWorkflowIds = new Set();
+    for (const rule of project.workflowSelection?.byLabel ?? []) {
+        if (labelNames.has(rule.label.trim().toLowerCase())) {
+            matchedWorkflowIds.add(rule.workflowId);
+        }
+    }
+    if (matchedWorkflowIds.size === 1) {
+        const [workflowId] = [...matchedWorkflowIds];
+        return resolveWorkflowDefinitionById(project, workflowId);
+    }
+    if (matchedWorkflowIds.size > 1) {
+        return undefined;
+    }
+    if (project.workflowSelection?.defaultWorkflowId) {
+        return resolveWorkflowDefinitionById(project, project.workflowSelection.defaultWorkflowId);
+    }
+    return workflowDefinitions[0];
+}
+function resolveStageList(project, options) {
+    if (options?.workflowDefinitionId) {
+        return resolveWorkflowDefinitionById(project, options.workflowDefinitionId)?.stages ?? [];
+    }
+    if (options?.issue) {
+        return selectWorkflowDefinition(project, options.issue)?.stages ?? [];
+    }
+    return project.workflows;
+}
+export function resolveWorkflow(project, stateName, options) {
     const normalized = normalize(stateName);
     if (!normalized) {
         return undefined;
     }
-    return project.workflows.find((workflow) => normalize(workflow.whenState) === normalized);
+    return resolveStageList(project, options).find((workflow) => normalize(workflow.whenState) === normalized);
 }
-export function resolveWorkflowStage(project, stateName) {
-    return resolveWorkflow(project, stateName)?.id;
+export function resolveWorkflowStage(project, stateName, options) {
+    return resolveWorkflow(project, stateName, options)?.id;
 }
-export function resolveWorkflowById(project, workflowId) {
+export function resolveWorkflowStageConfig(project, workflowId, workflowDefinitionId) {
     const normalized = normalize(workflowId);
     if (!normalized) {
         return undefined;
     }
-    return project.workflows.find((workflow) => normalize(workflow.id) === normalized);
+    return resolveStageList(project, withWorkflowDefinitionId(workflowDefinitionId)).find((workflow) => normalize(workflow.id) === normalized);
+}
+export function listRunnableStates(project, options) {
+    return [...new Set(resolveStageList(project, options).map((workflow) => workflow.whenState))];
+}
+export function listWorkflowStageIds(project, workflowDefinitionId) {
+    return resolveStageList(project, withWorkflowDefinitionId(workflowDefinitionId)).map((workflow) => workflow.id);
+}
+export function resolveWorkflowIndex(project, workflowId, workflowDefinitionId) {
+    if (!workflowId) {
+        return -1;
+    }
+    return resolveStageList(project, withWorkflowDefinitionId(workflowDefinitionId)).findIndex((workflow) => workflow.id === workflowId);
 }
-export function listRunnableStates(project) {
-    return project.workflows.map((workflow) => workflow.whenState);
+export function resolveDefaultTransitionTarget(project, currentStage, workflowDefinitionId) {
+    const stages = resolveStageList(project, withWorkflowDefinitionId(workflowDefinitionId));
+    const currentIndex = resolveWorkflowIndex(project, currentStage, workflowDefinitionId);
+    if (currentIndex < 0) {
+        return undefined;
+    }
+    const nextStage = stages[currentIndex + 1]?.id;
+    return nextStage ?? "done";
+}
+export function listAllowedTransitionTargets(project, currentStage, workflowDefinitionId) {
+    const stages = resolveStageList(project, withWorkflowDefinitionId(workflowDefinitionId));
+    const currentIndex = resolveWorkflowIndex(project, currentStage, workflowDefinitionId);
+    if (currentIndex < 0) {
+        return ["human_needed"];
+    }
+    const targets = new Set(["human_needed"]);
+    const defaultTarget = resolveDefaultTransitionTarget(project, currentStage, workflowDefinitionId);
+    if (defaultTarget) {
+        targets.add(defaultTarget);
+    }
+    if (currentIndex > 0) {
+        targets.add(stages[currentIndex - 1].id);
+    }
+    if (currentIndex > 1) {
+        targets.add(stages[0].id);
+    }
+    return [...targets];
+}
+export function transitionTargetAllowed(project, currentStage, nextTarget, workflowDefinitionId) {
+    return listAllowedTransitionTargets(project, currentStage, workflowDefinitionId).includes(nextTarget);
+}
+export function resolveWorkflowStageCandidate(project, value, workflowDefinitionId) {
+    const normalized = normalizeWorkflowLabel(value);
+    if (!normalized) {
+        return undefined;
+    }
+    return resolveStageList(project, withWorkflowDefinitionId(workflowDefinitionId)).find((workflow) => {
+        const candidates = [workflow.id, workflow.whenState, workflow.activeState];
+        return candidates.some((candidate) => normalizeWorkflowLabel(candidate) === normalized);
+    })?.id;
 }
 export function matchesProject(issue, project) {
     const issuePrefix = extractIssuePrefix(issue.identifier);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchrelay",
-  "version": "0.7.10",
+  "version": "0.8.0",
   "license": "MIT",
   "type": "module",
   "repository": {