omp-conductor 0.3.16 → 0.3.18

package/README.md

@@ -39,7 +39,7 @@ The package ships three deployables, plus two skills:
 | 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 npm and Herdr plugins as one maintenance operation: drain, halt, replace both halves, restart, re-arm through Telegram proof, and verify twice. See [Updating](#updating). |
+| 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
@@ -169,15 +169,20 @@ Also required on the host:
 ## Updating
 
 Say “update conductor” from an operator shell or maintenance omp session outside
-the target `herdr-fleet.service`. The bundled `skill://conductor-update` discovers
-the installed and registry versions, drains active work, pins exact-pane recovery,
-replaces both independently installed plugins, restarts through
-`omp-conductor start`, re-arms through the existing Telegram proof, and verifies
-the layered status twice.
-
-The skill deliberately does not publish npm or edit an install root. It also
-refuses to run from the fleet pane it must replace: an updater that kills itself
-cannot verify the result. With skill commands enabled, invoke it directly with:
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.3.16",
+  "version": "0.3.18",
   "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/skills/conductor-update/SKILL.md

@@ -1,157 +1,179 @@
 ---
 name: conductor-update
-description: Safely update an installed omp-conductor fleet as one maintenance operation across both separately installed halves: the npm omp plugin and the GitHub herdr-conductor plugin. Use when the user asks to update, upgrade, refresh, reinstall, or deploy a newly published conductor version, or when installed conductor code is behind npm/main. Quiesces work, preserves exact pane identity, performs a whole-version swap, restarts through the supported lifecycle, re-arms through Telegram proof, and verifies the live fleet.
+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
 
-Treat an update as one operation across two independently installed plugins:
+The operator interface is one request: **“update conductor.”** Do not hand them
+the implementation as a checklist unless execution is blocked.
 
-- `omp-conductor` comes from npm and owns dispatch, CLI, status, and heartbeat.
-- `herdr-conductor` comes from `TerrifiedBug/conductor/herdr` and owns exact-pane recovery.
+One release has three installed surfaces:
 
-Updating only one half can leave a version that starts but cannot recover correctly.
-This skill updates an installed fleet. It does **not** publish npm, merge a PR, tag a
-release, or edit files in an install directory.
+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 this procedure from an operator shell or maintenance omp session that is not
-hosted by the target `herdr-fleet.service`. If the current working directory
-contains `.conductor-tick.json`, or stopping that unit would kill the session
-executing this skill, stop and move the update to an external maintenance
-session. A self-terminating updater cannot produce trustworthy verification.
+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
+```
 
-Use the configured target host. Do not assume a hostname, state directory, Herdr
-session name, project name, or systemd availability. Read them from the existing
-installation and `omp-conductor status`. Never print bot tokens, npm tokens, or
-authentication files.
+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. Establish the desired version
+## 1. Resolve one release and inspect every surface
 
-Read, do not guess:
+Use the registry latest unless the operator names another published version:
 
 ```bash
-omp-conductor --version
 version=$(npm view omp-conductor version)
 gitHead=$(npm view "omp-conductor@$version" gitHead)
 npm view "omp-conductor@$version" version gitHead --json
-omp plugin list --json
-omp-conductor status [--project NAME]
 ```
 
-Use the registry latest as `$version` unless the user explicitly names another
-published version, then query that exact version as shown. Record its `gitHead`
-and require a full commit SHA: the npm spec and Herdr ref below are both pinned,
-so a concurrent release cannot mix two versions. If npm has no newer version, do
-not churn the fleet: report that it is current. Confirm that `herdr` and
-`systemctl` are present before taking anything down when status says Herdr
-manages the pane.
-
-## 2. Quiesce without losing work
+Require `$version` to be nonempty and `$gitHead` to be a full commit SHA before
+changing state.
 
-First stop new claims and heartbeat prompts:
+Inspect, without mutating:
 
 ```bash
-omp-conductor hold [--project NAME]
+omp-conductor --version
+omp plugin list --json
+herdr --session "$session" plugin list
+omp-conductor status [--project NAME]
 ```
 
-Read status until `active runs (none)`. Do not kill workers to make the update
-faster. If a run does not drain, report the run and stop; ordinary update authority
-does not include discarding work.
+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.
 
-Then stop the exact conductor pane and dispatch daemon through the supported,
-fail-closed path:
+Record:
 
-```bash
-omp-conductor halt --pane [--project NAME]
-```
+- 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.
 
-This writes the recovery pin before stopping the exact configured Herdr agent. If
-identity is invalid, missing, or ambiguous, it refuses rather than killing a guess.
-Do not bypass that refusal with `pkill`.
+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.
 
-When `herdr-fleet.service` is installed, stop it before replacing either plugin:
+## 2. Pause claims and drain
+
+If dispatch was running:
 
 ```bash
-systemctl stop herdr-fleet.service
+omp-conductor pause [--project NAME]
 ```
 
-At this point the daemon is stopped, the pane is stopped, and recovery remains
-pinned. If any of those statements is false, do not modify the install.
+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 both installed halves
+## 3. Replace all three surfaces with the pinned release
 
-Refresh the exact npm version using omp's package installer:
+Use exact versions. A broad `bun update` is prohibited.
 
 ```bash
+bun add -g "omp-conductor@$version"
 omp plugin install "omp-conductor@$version"
 ```
 
-Then refresh the Herdr managed checkout from the exact npm release commit. Herdr
-requires the GitHub source before its options:
+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
 ```
 
-Do not use `git pull`, `scp`, a linked checkout, or edits under either plugin's
-install root. This is a whole-version swap. If either install fails, leave the
-fleet stopped and recovery pinned; report the failed command and do not continue
-with a mixed live version.
+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. Start through the new lifecycle
+## 4. Reload the installed code
 
-Run the newly installed CLI:
+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
-omp-conductor --version
-omp-conductor start [--project NAME]
+systemctl restart herdr-fleet.service
 ```
 
-`start` clears the recovery pin, starts the optional `herdr-fleet.service`, and
-starts the dispatch daemon after a real `/healthz` check. Herdr then recovers the
-exact orchestrator pane and requests an immediate tick; the verification below,
-not the `start` command alone, proves that recovery completed.
+Wait until Herdr reports its unit active and the exact configured agent live.
 
-Wait until `omp-conductor status` reports the exact pane `live`; `start` returning
-only proves the service and dispatch daemon. `hold` deliberately disarmed ticks,
-so restore unattended operation through the existing Telegram proof:
+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 arm [--project NAME]
+omp-conductor restart [--project NAME]
 ```
 
-Wait for the operator's inbound Telegram reply. Never create the arm marker by
-hand and never treat an outbound challenge as proof.
+Do not substitute `start` when the daemon was initially stopped.
 
-## 5. Verify the live result
+## 5. Verify before restoring claims
 
-Require all of the following before reporting success:
+Check every surface again:
 
 ```bash
 omp-conductor --version
-npm view "omp-conductor@$version" version gitHead --json
 omp plugin list --json
-herdr plugin list
+herdr --session "$session" plugin list
 omp-conductor status [--project NAME]
 systemctl is-active herdr-fleet.service
 ```
 
-- installed version and the npm package entry both equal `$version`;
-- the Herdr plugin source revision equals the npm release `gitHead`;
-- `dispatch` is `running`;
-- `ticks` is `armed` and a next tick is shown;
-- `pane` is `live` for the exact configured Herdr agent;
-- `recovery` is `clear`;
-- `herdr` is `active` when managed;
-- Telegram is `ok` (or its exact supported degraded state is reported);
-- daemon `/healthz` is `ok`;
-- no unexpected active runs appeared during maintenance.
-
-Run a second status check after the immediate recovery tick is consumed. A single
-healthy snapshot is not proof that recovery and heartbeat scheduling survived the
-swap.
-
-Report the old and new versions, both plugin refreshes, the final layered status,
-and any supported degraded state. Do not report success for a partial update.
+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/tracker/github.ts

@@ -53,6 +53,12 @@ const CLOSERS_QUERY = `query($owner:String!,$repo:String!,$n:Int!){
   }
 }`;
 
+const PARENT_QUERY = `query($owner:String!,$repo:String!,$n:Int!){
+  repository(owner:$owner,name:$repo){
+    issue(number:$n){ parent{ number } }
+  }
+}`;
+
 /** The `gh api graphql` envelope for {@link CLOSERS_QUERY}. Every level is
  *  nullable: a deleted or wrong-numbered issue answers `null`, not an error. */
 interface ClosersResponse {
@@ -190,27 +196,30 @@ export function prStateFrom(raw: string): PrState | undefined {
 }
 
 /**
- * Parent number from a `gh issue view --json parent` payload, or undefined
- * when the issue has no parent. Throws on a payload that claims a parent but
- * does not carry a usable number — admission would otherwise treat garbage as
- * "no parent" and skip the epic soft-cap.
+ * Parent number from a raw GraphQL response, or undefined when the issue has
+ * no parent. Throws when the issue or claimed parent is malformed — admission
+ * must not turn an unknown relationship into permission to run siblings.
  */
 export function parentNumberFrom(raw: string): number | undefined {
-  const parsed = JSON.parse(raw) as { parent: { number?: unknown } | null };
-  if (parsed.parent == null) return undefined;
-  const n = parsed.parent.number;
+  const parsed = JSON.parse(raw) as {
+    data?: { repository?: { issue?: { parent?: { number?: unknown } | null } | null } | null };
+  };
+  const issue = parsed.data?.repository?.issue;
+  if (issue == null) throw new Error("unexpected missing issue in parent response");
+  if (issue.parent == null) return undefined;
+  const n = issue.parent.number;
   if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
     throw new Error(`unexpected parent number ${JSON.stringify(n)}`);
   }
   return n;
 }
 
-export function makeTracker(p: ProjectConfig): Tracker {
+export function makeTracker(p: ProjectConfig, runGh: typeof gh = gh): Tracker {
   const repo = p.tracker.repo;
 
   return {
     async listReady(): Promise<ReadyIssue[]> {
-      const raw = await gh([
+      const raw = await runGh([
         "issue",
         "list",
         "--repo",
@@ -246,7 +255,7 @@ export function makeTracker(p: ProjectConfig): Tracker {
 
     async addLabel(issue: number, label: string): Promise<void> {
       try {
-        await gh(["issue", "edit", String(issue), "--repo", repo, "--add-label", label]);
+        await runGh(["issue", "edit", String(issue), "--repo", repo, "--add-label", label]);
       } catch (err) {
         if (!isLabelNoop(err, "add")) throw err;
       }
@@ -254,7 +263,7 @@ export function makeTracker(p: ProjectConfig): Tracker {
 
     async removeLabel(issue: number, label: string): Promise<void> {
       try {
-        await gh(["issue", "edit", String(issue), "--repo", repo, "--remove-label", label]);
+        await runGh(["issue", "edit", String(issue), "--repo", repo, "--remove-label", label]);
       } catch (err) {
         if (!isLabelNoop(err, "remove")) throw err;
       }
@@ -263,25 +272,37 @@ export function makeTracker(p: ProjectConfig): Tracker {
     async comment(issue: number, body: string): Promise<void> {
       // `--body-file -` reads stdin, so the body is never shell- or argv-
       // mangled and has no length limit worth worrying about.
-      await gh(["issue", "comment", String(issue), "--repo", repo, "--body-file", "-"], body);
+      await runGh(["issue", "comment", String(issue), "--repo", repo, "--body-file", "-"], body);
     },
 
     async close(issue: number): Promise<void> {
-      await gh(["issue", "close", String(issue), "--repo", repo]);
+      await runGh(["issue", "close", String(issue), "--repo", repo]);
     },
 
     async linkParent(child: number, parent: number): Promise<void> {
       // Native sub-issue linkage rather than a body mention: it is what the
       // repo's own epic rollups read, so a human sees the split without us
       // maintaining a second index of it.
-      await gh(["issue", "edit", String(parent), "--repo", repo, "--add-sub-issue", String(child)]);
+      await runGh(["issue", "edit", String(parent), "--repo", repo, "--add-sub-issue", String(child)]);
     },
 
     async parentOf(issue: number): Promise<number | undefined> {
-      // Native sub-issue parent, not a body scrape. Verified on gh 2.97.0:
-      // `parent` is null with no link, otherwise `{ number, title, url, ... }`.
+      // gh 2.86 cannot expose `parent` through `issue view --json`; its raw
+      // GraphQL command can, and is already the adapter's path for PR closers.
+      const [owner = "", name = ""] = repo.split("/");
       return parentNumberFrom(
-        await gh(["issue", "view", String(issue), "--repo", repo, "--json", "parent"]),
+        await runGh([
+          "api",
+          "graphql",
+          "-f",
+          `query=${PARENT_QUERY}`,
+          "-F",
+          `owner=${owner}`,
+          "-F",
+          `repo=${name}`,
+          "-F",
+          `n=${issue}`,
+        ]),
       );
     },
 
@@ -290,7 +311,7 @@ export function makeTracker(p: ProjectConfig): Tracker {
       // that spelling, so an empty half means a hand-edited config: `gh` then
       // errors and the caller holds the candidate rather than guessing.
       const [owner = "", name = ""] = repo.split("/");
-      const raw = await gh([
+      const raw = await runGh([
         "api",
         "graphql",
         "-f",
@@ -316,7 +337,7 @@ export function makeTracker(p: ProjectConfig): Tracker {
       // what the URL already says.
       if (!PR_URL.test(url)) return undefined;
       try {
-        return prStateFrom(await gh(["pr", "view", url, "--json", "state", "--jq", ".state"]));
+        return prStateFrom(await runGh(["pr", "view", url, "--json", "state", "--jq", ".state"]));
       } catch {
         // Never throws, per the port's contract. A deleted PR, a revoked token
         // and a flaky network all mean "could not tell", and the caller's whole