omp-conductor 0.18.2 → 0.19.1

package/README.md

@@ -271,39 +271,39 @@ The Herdr half owns recovery, not dispatch or policy: it restores the exact
 session identity, requests an immediate heartbeat, or reports through Telegram
 and a Herdr notification that the fleet is down.
 
-### The worker identity and its harness binding
-
-Worker sessions do not run as you. `setup host` creates a dedicated
-unprivileged account, `omp-worker` (home `/var/lib/omp-worker`), and the daemon
-launches every worker session under it through `setpriv`. The account is granted
-search access to the paths a session needs and read access to your agent config
-files; its writable world is the worktree and session directory dispatch hands
-it per run, and nothing else.
-
-That boundary means the account cannot list your home — which is also where
-`omp-conductor` and its `@oh-my-pi/pi-coding-agent` peer are installed, and
-module resolution needs to list a directory to find the `node_modules` inside
-it. Left there, a worker silently resolved a *different* harness version out of
-its own package cache. So `setup host` also installs one mount unit,
-`var-lib-omp\x2dworker\x2dharness-node_modules.mount`, binding your install
-read-only at `/var/lib/omp-worker-harness/node_modules`, and launches worker
-children from that path. It is a bind, not a copy: upgrade the harness and every
-worker picks it up with nothing to re-materialise. The mount's parent directory
-is `root:omp-worker` `0750`, so the bound tree is reachable by root and the
-worker account and by no other local account.
-
-Three consequences worth knowing:
-
-- `omp-conductor` must be installed, not run from a source checkout, for worker
-  dispatch to work — a checkout has no install root to bind.
-- If the binding is missing or no longer resolves to your install, the daemon
-  refuses to launch workers and says so (`setup host` reports the same thing as
-  pending work). Re-run `omp-conductor setup host`; no attempt is charged to the
-  issue, because no session ever started.
-- The check runs at every launch, not once at daemon startup. The mount unit is
-  ordered before the daemon, so a reboot brings them up in the right order — and
-  if the binding ever arrives late anyway, the next dispatch picks it up with no
-  restart needed.
+### What confines a worker session
+
+Worker sessions run as the fleet account — the same account the daemon runs as.
+An earlier release ran them under a dedicated `omp-worker` UID with your install
+bind-mounted read-only for them to resolve; that design did not survive contact
+with Bun's install, cache and native-addon resolution (a worker could not load
+the harness at all), and it was withdrawn. Exposing package files is not a
+self-contained runnable runtime.
+
+What confines a worker is unchanged, and none of it needed a separate account:
+
+- **its worktree.** Dispatch hands each run an isolated git worktree and session
+  directory; that is its writable world for the attempt.
+- **its verbs.** A worker session may push and open a pull request through the
+  mediated verbs and nothing else: `conductor_pr_merge`, `conductor_label` and
+  `conductor_release` refuse a worker mechanically, whatever any config says.
+- **its budget.** Turn, wall-clock, spend and attempt caps bound every run, and
+  a cap kill is recorded rather than retried silently.
+- **its review.** A green pull request is where a worker stops; merging is the
+  orchestrator's, behind the exact-head, green-checks and single-flight gates.
+
+`setup host` no longer provisions that account, its ACL projection or the mount
+unit, and a host that carries them from an earlier release is converged the next
+time `setup host` or `upgrade` runs: the mount is disabled, unmounted and
+removed, before anything else in the transaction. The account itself is left
+alone — an unused Unix account is inert, and deleting one to tidy up is
+destructive.
+
+OS-user isolation is a design worth revisiting, and the next attempt needs an
+immutable self-contained worker runtime rather than a bind of the operator's
+install, a real end-to-end session preflight before any switch, and atomic
+rollback. Until then, `omp-conductor` still has to be *installed* (not run from a
+source checkout) for a worker to resolve its harness peer.
 
 ### Stop the conductor (hold / stop)
 
@@ -407,12 +407,77 @@ Clear the pin with `omp-conductor resume` when you want recovery again.
 ### See the fleet in a browser: `dashboard`
 
 `omp-conductor dashboard` serves the same fleet facts `status` and `board`
-render, in a browser: a static UI plus one read endpoint, `GET /api/projects`,
-which answers with every configured project annotated with its daemon state
-(the same `livingDaemon` + `/healthz` classification `status` uses), the
-daemon's port, and the raw `/healthz` body when it answers. It is a separate
-process from the dispatch daemon and only ever reads fleet state — nothing on
-the daemon port changes.
+render, in a browser, and — since #295 — lets you *act* on them without a shell
+on the host. It is a separate process from the dispatch daemon: the read surface
+(`GET /api/projects`, `/api/overview`, and per-project `board`, `status`,
+`ledger`, `reports`, `runs/:issue`) reads fleet state exactly as `status` does,
+and the control surface (`POST`) routes every action to the same code the CLI
+verb runs.
+
+| action | what it does |
+|---|---|
+| `pause` / `resume` | stop and restart new claims, **keeping the heartbeat** — the cheap, reversible control |
+| `hold` | stop claims *and* disarm ticks; re-arming costs a Telegram challenge, so the UI confirms it by name |
+| `disarm` | take the heartbeat down without touching dispatch |
+| `runs/:issue/extend` | raise a run's turn ceiling, **proxied to the owning daemon** so its own bounds and refusals apply verbatim |
+| `runs/:issue/worker/{pause,resume,stop}` | drive one live worker, proxied for the same reason — the daemon holds the session controller |
+| `runs/:issue/unblock` | the same `unblock` the CLI runs, `force` included and confirmed by name |
+| `decisions/:id/answer` | resolve one open decision; a second answer is a `409`, never a silent overwrite |
+
+Three properties are worth knowing before you use it:
+
+- **Nothing here is a second implementation.** Where an action already lives
+  behind the daemon's HTTP surface, the dashboard *calls that endpoint* rather
+  than reaching past it to the store. `extend` is the instructive case: the
+  daemon's `turn-limit` route owns the ceiling bound, the live-controller check
+  and the not-an-increase refusal, so its `409`/`422` answers pass through
+  unchanged and the browser cannot come to disagree with `omp-conductor extend`.
+- **A dead daemon is a `502` naming it**, never a `200` that pretends a worker
+  was paused.
+- **`arm` is deliberately absent.** It requires an inbound Telegram proof that a
+  human answered a challenge, and a browser button cannot supply one — a
+  dashboard `arm` would either weaken that proof or lie about having it. Arming
+  stays CLI/Telegram.
+
+**Watching a run.** The run detail view streams the transcript live
+(`GET .../runs/:issue/transcript/stream`, Server-Sent Events). It is the same
+follow `omp-conductor tail` runs — the same 1s re-stat cadence, reading from byte
+zero so attaching to a run ten turns in shows all ten, and the same advisor
+transcripts alongside. Nothing here touches the daemon: two browsers on one run
+are two read-only file follows, and a fleet with no daemon running at all still
+streams. A run with no transcript yet gets one explicit `error` event saying so
+rather than an empty stream that reads as a quiet worker; a finished run streams
+its tail, writes `run ended: <state>`, and closes.
+
+One wrinkle worth knowing: `EventSource` cannot set an `Authorization` header, so
+this endpoint — and only this endpoint — also accepts `?token=`. A URL can reach
+a server log or a browser history entry, which is why the acceptance is scoped to
+that exact path and stated rather than buried.
+
+**Analytics.** The Analytics tab answers *what did the fleet accomplish, and at
+what cost* — merges per week, USD per merged PR, lead-time p50/p90, attempts per
+merge, and a failure-class histogram, over a 7d/30d/custom window. It is the
+same aggregation `omp-conductor stats` prints, computed by the same module: one
+implementation, two consumers, so the page and the CLI cannot disagree about a
+number. Store-only — rendering it makes no GitHub API calls.
+
+Two things it deliberately will not do. A window in which nothing settled
+renders an explicit *nothing settled* rather than a chart of zeros, because a
+zero drawn on an axis reads as a measurement. And runs whose harness reported no
+spend (`spendUsd = 0`) are counted as **unmetered**, never averaged in as free:
+cost-per-merge divides by the merged issues that actually metered, and the
+unmetered remainder is named beside it.
+
+**Answering a question.** Open decisions render on the Reports tab with an
+answer box, resolving through the same `PUT /decisions/:id/answer` the CLI's
+`decision resolve` uses — so a second answer to the same question is a 409, not
+a silent overwrite. Watches are listed but never offered an answer box: a watch
+is the orchestrator's own condition, not a question anyone asked you.
+
+Every mutation attributes itself with source `dashboard`, so `status` can say
+*who* paused the fleet rather than only that it is paused. The operator's own
+sentence rides in the sentinel's `reason=` field, because `source=` is a
+space-free token the pause fence matches on.
 
 Binds `127.0.0.1:8788` by default. First start mints a bearer token at
 `<stateDir()>/dashboard-token` (mode `0600`, next to `config.json` under
@@ -620,7 +685,7 @@ reference — usage strings, flags and per-command behaviour — is in the
 | `doctor [--json] [--probe-telegram]` | Read-only deployment health — gh auth, exact-case labels, systemd drift, config backup, sqlite integrity, spend telemetry, timezones, Telegram. Run after install and after every upgrade; exit 0 only when nothing failed. |
 | `ledger [--json]` | The action audit — every mediated verb, refusal and turn budget. |
 | `board` | Live terminal kanban from Queue to Settled. |
-| `dashboard [--port N] [--host ADDR]` | Browser UI plus bearer-authenticated `/api/projects`: every project's daemon state, port and healthz. Loopback by default; the token lives at `<state>/dashboard-token`. |
+| `dashboard [--port N] [--host ADDR]` | Browser UI plus a bearer-authenticated API: read the fleet (`/api/projects`, `overview`, `board`, `status`, `ledger`, `reports`, `runs`, `stats`) and drive it (`pause`/`resume`/`hold`/`disarm`, `extend`, `unblock`, worker control, decision answering), plus a live SSE transcript stream per run and an analytics view over the same aggregation `stats` prints. `arm` is deliberately absent. Loopback by default; the token lives at `<state>/dashboard-token`. |
 | `hold [--keep-ticks]` | Pause claims and disarm ticks — the soft stop. |
 | `arm` / `disarm` | Gate / clear the orchestrator tick's arm marker. |
 | `tail <issue>` | Follow a live worker's transcript. |