omp-conductor 0.7.1 → 0.8.0

package/README.md

@@ -954,6 +954,7 @@ rest. `0` is a real value (a hard stop), not "unset".
 | Cap | Default | What it protects |
 | --- | --- | --- |
 | `maxConcurrentWorkers` | `2` (setup may write `1` on <16 GiB hosts) | Parallel omp sessions, each a child process of the daemon and all inside its cgroup. Two, because **CI runner slots, not model tokens, are the usual throughput ceiling** — a third worker would starve its own PR checks on a small self-hosted runner pool. On hosts under ~16 GiB RAM, prefer `1` so the unit stays out of swap ([host sizing](#host-sizing-and-memory)). Raise it only if you actually have the runners *and* the RAM. |
+| `maxConcurrentWorkersPerRepo` | `1` | Max live workers in the **same repo**. The mirror, branch-protection staleness and shared CI egress are all per-repo collision domains, so extra slots should land on other repos. Raise it only when a repo genuinely needs two workers at once. |
 | `dailySpendUsd` | `25` | Rolling-day spend ceiling in USD, or `null` for no spend gate. `0` is a hard stop. Metered from assistant `usage.cost.total`. |
 | `planUsage` | `null` (unmetered) | Subscription/plan allowance guard: `{ "windowId": "anthropic:7d", "maxUsedFraction": 0.85 }`, or `null` for no plan gate. Independent of `dailySpendUsd` — see [Plan allowance](#plan-allowance-planusage) below. |
 | `workerMaxTurns` | `120` | Startup ceiling for each new worker. Catches a session looping without converging; use `omp-conductor extend` to raise one live run without changing this default. |
@@ -1373,21 +1374,24 @@ omp-conductor decision resolve <id> --answer "yes, after #132 lands"
 omp-conductor decision withdraw <id> --reason "the release slipped a week"
 ```
 
-**`--resolves-when` is the part that makes a parked question wake up.** Three
+**`--resolves-when` is the part that makes a parked question wake up.** Six
 conditions, each one something this package can check without asking you:
 
 | Condition | Met when |
 | --- | --- |
 | `pr-merged:<https url>` | `gh` reports that pull request merged. |
+| `pr-checks-green:<https url>` | Every check on that pull request has a green verdict (a non-empty list, all `success`/`neutral`); a failing or still-pending check is not met. |
+| `pr-mergeable:<https url>` | The pull request is mergeable (`clean`, not `unknown` or conflicting). |
 | `issue-closed:<number>` | That issue is closed on the tracker. |
 | `npm-version:<pkg>@<version>` | `npm view <pkg>@<version> version` succeeds — the version is published. |
+| `rate-limit-reset:github` | GraphQL quota on `github` has any remaining capacity again. |
 
 The daemon evaluates them beside each tick, fire-and-forget: a hanging registry
 costs one unevaluated condition, never the tick. A met row is flagged in the next
 digest as `[CONDITION MET — act on this now]`, so the session acts on the answer
 at the moment it becomes actionable rather than when it happens to remember.
 
-Anything else exits `2` and lists the three forms. An unparseable condition on an
+Anything else exits `2` and lists the six forms. An unparseable condition on an
 existing row is *listed and never treated as met*: a grammar a future release
 adds must not make an old row unloadable, and a question must never be hidden by
 a condition nobody can check.
@@ -1613,6 +1617,7 @@ Field notes:
 | `defaults` | Every `Caps` field. Anything omitted falls back to the built-in default. |
 | `tracker.repo` | `owner/repo`. `tracker.kind` may be omitted; `"github"` is the only accepted value. |
 | `queueLabel` | The one label meaning "a human has signed this off as agent-ready". Matched exactly, case-sensitively. |
+| `groomBelow` | Optional; default `4`. Routable candidates below this count make the orchestrator's tick prompt say the queue is running low and to groom it (Duty 2). An integer ≥ 1; anything else degrades to the default. |
 | `stateLabels` | Optional; defaults to `agent:in-progress`, `agent:blocked`, `agent:failed`. |
 | `routing.labelPrefix` | Optional; defaults to `repo:`. |
 | `routing.repos` | At least one entry, or nothing can be routed. `name` defaults to the map key, `defaultBranch` to `main`. |
@@ -1710,6 +1715,7 @@ writes this file for external orchestration. A manual configuration has this for
 | Key | Required | Default | Notes |
 | --- | --- | --- | --- |
 | `intervalSeconds` | yes | — | Whole seconds between ticks, minimum `60`. A tick costs a full turn of a frontier model, so a sub-minute period is refused rather than obeyed. |
+| `budgetSeconds` | no | `600` | Seconds a turn may run before the tick guard refuses its remaining tool calls (#189), and before a queued operator message preempts them. An integer ≥ 60; anything else degrades to the default. |
 | `armedFile` | no | none — the gate passes | Path to the arm marker. A tick does nothing while the file is missing. Relative paths resolve against the session cwd, so `state/armed` means `<cwd>/state/armed`. |
 | `accessFile` | no | none — the gate passes | Path to the Telegram bridge's `access.json`. Every tick re-reads it and requires `enabled: true` with exactly one entry in `allowFrom`. Relative paths resolve against the session cwd. **Configure this on any fleet deploy** — see below. |
 | `message` | no | `Tick <ISO timestamp>: re-read <workspaceRoot>/ORCHESTRATOR.md from disk, then run your standing loop from it.`, then the `reporting.scope` line, then the delivery rule | Sent verbatim when set — and then it owns the whole contract: neither the scope line nor the delivery rule is appended to a prompt you wrote yourself. Re-read from disk on **every** tick, so rewording it binds the next heartbeat instead of waiting for a session restart; a re-read that fails — caught mid-edit, removed, or invalid — keeps the value read at session start rather than stopping the heartbeat. `intervalSeconds` is *not* re-read: rescheduling a live timer still needs a restart. The default *orders* the session to re-read its brief, naming the path resolved from the project's `workspaceRoot`, because a standing prompt drifts out of a long-lived session's context while the file on disk does not. |
@@ -1905,7 +1911,7 @@ least of all on a fleet whose session lives somewhere else.
 omp-conductor start [--port N] [--project NAME]
 omp-conductor --version
 omp-conductor stop
-omp-conductor restart [--port N] [--project NAME]
+omp-conductor restart [--now] [--timeout SECONDS] [--port N] [--project NAME]
 omp-conductor upgrade [--to VERSION] [--project NAME]
 omp-conductor status [--project NAME]
 omp-conductor ledger [--issue N] [--limit N] [--project NAME]
@@ -1917,7 +1923,7 @@ omp-conductor disarm [--project NAME]
 omp-conductor release-pane [--project NAME]
 omp-conductor tail <issue> [--project NAME]
 omp-conductor extend <issue> --turns N [--project NAME]
-omp-conductor unblock <issue> [--force] [--project NAME]
+omp-conductor unblock <issue> [--force] [--no-requeue] [--project NAME]
 omp-conductor verb <conductor_*> [--project NAME] [--arg k=v ...]
 omp-conductor friction <escalation-digest|report-noise|report-surprise> --detail TEXT [--issue N] [--project NAME]
 omp-conductor report --text TEXT [--kind material|digest] [--project NAME]
@@ -1926,7 +1932,7 @@ omp-conductor decision resolve <id> --answer TEXT [--project NAME]
 omp-conductor decision withdraw <id> [--reason TEXT] [--project NAME]
 omp-conductor decision list [--project NAME]
 omp-conductor daemon [--once] [--port N] [--project NAME]
-omp-conductor pause
+omp-conductor pause [--reason TEXT]
 omp-conductor resume
 omp-conductor graph-setup [--project NAME] [--write]
 omp-conductor brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]
@@ -1937,9 +1943,9 @@ omp-conductor help
 | --- | --- |
 | `start` | Start `herdr-fleet.service` when that optional unit is installed, clearing a previous pane-recovery pin, then spawn the dispatch loop in the background and wait until it answers `GET /healthz` on `:8787`. Without systemd or that unit it keeps the standalone daemon behaviour. It never clears pause or arms ticks. Refuses if a daemon is already live, naming its pid; if the process dies or never serves, it cleans up and quotes the tail of `daemon.log`. |
 | `stop` | Prefer `systemctl stop omp-conductor.service` when that unit's MainPID is the live daemon — systemd then owns the stop and will not schedule a restart for the exit it just requested. Otherwise `SIGTERM`, then `SIGKILL` after a 10-second grace period. Prints `not running` when there is nothing to stop, and tags the confirmation with `(via systemctl)` when the unit path was used. |
-| `restart` | Prefer `systemctl restart` when the unit owns the live pid so the replacement stays supervised; otherwise `stop` then `start`, inheriting the running daemon's port and project unless a flag overrides them. The new process **salvages dirty live worktrees before orphaning** those rows — see [Deploying a new package onto a busy fleet](#deploying-a-new-package-onto-a-busy-fleet). |
+| `restart [--now] [--timeout SECONDS] [--port N] [--project NAME]` | Drains the fleet by default: pause new claims, wait until live workers reach `0 / N` (bounded by `--timeout SECONDS`, default 1800 = 30 min), restart, then restore the prior dispatch state. Prefer `systemctl restart` when the unit owns the live pid so the replacement stays supervised; otherwise `stop` then `start`, inheriting the running daemon's port and project unless a flag overrides them. `--now` skips the drain and restarts immediately, orphaning any live runs (old behaviour). A drain that hits `--timeout` restarts nothing and leaves dispatch paused — `omp-conductor resume` lifts it, or re-run `restart` to keep waiting. The new process **salvages dirty live worktrees before orphaning** those rows — see [Deploying a new package onto a busy fleet](#deploying-a-new-package-onto-a-busy-fleet). |
 | `upgrade [--to VERSION] [--project NAME]` | Deterministically update the Bun-global CLI, omp plugin, Herdr recovery plugin, and managed brief as one release. Resolves the npm version and exact `gitHead`, pauses only new claims, drains active workers, installs all surfaces, reloads Herdr and the daemon, waits for pane recovery, verifies identities and fleet health twice, then restores the original dispatch state. A no-op when already current. Failure leaves dispatch paused. Must run outside a Herdr-managed session. |
-| `status [--project NAME]` | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / `brief` / `decisions` / optional `failure classes` and `code graph` / `daemon`, then the project body. The project body includes the latest completed dispatch timestamp, ready/routed/admitted counts, and bounded hold groups; API failures are marked `DEGRADED` so queue starvation cannot look idle. The next tick comes from the live heartbeat process, not a guess from log timestamps. Telegram health uses `getMe` to prove API authentication without sending a message and reports inbound bridge configuration separately. Configured graphs report prerequisites, indexed repos, timer state, and refresh freshness without blocking dispatch. A `reports` block lists everything the outbox has not delivered, with its age, and prints `pending` (nobody has it) differently from `SENDING` (outcome unknown, it may already have arrived) — see [Report delivery](#report-delivery-the-outbox). The daemon block includes `rss` from `/healthz`; live workers add a busy-deploy warning. A `.conductor-stalled` marker adds an `orchestrator STALLED since …` line. |
+| `status [--project NAME]` | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / `brief` / `decisions` / optional `failure classes` and `code graph` / `daemon`, then the project body. The project body includes the latest completed dispatch timestamp, ready/routed/admitted counts, bounded hold groups, and the GitHub API budget (`graphql` / `core` remaining and reset, in the caps block); API failures are marked `DEGRADED` so queue starvation cannot look idle. The next tick comes from the live heartbeat process, not a guess from log timestamps. Telegram health uses `getMe` to prove API authentication without sending a message and reports inbound bridge configuration separately. Configured graphs report prerequisites, indexed repos, timer state, and refresh freshness without blocking dispatch. A `reports` block lists everything the outbox has not delivered, with its age, and prints `pending` (nobody has it) differently from `SENDING` (outcome unknown, it may already have arrived) — see [Report delivery](#report-delivery-the-outbox). The daemon block includes `rss` from `/healthz`; live workers add a busy-deploy warning. A `.conductor-stalled` marker adds an `orchestrator STALLED since …` line. |
 | `ledger [--issue N] [--limit N]` | Every [mediated-verb](#the-mediated-verbs-126) call and how the daemon decided it: the verb, the arguments it was given, allow or refuse, the named refusal reason, and any resulting SHA. Sessions cannot push, open a PR, merge, label or release except through those verbs, so this is the record of what they *tried* as well as what they did — the thing an escalation cites. Reads (`conductor_pr_status`) are deliberately absent: a poll every thirty seconds would bury the refusals. `--issue` narrows to one issue's run; `--limit` defaults to 50. The newest few also appear in `status`. |
 | `board [--project NAME]` | Live keyboard-driven kanban over the same SQLite and `/healthz` truth as `status`, plus the tracker's current labels: Queue, Claimed, Running, Green, Blocked, Failed, Orphaned, and the last 24 hours of Merged and History. Columns are mutually exclusive and describe current state, not the newest run row, so a requeued issue is queued rather than failed and a closed issue is neither. Refreshes run/spend/turn values every second, and health plus the label read every ten seconds. `Enter` follows the selected transcript in place; `u` invokes the existing unblock workflow on a Blocked, Failed, or Orphaned card; `i` / `p` open the issue / PR; `r` refreshes health; `?` shows all keys. Requires an interactive terminal of at least 50×20. |
 | `hold [--project NAME]` | Soft stop: pause claiming **and** disarm ticks. Daemon and pane stay up. Prefer this over `pause` when the intent is "stop the conductor" without killing processes. See [Stop the conductor](#stop-the-conductor-hold--halt). |
@@ -1949,11 +1955,11 @@ omp-conductor help
 | `release-pane [--project NAME]` | Clear the `halt --pane` recovery pin so herdr-conductor may resume the fleet agent again. |
 | `tail <issue>` | Follow the newest run for that issue: the worker's assistant text as `assistant: …` and each tool it calls as `tool: <name>`, printed as they land. Workers are omp sessions inside the daemon rather than terminals, so this is the only way to watch one live — a herdr pane running it becomes an observation window. Starts from the top of the transcript, not the end, so attaching to a run that is already ten turns in shows those ten turns. Exits `1` with `no run recorded for #N` when the issue has never been dispatched, or `no transcript yet (state: …)` when the attempt has not opened one. Otherwise it runs until `Ctrl-C`, or until the run has finished and its transcript has been silent for five seconds, and prints `run ended: <state>`. |
 | `extend <issue> --turns N [--project NAME]` | Monotonically raise that live worker's effective turn ceiling through its owning daemon. The current omp session keeps running; no restart or continuation is created. The daemon persists the new ceiling for `status` and rejects missing, settled, cap-killed, equal, or lower requests instead of implying that an immutable session changed. |
-| `unblock <issue> [--force]` | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again. `agent:in-progress` comes off too, but only when the newest recorded run is terminal — that row is the proof no worker still owns the issue, so a live run keeps the label, and so does an issue with no run row at all. Run history remains intact: blocks consume the independent continuation budget, not failed implementation attempts. The output reports both budgets and warns when either will make the next tick escalate instead of dispatch. **Refuses, clearing nothing and exiting `3`, when the newest attempt's work could not be committed and its worktree is the only copy** — re-claiming removes that tree. `--force` records the operator's acceptance on the run row and then clears; the salvage failure stays in history. Exits `2` when the issue number is missing or malformed. |
+| `unblock <issue> [--force] [--no-requeue]` | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again, and restore the project queue label by default so the dispatcher actually sees it. `agent:in-progress` comes off too, but only when the newest recorded run is terminal — that row is the proof no worker still owns the issue, so a live run keeps the label (and the queue label stays off until that run settles), and so does an issue with no run row at all. Run history remains intact: blocks consume the independent continuation budget, not failed implementation attempts. The output reports both budgets and warns when either will make the next tick escalate instead of dispatch. `--no-requeue` clears the state labels only, leaving the queue label untouched — the case where you are about to close the issue. **Refuses, clearing nothing and exiting `3`, when the newest attempt's work could not be committed and its worktree is the only copy** — re-claiming removes that tree. `--force` records the operator's acceptance on the run row and then clears; the salvage failure stays in history. Exits `2` when the issue number is missing or malformed. |
 | `verb <conductor_*> [--arg k=v ...]` | Run one [mediated verb](#the-mediated-verbs-126) as the orchestrator, from the CLI — the external-orchestrator half of the verb surface. Every argument goes in as a `--arg k=v` string; an orchestrator can merge (`conductor_pr_merge`), label (`conductor_label`), release (`conductor_release`), update a branch (`conductor_pr_update_branch`) or title/body (`conductor_pr_update`), or read PR state (`conductor_pr_status`). The daemon applies the same checks and writes the same ledger rows a session's call would; a missing `--arg` is refused exactly as a missing tool argument is, worker-only verbs (`conductor_push`, `conductor_pr_create`) are refused with `role-not-allowed`, and a refusal exits `3`. An unknown verb exits `2`. |
 | `friction <kind> --detail TEXT [--issue N]` | Record one bounded judgment the daemon cannot infer: an escalation belonged in a digest, or a tick report was noise/surprising. The detail is limited to 160 characters. One event never changes policy; three observations inside seven days make the aggregate eligible for one Learning-loop prompt, followed by a seven-day cooldown. |
 | `report --text TEXT [--kind material|digest]` | Hand a rendered report to the daemon's durable outbox. The text is persisted **before** anything is sent and the command prints a report id; the daemon then owns delivery, retries on a bounded backoff, and records the Telegram message id it actually got back. Delivery is [at-least-once](#report-delivery-the-outbox) — a crash mid-send is retried and the retry says it may be a repeat — so `delivered` is never proof of exactly one message. `--kind digest` is accepted at most once per local day, decided from the ledger rather than from what the session remembers sending; an unknown `--kind` exits `2` rather than quietly becoming a material report. Anything undelivered shows in `status` with its age. |
-| `decision open --question TEXT [--blocks TEXT] [--resolves-when COND]` | Record a question the orchestrator has put to you, and print its id. A question that lives only in a session's context is lost at the next compaction — after which it is either asked twice or dropped silently. `--resolves-when` attaches a machine-checkable condition: `pr-merged:<https url>`, `issue-closed:<n>`, or `npm-version:<pkg>@<version>`; anything else exits `2` listing the three forms. See [The decision ledger](#the-decision-ledger-136). |
+| `decision open --question TEXT [--blocks TEXT] [--resolves-when COND]` | Record a question the orchestrator has put to you, and print its id. A question that lives only in a session's context is lost at the next compaction — after which it is either asked twice or dropped silently. `--resolves-when` attaches a machine-checkable condition: `pr-merged:<https url>`, `pr-checks-green:<https url>`, `pr-mergeable:<https url>`, `issue-closed:<n>`, `npm-version:<pkg>@<version>`, or `rate-limit-reset:github`; anything else exits `2` listing the six forms. See [The decision ledger](#the-decision-ledger-resolves-when). |
 | `decision resolve <id> --answer TEXT` | Record what you decided. Exits `1` naming the id when it is unknown or no longer open, so a second answer cannot overwrite the first. |
 | `decision withdraw <id> [--reason TEXT]` | Close a question the session stopped needing, with why. Same guard as `resolve`. |
 | `decision list` | Open questions, oldest first: id, age, what each blocks, whether its condition is met, and the question. Prints `no open decisions` when there are none. |
@@ -1961,7 +1967,7 @@ omp-conductor help
 | `daemon --once` | Run a single tick, wait for workers admitted by that tick, and exit. No HTTP server or pidfile — a drill must not register itself as the daemon, or the next reader believes it and the real daemon's in-flight runs get reconciled as orphans. |
 | `--port N` | Accepted by `start`, `restart` and `daemon`. Both `--port 9000` and `--port=9000` work; missing or out of range exits `2` rather than falling back to the default, because probing the wrong endpoint is worse than a hard failure. |
 | `--project NAME` | Pick the project to service. One daemon process serves exactly one project; with several configured projects the name is required. |
-| `pause` | Stop claiming new work only. The running daemon notices on its next tick; runs already in flight finish. The orchestrator heartbeat keeps ticking if armed — its gate is the arm marker, not this flag. Prefer `hold` to silence both. |
+| `pause [--reason TEXT]` | Stop claiming new work only. The running daemon notices on its next tick; runs already in flight finish. The orchestrator heartbeat keeps ticking if armed — its gate is the arm marker, not this flag. Prefer `hold` to silence both. `--reason TEXT` is recorded in the pause sentinel, which `status` shows as the pause provenance. |
 | `resume` | Clear pause only — does **not** re-arm. Run `arm` after an inbound Telegram proof to resume ticks. |
 | `--version`, `-V`, `version` | Print the installed `omp-conductor` package version and exit `0`. Works from the global binary and npm/plugin install because it reads the package metadata beside the shipped CLI. |
 | `graph-setup` | Print how to set up the code-graph indexes workers query instead of grepping: a `git clone` for every index-only clone that does not exist yet, the one-shot index command per repo, and a `cbm-reindex.service` + `cbm-reindex.timer` pair generated from the project's own repos and branches. Reads only, so it is safe on a host where you are not root. Exits `1` when no repo in the project has [`graphProject`](#configuration) set, because the fix is a wizard answer rather than a flag. See [Code-graph discovery](#code-graph-discovery). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/src/briefs/orchestrator.md

@@ -282,6 +282,16 @@ Not yours to relax:
   not the branch. A settled run means nobody else is coming:
   waiting is not caution, it is a stall.
 
+**You never sleep, poll, or wait inside a tick.** No `sleep`, no retry loop, no
+"watch this PR until green" — a tool call that exists to pass time is a tool
+call that blocks your operator's messages. Anything that needs waiting for is
+either a watch (`decision open --resolves-when pr-checks-green:<url>`,
+`pr-mergeable:<url>`, `pr-merged:<url>`, `issue-closed:<n>`,
+`npm-version:<pkg>@<version>`, `rate-limit-reset:github`) or a subagent's
+problem. The harness refuses further tool calls once a turn exceeds its budget
+or an operator message is queued — end the turn and let the next tick act on
+`[CONDITION MET]`.
+
 ## Your verb surface
 
 You can reach `gh`, and you do not publish with it. Everything below happens
@@ -420,8 +430,9 @@ omp-conductor decision withdraw <id> --reason "<why it stopped mattering>"
 ```
 
 Use `--resolves-when` whenever the answer only becomes actionable once something
-observable happens: `pr-merged:<url>`, `issue-closed:<n>`,
-`npm-version:<pkg>@<version>`. The daemon checks it for you and flags the row as
+observable happens: `pr-merged:<url>`, `pr-checks-green:<url>`,
+`pr-mergeable:<url>`, `issue-closed:<n>`, `npm-version:<pkg>@<version>`,
+`rate-limit-reset:github`. The daemon checks it for you and flags the row as
 `[CONDITION MET — act on this now]` in your tick digest, so a parked question
 wakes up on its own instead of waiting for you to think of it.
 

package/src/cli.ts

@@ -44,6 +44,7 @@ import {
   startDaemon,
   stopDaemon,
   writeRecord,
+  type RestartResult,
 } from "./lifecycle.ts";
 import { STALL_MARKER_FILE } from "./orchestrator-tick.ts";
 import { digestDedupeKey } from "./reports.ts";
@@ -63,7 +64,7 @@ import { handleVerbCall, type VerbChannel } from "./verbs/server.ts";
 import { REPORT_KINDS, VERB_NAMES } from "./types.ts";
 import type { ProjectConfig, ReportKind } from "./types.ts";
 import { formatUnblock, unblockIssue } from "./unblock.ts";
-import { upgradeConductor } from "./upgrade.ts";
+import { DEFAULT_DEPS, drainAndRestart, upgradeConductor, type UpgradeDeps } from "./upgrade.ts";
 
 const FRICTION_FEEDBACK_KINDS = {
   "escalation-digest": "feedback:escalation-should-digest",
@@ -89,7 +90,7 @@ usage:
   omp-conductor start [--port N] [--project NAME]
   omp-conductor --version
   omp-conductor stop
-  omp-conductor restart [--port N] [--project NAME]
+  omp-conductor restart [--now] [--timeout SECONDS] [--port N] [--project NAME]
   omp-conductor upgrade [--to VERSION] [--project NAME]
   omp-conductor board [--project NAME]
   omp-conductor status [--project NAME]
@@ -101,10 +102,10 @@ usage:
   omp-conductor release-pane [--project NAME]
   omp-conductor tail <issue> [--project NAME]
   omp-conductor extend <issue> --turns N [--project NAME]
-  omp-conductor unblock <issue> [--force] [--project NAME]
+  omp-conductor unblock <issue> [--force] [--no-requeue] [--project NAME]
   omp-conductor verb <conductor_*> [--project NAME] [--arg k=v ...]
   omp-conductor daemon [--once] [--port N] [--project NAME]
-  omp-conductor pause
+  omp-conductor pause [--reason TEXT]
   omp-conductor resume
   omp-conductor graph-setup [--project NAME] [--write]
   omp-conductor brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]
@@ -126,11 +127,15 @@ usage:
   stop     stop the running daemon. Uses systemctl when the omp-conductor
            unit owns the process (so Restart=on-failure cannot bring it back);
            otherwise SIGTERM then SIGKILL.
-  restart  stop then start, keeping the running daemon's port and project
-           unless a flag overrides them. On boot the new process salvages any
-           dirty live worktrees before orphaning those rows — see README
-           "Deploying a new package onto a busy fleet". Goes through systemctl
-           when the unit owns the live pid.
+  restart  drain the fleet by default: pause new claims, wait until live workers
+           reach 0/N (bounded by --timeout SECONDS, default 1800), restart keeping
+           the running daemon's port and project unless a flag overrides them,
+           then restore the prior dispatch state. --now skips the drain and
+           restarts immediately, orphaning any live runs (old behavior). A drain
+           that hits --timeout restarts nothing and leaves dispatch paused. On boot
+           the new process salvages dirty live worktrees before orphaning those
+           rows — see README "Deploying a new package onto a busy fleet". Goes
+           through systemctl when the unit owns the live pid.
   status   layered fleet report: dispatch (running|paused|stopped), ticks and
            next due time, pane, herdr, Telegram bot/API health, daemon, caps
            and active runs.
@@ -170,7 +175,10 @@ usage:
            operational-continuation budget, not failed implementation attempts.
            Refuses when the newest attempt's work could not be committed and
            its worktree is the only copy: re-claiming removes that tree. Use
-           --force once you have recovered it or accepted the loss.
+           --force once you have recovered it or accepted the loss. Restores
+           the project queue label by default so the issue is actually
+           dispatchable; --no-requeue clears state labels only (the "about to
+           close it" case).
   verb     run one conductor_* verb as the orchestrator, from the CLI: the same
            checks and the same ledger rows a session's call would get. This is
            how an external orchestrator merges, labels, releases or reads PR
@@ -202,6 +210,7 @@ usage:
   daemon   run the dispatch loop in the foreground; --once runs a single tick
            and exits. This is what \`start\` launches.
   pause    stop claiming new work only (ticks keep firing if armed). Prefer hold.
+           --reason TEXT is recorded in the pause sentinel (\`status\` shows it).
   resume   clear pause only — does NOT re-arm. Prefer hold's inverse: resume + arm.
   graph-setup
            print how to set up the code-graph indexes workers query instead of
@@ -525,23 +534,62 @@ try {
     }
 
     case "restart": {
-      // Inherit the running daemon's port and project: a restart that quietly
-      // moved to the default port would leave every existing health check
-      // pointing at nothing. When the unit owns the live pid, restartDaemon
-      // goes through systemctl so the replacement stays supervised.
-      const { previous, record, via } = await restartDaemon({
-        port: portFlag(argv),
-        project: flag(argv, "project"),
-      });
-      if (previous !== undefined) {
+      if (argv.includes("--now")) {
+        // Inherit the running daemon's port and project: a restart that quietly
+        // moved to the default port would leave every existing health check
+        // pointing at nothing. When the unit owns the live pid, restartDaemon
+        // goes through systemctl so the replacement stays supervised.
+        const { previous, record, via } = await restartDaemon({
+          port: portFlag(argv),
+          project: flag(argv, "project"),
+        });
+        if (previous !== undefined) {
+          process.stdout.write(
+            `stopped — pid ${previous.pid}${via === "systemctl" ? " (via systemctl)" : ""}\n`,
+          );
+        }
+        process.stdout.write(
+          `started — pid ${record.pid}, /healthz on :${record.port}` +
+            `${record.project === undefined ? "" : `, project ${record.project}`}` +
+            `${via === "systemctl" ? " (via systemctl)" : ""}\nlog ${record.logFile}\n`,
+        );
+        break;
+      }
+
+      // Default: drain the fleet before restarting — pause new claims, wait for
+      // live workers to reach 0/N (bounded by --timeout), restart, then restore
+      // the prior dispatch state. A timed-out drain restarts nothing and leaves
+      // dispatch paused, so it is safe to run while the daemon is wedged.
+      const timeoutRaw = flag(argv, "timeout");
+      const timeoutSeconds =
+        timeoutRaw === undefined ? 1800 : Number.parseInt(timeoutRaw, 10);
+      const timeoutMs = (Number.isNaN(timeoutSeconds) ? 1800 : timeoutSeconds) * 1000;
+      let result!: RestartResult;
+      const deps: UpgradeDeps = {
+        ...DEFAULT_DEPS,
+        setPaused: (v) => setPaused(v, { source: "restart", reason: "restart, draining" }),
+        restartDaemon: async () => {
+          result = await restartDaemon({
+            port: portFlag(argv),
+            project: flag(argv, "project"),
+          });
+        },
+      };
+      try {
+        await drainAndRestart(deps, { project: flag(argv, "project"), timeoutMs });
+      } catch (err) {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+      }
+      if (result.previous !== undefined) {
         process.stdout.write(
-          `stopped — pid ${previous.pid}${via === "systemctl" ? " (via systemctl)" : ""}\n`,
+          `stopped — pid ${result.previous.pid}${result.via === "systemctl" ? " (via systemctl)" : ""}\n`,
         );
       }
       process.stdout.write(
-        `started — pid ${record.pid}, /healthz on :${record.port}` +
-          `${record.project === undefined ? "" : `, project ${record.project}`}` +
-          `${via === "systemctl" ? " (via systemctl)" : ""}\nlog ${record.logFile}\n`,
+        `started — pid ${result.record.pid}, /healthz on :${result.record.port}` +
+          `${result.record.project === undefined ? "" : `, project ${result.record.project}`}` +
+          `${result.via === "systemctl" ? " (via systemctl)" : ""}\nlog ${result.record.logFile}\n`,
       );
       break;
     }
@@ -732,6 +780,7 @@ try {
       try {
         const outcome = await unblockIssue(project, makeTracker(project), store, issue, {
           force: argv.includes("--force"),
+          requeue: !argv.includes("--no-requeue"),
         });
         process.stdout.write(`${formatUnblock(issue, outcome, project, resolveCaps(project, cfg.defaults))}\n`);
         // A refusal must not read as success to a script or a board keypress.
@@ -1006,7 +1055,7 @@ try {
     }
 
     case "pause":
-      setPaused(true);
+      setPaused(true, { source: "pause", reason: flag(argv, "reason") });
       process.stdout.write(
         "paused — no new work will be claimed\n" +
           "note: ticks keep firing if armed; use hold to silence both\n",

package/src/config.ts

@@ -208,6 +208,7 @@ export function resolveCaps(p: ProjectConfig, defaults: Caps): Caps {
   const o: Partial<Caps> = p.caps ?? {};
   return {
     maxConcurrentWorkers: o.maxConcurrentWorkers ?? defaults.maxConcurrentWorkers,
+    maxConcurrentWorkersPerRepo: o.maxConcurrentWorkersPerRepo ?? defaults.maxConcurrentWorkersPerRepo,
     dailySpendUsd: o.dailySpendUsd !== undefined ? o.dailySpendUsd : defaults.dailySpendUsd,
     planUsage: o.planUsage !== undefined ? o.planUsage : defaults.planUsage,
     workerMaxTurns: o.workerMaxTurns ?? defaults.workerMaxTurns,
@@ -408,6 +409,15 @@ function normalizeProject(
   if (nonEmptyString(rawQueueLabel)) queueLabel = rawQueueLabel;
   else problems.push(`${label}: queueLabel must be a non-empty string — it is the human sign-off gate`);
 
+  // Tolerant like the other optional fields: an integer >= 1 is a grooming
+  // trigger, and anything else degrades to absent (the tick default) rather
+  // than invalidating the whole project.
+  const rawGroomBelow = raw["groomBelow"];
+  const groomBelow =
+    typeof rawGroomBelow === "number" && Number.isInteger(rawGroomBelow) && rawGroomBelow >= 1
+      ? rawGroomBelow
+      : undefined;
+
   const routing = raw["routing"] as Raw | undefined;
   const rawPrefix = routing?.["labelPrefix"];
   const labelPrefix = typeof rawPrefix === "string" ? rawPrefix : DEFAULT_LABEL_PREFIX;
@@ -434,6 +444,7 @@ function normalizeProject(
     name,
     tracker: { kind: "github", repo: trackerRepo },
     queueLabel,
+    ...(groomBelow === undefined ? {} : { groomBelow }),
     stateLabels: {
       inProgress: pickString(stateLabels?.["inProgress"], DEFAULT_STATE_LABELS.inProgress),
       blocked: pickString(stateLabels?.["blocked"], DEFAULT_STATE_LABELS.blocked),

package/src/daemon.ts

@@ -34,10 +34,10 @@ import { createReportOutbox, formatOpenReports } from "./reports.ts";
 import { recordReleaseBlock } from "./release-policy.ts";
 import { branchName, route } from "./routing.ts";
 import type { Routed, UnroutableReason } from "./routing.ts";
-import { evaluateDecisionConditions, probeNpmVersion } from "./decisions.ts";
+import { evaluateDecisionConditions, probeNpmVersion, probeRateLimitReset } from "./decisions.ts";
 import { classifyRun, type ClassifyFacts } from "./failure-class.ts";
 import { dbPath, openStore } from "./store.ts";
-import { makeTracker } from "./tracker/github.ts";
+import { makeTracker, type RateLimitStatus } from "./tracker/github.ts";
 import { RELEASE_SHAPES } from "./types.ts";
 import type {
   AdmissionHoldReason,
@@ -323,11 +323,45 @@ export function pausedAt(): number | undefined {
   }
 }
 
-export function setPaused(v: boolean): void {
+/**
+ * Who paused the fleet and why, read from line 2 of the same sentinel
+ * {@link setPaused} writes — `undefined` when the fleet is not paused or the
+ * file has no (parseable) line 2. Provenance lives on its own line so line 1
+ * stays a pure ISO timestamp that {@link pausedAt} can `Date.parse`; the `armed
+ * <ISO> owner=<id>` marker `armTicks` writes is the same one-key-per-line
+ * precedent.
+ */
+export function pauseProvenance(): { source: string; reason?: string } | undefined {
+  const f = join(stateDir(), "paused");
+  if (!existsSync(f)) return undefined;
+  try {
+    const second = readFileSync(f, "utf8").split("\n")[1];
+    if (second === undefined) return undefined;
+    const match = /^source=(\S+)(?: reason="(.*)")?$/.exec(second.trim());
+    if (match === null) return undefined;
+    const source = match[1]!; // the regex guarantees group 1 on a match
+    const reason = match[2];
+    return { source, ...(reason === undefined ? {} : { reason }) };
+  } catch {
+    // Unreadable sentinel: no provenance to name, and the refuse-everything
+    // posture of an unknown pause is unchanged.
+    return undefined;
+  }
+}
+
+export function setPaused(v: boolean, why?: { source: string; reason?: string }): void {
   const f = join(stateDir(), "paused");
   if (v) {
     mkdirSync(dirname(f), { recursive: true });
-    writeFileSync(f, `${new Date().toISOString()}\n`);
+    const line1 = `${new Date().toISOString()}\n`;
+    if (why === undefined) {
+      writeFileSync(f, line1);
+    } else {
+      // Quotes are stripped before embedding so a reason cannot break out of
+      // the `reason="..."` field of line 2.
+      const reason = why.reason === undefined ? "" : ` reason="${why.reason.replaceAll('"', "")}"`;
+      writeFileSync(f, `${line1}source=${why.source}${reason}\n`);
+    }
   } else {
     rmSync(f, { force: true });
   }
@@ -1757,6 +1791,13 @@ export async function admitCandidates(
     if (list === undefined) activeByIssue.set(run.issue, [run]);
     else list.push(run);
   }
+  // Live worker count per repo, seeded from live runs and incremented as this
+  // same pass admits — so two same-repo candidates can never both clear the
+  // per-repo cap in one tick (#186).
+  const liveByRepo = new Map<string, number>();
+  for (const run of store.liveRuns(project.name)) {
+    liveByRepo.set(run.repo, (liveByRepo.get(run.repo) ?? 0) + 1);
+  }
   const holds: AdmissionHold[] = [];
   const hold = (issue: number, reason: AdmissionHoldReason): void => {
     holds.push({ issue, reason });
@@ -1828,6 +1869,16 @@ export async function admitCandidates(
       }
     }
 
+    // Per-repo concurrency: the mirror, branch-protection staleness and shared
+    // CI egress are all per-repo collision domains, so extra slots should land
+    // on other repos rather than stacking workers into the same one (#186).
+    const liveInRepo = liveByRepo.get(r.repo.name) ?? 0;
+    if (liveInRepo >= caps.maxConcurrentWorkersPerRepo) {
+      hold(issue, "repo-active");
+      log(`#${issue} skipped: ${liveInRepo} live worker(s) already in ${r.repo.name} (cap ${caps.maxConcurrentWorkersPerRepo})`);
+      continue;
+    }
+
     const priorRuns = store.attemptsFor(project.name, issue);
     const failures = store.failuresFor(project.name, issue);
     if (failures >= caps.maxAttemptsPerIssue) {
@@ -1976,6 +2027,7 @@ export async function admitCandidates(
     }
 
     admitted.push({ r, attempt: priorRuns + 1 });
+    liveByRepo.set(r.repo.name, (liveByRepo.get(r.repo.name) ?? 0) + 1);
     if (parent !== undefined) occupiedParents.set(parent, issue);
   }
 
@@ -2083,7 +2135,13 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
   for (const expired of d.store.expireDueDecisions(d.project.name, Date.now())) {
     log(`decision ${expired.id} expired unanswered after seven days: ${expired.question}`);
   }
-  void evaluateDecisionConditions(d.store, d.project.name, d.tracker, probeNpmVersion, Date.now)
+  void evaluateDecisionConditions(
+    d.store,
+    d.project.name,
+    d.tracker,
+    { npm: probeNpmVersion, rateLimit: probeRateLimitReset },
+    Date.now,
+  )
     .then((met) => {
       for (const decision of met) {
         log(`decision ${decision.id} condition met (${decision.condition ?? "?"}) — surfacing on the next tick`);
@@ -2122,7 +2180,7 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
       `ERROR: the installed conductor changed under this daemon — ${integrity.diff.length} file(s) differ ` +
         `(${shown.join(", ")}${integrity.diff.length > shown.length ? ", …" : ""}) — pausing`,
     );
-    setPaused(true);
+    setPaused(true, { source: "integrity", reason: "installed package changed under the daemon" });
     if (integrity.page) {
       const delivered = await safeEscalate(d, {
         tier: 2,
@@ -2197,7 +2255,7 @@ export async function tick(d: Deps, workers?: WorkerPool): Promise<void> {
   // operator opted out — turns and wall-clock still brake every run (#46).
   const spent = store.spendSince(project.name, since);
   if (caps.dailySpendUsd !== null && spent >= caps.dailySpendUsd) {
-    setPaused(true);
+    setPaused(true, { source: "spend-cap", reason: `daily spend reached $${caps.dailySpendUsd}` });
     await safeEscalate(d, {
       tier: 2,
       project: project.name,
@@ -2403,6 +2461,13 @@ export interface StatusSnapshot {
    * than print a percentage nobody measured (#110).
    */
   planUsage?: PlanUsageStatus;
+  /**
+   * The GitHub API rate-limit budget, when the caller read one. Optional for
+   * the same reason as `planUsage` — the read is I/O and the snapshot is
+   * synchronous — and a broken `gh` must cost one status row, not the report
+   * (#188).
+   */
+  github?: RateLimitStatus;
 }
 
 /** Builds a status reading from an already-open store. Long-lived operator
@@ -2629,7 +2694,7 @@ export async function previewQueue(project?: string): Promise<QueuePreview> {
  */
 export function prepareConductor(): void {
   openStore(dbPath()).close();
-  setPaused(true);
+  setPaused(true, { source: "setup" });
 }
 
 /** Bounded per tick: each row costs tracker calls to gather facts for. */