patchrelay 0.2.0 → 0.3.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.2.0",
-  "commit": "67bd98adc642",
-  "builtAt": "2026-03-12T18:57:08.889Z"
+  "version": "0.3.0",
+  "commit": "c82e03b38d6e",
+  "builtAt": "2026-03-13T01:42:32.759Z"
 }

package/dist/cli/args.js

@@ -0,0 +1,73 @@
+export const KNOWN_COMMANDS = new Set([
+    "serve",
+    "inspect",
+    "live",
+    "report",
+    "events",
+    "worktree",
+    "open",
+    "retry",
+    "list",
+    "doctor",
+    "init",
+    "project",
+    "connect",
+    "installations",
+    "install-service",
+    "restart-service",
+    "help",
+]);
+export function parseArgs(argv) {
+    const positionals = [];
+    const flags = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (!value.startsWith("--")) {
+            positionals.push(value);
+            continue;
+        }
+        const trimmed = value.slice(2);
+        const [name, inline] = trimmed.split("=", 2);
+        if (!name) {
+            continue;
+        }
+        if (inline !== undefined) {
+            flags.set(name, inline);
+            continue;
+        }
+        const next = argv[index + 1];
+        if (next && !next.startsWith("--")) {
+            flags.set(name, next);
+            index += 1;
+            continue;
+        }
+        flags.set(name, true);
+    }
+    return { positionals, flags };
+}
+export function resolveCommand(parsed) {
+    const requestedCommand = parsed.positionals[0];
+    const command = !requestedCommand
+        ? "help"
+        : KNOWN_COMMANDS.has(requestedCommand)
+            ? requestedCommand
+            : "inspect";
+    const commandArgs = command === requestedCommand ? parsed.positionals.slice(1) : parsed.positionals;
+    return { command, commandArgs };
+}
+export function getStageFlag(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+export function parseCsvFlag(value) {
+    if (typeof value !== "string") {
+        return [];
+    }
+    return value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}

package/dist/cli/command-types.js

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

package/dist/cli/commands/connect.js

@@ -0,0 +1,28 @@
+import { runConnectFlow, parseTimeoutSeconds } from "../connect-flow.js";
+import { formatJson } from "../formatters/json.js";
+import { openExternalUrl } from "../interactive.js";
+import { writeOutput } from "../output.js";
+export async function handleConnectCommand(params) {
+    return await runConnectFlow({
+        config: params.config,
+        data: params.data,
+        stdout: params.stdout,
+        noOpen: params.parsed.flags.get("no-open") === true,
+        timeoutSeconds: parseTimeoutSeconds(params.parsed.flags.get("timeout"), "connect"),
+        json: params.json,
+        openExternal: params.options?.openExternal ?? openExternalUrl,
+        ...(params.options?.connectPollIntervalMs !== undefined ? { connectPollIntervalMs: params.options.connectPollIntervalMs } : {}),
+        ...(typeof params.parsed.flags.get("project") === "string" ? { projectId: String(params.parsed.flags.get("project")) } : {}),
+    });
+}
+export async function handleInstallationsCommand(params) {
+    const result = await params.data.listInstallations();
+    if (params.json) {
+        writeOutput(params.stdout, formatJson(result));
+        return 0;
+    }
+    writeOutput(params.stdout, `${(result.installations.length > 0
+        ? result.installations.map((item) => `${item.installation.id}  ${item.installation.workspaceName ?? item.installation.actorName ?? "-"}  projects=${item.linkedProjects.join(",") || "-"}`)
+        : ["No installations found."]).join("\n")}\n`);
+    return 0;
+}

package/dist/cli/commands/issues.js

@@ -0,0 +1,147 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { getStageFlag } from "../args.js";
+import { formatJson } from "../formatters/json.js";
+import { formatEvents, formatInspect, formatList, formatLive, formatOpen, formatReport, formatRetry, formatWorktree } from "../formatters/text.js";
+import { buildOpenCommand } from "../interactive.js";
+import { writeOutput } from "../output.js";
+export async function handleInspectCommand(params) {
+    const issueKey = params.commandArgs[0];
+    if (!issueKey) {
+        throw new Error("inspect requires <issueKey>.");
+    }
+    const result = await params.data.inspect(issueKey);
+    if (!result) {
+        throw new Error(`Issue not found: ${issueKey}`);
+    }
+    writeOutput(params.stdout, params.json ? formatJson(result) : formatInspect(result));
+    return 0;
+}
+export async function handleLiveCommand(params) {
+    const issueKey = params.commandArgs[0];
+    if (!issueKey) {
+        throw new Error("live requires <issueKey>.");
+    }
+    const watch = params.parsed.flags.get("watch") === true;
+    do {
+        const result = await params.data.live(issueKey);
+        if (!result) {
+            throw new Error(`No active stage found for ${issueKey}`);
+        }
+        writeOutput(params.stdout, params.json ? formatJson(result) : formatLive(result));
+        if (!watch || result.stageRun.status !== "running") {
+            break;
+        }
+        await delay(2000);
+    } while (true);
+    return 0;
+}
+export async function handleReportCommand(params) {
+    const issueKey = params.commandArgs[0];
+    if (!issueKey) {
+        throw new Error("report requires <issueKey>.");
+    }
+    const reportOptions = {};
+    const stage = getStageFlag(params.parsed.flags.get("stage"));
+    if (stage) {
+        reportOptions.stage = stage;
+    }
+    if (typeof params.parsed.flags.get("stage-run") === "string") {
+        reportOptions.stageRunId = Number(params.parsed.flags.get("stage-run"));
+    }
+    const result = params.data.report(issueKey, reportOptions);
+    if (!result) {
+        throw new Error(`Issue not found: ${issueKey}`);
+    }
+    writeOutput(params.stdout, params.json ? formatJson(result) : formatReport(result));
+    return 0;
+}
+export async function handleEventsCommand(params) {
+    const issueKey = params.commandArgs[0];
+    if (!issueKey) {
+        throw new Error("events requires <issueKey>.");
+    }
+    const follow = params.parsed.flags.get("follow") === true;
+    let afterId;
+    let stageRunId = typeof params.parsed.flags.get("stage-run") === "string" ? Number(params.parsed.flags.get("stage-run")) : undefined;
+    do {
+        const result = params.data.events(issueKey, {
+            ...(stageRunId !== undefined ? { stageRunId } : {}),
+            ...(typeof params.parsed.flags.get("method") === "string" ? { method: String(params.parsed.flags.get("method")) } : {}),
+            ...(afterId !== undefined ? { afterId } : {}),
+        });
+        if (!result) {
+            throw new Error(`Stage run not found for ${issueKey}`);
+        }
+        stageRunId = result.stageRun.id;
+        if (result.events.length > 0) {
+            writeOutput(params.stdout, params.json ? formatJson(result) : formatEvents(result));
+            afterId = result.events.at(-1)?.id;
+        }
+        if (!follow || result.stageRun.status !== "running") {
+            break;
+        }
+        await delay(2000);
+    } while (true);
+    return 0;
+}
+export async function handleWorktreeCommand(params) {
+    const issueKey = params.commandArgs[0];
+    if (!issueKey) {
+        throw new Error("worktree requires <issueKey>.");
+    }
+    const result = params.data.worktree(issueKey);
+    if (!result) {
+        throw new Error(`Workspace not found for ${issueKey}`);
+    }
+    writeOutput(params.stdout, params.json ? formatJson(result) : formatWorktree(result, params.parsed.flags.get("cd") === true));
+    return 0;
+}
+export async function handleOpenCommand(params) {
+    const issueKey = params.commandArgs[0];
+    if (!issueKey) {
+        throw new Error("open requires <issueKey>.");
+    }
+    const result = params.data.open(issueKey);
+    if (!result) {
+        throw new Error(`Workspace not found for ${issueKey}`);
+    }
+    if (params.json) {
+        writeOutput(params.stdout, formatJson(result));
+        return 0;
+    }
+    if (params.parsed.flags.get("print") === true) {
+        writeOutput(params.stdout, formatOpen(result));
+        return 0;
+    }
+    const openCommand = buildOpenCommand(params.config, result.workspace.worktreePath, result.resumeThreadId);
+    return await params.runInteractive(openCommand.command, openCommand.args);
+}
+export async function handleRetryCommand(params) {
+    const issueKey = params.commandArgs[0];
+    if (!issueKey) {
+        throw new Error("retry requires <issueKey>.");
+    }
+    const retryOptions = {};
+    const stage = getStageFlag(params.parsed.flags.get("stage"));
+    if (stage) {
+        retryOptions.stage = stage;
+    }
+    if (typeof params.parsed.flags.get("reason") === "string") {
+        retryOptions.reason = String(params.parsed.flags.get("reason"));
+    }
+    const result = params.data.retry(issueKey, retryOptions);
+    if (!result) {
+        throw new Error(`Issue not found: ${issueKey}`);
+    }
+    writeOutput(params.stdout, params.json ? formatJson(result) : formatRetry(result));
+    return 0;
+}
+export async function handleListCommand(params) {
+    const result = params.data.list({
+        active: params.parsed.flags.get("active") === true,
+        failed: params.parsed.flags.get("failed") === true,
+        ...(typeof params.parsed.flags.get("project") === "string" ? { project: String(params.parsed.flags.get("project")) } : {}),
+    });
+    writeOutput(params.stdout, params.json ? formatJson(result) : formatList(result));
+    return 0;
+}

package/dist/cli/commands/project.js

@@ -0,0 +1,140 @@
+import { loadConfig } from "../../config.js";
+import { installUserServiceUnits, upsertProjectInConfig } from "../../install.js";
+import { runPreflight } from "../../preflight.js";
+import { parseCsvFlag } from "../args.js";
+import { runConnectFlow, parseTimeoutSeconds } from "../connect-flow.js";
+import { CliDataAccess } from "../data.js";
+import { formatJson } from "../formatters/json.js";
+import { writeOutput } from "../output.js";
+import { installServiceCommands, tryManageService } from "../service-commands.js";
+export async function handleProjectCommand(params) {
+    try {
+        const subcommand = params.commandArgs[0];
+        if (subcommand !== "apply") {
+            throw new Error("Usage: patchrelay project apply <id> <repo-path> [--issue-prefix <prefixes>] [--team-id <ids>] [--no-connect] [--timeout <seconds>]");
+        }
+        const projectId = params.commandArgs[1];
+        const repoPath = params.commandArgs[2];
+        if (!projectId || !repoPath) {
+            throw new Error("Usage: patchrelay project apply <id> <repo-path> [--issue-prefix <prefixes>] [--team-id <ids>] [--no-connect] [--timeout <seconds>]");
+        }
+        const result = await upsertProjectInConfig({
+            id: projectId,
+            repoPath,
+            issueKeyPrefixes: parseCsvFlag(params.parsed.flags.get("issue-prefix")),
+            linearTeamIds: parseCsvFlag(params.parsed.flags.get("team-id")),
+        });
+        const serviceUnits = await installUserServiceUnits();
+        const noConnect = params.parsed.flags.get("no-connect") === true;
+        const lines = [
+            `Config file: ${result.configPath}`,
+            `${result.status === "created" ? "Created" : result.status === "updated" ? "Updated" : "Verified"} project ${result.project.id} for ${result.project.repoPath}`,
+            result.project.issueKeyPrefixes.length > 0 ? `Issue key prefixes: ${result.project.issueKeyPrefixes.join(", ")}` : undefined,
+            result.project.linearTeamIds.length > 0 ? `Linear team ids: ${result.project.linearTeamIds.join(", ")}` : undefined,
+            `Service unit: ${serviceUnits.unitPath} (${serviceUnits.serviceStatus})`,
+            `Watcher unit: ${serviceUnits.pathUnitPath} (${serviceUnits.pathStatus})`,
+        ].filter(Boolean);
+        let fullConfig;
+        try {
+            fullConfig = loadConfig(undefined, { profile: "doctor" });
+        }
+        catch (error) {
+            if (params.json) {
+                writeOutput(params.stdout, formatJson({
+                    ...result,
+                    serviceUnits,
+                    readiness: {
+                        ok: false,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                    connect: {
+                        attempted: false,
+                        skipped: "missing_env",
+                    },
+                }));
+                return 0;
+            }
+            lines.push(`Linear connect was skipped: ${error instanceof Error ? error.message : String(error)}`);
+            lines.push("Finish the required env vars and rerun `patchrelay project apply`.");
+            writeOutput(params.stdout, `${lines.join("\n")}\n`);
+            return 0;
+        }
+        const report = await runPreflight(fullConfig);
+        const failedChecks = report.checks.filter((check) => check.status === "fail");
+        if (failedChecks.length > 0) {
+            if (params.json) {
+                writeOutput(params.stdout, formatJson({
+                    ...result,
+                    serviceUnits,
+                    readiness: report,
+                    connect: {
+                        attempted: false,
+                        skipped: "preflight_failed",
+                    },
+                }));
+                return 0;
+            }
+            lines.push("Linear connect was skipped because PatchRelay is not ready yet:");
+            lines.push(...failedChecks.map((check) => `- [${check.scope}] ${check.message}`));
+            lines.push("Fix the failures above and rerun `patchrelay project apply`.");
+            writeOutput(params.stdout, `${lines.join("\n")}\n`);
+            return 0;
+        }
+        const serviceState = await tryManageService(params.runInteractive, installServiceCommands());
+        if (!serviceState.ok) {
+            throw new Error(`Project was saved, but PatchRelay could not be reloaded: ${serviceState.error}`);
+        }
+        const cliData = params.options?.data ?? new CliDataAccess(fullConfig);
+        try {
+            if (params.json) {
+                const connectResult = noConnect ? undefined : await cliData.connect(projectId);
+                writeOutput(params.stdout, formatJson({
+                    ...result,
+                    serviceUnits,
+                    readiness: report,
+                    serviceReloaded: true,
+                    ...(noConnect
+                        ? {
+                            connect: {
+                                attempted: false,
+                                skipped: "no_connect",
+                            },
+                        }
+                        : {
+                            connect: {
+                                attempted: true,
+                                result: connectResult,
+                            },
+                        }),
+                }));
+                return 0;
+            }
+            if (noConnect) {
+                lines.push("Project saved and PatchRelay was reloaded.");
+                lines.push(`Next: patchrelay connect --project ${result.project.id}`);
+                writeOutput(params.stdout, `${lines.join("\n")}\n`);
+                return 0;
+            }
+            writeOutput(params.stdout, `${lines.join("\n")}\n`);
+            return await runConnectFlow({
+                config: fullConfig,
+                data: cliData,
+                stdout: params.stdout,
+                noOpen: params.parsed.flags.get("no-open") === true,
+                timeoutSeconds: parseTimeoutSeconds(params.parsed.flags.get("timeout"), "project apply"),
+                projectId,
+                ...(params.options?.openExternal ? { openExternal: params.options.openExternal } : {}),
+                ...(params.options?.connectPollIntervalMs !== undefined ? { connectPollIntervalMs: params.options.connectPollIntervalMs } : {}),
+            });
+        }
+        finally {
+            if (!params.options?.data) {
+                cliData.close();
+            }
+        }
+    }
+    catch (error) {
+        writeOutput(params.stderr, `${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/cli/commands/setup.js

@@ -0,0 +1,140 @@
+import { getDefaultConfigPath, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getSystemdUserPathUnitPath, getSystemdUserReloadUnitPath, getSystemdUserUnitPath, } from "../../runtime-paths.js";
+import { initializePatchRelayHome, installUserServiceUnits } from "../../install.js";
+import { formatJson } from "../formatters/json.js";
+import { writeOutput } from "../output.js";
+import { installServiceCommands, restartServiceCommands, runServiceCommands, tryManageService } from "../service-commands.js";
+export async function handleInitCommand(params) {
+    try {
+        const requestedPublicBaseUrl = typeof params.parsed.flags.get("public-base-url") === "string"
+            ? String(params.parsed.flags.get("public-base-url"))
+            : params.commandArgs[0];
+        if (!requestedPublicBaseUrl) {
+            throw new Error([
+                "patchrelay init requires <public-base-url>.",
+                "PatchRelay must know the public HTTPS origin that Linear will call for the webhook and OAuth callback.",
+                "Example: patchrelay init https://patchrelay.example.com",
+            ].join("\n"));
+        }
+        const publicBaseUrl = normalizePublicBaseUrl(requestedPublicBaseUrl);
+        const result = await initializePatchRelayHome({
+            force: params.parsed.flags.get("force") === true,
+            publicBaseUrl,
+        });
+        const serviceUnits = await installUserServiceUnits({ force: params.parsed.flags.get("force") === true });
+        const serviceState = await tryManageService(params.runInteractive, installServiceCommands());
+        writeOutput(params.stdout, params.json
+            ? formatJson({ ...result, serviceUnits, serviceState })
+            : [
+                `Config directory: ${result.configDir}`,
+                `Runtime env: ${result.runtimeEnvPath} (${result.runtimeEnvStatus})`,
+                `Service env: ${result.serviceEnvPath} (${result.serviceEnvStatus})`,
+                `Config file: ${result.configPath} (${result.configStatus})`,
+                `State directory: ${result.stateDir}`,
+                `Data directory: ${result.dataDir}`,
+                `Service unit: ${serviceUnits.unitPath} (${serviceUnits.serviceStatus})`,
+                `Reload unit: ${serviceUnits.reloadUnitPath} (${serviceUnits.reloadStatus})`,
+                `Watcher unit: ${serviceUnits.pathUnitPath} (${serviceUnits.pathStatus})`,
+                "",
+                "PatchRelay public URLs:",
+                `- Public base URL: ${result.publicBaseUrl}`,
+                `- Webhook URL: ${result.webhookUrl}`,
+                `- OAuth callback: ${result.oauthCallbackUrl}`,
+                "",
+                "Created with defaults:",
+                `- Config file contains only machine-level essentials such as server.public_base_url`,
+                `- Database, logs, bind address, and worktree roots use built-in defaults`,
+                `- The user service and config watcher are installed for you`,
+                "",
+                "Register the app in Linear:",
+                "- Open Linear Settings > API > Applications",
+                "- Create an OAuth app for PatchRelay",
+                "- Choose actor `app`",
+                "- Choose scopes `read`, `write`, `app:assignable`, `app:mentionable`",
+                `- Add redirect URI ${result.oauthCallbackUrl}`,
+                `- Add webhook URL ${result.webhookUrl}`,
+                "- Enable webhook categories for issue events, comment events, agent session events, permission changes, and inbox/app-user notifications",
+                "",
+                result.configStatus === "skipped"
+                    ? `Config file was skipped, so make sure ${result.configPath} still has server.public_base_url: ${result.publicBaseUrl}`
+                    : `Config file already includes server.public_base_url: ${result.publicBaseUrl}`,
+                "",
+                "Service status:",
+                serviceState.ok
+                    ? "PatchRelay service and config watcher are installed and reload-or-restart has been requested."
+                    : `PatchRelay service units were installed, but the service could not be started yet: ${serviceState.error}`,
+                !serviceState.ok
+                    ? "This is expected until the required env vars and at least one valid project workflow are in place. The watcher will retry when config or env files change."
+                    : undefined,
+                "",
+                "Next steps:",
+                `1. Edit ${result.serviceEnvPath}`,
+                "2. Paste your Linear OAuth client id and client secret into service.env and keep the generated webhook secret and token encryption key",
+                "3. Paste LINEAR_WEBHOOK_SECRET from service.env into the Linear OAuth app webhook signing secret",
+                "4. Run `patchrelay project apply <id> <repo-path>`",
+                "5. Edit the generated project workflows if you want custom state names or workflow files, then add those workflow files to the repo",
+                "6. Run `patchrelay doctor`",
+            ]
+                .filter(Boolean)
+                .join("\n") + "\n");
+        return 0;
+    }
+    catch (error) {
+        writeOutput(params.stderr, `${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+export async function handleInstallServiceCommand(params) {
+    try {
+        const result = await installUserServiceUnits({ force: params.parsed.flags.get("force") === true });
+        const writeOnly = params.parsed.flags.get("write-only") === true;
+        if (!writeOnly) {
+            await runServiceCommands(params.runInteractive, installServiceCommands());
+        }
+        writeOutput(params.stdout, params.json
+            ? formatJson({ ...result, writeOnly })
+            : [
+                `Service unit: ${result.unitPath} (${result.serviceStatus})`,
+                `Reload unit: ${result.reloadUnitPath} (${result.reloadStatus})`,
+                `Watcher unit: ${result.pathUnitPath} (${result.pathStatus})`,
+                `Runtime env: ${result.runtimeEnvPath}`,
+                `Service env: ${result.serviceEnvPath}`,
+                `Config file: ${result.configPath}`,
+                writeOnly
+                    ? "Service units written. Start them with: systemctl --user daemon-reload && systemctl --user enable --now patchrelay.path && systemctl --user enable patchrelay.service && systemctl --user reload-or-restart patchrelay.service"
+                    : "PatchRelay user service and config watcher are installed and running.",
+                "After package updates, run: patchrelay restart-service",
+            ].join("\n") + "\n");
+        return 0;
+    }
+    catch (error) {
+        writeOutput(params.stderr, `${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+export async function handleRestartServiceCommand(params) {
+    try {
+        await runServiceCommands(params.runInteractive, restartServiceCommands());
+        writeOutput(params.stdout, params.json
+            ? formatJson({
+                service: "patchrelay",
+                unitPath: getSystemdUserUnitPath(),
+                reloadUnitPath: getSystemdUserReloadUnitPath(),
+                pathUnitPath: getSystemdUserPathUnitPath(),
+                runtimeEnvPath: getDefaultRuntimeEnvPath(),
+                serviceEnvPath: getDefaultServiceEnvPath(),
+                configPath: getDefaultConfigPath(),
+                restarted: true,
+            })
+            : "Reloaded systemd user units and reload-or-restart was requested for PatchRelay.\n");
+        return 0;
+    }
+    catch (error) {
+        writeOutput(params.stderr, `${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+function normalizePublicBaseUrl(value) {
+    const candidate = /^[a-zA-Z][a-zA-Z\d+.-]*:\/\//.test(value) ? value : `https://${value}`;
+    const url = new URL(candidate);
+    return url.origin;
+}

package/dist/cli/connect-flow.js

@@ -0,0 +1,52 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { formatJson } from "./formatters/json.js";
+import { writeOutput } from "./output.js";
+export function parseTimeoutSeconds(value, command) {
+    const timeoutSeconds = typeof value === "string" ? Number(value) : 180;
+    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
+        throw new Error(`${command} --timeout must be a positive number of seconds.`);
+    }
+    return timeoutSeconds;
+}
+export async function runConnectFlow(params) {
+    const result = await params.data.connect(params.projectId);
+    if (params.json) {
+        writeOutput(params.stdout, formatJson(result));
+        return 0;
+    }
+    if ("completed" in result && result.completed) {
+        const label = result.installation.workspaceName ?? result.installation.actorName ?? `installation #${result.installation.id}`;
+        writeOutput(params.stdout, `Linked project ${result.projectId} to existing Linear installation ${result.installation.id} (${label}). No new OAuth approval was needed.\n`);
+        return 0;
+    }
+    if ("completed" in result) {
+        throw new Error("Unexpected completed connect result.");
+    }
+    const opener = params.openExternal;
+    const opened = params.noOpen || !opener ? false : await opener(result.authorizeUrl);
+    writeOutput(params.stdout, `${result.projectId ? `Project: ${result.projectId}\n` : ""}${opened ? "Opened browser for Linear OAuth.\n" : "Open this URL in a browser:\n"}${opened ? result.authorizeUrl : `${result.authorizeUrl}\n`}Waiting for OAuth approval...\n`);
+    const deadline = Date.now() + (params.timeoutSeconds ?? 180) * 1000;
+    const pollIntervalMs = params.connectPollIntervalMs ?? 1000;
+    do {
+        const status = await params.data.connectStatus(result.state);
+        if (status.status === "completed") {
+            const label = status.installation?.workspaceName ?? status.installation?.actorName ?? `installation #${status.installation?.id ?? "unknown"}`;
+            writeOutput(params.stdout, [
+                `Connected ${label}${status.projectId ? ` for project ${status.projectId}` : ""}.${status.installation?.id ? ` Installation ${status.installation.id}.` : ""}`,
+                params.config.linear.oauth.actor === "app"
+                    ? "If your Linear OAuth app webhook settings are configured, Linear has now provisioned the workspace webhook automatically."
+                    : undefined,
+            ]
+                .filter(Boolean)
+                .join("\n") + "\n");
+            return 0;
+        }
+        if (status.status === "failed") {
+            throw new Error(status.errorMessage ?? "Linear OAuth failed.");
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`Timed out waiting for Linear OAuth after ${params.timeoutSeconds ?? 180} seconds.`);
+        }
+        await delay(pollIntervalMs);
+    } while (true);
+}