omp-conductor 0.18.2 → 0.19.1

package/src/upgrade.ts

@@ -1,11 +1,10 @@
 import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { backupTimestamp, copyToUniqueBackup } from "./backups.ts";
 import { inspectBriefLayout, type BriefLayout } from "./brief-upgrade.ts";
 import { pauseInstance, setPaused, statusSnapshot, type AdmissionAckRecord } from "./daemon.ts";
 import {
-  DEFAULT_HERDR_SESSION,
   fleetLayers,
-  LEGACY_HERDR_SESSION_HINT,
   resolveHerdrSession,
   telegramStateDir,
 } from "./fleet.ts";
@@ -23,6 +22,7 @@ import {
   appendJournal,
   readUpgradeJournal,
   upgradeJournalPath,
+  type UpgradeCheck,
   type UpgradeJournalEntry,
 } from "./upgrade-journal.ts";
 import {
@@ -43,6 +43,13 @@ import {
 const PACKAGE = "omp-conductor";
 const HERDR_PLUGIN = "herdr-conductor";
 const HERDR_SOURCE = "TerrifiedBug/conductor/herdr";
+
+/** The package root inside the repo, for a bootstrap install by git ref. */
+const PACKAGE_SOURCE = "TerrifiedBug/conductor/omp";
+
+/** A 40-hex commit: the only identity shape a bootstrap accepts. A branch or a
+ *  tag is a moving target, and "the exact build I verified" is the whole point. */
+const COMMIT_SHA = /^[0-9a-f]{40}$/i;
 const HERDR_UNIT = "herdr-fleet.service";
 const DRAIN_POLL_MS = 5_000;
 const RECOVERY_POLL_MS = 2_000;
@@ -50,6 +57,22 @@ const RECOVERY_ATTEMPTS = 30;
 
 export interface UpgradeOptions {
   version?: string;
+  /**
+   * Bootstrap from an exact source/build identity instead of a published semver
+   * (#908) — the path that exists because a reliability release cannot be cut
+   * when the *installed* conductor is the thing that is broken: publishing
+   * needs working workers, and the workers are what is broken.
+   *
+   * `sha` is the whole identity (a 40-hex commit, never a range), and `source`
+   * is a checkout of exactly that commit — its only job is to be the tree the
+   * package's own checks run against before anything is installed. The install
+   * itself is by git ref, so the identity is globally attestable rather than
+   * dependent on one machine's directory.
+   *
+   * Mutually exclusive with {@link version}: two identity kinds in one call is
+   * an ambiguity, not a merge.
+   */
+  bootstrap?: { sha: string; source: string };
   project?: string;
   /**
    * Run as the detached fleet installer (#486): journal every surface the
@@ -71,6 +94,15 @@ export interface UpgradeResult {
 
 export interface UpgradeDeps {
   run(command: string, args: readonly string[]): Promise<UpgradeCommandResult>;
+  /**
+   * A command run in a named working directory (#908): the bootstrap's checks
+   * run inside the source tree, and `run` is deliberately cwd-free everywhere
+   * else so no other step can depend on where it was invoked from.
+   */
+  runIn(cwd: string, command: string, args: readonly string[]): Promise<UpgradeCommandResult>;
+  /** Read one file as text. Injected so a bootstrap's manifest read is
+   *  testable without a checkout on disk. */
+  readFile(path: string): string;
   snapshot(project?: string): { liveWorkers: number };
   layers(project?: string): FleetLayers;
   brief(project?: string): { kind: BriefLayout["kind"]; current: boolean };
@@ -99,6 +131,14 @@ export interface UpgradeDeps {
   setPaused(value: boolean, project?: string): void;
   restartDaemon(): Promise<void>;
   sleep(ms: number): Promise<void>;
+  /**
+   * The environment every surface of this transaction resolves from — the
+   * herdr session included, through {@link resolveHerdrSession}. One source,
+   * because the `herdr plugin list` read and the pane probe MUST agree on
+   * which session this fleet is: when they did not, `upgrade` installed
+   * against one session and failed verification against another, then rolled
+   * a good release back (#976).
+   */
   env: NodeJS.ProcessEnv;
   log(message: string): void;
   /**
@@ -108,11 +148,6 @@ export interface UpgradeDeps {
    * session process actually loaded.
    */
   health(port: number): Promise<{ ok: boolean; body?: string }>;
-  /**
-   * The herdr session the fleet pane lives in, for the external-orchestrator
-   * pane probe (#832).
-   */
-  herdrSession(): string;
   /**
    * Every omp process the fleet pane currently claims by herdr, resolved to
    * its start time — the evidence an external (pane-owned) orchestrator
@@ -145,6 +180,8 @@ export interface UpgradeDeps {
  *  post-restart verifier and the rollback unit run processes the same way. */
 export const DEFAULT_DEPS: UpgradeDeps = {
   run: runCommand,
+  runIn: (cwd, command, args) => runCommand(command, args, cwd),
+  readFile: (path) => readFileSync(path, "utf8"),
   snapshot: statusSnapshot,
   layers: fleetLayers,
   brief: (projectName) => {
@@ -172,7 +209,6 @@ export const DEFAULT_DEPS: UpgradeDeps = {
     await restartDaemon({});
   },
   health: async (port) => healthCheck(port),
-  herdrSession: () => resolveHerdrSession(process.env),
   probePaneOmp: (session) => herdrPaneOmpStarts(runCommand, session, processStartTimeMs),
   // The bare host-global plan — the same render the advisory's `setup host`
   // command would install: no per-project tail, the recovery unit encoding no
@@ -191,7 +227,7 @@ function commandLine(command: string, args: readonly string[]): string {
 }
 
 async function mustRun(
-  deps: UpgradeDeps,
+  deps: SurfaceProbeDeps,
   command: string,
   args: readonly string[],
 ): Promise<UpgradeCommandResult> {
@@ -222,6 +258,108 @@ function parseRegistry(raw: string): { version: string; gitHead: string } {
   return { version, gitHead };
 }
 
+/**
+ * One release identity plus how to install it (#908).
+ *
+ * Two kinds, one shape downstream: everything after this — the currentness
+ * comparison, the journal, the install, the attestation and the rollback —
+ * reads a `{ version, gitHead }` pair and an install spec, so a bootstrap is a
+ * second accepted identity rather than a parallel installer.
+ */
+interface ReleaseIdentityPlan {
+  version: string;
+  gitHead: string;
+  /** What `bun add -g` / `omp plugin install` are given for this identity. */
+  packageSpec: string;
+  /** Named checks already run to earn this identity, journalled as evidence. */
+  checks: UpgradeCheck[];
+  /** True for a source/build identity: npm does not have this version. */
+  bootstrap: boolean;
+}
+
+/** The version a source tree declares — the identity's other half, read from
+ *  the tree itself because npm has never seen it. */
+function sourceVersion(deps: UpgradeDeps, source: string): string {
+  const manifest = join(source, "omp", "package.json");
+  let raw: string;
+  try {
+    raw = deps.readFile(manifest);
+  } catch (err) {
+    throw new Error(
+      `bootstrap refused: cannot read ${manifest} (${err instanceof Error ? err.message : String(err)}) — ` +
+        "--source must be a checkout of this repository",
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`bootstrap refused: ${manifest} is not valid JSON`);
+  }
+  const version = parsed !== null && typeof parsed === "object" ? Reflect.get(parsed, "version") : undefined;
+  if (typeof version !== "string" || version.length === 0) {
+    throw new Error(`bootstrap refused: ${manifest} declares no version`);
+  }
+  return version;
+}
+
+/**
+ * Resolve which release this run installs, and prove a bootstrap identity
+ * before it can touch anything (#908).
+ *
+ * The three refusals are the deliverable, not the install: a sha that is not a
+ * sha, a source tree that is not at that sha, and a source tree whose own
+ * checks fail. Each names the identity and what failed, and each happens before
+ * the first surface is replaced — an unverified tree must never become a live
+ * install, which is the difference between this and the `bun add github:...`
+ * POLICY forbids.
+ */
+async function resolveIdentity(deps: UpgradeDeps, options: UpgradeOptions): Promise<ReleaseIdentityPlan> {
+  const bootstrap = options.bootstrap;
+  if (bootstrap === undefined) {
+    const requested = options.version === undefined ? `${PACKAGE}@latest` : `${PACKAGE}@${options.version}`;
+    const release = parseRegistry(
+      (await mustRun(deps, "npm", ["view", requested, "version", "gitHead", "--json"])).stdout,
+    );
+    return { ...release, packageSpec: `${PACKAGE}@${release.version}`, checks: [], bootstrap: false };
+  }
+  if (options.version !== undefined) {
+    throw new Error("bootstrap refused: pass either --to VERSION or --bootstrap SHA, never both");
+  }
+  const sha = bootstrap.sha.toLowerCase();
+  if (!COMMIT_SHA.test(sha)) {
+    throw new Error(`bootstrap refused: "${bootstrap.sha}" is not a 40-character commit sha`);
+  }
+  const checks: UpgradeCheck[] = [];
+  // The tree must BE that commit. Without this the identity is a label the
+  // operator typed, and the checks below would attest a different build than
+  // the one installed.
+  const head = await deps.run("git", ["-C", bootstrap.source, "rev-parse", "HEAD"]);
+  const at = head.stdout.trim().toLowerCase();
+  if (head.code !== 0 || at !== sha) {
+    checks.push({ name: "source-at-sha", ok: false, detail: at.length === 0 ? head.stderr.trim() : at });
+    throw new Error(
+      `bootstrap refused: ${bootstrap.source} is at ${at.length === 0 ? "an unreadable HEAD" : at}, not ${sha} — ` +
+        "the checks would attest a different build than the one installed",
+    );
+  }
+  checks.push({ name: "source-at-sha", ok: true, detail: sha });
+  const version = sourceVersion(deps, bootstrap.source);
+  // The package's own declared gate, against the source, before anything is
+  // installed. A failure refuses: a partially verified tree must not go live.
+  deps.log(`bootstrap: running the package checks against ${bootstrap.source} (${sha.slice(0, 12)})`);
+  const gate = await deps.runIn(join(bootstrap.source, "omp"), "bun", ["run", "check"]);
+  if (gate.code !== 0) {
+    const detail = (gate.stderr.trim() || gate.stdout.trim()).split("\n").slice(-3).join("; ");
+    checks.push({ name: "package-checks", ok: false, detail });
+    throw new Error(
+      `bootstrap refused: \`bun run check\` failed against ${bootstrap.source} at ${sha} — ${detail}`,
+    );
+  }
+  checks.push({ name: "package-checks", ok: true });
+  return { version, gitHead: sha, packageSpec: `github:${PACKAGE_SOURCE}#${sha}`, checks, bootstrap: true };
+}
+
 function ompPluginVersion(raw: string): string | undefined {
   let parsed: unknown;
   try {
@@ -255,39 +393,44 @@ function herdrPluginSource(raw: string): string | undefined {
   return source;
 }
 
-interface InstalledSurfaces {
+/** The three installed identities one host carries: the Bun-global CLI/daemon
+ *  tree, the omp plugin, and the herdr recovery plugin's pin. */
+export interface InstalledSurfaces {
   cliVersion: string;
   ompVersion?: string;
   herdrSource?: string;
 }
 
-async function inspectSurfaces(deps: UpgradeDeps): Promise<InstalledSurfaces> {
-  // HERDR_SESSION is authoritative. Otherwise prefer DEFAULT_HERDR_SESSION, with
-  // #320's one-release bridge to a populated legacy "fleet" session.
-  let session = resolveHerdrSession(deps.env);
-  if (deps.env["HERDR_SESSION"] === undefined || deps.env["HERDR_SESSION"] === "") {
-    // Prefer a session that answers plugin list; fall back to conductor.
-    let conductorOk = false;
-    let fleetOk = false;
-    try {
-      const r = await deps.run("herdr", ["--session", DEFAULT_HERDR_SESSION, "plugin", "list"]);
-      conductorOk = r.code === 0;
-    } catch {
-      conductorOk = false;
-    }
-    try {
-      const r = await deps.run("herdr", ["--session", "fleet", "plugin", "list"]);
-      fleetOk = r.code === 0;
-    } catch {
-      fleetOk = false;
-    }
-    if (!conductorOk && fleetOk) {
-      session = "fleet";
-      deps.log(LEGACY_HERDR_SESSION_HINT);
-    } else {
-      session = DEFAULT_HERDR_SESSION;
-    }
+/** What reading the three surfaces needs — deliberately narrower than
+ *  {@link UpgradeDeps} so a read-only consumer (`doctor`'s surface-parity
+ *  finding, #904) can supply three fields instead of a whole transaction. */
+export type SurfaceProbeDeps = Pick<UpgradeDeps, "run" | "log" | "env">;
+
+/**
+ * Read the CLI, omp-plugin and herdr-plugin identities actually installed on
+ * this host. Exported because `upgrade` is not the only thing that needs to
+ * know whether the three agree: a host whose installs are manual diverges
+ * silently between transactions, and `doctor` reads them through this one
+ * seam rather than growing a second implementation (#904).
+ */
+export async function inspectSurfaces(
+  deps: SurfaceProbeDeps,
+  /** `readHerdr: false` skips the herdr session probe and plugin read
+   *  entirely, so a host with no herdr on PATH can still be asked what its
+   *  CLI and omp plugin are (#904). The upgrade transaction always reads all
+   *  three — a release pins every surface. */
+  opts: { readHerdr?: boolean } = {},
+): Promise<InstalledSurfaces> {
+  if (opts.readHerdr === false) {
+    const [cliOnly, ompOnly] = await Promise.all([
+      mustRun(deps, "omp-conductor", ["--version"]),
+      mustRun(deps, "omp", ["plugin", "list", "--json"]),
+    ]);
+    const version = cliOnly.stdout.trim();
+    if (version.length === 0) throw new Error("installed omp-conductor CLI has no version");
+    return { cliVersion: version, ompVersion: ompPluginVersion(ompOnly.stdout) };
   }
+  const session = resolveHerdrSession(deps.env);
   const [cli, omp, herdr] = await Promise.all([
     mustRun(deps, "omp-conductor", ["--version"]),
     mustRun(deps, "omp", ["plugin", "list", "--json"]),
@@ -302,12 +445,25 @@ async function inspectSurfaces(deps: UpgradeDeps): Promise<InstalledSurfaces> {
   };
 }
 
-function expectedHerdrSource(gitHead: string): string {
+export function expectedHerdrSource(gitHead: string): string {
   return `github:${HERDR_SOURCE}@${gitHead}`;
 }
 
+/**
+ * The published identity of one release: its version and the exact commit it
+ * was cut from, straight from the registry metadata `upgrade` already trusts.
+ * Exported so a read-only consumer can answer "which commit should this
+ * host's herdr plugin be pinned to?" without re-deriving the mapping (#904).
+ */
+export async function releaseIdentity(
+  deps: SurfaceProbeDeps,
+  version: string,
+): Promise<{ version: string; gitHead: string }> {
+  return parseRegistry((await mustRun(deps, "npm", ["view", `${PACKAGE}@${version}`, "version", "gitHead", "--json"])).stdout);
+}
+
 function surfacesCurrent(
-  surfaces: Awaited<ReturnType<typeof inspectSurfaces>>,
+  surfaces: InstalledSurfaces,
   version: string,
   gitHead: string,
 ): boolean {
@@ -727,7 +883,7 @@ async function sessionVerifyProblem(
     // No daemon to attest: only the pane could have reloaded anything, so the
     // pane probe decides alone, exactly as the external leg of the detached
     // verifier does.
-    const pane = await deps.probePaneOmp(deps.herdrSession());
+    const pane = await deps.probePaneOmp(resolveHerdrSession(deps.env));
     if ("problem" in pane) return `the fleet pane could not be probed: ${pane.problem}`;
     return paneRestartProblem(pane.starts, reloadAfterMs) ?? undefined;
   }
@@ -753,7 +909,7 @@ async function sessionVerifyProblem(
   if (names.length === 0) {
     return `the restarted daemon's /healthz on :${port} named no project — the live session cannot be attested`;
   }
-  const pane = await deps.probePaneOmp(deps.herdrSession());
+  const pane = await deps.probePaneOmp(resolveHerdrSession(deps.env));
   for (const project of names) {
     const problem = sessionReloadProblem({
       facts: orchestratorFactsFromHealth(health.body, project),
@@ -992,6 +1148,26 @@ export async function rollbackUpgrade(
     }
   }
 
+  // The units the forward transaction reconciled (#905). Restoring them is the
+  // same operation in the other direction: the *restored* CLI renders the
+  // previous version's templates, so running its own reconcile puts the
+  // pre-upgrade bytes back at every destination — and leaves anything the
+  // operator edited alone, because that drift is protected on both legs.
+  //
+  // Ordered before the restarts below, exactly as the forward leg is, and
+  // best-effort: a rollback that restored three surfaces must not fail because
+  // a unit file could not be rewritten. The failure is collected and reported
+  // with the rest.
+  if (installTouched) {
+    const restoreUnits = await deps.run("omp-conductor", ["reconcile-units", "--yes"]);
+    const summary = (restoreUnits.stdout.trim() || restoreUnits.stderr.trim()).split("\n").pop() ?? "";
+    if (restoreUnits.code === 0) {
+      deps.log(`rollback: ${summary.length === 0 ? "host units restored" : summary}`);
+    } else {
+      failures.push(`host units not restored: ${summary}`);
+    }
+  }
+
   if (herdrReloadStarted) {
     await restore("restart herdr-fleet.service", "systemctl", ["restart", HERDR_UNIT]);
   }
@@ -1053,7 +1229,16 @@ function logHostRuntimeDrift(deps: UpgradeDeps): void {
   if (plan.drift.length === 0) return;
   deps.log("host runtime:");
   for (const path of plan.drift) deps.log(`  ${path} differs from this version's render`);
-  deps.log("fix: run `omp-conductor setup host` from the fleet account to re-install the host units");
+  // Units are this transaction's own to reconcile (#905), and the reconcile
+  // verb is bounded to them. Anything else the render owns — the herdr
+  // pane-shell config, the herdr-conductor `config.env`, the worker identity —
+  // still needs `setup host`, so the advisory names the right tool for each
+  // rather than routing every drift into the flow that restarts (and kills)
+  // the caller's own pane (#834).
+  deps.log(
+    "fix: `omp-conductor reconcile-units` re-installs the host units; anything else above needs " +
+      "`omp-conductor setup host` from the fleet account",
+  );
 }
 
 export async function upgradeConductor(
@@ -1069,14 +1254,29 @@ export async function upgradeConductor(
     throw new Error("run omp-conductor upgrade from a shell outside the target Herdr session");
   }
 
-  const requested = options.version === undefined ? `${PACKAGE}@latest` : `${PACKAGE}@${options.version}`;
   // Host-wide by default (#389): one daemon serves every configured project,
   // so an upgrade that restarts it drains them all and refreshes every brief.
   const scope = resolveScope(deps, "upgrade", options.project);
 
-  const release = parseRegistry(
-    (await mustRun(deps, "npm", ["view", requested, "version", "gitHead", "--json"])).stdout,
-  );
+  // Published semver, or an exact source/build identity whose checks have
+  // already passed (#908). Everything below reads the same pair either way.
+  const identity = await resolveIdentity(deps, options);
+  const release = { version: identity.version, gitHead: identity.gitHead };
+  if (identity.bootstrap) {
+    // The bootstrap's evidence lands in the journal before the first surface
+    // moves, so an interrupted bootstrap leaves a record of what was verified
+    // rather than an unexplained half-install.
+    journal({
+      kind: "request",
+      ok: true,
+      version: release.version,
+      gitHead: release.gitHead,
+      phase: "bootstrap",
+      detail: `source identity from ${options.bootstrap?.source ?? "(source)"}`,
+      checks: identity.checks,
+      unit: deps.env["OMP_CONDUCTOR_UNIT"],
+    });
+  }
   if (detached) {
     // The durable request: written before anything can pause, so a unit that
     // dies after this line leaves a journal the returning process can act on
@@ -1096,6 +1296,18 @@ export async function upgradeConductor(
     ...deps.brief(selector),
   }));
   const installNeeded = !surfacesCurrent(surfaces, release.version, release.gitHead);
+  // The host-unit baseline, read while the OLD package is still the one
+  // rendering (#905). A destination already differing from the old render was
+  // edited outside conductor, so the reconcile after the install must not
+  // overwrite it; `undefined` means the baseline could not be established at
+  // all, and the reconcile is skipped rather than guessing.
+  const preInstallDrift = ((): string[] | undefined => {
+    try {
+      return [...deps.hostRuntime().drift];
+    } catch {
+      return undefined;
+    }
+  })();
   if (!installNeeded && briefs.every((b) => b.current)) {
     if (detached) {
       journal({
@@ -1151,6 +1363,23 @@ export async function upgradeConductor(
   }
   if (initial.herdr === "unknown") throw new Error("cannot determine whether herdr-fleet.service is active");
 
+  // The one verification input that can be read before anything moves (#976).
+  // Verification probes the fleet pane in `resolveHerdrSession(deps.env)`; a
+  // host whose session answers to another name only discovers that after three
+  // installs and two restarts, and a good release is then rolled back. Read it
+  // first: the same probe, at zero cost, as a refusal.
+  if (!detached && (initial.dispatch !== "stopped" || initial.herdr === "active")) {
+    const session = resolveHerdrSession(deps.env);
+    const pane = await deps.probePaneOmp(session);
+    if ("problem" in pane) {
+      throw new Error(
+        `the fleet pane in herdr session "${session}" cannot be probed, so this upgrade could not be ` +
+          `verified: ${pane.problem}. Set HERDR_SESSION to the session that owns the fleet pane and ` +
+          `re-run, or bring that session up first — nothing has been installed.`,
+      );
+    }
+  }
+
   if (detached) {
     // The durable record the returning process rolls back or verifies against:
     // what was installed, what dispatch state the fleet began in, which pause
@@ -1209,10 +1438,10 @@ export async function upgradeConductor(
     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}`]);
+      await mustRun(deps, "bun", ["add", "-g", identity.packageSpec]);
       journal({ kind: "phase", phase: "install", surface: "cli", ok: true, version: release.version, gitHead: release.gitHead });
       deps.log(`install 2/3: omp plugin omp-conductor → ${release.version}`);
-      await mustRun(deps, "omp", ["plugin", "install", `${PACKAGE}@${release.version}`]);
+      await mustRun(deps, "omp", ["plugin", "install", identity.packageSpec]);
       journal({ kind: "phase", phase: "install", surface: "omp", ok: true, version: release.version, gitHead: release.gitHead });
       if (surfaces.herdrSource?.startsWith("local:")) {
         await mustRun(deps, "herdr", ["plugin", "unlink", HERDR_PLUGIN]);
@@ -1236,6 +1465,56 @@ export async function upgradeConductor(
     await upgradeBriefs(deps, briefs);
     journal({ kind: "phase", phase: "brief", surface: "brief", ok: true, version: release.version });
 
+    // #905: the templates this release re-rendered. The render is CODE, so
+    // this process — which loaded the previous version before replacing it —
+    // cannot see the new one: the reconcile runs as a fresh child of the
+    // just-installed CLI, which is also why it is spawned rather than called.
+    // (Not an escalation of conductor itself: the child escalates only its own
+    // bounded `install`/`daemon-reload` steps, which is exactly the boundary
+    // `privileged.ts` draws.)
+    //
+    // It lands here, before the restarts below, so the daemon and the herdr
+    // session come up reading the units this release actually ships — and
+    // inside the same pause/drain window, so nothing is admitted against a
+    // half-reconciled host.
+    {
+      // No baseline means no *refresh*: drift the operator made cannot be told
+      // from drift the upgrade made, so nothing is overwritten. It does not
+      // mean no *retirement* (#895) — a unit this release stopped shipping is
+      // not a comparison against any render, and skipping the whole child
+      // there left an affected host mounting an obsolete bind after every
+      // upgrade, forever. So the child always runs; only its refresh half is
+      // gated.
+      const refreshable = preInstallDrift !== undefined;
+      if (!refreshable) {
+        deps.log(
+          "host units: refresh skipped — this version's host state could not be read before the install, " +
+            "so drift the operator made cannot be told from drift the upgrade made. Retirement still runs; " +
+            "run `omp-conductor reconcile-units --dry-run` to see what differs.",
+        );
+      }
+      const reconcile = await deps.run("omp-conductor", [
+        "reconcile-units",
+        "--yes",
+        ...(refreshable ? [] : ["--no-refresh"]),
+        // Destinations that already differed from the OLD render are the
+        // operator's own edits, not this upgrade's doing: named here so the
+        // child leaves them alone and reports them.
+        ...(preInstallDrift ?? []).flatMap((path) => ["--protect", path]),
+      ]);
+      const summary = (reconcile.stdout.trim() || reconcile.stderr.trim()).split("\n").pop() ?? "";
+      if (reconcile.code === 0) {
+        deps.log(summary.length === 0 ? "host units: reconciled" : summary);
+        journal({ kind: "phase", phase: "reconcile", surface: "units", ok: true, version: release.version, detail: summary });
+      } else {
+        // A failed reconcile is a drifted host, not a failed upgrade: the
+        // packages are installed and verifiable, and the units are exactly as
+        // they were. Say so precisely instead of rolling three surfaces back.
+        deps.log(`host units: reconcile did not complete — ${summary}`);
+        journal({ kind: "phase", phase: "reconcile", surface: "units", ok: false, version: release.version, detail: summary });
+      }
+    }
+
     if (initial.herdr === "active") {
       herdrReloadStarted = true;
       deps.log("reload: restarting herdr-fleet.service and recovering the orchestrator pane");