patchrelay 0.47.2 → 0.49.0

package/README.md

@@ -1,417 +1,126 @@
 # PatchRelay
 
-PatchRelay is a self-hosted harness for delegated Linear work and upkeep of linked pull requests on your own machine.
+Self-hosted toolkit for shipping code with agents: a Linear-driven harness that runs Codex sessions inside your real repos, plus two GitHub-native services that review PRs and deliver them through a merge queue. Each component works on its own, and they communicate only through GitHub.
 
-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 issue loop observable and resumable from the CLI. GitHub webhooks drive reactive loops for CI repair, review fixes, and merge-steward incidents on linked delegated PRs. Separate downstream services own review automation and merge execution.
+## The stack
 
-PatchRelay is the system around the model:
+This repository ships **three independent services**. Install one, two, or all three.
 
-- webhook intake and verification (Linear and GitHub)
-- Linear OAuth and workspace installations
-- issue-to-repo routing
-- issue worktree and branch lifecycle
-- context packaging, run orchestration, and thread continuity
-- 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
+| Service | Package | Role |
+|-|-|-|
+| [`patchrelay`](./) | `npm install -g patchrelay` | Linear-driven harness that runs Codex sessions inside your real repos. Fully autonomous on webhooks: implementation, review fix, CI repair, queue repair. |
+| [`review-quill`](./packages/review-quill) | `npm install -g review-quill` | GitHub PR review bot. Reviews every merge-ready head from a real local checkout and posts a normal `APPROVE` / `REQUEST_CHANGES` review. |
+| [`merge-steward`](./packages/merge-steward) | `npm install -g merge-steward` | Serial merge queue. Speculatively integrates approved PRs on top of the latest `main`, runs CI on the integrated SHA, and fast-forwards `main` only when that tested result is green. |
 
-If you want Codex to work inside your real repos with your real tools, secrets, SSH access, and deployment surface, PatchRelay is the harness that makes that loop reliable.
+Common setups:
 
-## Why PatchRelay
+- **Full autonomy** — all three. PatchRelay implements from a Linear issue, review-quill reviews, merge-steward delivers. No human in the room.
+- **Supervised delivery** — `review-quill` + `merge-steward` without PatchRelay, driven by your own agent (Claude Code, Cursor, Codex CLI, …). See [Use with your own agent](#use-with-your-own-agent).
+- **Queue only** or **review only** — run either downstream service on its own if you already have the other half of the story.
 
-- Keep the agent in the real environment instead of rebuilding that environment in a hosted sandbox.
-- Use your existing machine, repos, secrets, SSH config, shell tools, and deployment access.
-- Keep deterministic workflow logic outside the model: context packaging, routing, run orchestration, worktree ownership, verification, and reporting.
-- Choose the Codex approval and sandbox settings that match your risk tolerance.
-- Let Linear drive the loop through delegation and native agent sessions.
-- Let GitHub drive reactive loops through PR reviews and CI check events.
-- Drop into the exact issue worktree and resume control manually when needed.
+### What this buys you
 
-## What PatchRelay Owns
+- **PRs ship tested against the latest `main`.** The queue re-validates on the integrated SHA at admission time, and retries if `main` moves during validation. No more "green yesterday, broken today."
+- **Many PR failures have mechanical fixes an agent can handle.** Requested changes like a rename, a missing null check, a new test; rebase on `main`; resolving a conflict surfaced by speculation; rerunning a flaky job. Both services publish structured failure reasons (inline review comments, failing check names, queue incidents) an agent can act on directly.
+- **No prerequisites beyond GitHub.** A GitHub App, a webhook, and `npm install -g` per service.
 
-PatchRelay does the deterministic harness work that you do not want to re-implement around every model run:
+## Use with your own agent
 
-- verifies and deduplicates Linear and GitHub webhooks
-- maps issue events to the correct local project
-- 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 Steward evictions
-- opens and updates PRs for delegated implementation work
-- marks its own PRs ready when implementation is complete
-- can later repair a linked PR that was opened externally once the issue is delegated
-- 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
+For supervised delivery — an agent you drive from Claude Code / Cursor / Codex iterating on PRs in real time — install the [`ship-pr`](https://github.com/krasnoperov/patchrelay-agents) skill from the companion marketplace:
 
-PatchRelay does not own review decisions or queue admission. GitHub is the source of truth for PR readiness, `reviewbot` owns review automation, and [Merge Steward](./packages/merge-steward) owns queueing and merge execution.
-
-## System Layers
-
-PatchRelay works best when read as five layers with clear ownership:
-
-- policy layer: repo workflow files (`IMPLEMENTATION_WORKFLOW.md`, `REVIEW_WORKFLOW.md`)
-- coordination layer: issue claiming, run scheduling, retry budgets, and reconciliation
-- execution layer: durable worktrees, Codex threads, and queued turn input delivery
-- integration layer: Linear webhooks, GitHub webhooks, OAuth, project routing, and state sync
-- observability layer: CLI inspection, session status, and operator endpoints
-
-That separation is intentional. PatchRelay is not the policy itself and it is not the coding agent. It is the harness that keeps context, action, verification, and repair coordinated in a real repository with real operational state.
-
-## Runtime Model
-
-PatchRelay is designed for a local, operator-owned setup:
-
-- PatchRelay service runs on your machine or server (default `127.0.0.1:8787`)
-- Codex runs through `codex app-server`
-- Linear is the control surface
-- `patchrelay` CLI is the operator interface
-- a reverse proxy exposes the Linear-facing and GitHub-facing webhook routes
-
-Linux and Node.js `24+` are the intended runtime.
-
-You will also need:
-
-- `git`
-- `codex`
-- a Linear OAuth app for this PatchRelay deployment
-- a Linear webhook secret
-- a public HTTPS entrypoint such as Caddy, nginx, or a tunnel so Linear and GitHub can reach your PatchRelay webhooks
-
-## How It Works
-
-1. A human delegates PatchRelay on an issue to start automation.
-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 the appropriate first 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 and review fix on changes requested.
-6. Implementation issues usually open draft PRs while work is in progress and mark PatchRelay-owned PRs ready when implementation is complete.
-7. Downstream automation reacts to GitHub truth: `reviewbot` reviews ready PRs with green CI, and Merge Steward admits ready PRs with green CI and approval into the merge queue.
-8. If requested changes, red CI, or a merge-steward incident lands on a linked delegated PR, PatchRelay resumes work on that same PR branch.
-9. Native agent prompts and Linear comments can steer the active run. An operator can take over from the exact same worktree when needed.
-
-Not every delegated issue should produce its own PR. Some delegated issues are coordination-only:
-
-- parent trackers that spawn or coordinate child implementation issues
-- audit or convergence issues that should wait for child issues before doing a narrow final pass
-- planning/specification issues that are complete once the right follow-up issues or decisions exist
-
-In those cases, PatchRelay should avoid opening an overlapping umbrella PR and should finish through coordination, follow-up issue creation, or a no-PR completion path instead.
-
-### Undelegation And Re-delegation
-
-Undelegation pauses PatchRelay authority. It does not erase PR truth.
-
-- If there is no PR yet, the issue keeps its literal local-work state such as `delegated` or `implementing`, but PatchRelay becomes paused.
-- If a PR already exists, the issue keeps its PR-backed state and PatchRelay becomes observer-only.
-- Worktrees, branches, and PRs remain in place.
-- PatchRelay still reflects GitHub review, CI, queue, merge, and close events while undelegated.
-- PatchRelay does not enqueue implementation, review-fix, CI-repair, or queue-repair work again until the issue is delegated back.
-- If someone opens a new PR for the issue while it is undelegated, PatchRelay can link that PR when the title, body, or branch name contains one unambiguous tracked issue key for the project.
-
-Downstream services stay PR-centric:
-
-- `review-quill` may still review a qualifying PR
-- `merge-steward` may still queue or merge a qualifying PR
-
-When the issue is delegated back to PatchRelay, it should resume from current truth:
-
-- no PR: queue implementation
-- PR with requested changes: queue review fix or branch upkeep
-- PR with failing CI: queue CI repair
-- PR with queue eviction/conflict: queue queue repair
-- healthy open PR: keep waiting on review
-- approved PR: keep waiting downstream
-
-## Ownership Model
-
-PatchRelay keeps ownership simple:
-
-- workflow truth: the current factory state plus GitHub PR/review/CI facts
-- runtime authority: whether PatchRelay may actively write or repair code right now
-
-PatchRelay persists one explicit authority bit:
-
-- `delegatedToPatchRelay`: whether PatchRelay may actively implement or repair code for the issue right now
-
-Once a PR is linked to an issue, delegation decides whether PatchRelay may repair it. The PR may have been opened by PatchRelay, a human, or another external system.
-
-That authority does not change just because:
-
-- the issue is undelegated
-- the PR becomes ready for review
-- the PR is approved
-- the PR enters or leaves the merge queue
-
-## Factory State Machine
-
-Each issue progresses through a factory state machine:
-
-```text
-delegated → preparing → implementing → pr_open → awaiting_review
-  → changes_requested (review fix run) → back to implementing
-  → repairing_ci (CI repair run) → back to pr_open
-  → awaiting_queue → done (merged)
-  → repairing_queue (queue repair run) → back to pr_open
-  → escalated or failed (when retry budgets are exhausted)
+```
+/plugin marketplace add krasnoperov/patchrelay-agents
+/plugin install ship-pr@patchrelay
 ```
 
-Run types:
-
-- `implementation` — initial coding work
-- `review_fix` — address reviewer feedback
-- `ci_repair` — fix failing CI checks
-- `queue_repair` — fix merge queue failures
-
-PatchRelay treats these as distinct loop types with different context, entry conditions, and success criteria rather than as one generic "ask the agent again" workflow.
-
-The long-term runtime model is a small durable `IssueSession`:
-
-- `idle`
-- `running`
-- `waiting_input`
-- `done`
-- `failed`
-
-Waiting on review or queue should be represented as a waiting reason, not as a large internal control-plane state machine.
-
-`awaiting_input` is reserved for real human-needed situations:
-
-- a completion check asked a question
-- an operator explicitly stopped the run and wants a next decision
-- a reply is required before PatchRelay can continue
-
-Undelegated local work should stay in its literal workflow state and show a paused waiting reason instead.
-
-## Restart And Reconciliation
-
-PatchRelay treats restart safety as part of the harness contract, not as a best-effort extra.
-
-After a restart, the service can answer:
-
-- which issue owns each active worktree
-- which run was active or queued
-- which Codex thread and turn belong to that work
-- whether the issue is still eligible to continue
-- whether the run should resume, hand off, or fail back to a human state
-
-This is why PatchRelay keeps a durable `issues` and `runs` table alongside Codex thread history and Linear state. The goal is not to duplicate the model transcript. The goal is to make automation restartable, inspectable, and recoverable when the process or machine is interrupted.
-
-## Workflow Files
-
-PatchRelay uses repo-local workflow files as prompts for Codex runs:
-
-- `IMPLEMENTATION_WORKFLOW.md` — used for implementation, CI repair, and queue repair runs
-- `REVIEW_WORKFLOW.md` — used for review fix runs
-
-These files define how the agent should work in that repository. Keep them short, action-oriented, and human-authored.
-
-The built-in PatchRelay prompt scaffold lives in `src/prompting/patchrelay.ts`. It is intentionally small: task objective, scope discipline, reactive repair context, workflow guidance, and publication contract. Installation-level and repo-level prompt config can add one extra instructions file or replace a small set of policy sections. See [`docs/prompting.md`](./docs/prompting.md).
-
-## 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.
-
-- use `linear_team_ids`, `issue_key_prefixes`, and optional labels to keep unrelated or public boards out of scope
-- in the normal setup, anyone with access to the routed Linear project can delegate work to the PatchRelay app
-- use `trusted_actors` only when a project needs a narrower allowlist inside Linear
+`ship-pr` teaches the agent to block on `review-quill pr status --wait` and `merge-steward pr status --wait`, read structured failure reasons on exit `2`, fix the code, push, and re-enter the wait. No polling loop, no LLM-judged "is it done yet?". See [patchrelay-agents](https://github.com/krasnoperov/patchrelay-agents) for more.
 
-That keeps the default model simple without forcing an extra allowlist for every team.
+## Quick start (PatchRelay harness)
 
-## Quick Start
+Prerequisites:
 
-### 1. Install
+- Linux with shell access, Node.js `24+`
+- `git` and `codex` (authenticated for the same user that will run PatchRelay)
+- a Linear OAuth app and webhook secret
+- a public HTTPS entrypoint (Caddy, nginx, tunnel) so Linear and GitHub can reach your webhooks
 
 ```bash
 npm install -g patchrelay
-```
-
-### 2. Bootstrap config
-
-```bash
 patchrelay init https://patchrelay.example.com
 ```
 
-`patchrelay init` requires the public HTTPS origin up front because Linear needs a fixed webhook URL and OAuth callback URL for this PatchRelay instance.
-
-It creates the local config, env file, and system service units:
-
-- `~/.config/patchrelay/runtime.env`
-- `~/.config/patchrelay/service.env`
-- `~/.config/patchrelay/patchrelay.json`
-- `/etc/systemd/system/patchrelay.service`
-
-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.
-
-### 3. Configure access
-
-Edit `~/.config/patchrelay/service.env` and fill in only the Linear OAuth client values. Keep the generated webhook secret and token-encryption key:
+`init` writes the local config, env files, and systemd unit. Edit `~/.config/patchrelay/service.env` to fill in the Linear OAuth client id and secret (the webhook secret and token-encryption key are generated for you). Then:
 
 ```bash
-LINEAR_WEBHOOK_SECRET=generated-by-patchrelay-init
-PATCHRELAY_TOKEN_ENCRYPTION_KEY=generated-by-patchrelay-init
-LINEAR_OAUTH_CLIENT_ID=replace-with-linear-oauth-client-id
-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. 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
-
-Link repos by GitHub identity, not by local path:
-
-```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` stays machine-level service config. Repo links should be created with the CLI, not by hand-editing the file.
-
-`patchrelay repo link` is idempotent:
-
-- 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
-- if workflow files or secrets are still missing, it tells you exactly what to fix and can be rerun safely
-
-### 6. Add workflow docs to the repo
-
-PatchRelay looks for:
-
-```text
-IMPLEMENTATION_WORKFLOW.md
-REVIEW_WORKFLOW.md
-```
-
-These files define how the agent should work in that repo.
-
-### 7. Validate
-
-```bash
-patchrelay doctor
+patchrelay linear connect                              # one-time Linear OAuth
+patchrelay linear sync                                 # cache teams/projects
+patchrelay repo link krasnoperov/usertold \
+    --workspace usertold --team USE                    # link a GitHub repo
+patchrelay doctor                                      # validate
 patchrelay service status
 patchrelay dashboard
 ```
 
-### 8. Check linked workspaces and repos
-
-```bash
-patchrelay linear list
-patchrelay repo list
-```
-
-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:
+Each repo needs two workflow files that act as agent prompts:
 
-- Linear needs a public HTTPS URL to reach your webhook.
-- `patchrelay init <public-base-url>` writes `server.public_base_url`, which PatchRelay uses when it prints webhook URLs.
-- For ingress, OAuth app setup, and webhook details, use the self-hosting docs.
+- `IMPLEMENTATION_WORKFLOW.md` — implementation, CI repair, queue repair runs
+- `REVIEW_WORKFLOW.md` — review fix runs
 
-## Daily Loop
+Keep them short, action-oriented, human-authored. See [prompting.md](./docs/prompting.md) for how the built-in scaffold composes them with the rest of the prompt.
 
-1. Delegate a Linear issue to the PatchRelay app.
-2. Linear sends the delegation and agent-session webhooks to PatchRelay, which creates or reuses the issue worktree and launches an implementation run.
-3. Follow up in the Linear agent session to steer the active run or wake it with fresh input while it remains delegated.
-4. GitHub webhooks automatically trigger CI repair, review fix, or merge queue repair runs when needed.
-5. Watch progress from the terminal or open the same worktree and take over manually.
+Full install, ingress, and GitHub/Linear app setup: [self-hosting.md](./docs/self-hosting.md). Daily ops and CLI cheatsheet: [operator-guide.md](./docs/operator-guide.md).
 
-Useful commands:
+## How it works
 
-- `patchrelay dashboard`
-- `patchrelay issue list --active`
-- `patchrelay issue show APP-123`
-- `patchrelay issue watch APP-123`
-- `patchrelay issue path APP-123 --cd`
-- `patchrelay issue open APP-123`
-- `patchrelay issue retry APP-123`
-- `patchrelay service restart`
-- `patchrelay service logs --lines 100`
+1. A human delegates an issue to the PatchRelay Linear app.
+2. PatchRelay verifies the webhook, routes the issue to the right local repo, prepares a durable worktree, and launches an implementation run through `codex app-server`.
+3. PatchRelay persists thread ids, run state, and observations so work stays inspectable and restartable.
+4. GitHub webhooks drive reactive repair loops — CI repair on check failures, review fix on requested changes, queue repair on merge-steward evictions.
+5. `review-quill` reviews ready PRs; `merge-steward` admits approved, green PRs and delivers them by speculative integration.
+6. An operator can take over inside the same worktree at any time.
 
-PatchRelay's operator surface is being reduced to its own runtime responsibilities: issue status,
-active work, waiting reason, worktree handoff, and retry controls.
+Architecture and failure taxonomy: [architecture.md](./docs/architecture.md). Downstream delivery: [merge-queue.md](./docs/merge-queue.md).
 
-`patchrelay issue open` is the handoff bridge: it opens a normal Codex CLI session in the issue worktree and resumes the existing thread when PatchRelay has one.
+## Downstream services
 
-If automation looks stuck, this is the usual operator path:
+Two separate services handle review and delivery. Both are independent, GitHub-native, and usable without PatchRelay.
 
-1. `patchrelay dashboard` to see active issues and waiting reasons across the service.
-2. `patchrelay issue show APP-123` or `patchrelay issue watch APP-123` to inspect one issue in more detail.
-3. `patchrelay issue open APP-123` to take over inside the exact worktree and continue from the same issue context.
-4. `patchrelay service logs --lines 100` if the problem looks like webhook intake, Codex startup, or service runtime failure.
+### review-quill
 
-Today that takeover path is intentionally YOLO mode: it launches Codex with `--dangerously-bypass-approvals-and-sandbox`.
+Watches PRs and posts ordinary GitHub reviews from a real local checkout of the PR head. By default reviews as soon as the head updates; can optionally wait for configured checks to go green first.
 
-## Operator View
-
-PatchRelay keeps enough durable state to answer the questions that matter during and after a run:
-
-- which worktree and branch belong to an issue
-- which run is active or queued
-- which Codex thread owns the current work
-- what the agent said
-- which commands it ran
-- which files it changed
-- whether the run completed, failed, or needs handoff
-
-## Merge Steward
+```bash
+review-quill init https://review.example.com
+review-quill repo attach owner/repo
+review-quill doctor --repo repo
+```
 
-[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.
+See the [review-quill package README](./packages/review-quill/README.md) for the pitch and quick start, or [docs/review-quill.md](./docs/review-quill.md) for the full operator reference.
 
-The two services communicate through GitHub. PatchRelay makes its own PR ready, and Merge Steward decides queue admission and merge execution from GitHub truth. On failure, the steward reports the incident through GitHub signals, and PatchRelay can trigger a queue repair run in response.
+### merge-steward
 
-The steward now has its own bootstrap flow:
+Serial merge queue with speculative integration. Rebases each approved PR onto the current `main`, runs CI on the integrated SHA, and fast-forwards `main` only when that tested result is green. Evictions produce a durable incident and a GitHub check run — the signal an agent uses to trigger a repair.
 
 ```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 attach owner/repo --base-branch main
+merge-steward doctor --repo repo
 merge-steward service status
-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.
+See the [merge-steward package README](./packages/merge-steward/README.md) for the pitch and quick start, [docs/merge-steward.md](./docs/merge-steward.md) for the full operator reference, or [docs/merge-queue.md](./docs/merge-queue.md) for the two-service overview.
 
 ## 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)
+- [Self-hosting and deployment](./docs/self-hosting.md) — install, ingress, OAuth and GitHub App setup
+- [Architecture](./docs/architecture.md) — components, ownership, state machine, failure taxonomy
+- [Operator guide](./docs/operator-guide.md) — daily loop, CLI cheatsheet, troubleshooting
+- [Merge queue](./docs/merge-queue.md) — the two-service delivery story
+- [Prompting](./docs/prompting.md) — how workflow files and the built-in scaffold compose
+- [Secrets](./docs/secrets.md) — systemd credentials, resolution order
+- [review-quill reference](./docs/review-quill.md) · [merge-steward reference](./docs/merge-steward.md)
+- [Product specs](./docs/product-specs/index.md) · [Design docs](./docs/design-docs/index.md) · [Core beliefs](./docs/design-docs/core-beliefs.md)
+- [Contributing](./CONTRIBUTING.md) · [Security policy](./SECURITY.md)
 
 ## Status
 

package/dist/agent-session-plan.js

@@ -19,6 +19,14 @@ function implementationPlan() {
         { content: "Merge", status: "pending" },
     ];
 }
+function orchestrationPlan() {
+    return [
+        { content: "Review umbrella goal and child set", status: "pending" },
+        { content: "Wait for or inspect child progress", status: "pending" },
+        { content: "Audit delivered outcome", status: "pending" },
+        { content: "Close umbrella or create follow-up work", status: "pending" },
+    ];
+}
 function reviewFixPlan() {
     return [
         { content: "Prepare workspace", status: "completed" },
@@ -95,6 +103,38 @@ function resolvePlanRunType(params) {
     }
 }
 export function buildAgentSessionPlan(params) {
+    if (params.issueClass === "orchestration") {
+        const settling = params.orchestrationSettleUntil
+            ? Number.isFinite(Date.parse(params.orchestrationSettleUntil)) && Date.parse(params.orchestrationSettleUntil) > Date.now()
+            : false;
+        if (settling) {
+            return [
+                { content: "Wait for child set to settle", status: "inProgress" },
+                { content: "Review umbrella goal and child set", status: "pending" },
+                { content: "Wait for or inspect child progress", status: "pending" },
+                { content: "Audit delivered outcome", status: "pending" },
+            ];
+        }
+        switch (params.factoryState) {
+            case "done":
+                return setStatuses(orchestrationPlan(), ["completed", "completed", "completed", "completed"]);
+            case "awaiting_input":
+            case "failed":
+            case "escalated":
+                return setStatuses(orchestrationPlan(), ["completed", "completed", "completed", "inProgress"]);
+            case "implementing":
+            case "changes_requested":
+            case "repairing_ci":
+            case "repairing_queue":
+                return setStatuses(orchestrationPlan(), ["completed", "inProgress", "pending", "pending"]);
+            case "pr_open":
+            case "awaiting_queue":
+                return setStatuses(orchestrationPlan(), ["completed", "completed", "inProgress", "pending"]);
+            case "delegated":
+            default:
+                return setStatuses(orchestrationPlan(), ["inProgress", "pending", "pending", "pending"]);
+        }
+    }
     const runType = resolvePlanRunType(params);
     switch (params.factoryState) {
         case "delegated":
@@ -151,6 +191,8 @@ export function buildAgentSessionPlanForIssue(issue, options) {
         factoryState: issue.factoryState,
         ciRepairAttempts: issue.ciRepairAttempts,
         queueRepairAttempts: issue.queueRepairAttempts,
+        ...(issue.issueClass ? { issueClass: issue.issueClass } : {}),
+        ...(issue.orchestrationSettleUntil ? { orchestrationSettleUntil: issue.orchestrationSettleUntil } : {}),
         ...(issue.pendingRunType ? { pendingRunType: issue.pendingRunType } : {}),
         ...(options?.activeRunType ? { activeRunType: options.activeRunType } : {}),
     });

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.47.2",
-  "commit": "8e7084588da7",
-  "builtAt": "2026-04-18T12:47:45.623Z"
+  "version": "0.49.0",
+  "commit": "e4ca4c92eb96",
+  "builtAt": "2026-04-19T10:24:09.505Z"
 }