omp-conductor 0.3.21 → 0.3.23

package/README.md

@@ -165,6 +165,16 @@ Also required on the host:
     writes `access.json`. The fleet heartbeat also reads that file and refuses to
     tick unless exactly one owner is paired, on the grounds that unattended
     dispatch is only defensible while a tier-2 page can reach a person.
+  - **Approving a Learning-loop amendment from a heartbeat tick** needs one more
+    setting than pairing: a notify destination. `/telegram notify` writes
+    `notifyMode` and `notifyChat` into the same `access.json`; `/telegram topics`
+    does it with a forum topic instead. omp-telegram mounts its `telegram_ask`
+    tool only for a turn that resolves a notify target, and a locally injected
+    tick resolves one only through that setting — so without it the orchestrator
+    can page you but cannot put a yes/no question in front of you, which is the
+    one thing the Learning loop's approval step requires. `omp-conductor status`
+    reports this on the `telegram` row, and a tick that finds the tool missing
+    says so in its own prompt and falls back to `telegram_send`.
 
   With neither, tier 2 degrades to a comment on the issue. Nothing is broken in
   that configuration: it is supported, just slower to reach you.
@@ -462,22 +472,34 @@ Four control planes used to answer "stop" differently. The package verbs:
 
 `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, and Merged. Queue cards are the
-bounded per-issue hold sample recorded by the latest dispatch; the Queue count
-is the authoritative ready count even when there are more ready issues than
-sampled cards. Run columns show the newest attempt for each issue. Merged keeps
-only the last 24 hours so the board stays operational rather than becoming an
-analytics archive.
+Claimed, Running, Green, Blocked, Failed, Orphaned, Merged, and History.
+
+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
+a live worker or an open pull request is the most current fact there is. Every
+stopped column comes from the labels the tracker carries right now: Queue is the
+queue label plus the latest tick's admission holds, Failed is the failed state
+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
+recently finished runs that no current label claims, so the board stays
+operational rather than becoming an analytics archive.
 
 The board refreshes run, spend, turn, and dispatch values from SQLite every
-second. It refreshes the slower daemon, Herdr, Telegram, and code-graph health
-layer every ten seconds or immediately with `r`. Use arrow keys or `h/j/k/l` to
-select a card, `Enter` to inspect and follow its worker transcript, `u` to run
-the normal unblock workflow, `i` / `p` to open the issue / pull request, `?` for
-help, and `q`, `Esc`, or `Ctrl-C` to go back and quit. Narrow terminals show a
-sliding subset of columns around the selection; terminals below 50×20 get a
-single resize instruction instead of a broken layout. The board is read-only
-except for the explicit `u` action: it never claims work or changes stages.
+second. It refreshes the slower daemon, Herdr, Telegram, code-graph, and tracker
+label layer every ten seconds or immediately with `r`; the header reports
+`tracker ok`, or how stale the label read is and why, so an empty Queue is never
+mistaken for an empty queue. Use arrow keys or `h/j/k/l` to select a card,
+`Enter` to inspect and follow its worker transcript, `u` to run the normal
+unblock workflow on a Blocked, Failed, or Orphaned card, `i` / `p` to open the
+issue / pull request, `?` for help, and `q`, `Esc`, or `Ctrl-C` to go back and
+quit. Narrow terminals show a sliding subset of columns around the selection;
+terminals below 50×20 get a single resize instruction instead of a broken
+layout. The board is read-only except for the explicit `u` action: it never
+claims work or changes stages.
 
 `halt --pane` is **fail-closed**: it exits `0` only when the conductor agent is
 *proven* gone. It writes the recovery pin first, so a failed stop still cannot be
@@ -518,7 +540,8 @@ Per tick, for the daemon's project:
    the independent head/check verification; green → `pushed-green`, red →
    `failed`, and still pending stays occupied. For every verified
    `pushed-green` run, ask what became of its PR. Merged → `merged`; closed
-   without merging → `failed`. Unknown answers leave the row unchanged. This
+   without merging → `failed`. Unknown answers leave the row unchanged. Every row
+   that settles also loses its `agent:in-progress` label. This
    maintenance runs even while dispatch is paused or workers are active, so
    status converges on the five-minute tick cadence. It also runs above admission
    so a row settled here frees its issue in the same tick. See
@@ -548,8 +571,12 @@ Per tick, for the daemon's project:
    survived step 8 — so at most one API call per free slot, never one per queued
    issue — the daemon asks whether an **open** PR already closes it. An open PR
    normally holds the issue. One narrow exception permits a routed continuation:
-   the PR URL must match the latest terminal run's retained PR exactly. Drafts
-   count because their branch can hold the only copy of the work.
+   the latest run must be terminal, and the open PR must be that run's retained
+   work — either the PR URL it recorded or a PR opened on the branch it retained.
+   The branch half matters because a run can be cap-killed before its worker ever
+   opens a PR, leaving a retained branch and no recorded URL; a PR pushed to that
+   branch afterwards is still the continuation target. Drafts count because their
+   branch can hold the only copy of the work.
    The tracker also finds work missing from a new, moved, restored, or cleared
    store. If the check fails, the candidate is **held**, not admitted, and
    retried next tick: the cost of holding is five minutes, the cost of admitting
@@ -583,13 +610,14 @@ Then, per admitted issue:
    | Outcome | Labels | Worktree | Escalation |
    | --- | --- | --- | --- |
    | `pushed-pending` | `agent:in-progress` stays while the daemon rechecks GitHub | removed | none |
-   | `pushed-green` | `agent:in-progress` stays until the merge closes the issue | removed | none |
+   | `pushed-green` | `agent:in-progress` stays while the PR is open | removed | none |
    | `blocked` | swapped to `agent:blocked` | removed | Tier 1 |
    | `failed` / `killed` | swapped to `agent:failed` | dirty tree committed to the branch, then retained until the PR or issue is terminal | Tier 1 |
    | unexpected error | swapped to `agent:failed` | same | Tier 1 |
 
    `pushed-pending` and `pushed-green` are not the end of the row: later ticks
-   verify outstanding checks and settle the PR once it resolves. See
+   verify outstanding checks and settle the PR once it resolves, and a row that
+   settles gives up its `agent:in-progress` label. See
    [what settles a green PR](#what-settles-a-green-pr).
 
    Label swaps add the new label before removing the old one: the reverse order
@@ -683,11 +711,15 @@ every pushed PR it is still holding:
 | could not be determined | unchanged | A flaky network, a revoked token, a deleted PR. An unknown answer never settles a row; the next tick asks again for free. |
 
 Run history is untouched. A PR closed without merging becomes a concrete failed
-attempt; a merge does not spend failure or continuation budget. A merge normally
-closes the issue, and a human who closed a PR is already looking at it, so what
-an issue's labels should say next remains the orchestrator's drain-duty
-judgement. One unreachable PR costs its own row and nothing else; the rest of
-the sweep still settles.
+attempt; a merge does not spend failure or continuation budget. A settled row also
+loses `agent:in-progress` from its issue: the row transition and the label are one
+fact, and a terminal answer about the PR proves no worker process owns the issue,
+so the duplicate-dispatch guard it exists for is spent. Rows that did not settle
+keep the label, and a tracker that refuses the removal is logged rather than
+allowed to abort the sweep — `omp-conductor unblock` clears it by hand in that
+rare case. Anything beyond that one release — a re-queue, a `blocked` marker —
+is still the orchestrator's drain-duty judgement. One unreachable PR costs its own
+row and nothing else; the rest of the sweep still settles.
 
 Until this existed, nothing ever revisited a `pushed-green` row: the startup
 reconciler only settles rows that held a process, and `merged` went unwritten. On
@@ -696,6 +728,12 @@ merged and whose issues were all closed, through two daemon restarts — and bec
 the active set *is* the busy set, those three issues were permanently unclaimable.
 A status page that has stopped being evidence is worse than no status page.
 
+The label half of that outlived the row half by two days. On 2026-08-09 a merged
+PR and a closed-unmerged one both settled their rows correctly and both left their
+issues carrying `agent:in-progress`, which eligibility reads as "a worker owns
+this" — with the brief forbidding the orchestrator from editing a state label and
+`unblock` declining to clear that one, neither issue could ever be claimed again.
+
 ### Continuation runs
 
 When a worktree is provisioned onto a branch that already exists in the mirror
@@ -960,7 +998,9 @@ label on the issue, and eligibility reads any state label as disqualifying, so a
 answered issue that keeps one is never re-claimed and the answer is inert — nothing
 fails, the issue just stops existing as far as dispatch is concerned.
 [`omp-conductor unblock <issue>`](#cli-reference) is the way back: it clears the
-label through the same tracker the dispatcher writes with. The brief tells the
+label through the same tracker the dispatcher writes with, including
+`agent:in-progress` when the newest recorded run is terminal, since a terminal row
+is proof the worker process is gone. The brief tells the
 orchestrator to run that verb rather than edit the label itself, and that is not a
 formality — orphan detection works by comparing `agent:in-progress` labels against
 live runs, and it is only trustworthy while every state label on the tracker was
@@ -1350,7 +1390,7 @@ omp-conductor help
 | `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). |
 | `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` / optional `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. The daemon block includes `rss` from `/healthz`; live workers add a busy-deploy warning. A `.conductor-stalled` marker adds an `orchestrator STALLED since …` line. |
-| `board [--project NAME]` | Live keyboard-driven kanban over the same SQLite and `/healthz` truth as `status`: Queue, Claimed, Running, Green, Blocked, Failed, and the last 24 hours of Merged. Refreshes run/spend/turn values every second and slower health every ten seconds. `Enter` follows the selected transcript in place; `u` invokes the existing unblock workflow; `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, 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). |
 | `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`. |
@@ -1358,7 +1398,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. |
-| `unblock <issue>` | Remove that issue's `blocked` and `failed` labels so an answered escalation can be claimed again. `agent:in-progress` is never touched. 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. Exits `2` when the issue number is missing or malformed. |
+| `unblock <issue>` | 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. Exits `2` when the issue number is missing or malformed. |
 | `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. |
 | `daemon` | 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` | 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. |

package/package.json

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