omp-conductor 0.19.6 → 0.20.0

package/REFERENCE.md

@@ -848,6 +848,22 @@ the queue label is refused with `file-lane-unparseable` and an actionable
 message, because promoting beside overlapping work on a section that plainly
 tried to declare is the exact gap the interlock exists to close.
 
+Since #1036, a promotion also checks a contract. When the issue carries a
+durable `promotable` grooming verdict (the store's grooming row, written by
+the to-spec batch), adding the queue label first recovers that verdict's strict
+payload and requires its `PROMOTABLE` result, then compares the lane admission
+would enforce against the verdict's `fileLane` as deduplicated,
+order-independent path sets — exact in both directions, so a missing path
+refuses exactly like an extra one, and an order-only difference promotes. Any
+disagreement refuses with `promotion-brief-mismatch`, naming both sets; so
+does evidence behind a `promotable` row that does not recover as a strict
+PROMOTABLE result, and an issue unreadable at promotion time behind such a
+row. The durable verdict is what made the issue dispatchable, so the gate
+fails closed before any tracker mutation or daemon wake — but it never edits
+the issue itself: the remediation is applying the verdict's `proposedBrief`
+to the issue (its `## Exact write lane` included), then adding the label
+again. An issue without a `promotable` row promotes exactly as before.
+
 #### What status shows
 
 `status` renders the two lifecycle kinds as two blocks, because "a branch is
@@ -2795,7 +2811,9 @@ omp-conductor drain status [--project NAME]
 omp-conductor drain cancel [--project NAME]
 omp-conductor stop [--pane] [--project NAME]
 omp-conductor arm [--project NAME]
+omp-conductor arm --reply TEXT [--project NAME]
 omp-conductor disarm [--project NAME]
+omp-conductor console [--project NAME]
 omp-conductor tail <issue> [--project NAME]
 omp-conductor extend <issue> --turns N [--project NAME]
 omp-conductor worker pause <issue> [--project NAME]
@@ -2813,6 +2831,9 @@ omp-conductor decision withdraw <id> [--reason TEXT] [--project NAME]
 omp-conductor decision list [--project NAME] [--json]
 omp-conductor watch add --note TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
 omp-conductor watch list [--project NAME] [--json]
+omp-conductor epic approve <issue> [--project NAME]
+omp-conductor epic revoke <issue> [--project NAME]
+omp-conductor epic list [--project NAME] [--json]
 omp-conductor daemon [--once] [--port N] [--project NAME]
 omp-conductor resume [--project NAME]
 omp-conductor brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]
@@ -2836,8 +2857,9 @@ omp-conductor help
 | `hold [--keep-ticks] [--project NAME]` | fleet | Soft stop: pause claiming **and** disarm ticks. Daemon and pane stay up. Prefer this when the intent is "stop the conductor" without killing processes. `--keep-ticks` pauses claiming but leaves the arm marker, so the heartbeat keeps reporting and `resume` alone restores the fleet — no fresh arm challenge. See [Stop the conductor](README.md#stop-the-conductor-hold--stop). |
 | `drain start --until ISO\|DURATION [--reason TEXT]` / `drain status` / `drain cancel` | project | Start, inspect, or cancel the project's self-expiring admission fence (#484): a durable, bounded alternative to queue-label churn before a release. `start` writes the project's drain record through the landed `createDrain` — new claims pause while active runs settle, and admission resumes automatically at the absolute deadline even if the orchestrator dies. A successful mediated `conductor_release` also clears the drain once the terminal release act completes — version-bump preparation stays latched until the tag is actually cut — so the release window ends with the release itself rather than latching until the deadline (#791). `--until` takes an ISO instant or a relative duration (`90s`, `45m`, `2h`, `1d`) that must be bounded and in the future; a missing, unparseable, unbounded, or past expiry exits `2` before any state changes. `--reason` (1–500 characters) is persisted on the record. `status` reports inactive, or the active drain's creation time, absolute expiry, reason, and remaining active runs from the structured status snapshot. `cancel` removes only the named project's drain and is idempotent. The drain never touches the pause sentinel, the arm marker, or any queue label — it is a file record, not a hold. |
 | `stop [--pane] [--project NAME]` | fleet | Stop the conductor: pause claiming, disarm ticks, then stop the dispatch daemon (systemctl-aware). Pane stays up unless `--pane` is passed. `stop --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. To bounce the daemon without stopping the fleet, use `restart`. |
-| `arm [--project NAME]` | fleet | Proof-gated: send a Telegram challenge and write this project's arm marker only after the orchestrator's inbound adapter has acknowledged your reply in conductor's own state — no transcript is read, so where (or whether) a session file lives does not matter (#614). The challenge names the project, so a host running two fleets is not ambiguous. Never auto-armed by `resume` / `hold`. |
+| `arm [--project NAME]` / `arm --reply TEXT [--project NAME]` | fleet | Two mechanical halves, because nothing waits inside a session any more: the operator's reply lands in the console, which runs no tick extension, so the in-session acknowledgement this replaces could never be satisfied. `arm` files a challenge, sends it to the owner, and returns immediately — **nothing is armed yet** — printing the challenge id, how long it stays valid, the markers a reply will write, and the exact follow-up command. `arm --reply "<the operator's message, verbatim>"` verifies that message against the recorded challenge, writes the arm marker for exactly the projects that challenge named, and settles the challenge so the same code can never arm anything twice. Still proof-gated on conductor's own state — no transcript is read, so where (or whether) a session file lives does not matter (#614). A bare or empty `--reply` is refused rather than silently sending a second challenge in place of a verification. One ceremony covers the whole fleet (#991), and the challenge names its projects, so a host running two fleets is not ambiguous; `--project X` is still one project, one challenge, one marker. When the plumbing verdict is `claim-only` no challenge is sent and `arm` arms directly, naming that proof instead. Never auto-armed by `resume` / `hold`. |
 | `disarm [--project NAME]` | fleet | Remove this project's arm marker so its ticks skip; another project's ticks keep running. Also clears a pre-per-project shared `armed` marker while that marker is still what holds this fleet's gate open — otherwise the disarm would not disarm. Processes untouched. |
+| `console [--project NAME]` | project | Provision the operator console's workspace and print how to launch it: a dedicated cwd at `<state dir>/console/<project>`, this project's rendered console brief as `CONSOLE.md`, and an `AGENTS.md` symlink beside it so a session started there loads that brief. Idempotent — an already-current brief and a correct link are reported and left alone, and a *regular* `AGENTS.md` an operator wrote is never overwritten. It launches nothing: the printed pane command (`cd <cwd> && OMP_TELEGRAM_DM_OWNER=1 omp`, without the env prefix on a host configuring more than one project, which names the others and why) is what `herdr/bin/recover.sh` restores with the fleet, and what you run by hand otherwise. The console cwd deliberately holds no `.conductor-tick.json`, so the heartbeat extension cannot activate in it. |
 | `tail <issue>` | project | 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]` | project | Raise a live worker's effective turn ceiling through its owning daemon without restarting its session. If the latest run is failed, killed, orphaned, or blocked and has no live controller, store a one-shot ceiling for that issue's next claimed attempt instead. A next-attempt value must exceed the project base, every extension must stay at or below `workerMaxTurnsCeiling`, and live extensions remain monotonic. The pending value appears in `status`, is recorded in `ledger`, and is consumed atomically by one claim. |
 | `worker pause <issue>` / `worker resume <issue>` | project | 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 separate from fleet-level `hold`, which refuses new claims and work-starting mutations while allowing pre-pause completion work and releases. |
@@ -2853,6 +2875,9 @@ omp-conductor help
 | `decision list [--json]` | project | Open questions, oldest first: id, age, what each blocks, whether its condition is met, and the question. `--json` emits `{ project, decisions }`; the empty state is an empty array. Prints `no open decisions` in text mode when there are none. Watches are not listed here — `watch list` shows those. |
 | `watch add --note TEXT [--blocks TEXT] [--resolves-when COND]` | project | Record a condition or carry note the orchestrator set for itself, with no human in the loop (#459). `--resolves-when` attaches a machine-checkable condition the daemon checks for you; a met watch wakes the next tick exactly as a met question does. Renders under its own "Watches" heading, is never counted in `decisions N open`, and never expires while it is *waiting* — once a condition fires, the ordinary seven-day window runs from that instant (#966). |
 | `watch list [--json]` | project | Open watches, oldest first: id, age, what each blocks, whether its condition is met, and the note. `--json` emits `{ project, watches }`; the empty state is an empty array. Prints `no watches` in text mode when there are none. |
+| `epic approve <issue>` | project | Record standing consent to an epic's scope (#1041): brief-complete children of it pass the promotion ready gate and are queued without a fresh operator decision. Its own durable fact, not a resolved decision row — an approval never expires, and the gate reads a boolean instead of parsing an answer somebody wrote in prose. Idempotent and first-write-wins: re-approving keeps the original timestamp and prints that nothing changed, so a second approve is never mistaken for one that failed to stick. Whether the number really names an epic is not checked here — parents and children are native GitHub sub-issues, which the daemon resolves at promotion time. |
+| `epic revoke <issue>` | project | Withdraw an epic's approval, so its children need a decision again. A no-op on an epic that was never approved, and it exits `0`: `revoke` states what is true afterwards, exactly as `drain cancel` does. |
+| `epic list [--json]` | project | Approved epics, issue-ascending: issue, when it was approved, and who approved it. `--json` emits `{ project, epics }`; the empty state is an empty array. Prints `no approved epics` in text mode when there are none. |
 | `daemon` | host | Run the loop in the **foreground**, ticking every 5 minutes and serving `/healthz`. Admitted workers run in a tracked background pool, so settlement and capacity checks remain periodic while they work; shutdown drains the pool before closing the store. This is what `start` launches and what a systemd unit should call. |
 | `daemon --once` | host | 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. |
@@ -3099,7 +3124,7 @@ daemon, across a process boundary, not in a prompt the model can rewrite.
 | `conductor_pr_status` | worker or orchestrator | Read-only — nothing to gate. A worker reads only its own run's PR; an orchestrator may name any syntactically valid PR URL, open, merged, or closed, and gets its live state and head (checks are reported when available; a merged or closed PR reports its state instead of an `expected OPEN` refusal). |
 | `conductor_pr_update_branch` | orchestrator, or the worker owning the run | The PR belongs to this project and is open. A worker may only name its own run's PR. |
 | `conductor_pr_merge` | **orchestrator only** | Ordinarily, `authority.merge` equals the caller. A hand-edited `recoveryMerges` entry may instead authorize one exact unrecorded PR/head/reason while held. In both paths, while the project has an [active release composition](#the-active-release-composition-850), the PR must be named in it or carry an explicit operator override; then `headSha` equals the live head *at execution time*; checks are green at that same SHA; no [review evidence](#the-exact-head-review-gate-888) stands at that head without a recorded `conductor_pr_review_clear`; the project route and migration chain are valid; the project's single merge slot is free. |
-| `conductor_label` | **orchestrator only** | The label is in the project's own vocabulary. Lifecycle labels stay the daemon's. Adding the queue label echoes the parsed [file lane](#the-file-lane-declaration), or refuses with `file-lane-unparseable` when a clearly delimited write-lane section parsed nothing — it never claims fail-open beside a declaration that was actually attempted. |
+| `conductor_label` | **orchestrator only** | The label is in the project's own vocabulary. Lifecycle labels stay the daemon's. Adding the queue label echoes the parsed [file lane](#the-file-lane-declaration), or refuses with `file-lane-unparseable` when a clearly delimited write-lane section parsed nothing — it never claims fail-open beside a declaration that was actually attempted. When the issue carries a durable `promotable` grooming verdict, adding the queue label also verifies the current brief against that verdict before any mutation: a brief that disagrees with the verdict's `fileLane` (or evidence that no longer recovers as a strict PROMOTABLE result) refuses with `promotion-brief-mismatch` — apply the verdict's `proposedBrief`, then re-add ([the file-lane declaration](#the-file-lane-declaration)). |
 | `conductor_release` | **orchestrator only** | `authority.release` equals the caller; the per-shape grant permits it; the artefact or environment was declared; the release preconditions hold; the `reason` is in the closed enum. `version-bump-pr` creates or re-validates one deterministic version-only PR and, on a later call, merges only its exact green head through the project's single merge slot. |
 | `conductor_install` | **orchestrator only** | Gated like a release act: the `install` shape defaults to `human` and a grant is what moves it. The daemon refuses a version npm does not expose with a full `gitHead`, refuses while another install is still in flight, and otherwise starts a detached transient unit that pauses, drains, installs the CLI/omp plugin/Herdr plugin and reloads — outside this session and the daemon. The unit never declares its own success; the first tick after the restart verifies and reports through the durable outbox. |
 

package/agents/to-spec.md

@@ -29,15 +29,70 @@ Exactly one of these five strings, nothing else:
 - `ALREADY DONE` — the work already exists in the source (a later epic retired
   the issue's premise counts as done; prove it with the symbol/file, never the
   title).
-- `PROMOTABLE` — well-specified, fits one worker budget, and the acceptance
-  criteria are checkable; carries the proposed brief.
-- `NEEDS DECOMPOSITION` — the plan is real but too big for one budget; say what
-  slices it splits into and why each is a separate slice.
+- `PROMOTABLE` — well-specified, the acceptance criteria are checkable, and it
+  fits one worker budget *with the sizing evidence below to prove it*; carries
+  the proposed brief.
+- `NEEDS DECOMPOSITION` — the plan is real but does not fit one budget; carries
+  the ordered children it splits into and why each is its own slice.
 - `BLOCKED` — a named open prerequisite, lane, or credential gap stands in the
   way.
 - `NEEDS PRODUCT DECISION` — the issue cannot proceed until a human decides
   product shape, slice order, or scope; state the one question that unblocks it.
 
+## Sizing: the one-budget claim needs a falsifier
+
+`PROMOTABLE` asserts that one worker finishes this slice inside one attempt —
+a single session under the fleet's configured turn ceiling and its 90-minute
+wall clock, with continuations held in reserve for operational restarts and
+not for the rest of the work. That assertion is worth nothing on its own.
+Issue #1035 was groomed `PROMOTABLE` with nine acceptance criteria across four
+files; attempt 1 died at 181 of its 180 turns with the feature half-built. The
+verdict had claimed one-budget fit. What it never carried was evidence that
+could have falsified the claim.
+
+`sizingEvidence` is that evidence, read out of the source you just read:
+
+1. **The distinct behaviours.** Name each behaviour or state transition the
+   slice introduces — not each acceptance-criterion bullet. Two bullets about
+   one transition are one behaviour; one bullet hiding "create it, reconcile
+   it, clean it up" is three.
+2. **What each behaviour costs.** For every behaviour, the production module
+   that implements it and the focused test surface that proves it. A behaviour
+   whose proof needs a new integration harness costs far more than one an
+   existing unit test already reaches.
+3. **The sequencing between them.** Which behaviours write the same file, and
+   so cannot be discovered, implemented and re-proved independently inside one
+   session.
+4. **The conclusion.** Why that inventory fits one attempt — or, when it does
+   not, `NEEDS DECOMPOSITION`.
+
+**The multi-lifecycle shape is the one to refuse.** A candidate bundling core
+topology (creating the thing), lifecycle reconciliation (duplicate, live, dead
+and orphaned states converging) and daemon/restart integration (the same
+behaviour surviving a process restart) is three independently provable slices.
+That candidate is `NEEDS DECOMPOSITION` unless your verdict names the existing
+deep seam that already makes them one bounded change — a single reconciler
+both paths funnel through, say — by file and symbol. "They are related" is not
+a seam.
+
+**A small file count is not a small slice.** Four files can be 28,812 lines
+(that was #1035's own inventory) when they are high-fanout lifecycle modules
+with large integration suites. Weigh the fanout of what you touch and the size
+of the suites you must keep green, never the length of the write lane.
+
+No threshold decides this — not a line count, not a criterion count, not a
+file count. A threshold would be gamed by rewriting prose, and the sizes that
+matter are structural. The judgement is yours; the evidence is what makes it
+reviewable.
+
+**When it does not fit**, `decomposition` is a filing instruction and not a
+regret: the children in the order they must land, each with the title it would
+be filed under, the exact write lane it owns, what it waits on, the silent
+fake it invites and the commands that prove it. Two children writing the same
+core file must be serialised — the later one names the earlier in its
+dependencies — because two workers in one module is the collision the file
+lane exists to prevent.
+
 ## The return contract
 
 Answer in **one fenced JSON block, nothing else after it**. Every field is
@@ -46,10 +101,12 @@ required and no extra keys are accepted:
 - `verdict` — one of the five strings above.
 - `routing` — exactly one `owner/repo`, or `"MULTI"`.
 - `routingSplit` — required iff `routing` is `"MULTI"`: what each slice goes to.
-- `source` — `{ name, ref, freshAt }`: the authoritative source you read, the
-  exact ref, and `freshAt` = epoch milliseconds when you actually observed it.
-  Conductor refuses results whose source is older than 24 hours or missing
-  name/ref/freshAt — an unsourced verdict is not grooming, it is prose.
+- `source` — `{ name, ref }`: the authoritative source you read and the exact
+  ref you read it at. Conductor refuses a result that does not name both — an
+  unsourced verdict is not grooming, it is prose. Do not send a `freshAt`:
+  conductor stamps the observation time itself from the batch window and
+  refuses a batch whose window exceeds 24 hours, so inventing a timestamp is
+  neither required nor read (#1000).
 - `evidence` — the files/symbols that prove the verdict. Required for
   `ALREADY DONE`: name the symbol/file that already does the work, never a
   title match. Welcome on every other verdict.
@@ -69,6 +126,16 @@ required and no extra keys are accepted:
 - `fileLane` — the files and directories this slice writes.
 - `dependencies` — open prerequisite issue numbers, each a bare number
   (`875`) or a string (`"875"`); `[]` when none.
+- `sizingEvidence` — required iff `verdict` is `PROMOTABLE`: the one-budget
+  analysis from the sizing section above — the distinct behaviours, the
+  production module and focused test surface each one needs, the shared-file
+  sequencing between them, and why that fits one attempt.
+- `decomposition` — required iff `verdict` is `NEEDS DECOMPOSITION`, and
+  accepted on no other verdict: the ordered children, first to last. Each is
+  an object with `title`, `writeLane` (its exact write lane), `dependsOn` (an
+  earlier child's title or an existing issue number, `[]` for the first),
+  `likelySilentFake` and `proofCommands`. Children sharing a write-lane path
+  must serialise through `dependsOn`.
 - `proposedBrief` — required iff `verdict` is `PROMOTABLE`: the brief a worker
   would be dispatched with, including the silent fake and the proof commands.
 - `reasonNotToPromote` — required for every other verdict: why this must not
@@ -78,7 +145,7 @@ required and no extra keys are accepted:
 
 - **Prose is not evidence.** A verdict without the source-backed contract is
   refused as malformed: every field above is required, and `source` must name
-  the ref you read and when.
+  the ref you actually read.
 - **Stale source reads like good source.** Judge the candidate against the
   stated ref as it is now; a verdict drawn from memory of a different clone is
   stale and will be refused.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.19.6",
+  "version": "0.20.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/schema/config.schema.json

@@ -184,6 +184,10 @@
               }
             ]
           },
+          "groomRole": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+          },
           "stateLabels": {
             "type": "object",
             "properties": {