patchrelay 0.47.2 → 0.48.0

package/README.md

@@ -1,416 +1,125 @@
 # 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)
+- [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)
+- [Design docs](./docs/design-docs/index.md) · [Core beliefs](./docs/design-docs/core-beliefs.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,27 @@ function resolvePlanRunType(params) {
     }
 }
 export function buildAgentSessionPlan(params) {
+    if (params.issueClass === "orchestration") {
+        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 +180,7 @@ export function buildAgentSessionPlanForIssue(issue, options) {
         factoryState: issue.factoryState,
         ciRepairAttempts: issue.ciRepairAttempts,
         queueRepairAttempts: issue.queueRepairAttempts,
+        ...(issue.issueClass ? { issueClass: issue.issueClass } : {}),
         ...(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.48.0",
+  "commit": "a606bc8b729a",
+  "builtAt": "2026-04-18T14:29:29.224Z"
 }

package/dist/db/issue-store.js

@@ -20,6 +20,14 @@ export class IssueStore {
                 sets.push("delegated_to_patchrelay = @delegatedToPatchRelay");
                 values.delegatedToPatchRelay = params.delegatedToPatchRelay ? 1 : 0;
             }
+            if (params.issueClass !== undefined) {
+                sets.push("issue_class = @issueClass");
+                values.issueClass = params.issueClass;
+            }
+            if (params.issueClassSource !== undefined) {
+                sets.push("issue_class_source = @issueClassSource");
+                values.issueClassSource = params.issueClassSource;
+            }
             if (params.issueKey !== undefined) {
                 sets.push("issue_key = COALESCE(@issueKey, issue_key)");
                 values.issueKey = params.issueKey;
@@ -221,7 +229,7 @@ export class IssueStore {
         else {
             this.connection.prepare(`
         INSERT INTO issues (
-          project_id, linear_issue_id, delegated_to_patchrelay, issue_key, title, description, url,
+          project_id, linear_issue_id, delegated_to_patchrelay, issue_class, issue_class_source, issue_key, title, description, url,
           priority, estimate,
           current_linear_state, current_linear_state_type, factory_state, pending_run_type, pending_run_context_json,
           branch_name, worktree_path, thread_id, active_run_id, status_comment_id,
@@ -234,7 +242,7 @@ export class IssueStore {
           ci_repair_attempts, queue_repair_attempts, review_fix_attempts, zombie_recovery_attempts, last_zombie_recovery_at,
           updated_at
         ) VALUES (
-          @projectId, @linearIssueId, @delegatedToPatchRelay, @issueKey, @title, @description, @url,
+          @projectId, @linearIssueId, @delegatedToPatchRelay, @issueClass, @issueClassSource, @issueKey, @title, @description, @url,
           @priority, @estimate,
           @currentLinearState, @currentLinearStateType, @factoryState, @pendingRunType, @pendingRunContextJson,
           @branchName, @worktreePath, @threadId, @activeRunId, @statusCommentId,
@@ -251,6 +259,8 @@ export class IssueStore {
                 projectId: params.projectId,
                 linearIssueId: params.linearIssueId,
                 delegatedToPatchRelay: params.delegatedToPatchRelay === false ? 0 : 1,
+                issueClass: params.issueClass ?? null,
+                issueClassSource: params.issueClassSource ?? null,
                 issueKey: params.issueKey ?? null,
                 title: params.title ?? null,
                 description: params.description ?? null,
@@ -479,6 +489,10 @@ export function mapIssueRow(row) {
         projectId: String(row.project_id),
         linearIssueId: String(row.linear_issue_id),
         delegatedToPatchRelay: Number(row.delegated_to_patchrelay ?? 1) !== 0,
+        ...(row.issue_class !== null && row.issue_class !== undefined ? { issueClass: String(row.issue_class) } : {}),
+        ...(row.issue_class_source !== null && row.issue_class_source !== undefined
+            ? { issueClassSource: String(row.issue_class_source) }
+            : {}),
         ...(row.issue_key !== null ? { issueKey: String(row.issue_key) } : {}),
         ...(row.title !== null ? { title: String(row.title) } : {}),
         ...(row.description !== null && row.description !== undefined ? { description: String(row.description) } : {}),

package/dist/db/migrations.js

@@ -4,6 +4,8 @@ CREATE TABLE IF NOT EXISTS issues (
   project_id TEXT NOT NULL,
   linear_issue_id TEXT NOT NULL,
   delegated_to_patchrelay INTEGER NOT NULL DEFAULT 1,
+  issue_class TEXT,
+  issue_class_source TEXT,
   issue_key TEXT,
   title TEXT,
   url TEXT,
@@ -242,6 +244,8 @@ export function runPatchRelayMigrations(connection) {
     // Clean up stale dedupe-only webhook records (no payload, never processable)
     connection.prepare("UPDATE webhook_events SET processing_status = 'processed' WHERE processing_status = 'pending' AND payload_json IS NULL").run();
     addColumnIfMissing(connection, "issues", "delegated_to_patchrelay", "INTEGER NOT NULL DEFAULT 1");
+    addColumnIfMissing(connection, "issues", "issue_class", "TEXT");
+    addColumnIfMissing(connection, "issues", "issue_class_source", "TEXT");
     // Add pending_merge_prep column for merge queue stewardship
     addColumnIfMissing(connection, "issues", "pending_merge_prep", "INTEGER NOT NULL DEFAULT 0");
     // Add merge_prep_attempts for retry budget / escalation
@@ -324,6 +328,8 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         project_id TEXT NOT NULL,
         linear_issue_id TEXT NOT NULL,
         delegated_to_patchrelay INTEGER NOT NULL DEFAULT 1,
+        issue_class TEXT,
+        issue_class_source TEXT,
         issue_key TEXT,
         title TEXT,
         description TEXT,
@@ -382,6 +388,8 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         project_id,
         linear_issue_id,
         delegated_to_patchrelay,
+        issue_class,
+        issue_class_source,
         issue_key,
         title,
         description,
@@ -438,6 +446,8 @@ function removeRetiredIssueColumnsIfPresent(connection) {
         project_id,
         linear_issue_id,
         COALESCE(delegated_to_patchrelay, 1),
+        issue_class,
+        issue_class_source,
         issue_key,
         title,
         description,

package/dist/github-webhook-terminal-handler.js

@@ -1,6 +1,7 @@
 import { resolveClosedPrDisposition, resolveClosedPrFactoryState } from "./pr-state.js";
 import { resolvePreferredCompletedLinearState } from "./linear-workflow.js";
 import { syncGitHubLinearSession } from "./github-linear-session-sync.js";
+import { wakeOrchestrationParentsForChildEvent } from "./orchestration-parent-wake.js";
 export async function handleGitHubTerminalPrEvent(params) {
     const { db, linearProvider, enqueueIssue, logger, codex, issue, event, config } = params;
     const eventType = event.triggerEvent === "pr_merged" ? "pr_merged" : "pr_closed";
@@ -66,6 +67,12 @@ export async function handleGitHubTerminalPrEvent(params) {
         }
     }
     if (event.triggerEvent === "pr_merged") {
+        wakeOrchestrationParentsForChildEvent({
+            db,
+            child: updatedIssue,
+            eventType: "child_delivered",
+            enqueueIssue,
+        });
         await completeLinearIssueAfterMerge(params, updatedIssue);
     }
     void syncGitHubLinearSession({

package/dist/issue-class.js

@@ -0,0 +1,31 @@
+function normalizeText(value) {
+    return value?.trim().toLowerCase() ?? "";
+}
+function looksLikeUmbrellaText(issue) {
+    const haystack = `${normalizeText(issue.title)}\n${normalizeText(issue.description)}`;
+    if (!haystack.trim())
+        return false;
+    return [
+        "umbrella",
+        "tracker",
+        "tracking",
+        "rollout",
+        "migration",
+        "convergence",
+        "audit",
+        "follow-up issues",
+        "planning/specification issue only",
+    ].some((token) => haystack.includes(token));
+}
+export function classifyIssue(params) {
+    if (params.issue.issueClass === "implementation" || params.issue.issueClass === "orchestration") {
+        return { issueClass: params.issue.issueClass, issueClassSource: "explicit" };
+    }
+    if (params.trackedDependentCount > 0) {
+        return { issueClass: "orchestration", issueClassSource: "hierarchy" };
+    }
+    if (looksLikeUmbrellaText(params.issue)) {
+        return { issueClass: "orchestration", issueClassSource: "heuristic" };
+    }
+    return { issueClass: "implementation", issueClassSource: "heuristic" };
+}

package/dist/issue-session-events.js

@@ -52,7 +52,7 @@ export function deriveSessionWakePlan(issue, events) {
             case "delegated":
                 if (!runType) {
                     runType = "implementation";
-                    wakeReason = "delegated";
+                    wakeReason = issue.issueClass === "orchestration" ? "initial_delegate" : "delegated";
                 }
                 if (payload?.promptContext !== undefined) {
                     context.promptContext = payload.promptContext;
@@ -61,6 +61,16 @@ export function deriveSessionWakePlan(issue, events) {
                     context.promptBody = payload.promptBody;
                 }
                 break;
+            case "child_changed":
+            case "child_delivered":
+            case "child_regressed":
+                if (!runType) {
+                    runType = "implementation";
+                    wakeReason = event.eventType;
+                }
+                Object.assign(context, payload ?? {});
+                resumeThread = true;
+                break;
             case "direct_reply": {
                 if (!runType) {
                     runType = issue.prReviewState === "changes_requested" ? "review_fix" : "implementation";
@@ -98,7 +108,7 @@ export function deriveSessionWakePlan(issue, events) {
             case "operator_prompt": {
                 if (!runType) {
                     runType = issue.prReviewState === "changes_requested" ? "review_fix" : "implementation";
-                    wakeReason = event.eventType;
+                    wakeReason = issue.issueClass === "orchestration" ? "human_instruction" : event.eventType;
                 }
                 const text = typeof payload?.text === "string"
                     ? payload.text

package/dist/no-pr-completion-check.js

@@ -1,4 +1,5 @@
 import { buildCompletionCheckActivity } from "./linear-session-reporting.js";
+import { wakeOrchestrationParentsForChildEvent } from "./orchestration-parent-wake.js";
 function shouldContinueForUnpublishedLocalChanges(message) {
     const normalized = message.trim().toLowerCase();
     if (!normalized)
@@ -206,6 +207,12 @@ export async function handleNoPrCompletionCheck(params) {
             detail: completionCheck.summary,
             activity: buildCompletionCheckActivity("done", completionCheck),
         });
+        const doneIssue = params.db.issues.getIssue(params.run.projectId, params.run.linearIssueId) ?? params.issue;
+        wakeOrchestrationParentsForChildEvent({
+            db: params.db,
+            child: doneIssue,
+            eventType: "child_delivered",
+        });
         return;
     }
     const failureReason = `No PR observed and the completion check failed this run: ${completionCheck.summary}`;

package/dist/orchestration-parent-wake.js

@@ -0,0 +1,37 @@
+import { classifyIssue } from "./issue-class.js";
+export function wakeOrchestrationParentsForChildEvent(params) {
+    const parentIds = [];
+    for (const blocker of params.db.issues.listIssueDependencies(params.child.projectId, params.child.linearIssueId)) {
+        const parent = params.db.issues.getIssue(params.child.projectId, blocker.blockerLinearIssueId);
+        if (!parent || !parent.delegatedToPatchRelay) {
+            continue;
+        }
+        const classification = classifyIssue({
+            issue: parent,
+            trackedDependentCount: params.db.issues.listDependents(parent.projectId, parent.linearIssueId).length,
+        });
+        if (classification.issueClass !== "orchestration") {
+            continue;
+        }
+        params.db.issueSessions.appendIssueSessionEventRespectingActiveLease(parent.projectId, parent.linearIssueId, {
+            projectId: parent.projectId,
+            linearIssueId: parent.linearIssueId,
+            eventType: params.eventType,
+            eventJson: JSON.stringify({
+                childIssueId: params.child.linearIssueId,
+                ...(params.child.issueKey ? { childIssueKey: params.child.issueKey } : {}),
+                ...(params.child.title ? { childTitle: params.child.title } : {}),
+                factoryState: params.child.factoryState,
+                ...(params.child.currentLinearState ? { currentLinearState: params.child.currentLinearState } : {}),
+                ...(params.child.prNumber !== undefined ? { prNumber: params.child.prNumber } : {}),
+                ...(params.child.prState ? { prState: params.child.prState } : {}),
+            }),
+            dedupeKey: `${params.eventType}:${parent.linearIssueId}:${params.child.linearIssueId}:${params.child.factoryState}:${params.child.prState ?? "no-pr"}`,
+        });
+        if (params.db.issueSessions.peekIssueSessionWake(parent.projectId, parent.linearIssueId)) {
+            params.enqueueIssue?.(parent.projectId, parent.linearIssueId);
+        }
+        parentIds.push(parent.linearIssueId);
+    }
+    return parentIds;
+}

package/dist/prompting/patchrelay.js

@@ -162,6 +162,41 @@ function buildScopeDiscipline(issue, context) {
         "- A review repair should fix the concrete concern on the current head, not silently expand the Linear issue into a broader rewrite.",
     ].join("\n");
 }
+function buildOrchestrationScopeDiscipline(context) {
+    const unresolvedBlockers = Array.isArray(context?.unresolvedBlockers)
+        ? context.unresolvedBlockers.filter((entry) => Boolean(entry) && typeof entry === "object")
+        : [];
+    const trackedDependents = Array.isArray(context?.trackedDependents)
+        ? context.trackedDependents.filter((entry) => Boolean(entry) && typeof entry === "object")
+        : [];
+    return [
+        "## Scope Discipline",
+        "",
+        "This issue is orchestration work.",
+        "Treat it as the owner of convergence across related issues rather than as a normal code-owning implementation branch.",
+        "Inspect why this wake happened before acting.",
+        "Do not create an overlapping umbrella PR unless this parent clearly owns unique direct cleanup work that child issues do not already cover.",
+        "If child work is still in motion, babysit the plan, record useful observations, and return to waiting.",
+        "If child work looks delivered, audit whether the original parent goal is actually satisfied.",
+        "Create blocking follow-up work only when it is necessary to satisfy the original parent goal.",
+        "Prefer non-blocking follow-up issues over keeping the umbrella open for optional polish or adjacent expansion.",
+        "",
+        "### Child Issue Summaries",
+        "",
+        ...(trackedDependents.length > 0
+            ? summarizeRelationEntries(trackedDependents, { emptyText: "No child issues are currently tracked." })
+            : ["No child issues are currently tracked."]),
+        "",
+        ...(unresolvedBlockers.length > 0
+            ? ["### Unresolved Blockers", "", ...summarizeRelationEntries(unresolvedBlockers), ""]
+            : []),
+        "### Convergence Rule",
+        "",
+        "- Close the umbrella when the original parent goal is satisfied.",
+        "- If you discover one missing required slice, you may create a justified blocking follow-up.",
+        "- Do not invent optional expansion without explicit human approval.",
+    ].join("\n");
+}
 function buildHumanContext(context) {
     const promptContext = typeof context?.promptContext === "string" ? context.promptContext.trim() : "";
     const latestPrompt = typeof context?.promptBody === "string" ? context.promptBody.trim() : "";
@@ -357,18 +392,30 @@ function buildFollowUpPromptPrelude(issue, runType, context) {
         "",
         wakeReason === "direct_reply"
             ? "Why this turn exists: A human reply arrived for the outstanding question from the previous turn."
-            : wakeReason === "completion_check_continue"
-                ? "Why this turn exists: The previous turn ended without a PR, and PatchRelay's completion check decided the work should continue automatically."
-                : wakeReason === "branch_upkeep"
-                    ? "Why this turn exists: GitHub still shows the PR branch as needing upkeep after the requested code change was addressed."
-                    : wakeReason === "followup_comment"
-                        ? "Why this turn exists: A human follow-up comment arrived after the previous turn."
-                        : `Why this turn exists: Continue the existing ${runType} run from the latest issue state.`,
+            : wakeReason === "initial_delegate"
+                ? "Why this turn exists: This orchestration issue was just delegated and needs an initial plan."
+                : wakeReason === "child_delivered"
+                    ? "Why this turn exists: A child issue was delivered and the umbrella needs to review the outcome."
+                    : wakeReason === "child_changed"
+                        ? "Why this turn exists: A child issue changed state and the umbrella may need to adjust."
+                        : wakeReason === "child_regressed"
+                            ? "Why this turn exists: A previously progressing child issue regressed and the umbrella needs to reassess."
+                            : wakeReason === "human_instruction"
+                                ? "Why this turn exists: A human added new guidance for this orchestration issue."
+                                : wakeReason === "completion_check_continue"
+                                    ? "Why this turn exists: The previous turn ended without a PR, and PatchRelay's completion check decided the work should continue automatically."
+                                    : wakeReason === "branch_upkeep"
+                                        ? "Why this turn exists: GitHub still shows the PR branch as needing upkeep after the requested code change was addressed."
+                                        : wakeReason === "followup_comment"
+                                            ? "Why this turn exists: A human follow-up comment arrived after the previous turn."
+                                            : `Why this turn exists: Continue the existing ${runType} run from the latest issue state.`,
         wakeReason === "direct_reply"
             ? "Required action now: Apply the latest human answer, continue from the current branch/session context, and publish the next concrete result."
-            : wakeReason === "completion_check_continue"
-                ? "Required action now: Continue from the current branch and thread context, finish the task, and publish the next concrete result."
-                : "Required action now: Continue from the latest branch state, refresh any stale assumptions, and publish the next concrete result.",
+            : wakeReason === "initial_delegate"
+                ? "Required action now: Inspect the umbrella goal, review the child set, and record the next orchestration step."
+                : wakeReason === "completion_check_continue"
+                    ? "Required action now: Continue from the current branch and thread context, finish the task, and publish the next concrete result."
+                    : "Required action now: Continue from the latest branch state, refresh any stale assumptions, and publish the next concrete result.",
         "",
     ];
     if (wakeReason === "completion_check_continue" && typeof context?.completionCheckSummary === "string" && context.completionCheckSummary.trim()) {
@@ -417,14 +464,32 @@ function buildWorkflowGuidance(repoPath, runType) {
     }
     return "";
 }
-function buildPublicationContract(runType) {
+function buildOrchestrationWorkflowGuidance() {
+    return [
+        "## Workflow Guidance",
+        "",
+        "Use the wake reason and current child issue summaries to decide what kind of orchestration work is needed now.",
+        "Typical orchestration phases are: initial setup, waiting on child progress, reviewing delivered child work, final audit, creating a justified follow-up, or closing the umbrella.",
+        "Keep outputs concise and observable in Linear.",
+    ].join("\n");
+}
+function buildPublicationContract(runType, issueClass) {
+    if (issueClass === "orchestration") {
+        return [
+            "## Publication Requirements",
+            "",
+            "Before finishing, publish the orchestration outcome rather than leaving it implicit.",
+            "By default, orchestration work should finish without opening an overlapping umbrella PR.",
+            "Valid orchestration outcomes include: recording an observation, updating the rollout plan, creating follow-up issues, opening a small cleanup PR that the parent clearly owns, or closing the umbrella.",
+            "If you create new blocking follow-up work, justify it against the original parent goal rather than optional polish.",
+        ].join("\n");
+    }
     if (runType === "implementation") {
         return [
             "## Publication Requirements",
             "",
             "Before finishing, publish the result instead of leaving it only in the worktree.",
             "If the task is genuinely complete without a PR, say so clearly in your normal summary instead of inventing one.",
-            "If the issue is acting as coordination-only work and the real implementation belongs in child issues, finish without opening an overlapping umbrella PR.",
             "If the worktree already contains relevant changes for this issue, verify them and publish them.",
             "If you changed files for this issue, commit them, push the issue branch, and open or update the PR before stopping.",
             "Do not stop with only local commits or uncommitted changes.",
@@ -456,6 +521,7 @@ function buildPublicationContract(runType) {
     ].join("\n");
 }
 function buildSections(issue, runType, repoPath, context, followUp = false) {
+    const issueClass = issue.issueClass;
     const sections = [
         { id: "header", content: buildPromptHeader(issue) },
     ];
@@ -463,7 +529,10 @@ function buildSections(issue, runType, repoPath, context, followUp = false) {
     if (followUp && reactiveContext) {
         sections.push({ id: "follow-up-turn", content: reactiveContext });
     }
-    sections.push({ id: "task-objective", content: buildTaskObjective(issue) }, { id: "scope-discipline", content: buildScopeDiscipline(issue, context) });
+    sections.push({ id: "task-objective", content: buildTaskObjective(issue) }, {
+        id: "scope-discipline",
+        content: issueClass === "orchestration" ? buildOrchestrationScopeDiscipline(context) : buildScopeDiscipline(issue, context),
+    });
     const humanContext = buildHumanContext(context);
     if (humanContext) {
         sections.push({ id: "human-context", content: humanContext });
@@ -471,11 +540,13 @@ function buildSections(issue, runType, repoPath, context, followUp = false) {
     if (!followUp && reactiveContext) {
         sections.push({ id: "reactive-context", content: reactiveContext });
     }
-    const workflow = buildWorkflowGuidance(repoPath, runType);
+    const workflow = issueClass === "orchestration"
+        ? buildOrchestrationWorkflowGuidance()
+        : buildWorkflowGuidance(repoPath, runType);
     if (workflow) {
         sections.push({ id: "workflow-guidance", content: workflow });
     }
-    sections.push({ id: "publication-contract", content: buildPublicationContract(runType) });
+    sections.push({ id: "publication-contract", content: buildPublicationContract(runType, issueClass) });
     return sections;
 }
 function filterAllowedReplacements(promptLayer) {

package/dist/run-orchestrator.js

@@ -16,6 +16,7 @@ import { RunReconciler } from "./run-reconciler.js";
 import { RunRecoveryService } from "./run-recovery-service.js";
 import { RunWakePlanner } from "./run-wake-planner.js";
 import { getRemainingZombieRecoveryDelayMs } from "./zombie-recovery.js";
+import { classifyIssue } from "./issue-class.js";
 import { loadConfig } from "./config.js";
 function lowerCaseFirst(value) {
     return value ? `${value.slice(0, 1).toLowerCase()}${value.slice(1)}` : value;
@@ -138,7 +139,7 @@ export class RunOrchestrator {
     materializeLegacyPendingWake(issue, lease) {
         return this.runWakePlanner.materializeLegacyPendingWake(issue, lease);
     }
-    buildImplementationCoordinationContext(issue) {
+    buildRelatedIssueContext(issue) {
         const unresolvedBlockers = this.db.issues
             .listIssueDependencies(issue.projectId, issue.linearIssueId)
             .filter((entry) => !isResolvedDependencyState(entry.blockerCurrentLinearStateType))
@@ -170,6 +171,19 @@ export class RunOrchestrator {
             ...(trackedDependents.length > 0 ? { trackedDependents } : {}),
         };
     }
+    classifyTrackedIssue(issue) {
+        const trackedDependentCount = this.db.issues.listDependents(issue.projectId, issue.linearIssueId).length;
+        const classification = classifyIssue({ issue, trackedDependentCount });
+        if (issue.issueClass === classification.issueClass && issue.issueClassSource === classification.issueClassSource) {
+            return issue;
+        }
+        return this.db.issues.upsertIssue({
+            projectId: issue.projectId,
+            linearIssueId: issue.linearIssueId,
+            issueClass: classification.issueClass,
+            issueClassSource: classification.issueClassSource,
+        });
+    }
     // ─── Run ────────────────────────────────────────────────────────
     async run(item) {
         await this.refreshCodexRuntimeConfig();
@@ -179,7 +193,8 @@ export class RunOrchestrator {
         if (this.leaseService.hasLocalLease(item.projectId, item.issueId)) {
             return;
         }
-        const issue = this.db.issues.getIssue(item.projectId, item.issueId);
+        const initialIssue = this.db.issues.getIssue(item.projectId, item.issueId);
+        const issue = initialIssue ? this.classifyTrackedIssue(initialIssue) : undefined;
         if (!issue || issue.activeRunId !== undefined)
             return;
         const issueSession = this.db.issueSessions.getIssueSession(item.projectId, item.issueId);
@@ -216,7 +231,7 @@ export class RunOrchestrator {
             ? await this.runCompletionPolicy.resolveRequestedChangesWakeContext(issue, runType, context)
             : context;
         const coordinationContext = runType === "implementation"
-            ? this.buildImplementationCoordinationContext(issue)
+            ? this.buildRelatedIssueContext(issue)
             : undefined;
         const effectiveContext = coordinationContext
             ? { ...coordinationContext, ...(baseContext ?? {}) }

package/dist/tracked-issue-projector.js

@@ -42,6 +42,7 @@ export function buildTrackedIssueRecord(params) {
         projectId: params.issue.projectId,
         linearIssueId: params.issue.linearIssueId,
         delegatedToPatchRelay: params.issue.delegatedToPatchRelay,
+        ...(params.issue.issueClass ? { issueClass: params.issue.issueClass } : {}),
         ...(params.issue.issueKey ? { issueKey: params.issue.issueKey } : {}),
         ...(params.issue.title ? { title: params.issue.title } : {}),
         ...(params.issue.url ? { issueUrl: params.issue.url } : {}),

package/dist/webhooks/comment-wake-handler.js

@@ -1,5 +1,6 @@
 import { triggerEventAllowed } from "../project-resolution.js";
 import { hasExplicitPatchRelayWakeIntent, isInertPatchRelayComment, isPatchRelayManagedCommentAuthor, } from "./comment-policy.js";
+import { classifyIssue } from "../issue-class.js";
 const ENQUEUEABLE_STATES = new Set(["pr_open", "changes_requested", "implementing", "delegated", "awaiting_input"]);
 export class CommentWakeHandler {
     db;
@@ -24,6 +25,10 @@ export class CommentWakeHandler {
         const issue = this.db.issues.getIssue(project.id, normalized.issue.id);
         if (!issue)
             return;
+        const issueClass = classifyIssue({
+            issue,
+            trackedDependentCount: this.db.issues.listDependents(project.id, normalized.issue.id).length,
+        }).issueClass;
         const trimmedBody = normalized.comment.body.trim();
         const installation = this.db.linearInstallations.getLinearInstallationForProject(project.id);
         const selfAuthored = isPatchRelayManagedCommentAuthor(installation, normalized.actor, normalized.comment.userName);
@@ -55,7 +60,7 @@ export class CommentWakeHandler {
         if (!issue.activeRunId) {
             if (ENQUEUEABLE_STATES.has(issue.factoryState)) {
                 const directReply = params.isDirectReplyToOutstandingQuestion(issue);
-                const wakeIntent = directReply || hasExplicitPatchRelayWakeIntent(trimmedBody);
+                const wakeIntent = issueClass === "orchestration" || directReply || hasExplicitPatchRelayWakeIntent(trimmedBody);
                 if (!wakeIntent) {
                     this.feed?.publish({
                         level: "info",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchrelay",
-  "version": "0.47.2",
+  "version": "0.48.0",
   "license": "MIT",
   "type": "module",
   "repository": {