omp-conductor 0.3.19 → 0.3.21

package/README.md

@@ -194,12 +194,17 @@ or installation, so an operator cannot drain one queue and kill another queue's
 workers.
 
 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 command never publishes npm, edits an install
-root, or delegates lifecycle steps to an AI session. It refuses to run inside a
-Herdr-managed session because an updater that restarts itself cannot verify the
-result.
+does not halt the exact pane or require another Telegram arm challenge. Progress
+names the Bun-global CLI, omp plugin, Herdr plugin, brief, reloads, and both
+verification passes separately.
+
+An installation, brief, reload, or verification failure pauses dispatch and
+attempts to restore the exact CLI/plugin identities that were present before the
+command. If rollback also fails, the error names every failed restoration and
+keeps dispatch paused; it never brings a known mixed fleet back into service.
+The command never publishes npm, edits an install root, or delegates lifecycle
+steps to an AI session. It refuses to run inside a Herdr-managed session because
+an updater that restarts itself cannot verify the result.
 
 The bundled `skill://conductor-update` remains available as a natural-language
 entry point, but it only runs this command; the lifecycle is implemented and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.3.19",
+  "version": "0.3.21",
   "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-onboarding/SKILL.md

@@ -121,24 +121,37 @@ any agent is: it is long-lived, it can see everything that merged since the last
 release, and batching is exactly the judgement a per-issue session cannot make.
 
 So frame it as **three** options, in this order, and name the default. Each one
-maps to an `authority` answer the wizard asks for directly — the interview
-decides *which answer to give*, and `/conductor setup` is what records it. Never
-write authority into the brief by hand: the config is what words the brief, and
-a hand-edit is a second source that outlives the operator's memory of making it.
+maps to two independent wizard answers:
+
+- `authority.release` says **who owns the release decision**;
+- `releasePolicy` is the mechanical tool gate that says whether release-shaped
+  commands may run at all.
+
+The interview decides both answers, and `/conductor setup` records them. Never
+write either value into the brief or hand-edit `config.json`: config is the
+single source, and the wizard's dry run is where the operator sees the combined
+grant.
 
 1. **Humans release.** *(default, and what the package ships)* Work ends at a
-   green PR. Merging is a separate human action; releasing is a separate human
-   action after that. Neither a worker nor the orchestrator ever tags, pins,
-   publishes, or deploys. "This needs releasing" becomes something the
-   orchestrator *reports*. → `authority: merge=human, release=human`; answer
-   **no** to both wizard confirms.
-2. **The orchestrator releases up to a named boundary.** Delegating part of the
-   release to the supervising session, with the stopping line written down.
-   → usually `merge=orchestrator, release=orchestrator`, with the boundary in
-   the procedure rather than in the grant; `merge=orchestrator, release=human`
-   when the line falls before the tag.
-3. **The orchestrator releases fully.** → `merge=orchestrator,
-   release=orchestrator`.
+   green PR. Merging is a separate decision; releasing is a separate human
+   action. Neither a worker nor the orchestrator tags, pins, publishes, or
+   deploys. "This needs releasing" becomes something the orchestrator reports.
+   → `authority.release=human`, `releasePolicy=none`; answer **no** to both
+   release confirms.
+2. **The orchestrator releases up to a named boundary.** Delegate release
+   authority only when its leg includes the first release action (for example,
+   creating a tag or dispatching a release workflow). → usually
+   `authority.release=orchestrator`, `releasePolicy=operator-brief`, with the
+   boundary in the procedure rather than in the grant. If its leg ends before
+   that action, use `authority.release=human`, `releasePolicy=none`.
+3. **The orchestrator releases fully.** →
+   `authority.release=orchestrator`, `releasePolicy=operator-brief`.
+
+Merge authority is its own confirm in every option. Also say what opening the
+tool gate means: it is project-wide and is passed to worker sessions as well as
+the orchestrator. It does not grant workers release authority — their brief
+still stops them at a green PR — but it removes the mechanical block. Never open
+it until the operator has reviewed the release procedure and stopping boundary.
 
 Then ask the question that makes option 2 real:
 
@@ -443,12 +456,15 @@ PR URL, an issue number, or a named check actually read.* "Should be fine",
 "looks green" and "probably passing" are not evidence.
 
 Know what is *not* up there, though, because operators expect it to be: the
-orchestrator's own merge and release authority is **not** a hard boundary. It is
-config — the two `authority` answers — and it defaults to none. What is fixed
-above the banner is that a *worker* never merges or releases, and that PRs land
-one at a time with a freshness re-check. Delegating a release to the
-orchestrator does not touch either of those, so it needs no negotiation with the
-shipped half.
+orchestrator's merge and release authority is **not** a hard boundary. It comes
+from the two `authority` answers in config. Release execution has a second,
+independent config control: `releasePolicy=none` mechanically blocks tags,
+publishing, releases, and deploy commands even when
+`authority.release=orchestrator`; `operator-brief` opens that gate for the
+reviewed procedure. What is fixed above the banner is that a *worker* never
+merges or releases, and that PRs land one at a time with a freshness re-check.
+Changing either release control needs no negotiation with the shipped half, but
+both must agree with the procedure below the banner.
 
 **Below the banner — rewrite from the interview.**
 
@@ -552,9 +568,11 @@ label; whether to rename the state labels; routing label prefix; then per repo t
 routing key, clone URL, default branch and **pre-push gates** (your Step 2
 proposal, in `cmd @ cwd` form); whether to add another repo; whether to set up
 **code-graph discovery** and the root its clones live under (Step 8); caps; the
-authority confirms; the worker model; the Telegram chat id for tier 2; the
-escalation fallback; whether an orchestrator session already runs elsewhere; the
-report scope; and finally whether to write `ORCHESTRATOR.md` + `POLICY.md`.
+merge and release authority confirms; the independent **Release tool gate**
+confirm (`none` or `operator-brief`); the worker model; the Telegram chat id for
+tier 2; the escalation fallback; whether an orchestrator session already runs
+elsewhere; the report scope; and finally whether to write `ORCHESTRATOR.md` +
+`POLICY.md`.
 
 The end of the wizard is load-bearing:
 
@@ -565,6 +583,12 @@ The end of the wizard is load-bearing:
 - **Nothing changes before consent.** Setup creates no label, file, database, or
   arm marker before the operator agrees. Never answer that consent prompt for
   the operator.
+- **Review authority and gate together.** If the procedure assigns tags,
+  publishing, release creation, or deploy commands to the orchestrator, the dry
+  run must show both `release=orchestrator` and
+  `releasePolicy=operator-brief`. `release=orchestrator` with
+  `releasePolicy=none` assigns the job while mechanically preventing it. A
+  human-owned release should normally remain `releasePolicy=none`.
 - **The host plan is part of consent.** For an external orchestrator, setup names
   the heartbeat file and both safety gates. It also names the staged systemd
   unit. An invalid existing heartbeat stops setup before any write.

package/src/cli.ts

@@ -394,10 +394,12 @@ try {
         project: flag(argv, "project"),
       });
       process.stdout.write(
-        result.alreadyCurrent
-          ? `conductor ${result.version} already current on all three surfaces\n`
-          : `upgraded conductor ${result.previousVersion} → ${result.version} (${result.gitHead})\n` +
-              `dispatch ${result.dispatch} restored\n`,
+        `${result.alreadyCurrent ? "already current" : "upgrade complete"}:\n` +
+          `  Bun-global CLI     omp-conductor@${result.version}\n` +
+          `  omp plugin         omp-conductor@${result.version}\n` +
+          `  Herdr plugin       herdr-conductor@${result.gitHead}\n` +
+          `  orchestrator brief managed ORCHESTRATOR.md floor current; POLICY.md preserved\n` +
+          `  dispatch           ${result.dispatch}${result.alreadyCurrent ? "" : " restored"}\n`,
       );
       break;
     }

package/src/upgrade.ts

@@ -125,33 +125,55 @@ function parseRegistry(raw: string): { version: string; gitHead: string } {
 }
 
 function ompPluginVersion(raw: string): string | undefined {
+  let parsed: unknown;
   try {
-    const parsed = JSON.parse(raw) as { npm?: Array<{ name?: unknown; version?: unknown }> };
-    const plugin = parsed.npm?.find((entry) => entry.name === PACKAGE);
-    return typeof plugin?.version === "string" ? plugin.version : undefined;
+    parsed = JSON.parse(raw);
   } catch {
-    return undefined;
+    throw new Error("omp plugin list returned invalid JSON");
   }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("omp plugin list returned an invalid inventory");
+  }
+  const npm = Reflect.get(parsed, "npm");
+  if (!Array.isArray(npm)) throw new Error("omp plugin list returned no npm inventory");
+  const plugin = npm.find(
+    (entry) => entry !== null && typeof entry === "object" && Reflect.get(entry, "name") === PACKAGE,
+  );
+  if (plugin === undefined) return undefined;
+  const version = Reflect.get(plugin, "version");
+  if (typeof version !== "string" || version.length === 0) {
+    throw new Error("installed omp-conductor plugin has no version");
+  }
+  return version;
 }
 
 function herdrPluginSource(raw: string): string | undefined {
   const line = raw.split("\n").find((candidate) => /^- herdr-conductor\b/.test(candidate.trim()));
-  return line?.match(/\[([^\]]+)\]\s*$/)?.[1];
+  if (line === undefined) return undefined;
+  const source = line.match(/\[([^\]]+)\]\s*$/)?.[1];
+  if (source === undefined) {
+    throw new Error("cannot determine installed Herdr plugin source");
+  }
+  return source;
 }
 
-async function inspectSurfaces(deps: UpgradeDeps): Promise<{
+interface InstalledSurfaces {
   cliVersion: string;
   ompVersion?: string;
   herdrSource?: string;
-}> {
+}
+
+async function inspectSurfaces(deps: UpgradeDeps): Promise<InstalledSurfaces> {
   const session = deps.env["HERDR_SESSION"] || "fleet";
   const [cli, omp, herdr] = await Promise.all([
     mustRun(deps, "omp-conductor", ["--version"]),
     mustRun(deps, "omp", ["plugin", "list", "--json"]),
     mustRun(deps, "herdr", ["--session", session, "plugin", "list"]),
   ]);
+  const cliVersion = cli.stdout.trim();
+  if (cliVersion.length === 0) throw new Error("installed omp-conductor CLI has no version");
   return {
-    cliVersion: cli.stdout.trim(),
+    cliVersion,
     ompVersion: ompPluginVersion(omp.stdout),
     herdrSource: herdrPluginSource(herdr.stdout),
   };
@@ -173,6 +195,19 @@ function surfacesCurrent(
   );
 }
 
+function previousHerdrInstall(source: string): readonly [string, readonly string[]] | undefined {
+  if (source.startsWith("local:")) {
+    return ["herdr", ["plugin", "link", source.slice("local:".length), "--enabled"]];
+  }
+  if (!source.startsWith("github:")) return undefined;
+  const at = source.lastIndexOf("@");
+  if (at < "github:".length) return undefined;
+  return [
+    "herdr",
+    ["plugin", "install", source.slice("github:".length, at), "--ref", source.slice(at + 1), "--yes"],
+  ];
+}
+
 async function waitForDrain(deps: UpgradeDeps, project?: string): Promise<void> {
   let last = -1;
   while (true) {
@@ -230,6 +265,122 @@ async function upgradeBrief(
   await mustRun(deps, "omp-conductor", ["brief-upgrade", "--migrate", "--apply", ...selected]);
 }
 
+async function rollbackUpgrade(
+  deps: UpgradeDeps,
+  previous: InstalledSurfaces,
+  project: string | undefined,
+  installTouched: boolean,
+  briefChanged: boolean,
+  herdrReloadStarted: boolean,
+  daemonReloadStarted: boolean,
+): Promise<void> {
+  const failures: string[] = [];
+  const restore = async (label: string, command: string, args: readonly string[]): Promise<void> => {
+    deps.log(`rollback: ${label}`);
+    try {
+      await mustRun(deps, command, args);
+    } catch (err) {
+      failures.push(err instanceof Error ? err.message : String(err));
+    }
+  };
+  const removeIfPresent = async (
+    label: string,
+    command: string,
+    args: readonly string[],
+  ): Promise<void> => {
+    deps.log(`rollback: ${label}`);
+    try {
+      await deps.run(command, args);
+    } catch {
+      // Exact post-rollback identity verification decides whether absence is safe.
+    }
+  };
+
+  if (installTouched) {
+    await restore("Bun-global omp-conductor CLI", "bun", [
+      "add",
+      "-g",
+      `${PACKAGE}@${previous.cliVersion}`,
+    ]);
+    if (previous.ompVersion === undefined) {
+      await removeIfPresent("remove newly installed omp plugin", "omp", [
+        "plugin",
+        "uninstall",
+        PACKAGE,
+      ]);
+    } else {
+      await restore("omp plugin omp-conductor", "omp", [
+        "plugin",
+        "install",
+        `${PACKAGE}@${previous.ompVersion}`,
+      ]);
+    }
+
+    if (previous.herdrSource === undefined) {
+      await removeIfPresent("remove newly installed Herdr plugin", "herdr", [
+        "plugin",
+        "uninstall",
+        HERDR_PLUGIN,
+      ]);
+    } else {
+      const install = previousHerdrInstall(previous.herdrSource);
+      if (install === undefined) {
+        failures.push(`cannot restore unknown Herdr source ${previous.herdrSource}`);
+      } else {
+        if (previous.herdrSource.startsWith("local:")) {
+          await removeIfPresent("remove managed Herdr plugin", "herdr", [
+            "plugin",
+            "uninstall",
+            HERDR_PLUGIN,
+          ]);
+        }
+        await restore("Herdr plugin herdr-conductor", install[0], install[1]);
+      }
+    }
+
+  }
+  if (briefChanged) {
+    try {
+      deps.log("rollback: ORCHESTRATOR.md package floor");
+      await upgradeBrief(deps, "overlay", project);
+    } catch (err) {
+      failures.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  if (herdrReloadStarted) {
+    await restore("restart herdr-fleet.service", "systemctl", ["restart", HERDR_UNIT]);
+  }
+  if (daemonReloadStarted) {
+    try {
+      deps.log("rollback: restart omp-conductor dispatch daemon");
+      await deps.restartDaemon();
+    } catch (err) {
+      failures.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  if (installTouched) {
+    try {
+      const restored = await inspectSurfaces(deps);
+      if (
+        restored.cliVersion !== previous.cliVersion ||
+        restored.ompVersion !== previous.ompVersion ||
+        restored.herdrSource !== previous.herdrSource
+      ) {
+        failures.push(
+          `restored identities differ: cli=${restored.cliVersion}, omp=${restored.ompVersion ?? "missing"}, ` +
+            `herdr=${restored.herdrSource ?? "missing"}`,
+        );
+      }
+    } catch (err) {
+      failures.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+
+  if (failures.length > 0) throw new Error(failures.join("; "));
+}
+
 export async function upgradeConductor(
   options: UpgradeOptions = {},
   overrides: Partial<UpgradeDeps> = {},
@@ -268,54 +419,113 @@ export async function upgradeConductor(
   if (brief.kind === "missing") throw new Error("no ORCHESTRATOR.md exists for the configured project");
   if (initial.herdr === "unknown") throw new Error("cannot determine whether herdr-fleet.service is active");
 
-  if (initial.dispatch === "running") deps.setPaused(true);
-  await waitForDrain(deps, project);
-
-  deps.log(`upgrading conductor ${surfaces.cliVersion} → ${release.version}`);
-  if (installNeeded) {
-    await mustRun(deps, "bun", ["add", "-g", `${PACKAGE}@${release.version}`]);
-    await mustRun(deps, "omp", ["plugin", "install", `${PACKAGE}@${release.version}`]);
-    if (surfaces.herdrSource?.startsWith("local:")) {
-      await mustRun(deps, "herdr", ["plugin", "unlink", HERDR_PLUGIN]);
-    }
-    await mustRun(deps, "herdr", [
-      "plugin",
-      "install",
-      HERDR_SOURCE,
-      "--ref",
-      release.gitHead,
-      "--yes",
-    ]);
+  deps.log(`target release: omp-conductor@${release.version} (${release.gitHead})`);
+  if (!initial.paused) {
+    deps.log("safety: pausing new issue claims");
+    deps.setPaused(true);
   }
-  await upgradeBrief(deps, brief.kind, project);
-
-  if (initial.herdr === "active") {
-    await mustRun(deps, "systemctl", ["restart", HERDR_UNIT]);
-  }
-  if (initial.dispatch !== "stopped") {
-    await deps.restartDaemon();
-  }
-
-  const installed = await inspectSurfaces(deps);
-  if (!surfacesCurrent(installed, release.version, release.gitHead)) {
+  deps.log("drain: waiting for live omp worker sessions");
+  try {
+    await waitForDrain(deps, project);
+  } catch (err) {
+    const failure = err instanceof Error ? err.message : String(err);
     throw new Error(
-      `upgrade verification failed: cli=${installed.cliVersion}, omp=${installed.ompVersion ?? "missing"}, ` +
-        `herdr=${installed.herdrSource ?? "missing"}`,
+      `upgrade failed while draining workers: ${failure}; no installation started; dispatch remains paused`,
     );
   }
-  if (initial.herdr === "active") {
-    const active = await mustRun(deps, "systemctl", ["is-active", HERDR_UNIT]);
-    if (active.stdout.trim() !== "active") throw new Error(`${HERDR_UNIT} is not active after restart`);
-  }
-  await waitForRecovery(deps, initial, project);
-  await deps.sleep(1_000);
-  await waitForRecovery(deps, initial, project);
-
-  if (initial.dispatch === "running") {
-    deps.setPaused(false);
-    if (deps.layers(project).dispatch !== "running") {
-      throw new Error("upgrade installed successfully, but dispatch did not resume");
+  deps.log("drain: complete");
+
+  let installTouched = false;
+  let briefChanged = false;
+  let herdrReloadStarted = false;
+  let daemonReloadStarted = false;
+  try {
+    if (installNeeded) {
+      installTouched = true;
+      deps.log(`install 1/3: Bun-global omp-conductor CLI → ${release.version}`);
+      await mustRun(deps, "bun", ["add", "-g", `${PACKAGE}@${release.version}`]);
+      deps.log(`install 2/3: omp plugin omp-conductor → ${release.version}`);
+      await mustRun(deps, "omp", ["plugin", "install", `${PACKAGE}@${release.version}`]);
+      if (surfaces.herdrSource?.startsWith("local:")) {
+        await mustRun(deps, "herdr", ["plugin", "unlink", HERDR_PLUGIN]);
+      }
+      deps.log(`install 3/3: Herdr plugin herdr-conductor → ${release.gitHead}`);
+      await mustRun(deps, "herdr", [
+        "plugin",
+        "install",
+        HERDR_SOURCE,
+        "--ref",
+        release.gitHead,
+        "--yes",
+      ]);
+    } else {
+      deps.log("install: CLI, omp plugin, and Herdr plugin already pinned to the target release");
+    }
+
+    deps.log("brief: refreshing managed ORCHESTRATOR.md floor while preserving POLICY.md");
+    briefChanged = true;
+    await upgradeBrief(deps, brief.kind, project);
+
+    if (initial.herdr === "active") {
+      herdrReloadStarted = true;
+      deps.log("reload: restarting herdr-fleet.service and recovering the orchestrator pane");
+      await mustRun(deps, "systemctl", ["restart", HERDR_UNIT]);
+    }
+    if (initial.dispatch !== "stopped") {
+      daemonReloadStarted = true;
+      deps.log("reload: restarting the omp-conductor dispatch daemon");
+      await deps.restartDaemon();
+    }
+
+    deps.log("verify 1/2: package identities, services, pane, ticks, and paused dispatch");
+    const installed = await inspectSurfaces(deps);
+    if (!surfacesCurrent(installed, release.version, release.gitHead)) {
+      throw new Error(
+        `installed identities differ: cli=${installed.cliVersion}, omp=${installed.ompVersion ?? "missing"}, ` +
+          `herdr=${installed.herdrSource ?? "missing"}`,
+      );
+    }
+    if (initial.herdr === "active") {
+      const active = await mustRun(deps, "systemctl", ["is-active", HERDR_UNIT]);
+      if (active.stdout.trim() !== "active") throw new Error(`${HERDR_UNIT} is not active after restart`);
+    }
+    await waitForRecovery(deps, initial, project);
+    deps.log("verify 2/2: recovered fleet remains stable");
+    await deps.sleep(1_000);
+    await waitForRecovery(deps, initial, project);
+
+    if (!initial.paused) deps.setPaused(false);
+    const restoredDispatch = deps.layers(project).dispatch;
+    if (restoredDispatch !== initial.dispatch) {
+      throw new Error(
+        `dispatch state is ${restoredDispatch}; expected to restore ${initial.dispatch}`,
+      );
+    }
+  } catch (err) {
+    try {
+      if (!deps.layers(project).paused) deps.setPaused(true);
+    } catch {
+      deps.setPaused(true);
+    }
+    const failure = err instanceof Error ? err.message : String(err);
+    deps.log(`upgrade failed: ${failure}`);
+    try {
+      await rollbackUpgrade(
+        deps,
+        surfaces,
+        project,
+        installTouched,
+        briefChanged,
+        herdrReloadStarted,
+        daemonReloadStarted,
+      );
+    } catch (rollbackErr) {
+      const rollback = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);
+      throw new Error(
+        `upgrade failed: ${failure}; rollback incomplete: ${rollback}; dispatch remains paused`,
+      );
     }
+    throw new Error(`upgrade failed: ${failure}; previous installation restored; dispatch remains paused`);
   }
 
   return {