patchrelay 0.26.0 → 0.29.1

package/README.md

@@ -2,7 +2,7 @@
 
 PatchRelay is a self-hosted harness for running a controlled coding loop per Linear issue on your own machine.
 
-It receives Linear webhooks, routes issues to the right local repository, prepares durable issue worktrees, runs Codex sessions through `codex app-server`, and keeps the whole issue loop observable and resumable from the CLI. GitHub webhooks drive reactive loops for CI repair, review fixes, and merge queue failures.
+It receives Linear webhooks, routes issues to the right local repository, prepares durable issue worktrees, runs Codex sessions through `codex app-server`, and keeps the whole issue loop observable and resumable from the CLI. GitHub webhooks drive reactive loops for CI repair and review fixes. A separate [Merge Steward](./packages/merge-steward) service handles serial queue integration and landing.
 
 PatchRelay is the system around the model:
 
@@ -11,7 +11,8 @@ PatchRelay is the system around the model:
 - issue-to-repo routing
 - issue worktree and branch lifecycle
 - context packaging, run orchestration, and thread continuity
-- reactive CI repair, review fix, and merge queue repair loops
+- reactive CI repair and review fix loops
+- queue repair runs triggered by Merge Steward evictions
 - native Linear agent input forwarding into active runs
 - read-only inspection and run reporting
 
@@ -36,7 +37,7 @@ PatchRelay does the deterministic harness work that you do not want to re-implem
 - packages the right issue, repo, review, and failure context for each loop
 - creates and reuses one durable worktree and branch per issue lifecycle
 - starts Codex threads for implementation runs
-- triggers reactive runs for CI failures, review feedback, and merge queue failures
+- triggers reactive runs for CI failures, review feedback, and Merge Steward evictions
 - persists enough state to correlate the Linear issue, local workspace, run, and Codex thread
 - reports progress back to Linear and forwards follow-up agent input into active runs
 - exposes CLI and optional read-only inspection surfaces so operators can understand what happened
@@ -79,8 +80,9 @@ You will also need:
 2. PatchRelay verifies the webhook, routes the issue to the right local project, and packages the issue context for the first loop.
 3. Delegated issues create or reuse the issue worktree and launch an implementation run through `codex app-server`.
 4. PatchRelay persists thread ids, run state, and observations so the work stays inspectable and resumable.
-5. GitHub webhooks drive reactive verification and repair loops: CI repair on check failures, review fix on changes requested, and merge queue repair on queue failures.
-6. Native agent prompts and Linear comments can steer the active run. An operator can take over from the exact same worktree when needed.
+5. GitHub webhooks drive reactive verification and repair loops: CI repair on check failures and review fix on changes requested.
+6. When the PR is approved and CI is green, PatchRelay adds the `queue` label. Merge Steward takes over — rebasing, validating, and merging the PR. If the steward evicts the PR, PatchRelay triggers a queue repair run.
+7. Native agent prompts and Linear comments can steer the active run. An operator can take over from the exact same worktree when needed.
 
 ## Factory State Machine
 
@@ -127,6 +129,22 @@ PatchRelay uses repo-local workflow files as prompts for Codex runs:
 
 These files define how the agent should work in that repository. Keep them short, action-oriented, and human-authored.
 
+## Knowledge And Validation Surfaces
+
+PatchRelay works best when repository guidance follows progressive disclosure:
+
+- keep the root entrypoints short and navigational
+- treat deeper `docs/` content as the durable system of record
+- capture architecture, workflow, and product decisions in versioned files instead of chat history or operator memory
+
+PatchRelay should also help agents validate their own work inside the issue loop:
+
+- package the smallest useful context for the current run instead of replaying ever-growing transcript history
+- preserve high-signal failure evidence such as review feedback, failing checks, and queue incidents
+- make repo-local validation surfaces legible per worktree so the next run can see what passed, what failed, and what needs repair
+
+Keeping those knowledge and validation surfaces clean is part of the harness, not optional documentation polish.
+
 ## Access Control
 
 PatchRelay reacts only for issues that route to a configured project.
@@ -159,8 +177,6 @@ It creates the local config, env file, and system service units:
 - `~/.config/patchrelay/service.env`
 - `~/.config/patchrelay/patchrelay.json`
 - `/etc/systemd/system/patchrelay.service`
-- `/etc/systemd/system/patchrelay-reload.service`
-- `/etc/systemd/system/patchrelay.path`
 
 The generated `patchrelay.json` is intentionally minimal, and `patchrelay init` prints the webhook URL, OAuth callback URL, and the Linear app values you need next.
 
@@ -177,23 +193,37 @@ LINEAR_OAUTH_CLIENT_SECRET=replace-with-linear-oauth-client-secret
 
 Keep service secrets in `service.env`. `runtime.env` is for non-secret overrides such as `PATCHRELAY_DB_PATH` or `PATCHRELAY_LOG_FILE`. Everyday local inspection commands do not require exporting these values in your shell.
 
-### 4. Configure a project
+### 4. Connect PatchRelay to Linear
+
+Connect PatchRelay to one Linear workspace:
+
+```bash
+patchrelay linear connect
+patchrelay linear sync
+```
+
+This authorizes the workspace once, then caches its teams and projects locally. Workspace auth is separate from repo linking.
+
+### 5. Link a GitHub repo
 
-Add repositories after `patchrelay init` with `patchrelay project apply <id> <repo-path>`.
+Link repos by GitHub identity, not by local path:
 
-For a single project, that is usually enough. For multiple projects, add routing with `--issue-prefix APP` or `--team-id <linear-team-id>`.
+```bash
+patchrelay repo link krasnoperov/usertold --workspace usertold --team USE
+```
+
+PatchRelay treats the GitHub repo as the source of truth. It reuses an existing local clone under the managed repo root when `origin` already matches, or clones it automatically when missing. Use `--path <path>` only when you want a non-default local location.
 
-The generated `~/.config/patchrelay/patchrelay.json` is machine-level service config only. Project entries should be created with the CLI, not by hand-editing a placeholder template.
+The generated `~/.config/patchrelay/patchrelay.json` stays machine-level service config. Repo links should be created with the CLI, not by hand-editing the file.
 
-`patchrelay project apply` is idempotent:
+`patchrelay repo link` is idempotent:
 
-- it creates or updates the local project entry
-- it checks whether PatchRelay is ready
+- it creates or updates the linked repo entry
+- it refreshes the selected Linear workspace catalog before resolving teams/projects
 - it reloads the service when it can
-- it reuses or starts the Linear connect flow when the local setup is ready
 - if workflow files or secrets are still missing, it tells you exactly what to fix and can be rerun safely
 
-### 5. Add workflow docs to the repo
+### 6. Add workflow docs to the repo
 
 PatchRelay looks for:
 
@@ -204,21 +234,21 @@ REVIEW_WORKFLOW.md
 
 These files define how the agent should work in that repo.
 
-### 6. Validate
+### 7. Validate
 
 ```bash
 patchrelay doctor
+patchrelay service status
 ```
 
-### 7. Check the installation
+### 8. Check linked workspaces and repos
 
 ```bash
-patchrelay installations
+patchrelay linear list
+patchrelay repo list
 ```
 
-In the normal happy path, the earlier `patchrelay project apply <id> <repo-path>` command already handles the connect step for you. `patchrelay connect --project <id>` still exists as the advanced/manual command when you want to retry or debug only the Linear authorization layer.
-
-If you later add another local repo that should use the same Linear installation, run `patchrelay project apply <id> <repo-path>` for that repo too. PatchRelay now reuses the single saved installation automatically when there is no ambiguity, so you usually will not need another browser approval.
+If you later add another local repo from the same workspace, run `patchrelay repo link <owner/repo> --workspace <workspace> --team <team>` again. PatchRelay reuses the existing workspace installation instead of opening a new OAuth flow.
 
 Important:
 
@@ -236,16 +266,18 @@ Important:
 
 Useful commands:
 
-- `patchrelay list --active`
-- `patchrelay inspect APP-123`
-- `patchrelay live APP-123 --watch`
-- `patchrelay report APP-123`
-- `patchrelay events APP-123 --follow`
-- `patchrelay worktree APP-123 --cd`
-- `patchrelay open APP-123`
-- `patchrelay retry APP-123`
+- `patchrelay issue list --active`
+- `patchrelay issue show APP-123`
+- `patchrelay issue watch APP-123`
+- `patchrelay dashboard`
+- `patchrelay issue report APP-123`
+- `patchrelay issue events APP-123 --follow`
+- `patchrelay issue path APP-123 --cd`
+- `patchrelay issue open APP-123`
+- `patchrelay issue retry APP-123`
+- `patchrelay service logs --lines 100`
 
-`patchrelay open` is the handoff bridge: it opens Codex in the issue worktree and resumes the existing thread when PatchRelay has one.
+`patchrelay issue open` is the handoff bridge: it opens Codex in the issue worktree and resumes the existing thread when PatchRelay has one.
 
 Today that takeover path is intentionally YOLO mode: it launches Codex with `--dangerously-bypass-approvals-and-sandbox`.
 
@@ -261,12 +293,32 @@ PatchRelay keeps enough durable state to answer the questions that matter during
 - which files it changed
 - whether the run completed, failed, or needs handoff
 
+## Merge Steward
+
+[Merge Steward](./packages/merge-steward) is a separate service that owns serial merge queue integration. PatchRelay develops code and produces pull requests. Merge Steward delivers those PRs into production — rebasing onto main, waiting for CI, and merging when green.
+
+The two services communicate through GitHub. PatchRelay adds a `queue` label when a PR is ready. The steward processes the queue. On failure, the steward evicts the PR with a check run report, and PatchRelay can trigger a queue repair run in response.
+
+The steward now has its own bootstrap flow:
+
+```bash
+merge-steward init https://queue.example.com
+merge-steward attach app owner/repo --base-branch main --required-check test,lint
+merge-steward doctor --repo app
+merge-steward service status app
+merge-steward queue status --repo app
+```
+
+See [Merge queue](./docs/merge-queue.md) for the full two-service overview and [Merge Steward README](./packages/merge-steward/README.md) for operational details.
+
 ## Docs
 
 Use the README for the product overview and quick start. Use the docs for operating details:
 
+- [Merge queue and delivery](./docs/merge-queue.md)
 - [Self-hosting and deployment](./docs/self-hosting.md)
 - [Architecture](./docs/architecture.md)
+- [Design docs index](./docs/design-docs/index.md)
 - [Design principles](./docs/design-docs/core-beliefs.md)
 - [External reference patterns](./docs/references/external-patterns.md)
 - [Security policy](./SECURITY.md)

package/dist/agent-session-plan.js

@@ -88,7 +88,6 @@ export function buildAgentSessionPlan(params) {
     const runType = resolvePlanRunType(params);
     switch (params.factoryState) {
         case "delegated":
-        case "preparing":
             return setStatuses(planForRunType(runType, params), ["inProgress", "pending", "pending", "pending"]);
         case "implementing":
             return setStatuses(planForRunType("implementation", params), ["completed", "inProgress", "pending", "pending"]);
@@ -144,12 +143,6 @@ export function buildAgentSessionPlanForIssue(issue, options) {
         ...(options?.activeRunType ? { activeRunType: options.activeRunType } : {}),
     });
 }
-export function buildPreparingSessionPlan(runType) {
-    return buildAgentSessionPlan({
-        factoryState: "preparing",
-        pendingRunType: runType,
-    });
-}
 export function buildRunningSessionPlan(runType) {
     return buildAgentSessionPlan({
         factoryState: runType === "ci_repair" ? "repairing_ci"

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.26.0",
-  "commit": "a2509ed10bce",
-  "builtAt": "2026-03-27T10:15:02.197Z"
+  "version": "0.29.1",
+  "commit": "a5915b7ea36c",
+  "builtAt": "2026-03-31T23:14:36.879Z"
 }

package/dist/cli/args.js

@@ -2,26 +2,22 @@ import { UnknownCommandError, UnknownFlagsError } from "./errors.js";
 export const KNOWN_COMMANDS = new Set([
     "version",
     "serve",
-    "inspect",
-    "live",
-    "report",
-    "events",
-    "worktree",
-    "open",
-    "retry",
-    "list",
+    "issue",
     "doctor",
     "init",
-    "project",
+    "attach",
+    "repos",
+    "linear",
+    "repo",
+    "dashboard",
+    "dash",
+    "d",
+    "service",
     "connect",
     "installations",
     "feed",
-    "watch",
-    "install-service",
-    "restart-service",
     "help",
 ]);
-const ISSUE_KEY_PATTERN = /^[A-Za-z][A-Za-z0-9]*-\d+$/;
 export function parseArgs(argv) {
     const positionals = [];
     const flags = new Map();
@@ -60,10 +56,10 @@ export function resolveCommand(parsed) {
         return { command: "help", commandArgs: [] };
     }
     if (KNOWN_COMMANDS.has(requestedCommand)) {
-        return { command: requestedCommand, commandArgs: parsed.positionals.slice(1) };
-    }
-    if (ISSUE_KEY_PATTERN.test(requestedCommand)) {
-        return { command: "inspect", commandArgs: parsed.positionals };
+        const command = requestedCommand === "dash" || requestedCommand === "d"
+            ? "dashboard"
+            : requestedCommand;
+        return { command, commandArgs: parsed.positionals.slice(1) };
     }
     throw new UnknownCommandError(requestedCommand);
 }
@@ -92,7 +88,15 @@ export function assertKnownFlags(parsed, command, allowedFlags) {
     if (unknownFlags.length === 0) {
         return;
     }
-    throw new UnknownFlagsError(unknownFlags, command === "project" || command === "project apply" ? "project" : "root");
+    throw new UnknownFlagsError(unknownFlags, command === "repo"
+        ? "repo"
+        : command === "linear"
+            ? "linear"
+            : command === "issue"
+                ? "issue"
+                : command === "service"
+                    ? "service"
+                    : "root");
 }
 export function parsePositiveIntegerFlag(value, flagName) {
     if (typeof value !== "string") {

package/dist/cli/commands/feed.js

@@ -26,7 +26,7 @@ export async function handleFeedCommand(params) {
     const limit = parseLimit(params.parsed.flags.get("limit"));
     const follow = params.parsed.flags.get("follow") === true;
     const issueKey = readOptionalStringFlag(params.parsed, "issue");
-    const projectId = readOptionalStringFlag(params.parsed, "project");
+    const projectId = readOptionalStringFlag(params.parsed, "repo");
     const kind = readOptionalStringFlag(params.parsed, "kind");
     const stage = readOptionalStringFlag(params.parsed, "stage");
     const status = readOptionalStringFlag(params.parsed, "status");

package/dist/cli/commands/issues.js

@@ -1,13 +1,53 @@
 import { setTimeout as delay } from "node:timers/promises";
 import { getRunTypeFlag, parsePositiveIntegerFlag } from "../args.js";
+import { CliUsageError } from "../errors.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 handleIssueCommand(params) {
+    const subcommand = params.commandArgs[0];
+    if (!subcommand) {
+        throw new CliUsageError("patchrelay issue requires a subcommand.", "issue");
+    }
+    const nested = {
+        ...params,
+        commandArgs: params.commandArgs.slice(1),
+    };
+    switch (subcommand) {
+        case "show":
+            return await handleInspectCommand(nested);
+        case "list":
+            return await handleListCommand(nested);
+        case "watch": {
+            const flags = new Map(params.parsed.flags);
+            flags.set("watch", true);
+            return await handleLiveCommand({
+                ...nested,
+                parsed: {
+                    ...params.parsed,
+                    flags,
+                },
+            });
+        }
+        case "report":
+            return await handleReportCommand(nested);
+        case "events":
+            return await handleEventsCommand(nested);
+        case "path":
+            return await handleWorktreeCommand(nested);
+        case "open":
+            return await handleOpenCommand(nested);
+        case "retry":
+            return await handleRetryCommand(nested);
+        default:
+            throw new CliUsageError(`Unknown issue command: ${subcommand}`, "issue");
+    }
+}
 export async function handleInspectCommand(params) {
     const issueKey = params.commandArgs[0];
     if (!issueKey) {
-        throw new Error("inspect requires <issueKey>.");
+        throw new Error("show requires <issueKey>.");
     }
     const result = await params.data.inspect(issueKey);
     if (!result) {
@@ -19,7 +59,7 @@ export async function handleInspectCommand(params) {
 export async function handleLiveCommand(params) {
     const issueKey = params.commandArgs[0];
     if (!issueKey) {
-        throw new Error("live requires <issueKey>.");
+        throw new Error(`${params.parsed.flags.get("watch") === true ? "watch" : "status"} requires <issueKey>.`);
     }
     const watch = params.parsed.flags.get("watch") === true;
     do {
@@ -88,7 +128,7 @@ export async function handleEventsCommand(params) {
 export async function handleWorktreeCommand(params) {
     const issueKey = params.commandArgs[0];
     if (!issueKey) {
-        throw new Error("worktree requires <issueKey>.");
+        throw new Error("path requires <issueKey>.");
     }
     const result = params.data.worktree(issueKey);
     if (!result) {
@@ -150,7 +190,7 @@ 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")) } : {}),
+        ...(typeof params.parsed.flags.get("repo") === "string" ? { project: String(params.parsed.flags.get("repo")) } : {}),
     });
     writeOutput(params.stdout, params.json ? formatJson(result) : formatList(result));
     return 0;

package/dist/cli/commands/linear.js

@@ -0,0 +1,67 @@
+import { loadConfig } from "../../config.js";
+import { runConnectFlow, parseTimeoutSeconds } from "../connect-flow.js";
+import { formatJson } from "../formatters/json.js";
+import { writeOutput } from "../output.js";
+import { openExternalUrl } from "../interactive.js";
+export async function handleLinearCommand(params) {
+    const subcommand = params.commandArgs[0] ?? "list";
+    const config = params.options?.config ?? loadConfig(undefined, { profile: "operator_cli" });
+    const data = params.options?.data ?? (await createCliOperatorDataAccess(config));
+    try {
+        switch (subcommand) {
+            case "connect":
+                return await runConnectFlow({
+                    config,
+                    data,
+                    stdout: params.stdout,
+                    noOpen: params.parsed.flags.get("no-open") === true,
+                    timeoutSeconds: parseTimeoutSeconds(params.parsed.flags.get("timeout"), "linear connect"),
+                    json: params.json,
+                    openExternal: params.options?.openExternal ?? openExternalUrl,
+                    ...(params.options?.connectPollIntervalMs !== undefined ? { connectPollIntervalMs: params.options.connectPollIntervalMs } : {}),
+                });
+            case "list": {
+                const result = await data.listLinearWorkspaces();
+                writeOutput(params.stdout, params.json
+                    ? formatJson({ ok: true, ...result })
+                    : result.workspaces.length === 0
+                        ? "No Linear workspaces connected.\n"
+                        : `${result.workspaces.map((workspace) => {
+                            const name = workspace.installation.workspaceKey ?? workspace.installation.workspaceName ?? `installation-${workspace.installation.id}`;
+                            return `${name}  repos=${workspace.linkedRepos.length} teams=${workspace.teams.length} projects=${workspace.projects.length}`;
+                        }).join("\n")}\n`);
+                return 0;
+            }
+            case "sync": {
+                const workspace = params.commandArgs[1];
+                const result = await data.syncLinearWorkspace(workspace);
+                writeOutput(params.stdout, params.json
+                    ? formatJson({ ok: true, ...result })
+                    : `Synced ${result.installation.workspaceKey ?? result.installation.workspaceName ?? result.installation.id}: ${result.teams.length} teams, ${result.projects.length} projects\n`);
+                return 0;
+            }
+            case "disconnect": {
+                const workspace = params.commandArgs[1];
+                if (!workspace) {
+                    throw new Error("patchrelay linear disconnect requires <workspace>.");
+                }
+                const result = await data.disconnectLinearWorkspace(workspace);
+                writeOutput(params.stdout, params.json
+                    ? formatJson({ ok: true, ...result })
+                    : `Disconnected ${result.installation.workspaceKey ?? result.installation.workspaceName ?? result.installation.id}.\n`);
+                return 0;
+            }
+            default:
+                throw new Error(`Unknown linear subcommand: ${subcommand}`);
+        }
+    }
+    finally {
+        if (!params.options?.data) {
+            data.close();
+        }
+    }
+}
+async function createCliOperatorDataAccess(config) {
+    const { CliOperatorApiClient } = await import("../operator-client.js");
+    return new CliOperatorApiClient(config);
+}