omp-conductor 0.4.0 → 0.4.2

package/package.json

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

@@ -513,6 +513,62 @@ lose the substituted coordinates and the overwrite confirmation.
 
 ---
 
+## Step 5b — offer the credential boundary, and be honest about its cost
+
+Ask this once, plainly, because the default is not the safe answer — it is the
+*non-breaking* one:
+
+> Should worker and orchestrator sessions run under their own OS accounts, so a
+> session that goes rogue in bash holds no credential capable of merging,
+> pushing, releasing or reading your `gh` config?
+
+`credentials.isolation` is `none` unless someone says otherwise, and `status`
+reports such a fleet **unprotected** on every tick. That is deliberate: a fleet
+that refuses to dispatch the moment it upgrades is worse than one that is
+honestly unprotected.
+
+Say what it costs before they answer:
+
+- **Linux only** for the real thing. macOS dev hosts get `sandbox-exec`, which
+  is Apple-deprecated but is still the only stock mechanism that denies a *read*.
+- **Root, once**, to create the accounts and groups.
+- **A service restart**, because supplementary group membership is fixed when a
+  process starts.
+- Worktrees and mirrors move to `/var/lib/omp-conductor`. Uninstall becomes two
+  paths instead of one.
+
+If they say yes, the order matters and getting it wrong looks like a bug:
+
+```bash
+omp-conductor boundary-setup --slots <maxConcurrentWorkers>   # read it first
+omp-conductor boundary-setup --slots <maxConcurrentWorkers> | sudo bash
+sudo systemctl restart omp-conductor.service
+```
+
+**Then open a fresh shell before running the wizard.** The setup probe reads its
+*own* process credentials, so a stale login will refuse to offer `per-run` and
+that reads like a broken install rather than an un-refreshed session.
+
+Only then run `/conductor setup` and choose `per-run`. That single amend writes
+the isolation, relocates the roots, and regenerates the systemd unit *with* the
+capabilities the launcher needs — the unit is not optional, and a fleet
+configured `per-run` whose unit lacks them probes down to `group-mode` and
+refuses every issue. Install the unit with the commands the wizard prints, then
+confirm:
+
+```bash
+omp-conductor status     # boundary: per-run — uid-pool
+```
+
+`status` reports the **daemon's** boundary, read from `/healthz`, not a probe of
+whatever shell you are standing in — capabilities belong to the process, and an
+interactive shell has none of the unit's. If no daemon is running it falls back
+to a local probe and says so; that line is not the fleet's answer.
+
+If it says anything else, the reason names the missing capability, group or
+path. Do not guess at it, and never "fix" it by widening the state directory —
+that is where `conductor.db` lives.
+
 ## Step 6 — check the worker brief's assumptions against reality
 
 The worker brief makes concrete claims to a session that has no other context. If

package/skills/conductor-update/SKILL.md

@@ -23,6 +23,33 @@ drain, exact-version installation across the Bun-global CLI, omp plugin, and
 Herdr plugin, managed-brief recomposition, process reload, pane recovery,
 two-pass verification, and restoration of the previous dispatch state.
 
+## When it fails on the systemd unit
+
+Since 0.4.0 the command also verifies the unit systemd actually booted from, not
+just the staged copy. A fleet configured `credentials.isolation: "per-run"`
+whose installed unit predates the capability grant probes down to `group-mode`
+and then refuses every issue — and package identities, services, pane and ticks
+all look perfectly healthy around it, which is why it needed its own check.
+
+The error names the missing directives. Fix it by re-staging rather than by
+hand-editing the live unit:
+
+```bash
+# in an omp session
+/conductor setup            # amend nothing; it re-renders the unit
+# then run the install commands it prints, and:
+sudo systemctl daemon-reload && sudo systemctl restart omp-conductor.service
+omp-conductor upgrade       # re-run; it now verifies clean
+```
+
+Only directives this configuration *requires* are checked, so an operator's own
+`MemoryMax`, `After=` or extra `Environment=` never fails an upgrade.
+
+What the command deliberately does **not** do is create the accounts and groups
+the boundary needs. That is `omp-conductor boundary-setup`, it needs root, and
+the daemon runs unprivileged on purpose — so it detects and instructs rather
+than escalating.
+
 Report the command's result. Do not reproduce its lifecycle as an AI checklist,
 edit installed files, publish npm, or substitute separate install/restart steps.
 If it fails, report the exact error and leave dispatch paused as the command

package/src/config.ts

@@ -219,6 +219,18 @@ export function loadConfig(): ConductorConfig {
  * a truncated one. Mode 0600 because a config carries chat ids and clone URLs.
  */
 export function saveConfig(c: ConductorConfig): void {
+  writeConfigFile(c);
+}
+
+/**
+ * Atomic write of whatever object is handed in.
+ *
+ * Takes `unknown` rather than `ConductorConfig` so the credentials migration
+ * can persist the operator's own parsed file with one key added, instead of a
+ * value that has been through the loader and back out. That round-trip is what
+ * rewrote a live fleet's config into a dialect the previous release rejected.
+ */
+export function writeConfigFile(c: unknown): void {
   const dir = stateDir();
   const created = mkdirSync(dir, { recursive: true, mode: 0o700 });
   // mkdir's mode is masked by umask; chmod only what we just created so an
@@ -931,9 +943,39 @@ export function migrateCredentialsOnDisk(): { migrated: string[]; path: string }
   }
   const migrated = projectsMissingCredentials(parsed);
   if (migrated.length === 0) return { migrated: [], path };
-  // Through the loader and back out, so the rewrite is the same normalisation
-  // every other key already gets rather than a second, divergent writer.
-  saveConfig(loadConfig());
+
+  // A SURGICAL edit: add the one missing key to the projects that lack it and
+  // leave every other byte exactly as the operator wrote it.
+  //
+  // This was `saveConfig(loadConfig())` once, and that round-trip took a live
+  // fleet down. Normalising on the way out rewrites the whole file into the
+  // current dialect — `defaults.planUsage`, `releasePolicy` as a per-shape map
+  // — and the previous release rejects both. The daemon performing the
+  // migration is started *by* an upgrade still running the previous CLI, so
+  // that CLI's next `loadConfig` failed, and its rollback reinstalled a version
+  // which then could not read the file either. A migration must never make a
+  // config unreadable by the release you may have to roll back to.
+  // Verified against the real previous release, not just against this parser:
+  // omp-conductor@0.3.25 loads a config carrying `credentials` and prints
+  // `status` normally, because it ignores unknown *project* keys while
+  // rejecting unknown `defaults` keys and a non-string `releasePolicy` — the
+  // two things the old round-trip wrote. Re-check that with `npm install
+  // omp-conductor@<previous>` before widening what this writes.
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return { migrated: [], path };
+  const projects = (parsed as Raw)["projects"];
+  if (!Array.isArray(projects)) return { migrated: [], path };
+  for (const entry of projects) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) continue;
+    const raw = entry as Raw;
+    const credentials = raw["credentials"];
+    const explicit =
+      typeof credentials === "object" &&
+      credentials !== null &&
+      !Array.isArray(credentials) &&
+      (credentials as Raw)["isolation"] !== undefined;
+    if (!explicit) (raw as Record<string, unknown>)["credentials"] = { isolation: "none" };
+  }
+  writeConfigFile(parsed);
   return { migrated, path };
 }
 

package/src/daemon.ts

@@ -60,7 +60,7 @@ import type {
   Tracker,
   VerbLedgerEntry,
 } from "./types.ts";
-import { CONDUCTOR_GROUPS } from "./types.ts";
+import { CONDUCTOR_GROUPS, type IsolationMechanism } from "./types.ts";
 import { type KilledBy, type WorkerResult, renderBrief, runWorker } from "./worker.ts";
 import {
   addRunRepo,
@@ -2353,6 +2353,20 @@ export interface DaemonHealthSnapshot {
   rssBytes: number;
   dispatch?: DispatchSummary;
   codeGraph?: CodeGraphHealth;
+  /**
+   * The boundary THIS daemon resolved at startup.
+   *
+   * Published because capabilities are a property of the process, not the host:
+   * `omp-conductor status` runs in an interactive shell with none of the unit's
+   * ambient capabilities and no conductor groups, so re-probing there reports
+   * `group-mode` on a fleet that is genuinely `uid-pool`. The operator's
+   * verification step would say the boundary failed while it was working.
+   *
+   * It is also the only answer that survives a `daemon-reload` without a
+   * restart: the config on disk can say anything, this is what the running
+   * process actually got.
+   */
+  boundary?: { isolation: CredentialIsolation; mechanism: IsolationMechanism; headline: string };
 }
 
 export function daemonHealthSnapshot(
@@ -2361,6 +2375,7 @@ export function daemonHealthSnapshot(
   paused = isPaused(),
   rssBytes = process.memoryUsage().rss,
   codeGraph?: CodeGraphHealth,
+  boundary?: DaemonHealthSnapshot["boundary"],
 ): DaemonHealthSnapshot {
   const dispatch = store.latestDispatch(project);
   return {
@@ -2371,6 +2386,7 @@ export function daemonHealthSnapshot(
     rssBytes,
     ...(dispatch === undefined ? {} : { dispatch }),
     ...(codeGraph?.configured === true ? { codeGraph } : {}),
+    ...(boundary === undefined ? {} : { boundary }),
   };
 }
 
@@ -3174,7 +3190,12 @@ export async function runDaemon(o: DaemonOpts = {}): Promise<void> {
         project: project.name,
         store,
         turnLimits,
-        health: () => daemonHealthSnapshot(store, project.name, undefined, undefined, codeGraph),
+        health: () =>
+          daemonHealthSnapshot(store, project.name, undefined, undefined, codeGraph, {
+            isolation: boundary.isolation,
+            mechanism: boundary.probe.mechanism,
+            headline: describeBoundary(boundary.isolation, boundary.probe).headline,
+          }),
       }),
   });
   log(`serving /healthz on :${server.port}, project ${project.name}`);

package/src/fleet.ts

@@ -1112,11 +1112,32 @@ export async function renderStatus(projectName?: string): Promise<string> {
   ]);
   const cached = codeGraphFromHealthz(health?.body, project.name);
   const codeGraph = cached ?? (await probeCodeGraph(project));
-  // Probed here, per `status` call, rather than read off the daemon: an
-  // operator asking whether their fleet is protected must get the answer for
-  // the host they are standing on, including when no daemon is running.
+  // The daemon's own answer wins, and this is not an optimisation.
+  //
+  // Capabilities are a property of the PROCESS, not the host. `status` runs in
+  // an interactive shell with none of the unit's ambient capabilities and none
+  // of the conductor groups, so re-probing here reports `group-mode` — or
+  // "REFUSING DISPATCH" — on a fleet whose daemon is genuinely `uid-pool`. An
+  // operator following the documented verification step would conclude the
+  // boundary had failed while it was working perfectly.
+  //
+  // It is also the only answer that survives a `daemon-reload` without a
+  // restart, which no config check can see: this is what the running process
+  // actually got at startup.
+  //
+  // Falling back to a local probe when no daemon is running is still right —
+  // there is a real question to answer then — but it is labelled, because it is
+  // a different question.
   const credentials = resolveCredentials(project);
-  const probe = await probeHost({ slots: s.caps.maxConcurrentWorkers });
+  const live = boundaryFromHealthz(health?.body);
+  const boundary =
+    live ?? {
+      ...describeBoundary(credentials.isolation, await probeHost({ slots: s.caps.maxConcurrentWorkers })),
+      detail: [
+        "No daemon is running, so this is THIS SHELL's view, not the fleet's — an interactive shell holds",
+        "none of the unit's capabilities. Start the daemon and re-read before concluding anything.",
+      ],
+    };
   return formatFleetStatus(
     { ...s, planUsage },
     layers,
@@ -1125,7 +1146,7 @@ export async function renderStatus(projectName?: string): Promise<string> {
     Date.now(),
     codeGraph,
     confinementRefusalsToday(),
-    describeBoundary(credentials.isolation, probe),
+    boundary,
   );
 }
 
@@ -1419,3 +1440,21 @@ function probeOmpPane(
     return { kind: "unknown", reason: err instanceof Error ? err.message : String(err) };
   }
 }
+
+/**
+ * The boundary the running daemon resolved, out of its `/healthz` body.
+ *
+ * Same posture as `codeGraphFromHealthz`: an older daemon that predates the
+ * field simply does not answer, and the caller falls back to a local probe with
+ * that difference stated rather than papered over.
+ */
+export function boundaryFromHealthz(
+  body: unknown,
+): { headline: string; detail: string[] } | undefined {
+  if (typeof body !== "object" || body === null) return undefined;
+  const boundary = (body as { boundary?: unknown }).boundary;
+  if (typeof boundary !== "object" || boundary === null) return undefined;
+  const headline = (boundary as { headline?: unknown }).headline;
+  if (typeof headline !== "string" || headline.length === 0) return undefined;
+  return { headline, detail: [] };
+}

package/src/setup-host.ts

@@ -110,11 +110,14 @@ export function renderDaemonService(
     `Environment=${systemdQuote(`PATH=${runtime.path}`)}`,
     `Environment=${systemdQuote(`OMP_CONDUCTOR_HOME=${runtime.conductorHome}`)}`,
     `Environment=${systemdQuote(`OMP_TELEGRAM_STATE_DIR=${runtime.telegramStateDir}`)}`,
-    // Baked in so a custom shared root survives systemd's clean environment.
-    // Without it the daemon resolves the platform default while the operator
-    // provisioned somewhere else, and every per-run dispatch is refused for a
-    // path nobody chose (#125).
-    `Environment=${systemdQuote(`OMP_CONDUCTOR_SHARED=${sharedRoot()}`)}`,
+    // Both of these are per-run only, and grouped so the managed set stays one
+    // idea. The shared root is baked in so a custom location survives systemd's
+    // clean environment — without it the daemon resolves the platform default
+    // while the operator provisioned somewhere else, and every dispatch is
+    // refused for a path nobody chose. It is meaningless under `none`, where
+    // nothing resolves it, and rendering it there would make every unit
+    // installed before 0.4.0 look drifted for no reason (#125).
+    //
     // The capabilities exist to be DROPPED INTO run children by the
     // privilege-dropping launcher, never inherited by them — see `setprivArgv`.
     // Rendered only for `per-run`, because that is the only isolation that
@@ -124,6 +127,7 @@ export function renderDaemonService(
     // failure an operator following setup would otherwise hit first.
     ...(resolveCredentials(project).isolation === "per-run"
       ? [
+          `Environment=${systemdQuote(`OMP_CONDUCTOR_SHARED=${sharedRoot()}`)}`,
           "AmbientCapabilities=CAP_SETUID CAP_SETGID CAP_CHOWN CAP_FOWNER CAP_SETPCAP",
           "CapabilityBoundingSet=CAP_SETUID CAP_SETGID CAP_CHOWN CAP_FOWNER CAP_SETPCAP",
         ]
@@ -301,3 +305,142 @@ export async function runSetupSmoke(
     await deps.stop();
   }
 }
+
+/** Absolute path of the unit systemd actually reads. */
+export function installedUnitPath(): string {
+  return join(SYSTEMD_UNIT_DIR, STAGED_SERVICE_NAME);
+}
+
+/**
+ * Why the *live* systemd unit no longer matches what this version would render.
+ *
+ * `planHostRuntime` compares against the **staged** copy under the state dir,
+ * which says nothing about the file systemd booted from. That gap is not
+ * cosmetic since 0.4.0: a fleet configured `per-run` whose installed unit
+ * predates the capability grant probes down to `group-mode` and then refuses
+ * every dispatch — and `upgrade` would happily verify package identities,
+ * services, pane and ticks around it, because none of those look at the unit.
+ *
+ * Checked by directive rather than by whole-file equality on purpose. An
+ * operator is entitled to hand-tune `MemoryMax`, add `After=`, or set an
+ * `Environment=` of their own, and failing an upgrade over that would teach
+ * them to stop running upgrades. What is reported is the set of directives this
+ * configuration *requires* and the live unit lacks.
+ *
+ * `undefined` means either "no drift that matters" or "no installed unit at
+ * all" — a host running `omp-conductor start` without systemd is not broken,
+ * and must not be told it is.
+ */
+/**
+ * What systemd has actually loaded for the unit, as `systemctl show` reports it.
+ *
+ * Deliberately not the file on disk. A unit installed without `daemon-reload`
+ * can match the rendered text byte for byte while the manager still runs the
+ * previous configuration, and a drop-in under `…service.d/` changes what runs
+ * without touching the file at all. Both read clean from the filesystem.
+ */
+export interface EffectiveUnit {
+  /** `systemctl show -p AmbientCapabilities`; empty string when unset. */
+  ambientCapabilities: string;
+  capabilityBoundingSet: string;
+  /** `systemctl show -p Environment`, newline- or space-joined. */
+  environment: string;
+  needDaemonReload: boolean;
+}
+
+/** Capability names as a comparable set: systemd reports them lowercased, `cap_`-prefixed and reordered. */
+function capabilitySet(text: string): Set<string> {
+  return new Set(
+    text
+      .split(/[\s,]+/)
+      .map((name) => name.trim().toLowerCase().replace(/^cap_/, ""))
+      .filter((name) => name.length > 0),
+  );
+}
+
+function renderedDirective(rendered: string, key: string): string | undefined {
+  for (const line of rendered.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith(`${key}=`)) return trimmed.slice(key.length + 1);
+  }
+  return undefined;
+}
+
+/**
+ * Why what systemd loaded no longer matches what this version would render.
+ *
+ * Three asymmetries, each for a reason:
+ *
+ * - **Ambient capabilities are compared exactly, both ways.** Missing them
+ *   breaks a per-run fleet; *leftover* ones are worse. Roll back to `none` and
+ *   there is no `setpriv` launcher at all, so ambient capabilities on the unit
+ *   are inherited straight into model-executed code, which can then `setuid()`
+ *   to any account. `systemctl` reports an empty string when unset, so the
+ *   rollback case is unambiguous.
+ * - **The bounding set is checked only when this version sets it.** systemd
+ *   reports the full default set when a unit does not, so comparing both ways
+ *   would flag every ordinary host.
+ * - **Only directives this configuration manages are considered**, so an
+ *   operator's own `MemoryMax`, `After=` or drop-in never fails an upgrade.
+ */
+export function unitDriftReason(rendered: string, effective: EffectiveUnit | undefined): string | undefined {
+  if (effective === undefined) return undefined;
+  const problems: string[] = [];
+
+  const wantAmbient = capabilitySet(renderedDirective(rendered, "AmbientCapabilities") ?? "");
+  const haveAmbient = capabilitySet(effective.ambientCapabilities);
+  const missingAmbient = [...wantAmbient].filter((c) => !haveAmbient.has(c));
+  const extraAmbient = [...haveAmbient].filter((c) => !wantAmbient.has(c));
+  if (missingAmbient.length > 0) {
+    problems.push(`AmbientCapabilities is missing ${missingAmbient.join(", ")}`);
+  }
+  if (extraAmbient.length > 0) {
+    problems.push(
+      `AmbientCapabilities grants ${extraAmbient.join(", ")} that this configuration does not — with ` +
+        `isolation off there is no privilege-dropping launcher, so these are inherited by model-executed code`,
+    );
+  }
+
+  const wantBounding = renderedDirective(rendered, "CapabilityBoundingSet");
+  if (wantBounding !== undefined) {
+    const missing = [...capabilitySet(wantBounding)].filter(
+      (c) => !capabilitySet(effective.capabilityBoundingSet).has(c),
+    );
+    if (missing.length > 0) problems.push(`CapabilityBoundingSet is missing ${missing.join(", ")}`);
+  }
+
+  const wantShared = rendered
+    .split("\n")
+    .map((l) => l.trim())
+    .find((l) => l.includes("OMP_CONDUCTOR_SHARED="));
+  if (wantShared !== undefined) {
+    const value = wantShared.slice(wantShared.indexOf("OMP_CONDUCTOR_SHARED=")).replace(/"$/, "");
+    if (!effective.environment.includes(value)) {
+      problems.push(`Environment is missing ${value}`);
+    }
+  }
+
+  if (effective.needDaemonReload) {
+    problems.push("systemd reports the unit needs a daemon-reload, so what runs is not what is on disk");
+  }
+
+  if (problems.length === 0) return undefined;
+  return (
+    `what systemd loaded for ${STAGED_SERVICE_NAME} does not match this configuration: ${problems.join("; ")}.`
+  );
+}
+
+/** Parse `systemctl show -p …` key=value output into an {@link EffectiveUnit}. */
+export function parseEffectiveUnit(stdout: string): EffectiveUnit {
+  const values = new Map<string, string>();
+  for (const line of stdout.split("\n")) {
+    const at = line.indexOf("=");
+    if (at > 0) values.set(line.slice(0, at).trim(), line.slice(at + 1).trim());
+  }
+  return {
+    ambientCapabilities: values.get("AmbientCapabilities") ?? "",
+    capabilityBoundingSet: values.get("CapabilityBoundingSet") ?? "",
+    environment: values.get("Environment") ?? "",
+    needDaemonReload: (values.get("NeedDaemonReload") ?? "no") === "yes",
+  };
+}

package/src/upgrade.ts

@@ -1,10 +1,18 @@
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { inspectBriefLayout, type BriefLayout } from "./brief-upgrade.ts";
 import { setPaused, statusSnapshot } from "./daemon.ts";
-import { fleetLayers, type DispatchLayer, type FleetLayers } from "./fleet.ts";
+import { fleetLayers, telegramStateDir, type DispatchLayer, type FleetLayers } from "./fleet.ts";
 import { livingDaemon, restartDaemon } from "./lifecycle.ts";
-import { findProject, loadConfig } from "./config.ts";
+import { configPath, findProject, loadConfig, resolveCaps, writeConfigFile } from "./config.ts";
 import { renderBriefForProject } from "./setup.ts";
+import {
+  STAGED_SERVICE_NAME,
+  parseEffectiveUnit,
+  planHostRuntime,
+  unitDriftReason,
+  writeHostRuntime,
+  type EffectiveUnit,
+} from "./setup-host.ts";
 
 const PACKAGE = "omp-conductor";
 const HERDR_PLUGIN = "herdr-conductor";
@@ -33,6 +41,15 @@ export interface UpgradeResult {
   dispatch: DispatchLayer;
 }
 
+/** What the unit check reads, and how it repairs what it can. */
+export interface UnitFiles {
+  rendered: string;
+  /** What systemd loaded, not what is on disk. Undefined means no systemd here. */
+  effective: EffectiveUnit | undefined;
+  /** Writes the corrected unit to the state dir; returns the commands root must run. */
+  stage?(): readonly string[];
+}
+
 export interface UpgradeDeps {
   run(command: string, args: readonly string[]): Promise<UpgradeCommandResult>;
   snapshot(project?: string): { liveWorkers: number };
@@ -44,6 +61,12 @@ export interface UpgradeDeps {
   sleep(ms: number): Promise<void>;
   env: NodeJS.ProcessEnv;
   log(message: string): void;
+  /**
+   * What this version would render as the unit, and what systemd actually
+   * booted from. Injected so the drift check is testable without a systemd host
+   * — and defaulted, so no production caller has to know it exists.
+   */
+  unitFiles?(): Promise<UnitFiles | undefined> | UnitFiles | undefined;
 }
 
 async function runCommand(command: string, args: readonly string[]): Promise<UpgradeCommandResult> {
@@ -273,8 +296,30 @@ async function rollbackUpgrade(
   briefChanged: boolean,
   herdrReloadStarted: boolean,
   daemonReloadStarted: boolean,
+  configBefore?: string,
 ): Promise<void> {
   const failures: string[] = [];
+
+  // Restored FIRST, before the packages that have to read it.
+  //
+  // Rolling back binaries alone is not a rollback. The new daemon starts during
+  // the upgrade and may migrate config.json; the reinstated older release then
+  // cannot parse its own config and will not boot — which is exactly how an
+  // upgrade failure turned into an outage. The snapshot is taken before the
+  // first install, and restoring it is unconditional: writing back a file that
+  // never changed is harmless, and detecting "did it change" is one more thing
+  // to get wrong while the fleet is down.
+  if (configBefore !== undefined) {
+    try {
+      const path = configPath();
+      if (readFileSync(path, "utf8") !== configBefore) {
+        deps.log("rollback: conductor config.json");
+        writeConfigFile(JSON.parse(configBefore));
+      }
+    } catch (err) {
+      failures.push(`could not restore config.json: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
   const restore = async (label: string, command: string, args: readonly string[]): Promise<void> => {
     deps.log(`rollback: ${label}`);
     try {
@@ -381,6 +426,49 @@ async function rollbackUpgrade(
   if (failures.length > 0) throw new Error(failures.join("; "));
 }
 
+/**
+ * The rendered-vs-installed pair for {@link unitDriftReason}.
+ *
+ * Best-effort by design: a host with no config, no project, or no systemd is
+ * not a host with a broken unit, and an upgrade must not fail because it could
+ * not answer a question that does not apply there.
+ */
+async function defaultUnitFiles(deps: UpgradeDeps): Promise<UnitFiles | undefined> {
+  try {
+    const cfg = loadConfig();
+    const project = cfg.projects[0];
+    if (project === undefined) return undefined;
+    const plan = planHostRuntime(project, resolveCaps(project, cfg.defaults), telegramStateDir());
+    const shown = await deps.run("systemctl", [
+      "show",
+      STAGED_SERVICE_NAME,
+      "-p",
+      "AmbientCapabilities",
+      "-p",
+      "CapabilityBoundingSet",
+      "-p",
+      "Environment",
+      "-p",
+      "NeedDaemonReload",
+    ]);
+    return {
+      rendered: plan.service.content,
+      effective: shown.code === 0 ? parseEffectiveUnit(shown.stdout) : undefined,
+      // Staging needs no privilege, so the repair is reduced to the two lines
+      // that genuinely do. Installing the unit is root's, and this command runs
+      // as the fleet user by design — so it goes as far as it can and then says
+      // exactly what is left, rather than sending the operator back through a
+      // wizard to regenerate a file it could write itself.
+      stage: () => {
+        writeHostRuntime(plan);
+        return plan.installCommands;
+      },
+    };
+  } catch {
+    return undefined;
+  }
+}
+
 export async function upgradeConductor(
   options: UpgradeOptions = {},
   overrides: Partial<UpgradeDeps> = {},
@@ -407,6 +495,22 @@ export async function upgradeConductor(
   const surfaces = await inspectSurfaces(deps);
   const brief = deps.brief(project);
   const installNeeded = !surfacesCurrent(surfaces, release.version, release.gitHead);
+  // Computed BEFORE the no-op decision, not inside verification, and that
+  // placement is the whole point. The upgrade that installs a version is run by
+  // the *previous* CLI, so a check living only in the new code never executes
+  // for the release that introduces it — and re-running afterwards would take
+  // the already-current early return and skip it forever. A fleet whose unit is
+  // stale is not current, whatever its package identities say.
+  const files = await (deps.unitFiles === undefined ? defaultUnitFiles(deps) : deps.unitFiles());
+  const drift = files === undefined ? undefined : unitDriftReason(files.rendered, files.effective);
+  if (drift !== undefined) {
+    const commands = files?.stage?.() ?? [];
+    throw new Error(
+      commands.length === 0
+        ? drift
+        : `${drift}\n\nThe corrected unit has been staged. Run:\n${commands.map((c) => `  ${c}`).join("\n")}`,
+    );
+  }
   if (!installNeeded && brief.current) {
     return {
       previousVersion: surfaces.cliVersion,
@@ -416,6 +520,18 @@ export async function upgradeConductor(
     };
   }
 
+  // Snapshotted before anything is installed, because the new daemon starts
+  // during this transaction and may migrate the file — see the restore in
+  // `rollbackUpgrade`. Read as bytes, not through the loader: the point is to
+  // put back exactly what was there, dialect and all.
+  let configBefore: string | undefined;
+  try {
+    configBefore = readFileSync(configPath(), "utf8");
+  } catch {
+    // No readable config is not a reason to refuse an upgrade; there is simply
+    // nothing to put back.
+  }
+
   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");
 
@@ -489,6 +605,17 @@ export async function upgradeConductor(
       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`);
     }
+    // The unit is the one surface `upgrade` never looked at, and since 0.4.0 it
+    // is the difference between a working per-run fleet and one that refuses
+    // every issue. Fatal rather than a warning: the whole point of this command
+    // is that a fleet is either upgraded or explicitly left paused, and a
+    // "verified" fleet that cannot dispatch is the worse outcome.
+    // Re-read rather than trust the earlier pass: the daemon has restarted
+    // since, and an operator who installed a unit mid-upgrade should not get a
+    // green verification for a file nobody checked.
+    const after = await (deps.unitFiles === undefined ? defaultUnitFiles(deps) : deps.unitFiles());
+    const stillDrifted = after === undefined ? undefined : unitDriftReason(after.rendered, after.effective);
+    if (stillDrifted !== undefined) throw new Error(stillDrifted);
     await waitForRecovery(deps, initial, project);
     deps.log("verify 2/2: recovered fleet remains stable");
     await deps.sleep(1_000);
@@ -518,6 +645,7 @@ export async function upgradeConductor(
         briefChanged,
         herdrReloadStarted,
         daemonReloadStarted,
+        configBefore,
       );
     } catch (rollbackErr) {
       const rollback = rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr);