omp-conductor 0.3.15 → 0.3.17

package/README.md

@@ -7,17 +7,16 @@ tiers: first to an orchestrator session that can re-brief the worker, then to yo
 ## What it is
 
 You label an issue. Within one tick the conductor claims it on the tracker, cuts a
-worktree, hands one omp session a self-contained brief, watches it to a green PR —
-and then stops. Merging is a human act; the conductor never performs it.
+worktree, hands one omp worker a self-contained brief, and watches it to a green
+PR. The worker then stops: it never merges, tags, publishes or deploys.
 
 ### Scope
 
-One issue, one green PR. That is the whole remit.
-
-Merging is a human act, and so is releasing. Releases are **batched**: cut from a
-coherent group of merged work by a human-supervised decision, never one per PR. So
-nothing in this package tags, pins, deploys or publishes, and no worker is ever
-asked to. A worker whose change needs releasing reports that and stops.
+One issue, one green PR. That is the worker's whole remit. A change that needs a
+merge or release is reported to the orchestrator, whose `merge` and `release`
+authority are chosen during setup and default to `human`. Granting either action
+to the orchestrator never grants it to a worker or the dispatch daemon. Releases
+remain batched from coherent groups of merged work, never cut one per worker PR.
 
 Code counts every limit that decides whether work starts: concurrency, dollars per
 day, turns and wall clock per worker, attempts per issue. None of it is left to the
@@ -29,10 +28,10 @@ When a run does get stuck, the first responder is not you. A tier-1 escalation i
 injected into a long-lived **orchestrator session** that can read the issue and the
 run's transcript and then either re-brief the worker or decide the problem genuinely
 needs a human. It never edits product code and never pushes a branch; whether it
-may *merge* is a setup answer (`authority`), and it defaults to no. Only tier 2
-pages you directly.
+may merge or release is a setup answer (`authority`), and both default to no. Only
+tier 2 pages you directly.
 
-The package ships three deployables, plus one skill:
+The package ships three deployables, plus two skills:
 
 | Deployable | Entry | What it is for |
 | --- | --- | --- |
@@ -40,6 +39,7 @@ The package ships three deployables, plus one skill:
 | Standalone daemon | `omp-conductor` binary | The dispatch loop, managed as a background process (`start` / `stop` / `restart`) with a `/healthz` endpoint for a supervisor. |
 | Orchestrator heartbeat | omp extension, activated by `.conductor-tick.json` | Prompts a 24/7 orchestrator session on a fixed interval so its standing loop actually runs, and marks the session stalled when its prompts stop being consumed. Inert in every other session — including a second session opened in the fleet's own directory. See [Orchestrator tick](#orchestrator-tick). |
 | Onboarding skill | `skill://conductor-onboarding` | Directs an omp session to interview you, read your repos for real CI gates, and tailor `ORCHESTRATOR.md` — then finish through the wizard. Discovered automatically once the plugin is installed. See [Onboarding](#onboarding). |
+| Update skill | `skill://conductor-update` | Treats the Bun-global CLI, omp plugin, and Herdr plugin as one operation: pause claims, drain, install one pinned release, reload, verify twice, and restore the prior pause state. See [Updating](#updating). |
 
 The first two are thin wrappers over the same `daemon.ts`, so the plugin and the
 CLI cannot disagree about what a cap means or where the state lives. Claiming is
@@ -166,6 +166,28 @@ Also required on the host:
   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.
 
+## Updating
+
+Say “update conductor” from an operator shell or maintenance omp session outside
+the target `herdr-fleet.service`. That is the whole operator interface. The bundled
+`skill://conductor-update` discovers the installed and registry versions, pauses
+new claims while active work drains, and pins one release across the Bun-global
+CLI, omp plugin, and Herdr plugin. It converts an old local Herdr link to a managed
+checkout when necessary, reloads the Herdr service and dispatch daemon, verifies
+the layered status twice, and restores the original dispatch state.
+
+Ticks remain in their existing armed or disarmed state, so an ordinary update
+does not halt the exact pane or require another Telegram arm challenge. Any
+installation, reload, or verification failure leaves dispatch paused instead of
+bringing up a mixed fleet. The skill does not publish npm or edit an install root.
+It also refuses to run from the fleet pane that Herdr must restart: an updater
+that kills itself cannot verify the result. With skill commands enabled, invoke
+it directly with:
+
+```text
+/skill:conductor-update
+```
+
 ## Onboarding
 
 Onboarding this package has two layers, and installing it gives you both.
@@ -225,7 +247,7 @@ the file behind instead. So a re-run against a project that is already configure
 opens with one question:
 
 ```text
-"veltro" is already configured — what would you like to do?
+"platform" is already configured — what would you like to do?
 > Change one area
     asks one area's questions; every other answer is carried through from the saved config
   Walk every question again
@@ -237,14 +259,14 @@ says right now, so the row you want is the row you can see:
 
 ```text
 Which area? Each row shows what it says now
-  tracker & repos — veltrosecurity/veltro, queue "ready-for-agent", "repo:" → veltro, chad, warden, vectorflow
-  gates — veltro: none; chad: ruff check . @ backend, pnpm lint @ frontend; warden: ruff check . @ backen…
+  tracker & repos — acme/platform, queue "ready-for-agent", "repo:" → platform, api, web, worker
+  gates — platform: bun run check; api: ruff check . @ backend; web: pnpm lint…
   caps & worker model — 2 workers, 120 turns, 90m, $25/day, 2 attempts (all defaults) — harness default model
   code graph — not configured — workers grep
   authority — merge=orchestrator, release=orchestrator
-  escalation & triage — tier 2 pages Telegram 8236653927, comments too, triage external
+  escalation & triage — tier 2 pages Telegram 123456789, comments too, triage external
   reporting scope — material — escalations, plus green PRs, second failures, and anything that stops the fleet
-  orchestrator brief — none at /root/.omp/conductor/worktrees/ORCHESTRATOR.md
+  orchestrator brief — none at ~/.omp/conductor/worktrees/ORCHESTRATOR.md
 ```
 
 Only that area's questions are asked. Every other answer is read back out of
@@ -254,11 +276,11 @@ writes a config, and it still writes nothing before you agree. The consent scree
 leads with the delta and then shows the whole project as it would be written:
 
 ```text
-amending       code graph  —  project veltro
+amending       code graph  —  project platform
   was            not configured — workers grep
-  now            /root/.cache/conductor-graph/veltrosecurity — 4 clone(s): veltro, chad, warden, vectorflow
+  now            ~/.cache/conductor-graph/acme — 4 clone(s): platform, api, web, worker
   carried over   tracker & repos, gates, caps & worker model, authority, escalation & triage, reporting scope, orchestrator brief
-                 read back from /root/.omp/conductor/config.json and rewritten unchanged
+                 read back from ~/.omp/conductor/config.json and rewritten unchanged
 ```
 
 A first run, or a project name this config has never seen, never sees either
@@ -331,12 +353,22 @@ The **Learning loop** proposes diffs against `POLICY.md` for you to approve over
    omp-conductor start
    ```
 
-   `start` does not report success until the daemon actually answers
-   `GET /healthz`. Spawning is not starting: a daemon whose config is broken, whose
-   port is taken or whose database is locked exits within a second, and a `start`
-   that printed "started" for it would hand you a lie you discover only when work
-   silently fails to be picked up. On failure the error quotes the tail of
-   `daemon.log`. It refuses to start a second daemon, naming the pid of the live one.
+   `start` first starts `herdr-fleet.service` when that optional unit is installed,
+   clearing a previous `halt --pane` recovery pin so Herdr can resume the exact
+   conductor pane. Hosts without systemd or without that unit keep the standalone
+   daemon behaviour. It then waits until the daemon actually answers
+   `GET /healthz`; spawning is not starting. A daemon whose config is broken,
+   whose port is taken or whose database is locked exits within a second, and the
+   command fails with the tail of `daemon.log` instead of printing a false
+   success. It refuses to start a second daemon, naming the live pid. Starting
+   processes does not clear `pause` or arm ticks; those remain explicit operator
+   decisions.
+
+   Pane recovery spans two separately installed plugins: npm ships the omp
+   heartbeat/status half, while `herdr-conductor` supplies `recover.sh`. After an
+   npm upgrade, refresh the Herdr plugin from `TerrifiedBug/conductor/herdr` as
+   well; publishing or installing npm alone cannot add the recovery-side tick
+   request.
 
    For a first run, take a single tick in the foreground and watch it:
 
@@ -366,7 +398,7 @@ Four control planes used to answer "stop" differently. The package verbs:
 
 `resume` clears pause only and **never re-arms**. `arm` is proof-gated: it sends a Telegram challenge and writes the arm marker only after your reply appears as a *user* turn in the orchestrator transcript. `halt --pane` targets the configured conductor agent only — it does **not** run `systemctl stop herdr-fleet`.
 
-`status` prints a layered header (`dispatch` / `ticks` / `pane` / `recovery` / `herdr` / `daemon`) so a paused fleet cannot hide an armed orchestrator still spending turns.
+`status` prints a layered header (`dispatch` / `ticks` / next tick time / `pane` / `recovery` / `herdr` / `telegram` / `daemon`) so a paused fleet cannot hide an armed orchestrator still spending turns. The Telegram line calls the official `getMe` endpoint to prove the token and API are usable without sending a message, then separately reports whether the inbound bridge is configured.
 
 `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
@@ -1043,7 +1075,7 @@ indistinguishable from the first:
 ```text
 [omp-conductor] orchestrator tick inactive: pane w1:p1 (agent "fleet") owns the fleet tick here — this session will not tick
 [omp-conductor] orchestrator tick inactive: this pane is agent "scratch", not the fleet agent "fleet" — this session will not tick
-[omp-conductor] orchestrator tick inactive: pid 4147344 (claimed 2026-08-07T07:55:36.001Z, session …/fleet.jsonl) owns the fleet tick in /root/.omp/conductor — this session will not tick
+[omp-conductor] orchestrator tick inactive: pid 12345 (claimed 2026-01-02T03:04:05.000Z, session …/fleet.jsonl) owns the fleet tick in /home/conductor/.omp/conductor — this session will not tick
 ```
 
 A `herdr agent list` that does not answer also declines, for the same reason the
@@ -1164,6 +1196,7 @@ least of all on a fleet whose session lives somewhere else.
 
 ```bash
 omp-conductor start [--port N] [--project NAME]
+omp-conductor --version
 omp-conductor stop
 omp-conductor restart [--port N] [--project NAME]
 omp-conductor status [--project NAME]
@@ -1184,10 +1217,10 @@ omp-conductor help
 
 | Command | Behaviour |
 | --- | --- |
-| `start` | Spawn the loop in the background, detached, and wait until it answers `GET /healthz` on `:8787`. Refuses if one is already live, naming its pid. If the process dies or never serves, `start` cleans up after it and quotes the tail of `daemon.log`. |
+| `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). |
-| `status [--project NAME]` | Layered fleet report first: `dispatch` / `ticks` / `pane` / `recovery` / `herdr` / `daemon`, then the project body (caps, active runs, today's usage). The `daemon` block includes `rss` from `/healthz` when the process is up (workers share that PID — see [host sizing](#host-sizing-and-memory)). While live workers > 0, prints a `deploy` line naming the count so a busy restart is visible before you take it. A `.conductor-stalled` marker in the state directory adds an `orchestrator   STALLED since …` line — see [the stall marker](#a-wedged-session-and-the-marker-that-notices). Reads while a daemon in another process writes. |
+| `status [--project NAME]` | Layered fleet report first: `dispatch` / `ticks` / next scheduled tick / `pane` / `recovery` / `herdr` / `telegram` / `daemon`, then the project body. The next time 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. The daemon block includes `rss` from `/healthz`; live workers add a busy-deploy warning. A `.conductor-stalled` marker adds an `orchestrator STALLED since …` line. |
 | `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`. |
@@ -1201,6 +1234,7 @@ omp-conductor help
 | `--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. |
 | `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). |
 | `--write` | Only for `graph-setup`. Writes the refresh script into the state directory and the two units into `/etc/systemd/system`, then prints the exact `systemctl daemon-reload && systemctl enable --now cbm-reindex.timer` to run. It never runs `systemctl` itself and never enables anything: that needs root, and a package that enables system timers behind your back is one you cannot audit by reading its output. |
 | `brief-upgrade` | Inspect the package-floor + `POLICY.md` overlay. Reports by default; see [Keeping a brief current](#keeping-a-brief-current). |
@@ -1368,8 +1402,9 @@ Known and deliberate in this version:
   `slots = maxConcurrentWorkers - live workers`, admits at most that many issues
   per tick, and dispatches them together. To see them, read `omp-conductor
   status`, which lists every occupied issue, or follow `daemon.log`.
-- **Merges, releases and deploys are human-only, by design.** The conductor
-  produces green PRs and stops.
+- **Workers stop at green PRs.** They never merge, release or deploy. Those
+  actions default to a human, but setup may grant either to the orchestrator;
+  `authority` never grants them to a worker or the dispatch daemon.
 - **Worker confinement is partial.** Structured `write` / `edit` / `read` /
   `grep` / `glob` calls are blocked outside the worktree by an inline harness
   extension (`confineToCwd`). `bash` is not: a shell one-liner can still leave

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "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.",
@@ -17,7 +17,7 @@
     ]
   },
   "bin": {
-    "omp-conductor": "./src/cli.ts"
+    "omp-conductor": "src/cli.ts"
   },
   "files": [
     "src",

package/skills/conductor-update/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: conductor-update
+description: Update an installed conductor fleet through one operator request. Use when the user asks to update, upgrade, refresh, reinstall, or deploy conductor. Pins one npm release across the Bun-global CLI, omp plugin, and Herdr recovery plugin; converts a local Herdr link when needed; pauses claims, reloads processes, verifies the fleet, and restores the operator's prior pause state.
+---
+
+# Update a conductor fleet
+
+The operator interface is one request: **“update conductor.”** Do not hand them
+the implementation as a checklist unless execution is blocked.
+
+One release has three installed surfaces:
+
+1. Bun-global `omp-conductor`: CLI and systemd daemon source.
+2. omp npm plugin `omp-conductor`: slash command and heartbeat loaded by sessions.
+3. Herdr plugin `herdr-conductor`: exact-pane recovery, pinned to the npm
+   release's `gitHead`.
+
+This skill performs the whole swap. It does not publish npm, merge, tag, edit an
+install root, or update unrelated Bun packages.
+
+## Safety boundary
+
+Run from an operator shell or maintenance omp session that is not hosted by the
+target `herdr-fleet.service`. If restarting that unit would kill this updater,
+move to an external session first. Never print npm, Telegram, or bot credentials.
+
+The normal update is:
+
+```text
+inspect → pause claims → drain → pinned installs → reload → verify → restore pause state
+```
+
+Ticks stay in their existing armed or disarmed state. Do not use `hold`,
+`halt --pane`, `disarm`, `arm`, recovery pins, `pkill`, or manual install-root
+edits for a healthy update.
+
+## 1. Resolve one release and inspect every surface
+
+Use the registry latest unless the operator names another published version:
+
+```bash
+version=$(npm view omp-conductor version)
+gitHead=$(npm view "omp-conductor@$version" gitHead)
+npm view "omp-conductor@$version" version gitHead --json
+```
+
+Require `$version` to be nonempty and `$gitHead` to be a full commit SHA before
+changing state.
+
+Inspect, without mutating:
+
+```bash
+omp-conductor --version
+omp plugin list --json
+herdr --session "$session" plugin list
+omp-conductor status [--project NAME]
+```
+
+Honor the installation's existing Herdr session and `HERDR_CONFIG_PATH`; discover
+them from the running unit/config rather than assuming `fleet` or a path.
+
+Record:
+
+- Bun-global CLI version;
+- omp plugin version;
+- Herdr plugin source: GitHub revision, `local:<path>`, or missing;
+- initial dispatch state: running, paused, or stopped;
+- initial ticks state, which this update must not change;
+- active runs and layered health.
+
+Report “already current” only when **all** of these are true:
+
+- Bun-global CLI version equals `$version`;
+- omp plugin version equals `$version`;
+- Herdr source revision equals `$gitHead`;
+- layered status is healthy for the fleet's configured topology.
+
+A current npm version with a linked, missing, or stale Herdr plugin is a partial
+update, not a no-op. If all versions match but status is unhealthy, diagnose the
+reported layer; never call an unhealthy fleet current.
+
+## 2. Pause claims and drain
+
+If dispatch was running:
+
+```bash
+omp-conductor pause [--project NAME]
+```
+
+If it was already paused, preserve that state. If it was stopped, do not start it
+later merely because packages were updated.
+
+Wait for `active runs (none)`. Never kill workers for an update. If a run does not
+drain, stop and report it; leave any pause this skill added in place.
+
+## 3. Replace all three surfaces with the pinned release
+
+Use exact versions. A broad `bun update` is prohibited.
+
+```bash
+bun add -g "omp-conductor@$version"
+omp plugin install "omp-conductor@$version"
+```
+
+For Herdr, inspect the source found in step 1:
+
+- `local:<path>`: unlink the plugin id first;
+- GitHub-managed or missing: do not unlink.
+
+Then install the exact npm release commit. Herdr requires the source argument
+before its options:
+
+```bash
+herdr plugin unlink herdr-conductor  # only when step 1 reported local:<path>
+herdr plugin install TerrifiedBug/conductor/herdr --ref "$gitHead" --yes
+```
+
+If any install fails, do not reload processes and do not restore dispatch.
+Leave the fleet paused, report the failed surface, and give the one retry command.
+The still-running processes keep their already-loaded code until a successful
+reload.
+
+## 4. Reload the installed code
+
+When Herdr is systemd-managed, restart its fleet unit. This reloads the managed
+recovery plugin and causes exact-identity recovery to resume the orchestrator pane
+with the new omp extension:
+
+```bash
+systemctl restart herdr-fleet.service
+```
+
+Wait until Herdr reports its unit active and the exact configured agent live.
+
+If the dispatch daemon was running or paused initially, restart it so its process
+and source-integrity baseline use the new Bun-global package:
+
+```bash
+omp-conductor restart [--project NAME]
+```
+
+Do not substitute `start` when the daemon was initially stopped.
+
+## 5. Verify before restoring claims
+
+Check every surface again:
+
+```bash
+omp-conductor --version
+omp plugin list --json
+herdr --session "$session" plugin list
+omp-conductor status [--project NAME]
+systemctl is-active herdr-fleet.service
+```
+
+Require:
+
+- global CLI and omp plugin both equal `$version`;
+- Herdr source equals `TerrifiedBug/conductor` at `$gitHead`;
+- exact pane is live and recovery is clear;
+- Herdr and daemon health are OK when managed;
+- ticks equal their initial state;
+- active runs remain empty;
+- dispatch remains paused if this skill paused it.
+
+Run status a second time after recovery settles. Any failed check leaves dispatch
+paused and is reported as a partial update.
+
+Only if dispatch was initially running and every check passed:
+
+```bash
+omp-conductor resume [--project NAME]
+```
+
+Verify `dispatch running` once more. If dispatch was initially paused or stopped,
+preserve that state and report it.
+
+Finish with one compact result: old → new version, all three installed surfaces,
+final layered status, and whether the original dispatch state was restored.

package/src/cli.ts

@@ -31,6 +31,7 @@ import {
   hold,
   releaseHold,
   renderStatus,
+  startHerdrFleet,
 } from "./fleet.ts";
 import { formatGraphSetup, graphRepos, writeGraphSetup, type GraphSetupWrite } from "./graph.ts";
 import {
@@ -55,10 +56,21 @@ import { makeTracker } from "./tracker/github.ts";
 import type { ProjectConfig } from "./types.ts";
 import { formatUnblock, unblockIssue } from "./unblock.ts";
 
+function packageVersion(): string {
+  const parsed = JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"), "utf8")) as {
+    version?: unknown;
+  };
+  if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+    throw new Error("installed package.json has no version");
+  }
+  return parsed.version;
+}
+
 const USAGE = `omp-conductor — dispatch ready issues to omp coding sessions
 
 usage:
   omp-conductor start [--port N] [--project NAME]
+  omp-conductor --version
   omp-conductor stop
   omp-conductor restart [--port N] [--project NAME]
   omp-conductor status [--project NAME]
@@ -76,9 +88,9 @@ usage:
   omp-conductor brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]
   omp-conductor help
 
-  start    run the dispatch loop in the background and wait until it answers
-           GET /healthz on :8787 (override with --port). Refuses if one is
-           already running.
+  start    start the installed herdr-fleet.service when present, then run the
+           dispatch loop in the background and wait until it answers GET
+           /healthz on :8787 (override with --port). Refuses if one is running.
   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.
@@ -87,8 +99,9 @@ usage:
            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
-           (armed|disarmed|…), pane, herdr, daemon — then caps and active runs.
+  status   layered fleet report: dispatch (running|paused|stopped), ticks and
+           next due time, pane, herdr, Telegram bot/API health, daemon, caps
+           and active runs.
   hold     soft stop: pause claiming AND disarm ticks. Daemon and pane stay up.
            This is "stop the conductor overnight" without killing processes.
   halt     hold, then stop the dispatch daemon (systemctl-aware). Pane stays up
@@ -133,6 +146,8 @@ usage:
            --apply still merges a bannered single-file brief. --file checks a
            brief that is not where the wizard would have put it.
   help     print this text (also --help, -h).
+  --version
+           print the installed omp-conductor package version (also -V, version).
 
 Pause is a flag file under the state directory, so it applies to every project
 and survives a daemon restart. Hold also removes the arm marker the heartbeat
@@ -378,6 +393,11 @@ const cmd = argv[0];
 
 try {
   switch (cmd) {
+    case "--version":
+    case "-V":
+    case "version":
+      process.stdout.write(`${packageVersion()}\n`);
+      break;
     case "daemon": {
       // Until now only `lifecycle.startDaemon()` — the spawn path — wrote the
       // pidfile, which left a daemon started in the foreground (which is how
@@ -429,10 +449,14 @@ try {
     }
 
     case "start": {
-      const rec = await startDaemon({ port: portFlag(argv), project: flag(argv, "project") });
+      const project = flag(argv, "project");
+      const herdr = startHerdrFleet(project);
+      const rec = await startDaemon({ port: portFlag(argv), project });
       process.stdout.write(
         `started — pid ${rec.pid}, /healthz on :${rec.port}` +
-          `${rec.project === undefined ? "" : `, project ${rec.project}`}\nlog ${rec.logFile}\n`,
+          `${rec.project === undefined ? "" : `, project ${rec.project}`}\n` +
+          `herdr ${herdr.kind === "active" ? `active (${herdr.unit})${herdr.recoveryReleased ? "; recovery pin cleared" : ""}` : `unmanaged (${herdr.reason})`}\n` +
+          `log ${rec.logFile}\n`,
       );
       break;
     }

package/src/fleet.ts

@@ -31,6 +31,7 @@ import { findProject, loadConfig, stateDir } from "./config.ts";
 import { isPaused, setPaused, statusSnapshot, type StatusSnapshot } from "./daemon.ts";
 import {
   healthCheck,
+  isAlive,
   livingDaemon,
   stopDaemon,
   type StopResult,
@@ -39,6 +40,7 @@ import {
 import { formatRss, rssBytesFromHealthz } from "./host.ts";
 import {
   readTickConfig,
+  readTickRuntimeStatus,
   TICK_CONFIG_FILE,
   type TickConfig,
   type TickConfigResult,
@@ -304,6 +306,66 @@ export function clearPaneHalt(projectName?: string): { path: string; wasHalted:
   return { path, wasHalted };
 }
 
+export type HerdrStartResult =
+  | { kind: "active"; unit: string; recoveryReleased: boolean }
+  | { kind: "unmanaged"; unit: string; reason: string };
+
+export interface HerdrStartDeps {
+  systemctl?: (args: string[]) => { ok: boolean; stdout: string; stderr: string; missing?: boolean };
+}
+
+/**
+ * Starts the dedicated Herdr fleet unit when it is installed. Hosts without
+ * systemd or without that optional unit keep the standalone daemon behaviour.
+ */
+export function startHerdrFleet(projectName?: string, deps: HerdrStartDeps = {}): HerdrStartResult {
+  const run: NonNullable<HerdrStartDeps["systemctl"]> =
+    deps.systemctl ??
+    ((args: string[]) => {
+      const res = spawnSync("systemctl", args, { encoding: "utf8", timeout: 15_000, env: process.env });
+      if (res.error) {
+        const err = res.error as NodeJS.ErrnoException;
+        return {
+          ok: false,
+          stdout: "",
+          stderr: err.message,
+          ...(err.code === "ENOENT" ? { missing: true } : {}),
+        };
+      }
+      return { ok: res.status === 0, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+    });
+
+  const shown = run(["show", DEFAULT_HERDR_UNIT, "--property=LoadState", "--value"]);
+  if (shown.missing) return { kind: "unmanaged", unit: DEFAULT_HERDR_UNIT, reason: "no systemctl" };
+  if (!shown.ok) {
+    const detail = (shown.stderr.trim() || shown.stdout.trim() || "systemctl show failed").split("\n")[0]!;
+    throw new Error(`cannot inspect ${DEFAULT_HERDR_UNIT}: ${detail}`);
+  }
+  const loadState = shown.stdout.trim();
+  if (loadState === "not-found" || loadState === "") {
+    return { kind: "unmanaged", unit: DEFAULT_HERDR_UNIT, reason: "unit not installed" };
+  }
+  if (loadState !== "loaded") {
+    throw new Error(`${DEFAULT_HERDR_UNIT} is ${loadState}, not startable`);
+  }
+
+  const halt = resolvePaneHaltPath(projectName);
+  const recoveryReleased = halt.kind === "ok" && existsSync(halt.path);
+  if (halt.kind === "ok") rmSync(halt.path, { force: true });
+
+  const started = run(["start", DEFAULT_HERDR_UNIT]);
+  if (!started.ok) {
+    const detail = (started.stderr.trim() || started.stdout.trim() || "systemctl start failed").split("\n")[0]!;
+    throw new Error(`systemctl start ${DEFAULT_HERDR_UNIT} failed: ${detail}`);
+  }
+  const active = run(["is-active", DEFAULT_HERDR_UNIT]);
+  if (!active.ok || active.stdout.trim() !== "active") {
+    const detail = (active.stderr.trim() || active.stdout.trim() || "not active").split("\n")[0]!;
+    throw new Error(`${DEFAULT_HERDR_UNIT} did not become active: ${detail}`);
+  }
+  return { kind: "active", unit: DEFAULT_HERDR_UNIT, recoveryReleased };
+}
+
 export interface HerdrAgent {
   name: string;
   paneId: string;
@@ -565,11 +627,13 @@ async function herdrAgentList(deps: PaneStopDeps): Promise<HerdrAgent[]> {
   if (res.status !== 0) {
     throw new Error((res.stderr ?? res.stdout ?? `herdr exit ${String(res.status)}`).trim());
   }
-  // Everything below is fail-closed: only an explicit `agents: []` means "no
-  // agents". Empty output, unparseable JSON, a missing `agents` key or a row
-  // we cannot read is uncertainty — collapsing any of it to `[]` would report
-  // a live conductor pane as `already-gone`.
-  const raw = (res.stdout ?? "").trim();
+  return parseHerdrAgentList(res.stdout ?? "");
+}
+
+export function parseHerdrAgentList(rawOutput: string): HerdrAgent[] {
+  // Only an explicit `agents: []` means no agents. Every malformed answer is
+  // uncertainty, never permission to report the conductor pane missing.
+  const raw = rawOutput.trim();
   if (raw.length === 0) {
     throw new Error("herdr agent list printed nothing — cannot tell whether the pane is running");
   }
@@ -590,38 +654,35 @@ async function herdrAgentList(deps: PaneStopDeps): Promise<HerdrAgent[]> {
     if (row === null || typeof row !== "object") {
       throw new Error("herdr agent list contains a non-object agent row — unrecognized schema");
     }
-    const a = row as { readonly [key: string]: unknown };
-    const name = a["name"];
-    const paneId = a["pane_id"];
+    const agent = row as { readonly [key: string]: unknown };
+    const name = agent["name"];
+    const paneId = agent["pane_id"];
     if (typeof name !== "string" || typeof paneId !== "string") {
       throw new Error(
         "herdr agent list row is missing a string `name`/`pane_id` — " +
           "cannot tell whether it is the conductor pane",
       );
     }
-    // An absent (or null) `agent` is how herdr reports a sticky claim whose
-    // agent has exited — recover.sh reads the same field as `(.agent // "")`,
-    // and the released-agent fixture omits the key entirely. A *present* value
-    // of any other type is a row we cannot read: coercing it to `undefined`
-    // would report a live pane as already-gone.
-    const rawAgent = a["agent"];
+    const rawAgent = agent["agent"];
     if (rawAgent !== undefined && rawAgent !== null && typeof rawAgent !== "string") {
       throw new Error(
         `herdr agent list row for ${name} has a non-string \`agent\` (${typeof rawAgent}) — ` +
           `cannot tell whether an agent is live`,
       );
     }
-    const agent = typeof rawAgent === "string" ? rawAgent : undefined;
+    const liveAgent = typeof rawAgent === "string" ? rawAgent : undefined;
     let sessionPath: string | undefined;
-    const sess = a["agent_session"];
-    if (sess !== null && typeof sess === "object") {
-      const s = sess as { readonly [key: string]: unknown };
-      if (s["source"] === "herdr:omp" && typeof s["value"] === "string") sessionPath = s["value"];
+    const session = agent["agent_session"];
+    if (session !== null && typeof session === "object") {
+      const value = session as { readonly [key: string]: unknown };
+      if (value["source"] === "herdr:omp" && typeof value["value"] === "string") {
+        sessionPath = value["value"];
+      }
     }
     out.push({
       name,
       paneId,
-      ...(agent === undefined ? {} : { agent }),
+      ...(liveAgent === undefined ? {} : { agent: liveAgent }),
       ...(sessionPath === undefined ? {} : { sessionPath }),
     });
   }
@@ -709,11 +770,18 @@ export type PaneLayer = "live" | "missing" | "unknown";
 /** `unpinnable`: no tick config, so FLEET_CWD — the only path recovery reads — is unknown. */
 export type RecoveryLayer = "pinned" | "clear" | "unpinnable";
 export type HerdrLayer = "active" | "inactive" | "unknown";
+export type TelegramLayer = "ok" | "degraded" | "down" | "unconfigured" | "unprobed";
+
+export interface TelegramHealth {
+  kind: TelegramLayer;
+  detail?: string;
+}
 
 export interface FleetLayers {
   dispatch: DispatchLayer;
   ticks: TicksLayer;
   ticksDetail?: string;
+  nextTickAt?: string;
   pane: PaneLayer;
   paneDetail?: string;
   recovery: RecoveryLayer;
@@ -735,6 +803,7 @@ export function fleetLayers(projectName?: string): FleetLayers {
   const tick = resolveTickConfig(projectName);
   let ticks: TicksLayer;
   let ticksDetail: string | undefined;
+  let nextTickAt: string | undefined;
   let armedPath: string | undefined;
   let tickConfigPath: string | undefined;
   if (tick.kind === "absent") {
@@ -756,6 +825,8 @@ export function fleetLayers(projectName?: string): FleetLayers {
       ticks = "disarmed";
       ticksDetail = tick.config.armedFile;
     }
+    const runtime = readTickRuntimeStatus(tick.cwd);
+    if (runtime !== undefined && isAlive(runtime.pid)) nextTickAt = runtime.nextTickAt;
   }
   if (armedPath === undefined) armedPath = armedMarkerPath(projectName);
 
@@ -764,7 +835,7 @@ export function fleetLayers(projectName?: string): FleetLayers {
   const resolvedHalt = resolvePaneHaltPath(projectName);
   const haltPath = resolvedHalt.kind === "ok" ? resolvedHalt.path : undefined;
   const recoveryPinned = haltPath !== undefined && existsSync(haltPath);
-  const omp = probeOmpPane();
+  const omp = probeOmpPane(projectName);
   let pane: PaneLayer;
   let paneDetail: string | undefined;
   if (omp.kind === "live") {
@@ -783,6 +854,7 @@ export function fleetLayers(projectName?: string): FleetLayers {
     dispatch,
     ticks,
     ...(ticksDetail === undefined ? {} : { ticksDetail }),
+    ...(nextTickAt === undefined ? {} : { nextTickAt }),
     pane,
     ...(paneDetail === undefined ? {} : { paneDetail }),
     recovery: haltPath === undefined ? "unpinnable" : recoveryPinned ? "pinned" : "clear",
@@ -805,11 +877,21 @@ export function formatFleetStatus(
   s: StatusSnapshot,
   layers: FleetLayers,
   daemonHealth?: { ok: boolean; body?: string },
+  telegram: TelegramHealth = { kind: "unprobed" },
+  now = Date.now(),
 ): string {
   const tickLine =
     layers.ticksDetail === undefined
       ? `ticks     ${layers.ticks}`
       : `ticks     ${layers.ticks}  (${layers.ticksDetail})`;
+  let nextTickLine: string | undefined;
+  if (layers.nextTickAt !== undefined) {
+    const delta = Date.parse(layers.nextTickAt) - now;
+    const minutes = Math.max(1, Math.ceil(Math.abs(delta) / 60_000));
+    nextTickLine =
+      `next tick ${layers.nextTickAt}  ` +
+      `(${delta >= 0 ? `in ${minutes}m` : `overdue by ${minutes}m`})`;
+  }
   const paneLine =
     layers.paneDetail === undefined
       ? `pane      ${layers.pane}`
@@ -822,6 +904,10 @@ export function formatFleetStatus(
     layers.herdrDetail === undefined
       ? `herdr     ${layers.herdr}`
       : `herdr     ${layers.herdr}  (${layers.herdrDetail})`;
+  const telegramLine =
+    telegram.detail === undefined
+      ? `telegram  ${telegram.kind}`
+      : `telegram  ${telegram.kind}  (${telegram.detail})`;
 
   let daemonBlock: string;
   if (!layers.daemon.running || layers.daemon.pid === undefined) {
@@ -847,9 +933,11 @@ export function formatFleetStatus(
   return [
     `dispatch  ${layers.dispatch}`,
     tickLine,
+    ...(nextTickLine === undefined ? [] : [nextTickLine]),
     paneLine,
     recoveryLine,
     herdrLine,
+    telegramLine,
     daemonBlock,
     "",
     formatProjectBody(s),
@@ -898,10 +986,12 @@ function formatProjectBody(s: StatusSnapshot): string {
 export async function renderStatus(projectName?: string): Promise<string> {
   const s = statusSnapshot(projectName);
   const layers = fleetLayers(projectName);
-  let health: { ok: boolean; body?: string } | undefined;
   const rec = livingDaemon();
-  if (rec !== undefined) health = await healthCheck(rec.port);
-  return formatFleetStatus(s, layers, health);
+  const [health, telegram] = await Promise.all([
+    rec === undefined ? undefined : healthCheck(rec.port),
+    probeTelegramHealth(projectName),
+  ]);
+  return formatFleetStatus(s, layers, health, telegram);
 }
 
 // ---------------------------------------------------------------------------
@@ -949,6 +1039,57 @@ function readBotToken(): string | undefined {
   return undefined;
 }
 
+export async function probeTelegramHealth(
+  projectName?: string,
+  request: (input: string, init?: RequestInit) => Promise<Response> = fetch,
+): Promise<TelegramHealth> {
+  const tick = resolveTickConfig(projectName);
+  const accessPath =
+    tick.kind === "ok" && tick.config.accessFile !== undefined
+      ? tick.config.accessFile
+      : join(telegramStateDir(), "access.json");
+  const channel = readPairedChannel(accessPath);
+  const token = readBotToken();
+  if (token === undefined) {
+    return {
+      kind: "unconfigured",
+      detail: `no TELEGRAM_BOT_TOKEN; inbound ${channel.kind === "up" ? "configured" : channel.reason}`,
+    };
+  }
+
+  let response: Response;
+  let body: unknown;
+  try {
+    response = await request(`https://api.telegram.org/bot${token}/getMe`, {
+      signal: AbortSignal.timeout(5_000),
+    });
+    body = await response.json();
+  } catch {
+    return {
+      kind: "down",
+      detail: `Telegram API request failed; inbound ${channel.kind === "up" ? "configured" : channel.reason}`,
+    };
+  }
+
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    return { kind: "down", detail: "Telegram API returned an invalid response" };
+  }
+  const result = body as Record<string, unknown>;
+  if (!response.ok || result["ok"] !== true) {
+    const description =
+      typeof result["description"] === "string" ? result["description"] : `HTTP ${response.status}`;
+    return { kind: "down", detail: `${description}; inbound ${channel.kind === "up" ? "configured" : channel.reason}` };
+  }
+
+  const user =
+    result["result"] !== null && typeof result["result"] === "object" && !Array.isArray(result["result"])
+      ? (result["result"] as Record<string, unknown>)
+      : undefined;
+  const username = typeof user?.["username"] === "string" ? `@${user["username"]}` : "authenticated";
+  if (channel.kind === "down") return { kind: "degraded", detail: `${username}; inbound ${channel.reason}` };
+  return { kind: "ok", detail: `${username}; inbound configured` };
+}
+
 export function sessionDirForCwd(cwd: string): string {
   const home = homedir();
   const slug = cwd.startsWith(home) ? cwd.slice(home.length) : cwd;
@@ -1067,33 +1208,63 @@ function probeHerdrUnit(unit = DEFAULT_HERDR_UNIT): { kind: HerdrLayer; detail?:
   }
 }
 
-function probeOmpPane():
+export function paneLayerFromAgents(
+  agents: HerdrAgent[],
+  agentName: string,
+):
+  | { kind: "live"; summary: string }
+  | { kind: "missing" }
+  | { kind: "unknown"; reason: string } {
+  const matches = agents.filter((agent) => agent.name === agentName);
+  if (matches.length === 0) return { kind: "missing" };
+  if (matches.length > 1) {
+    return { kind: "unknown", reason: `${matches.length} herdr agents named ${agentName}` };
+  }
+  const match = matches[0]!;
+  if (match.agent === "omp") {
+    return { kind: "live", summary: `agent ${agentName} pane ${match.paneId}` };
+  }
+  if (match.agent === undefined || match.agent === "") return { kind: "missing" };
+  return {
+    kind: "unknown",
+    reason: `agent ${agentName} pane ${match.paneId} is ${match.agent}, not omp`,
+  };
+}
+
+function probeOmpPane(
+  projectName?: string,
+):
   | { kind: "live"; summary: string }
   | { kind: "missing" }
   | { kind: "unknown"; reason: string } {
+  const tick = resolveTickConfig(projectName);
+  if (tick.kind === "invalid") {
+    return {
+      kind: "unknown",
+      reason:
+        `tick config invalid at ${tick.path} (${tick.problem}) — ` +
+        "the conductor agent name cannot be read",
+    };
+  }
+  const agentName =
+    tick.kind === "ok" ? (tick.config.agentName ?? DEFAULT_FLEET_AGENT_NAME) : DEFAULT_FLEET_AGENT_NAME;
+  const session = process.env["HERDR_SESSION"] ?? "fleet";
   try {
-    const res = spawnSync("pgrep", ["-af", String.raw`bun .*/omp( |$)`], {
+    const res = spawnSync("herdr", ["--session", session, "agent", "list"], {
       encoding: "utf8",
-      timeout: 5_000,
+      timeout: 8_000,
       env: process.env,
     });
     if (res.error) {
       const err = res.error as NodeJS.ErrnoException;
-      if (err.code === "ENOENT") return { kind: "unknown", reason: "no pgrep" };
+      if (err.code === "ENOENT") return { kind: "unknown", reason: "no herdr" };
       return { kind: "unknown", reason: err.message };
     }
-    const lines = (res.stdout ?? "")
-      .split("\n")
-      .map((l) => l.trim())
-      .filter((l) => l.length > 0)
-      .filter((l) => !l.includes("omp-conductor"));
-    if (lines.length === 0) return { kind: "missing" };
-    const first = lines[0]!;
-    const summary = first.length > 100 ? `${first.slice(0, 97)}…` : first;
-    return {
-      kind: "live",
-      summary: lines.length === 1 ? summary : `${summary} (+${lines.length - 1} more)`,
-    };
+    if (res.status !== 0) {
+      const detail = (res.stderr ?? res.stdout ?? `herdr exit ${String(res.status)}`).trim();
+      return { kind: "unknown", reason: detail };
+    }
+    return paneLayerFromAgents(parseHerdrAgentList(res.stdout ?? ""), agentName);
   } catch (err) {
     return { kind: "unknown", reason: err instanceof Error ? err.message : String(err) };
   }

package/src/orchestrator-tick.ts

@@ -41,7 +41,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 import { findProject, loadConfig } from "./config.ts";
 import {
@@ -107,6 +107,43 @@ export const STALL_TICKS = 2;
  */
 export const TICK_REQUESTED_FILE = ".conductor-tick-requested";
 
+/** Runtime heartbeat schedule consumed by `omp-conductor status`. */
+export const TICK_STATUS_FILE = ".conductor-tick-status.json";
+
+export interface TickRuntimeStatus {
+  pid: number;
+  intervalSeconds: number;
+  nextTickAt: string;
+}
+
+export function readTickRuntimeStatus(cwd: string): TickRuntimeStatus | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(join(cwd, TICK_STATUS_FILE), "utf8"));
+  } catch {
+    return undefined;
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+  const row = parsed as Record<string, unknown>;
+  if (
+    typeof row["pid"] !== "number" ||
+    !Number.isInteger(row["pid"]) ||
+    row["pid"] <= 1 ||
+    typeof row["intervalSeconds"] !== "number" ||
+    !Number.isInteger(row["intervalSeconds"]) ||
+    row["intervalSeconds"] < MIN_INTERVAL_SECONDS ||
+    typeof row["nextTickAt"] !== "string" ||
+    !Number.isFinite(Date.parse(row["nextTickAt"]))
+  ) {
+    return undefined;
+  }
+  return {
+    pid: row["pid"],
+    intervalSeconds: row["intervalSeconds"],
+    nextTickAt: row["nextTickAt"],
+  };
+}
+
 /**
  * The marker's one line after its ISO timestamp, and the middle of the error
  * log. Shared so the file and the log can never describe different failures.
@@ -971,6 +1008,23 @@ function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSe
   clearTickRequest(pi, ctx.cwd);
 }
 
+function writeTickRuntimeStatus(pi: TickApi, cwd: string, intervalSeconds: number): void {
+  const path = join(cwd, TICK_STATUS_FILE);
+  const tmp = `${path}.${process.pid}.tmp`;
+  const status: TickRuntimeStatus = {
+    pid: process.pid,
+    intervalSeconds,
+    nextTickAt: new Date(Date.now() + intervalSeconds * 1000).toISOString(),
+  };
+  try {
+    writeFileSync(tmp, `${JSON.stringify(status)}\n`);
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    pi.logger.error(`[omp-conductor] could not write ${path}: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 /**
  * Arm the interval heartbeat, then honour a recover poke if one is waiting.
  * Extracted so the ownership-retry path and the immediate-accept path cannot
@@ -978,7 +1032,14 @@ function tick(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSe
  * behaviour.
  */
 function armTickHeartbeat(pi: TickApi, ctx: TickContext, config: TickConfig, session: TickSession): void {
-  ctx.setInterval(() => tick(pi, ctx, config, session), config.intervalSeconds * 1000);
+  writeTickRuntimeStatus(pi, ctx.cwd, config.intervalSeconds);
+  ctx.setInterval(() => {
+    try {
+      tick(pi, ctx, config, session);
+    } finally {
+      writeTickRuntimeStatus(pi, ctx.cwd, config.intervalSeconds);
+    }
+  }, config.intervalSeconds * 1000);
   if (!existsSync(join(ctx.cwd, TICK_REQUESTED_FILE))) return;
   pi.logger.info("[omp-conductor] tick requested by recover — firing without waiting for the interval");
   tick(pi, ctx, config, session);