patchrelay 0.2.0 → 0.4.0

package/dist/cli/interactive.js

@@ -0,0 +1,48 @@
+import { spawn } from "node:child_process";
+export function buildOpenCommand(config, worktreePath, resumeThreadId) {
+    const args = ["--dangerously-bypass-approvals-and-sandbox"];
+    if (resumeThreadId) {
+        args.push("resume", "-C", worktreePath, resumeThreadId);
+    }
+    else {
+        args.push("-C", worktreePath);
+    }
+    return {
+        command: config.runner.codex.bin,
+        args,
+    };
+}
+export async function runInteractiveCommand(command, args) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: "inherit",
+        });
+        child.on("error", reject);
+        child.on("exit", (code, signal) => {
+            if (signal) {
+                resolve(1);
+                return;
+            }
+            resolve(code ?? 0);
+        });
+    });
+}
+export async function openExternalUrl(url) {
+    const candidates = process.platform === "darwin"
+        ? [{ command: "open", args: [url] }]
+        : process.platform === "win32"
+            ? [{ command: "cmd", args: ["/c", "start", "", url] }]
+            : [{ command: "xdg-open", args: [url] }];
+    for (const candidate of candidates) {
+        try {
+            const exitCode = await runInteractiveCommand(candidate.command, candidate.args);
+            if (exitCode === 0) {
+                return true;
+            }
+        }
+        catch {
+            // Try the next opener.
+        }
+    }
+    return false;
+}

package/dist/cli/output.js

@@ -0,0 +1,13 @@
+export function writeOutput(stream, text) {
+    stream.write(text);
+}
+export function formatDoctor(report) {
+    const lines = ["PatchRelay doctor", ""];
+    for (const check of report.checks) {
+        const marker = check.status === "pass" ? "PASS" : check.status === "warn" ? "WARN" : "FAIL";
+        lines.push(`${marker} [${check.scope}] ${check.message}`);
+    }
+    lines.push("");
+    lines.push(report.ok ? "Doctor result: ready" : "Doctor result: not ready");
+    return `${lines.join("\n")}\n`;
+}

package/dist/cli/service-commands.js

@@ -0,0 +1,31 @@
+export async function runServiceCommands(runner, commands) {
+    for (const entry of commands) {
+        const exitCode = await runner(entry.command, entry.args);
+        if (exitCode !== 0) {
+            throw new Error(`Command failed with exit code ${exitCode}: ${entry.command} ${entry.args.join(" ")}`);
+        }
+    }
+}
+export async function tryManageService(runner, commands) {
+    try {
+        await runServiceCommands(runner, commands);
+        return { ok: true };
+    }
+    catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export function installServiceCommands() {
+    return [
+        { command: "systemctl", args: ["--user", "daemon-reload"] },
+        { command: "systemctl", args: ["--user", "enable", "--now", "patchrelay.path"] },
+        { command: "systemctl", args: ["--user", "enable", "patchrelay.service"] },
+        { command: "systemctl", args: ["--user", "reload-or-restart", "patchrelay.service"] },
+    ];
+}
+export function restartServiceCommands() {
+    return [
+        { command: "systemctl", args: ["--user", "daemon-reload"] },
+        { command: "systemctl", args: ["--user", "reload-or-restart", "patchrelay.service"] },
+    ];
+}

package/dist/db/authoritative-ledger-store.js

@@ -141,6 +141,85 @@ export class AuthoritativeLedgerStore {
             .get(projectId, linearIssueId);
         return row ? mapWorkspaceOwnership(row) : undefined;
     }
+    upsertIssueSession(params) {
+        const now = isoNow();
+        this.connection
+            .prepare(`
+        INSERT INTO issue_sessions (
+          project_id, linear_issue_id, workspace_ownership_id, run_lease_id, thread_id, parent_thread_id,
+          source, linked_agent_session_id, created_at, updated_at, last_opened_at
+        ) VALUES (
+          @projectId, @linearIssueId, @workspaceOwnershipId, @runLeaseId, @threadId, @parentThreadId,
+          @source, @linkedAgentSessionId, @createdAt, @updatedAt, NULL
+        )
+        ON CONFLICT(thread_id) DO UPDATE SET
+          project_id = @projectId,
+          linear_issue_id = @linearIssueId,
+          workspace_ownership_id = @workspaceOwnershipId,
+          run_lease_id = CASE WHEN @setRunLeaseId = 1 THEN @runLeaseId ELSE issue_sessions.run_lease_id END,
+          parent_thread_id = CASE WHEN @setParentThreadId = 1 THEN @parentThreadId ELSE issue_sessions.parent_thread_id END,
+          source = @source,
+          linked_agent_session_id = CASE
+            WHEN @setLinkedAgentSessionId = 1 THEN @linkedAgentSessionId
+            ELSE issue_sessions.linked_agent_session_id
+          END,
+          updated_at = @updatedAt
+        `)
+            .run({
+            projectId: params.projectId,
+            linearIssueId: params.linearIssueId,
+            workspaceOwnershipId: params.workspaceOwnershipId,
+            runLeaseId: params.runLeaseId ?? null,
+            threadId: params.threadId,
+            parentThreadId: params.parentThreadId ?? null,
+            source: params.source,
+            linkedAgentSessionId: params.linkedAgentSessionId ?? null,
+            createdAt: now,
+            updatedAt: now,
+            setRunLeaseId: Number("runLeaseId" in params),
+            setParentThreadId: Number("parentThreadId" in params),
+            setLinkedAgentSessionId: Number("linkedAgentSessionId" in params),
+        });
+        return this.getIssueSessionByThreadId(params.threadId);
+    }
+    getIssueSessionByThreadId(threadId) {
+        const row = this.connection
+            .prepare("SELECT * FROM issue_sessions WHERE thread_id = ?")
+            .get(threadId);
+        return row ? mapIssueSession(row) : undefined;
+    }
+    listIssueSessionsForIssue(projectId, linearIssueId) {
+        const rows = this.connection
+            .prepare(`
+        SELECT * FROM issue_sessions
+        WHERE project_id = ? AND linear_issue_id = ?
+        ORDER BY
+          CASE WHEN last_opened_at IS NULL THEN 1 ELSE 0 END,
+          last_opened_at DESC,
+          id DESC
+        `)
+            .all(projectId, linearIssueId);
+        return rows.map((row) => mapIssueSession(row));
+    }
+    touchIssueSession(threadId) {
+        const now = isoNow();
+        const result = this.connection
+            .prepare(`
+        UPDATE issue_sessions
+        SET updated_at = @updatedAt,
+            last_opened_at = @lastOpenedAt
+        WHERE thread_id = @threadId
+        `)
+            .run({
+            threadId,
+            updatedAt: now,
+            lastOpenedAt: now,
+        });
+        if (result.changes < 1) {
+            return undefined;
+        }
+        return this.getIssueSessionByThreadId(threadId);
+    }
     createRunLease(params) {
         const result = this.connection
             .prepare(`
@@ -416,6 +495,22 @@ function mapRunLease(row) {
         ...(row.failure_reason === null ? {} : { failureReason: String(row.failure_reason) }),
     };
 }
+function mapIssueSession(row) {
+    return {
+        id: Number(row.id),
+        projectId: String(row.project_id),
+        linearIssueId: String(row.linear_issue_id),
+        workspaceOwnershipId: Number(row.workspace_ownership_id),
+        threadId: String(row.thread_id),
+        source: row.source,
+        ...(row.run_lease_id === null ? {} : { runLeaseId: Number(row.run_lease_id) }),
+        ...(row.parent_thread_id === null ? {} : { parentThreadId: String(row.parent_thread_id) }),
+        ...(row.linked_agent_session_id === null ? {} : { linkedAgentSessionId: String(row.linked_agent_session_id) }),
+        createdAt: String(row.created_at),
+        updatedAt: String(row.updated_at),
+        ...(row.last_opened_at === null ? {} : { lastOpenedAt: String(row.last_opened_at) }),
+    };
+}
 function mapObligation(row) {
     return {
         id: Number(row.id),

package/dist/db/issue-projection-store.js

@@ -0,0 +1,54 @@
+import { isoNow } from "./shared.js";
+export class IssueProjectionStore {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    upsertIssueProjection(params) {
+        this.connection
+            .prepare(`
+        INSERT INTO issue_projection (
+          project_id, linear_issue_id, issue_key, title, issue_url, current_linear_state, last_webhook_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(project_id, linear_issue_id) DO UPDATE SET
+          issue_key = COALESCE(excluded.issue_key, issue_projection.issue_key),
+          title = COALESCE(excluded.title, issue_projection.title),
+          issue_url = COALESCE(excluded.issue_url, issue_projection.issue_url),
+          current_linear_state = COALESCE(excluded.current_linear_state, issue_projection.current_linear_state),
+          last_webhook_at = COALESCE(excluded.last_webhook_at, issue_projection.last_webhook_at),
+          updated_at = excluded.updated_at
+        `)
+            .run(params.projectId, params.linearIssueId, params.issueKey ?? null, params.title ?? null, params.issueUrl ?? null, params.currentLinearState ?? null, params.lastWebhookAt ?? null, isoNow());
+    }
+    getIssueProjection(projectId, linearIssueId) {
+        const row = this.connection
+            .prepare("SELECT * FROM issue_projection WHERE project_id = ? AND linear_issue_id = ?")
+            .get(projectId, linearIssueId);
+        return row ? mapIssueProjection(row) : undefined;
+    }
+    getIssueProjectionByKey(issueKey) {
+        const row = this.connection
+            .prepare("SELECT * FROM issue_projection WHERE issue_key = ? ORDER BY updated_at DESC LIMIT 1")
+            .get(issueKey);
+        return row ? mapIssueProjection(row) : undefined;
+    }
+    getIssueProjectionByLinearIssueId(linearIssueId) {
+        const row = this.connection
+            .prepare("SELECT * FROM issue_projection WHERE linear_issue_id = ? ORDER BY updated_at DESC LIMIT 1")
+            .get(linearIssueId);
+        return row ? mapIssueProjection(row) : undefined;
+    }
+}
+function mapIssueProjection(row) {
+    return {
+        id: Number(row.id),
+        projectId: String(row.project_id),
+        linearIssueId: String(row.linear_issue_id),
+        ...(row.issue_key === null ? {} : { issueKey: String(row.issue_key) }),
+        ...(row.title === null ? {} : { title: String(row.title) }),
+        ...(row.issue_url === null ? {} : { issueUrl: String(row.issue_url) }),
+        ...(row.current_linear_state === null ? {} : { currentLinearState: String(row.current_linear_state) }),
+        ...(row.last_webhook_at === null ? {} : { lastWebhookAt: String(row.last_webhook_at) }),
+        updatedAt: String(row.updated_at),
+    };
+}

package/dist/db/issue-workflow-coordinator.js

@@ -0,0 +1,309 @@
+import { isoNow } from "./shared.js";
+export class IssueWorkflowCoordinator {
+    connection;
+    authoritativeLedger;
+    issueProjections;
+    issueWorkflows;
+    runReports;
+    constructor(dependencies) {
+        this.connection = dependencies.connection;
+        this.authoritativeLedger = dependencies.authoritativeLedger;
+        this.issueProjections = dependencies.issueProjections;
+        this.issueWorkflows = dependencies.issueWorkflows;
+        this.runReports = dependencies.runReports;
+    }
+    upsertTrackedIssue(params) {
+        this.issueProjections.upsertIssueProjection({
+            projectId: params.projectId,
+            linearIssueId: params.linearIssueId,
+            ...(params.issueKey ? { issueKey: params.issueKey } : {}),
+            ...(params.title ? { title: params.title } : {}),
+            ...(params.issueUrl ? { issueUrl: params.issueUrl } : {}),
+            ...(params.currentLinearState ? { currentLinearState: params.currentLinearState } : {}),
+            ...(params.lastWebhookAt ? { lastWebhookAt: params.lastWebhookAt } : {}),
+        });
+        const desiredReceiptId = this.resolveDesiredReceiptId({
+            projectId: params.projectId,
+            linearIssueId: params.linearIssueId,
+            ...(params.desiredWebhookId !== undefined ? { desiredWebhookId: params.desiredWebhookId } : {}),
+            ...(params.desiredReceiptId !== undefined ? { desiredReceiptId: params.desiredReceiptId } : {}),
+        });
+        this.authoritativeLedger.upsertIssueControl({
+            projectId: params.projectId,
+            linearIssueId: params.linearIssueId,
+            ...(params.desiredStage !== undefined ? { desiredStage: params.desiredStage } : {}),
+            ...(desiredReceiptId !== undefined ? { desiredReceiptId } : {}),
+            ...(params.activeWorkspaceId !== undefined ? { activeWorkspaceOwnershipId: params.activeWorkspaceId } : {}),
+            ...(params.activeStageRunId !== undefined ? { activeRunLeaseId: params.activeStageRunId } : {}),
+            ...(params.statusCommentId !== undefined ? { serviceOwnedCommentId: params.statusCommentId } : {}),
+            ...(params.activeAgentSessionId !== undefined ? { activeAgentSessionId: params.activeAgentSessionId } : {}),
+            lifecycleStatus: params.lifecycleStatus,
+        });
+        return this.issueWorkflows.getTrackedIssue(params.projectId, params.linearIssueId);
+    }
+    recordDesiredStage(params) {
+        const existing = this.issueWorkflows.getTrackedIssue(params.projectId, params.linearIssueId);
+        this.issueProjections.upsertIssueProjection({
+            projectId: params.projectId,
+            linearIssueId: params.linearIssueId,
+            ...(params.issueKey ? { issueKey: params.issueKey } : existing?.issueKey ? { issueKey: existing.issueKey } : {}),
+            ...(params.title ? { title: params.title } : existing?.title ? { title: existing.title } : {}),
+            ...(params.issueUrl ? { issueUrl: params.issueUrl } : existing?.issueUrl ? { issueUrl: existing.issueUrl } : {}),
+            ...(params.currentLinearState
+                ? { currentLinearState: params.currentLinearState }
+                : existing?.currentLinearState
+                    ? { currentLinearState: existing.currentLinearState }
+                    : {}),
+            lastWebhookAt: params.lastWebhookAt,
+        });
+        const existingIssueControl = this.authoritativeLedger.getIssueControl(params.projectId, params.linearIssueId);
+        const lifecycleStatus = existingIssueControl?.activeRunLeaseId || params.desiredStage
+            ? existing?.lifecycleStatus ?? "queued"
+            : existing?.lifecycleStatus ?? "idle";
+        const desiredReceiptId = this.resolveDesiredReceiptId({
+            projectId: params.projectId,
+            linearIssueId: params.linearIssueId,
+            ...(params.desiredWebhookId !== undefined ? { desiredWebhookId: params.desiredWebhookId } : {}),
+            ...(params.desiredReceiptId !== undefined ? { desiredReceiptId: params.desiredReceiptId } : {}),
+        });
+        this.authoritativeLedger.upsertIssueControl({
+            projectId: params.projectId,
+            linearIssueId: params.linearIssueId,
+            ...(params.desiredStage !== undefined ? { desiredStage: params.desiredStage } : {}),
+            ...(desiredReceiptId !== undefined ? { desiredReceiptId } : {}),
+            lifecycleStatus,
+            ...(existing?.statusCommentId ? { serviceOwnedCommentId: existing.statusCommentId } : {}),
+            ...(params.activeAgentSessionId !== undefined
+                ? { activeAgentSessionId: params.activeAgentSessionId }
+                : existing?.activeAgentSessionId
+                    ? { activeAgentSessionId: existing.activeAgentSessionId }
+                    : {}),
+            ...(existing?.activeWorkspaceId !== undefined ? { activeWorkspaceOwnershipId: existing.activeWorkspaceId } : {}),
+            ...(existingIssueControl?.activeRunLeaseId !== undefined ? { activeRunLeaseId: existingIssueControl.activeRunLeaseId } : {}),
+        });
+        return this.issueWorkflows.getTrackedIssue(params.projectId, params.linearIssueId);
+    }
+    claimStageRun(params) {
+        const transaction = this.connection.transaction(() => {
+            const issue = this.issueWorkflows.getTrackedIssue(params.projectId, params.linearIssueId);
+            const issueControl = this.authoritativeLedger.getIssueControl(params.projectId, params.linearIssueId);
+            if (!issue ||
+                !issueControl ||
+                issueControl.activeRunLeaseId !== undefined ||
+                issue.desiredStage !== params.stage ||
+                issue.desiredWebhookId !== params.triggerWebhookId) {
+                return undefined;
+            }
+            const workspaceOwnership = this.authoritativeLedger.upsertWorkspaceOwnership({
+                projectId: params.projectId,
+                linearIssueId: params.linearIssueId,
+                branchName: params.branchName,
+                worktreePath: params.worktreePath,
+                status: "active",
+            });
+            const runLease = this.authoritativeLedger.createRunLease({
+                issueControlId: issueControl.id,
+                projectId: params.projectId,
+                linearIssueId: params.linearIssueId,
+                workspaceOwnershipId: workspaceOwnership.id,
+                stage: params.stage,
+                status: "running",
+                workflowFile: params.workflowFile,
+                promptText: params.promptText,
+                triggerReceiptId: issueControl.desiredReceiptId ?? null,
+            });
+            this.authoritativeLedger.upsertWorkspaceOwnership({
+                projectId: params.projectId,
+                linearIssueId: params.linearIssueId,
+                branchName: params.branchName,
+                worktreePath: params.worktreePath,
+                status: "active",
+                currentRunLeaseId: runLease.id,
+            });
+            this.authoritativeLedger.upsertIssueControl({
+                projectId: params.projectId,
+                linearIssueId: params.linearIssueId,
+                desiredStage: null,
+                desiredReceiptId: null,
+                activeWorkspaceOwnershipId: workspaceOwnership.id,
+                activeRunLeaseId: runLease.id,
+                lifecycleStatus: "running",
+                ...(issue.statusCommentId ? { serviceOwnedCommentId: issue.statusCommentId } : {}),
+                ...(issue.activeAgentSessionId ? { activeAgentSessionId: issue.activeAgentSessionId } : {}),
+            });
+            const refreshedIssue = this.issueWorkflows.getTrackedIssue(params.projectId, params.linearIssueId);
+            const workspace = this.issueWorkflows.getWorkspace(workspaceOwnership.id);
+            const stageRun = this.issueWorkflows.getStageRun(runLease.id);
+            const pipeline = this.issueWorkflows.getPipelineRun(runLease.id);
+            return { issue: refreshedIssue, workspace, pipeline, stageRun };
+        });
+        return transaction();
+    }
+    updateStageRunThread(params) {
+        this.authoritativeLedger.updateRunLeaseThread({
+            runLeaseId: params.stageRunId,
+            threadId: params.threadId,
+            ...(params.parentThreadId !== undefined ? { parentThreadId: params.parentThreadId } : {}),
+            ...(params.turnId !== undefined ? { turnId: params.turnId } : {}),
+        });
+        const stageRun = this.issueWorkflows.getStageRun(params.stageRunId);
+        if (!stageRun) {
+            return;
+        }
+        const issue = this.issueWorkflows.getTrackedIssue(stageRun.projectId, stageRun.linearIssueId);
+        this.authoritativeLedger.upsertIssueSession({
+            projectId: stageRun.projectId,
+            linearIssueId: stageRun.linearIssueId,
+            workspaceOwnershipId: stageRun.workspaceId,
+            runLeaseId: stageRun.id,
+            threadId: params.threadId,
+            ...(params.parentThreadId !== undefined ? { parentThreadId: params.parentThreadId } : {}),
+            ...(issue?.activeAgentSessionId ? { linkedAgentSessionId: issue.activeAgentSessionId } : {}),
+            source: "stage_run",
+        });
+    }
+    finishStageRun(params) {
+        const stageRun = this.issueWorkflows.getStageRun(params.stageRunId);
+        if (!stageRun) {
+            return;
+        }
+        this.runReports.saveRunReport({
+            runLeaseId: params.stageRunId,
+            ...(params.summaryJson !== undefined ? { summaryJson: params.summaryJson } : {}),
+            ...(params.reportJson !== undefined ? { reportJson: params.reportJson } : {}),
+        });
+        this.authoritativeLedger.finishRunLease({
+            runLeaseId: params.stageRunId,
+            status: params.status === "failed" ? "failed" : "completed",
+            threadId: params.threadId,
+            ...(params.turnId !== undefined ? { turnId: params.turnId } : {}),
+        });
+        const runLease = this.authoritativeLedger.getRunLease(params.stageRunId);
+        if (runLease?.workspaceOwnershipId !== undefined) {
+            const issue = this.issueWorkflows.getTrackedIssue(stageRun.projectId, stageRun.linearIssueId);
+            this.authoritativeLedger.upsertIssueSession({
+                projectId: stageRun.projectId,
+                linearIssueId: stageRun.linearIssueId,
+                workspaceOwnershipId: runLease.workspaceOwnershipId,
+                runLeaseId: params.stageRunId,
+                threadId: params.threadId,
+                ...(runLease.parentThreadId ? { parentThreadId: runLease.parentThreadId } : {}),
+                ...(issue?.activeAgentSessionId ? { linkedAgentSessionId: issue.activeAgentSessionId } : {}),
+                source: "stage_run",
+            });
+        }
+        const workspace = this.authoritativeLedger.getWorkspaceOwnership(stageRun.workspaceId);
+        if (workspace) {
+            this.authoritativeLedger.upsertWorkspaceOwnership({
+                projectId: stageRun.projectId,
+                linearIssueId: stageRun.linearIssueId,
+                branchName: workspace.branchName,
+                worktreePath: workspace.worktreePath,
+                status: params.status === "completed" ? "active" : "paused",
+                currentRunLeaseId: null,
+            });
+        }
+    }
+    setIssueDesiredStage(projectId, linearIssueId, desiredStage, options) {
+        const existing = this.issueWorkflows.getTrackedIssue(projectId, linearIssueId);
+        const existingIssueControl = this.authoritativeLedger.getIssueControl(projectId, linearIssueId);
+        const desiredReceiptId = this.resolveDesiredReceiptId({
+            projectId,
+            linearIssueId,
+            ...(options?.desiredWebhookId !== undefined ? { desiredWebhookId: options.desiredWebhookId } : {}),
+            ...(options?.desiredReceiptId !== undefined ? { desiredReceiptId: options.desiredReceiptId } : {}),
+        });
+        this.authoritativeLedger.upsertIssueControl({
+            projectId,
+            linearIssueId,
+            ...(desiredStage !== undefined ? { desiredStage } : { desiredStage: null }),
+            ...(desiredReceiptId !== undefined
+                ? { desiredReceiptId }
+                : desiredStage === undefined
+                    ? { desiredReceiptId: null }
+                    : {}),
+            lifecycleStatus: options?.lifecycleStatus ??
+                (desiredStage ? "queued" : existingIssueControl?.activeRunLeaseId ? (existing?.lifecycleStatus ?? "idle") : "idle"),
+            ...(existing?.statusCommentId ? { serviceOwnedCommentId: existing.statusCommentId } : {}),
+            ...(existing?.activeAgentSessionId ? { activeAgentSessionId: existing.activeAgentSessionId } : {}),
+            ...(existing?.activeWorkspaceId !== undefined ? { activeWorkspaceOwnershipId: existing.activeWorkspaceId } : {}),
+            ...(existingIssueControl?.activeRunLeaseId !== undefined ? { activeRunLeaseId: existingIssueControl.activeRunLeaseId } : {}),
+        });
+    }
+    setIssueLifecycleStatus(projectId, linearIssueId, lifecycleStatus) {
+        const existing = this.issueWorkflows.getTrackedIssue(projectId, linearIssueId);
+        const existingIssueControl = this.authoritativeLedger.getIssueControl(projectId, linearIssueId);
+        this.authoritativeLedger.upsertIssueControl({
+            projectId,
+            linearIssueId,
+            lifecycleStatus,
+            ...(existing?.desiredStage ? { desiredStage: existing.desiredStage } : {}),
+            ...(existingIssueControl?.desiredReceiptId !== undefined ? { desiredReceiptId: existingIssueControl.desiredReceiptId } : {}),
+            ...(existing?.activeWorkspaceId !== undefined ? { activeWorkspaceOwnershipId: existing.activeWorkspaceId } : {}),
+            ...(existingIssueControl?.activeRunLeaseId !== undefined ? { activeRunLeaseId: existingIssueControl.activeRunLeaseId } : {}),
+            ...(existing?.statusCommentId ? { serviceOwnedCommentId: existing.statusCommentId } : {}),
+            ...(existing?.activeAgentSessionId ? { activeAgentSessionId: existing.activeAgentSessionId } : {}),
+        });
+    }
+    setIssueStatusComment(projectId, linearIssueId, statusCommentId) {
+        const existing = this.issueWorkflows.getTrackedIssue(projectId, linearIssueId);
+        const existingIssueControl = this.authoritativeLedger.getIssueControl(projectId, linearIssueId);
+        this.authoritativeLedger.upsertIssueControl({
+            projectId,
+            linearIssueId,
+            lifecycleStatus: existing?.lifecycleStatus ?? "idle",
+            ...(existing?.desiredStage ? { desiredStage: existing.desiredStage } : {}),
+            ...(existingIssueControl?.desiredReceiptId !== undefined ? { desiredReceiptId: existingIssueControl.desiredReceiptId } : {}),
+            ...(existing?.activeWorkspaceId !== undefined ? { activeWorkspaceOwnershipId: existing.activeWorkspaceId } : {}),
+            ...(existingIssueControl?.activeRunLeaseId !== undefined ? { activeRunLeaseId: existingIssueControl.activeRunLeaseId } : {}),
+            serviceOwnedCommentId: statusCommentId ?? null,
+            ...(existing?.activeAgentSessionId ? { activeAgentSessionId: existing.activeAgentSessionId } : {}),
+        });
+    }
+    setIssueActiveAgentSession(projectId, linearIssueId, agentSessionId) {
+        const existing = this.issueWorkflows.getTrackedIssue(projectId, linearIssueId);
+        const existingIssueControl = this.authoritativeLedger.getIssueControl(projectId, linearIssueId);
+        this.authoritativeLedger.upsertIssueControl({
+            projectId,
+            linearIssueId,
+            lifecycleStatus: existing?.lifecycleStatus ?? "idle",
+            ...(existing?.desiredStage ? { desiredStage: existing.desiredStage } : {}),
+            ...(existingIssueControl?.desiredReceiptId !== undefined ? { desiredReceiptId: existingIssueControl.desiredReceiptId } : {}),
+            ...(existing?.activeWorkspaceId !== undefined ? { activeWorkspaceOwnershipId: existing.activeWorkspaceId } : {}),
+            ...(existingIssueControl?.activeRunLeaseId !== undefined ? { activeRunLeaseId: existingIssueControl.activeRunLeaseId } : {}),
+            ...(existing?.statusCommentId ? { serviceOwnedCommentId: existing.statusCommentId } : {}),
+            activeAgentSessionId: agentSessionId ?? null,
+        });
+    }
+    resolveDesiredReceiptId(params) {
+        if (params.desiredReceiptId !== undefined) {
+            return params.desiredReceiptId;
+        }
+        if (params.desiredWebhookId === undefined) {
+            return undefined;
+        }
+        if (params.desiredWebhookId === null) {
+            return null;
+        }
+        return this.ensureDesiredReceipt(params.projectId, params.linearIssueId, params.desiredWebhookId);
+    }
+    ensureDesiredReceipt(projectId, linearIssueId, webhookId) {
+        const existing = this.connection
+            .prepare("SELECT id FROM event_receipts WHERE external_id = ? ORDER BY id DESC LIMIT 1")
+            .get(webhookId);
+        if (existing) {
+            return Number(existing.id);
+        }
+        const receipt = this.authoritativeLedger.insertEventReceipt({
+            source: "patchrelay-desired-stage",
+            externalId: webhookId,
+            eventType: "desired_stage",
+            receivedAt: isoNow(),
+            acceptanceStatus: "accepted",
+            projectId,
+            linearIssueId,
+        });
+        this.authoritativeLedger.markEventReceiptProcessed(receipt.id, "processed");
+        return receipt.id;
+    }
+}