omp-conductor 0.9.1 → 0.12.0

package/README.md

@@ -538,7 +538,8 @@ add waits with it.
 
 `omp-conductor board [--project NAME]` opens the same facts as a live terminal
 kanban instead of a scrolling wall of status text. Its columns are Queue,
-Claimed, Running, Green, Blocked, Failed, Orphaned, Merged, and History.
+Claimed, Running, Green, Blocked, Failed, Orphaned, Merged, Settled, and
+Parked.
 
 Every column is a claim about an issue's state **now**, and each issue appears
 in exactly one of them. Claimed, Running, and Green come from the store, because
@@ -549,10 +550,17 @@ label, Blocked is the blocked state label, and Orphaned is an issue the
 in-progress label still claims with no worker running it — a protected orphan
 whose worktree is kept because it may hold uncommitted work. So a requeued issue
 is queue work even when its last attempt failed, and a closed issue is not
-active work at all. Merged and History are the two backward-looking columns,
-both bounded to the last 24 hours and neither one an action list: History holds
+active work at all. Merged and Settled are the two backward-looking columns,
+both bounded to the last 24 hours and neither one an action list: Settled holds
 recently finished runs that no current label claims, so the board stays
-operational rather than becoming an analytics archive.
+operational rather than becoming an analytics archive. Parked is the issue's
+last word when the tracker has **not** confirmed it closed — a terminal run
+whose issue wears no state or queue label (still open, or a label read that
+failed), so nothing dispatches it until a human labels it. Unlike Merged and
+Settled it is not bounded to 24 hours, because parked work does not stop being
+the issue's only remaining record; Settled alone asserts the issue is closed,
+so an unreadable probe parks rather than letting a run masquerade as finished
+work.
 
 The board refreshes run, spend, turn, and dispatch values from SQLite every
 second. It refreshes the slower daemon, Herdr, Telegram, code-graph, and tracker
@@ -1004,6 +1012,13 @@ effective value is persisted and shown beside that active run in `status`; editi
 flight. A cap that fires aborts the run, records it as `killed`, and names the
 ceiling in the escalation.
 
+Pause one live worker cooperatively with
+`omp-conductor worker pause <issue> [--project NAME]`. The daemon aborts the
+active turn to an idle harness state, freezes the remaining wall-clock budget,
+and keeps the run in the Running lane. `omp-conductor worker resume <issue>`
+continues the same session with a prompt to re-check its last action before
+proceeding. This is separate from fleet-level `pause`, which stops new claims.
+
 ### Plan allowance (`planUsage`)
 
 `dailySpendUsd` meters money, which is the only thing an API-billed account can
@@ -1458,6 +1473,7 @@ persists the class on the row, and performs the one recovery that class names.
 | `admin-kill` | killed *below* its own ceiling — a restart or a drain | requeue | none |
 | `ci-infra` | PR open, every unresolved check cancelled / timed out / stale | re-run the failed jobs | none |
 | `ci-deterministic` | PR open, a check genuinely reports `FAILURE` | escalate with the failing check names and links | failed attempt |
+| `provider-credit` | the provider refused the run for credit (HTTP 402, or its own out-of-credit text read off the transcript) | pause the fleet and require `omp-conductor resume` once the provider has credit | none |
 | `unknown` | anything unrecognised | escalate | as recorded |
 
 **Unknown escalates; it never silently retries.** A shape this table does not
@@ -1466,11 +1482,14 @@ cause nobody has named — the behaviour this exists to end.
 
 ### The budgets follow the cause
 
-`failuresFor` (implementation attempts) excludes `ci-infra`, `settlement-stuck`
-and `env-start-failure`; `continuationsFor` excludes `admin-kill`,
-`settlement-stuck` and `env-start-failure`. An environment fault charges neither:
-the session never started, so nothing about the issue was attempted. A merge conflict *is* charged as a continuation, because a
-rebase is real work — just never as a failed implementation attempt.
+`failuresFor` (implementation attempts) excludes `ci-infra`, `settlement-stuck`,
+`env-start-failure` and `provider-credit`; `continuationsFor` excludes
+`admin-kill`, `settlement-stuck`, `env-start-failure` and `provider-credit`. An
+environment fault charges neither: the session never started, so nothing about
+the issue was attempted, and nor does a provider-credit refusal, which is a
+billing state rather than an implementation failure. A merge conflict *is*
+charged as a continuation, because a rebase is real work — just never as a
+failed implementation attempt.
 
 An **unclassified** row (every row written before 0.4.3) counts exactly as it
 did before classification existed. Upgrading therefore changes no existing
@@ -1575,7 +1594,8 @@ A complete, valid config for one project with two target repos:
               { "cmd": "bun run lint", "cwd": "." },
               { "cmd": "bun test", "cwd": "." }
             ],
-            "graphProject": "~/.cache/conductor-graph/acme/api"
+            "graphProject": "~/.cache/conductor-graph/acme/api",
+            "migrations": { "dir": "backend/alembic/versions" }
           },
           "worker": {
             "name": "worker",
@@ -1647,12 +1667,13 @@ Field notes:
 | `routing.repos` | At least one entry, or nothing can be routed. `name` defaults to the map key, `defaultBranch` to `main`. |
 | `gates` | The exact cheap commands CI also runs, each with the `cwd` it runs from (`cwd` defaults to `.`). Running the real gate locally is what makes an unattended push safe — a subset lets an error outside the source dir reach the runners. |
 | `graphProject` | Optional, per repo. Absolute path of the **index-only clone** whose code graph this repo's workers query — conductor's own disposable clone, pinned to the repo's default branch, never a checkout you work in and never a worker's worktree. Written by the wizard; `~` is expanded, and a relative path is an error rather than something resolved against whichever cwd happened to read the file. Absent means this repo has no graph and its briefs say nothing about one. See [Code-graph discovery](#code-graph-discovery). |
+| `migrations` | Optional, per repo: `{ "dir": "backend/alembic/versions" }`. Names the repo-relative directory of an Alembic-style ordered migration chain (`revision` / `down_revision` in `*.py`). When set, `conductor_pr_merge` **refuses** a merge that would corrupt the chain at the base tip: reusing a revision id another file already declares, deleting a published migration, or a merge that would leave the combined graph with more than one head (so a stale parent is refused, and a fork-repair merge migration that unifies the heads passes). Absent means the repo opts out of the chain check entirely. Repo-relative only: a leading `/` or `..` is an error. |
 | `caps` | Per-project overrides; omit it or pin only the fields you want to change. |
 | `escalation.fallbackToIssueComment` | Defaults to `true`. Absent means "yes, still tell me". |
 | `escalation.orchestrator` | Optional; `"embedded"` (default) or `"external"`. `external` means an orchestrator session already runs elsewhere: the daemon starts none, and tier-1 escalations post as issue comments for that session to drain. Any other value is an error. |
 | `authority` | Optional; `{ "merge": …, "release": … }`, each `"human"` (default) or `"orchestrator"`. It grants nothing to the daemon — it words the orchestrator's standing orders and the Releases paragraph of the rendered brief, so the config and the prompt cannot disagree about who holds the merge button. Unknown keys and any other value are errors, never folded to the default. |
 | `releasePolicy` | Optional; `"none"` (default) or `"operator-brief"`. `none` installs a pre-tool-call tripwire in worker, embedded-orchestrator and external-orchestrator sessions. It blocks `git tag`, tag pushes, package publishing, GitHub release creation and recognised deploy commands before execution. `operator-brief` opens that gate only for the procedure in the operator-owned brief. Unknown values are errors. Every rejection is written to `release-policy-blocks.jsonl`; the heartbeat carries that day's count into the daily digest so configured intent and observed behaviour cannot drift silently. This is the mechanical gate; `authority.release` still says who owns the decision. |
-| `reporting.scope` | Optional; `"material"` (default), `"decisions"` or `"escalations"`. Every orchestrator tick appends the matching constraint line to its prompt, re-read from this file each tick — see [Your workflow vs. the package](#your-workflow-vs-the-package). It constrains what the session is told to report; it is not an outbound filter. A config written without the key keeps reporting material events — a release never turns an existing fleet's volume down on its own. Any other value is an error, never folded to the default. |
+| `reporting` | Optional; a **legacy scope preset** (`reporting.scope` — `"material"` default, `"decisions"`, `"escalations"`) or the **explicit form** `{ "interruptOn": [...], "digest": { ... } }`. The preset writes which categories may page the operator (`interruptOn`) and when the rollup happens (`digest.cadence`); the explicit form sets both directly and the two forms are mutually exclusive in one config. See [Reporting policy](#reporting-policy-reporting). |
 | `orchestratorReadPaths` | **Retired in 0.4.3.** Still accepted in a config and ignored, so a fleet carrying it upgrades without an edit. It widened the orchestrator's file-tool allowlist; there is no allowlist any more — the orchestrator is [unconfined by design](#the-orchestrator-is-unconfined-deliberately). |
 | `policy` | Optional; the gating conditions a merge or a release must satisfy, in two sections — `policy.merge` and `policy.release`. Any member may be omitted and the loader fills it from the strict default; an unknown key in either section, or a value outside its vocabulary, is an error naming the field, never a silent downgrade. See [Merge and release preconditions](#merge-and-release-preconditions-policy). |
 | `workspaceRoot` / `mirrorRoot` | Optional; default to `worktrees/` and `mirrors/` under the state directory. `~` is expanded. |
@@ -1661,6 +1682,27 @@ Prefer an SSH `cloneUrl`, or an https URL backed by a credential helper. A clone
 with credentials embedded is persisted into the mirror's git config, exactly as it
 would be for a hand-run clone.
 
+### Reporting policy (`reporting`)
+
+What may interrupt the operator's phone, and when the daily rollup happens. Two
+spellings, mutually exclusive in one config (the loader rejects a `scope` next to
+`interruptOn`/`digest`):
+
+- **Preset** — `reporting.scope`, the three legacy values, mapped verbatim:
+  - `material` (default) → `interruptOn: [tier2, decision-needed, fleet-stopped, confirmed-failure, material]`, digest `per-tick`.
+  - `decisions` → `interruptOn: [tier2, decision-needed, fleet-stopped]`, digest `per-tick`.
+  - `escalations` → `interruptOn: [tier2, fleet-stopped]`, digest `daily` (model-timed).
+- **Explicit** — `reporting: { "interruptOn": ["tier2", "fleet-stopped", ...], "digest": { "cadence": "none" | "per-tick" | "daily" } }`.
+  `interruptOn` must be a non-empty array of known categories (`tier2`, `decision-needed`, `fleet-stopped`, `confirmed-failure`, `material`), each an escalation's tier-2 category. `daily` may add `at` (`HH:MM`, 24h) and `timezone` (a known IANA zone, defaulting to the host zone) — both only valid with `daily`.
+
+A tier-2 escalation whose category is **not** in `interruptOn` is not dropped: it
+is held (`held_notices`) and the next accepted digest is its delivery authority.
+The digest itself is at-most-once per local day (`digest:<YYYY-MM-DD>` in the
+configured zone), which remains the delivery authority across restarts. A
+scheduled `daily` digest is only sent on a day it has not already run, once the
+local clock has passed `at`; a restart after `at` still sends today's (one
+catch-up), and a fully missed day is skipped, never sent late.
+
 ### Merge and release preconditions (`policy`)
 
 These used to be sentences in your `POLICY.md`: when a PR may be merged, what
@@ -1947,6 +1989,8 @@ 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 worker pause <issue> [--project NAME]
+omp-conductor worker resume <issue> [--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]
@@ -1971,7 +2015,7 @@ omp-conductor help
 | `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, 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. |
+| `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, the last 24 hours of Merged and Settled, and Parked (an issue the tracker has not confirmed closed — still open, or a label read that failed — so nothing dispatches it until a human labels it). 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). |
 | `halt [--pane] [--project NAME]` | `hold`, then stop the dispatch daemon (systemctl-aware). Pane stays up unless `--pane` is passed. `halt --pane` also pins herdr-conductor recovery off for the conductor agent only — it does **not** stop `herdr-fleet.service` or any other herdr session. Fail-closed: exits nonzero unless the agent is proven gone. |
 | `arm [--project NAME]` | Proof-gated: send a Telegram challenge and write the arm marker only after your reply appears as a user turn in the orchestrator transcript. Never auto-armed by `resume` / `hold`. |
@@ -1979,6 +2023,7 @@ 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. |
+| `worker pause <issue>` / `worker resume <issue>` | Cooperatively park one live worker without changing its run state or lane. Pause aborts the active turn to harness idle and freezes the remaining wall-clock budget; resume continues the same session with a prompt to re-check its last action before repeating it. This is distinct from fleet-level `pause`, which stops new claims. |
 | `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. The label changes go through the [label projection outbox](#the-tick): they are applied inline before the command returns, but **a tracker that refuses them (403, rate limit) no longer fails the verb** — it exits `0`, the intended label state is durable and the daemon retries it, and the output says `label sync queued (N pending) — the daemon retries` instead of claiming the labels were restored. Safety is preserved, but the issue is only claimable once the queue label itself lands: the queue read asks GitHub for issues carrying that label, so a refused queue-label add keeps the issue out of dispatch until projection succeeds. `--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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.9.1",
+  "version": "0.12.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.",