patchrelay 0.1.0

package/dist/service-webhook-processor.js

@@ -0,0 +1,181 @@
+import { resolveProject, trustedActorAllowed } from "./project-resolution.js";
+import { StageAgentActivityPublisher } from "./stage-agent-activity-publisher.js";
+import { StageTurnInputDispatcher } from "./stage-turn-input-dispatcher.js";
+import { safeJsonParse, sanitizeDiagnosticText } from "./utils.js";
+import { AgentSessionWebhookHandler } from "./webhook-agent-session-handler.js";
+import { CommentWebhookHandler } from "./webhook-comment-handler.js";
+import { WebhookDesiredStageRecorder } from "./webhook-desired-stage-recorder.js";
+import { InstallationWebhookHandler } from "./webhook-installation-handler.js";
+import { normalizeWebhook } from "./webhooks.js";
+export class ServiceWebhookProcessor {
+    config;
+    stores;
+    enqueueIssue;
+    logger;
+    desiredStageRecorder;
+    agentSessionHandler;
+    commentHandler;
+    installationHandler;
+    constructor(config, stores, linearProvider, codex, enqueueIssue, logger) {
+        this.config = config;
+        this.stores = stores;
+        this.enqueueIssue = enqueueIssue;
+        this.logger = logger;
+        const turnInputDispatcher = new StageTurnInputDispatcher(stores, codex, logger);
+        const agentActivity = new StageAgentActivityPublisher(linearProvider, logger);
+        this.desiredStageRecorder = new WebhookDesiredStageRecorder(stores);
+        this.agentSessionHandler = new AgentSessionWebhookHandler(stores, turnInputDispatcher, agentActivity);
+        this.commentHandler = new CommentWebhookHandler(stores, turnInputDispatcher);
+        this.installationHandler = new InstallationWebhookHandler(config, stores, logger);
+    }
+    async processWebhookEvent(webhookEventId) {
+        const event = this.stores.webhookEvents.getWebhookEvent(webhookEventId);
+        if (!event) {
+            this.logger.warn({ webhookEventId }, "Webhook event was not found during processing");
+            return;
+        }
+        try {
+            const payload = safeJsonParse(event.payloadJson);
+            if (!payload) {
+                this.stores.webhookEvents.markWebhookProcessed(webhookEventId, "failed");
+                this.markEventReceiptProcessed(event.webhookId, "failed");
+                throw new Error(`Stored webhook payload is invalid JSON: event ${webhookEventId}`);
+            }
+            const normalized = normalizeWebhook({
+                webhookId: event.webhookId,
+                payload,
+            });
+            this.logger.info({
+                webhookEventId,
+                webhookId: event.webhookId,
+                eventType: normalized.eventType,
+                triggerEvent: normalized.triggerEvent,
+                issueKey: normalized.issue?.identifier,
+                issueId: normalized.issue?.id,
+            }, "Processing stored webhook event");
+            if (!normalized.issue) {
+                this.installationHandler.handle(normalized);
+                this.stores.webhookEvents.markWebhookProcessed(webhookEventId, "processed");
+                this.markEventReceiptProcessed(event.webhookId, "processed");
+                return;
+            }
+            const project = resolveProject(this.config, normalized.issue);
+            if (!project) {
+                this.logger.info({
+                    webhookEventId,
+                    webhookId: event.webhookId,
+                    issueKey: normalized.issue.identifier,
+                    issueId: normalized.issue.id,
+                    teamId: normalized.issue.teamId,
+                    teamKey: normalized.issue.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;
+            }
+            if (!trustedActorAllowed(project, normalized.actor)) {
+                this.logger.info({
+                    webhookId: normalized.webhookId,
+                    projectId: project.id,
+                    triggerEvent: normalized.triggerEvent,
+                    actorId: normalized.actor?.id,
+                    actorName: normalized.actor?.name,
+                    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.markEventReceiptProcessed(event.webhookId, "processed");
+                return;
+            }
+            this.stores.webhookEvents.assignWebhookProject(webhookEventId, project.id);
+            const receipt = this.ensureEventReceipt(event, project.id, normalized.issue.id);
+            const issueState = this.desiredStageRecorder.record(project, normalized, receipt ? { eventReceiptId: receipt.id } : undefined);
+            await this.agentSessionHandler.handle({
+                normalized,
+                project,
+                issue: issueState.issue,
+                desiredStage: issueState.desiredStage,
+                delegatedToPatchRelay: issueState.delegatedToPatchRelay,
+            });
+            await this.commentHandler.handle(normalized, project);
+            this.stores.webhookEvents.markWebhookProcessed(webhookEventId, "processed");
+            this.markEventReceiptProcessed(event.webhookId, "processed");
+            if (issueState.desiredStage) {
+                this.logger.info({
+                    webhookEventId,
+                    webhookId: event.webhookId,
+                    projectId: project.id,
+                    issueKey: normalized.issue.identifier,
+                    issueId: normalized.issue.id,
+                    desiredStage: issueState.desiredStage,
+                    delegatedToPatchRelay: issueState.delegatedToPatchRelay,
+                }, "Recorded desired stage from webhook and enqueued issue execution");
+                this.enqueueIssue(project.id, normalized.issue.id);
+                return;
+            }
+            this.logger.info({
+                webhookEventId,
+                webhookId: event.webhookId,
+                projectId: project.id,
+                issueKey: normalized.issue.identifier,
+                issueId: normalized.issue.id,
+                triggerEvent: normalized.triggerEvent,
+                delegatedToPatchRelay: issueState.delegatedToPatchRelay,
+            }, "Processed webhook without enqueuing a new stage run");
+        }
+        catch (error) {
+            this.stores.webhookEvents.markWebhookProcessed(webhookEventId, "failed");
+            this.markEventReceiptProcessed(event.webhookId, "failed");
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger.error({
+                webhookEventId,
+                webhookId: event.webhookId,
+                issueId: event.issueId,
+                projectId: event.projectId,
+                error: sanitizeDiagnosticText(err.message),
+                stack: err.stack,
+            }, "Failed to process Linear webhook event");
+            throw err;
+        }
+    }
+    assignEventReceiptContext(webhookId, projectId, linearIssueId) {
+        const receipt = this.lookupEventReceipt(webhookId);
+        if (!receipt) {
+            return;
+        }
+        this.stores.eventReceipts.assignEventReceiptContext(receipt.id, {
+            ...(projectId ? { projectId } : {}),
+            ...(linearIssueId ? { linearIssueId } : {}),
+        });
+    }
+    markEventReceiptProcessed(webhookId, status) {
+        const receipt = this.lookupEventReceipt(webhookId);
+        if (!receipt) {
+            return;
+        }
+        this.stores.eventReceipts.markEventReceiptProcessed(receipt.id, status);
+    }
+    lookupEventReceipt(webhookId) {
+        return this.stores.eventReceipts.getEventReceiptBySourceExternalId("linear-webhook", webhookId);
+    }
+    ensureEventReceipt(event, projectId, linearIssueId) {
+        const existing = this.lookupEventReceipt(event.webhookId);
+        if (existing) {
+            this.assignEventReceiptContext(event.webhookId, projectId, linearIssueId);
+            return existing;
+        }
+        const inserted = this.stores.eventReceipts.insertEventReceipt({
+            source: "linear-webhook",
+            externalId: event.webhookId,
+            eventType: event.eventType,
+            receivedAt: event.receivedAt,
+            acceptanceStatus: "accepted",
+            ...(projectId ? { projectId } : {}),
+            ...(linearIssueId ? { linearIssueId } : {}),
+            headersJson: event.headersJson,
+            payloadJson: event.payloadJson,
+        });
+        return this.stores.eventReceipts.getEventReceipt(inserted.id);
+    }
+}

package/dist/service-webhooks.js

@@ -0,0 +1,148 @@
+import { archiveWebhook } from "./webhook-archive.js";
+import { normalizeWebhook } from "./webhooks.js";
+import { redactSensitiveHeaders, timestampMsWithinSkew, verifyHmacSha256Hex } from "./utils.js";
+export async function acceptIncomingWebhook(params) {
+    const receivedAt = new Date().toISOString();
+    const signature = typeof params.headers["linear-signature"] === "string" ? params.headers["linear-signature"] : "";
+    if (!verifyHmacSha256Hex(params.rawBody, params.config.linear.webhookSecret, signature)) {
+        params.logger.warn({ webhookId: params.webhookId }, "Rejecting webhook with invalid signature");
+        return { status: 401, body: { ok: false, reason: "invalid_signature" } };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(params.rawBody.toString("utf8"));
+    }
+    catch {
+        params.logger.warn({ webhookId: params.webhookId }, "Rejecting malformed webhook payload");
+        return { status: 400, body: { ok: false, reason: "invalid_json" } };
+    }
+    if (!timestampMsWithinSkew(payload.webhookTimestamp, params.config.ingress.maxTimestampSkewSeconds)) {
+        params.logger.warn({ webhookId: params.webhookId, webhookTimestamp: payload.webhookTimestamp }, "Rejecting stale webhook payload");
+        return { status: 401, body: { ok: false, reason: "stale_timestamp" } };
+    }
+    let normalized;
+    try {
+        normalized = normalizeWebhook({
+            webhookId: params.webhookId,
+            payload,
+        });
+    }
+    catch (error) {
+        params.logger.warn({ webhookId: params.webhookId, error }, "Rejecting unsupported webhook payload");
+        return { status: 400, body: { ok: false, reason: "unsupported_payload" } };
+    }
+    const sanitizedHeaders = redactSensitiveHeaders(params.headers);
+    const headersJson = JSON.stringify(sanitizedHeaders);
+    const payloadJson = JSON.stringify(payload);
+    logWebhookSummary(params.logger, normalized);
+    await archiveAcceptedPayload({
+        config: params.config,
+        logger: params.logger,
+        webhookId: params.webhookId,
+        receivedAt,
+        headers: params.headers,
+        rawBody: params.rawBody,
+        payload,
+    });
+    const stored = params.stores.webhookEvents.insertWebhookEvent({
+        webhookId: params.webhookId,
+        receivedAt,
+        eventType: normalized.eventType,
+        ...(normalized.issue ? { issueId: normalized.issue.id } : {}),
+        headersJson,
+        payloadJson,
+        signatureValid: true,
+        dedupeStatus: "accepted",
+    });
+    if (!stored.inserted) {
+        recordEventReceipt(params.stores, {
+            webhookId: params.webhookId,
+            receivedAt,
+            normalized,
+            headersJson,
+            payloadJson,
+        });
+        params.logger.info({ webhookId: params.webhookId, webhookEventId: stored.id }, "Ignoring duplicate webhook delivery");
+        return { status: 200, body: { ok: true, duplicate: true } };
+    }
+    recordEventReceipt(params.stores, {
+        webhookId: params.webhookId,
+        receivedAt,
+        normalized,
+        headersJson,
+        payloadJson,
+    });
+    params.logger.info({
+        webhookId: params.webhookId,
+        webhookEventId: stored.id,
+        triggerEvent: normalized.triggerEvent,
+        issueKey: normalized.issue?.identifier,
+        issueId: normalized.issue?.id,
+    }, "Accepted Linear webhook for asynchronous processing");
+    return {
+        accepted: {
+            id: stored.id,
+            normalized,
+            payload,
+        },
+        status: 200,
+        body: { ok: true, accepted: true, webhookEventId: stored.id },
+    };
+}
+function recordEventReceipt(stores, params) {
+    stores.eventReceipts.insertEventReceipt({
+        source: "linear-webhook",
+        externalId: params.webhookId,
+        eventType: params.normalized.eventType,
+        receivedAt: params.receivedAt,
+        acceptanceStatus: "accepted",
+        ...(params.normalized.issue ? { linearIssueId: params.normalized.issue.id } : {}),
+        headersJson: params.headersJson,
+        payloadJson: params.payloadJson,
+    });
+}
+function logWebhookSummary(logger, normalized) {
+    const issueRef = normalized.issue?.identifier ?? normalized.issue?.id ?? normalized.installation?.appUserId ?? normalized.entityType;
+    const stateName = normalized.issue?.stateName;
+    const title = normalized.issue?.title;
+    const summary = [
+        `Linear webhook for ${issueRef}`,
+        normalized.triggerEvent,
+        stateName ? `to ${stateName}` : undefined,
+        title ? `(${title})` : undefined,
+    ]
+        .filter(Boolean)
+        .join(" ");
+    logger.info({
+        issueKey: normalized.issue?.identifier,
+        triggerEvent: normalized.triggerEvent,
+        state: stateName,
+        title,
+        appUserId: normalized.installation?.appUserId,
+        notificationType: normalized.installation?.notificationType,
+    }, summary);
+    logger.debug({
+        webhookId: normalized.webhookId,
+        eventType: normalized.eventType,
+        issueId: normalized.issue?.id,
+    }, "Webhook metadata");
+}
+async function archiveAcceptedPayload(params) {
+    if (!params.config.logging.webhookArchiveDir) {
+        return;
+    }
+    try {
+        const archivePath = await archiveWebhook({
+            archiveDir: params.config.logging.webhookArchiveDir,
+            webhookId: params.webhookId,
+            receivedAt: params.receivedAt,
+            headers: redactSensitiveHeaders(params.headers),
+            rawBody: params.rawBody,
+            payload: params.payload,
+        });
+        params.logger.debug({ webhookId: params.webhookId, archivePath }, "Archived webhook to local file");
+    }
+    catch (error) {
+        params.logger.error({ webhookId: params.webhookId, error }, "Failed to archive webhook to local file");
+    }
+}

package/dist/service.js

@@ -0,0 +1,139 @@
+import { IssueQueryService } from "./issue-query-service.js";
+import { LinearOAuthService } from "./linear-oauth-service.js";
+import { ServiceRuntime } from "./service-runtime.js";
+import { ServiceStageFinalizer } from "./service-stage-finalizer.js";
+import { ServiceStageRunner } from "./service-stage-runner.js";
+import { ServiceWebhookProcessor } from "./service-webhook-processor.js";
+import { acceptIncomingWebhook } from "./service-webhooks.js";
+function createServiceStores(db) {
+    return {
+        webhookEvents: db.webhookEvents,
+        eventReceipts: db.eventReceipts,
+        issueControl: db.issueControl,
+        workspaceOwnership: db.workspaceOwnership,
+        runLeases: db.runLeases,
+        obligations: db.obligations,
+        issueWorkflows: db.issueWorkflows,
+        stageEvents: db.stageEvents,
+        linearInstallations: db.linearInstallations,
+    };
+}
+function createReadyIssueSource(stores) {
+    return {
+        listIssuesReadyForExecution: () => stores.issueControl.listIssueControlsReadyForLaunch().map((issue) => ({
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+        })),
+    };
+}
+// PatchRelayService wires together the harness layers:
+// - integration: webhook intake, OAuth, Linear client access
+// - coordination: runtime queueing, stage launch, completion, reconciliation
+// - execution: Codex app-server and worktree-backed stage runs
+// - observability: issue/report query surfaces
+export class PatchRelayService {
+    config;
+    db;
+    codex;
+    logger;
+    linearProvider;
+    stageRunner;
+    stageFinalizer;
+    webhookProcessor;
+    oauthService;
+    queryService;
+    runtime;
+    constructor(config, db, codex, linearProvider, logger) {
+        this.config = config;
+        this.db = db;
+        this.codex = codex;
+        this.logger = logger;
+        this.linearProvider = toLinearClientProvider(linearProvider);
+        const stores = createServiceStores(db);
+        this.stageRunner = new ServiceStageRunner(config, stores, codex, this.linearProvider, logger, (fn) => db.connection.transaction(fn)());
+        let enqueueIssue = () => {
+            throw new Error("Service runtime enqueueIssue is not initialized");
+        };
+        this.stageFinalizer = new ServiceStageFinalizer(config, stores, codex, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, (fn) => db.connection.transaction(fn)());
+        this.webhookProcessor = new ServiceWebhookProcessor(config, stores, this.linearProvider, codex, (projectId, issueId) => enqueueIssue(projectId, issueId), logger);
+        const runtime = new ServiceRuntime(codex, logger, this.stageFinalizer, createReadyIssueSource(stores), this.webhookProcessor, {
+            processIssue: (item) => this.stageRunner.run(item),
+        });
+        enqueueIssue = (projectId, issueId) => runtime.enqueueIssue(projectId, issueId);
+        this.oauthService = new LinearOAuthService(config, stores, logger);
+        this.queryService = new IssueQueryService(stores, codex, this.stageFinalizer);
+        this.runtime = runtime;
+        this.codex.on("notification", (notification) => {
+            void this.stageFinalizer.handleCodexNotification(notification);
+        });
+    }
+    async start() {
+        await this.runtime.start();
+    }
+    stop() {
+        this.runtime.stop();
+    }
+    createLinearOAuthStart(params) {
+        return this.oauthService.createStart(params);
+    }
+    async completeLinearOAuth(params) {
+        return await this.oauthService.complete(params);
+    }
+    getLinearOAuthStateStatus(state) {
+        return this.oauthService.getStateStatus(state);
+    }
+    listLinearInstallations() {
+        return this.oauthService.listInstallations();
+    }
+    getReadiness() {
+        return this.runtime.getReadiness();
+    }
+    async acceptWebhook(params) {
+        const result = await acceptIncomingWebhook({
+            config: this.config,
+            stores: {
+                webhookEvents: this.db.webhookEvents,
+                eventReceipts: this.db.eventReceipts,
+            },
+            logger: this.logger,
+            webhookId: params.webhookId,
+            headers: params.headers,
+            rawBody: params.rawBody,
+        });
+        if (result.accepted) {
+            this.runtime.enqueueWebhookEvent(result.accepted.id);
+        }
+        return {
+            status: result.status,
+            body: result.body,
+        };
+    }
+    async processWebhookEvent(webhookEventId) {
+        await this.webhookProcessor.processWebhookEvent(webhookEventId);
+    }
+    async processIssue(item) {
+        await this.stageRunner.run(item);
+    }
+    async getIssueOverview(issueKey) {
+        return await this.queryService.getIssueOverview(issueKey);
+    }
+    async getIssueReport(issueKey) {
+        return await this.queryService.getIssueReport(issueKey);
+    }
+    async getStageEvents(issueKey, stageRunId) {
+        return await this.queryService.getStageEvents(issueKey, stageRunId);
+    }
+    async getActiveStageStatus(issueKey) {
+        return await this.queryService.getActiveStageStatus(issueKey);
+    }
+}
+function toLinearClientProvider(linear) {
+    if (linear && typeof linear.forProject === "function") {
+        return linear;
+    }
+    return {
+        async forProject() {
+            return linear;
+        },
+    };
+}

package/dist/stage-agent-activity-publisher.js

@@ -0,0 +1,33 @@
+export class StageAgentActivityPublisher {
+    linearProvider;
+    logger;
+    constructor(linearProvider, logger) {
+        this.linearProvider = linearProvider;
+        this.logger = logger;
+    }
+    async publishForSession(projectId, agentSessionId, content) {
+        const linear = await this.linearProvider.forProject(projectId);
+        if (!linear) {
+            return;
+        }
+        try {
+            await linear.createAgentActivity({
+                agentSessionId,
+                content,
+                ephemeral: content.type === "thought" || content.type === "action",
+            });
+        }
+        catch (error) {
+            this.logger.warn({
+                agentSessionId,
+                error: error instanceof Error ? error.message : String(error),
+            }, "Failed to publish Linear agent activity");
+        }
+    }
+    async publishForIssue(issue, content) {
+        if (!issue.activeAgentSessionId) {
+            return;
+        }
+        await this.publishForSession(issue.projectId, issue.activeAgentSessionId, content);
+    }
+}

package/dist/stage-event-ports.js

@@ -0,0 +1 @@
+export {};

package/dist/stage-failure.js

@@ -0,0 +1,92 @@
+import { buildStageFailedComment, resolveActiveLinearState, resolveFallbackLinearState, resolveWorkflowLabelCleanup, } from "./linear-workflow.js";
+function normalizeStateName(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed.toLowerCase() : undefined;
+}
+export async function syncFailedStageToLinear(params) {
+    const linear = await params.linearProvider.forProject(params.stageRun.projectId);
+    if (!linear) {
+        return;
+    }
+    const fallbackState = resolveFallbackLinearState(params.project, params.stageRun.stage);
+    let shouldWriteFailureState = true;
+    if (params.requireActiveLinearStateMatch) {
+        const activeState = resolveActiveLinearState(params.project, params.stageRun.stage);
+        if (!activeState) {
+            shouldWriteFailureState = false;
+        }
+        else {
+            try {
+                const linearIssue = await linear.getIssue(params.stageRun.linearIssueId);
+                shouldWriteFailureState = normalizeStateName(linearIssue.stateName) === normalizeStateName(activeState);
+            }
+            catch {
+                shouldWriteFailureState = false;
+            }
+        }
+    }
+    const cleanup = resolveWorkflowLabelCleanup(params.project);
+    if (cleanup.remove.length > 0) {
+        await linear
+            .updateIssueLabels({
+            issueId: params.stageRun.linearIssueId,
+            removeNames: cleanup.remove,
+        })
+            .catch(() => undefined);
+    }
+    if (!shouldWriteFailureState) {
+        return;
+    }
+    if (fallbackState) {
+        await linear.setIssueState(params.stageRun.linearIssueId, fallbackState).catch(() => undefined);
+        params.stores.issueWorkflows.setIssueLifecycleStatus(params.stageRun.projectId, params.stageRun.linearIssueId, "failed");
+        params.stores.issueWorkflows.upsertTrackedIssue({
+            projectId: params.stageRun.projectId,
+            linearIssueId: params.stageRun.linearIssueId,
+            currentLinearState: fallbackState,
+            statusCommentId: params.issue.statusCommentId ?? null,
+            lifecycleStatus: "failed",
+        });
+        params.stores.issueControl.upsertIssueControl({
+            projectId: params.stageRun.projectId,
+            linearIssueId: params.stageRun.linearIssueId,
+            lifecycleStatus: "failed",
+            ...(params.issue.statusCommentId ? { serviceOwnedCommentId: params.issue.statusCommentId } : {}),
+            ...(params.issue.activeAgentSessionId ? { activeAgentSessionId: params.issue.activeAgentSessionId } : {}),
+        });
+    }
+    const result = await linear
+        .upsertIssueComment({
+        issueId: params.stageRun.linearIssueId,
+        ...(params.issue.statusCommentId ? { commentId: params.issue.statusCommentId } : {}),
+        body: buildStageFailedComment({
+            issue: params.issue,
+            stageRun: params.stageRun,
+            message: params.message,
+            ...(fallbackState ? { fallbackState } : {}),
+            ...(params.mode ? { mode: params.mode } : {}),
+        }),
+    })
+        .catch(() => undefined);
+    if (result) {
+        params.stores.issueWorkflows.setIssueStatusComment(params.stageRun.projectId, params.stageRun.linearIssueId, result.id);
+        params.stores.issueControl.upsertIssueControl({
+            projectId: params.stageRun.projectId,
+            linearIssueId: params.stageRun.linearIssueId,
+            serviceOwnedCommentId: result.id,
+            lifecycleStatus: "failed",
+            ...(params.issue.activeAgentSessionId ? { activeAgentSessionId: params.issue.activeAgentSessionId } : {}),
+        });
+    }
+    if (params.issue.activeAgentSessionId) {
+        await linear
+            .createAgentActivity({
+            agentSessionId: params.issue.activeAgentSessionId,
+            content: {
+                type: "error",
+                body: `PatchRelay could not complete the ${params.stageRun.stage} workflow: ${params.message}`,
+            },
+        })
+            .catch(() => undefined);
+    }
+}

package/dist/stage-launch.js

@@ -0,0 +1,54 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { resolveWorkflowById } from "./workflow-policy.js";
+function slugify(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 60);
+}
+function sanitizePathSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+export function isCodexThreadId(value) {
+    if (!value) {
+        return false;
+    }
+    return !value.startsWith("missing-thread-") && !value.startsWith("launch-failed-");
+}
+export function buildStageLaunchPlan(project, issue, stage) {
+    const workflow = resolveWorkflowById(project, stage);
+    if (!workflow) {
+        throw new Error(`Workflow "${stage}" is not configured for project ${project.id}`);
+    }
+    const issueRef = sanitizePathSegment(issue.issueKey ?? issue.linearIssueId);
+    const slug = issue.title ? slugify(issue.title) : "";
+    const branchSuffix = slug ? `${issueRef}-${slug}` : issueRef;
+    return {
+        branchName: `${project.branchPrefix}/${branchSuffix}`,
+        worktreePath: path.join(project.worktreeRoot, issueRef),
+        workflowFile: workflow.workflowFile,
+        stage,
+        prompt: buildStagePrompt(issue, workflow.id, workflow.whenState, workflow.workflowFile),
+    };
+}
+export function buildStagePrompt(issue, stage, triggerState, workflowFile) {
+    const workflowBody = existsSync(workflowFile) ? readFileSync(workflowFile, "utf8").trim() : "";
+    return [
+        `Issue: ${issue.issueKey ?? issue.linearIssueId}`,
+        issue.title ? `Title: ${issue.title}` : undefined,
+        issue.issueUrl ? `Linear URL: ${issue.issueUrl}` : undefined,
+        issue.currentLinearState ? `Current Linear State: ${issue.currentLinearState}` : undefined,
+        `Workflow: ${stage}`,
+        `Triggered By State: ${triggerState}`,
+        "",
+        "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.",
+        "",
+        `Workflow File: ${path.basename(workflowFile)}`,
+        workflowBody,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}