omp-conductor 0.18.1 → 0.19.0

package/src/setup-host.ts

@@ -1,7 +1,7 @@
 import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, type Stats } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { homedir, userInfo } from "node:os";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { configPath, loadConfig, resolveCaps, stateDir } from "./config.ts";
 import { isPaused, runDaemon, statusSnapshot, type StatusSnapshot } from "./daemon.ts";
 import { ORCHESTRATOR_BRIEF_NAME } from "./brief-upgrade.ts";
@@ -12,12 +12,7 @@ import {
   resolveHerdrSessionWithBridge,
 } from "./fleet.ts";
 import {
-  harnessBindingProblem,
-  workerHarnessImportProblem,
-  WORKER_ACCOUNT,
   WORKER_HARNESS_DIR,
-  WORKER_HARNESS_NODE_MODULES,
-  WORKER_HOME_DIR,
   packageNodeModulesRoot,
 } from "./host.ts";
 import {
@@ -48,6 +43,16 @@ export const DEFAULT_TICK_INTERVAL_SECONDS = 900;
 export const STAGED_SERVICE_NAME = "omp-conductor.service";
 export const SYSTEMD_UNIT_DIR = "/etc/systemd/system";
 
+/**
+ * The system directories every rendered service PATH ends with, in systemd's
+ * own default order: git, gh and the other tools the fleet spawns by name
+ * live here on every target host. The service PATH as a whole is canonical
+ * (#879) — these directories plus the resolved fleet-binary directories — so
+ * `setup host` stages and `doctor` compares one value, whichever process
+ * renders it and whatever the invoking shell happened to carry.
+ */
+export const SERVICE_SYSTEM_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
+
 /**
  * The one recovery unit every fleet unit's `OnFailure=` points at (#485).
  *
@@ -70,9 +75,14 @@ export const RECOVER_SCRIPT_FILE = "omp-conductor-recover.sh";
 export const RECOVER_SCRIPT_INSTALL_PATH = "/usr/local/sbin/omp-conductor-recover";
 
 /**
- * The systemd unit that binds the operator's install read-only at
- * {@link WORKER_HARNESS_NODE_MODULES} so worker sessions resolve the harness
- * the operator installed (#828).
+ * The mount unit releases 0.18.1-era installed to bind the operator's install
+ * read-only for a separate worker account (#828), kept **only** so this
+ * version can retire it (#895).
+ *
+ * Nothing renders or installs it any more: worker sessions launch under the
+ * fleet account again (#894), so the bind serves nobody, and a `.mount` unit
+ * an earlier release enabled stays enabled until something disables it. This
+ * constant is that something's target — see {@link HostRuntimePlan.retire}.
  *
  * The name is not a choice: systemd derives a mount unit's name from its mount
  * point and refuses to load one under any other, so this is the escaped form of
@@ -81,6 +91,23 @@ export const RECOVER_SCRIPT_INSTALL_PATH = "/usr/local/sbin/omp-conductor-recove
  */
 export const HARNESS_MOUNT_UNIT_NAME = "var-lib-omp\\x2dworker\\x2dharness-node_modules.mount";
 
+/**
+ * Host state a previous release installed that this one retires (#895).
+ *
+ * Kept as one value rather than three so a caller cannot execute the steps
+ * without being able to say what they retire (the CLI prints `units`/`staged`,
+ * the reconcile reports them, and `formatHostRuntimePlan` shows them before
+ * the confirm).
+ */
+export interface HostRetirement {
+  /** Installed unit paths this version no longer ships, still on disk. */
+  units: readonly string[];
+  /** Staged renders of those units still sitting in the state directory. */
+  staged: readonly string[];
+  /** The ordered steps that retire them: disable/unmount, remove, reload. */
+  steps: readonly PrivilegedStep[];
+}
+
 /**
  * The symlink the session cwd loads as its brief. omp auto-loads `AGENTS.md`
  * from the session cwd, so the fleet pane's cwd needs a link at this name
@@ -138,15 +165,6 @@ export interface HostRuntimePlan {
    * rendering that provisions it (see {@link renderHerdrUnit}).
    */
   herdrUnit?: PlannedWrite<string>;
-  /**
-   * The worker harness binding's mount unit (#828): a read-only bind of the
-   * operator's install at {@link WORKER_HARNESS_NODE_MODULES}, which is the
-   * only path a worker session can resolve the harness through. Present
-   * exactly when the caller planned a worker identity this host can establish
-   * — the binding has no purpose without one, and a host that cannot run the
-   * account machinery has nothing to bind it for.
-   */
-  harnessMount?: PlannedWrite<string>;
   /**
    * The fleet recovery oneshot (#485): staged always, because the daemon unit
    * (which every fleet has) carries `OnFailure=` to it. Rendered by
@@ -195,6 +213,13 @@ export interface HostRuntimePlan {
   herdrEnv?: PlannedWrite<string>;
   /** The live plugin config.env {@link herdrEnv} merges into, post-consent. */
   herdrEnvTarget?: string;
+  /**
+   * The Herdr session this host's unit serves, present exactly when
+   * {@link herdrUnit} is. Carried on the plan because the install has to know
+   * which session to prove supervision of (#893), and re-deriving it there
+   * would let the unit's `--session` and the session probed disagree.
+   */
+  herdrSession?: string;
   /**
    * When {@link planTick} rewrote a shared-default `agentName`, the live herdr
    * pane still carries the old identity — the ticking decline that names the
@@ -253,12 +278,21 @@ export interface HostRuntimePlan {
    */
   drift: readonly string[];
   /**
-   * The worker identity plan (#798) when the caller asked for one: the
-   * account/agent-bind/grant steps prepended to {@link steps}, and the
-   * verdict that feeds {@link currentInstall}. Absent on the historical
-   * surface (callers that plan no identity).
+   * Host state this version no longer ships but a previous one installed, and
+   * the ordered steps that retire it (#895). Absent when there is nothing to
+   * retire, which is every host that never ran the separate worker boundary
+   * and every host that has already been converged.
+   *
+   * Retirement is planned rather than merely dropped because deleting the
+   * provisioning code cannot unmount anything: the `.mount` unit an earlier
+   * release enabled stays enabled across upgrades, and a bind of the
+   * operator's install would keep being mounted at a path nothing reads. So
+   * the steps run FIRST in {@link steps}, and while any of them are owed
+   * {@link currentInstall} is false — a re-run that reported "already current"
+   * with the obsolete mount still active is exactly the half-applied
+   * retirement this exists to prevent.
    */
-  workerIdentity?: WorkerIdentityPlan;
+  retire?: HostRetirement;
   /**
    * True when every file the privileged install steps would write is already
    * at its destination with the current bytes. `runHostInstall` uses it to
@@ -464,21 +498,149 @@ function refusal(
   ].join("\n");
 }
 
+/**
+ * Whether a planned step list restarts the Herdr session unit — read off the
+ * exact argv the transaction would run, never a step title, so a renamed step
+ * cannot silently disarm the guard below.
+ */
+function restartsHerdrUnit(steps: readonly PrivilegedStep[]): boolean {
+  return steps.some(
+    (step) =>
+      step.argv[0] === "systemctl" &&
+      step.argv[1] === "restart" &&
+      step.argv[2] === DEFAULT_HERDR_UNIT,
+  );
+}
+
+/**
+ * Refuses a host transaction that would kill the shell running it (#834).
+ *
+ * Herdr panes are children of {@link DEFAULT_HERDR_UNIT}, so the step list's
+ * `systemctl restart` of that unit terminates every pane in the session —
+ * including the one that invoked `setup host`. Measured 2026-08-20: the install
+ * reached `[20/20] restart herdr-fleet.service` and completed, while the calling
+ * OMP pane died at exit 143 with `stopReason: aborted`. The install was fine and
+ * *looked* like a failure, because the process that would have reported and
+ * verified it no longer existed. `upgrade` already refuses this context
+ * outright; this is the same refusal for the other transaction that restarts
+ * the same unit.
+ *
+ * Two conditions, both required, so the refusal is exactly as narrow as the
+ * hazard:
+ *
+ *   - the plan actually restarts the session unit (a host with no herdr unit,
+ *     or a no-op re-run that installs nothing, cannot kill anybody);
+ *   - the caller is inside a Herdr pane (`$HERDR_ENV`), which is the same
+ *     signal {@link upgradeConductor} keys on.
+ *
+ * Refusing *before* any mutation is what makes it safe to refuse at all:
+ * nothing is staged, nothing is installed, and the operator re-runs the whole
+ * transaction from a context that survives it.
+ */
+export function checkSessionRestartContext(
+  verb: string,
+  steps: readonly PrivilegedStep[],
+  env: Record<string, string | undefined> = process.env,
+): EscalationVerdict {
+  const inSession = env["HERDR_ENV"] !== undefined && env["HERDR_ENV"] !== "";
+  if (!inSession || !restartsHerdrUnit(steps)) return { kind: "ok" };
+  return {
+    kind: "refuse",
+    message: [
+      `omp-conductor: run ${verb} from a shell outside the target Herdr session.`,
+      `This transaction restarts ${DEFAULT_HERDR_UNIT}, and this shell is a pane inside it`,
+      "($HERDR_ENV is set). The restart would kill this process mid-install, before it could",
+      "report the outcome or verify anything — a completed install that looks like a failure.",
+      "Nothing has been staged or installed.",
+      "",
+      "Run the same command from a context the restart cannot reach:",
+      `  - a plain login shell on this host (ssh, or a terminal outside herdr), or`,
+      `  - a detached transient unit: systemd-run --collect --unit=omp-conductor-setup-host \\`,
+      `      --property=Type=oneshot --uid="$(id -un)" omp-conductor ${verb} …`,
+      "",
+      "The fleet keeps running until you do; this refusal changed nothing.",
+    ].join("\n"),
+  };
+}
+
+
+/**
+ * Where the fleet's own binaries are looked for, independent of whoever invoked
+ * this process (#890).
+ *
+ * `Bun.which` searches `process.env.PATH` by default, which is how #879's fix
+ * stayed half-done: the staged PATH stopped *containing* caller entries, but
+ * the two directories it derives from `omp-conductor` and `herdr` were still
+ * resolved through the caller's PATH. Under a reduced startup PATH — a systemd
+ * unit, a cron shell, `ssh host '<cmd>'` — `herdr` resolves to null, the staged
+ * unit silently loses its directory (and its `herdr` line entirely), and
+ * `doctor` re-deriving the render in a richer shell reports drift on an install
+ * nobody touched.
+ *
+ * So resolution answers to the host's install layout instead, in this order:
+ *
+ * 1. the directory of the Bun that is executing right now — a global `bun add`
+ *    install puts `omp-conductor` beside it;
+ * 2. this package's own `node_modules/.bin`, when it is installed as a package
+ *    rather than run from a checkout — the binaries that ship with *this* code;
+ * 3. the two conventional per-user bin directories;
+ * 4. the standard system directories the staged unit already carries.
+ *
+ * The caller's PATH is deliberately absent: including it as a fallback would
+ * make the resolved value depend on the invoking shell again, which is the whole
+ * defect. A binary installed somewhere none of these cover is not resolved, and
+ * that renders identically from every shell — a wrong-but-stable answer a
+ * `doctor` finding can name, rather than an answer that changes per caller.
+ */
+export function canonicalBinSearchPath(home: string = homedir()): string {
+  const packageBin = ((): string[] => {
+    // `<root>/node_modules/omp-conductor/omp/src` → `<root>/node_modules/.bin`
+    const marker = `${sep}node_modules${sep}`;
+    const at = import.meta.dir.lastIndexOf(marker);
+    return at === -1 ? [] : [join(import.meta.dir.slice(0, at), "node_modules", ".bin")];
+  })();
+  return [
+    dirname(process.execPath),
+    ...packageBin,
+    join(home, ".bun", "bin"),
+    join(home, ".local", "bin"),
+    ...SERVICE_SYSTEM_PATH.split(":"),
+  ]
+    .filter((value, index, all) => value.length > 0 && all.indexOf(value) === index)
+    .join(":");
+}
 
 export function defaultServiceRuntime(
   telegramStateDir: string,
   // Bridge-resolved session name. Passed in so tests stay hermetic (no herdr
   // spawn) and the renderer never shells out — same threading as telegramStateDir.
   herdrSession: string = resolveHerdrSessionWithBridge(),
+  // The canonical search path (#890), injectable for the same reason: a test
+  // must be able to prove the render does not move when the CALLER's PATH does,
+  // which means controlling what "installed here" means without touching the
+  // process environment the assertion is about.
+  searchPath: string = canonicalBinSearchPath(),
 ): ServiceRuntime {
   const home = homedir();
   const bun = process.execPath;
-  const globalCli = Bun.which("omp-conductor");
-  const herdr = Bun.which("herdr");
+  // Resolved against the canonical install layout, never `process.env.PATH`:
+  // the whole point of #890 is that these two directories are facts about the
+  // host, not about the shell that happened to run setup or doctor.
+  const globalCli = Bun.which("omp-conductor", { PATH: searchPath });
+  const herdr = Bun.which("herdr", { PATH: searchPath });
   const loginShell = userInfo().shell;
-  const pathParts = [dirname(bun), ...(process.env["PATH"] ?? "").split(":")].filter(
-    (value, index, all) => value.length > 0 && all.indexOf(value) === index,
-  );
+  // #879: the staged PATH is a canonical host-runtime value — the directories
+  // of the binaries this runtime resolved plus SERVICE_SYSTEM_PATH — never the
+  // invoking shell's PATH. Caller entries (/root/bin, /opt/puppetlabs/bin, …)
+  // once leaked into the staged units, so `doctor` re-deriving the render in
+  // its own process reported PATH drift against byte-identical installs, and
+  // rerunning setup reproduced the finding its own fix text prescribes away.
+  const pathParts = [
+    dirname(bun),
+    ...(globalCli === null ? [] : [dirname(globalCli)]),
+    ...(herdr === null ? [] : [dirname(herdr)]),
+    ...SERVICE_SYSTEM_PATH.split(":"),
+  ].filter((value, index, all) => value.length > 0 && all.indexOf(value) === index);
   return {
     username: userInfo().username,
     home,
@@ -643,60 +805,6 @@ export function renderRecoverUnit(runtime: ServiceRuntime, projectName: string |
   ].join("\n");
 }
 
-/**
- * The worker harness binding (#828): a read-only bind of the operator's
- * `node_modules` at {@link WORKER_HARNESS_NODE_MODULES}, which is how a worker
- * session reaches the exact harness build installed alongside omp-conductor.
- *
- * A bind rather than a copy, because the two must never diverge: it shares
- * inodes with the source, so an operator who upgrades the harness upgrades what
- * every worker loads, with no mirror to re-materialise and no window in which a
- * worker runs last week's build.
- *
- * `ro` because a session has no business writing the install; `nosuid,nodev`
- * because a tree the worker account reads should carry neither. Never `noexec`:
- * the harness dlopens its native addon out of this tree, and `noexec` refuses
- * the executable mapping that needs.
- *
- * The ordering edge lives here rather than in the daemon unit, and that is not
- * a style choice. Both units are pulled in by `multi-user.target`, so without
- * an edge a reboot can start the daemon first — and although dispatch
- * re-resolves the binding per launch (so the fleet recovers on the next tick
- * rather than needing a restart), ordering removes the window instead of
- * tolerating it. It is declared as `Before=` on the mount because the *daemon*
- * unit's name needs no escaping: systemd does not resolve a `\x2d`-escaped unit
- * name written into a dependency setting back to the real unit, so the reverse
- * spelling silently binds nothing (verified on a live host).
- *
- * Deliberately not `Requires=`/`RequiresMountsFor=` from the daemon: those
- * would keep the control plane down whenever the bind failed, and a daemon that
- * is up and refusing worker launches with the reason is what an operator can
- * actually diagnose.
- */
-export function renderHarnessMountUnit(packageRoot: string): string {
-  return [
-    "[Unit]",
-    "Description=omp-conductor worker harness binding",
-    "Documentation=https://github.com/TerrifiedBug/conductor",
-    // The source is a directory on some filesystem; systemd must have that
-    // filesystem before it can bind anything out of it.
-    `RequiresMountsFor=${systemdPath(packageRoot)}`,
-    // Ordering only, never a requirement: the daemon must not be started before
-    // the bind exists, but a failed bind must not keep the control plane down.
-    `Before=${STAGED_SERVICE_NAME}`,
-    "",
-    "[Mount]",
-    `What=${systemdPath(packageRoot)}`,
-    `Where=${systemdPath(WORKER_HARNESS_NODE_MODULES)}`,
-    "Type=none",
-    "Options=bind,ro,nosuid,nodev",
-    "",
-    "[Install]",
-    "WantedBy=multi-user.target",
-    "",
-  ].join("\n");
-}
-
 /**
  * Whether a login-shell value may be pinned into herdr's config at all.
  *
@@ -1099,964 +1207,164 @@ function planBriefLink(project: ProjectConfig): BriefLinkPlan {
   };
 }
 
-// -------------------------------------------------- worker identity plan (#798) --
-
-/** The fleet agent-config files the worker home binds (when they exist):
- *  provided read-only, never copied — the fleet stays the single source, and
- *  the worker cannot edit what it only reads. `.env` is where MCP secrets
- *  live; `AGENTS.md` is the mandatory host policy every session must read. */
-const WORKER_AGENT_LINK_FILES = ["config.yml", "models.yml", "mcp.json", ".env", "AGENTS.md"] as const;
-
-/** The fleet agent-config directories the worker home binds (when they exist):
- *  skills, managed skills, extensions and scripts are the harness's read-only
- *  discovery roots. */
-const WORKER_AGENT_LINK_DIRS = ["commands", "prompts", "skills", "managed-skills", "extensions", "scripts"] as const;
-
 /**
- * Read-only facts the identity plan is computed from, all injectable so tests
- * pin the plan hermetically. Production defaults probe the real host: the
- * account's presence in /etc/passwd, the on-disk agent config, and (through
- * `getfacl`) whether the grants are already in place.
+ * Read-only facts about who is serving the fleet's Herdr session.
+ *
+ * Deliberately two independent reads rather than one: herdr answers whether the
+ * *session* is served, systemd answers whether the *unit* is serving anything,
+ * and the incident this exists for is exactly the case where those two
+ * disagree.
  */
-export interface WorkerIdentityProbes {
-  /** Whether this host can run the account/ACL machinery at all (Linux). */
-  linux?: boolean;
-  /** Whether the worker account already exists. */
-  accountExists?: boolean;
-  /** Whether `setfacl` is installed. */
-  setfaclInstalled?: boolean;
-  /** The fleet agent-config files to bind into the worker home and grant read
-   *  access to (existing files only — absent ones are nothing to bind). */
-  configFiles?: readonly string[];
-  dirExists?(path: string): boolean;
-  /** Whether a path is searchable by other accounts (mode `o+x`). */
-  searchable?(path: string): boolean;
-  /** Whether `path` is a symlink resolving to `target`. */
-  linkCurrent?(path: string, target: string): boolean;
-  /** Whether the worker account already holds *effective* `perms` on `path`
-   *  through an ACL — the named entry intersected with the mask, never the
-   *  named entry alone (#835). */
-  aclCurrent?(path: string, perms: "x" | "r"): boolean;
-  /** Whether the operator's auth database (`<agentDir>/agent.db`) exists to
-   *  copy into the worker's runtime. */
-  agentDbPresent?: boolean;
-  /** Whether the worker's own writable copy of the auth database exists. */
-  workerAuthDbCurrent?: boolean;
-  /** Whether the operator's `~/.config/gh` credentials exist to copy. */
-  ghConfigPresent?: boolean;
-  /** Whether the worker's copy of the gh credentials exists. */
-  workerGhConfigCurrent?: boolean;
-  /** Whether the operator's `~/.gitconfig` exists to copy. */
-  gitconfigPresent?: boolean;
-  /** Whether the worker's copy of the git identity exists. */
-  workerGitconfigCurrent?: boolean;
-  /**
-   * Whether {@link WORKER_HARNESS_DIR} is currently restricted exactly as the
-   * worker needs it (#831): owned by root, its group the worker account's live
-   * primary gid, group read+execute, and no `other` permissions. False when it
-   * is drifted — wrong owner or group, missing group access, world-readable —
-   * including when it is absent (systemd would create a missing mount point at
-   * 0755) or unverifiable. Replaces the earlier other-bits-only check, which
-   * read `0750 root:root` as current because it had no `other` bits while the
-   * worker could not traverse it.
-   */
-  harnessDirRestricted?: boolean;
+export interface HerdrOwnershipFacts {
   /**
-   * Why the worker harness binding is not usable, or `undefined` when it is
-   * live (#828). A function, not a value, so the non-Linux plan never pays for
-   * a probe it will not consult; production reads the host through
-   * {@link harnessBindingProblem}.
+   * Whether the target session has a live server, from herdr's own session
+   * list. `undefined` when that could not be read — never `false`, because
+   * "herdr did not answer" and "no server" lead to opposite actions.
    */
-  harnessProblem?: () => string | undefined;
-}
-
-/** The worker account's presence in /etc/passwd, the resolution's source of
- *  truth; unreadable passwd means "not present" for planning purposes. */
-function passwdHasAccount(): boolean {
-  try {
-    return readFileSync("/etc/passwd", "utf8")
-      .split("\n")
-      .some((entry) => entry.startsWith(`${WORKER_ACCOUNT}:`));
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Whether a `getfacl -p -c` dump proves that `account`'s **effective**
- * permissions on one path include `perms`. The named entry alone is not
- * enough: a later `chmod` of the path rewrites the ACL mask, and an entry the
- * mask strips reads `user:omp-worker:--x  #effective:---` while its granted
- * bits still carry the letter — the post-restart shape #835 fell into. The
- * effective permissions are the named entry intersected with the mask — the
- * same result getfacl renders as the `#effective:` annotation, computed here
- * so a host whose getfacl omits the annotation cannot slip a
- * named-but-ineffective ACL past the verdict, and an entry for any other
- * account never counts as this account's grant.
- */
-export function aclEffectivePermits(dump: string, account: string, perms: "x" | "r"): boolean {
-  let entryPerms: string | undefined;
-  let maskPerms: string | undefined;
-  for (const raw of dump.split("\n")) {
-    const line = raw.trim();
-    if (line.startsWith("#")) continue;
-    // `user:omp-worker:r-x`; the trailing `#effective:...` annotation (when
-    // present) is after the perms and irrelevant to the match.
-    if (line.startsWith(`user:${account}:`)) {
-      entryPerms = /^([r-][w-][x-])/.exec(line.slice(`user:${account}:`.length))?.[1];
-    } else if (line.startsWith("mask:")) {
-      // A mask line renders as `mask::r-x` (the name field is empty).
-      maskPerms = /^([r-][w-][x-])/.exec(line.slice("mask:".length).replace(/^:+/u, ""))?.[1];
-    }
-  }
-  if (entryPerms === undefined) return false;
-  const effective =
-    maskPerms === undefined
-      ? entryPerms
-      : [0, 1, 2]
-          .map((i) => (entryPerms[i] === "-" || maskPerms[i] === "-" ? "-" : maskPerms[i]) as string)
-          .join("");
-  return perms === "r" ? effective[0] === "r" : effective[2] === "x";
-}
-
-/** Whether one path already grants the worker's *effective* ACL permissions
- *  for `perms`, read through `getfacl -p -c` and judged by the mask
- *  intersection ({@link aclEffectivePermits}). A host without getfacl, an
- *  unreadable path, or a path whose ACL entry is masked off all report "not
- *  current" — the grant steps then run, the safe direction for an unverifiable
- *  grant. Exported so `doctor` reads the live host through the same probe the
- *  identity plan plans with (#835). */
-export function workerAclProbe(path: string, perms: "x" | "r"): boolean {
-  const ran = spawnSync("getfacl", ["-p", "-c", path], { encoding: "utf8" });
-  if (ran.status !== 0 || ran.stdout === null) return false;
-  return aclEffectivePermits(ran.stdout, WORKER_ACCOUNT, perms);
-}
-
-/** The linked worker config paths' effective-ACL verdict for the dedicated
- *  worker account: how many paths were checkable, and which of them do not
- *  currently grant the worker's needed effective access. */
-export interface WorkerAclHealth {
-  /** The agent config dir plus every existing linked config file. */
-  checkable: number;
-  /** The checkable paths whose grant is not effective — the named entry is
-   *  absent, the path is unreadable, or the ACL mask strips the entry's
-   *  effective permissions (#835). */
-  missing: readonly string[];
-}
-
-/**
- * The linked worker config paths (search `x` on the agent config dir and its
- * existing ancestors that other accounts cannot already traverse, read `r` on
- * every existing linked config file) with each path's effective-ACL verdict
- * for the worker account. Pure of any privilege: the paths are read-only and
- * every verdict is {@link workerAclProbe}'s own read, so `doctor` and the
- * identity plan cannot disagree about an ACL (#835).
- */
-export function workerAclHealth(agentDir: string): WorkerAclHealth {
-  const targets: [string, "x" | "r"][] = [];
-  // The same ancestor rule the identity plan's grantPaths applies to this
-  // root: only the existing segments other accounts cannot already traverse
-  // (mode `o+x`) need an ACL at all. The harness chmods the leaf back to 0700
-  // on every open, so the leaf is virtually always in this set.
-  const parts = resolve(agentDir)
-    .split("/")
-    .filter((part) => part !== "");
-  let cur = "/";
-  for (const part of parts) {
-    cur = cur === "/" ? `/${part}` : `${cur}/${part}`;
-    let st: Stats | undefined;
-    try {
-      st = statSync(cur);
-    } catch {
-      break;
-    }
-    if (!st.isDirectory()) break;
-    if ((st.mode & 0o001) === 0) targets.push([cur, "x"]);
-  }
-  for (const name of WORKER_AGENT_LINK_FILES) {
-    const file = join(agentDir, name);
-    if (existsSync(file)) targets.push([file, "r"]);
-  }
-  const missing = targets
-    .filter(([path, perms]) => !workerAclProbe(path, perms))
-    .map(([path]) => path);
-  return { checkable: targets.length, missing };
+  sessionRunning: boolean | undefined;
+  /** The canonical unit as systemd reports it, or `undefined` when unreadable. */
+  unit:
+    | {
+        activeState: string;
+        subState: string;
+        mainPid: number;
+        /** How many times systemd has restarted it — a loop's own tell. */
+        nRestarts: number;
+      }
+    | undefined;
 }
 
-// --------------------------------------------------- pane settle gate (#835) --
-
-/**
- * How many 1-second probes the {@link paneSettleScript} gate may take before
- * declaring the restored pane's startup chmod unsettled. A herdr pane boots in
- * well under this on a healthy host; every extra probe delays setup by one
- * second, so the bound is deliberately short.
- */
-export const AGENT_SETTLE_PROBE_STEPS = 12;
-
-/**
- * How long a settled mask must stay settled before the gate lets the grants
- * through: two consecutive reads a probe-interval apart, so a boot churn of
- * two panes still reads unsettled.
- */
-export const AGENT_SETTLE_PROBE_INTERVAL_S = 1;
+export type HerdrOwnership =
+  /** The canonical unit is up and is the only thing that can be serving it. */
+  | { kind: "unit"; detail: string }
+  /** A live session the canonical unit is not serving: the #893 collision. */
+  | { kind: "unmanaged"; detail: string }
+  /** No live session at all — a fresh host, or one whose server is down. */
+  | { kind: "absent"; detail: string }
+  /** A read failed. Never treated as either of the decided answers. */
+  | { kind: "unknown"; detail: string };
 
 /**
- * The bounded readiness barrier the final ACL grants wait on. `systemctl
- * restart herdr-fleet.service` returns when herdr's own (Type=simple) server
- * process is up — the restored OMP panes boot *after* that, and each pane's
- * AgentStorage ctor chmods the fleet agent config dir back to 0700 on open. A
- * chmod rewrites the ACL mask, so a grant that lands before that chmod is
- * `user:omp-worker:--x  #effective:---` again within seconds (#835).
+ * Who owns the fleet session (#893).
  *
- * The gate reads two things: the agent dir's ACL mask, and the live herdr
- * agent list. A mask is *settled* when it is zeroed (`---`, what a startup
- * chmod leaves) or absent altogether (an ACL-less dir — the shape of every
- * first-ever `setup host`, whose grants have not run yet because they run
- * *after* this gate). Neither reading, on its own, says anything about *this*
- * restart: the #835 host starts with a zeroed mask, because a previous grant
- * plus a previous pane's chmod already left one, and an absent mask cannot
- * render a chmod at all. So on a herdr host a settled mask releases the grants
- * only once this restart has positively observed a live agent: herdr lists a
- * pane as an agent when that pane's OMP process registers, which is after the
- * `AgentStorage` open that chmods, so a live row is the one witness available
- * that the chmod is behind us. With the witness in hand the gate wants the
- * mask settled on two consecutive probes (nothing is churning) and exits 0.
+ * `setup host` can complete its whole transaction successfully while
+ * `herdr-fleet.service` sits in `activating (auto-restart)`: an unmanaged
+ * `herdr --session <name> server` already holds the session, so every start of
+ * the unit exits 1, the panes stay under the unmanaged process, and dispatch
+ * stays paused after a green setup. Measured 2026-08-22T09:01:31Z: exit 0,
+ * `NRestarts=2`, `ExecStart` status 1, the real fleet under
+ * `herdr session attach` ancestry. A `systemctl restart` returning 0 is
+ * therefore not evidence that supervision transferred — `Type=simple` returns
+ * before the child discovers the collision and dies.
  *
- * Both halves of that rule were learned the hard way. Demanding a literal
- * `mask::---` line deadlocked first-run setup outright, since that line cannot
- * appear before the grants that create it (#835 review 3); releasing on a
- * settled mask without the witness let a pane that registered late chmod after
- * the grants had already verified — #835 again, first for the absent mask
- * (review 4) and then for the stale zeroed one (review 5).
+ * The reasoning behind the verdicts, since only one of them is an observation:
  *
- * What the gate still cannot promise, the grant says for itself: each grant
- * step verifies its own effective result and fails the transaction when a
- * chmod lands inside its window, and a chmod later than that makes the
- * identity pending again — `doctor`'s `worker-acl` finding names it and an
- * idempotent `setup host` re-run re-grants behind the full gate. A `getfacl`
- * that could not read the path is not a settled mask — it prints no mask
- * because it printed nothing — so it stays unsettled. A host whose herdr
- * restores panes as plain shells — the `resume_agents_on_restore = false`
- * headless shape, which the pane-shell merge writes and `doctor` blesses —
- * restores *no* agent process, so no witness will ever come and nothing will
- * ever chmod: the gate reads the agent list through its CLI envelope,
- * `{"id":"cli:agent:list","result":{"agents":[…]}}`, the shape
- * `parseHerdrAgents` reads, and treats a window in which `result.agents` was
- * explicitly empty on *every* probe as a legitimate pass — the full window,
- * never an early release. A list it could not read is not that window: a
- * nonzero `herdr` exit or an unrecognized schema proves nothing about whether
- * a pane is about to chmod, so it fails the gate on its own (#835 review 2)
- * rather than buying the agentless pass. A host with no herdr at all restores
- * no pane and needs no witness, so there a settled mask releases on its own
- * two probes. If an agent is live but the mask never settles within the probe
- * bound — a still-booting pane, or a mask that keeps changing — the gate exits
- * 1 and the transaction stops: no grant is bet against a still-booting pane
- * (fail closed, per #835 review 1).
- */
-export function paneSettleScript(
-  agentDir: string,
-  herdr: string | undefined,
-  session: string,
-  steps: number = AGENT_SETTLE_PROBE_STEPS,
-  intervalS: number = AGENT_SETTLE_PROBE_INTERVAL_S,
-): string {
-  const sq = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`;
-  const agentProbe = herdr === undefined ? "" : `${sq(herdr)} --session ${sq(session)} agent list`;
-  return [
-    `# The herdr restart returned once herdr's own process was up; the restored`,
-    `# OMP panes boot after it and each chmods the agent config dir to 0700 in`,
-    `# AgentStorage -- a chmod that rewrites the ACL mask. The grants that follow`,
-    `# this gate may only land once that startup chmod is behind us (#835).`,
-    `# A mask is settled when it is zeroed ('---', what a chmod leaves) or`,
-    `# absent (a dir with no extended ACL: nothing has been granted yet, so`,
-    `# there is no named entry a later chmod could strip -- #835 review 3).`,
-    `# Neither reading identifies *this* restart on its own: this host starts`,
-    `# with a zeroed mask left by an earlier grant and an earlier pane, and an`,
-    `# absent mask cannot render a chmod at all. So wherever a pane can exist,`,
-    `# a settled mask releases the grants only with a live agent to witness the`,
-    `# chmod -- see the loop below (#835 reviews 4 and 5). The command's status`,
-    `# is kept outside the pipe so a getfacl that cannot read the path stays`,
-    `# unsettled rather than passing as a mask-less dir.`,
-    `probe() { # prints the mask's perms; empty output = the ACL carries no mask`,
-    `  if ! acl=$(getfacl -p -c ${sq(agentDir)} 2>/dev/null); then return 1; fi`,
-    `  printf '%s\\n' "$acl" | sed -nE 's/^mask::([r-][w-][x-])$/\\1/p'`,
-    `}`,
-    ...(herdr === undefined
-      ? []
-      : [
-          `# 'herdr agent list' answers with its CLI envelope --`,
-          `# {"id":"cli:agent:list","result":{"agents":[...]}} -- and never a bare`,
-          `# array, so an explicitly empty list still prints a non-empty object and`,
-          `# a substring test for '[]' would read every host as agent-bearing. The`,
-          `# project's own parser (parseHerdrAgents) reads that envelope, but it is`,
-          `# TypeScript and this gate is a privileged shell step, so its contract is`,
-          `# reproduced here: result.agents non-empty is a live agent, an explicitly`,
-          `# empty result.agents is an agentless host, and everything else -- a`,
-          `# nonzero exit, no output, an unrecognized schema -- is unreadable. The`,
-          `# command's status is captured outside a pipe so a failure stays a`,
-          `# failure: an unreadable list is never an authoritative empty success,`,
-          `# because it cannot prove no pane will chmod the mask (#835 review 2).`,
-          `agents() { # 0 = an agent is live, 1 = an explicitly empty list, 2 = unreadable`,
-          `  if ! out=$(${agentProbe} 2>/dev/null); then return 2; fi`,
-          `  out=$(printf '%s' "$out" | tr -d ' \\t\\r\\n')`,
-          `  case "$out" in`,
-          `    *'"agents":[]'*) return 1 ;;`,
-          `    *'"agents":['*) return 0 ;;`,
-          `    *) return 2 ;;`,
-          `  esac`,
-          `}`,
-        ]),
-    `zero=0`,
-    ...(herdr === undefined ? [] : [`agents_seen=0`, `list_unreadable=0`]),
-    `for _ in $(seq 1 ${String(steps)}); do`,
-    ...(herdr === undefined
-      ? []
-      : [
-          `  # The agent list is read before the mask is judged: a settled mask is`,
-          `  # evidence only once a live agent has been observed, so the read that`,
-          `  # can establish that must come first (#835 reviews 4 and 5).`,
-          `  agents; rc=$?`,
-          `  if [ "$rc" -eq 0 ]; then agents_seen=1; elif [ "$rc" -eq 2 ]; then list_unreadable=1; fi`,
-        ]),
-    `  if mask=$(probe); then`,
-    `    case "$mask" in`,
-    // A zeroed mask and an absent one are the same verdict — settled — and on
-    // a herdr host they carry the same burden of proof.
-    `      ''|'---')`,
-    ...(herdr === undefined
-      ? [
-          // No herdr is no restored pane and no process that could ever chmod,
-          // so there is no witness to want: the mask speaks for itself.
-          `        zero=$((zero + 1))`,
-          `        if [ "$zero" -ge 2 ]; then exit 0; fi`,
-        ]
-      : [
-          `        # A settled mask needs a witness that the startup chmod is behind`,
-          `        # us, because neither settled shape can show one: this host begins`,
-          `        # with a mask an earlier grant and an earlier pane already zeroed,`,
-          `        # and an ACL-less dir has no mask to zero. A live agent is that`,
-          `        # witness -- herdr lists a pane as an agent once that pane's OMP`,
-          `        # process has registered, which is after the AgentStorage open that`,
-          `        # chmods. A list that has only ever been empty is indistinguishable`,
-          `        # from a pane that has not started yet, so it releases nothing`,
-          `        # (#835 reviews 4 and 5); a window that stays empty for its whole`,
-          `        # length is the headless pass below instead.`,
-          `        if [ "$agents_seen" = 1 ]; then`,
-          `          zero=$((zero + 1))`,
-          `          if [ "$zero" -ge 2 ]; then exit 0; fi`,
-          `        else`,
-          `          zero=0`,
-          `        fi`,
-        ]),
-    `        ;;`,
-    `      *) zero=0 ;;`,
-    `    esac`,
-    `  else`,
-    `    zero=0`,
-    `  fi`,
-    `  sleep ${String(intervalS)}`,
-    `done`,
-    ...(herdr === undefined
-      ? []
-      : [
-          // No agent existed at any probe, every probe read the list, and the
-          // mask never settled: the restart restored nothing that could chmod,
-          // so the grants are safe to land — the ever-clean shape is a pass,
-          // not a failure.
-          `if [ "$agents_seen" = 0 ] && [ "$list_unreadable" = 0 ]; then exit 0; fi`,
-          // A list we could not read is its own failure, distinct from an empty
-          // one: it proves nothing about whether a pane is about to chmod, so
-          // it may not buy the agentless pass.
-          `if [ "$agents_seen" = 0 ]; then`,
-          `  printf '%s\n' "could not read the live herdr agent list (${agentProbe} exited nonzero or answered without a result.agents array) -- refusing to treat an unreadable agent list as an agentless host and grant an ACL a restored pane may zero" >&2`,
-          `  exit 1`,
-          `fi`,
-        ]),
-    `printf '%s\n' "the restored fleet agent pane never settled: ${sq(agentDir)} did not hold a settled ACL mask${herdr === undefined ? "" : " with a live herdr agent to witness the pane's startup chmod"} within ${String(steps * intervalS)}s -- refusing to grant an ACL a still-booting pane may zero again" >&2`,
-    `exit 1`,
-  ].join("\n");
-}
-
-/**
- * The worker account's primary gid on this host, resolved live from
- * `/etc/passwd` — the account line's fourth field (`name:x:uid:gid:…`) — or
- * `undefined` when it cannot be determined: an absent account, a malformed or
- * unreadable passwd. `undefined` is not a gid: the harness directory can never
- * be "current" while we cannot say which group it must accept.
+ *   - A live session with the unit **not** active is decided: something outside
+ *     the unit is serving it. Nothing else can be true.
+ *   - A live session with the unit active *is* the unit's, because two servers
+ *     cannot hold one session — that mutual exclusion is precisely what makes
+ *     the collision fatal, so it is also what makes this inference sound.
+ *   - Either read failing is `unknown`, which callers must treat as a refusal
+ *     rather than as "probably fine": the destructive remedy here is stopping
+ *     somebody's live session.
  */
-export function resolveWorkerGroupGid(): number | undefined {
-  let line: string | undefined;
-  try {
-    line = readFileSync("/etc/passwd", "utf8")
-      .split("\n")
-      .find((entry) => entry.startsWith(`${WORKER_ACCOUNT}:`));
-  } catch {
-    return undefined;
+export function herdrOwnership(facts: HerdrOwnershipFacts): HerdrOwnership {
+  if (facts.sessionRunning === undefined) {
+    return {
+      kind: "unknown",
+      detail: "herdr could not say whether the fleet session has a live server",
+    };
   }
-  if (line === undefined) return undefined;
-  const gid = Number.parseInt(line.split(":")[3] ?? "", 10);
-  return Number.isInteger(gid) && gid >= 0 ? gid : undefined;
-}
-
-/** The live ownership/access facts the {@link WORKER_HARNESS_DIR} verdict
- *  compares — and only those, so the decision stays pure of stat and
- *  privilege and every drift shape can be pinned hermetically. */
-export interface HarnessDirFacts {
-  uid: number;
-  gid: number;
-  mode: number;
-}
-
-/**
- * Read {@link WORKER_HARNESS_DIR}'s facts for the currentness verdict, or
- * `undefined` when the path is missing, unreadable, or not a directory —
- * each of which must read pending (#831).
- */
-export function harnessDirFacts(dir: string = WORKER_HARNESS_DIR): HarnessDirFacts | undefined {
-  let st: Stats;
-  try {
-    st = statSync(dir);
-  } catch {
-    return undefined;
+  if (facts.unit === undefined) {
+    return {
+      kind: "unknown",
+      detail: "systemctl could not say what state the fleet session unit is in",
+    };
+  }
+  const { activeState, subState, mainPid, nRestarts } = facts.unit;
+  const unitServing = activeState === "active" && subState === "running" && mainPid > 0;
+  if (!facts.sessionRunning) {
+    return {
+      kind: "absent",
+      detail: unitServing
+        ? `the unit is ${activeState} (${subState}) but no session server answers — it is coming up`
+        : `no live fleet session server (unit ${activeState}/${subState})`,
+    };
+  }
+  if (unitServing) {
+    return { kind: "unit", detail: `served by ${DEFAULT_HERDR_UNIT} (pid ${mainPid})` };
   }
-  if (!st.isDirectory()) return undefined;
-  return { uid: st.uid, gid: st.gid, mode: st.mode };
-}
-
-/**
- * Whether the harness directory is restricted exactly as the worker needs it
- * (#831): owned by root (uid 0), its group the worker account's live primary
- * gid, group read+execute, and no `other` bits — the `0750 root:<worker gid>`
- * shape the install-d step converges to. `facts` `undefined` (a missing,
- * unreadable, or non-directory path) or a `workerGid` `undefined` (an absent
- * account or unreadable passwd) both read `false`: an unverifiable directory
- * is pending, never "current". The old check read only the `other` bits and
- * called `0750 root:root` current; this compares every dimension the worker's
- * traversal depends on.
- */
-export function harnessDirRestricted(
-  facts: HarnessDirFacts | undefined,
-  workerGid: number | undefined,
-): boolean {
-  if (facts === undefined || workerGid === undefined) return false;
-  if (facts.uid !== 0 || facts.gid !== workerGid) return false;
-  if ((facts.mode & 0o050) !== 0o050) return false;
-  if ((facts.mode & 0o007) !== 0) return false;
-  return true;
-}
-
-/**
- * The production probes: the real host, read-only. Built from the fleet
- * runtime so the agent-config source is the fleet account's own agent dir.
- */
-export function defaultIdentityProbes(runtime: { home: string; bun?: string }): WorkerIdentityProbes {
-  const agentDir = join(runtime.home, ".omp", "agent");
-  const workerAgentDir = join(WORKER_HOME_DIR, ".omp", "agent");
-  const dirExists = (path: string): boolean => {
-    try {
-      return statSync(path).isDirectory();
-    } catch {
-      return false;
-    }
-  };
   return {
-    linux: process.platform === "linux",
-    accountExists: passwdHasAccount(),
-    setfaclInstalled: existsSync("/usr/bin/setfacl"),
-    configFiles: WORKER_AGENT_LINK_FILES.filter((name) => existsSync(join(agentDir, name))).map(
-      (name) => join(agentDir, name),
-    ),
-    dirExists,
-    searchable: (path) => {
-      try {
-        return (statSync(path).mode & 0o001) !== 0;
-      } catch {
-        return false;
-      }
-    },
-    linkCurrent: (path, target) => {
-      try {
-        return lstatSync(path).isSymbolicLink() && readlinkSync(path) === target;
-      } catch {
-        return false;
-      }
-    },
-    aclCurrent: workerAclProbe,
-    // The provisioned runtime (#798 review 2): the worker owns a copy of the
-    // auth database (the harness writes perf/settings into it — a link would
-    // let the worker mutate the operator's), scoped copies of the gh
-    // credentials and git identity, and read-only binds for everything else.
-    agentDbPresent: existsSync(join(agentDir, "agent.db")),
-    workerAuthDbCurrent: existsSync(join(workerAgentDir, "agent.db")),
-    ghConfigPresent: existsSync(join(runtime.home, ".config", "gh", "hosts.yml")),
-    workerGhConfigCurrent: existsSync(join(WORKER_HOME_DIR, ".config", "gh", "hosts.yml")),
-    gitconfigPresent: existsSync(join(runtime.home, ".gitconfig")),
-    workerGitconfigCurrent: existsSync(join(WORKER_HOME_DIR, ".gitconfig")),
-    // Setup currentness is the effective import contract, not just mount
-    // metadata: after the inode check passes, execute the same anchored loader
-    // with --no-install through the real HOME/setpriv transition. A mounted
-    // tree whose Bun resolution still reaches the worker cache is pending.
-    harnessProblem: () =>
-      harnessBindingProblem() ?? workerHarnessImportProblem({ bun: runtime.bun ?? process.execPath }),
-    // The bound tree's reach (#828 review), hardened to the directory's whole
-    // shape (#831): the verdict is a live ownership/access check read fresh on
-    // every planning run — root-owned, group the worker's live primary gid,
-    // group read+execute, and no `other` bits. A re-run of `setup host` after
-    // an operator chown/chmod'd the mount point re-checks rather than trusting
-    // a stale verdict, and absent or unverifiable reads pending (the safe
-    // direction): systemd would create a missing mount point at 0755, so "not
-    // there yet" and "world-readable" have always shared one step.
-    harnessDirRestricted: harnessDirRestricted(harnessDirFacts(), resolveWorkerGroupGid()),
+    kind: "unmanaged",
+    detail:
+      `the fleet session has a live server, but ${DEFAULT_HERDR_UNIT} is ${activeState} (${subState})` +
+      `${nRestarts > 0 ? `, restarted ${nRestarts} time(s)` : ""} with no main pid — ` +
+      "the session is held outside systemd, so every start of the unit exits 1",
   };
 }
 
-export interface WorkerIdentityPlanOptions {
-  /** The daemon's state root (worktrees, mirrors, sessions live under it). */
-  stateRoot: string;
-  /** The fleet account's agent config dir. */
-  agentDir: string;
-  /** The directory holding the bun binary the worker sessions exec. */
-  bunRoot: string;
-  /** The node_modules root of the installed conductor package. */
-  packageRoot: string;
-  /** The fleet account's home: the source of the gh credentials and git
-   *  identity the worker runtime is provisioned from. */
-  home: string;
-  probes?: WorkerIdentityProbes;
-}
-
-/**
- * The identity plan's outcome: the steps that establish it, and why any are
- * still pending. {@link steps} and {@link grantSteps} together are the single
- * source the install renders and executes, exactly like the host runtime's
- * own steps.
- */
-export interface WorkerIdentityPlan {
-  account: string;
-  home: string;
-  /** The worker's harness agent dir (where the fleet config is bound). */
-  agentDir: string;
-  /** Dirs granted search access (`o+x`-style ACL), for the plan display. */
-  grantPaths: readonly string[];
-  /** Fleet agent config files granted read access, for the plan display. */
-  configFiles: readonly string[];
-  /** The steps that establish the identity before the daemon restart can
-   *  resolve it: account creation, the agent-config bind, and the runtime
-   *  provision. Prepended to the host plan's own steps. */
-  steps: readonly PrivilegedStep[];
-  /**
-   * The ACL grant steps, deliberately **not** in {@link steps}: they must
-   * execute *after* the transaction's final daemon and herdr restarts, behind
-   * the bounded pane settle gate {@link planHostRuntime} places ahead of them.
-   * An OMP startup chmods its agent config dir back to 0700 on every open —
-   * the harness's own `AgentStorage` boot — and a chmod rewrites the ACL
-   * mask, so a grant applied before the restarts is `user:omp-worker:--x
-   * #effective:---` by the time a worker reads it, and a grant applied before
-   * a restored pane has finished booting can still be zeroed moments later
-   * (#835). Each grant step also verifies its own effective result through
-   * getfacl and exits nonzero — stopping the transaction — when the ACL mask
-   * strips the worker's entry.
-   */
-  grantSteps: readonly PrivilegedStep[];
-  /** One item per pending change, in the order the steps would make them. */
-  pending: readonly string[];
-  /** True when every step is already satisfied — nothing to do. */
-  current: boolean;
-}
-
 /**
- * The plan that establishes the dedicated worker identity on this host
- * (#798), in the same shape as the rest of the host plan: privileged steps
- * with human titles, a read-only "current" verdict, and the reasons anything
- * is pending. The steps are idempotent by construction — the account step is
- * guarded by `getent`, the bind uses `ln -sfn`, and `setfacl -m` converges —
- * so a re-run of `setup host` converges rather than failing on a half-applied
- * prior run.
+ * What this version retires from the host, read from disk (#895).
  *
- * The grants are deliberate and narrow: search access (`x`, never `r` or `w`)
- * down the existing ancestor chains of the state root, the bun install and
- * the package root (their own modes are already world-searchable), plus read
- * access on the fleet's 0600 agent config files. The worker's writable world
- * is what dispatch chowns to it per run — worktree and session dir — and
- * nothing else. It cannot write daemon state (no grant writes), and it cannot
- * migrate itself into a daemon-owned cgroup (every cgroup.procs is
- * root-owned).
- */
-/**
- * A shell guard the privileged worker-identity steps run first (#816): the
- * worker owns everything under its home between setups, so a worker-planted
- * symlink on any component of a directory root is about to create or hand
- * back would redirect that mkdir / cp / chown to an arbitrary target — `chown
- * omp-worker /etc`, or a copy written into it. Every component of each named
- * target is checked, and the first symlink fails the whole step, naming the
- * component, before anything follows it.
+ * One entry today — the worker harness bind mount 0.18.1 installed — and the
+ * shape is deliberately a list, because "the release that removes a unit" is a
+ * recurring event and the alternative is a bespoke check each time.
+ *
+ * Ordering is the whole content of the step list:
  *
- * Executed verbatim in the step scripts, so the definition lives here, in the
- * shape the tests read.
+ *   1. `disable --now` first, which stops (for a `.mount`: unmounts) and drops
+ *      the enablement symlinks in one call. Doing it before the file is gone
+ *      matters — systemd cannot disable a unit whose file it can no longer
+ *      read, so removing first would strand the enablement symlink and leave
+ *      the mount live until reboot.
+ *   2. Then remove the installed file, then one `daemon-reload` so systemd
+ *      forgets the unit rather than keeping it loaded-but-absent.
+ *   3. Then `rmdir` the empty mount point, best-effort: it refuses a non-empty
+ *      directory by construction, so it can never destroy anything, and a host
+ *      where the unmount left files behind keeps them for an operator to see.
+ *
+ * Nothing here touches the `omp-worker` account or its home. An unused account
+ * is inert, and deleting a Unix account (with whatever a previous release put
+ * in its home) to tidy up is a destructive act this retirement deliberately
+ * refuses — the same judgement #895 records.
  */
-const REFUSE_SYMLINKED_TARGETS_SH = [
-  "refuse_symlink() {",
-  '  [ "$#" -eq 1 ] || return 1',
-  "  target=$1",
-  "  rest=${target#/}",
-  "  cur=",
-  '  while [ -n "$rest" ]; do',
-  '    case "$rest" in',
-  "      */*) next=${rest%%/*}; rest=${rest#*/} ;;",
-  "      *) next=$rest; rest= ;;",
-  "    esac",
-  "    cur=$cur/$next",
-  '    if [ -L "$cur" ]; then printf "refusing: %s is a symlink\\n" "$cur" >&2; exit 1; fi',
-  "  done",
-  "}",
-].join("\n");
-
-export function planWorkerIdentity(options: WorkerIdentityPlanOptions): WorkerIdentityPlan {
-  const probes = options.probes ?? {};
-  const linux = probes.linux ?? process.platform === "linux";
-  if (!linux) {
-    // The account/ACL machinery is util-linux: a non-Linux host cannot
-    // establish the identity, and dispatch there fails closed per launch. The
-    // plan says so rather than pretending nothing is missing.
-    return {
-      account: WORKER_ACCOUNT,
-      home: WORKER_HOME_DIR,
-      agentDir: options.agentDir,
-      grantPaths: [],
-      configFiles: [],
-      steps: [],
-      grantSteps: [],
-      pending: ["worker identity requires Linux (useradd/setfacl/setpriv); worker sessions fail closed here"],
-      current: false,
-    };
-  }
-  const dirExists = probes.dirExists ?? ((path: string) => existsSync(path));
-  const searchable =
-    probes.searchable ??
-    ((path: string) => {
-      try {
-        return (statSync(path).mode & 0o001) !== 0;
-      } catch {
-        return false;
-      }
-    });
-  const linkCurrent =
-    probes.linkCurrent ??
-    ((path: string, target: string) => {
-      try {
-        return lstatSync(path).isSymbolicLink() && readlinkSync(path) === target;
-      } catch {
-        return false;
-      }
-    });
-  const aclCurrent = probes.aclCurrent ?? workerAclProbe;
-
-  const account = WORKER_ACCOUNT;
-  const home = WORKER_HOME_DIR;
-  const workerAgentDir = join(home, ".omp", "agent");
-  const configFiles = [...(probes.configFiles ?? [])];
-
-  // The dirs that must be searchable by the worker: the existing ancestor
-  // chain of each root down to the first component that is not there yet (the
-  // daemon creates its own dirs searchable). This is what turns "cannot even
-  // reach /root" into "can reach exactly the granted trees".
-  const grantRoots = [options.stateRoot, options.agentDir, options.bunRoot, options.packageRoot];
-  const grantPaths: string[] = [];
-  for (const root of grantRoots) {
-    const parts = resolve(root)
-      .split("/")
-      .filter((part) => part !== "");
-    let cur = "/";
-    for (const part of parts) {
-      cur = cur === "/" ? `/${part}` : `${cur}/${part}`;
-      if (!dirExists(cur)) break;
-      if (!searchable(cur) && !grantPaths.includes(cur)) grantPaths.push(cur);
-    }
-  }
-
-  const pending: string[] = [];
-  const accountExists = probes.accountExists ?? passwdHasAccount();
-  const setfaclInstalled = probes.setfaclInstalled ?? existsSync("/usr/bin/setfacl");
-
-  if (!accountExists) {
-    pending.push(`the ${account} account does not exist yet (created as a system account with no login)`);
-  }
-  if (accountExists && !dirExists(workerAgentDir)) {
-    pending.push(`the worker agent dir ${workerAgentDir} is not bound to the fleet agent config yet`);
-  }
-  for (const name of WORKER_AGENT_LINK_FILES) {
-    if (!configFiles.some((f) => f === join(options.agentDir, name))) continue;
-    const link = join(workerAgentDir, name);
-    if (!linkCurrent(link, join(options.agentDir, name))) {
-      pending.push(`${link} does not resolve to the fleet's ${name}`);
-    }
-  }
-  // The provisioned worker runtime (#798 review 2): the worker owns a writable
-  // copy of the auth database (the harness writes into it — a read-only view
-  // would fail, a link would mutate the operator's), scoped copies of the gh
-  // credentials (HOME-scoped, 0600) and the git identity. A missing worker
-  // copy is pending whether or not the source exists: the message says which.
-  const workerGhHosts = join(home, ".config", "gh", "hosts.yml");
-  const workerGitconfig = join(home, ".gitconfig");
-  const workerAuthDb = join(workerAgentDir, "agent.db");
-  const authSource = join(options.agentDir, "agent.db");
-  const ghSource = join(options.home, ".config", "gh");
-  const gitSource = join(options.home, ".gitconfig");
-  const agentDbPresent = probes.agentDbPresent ?? existsSync(authSource);
-  const workerAuthDbCurrent = probes.workerAuthDbCurrent ?? existsSync(workerAuthDb);
-  const ghConfigPresent = probes.ghConfigPresent ?? existsSync(join(ghSource, "hosts.yml"));
-  const workerGhConfigCurrent = probes.workerGhConfigCurrent ?? existsSync(workerGhHosts);
-  const gitconfigPresent = probes.gitconfigPresent ?? existsSync(gitSource);
-  const workerGitconfigCurrent = probes.workerGitconfigCurrent ?? existsSync(workerGitconfig);
-  if (!workerAuthDbCurrent) {
-    pending.push(
-      `the worker auth database ${workerAuthDb} is not provisioned yet ` +
-        `(source ${authSource} ${agentDbPresent ? "exists" : "does not exist"})`,
-    );
-  }
-  if (!workerGhConfigCurrent) {
-    pending.push(
-      `the worker gh credentials ${workerGhHosts} are not provisioned yet ` +
-        `(source ${join(ghSource, "hosts.yml")} ${ghConfigPresent ? "exists" : "does not exist"})`,
-    );
-  }
-  if (!workerGitconfigCurrent) {
-    pending.push(
-      `the worker git identity ${workerGitconfig} is not provisioned yet ` +
-        `(source ${gitSource} ${gitconfigPresent ? "exists" : "does not exist"})`,
-    );
-  }
-  if (!setfaclInstalled) {
-    pending.push("/usr/bin/setfacl is not installed — the worker's path grants cannot be applied");
-  } else {
-    for (const path of grantPaths) {
-      if (!aclCurrent(path, "x")) pending.push(`search access for ${account} is not granted on ${path}`);
-    }
-    for (const file of configFiles) {
-      if (!aclCurrent(file, "r")) pending.push(`read access for ${account} is not granted on ${file}`);
-    }
-  }
-  // The harness binding (#828). Pending like any other missing piece of the
-  // identity, and for the same reason: without it a launched worker resolves a
-  // harness the operator never installed, so a host whose binding is absent is
-  // not a ready host however complete its account and grants are.
-  const harnessProblem =
-    probes.harnessProblem === undefined ? harnessBindingProblem() : probes.harnessProblem();
-  if (harnessProblem !== undefined) pending.push(harnessProblem);
-  // The bound tree's reach (#828 review), hardened to the directory's whole
-  // shape (#831). A bind shows its source's mode, so the mount point's parent
-  // is the only place to narrow it — and it is only "restricted" when root
-  // owns it, its group is the live worker group, the group can read+execute,
-  // and no other account can reach it (the `0750 root:<account>` shape). An
-  // open parent hands every local account the whole dependency tree, which
-  // the #798 boundary did not; a `0750 root:root` parent locks the worker out
-  // of the very install it must traverse. Both read pending.
-  if (!(probes.harnessDirRestricted ?? false)) {
-    pending.push(
-      `${WORKER_HARNESS_DIR} is not restricted to root and the ${account} group ` +
-        `(owner root, group ${account} with read+execute, and no other permissions, ` +
-        `so the worker can traverse the bound install and nobody else can)`,
-    );
-  }
-
-  const sq = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`;
-  const refuseSymlink = (path: string): string => `refuse_symlink ${sq(path)}`;
-  const steps: PrivilegedStep[] = [];
-  // Account first: the bind and the grants name the account, so it must exist
-  // before they run; the daemon restart later in the batch then comes up
-  // already able to resolve it.
-  steps.push({
-    title: `create the ${account} worker account (unprivileged, no login, home ${home}) if missing`,
-    argv: [
-      "sh",
-      "-c",
-      `getent passwd ${account} >/dev/null 2>&1 || useradd --system --create-home ` +
-        `--home-dir ${sq(home)} --shell /usr/sbin/nologin --user-group ${account}`,
-    ],
-  });
-  steps.push({
-    title: `bind the fleet agent config into ${workerAgentDir}`,
-    argv: [
-      "sh",
-      "-c",
-      // One statement per link, never an `&&` chain: an absent optional
-      // fleet file skips only its own link and cannot abort the later links
-      // or the ownership hand-back below. The chown is unconditional — it is
-      // the step's point, not a trailing detail.
-      [
-        // The worker owns everything under its home, so any component of a
-        // directory root is about to mkdir or hand back may already be a
-        // worker-planted symlink; root follows it otherwise and redirects the
-        // whole step to the target (#816). Refused first, naming the link.
-        REFUSE_SYMLINKED_TARGETS_SH,
-        refuseSymlink(home),
-        refuseSymlink(join(home, ".omp")),
-        refuseSymlink(workerAgentDir),
-        `mkdir -p ${sq(workerAgentDir)}`,
-        `cd ${sq(workerAgentDir)}`,
-        ...WORKER_AGENT_LINK_FILES.map(
-          (name) =>
-            `if [ -f ${sq(join(options.agentDir, name))} ]; then ln -sfn ${sq(join(options.agentDir, name))} ${sq(name)}; fi`,
-        ),
-        ...WORKER_AGENT_LINK_DIRS.map(
-          (name) =>
-            `if [ -d ${sq(join(options.agentDir, name))} ]; then ln -sfn ${sq(join(options.agentDir, name))} ${sq(name)}; fi`,
-        ),
-        // The bind ran as root, so the freshly created dirs are root's — hand
-        // the worker's own state dirs back to the account (never -R: the
-        // bound links stay root-owned, and the fleet files they point at must
-        // not gain a writable owner through them). `-h` re-owns a symlink
-        // itself rather than the directory it points at (#816).
-        `chown -h ${account} ${sq(join(home, ".omp"))} ${sq(workerAgentDir)}`,
-      ].join("\n"),
-    ],
-  });
-  // The worker runtime (#798 review 2): writable worker-owned copies of the
-  // auth database (the harness persists credentials, usage and settings into
-  // it), the gh credentials and the git identity — everything a session needs
-  // to call a model, read the tracker through gh and commit. Each copy is
-  // guarded: an absent source waits for the operator, it never aborts the
-  // other copies or the ownership hand-back, and a re-run re-copies (converges).
-  const workerGhDir = join(home, ".config", "gh");
-  const own = (file: string): string => `if [ -e ${sq(file)} ]; then chown -h ${account} ${sq(file)}; fi`;
-  steps.push({
-    title: `provision the worker runtime: auth database, gh credentials, git identity`,
-    argv: [
-      "sh",
-      "-c",
-      [
-        // Every directory root this step creates, copies into or hands back,
-        // checked before anything follows (#816): the worker owns its home, so
-        // `.omp`, `.config` or `.cache` can already be a symlink pointing at
-        // an arbitrary root-owned target.
-        REFUSE_SYMLINKED_TARGETS_SH,
-        refuseSymlink(home),
-        refuseSymlink(join(home, ".omp")),
-        refuseSymlink(workerAgentDir),
-        refuseSymlink(join(home, ".config")),
-        refuseSymlink(workerGhDir),
-        refuseSymlink(join(home, ".cache")),
-        `mkdir -p ${sq(workerGhDir)} ${sq(join(home, ".cache", "gh"))}`,
-        // `--remove-destination` unlinks a worker-planted *destination*
-        // symlink before copying, so a copy lands as a fresh regular file
-        // instead of following the link to an arbitrary target (#816).
-        `if [ -f ${sq(authSource)} ]; then cp -f -p --remove-destination ${sq(authSource)} ${sq(workerAuthDb)}; fi`,
-        `if [ -f ${sq(`${authSource}-wal`)} ]; then cp -f -p --remove-destination ${sq(`${authSource}-wal`)} ${sq(`${workerAuthDb}-wal`)}; fi`,
-        `if [ -f ${sq(`${authSource}-shm`)} ]; then cp -f -p --remove-destination ${sq(`${authSource}-shm`)} ${sq(`${workerAuthDb}-shm`)}; fi`,
-        `if [ -f ${sq(join(ghSource, "hosts.yml"))} ]; then cp -f -p --remove-destination ${sq(join(ghSource, "hosts.yml"))} ${sq(workerGhHosts)}; fi`,
-        `if [ -f ${sq(join(ghSource, "config.yml"))} ]; then cp -f -p --remove-destination ${sq(join(ghSource, "config.yml"))} ${sq(join(workerGhDir, "config.yml"))}; fi`,
-        `if [ -f ${sq(gitSource)} ]; then cp -f -p --remove-destination ${sq(gitSource)} ${sq(workerGitconfig)}; fi`,
-        // The copies are the worker's own — never root's: the account writes
-        // its auth/usage data and runs gh/git under its own identity. `-h`:
-        // a worker-planted symlink at a directory is re-owned, not followed
-        // (#816).
-        `chown -h ${account} ${sq(join(home, ".config"))} ${sq(workerGhDir)} ${sq(join(home, ".cache"))}`,
-        own(workerAuthDb),
-        own(`${workerAuthDb}-wal`),
-        own(`${workerAuthDb}-shm`),
-        own(workerGhHosts),
-        own(join(workerGhDir, "config.yml")),
-        own(workerGitconfig),
-      ].join("\n"),
-    ],
-  });
-  // The ACL grants live in their own list, kept apart from the identity's
-  // pre-restart steps: they are the transaction's *last* executed steps, after
-  // the daemon and herdr restarts and the pane settle gate below, because an
-  // OMP startup chmods the agent config dir back to 0700 on every open and a
-  // chmod rewrites the ACL mask — a grant that runs before that is
-  // `#effective:---` by the time a worker is admitted (#835). The mask is set
-  // explicitly (`m::x` / `m::r`) so the re-grant defeats a zeroed mask without
-  // relying on setfacl recalculation, and the named entry is the worker
-  // account alone — no other local account gains anything. Each grant step
-  // *verifies* its own result afterwards through getfacl: the worker's entry
-  // must carry the granted bits and carry no `#effective:` annotation on the
-  // worker's own line (the mask stripping it — a pane that chmod'd after the
-  // settle gate). A grant
-  // that does not verify exits nonzero, which stops the setup transaction
-  // rather than leaving workers to be admitted under a dead ACL.
-  const grantSteps: PrivilegedStep[] = [];
-  if (grantPaths.length > 0) {
-    const all = grantPaths.map(sq).join(" ");
-    grantSteps.push({
-      title: `grant ${account} search access to the fleet paths a worker session needs`,
-      argv: [
-        "sh",
-        "-c",
-        [
-          `setfacl -m ${sq(`m::x,u:${account}:x`)} ${all}`,
-          `for p in ${all}; do`,
-          `  [ -e "$p" ] || continue`,
-          `  out=$(getfacl -p -c "$p" 2>/dev/null)`,
-          // The `#effective:` probe is scoped to the worker's own entry line:
-          // a group or other named entry that the explicit mask narrows also
-          // renders an annotation (`group::r-x  #effective:--x`) without the
-          // worker's grant being dead — matching the whole dump would fail a
-          // perfectly effective grant on any path whose owner group class
-          // carries bits the mask narrows.
-          `  if [ -z "$out" ] || ! printf '%s\\n' "$out" | grep -q "user:${account}:--x" || printf '%s\\n' "$out" | grep -qE "user:${account}:--x[[:space:]]+#effective:"; then`,
-          `    printf '%s\n' "worker search access on $p is not effective after the grant (the ACL mask strips ${account}'s entry -- a pane chmod may have landed after the settle gate); refusing to admit workers under a dead grant" >&2`,
-          `    exit 1`,
-          `  fi`,
-          `done`,
-        ].join("\n"),
-      ],
-    });
-  }
-  if (configFiles.length > 0) {
-    const all = configFiles.map(sq).join(" ");
-    grantSteps.push({
-      title: `grant ${account} read access to the fleet agent config files`,
-      argv: [
-        "sh",
-        "-c",
-        // One statement per file, never an `&&` chain: a fleet file that
-        // vanished since the plan was rendered skips only its own grant and
-        // cannot abort the grants for the files that are still there. Same
-        // verification as the search grant: the pass is only a pass when the
-        // worker's read entry is effective, never when the mask keeps it out.
-        [
-          ...configFiles.map(
-            (file) =>
-              `if [ -f ${sq(file)} ]; then setfacl -m ${sq(`m::r,u:${account}:r`)} ${sq(file)}; fi`,
-          ),
-          `for p in ${all}; do`,
-          `  [ -f "$p" ] || continue`,
-          `  out=$(getfacl -p -c "$p" 2>/dev/null)`,
-          // Same worker-entry scoping as the search grant: an annotation on
-          // another line never fails the worker's own effective read.
-          `  if [ -z "$out" ] || ! printf '%s\\n' "$out" | grep -q "user:${account}:r--" || printf '%s\\n' "$out" | grep -qE "user:${account}:r--[[:space:]]+#effective:"; then`,
-          `    printf '%s\n' "worker read access on $p is not effective after the grant (the ACL mask strips ${account}'s entry -- a pane chmod may have landed after the settle gate); refusing to admit workers under a dead grant" >&2`,
-          `    exit 1`,
-          `  fi`,
-          `done`,
-        ].join("\n"),
-      ],
-    });
-  }
-
+function planRetirement(unitDir: string): HostRetirement | undefined {
+  const installed = join(unitDir, HARNESS_MOUNT_UNIT_NAME);
+  const staged = join(stateDir(), HARNESS_MOUNT_UNIT_NAME);
+  const units = existsSync(installed) ? [installed] : [];
+  const stagedFiles = existsSync(staged) ? [staged] : [];
+  if (units.length === 0 && stagedFiles.length === 0) return undefined;
   return {
-    account,
-    home,
-    agentDir: workerAgentDir,
-    grantPaths,
-    configFiles,
-    steps,
-    grantSteps,
-    pending,
-    current: pending.length === 0,
+    units,
+    staged: stagedFiles,
+    steps: [
+      ...(units.length === 0
+        ? []
+        : [
+            {
+              title: `disable and unmount ${HARNESS_MOUNT_UNIT_NAME} (retired: worker sessions run as the fleet account again)`,
+              argv: ["systemctl", "disable", "--now", HARNESS_MOUNT_UNIT_NAME],
+            },
+            { title: `remove ${installed}`, argv: ["rm", "-f", installed] },
+            { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
+            {
+              title: `remove the now-unused mount point ${WORKER_HARNESS_DIR}`,
+              argv: ["rmdir", "--ignore-fail-on-non-empty", WORKER_HARNESS_DIR],
+              bestEffort: true,
+            },
+          ]),
+      // The staged render is the fleet account's own file, so it needs no
+      // escalation — and it goes last: a failed disable must not leave the
+      // state directory looking converged.
+      ...stagedFiles.map((path) => ({
+        title: `remove the staged ${HARNESS_MOUNT_UNIT_NAME} render`,
+        argv: ["rm", "-f", path],
+        unprivileged: true,
+      })),
+    ],
   };
 }
 
-/** The identity plan as the host runtime plan carries it for display. */
-export interface WorkerIdentityPlanState {
-  account: string;
-  home: string;
-  agentDir: string;
-  current: boolean;
-  pending: readonly string[];
-}
-
 function planTick(project: ProjectConfig, telegramStateDir: string): {
   write: PlannedWrite<TickConfig>;
   /** Set when the config was restamped from the shared default: the live herdr
@@ -2133,11 +1441,6 @@ export function planHostRuntime(
   // host-global, so on a multi-project host it must not encode one project's
   // name — and a no-project install never does (#510/#530).
   multiProject: boolean = false,
-  // The worker identity plan (#798). `undefined`/`null` plans none (the
-  // historical surface — every existing caller); `runHostInstall` passes the
-  // real probes (or an explicit disable), so the consent the operator
-  // approves names every account and grant change the install will make.
-  identityProbes?: WorkerIdentityProbes | null,
 ): HostRuntimePlan {
   const servicePath = join(stateDir(), STAGED_SERVICE_NAME);
   const serviceContent = renderDaemonService(runtime, totalWorkers);
@@ -2285,87 +1588,14 @@ export function planHostRuntime(
   // The worker identity plan (#798): account creation, the agent-config bind,
   // the runtime provision, and the search/read ACL grants are host changes
   // the same install consent covers, so they join the same single step list.
-  // The identity's own steps are prepended — the account must exist before
-  // the bind and provision name it, and before the daemon restart below comes
-  // up resolving it. The ACL grants are appended *after* the transaction's
-  // final restarts instead — behind a bounded settle gate, because an OMP
-  // startup chmods the agent config dir back to 0700 (resetting the ACL
-  // mask), so a grant placed before the restarts is named-but-ineffective by
-  // the time a worker reads it, and a grant placed before a pane has finished
-  // booting can still be zeroed moments later (#835, review 1). A re-run
-  // whose only pending work is the identity still runs the (idempotent) steps
-  // and restarts — and ends with the grants effective again.
-  const fleetAgentDir = join(runtime.home, ".omp", "agent");
-  const harnessSource = packageRootOf(runtime.packageCli);
-  // The bind's source must be a real install root, not just "wherever the CLI
-  // lives": a source checkout has no `node_modules` ancestor, and binding its
-  // `src/` at a path named `node_modules` would produce a resolution root with
-  // no packages in it. There the binding cannot be established at all, which is
-  // what the identity plan's pending reason says — so plan no unit rather than
-  // install one that could never work.
-  const harnessInstallRoot = packageNodeModulesRoot(runtime.packageCli);
-  const identityPlan: WorkerIdentityPlan | undefined =
-    identityProbes === undefined || identityProbes === null
-      ? undefined
-      : planWorkerIdentity({
-          stateRoot: runtime.conductorHome,
-          agentDir: fleetAgentDir,
-          bunRoot: dirname(runtime.bun),
-          packageRoot: harnessSource,
-          home: runtime.home,
-          probes: identityProbes,
-        });
-  // The harness binding (#828) exists only to serve that identity, so it is
-  // planned exactly when the identity can be established at all — a host that
-  // cannot run the account machinery (the non-Linux plan, which stages no
-  // steps) has nothing to bind it for.
-  const harnessMountPath = join(stateDir(), HARNESS_MOUNT_UNIT_NAME);
-  const harnessMount: PlannedWrite<string> | undefined =
-    harnessInstallRoot === undefined || identityPlan === undefined || identityPlan.steps.length === 0
-      ? undefined
-      : (() => {
-          const content = renderHarnessMountUnit(harnessInstallRoot);
-          return {
-            path: harnessMountPath,
-            action: actionFor(harnessMountPath, content),
-            content,
-            value: content,
-          };
-        })();
+  // What an earlier release left on this host and this one takes away (#895),
+  // read from disk exactly like every other currentness fact in this plan.
+  const retire = planRetirement(unitDir);
   // Recovery first: the daemon unit that follows names it in OnFailure=, so
   // the restart below must never point at a unit systemd cannot load. This is
   // the single list `runHostInstall` executes and {@link installCommands}
   // renders from, so no step can be in one and missing from the other (#509).
   const installSteps: PrivilegedStep[] = [
-    // The binding first: everything after it may restart the daemon, and a
-    // daemon that comes up before the mount exists refuses every worker launch
-    // until something restarts it again (#828). `enable --now` mounts it in the
-    // same step it makes persistent; both halves are idempotent, and neither
-    // unmounts a live bind out from under a running worker.
-    ...(harnessMount === undefined
-      ? []
-      : [
-          // The mount point's own directory, created before systemd would
-          // create it 0755. A bind shows the *source* directory's mode, so the
-          // only place the bound tree's reach can be narrowed is the parent:
-          // `0750 root:omp-worker` leaves it enumerable by root and the worker
-          // account and by nobody else, which is the #798 posture the binding
-          // must not widen. `install -d` applies owner and mode to a directory
-          // that already exists, so a re-run converges.
-          {
-            title: `restrict ${WORKER_HARNESS_DIR} to root and the ${WORKER_ACCOUNT} account`,
-            argv: ["install", "-d", "-o", "root", "-g", WORKER_ACCOUNT, "-m", "0750", WORKER_HARNESS_DIR],
-          },
-          {
-            title: `install ${HARNESS_MOUNT_UNIT_NAME} (binds ${harnessInstallRoot} read-only at ${WORKER_HARNESS_NODE_MODULES})`,
-            argv: ["install", "-m", "0644", harnessMountPath, join(unitDir, HARNESS_MOUNT_UNIT_NAME)],
-          },
-          { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
-          {
-            title: `enable and mount ${HARNESS_MOUNT_UNIT_NAME}`,
-            argv: ["systemctl", "enable", "--now", HARNESS_MOUNT_UNIT_NAME],
-          },
-        ]),
     {
       title: "install the recovery playbook",
       argv: ["install", "-m", "0755", recoverScriptPath, recoverScriptInstallPath],
@@ -2425,38 +1655,11 @@ export function planHostRuntime(
         ]),
   ];
   const installStepsAll: PrivilegedStep[] = [
-    ...(identityPlan === undefined ? [] : identityPlan.steps),
+    // Retirement first (#895): the obsolete bind is unmounted before anything
+    // restarts, so no unit comes up while a mount nothing reads is still live,
+    // and an operator watching the plan sees the removal before the installs.
+    ...(retire === undefined ? [] : retire.steps),
     ...installSteps,
-    // The ACL grants ride *last* — after the daemon and herdr restarts above —
-    // because an OMP startup chmods its agent config dir back to 0700 and a
-    // chmod rewrites the ACL mask: a grant applied before the restart is
-    // `user:omp-worker:--x  #effective:---` by the time a worker reads it (#835).
-    // The herdr restart returns once herdr's own process is up, not once its
-    // restored OMP panes have booted — so on a herdr host the grants wait on a
-    // bounded settle gate that observes the pane's startup chmod in the ACL
-    // mask before any setfacl may run (#835 review 1). The grant steps then
-    // verify their own effective result, and a dead grant stops the
-    // transaction rather than admitting workers under it.
-    ...(identityPlan === undefined || identityPlan.grantSteps.length === 0
-      ? []
-      : [
-          ...(runtime.herdr === undefined
-            ? []
-            : [
-                {
-                  title: `wait for the fleet agent panes to settle after the herdr restart (bounded readiness gate)`,
-                  // The pane settle gate is a required step: a pane whose
-                  // startup chmod does not settle must fail the transaction
-                  // rather than let a grant land under a still-booting pane.
-                  argv: [
-                    "sh",
-                    "-c",
-                    paneSettleScript(fleetAgentDir, runtime.herdr, runtime.herdrSession ?? DEFAULT_HERDR_SESSION),
-                  ],
-                },
-              ]),
-          ...identityPlan.grantSteps,
-        ]),
   ];
   // Everything the privileged steps install is already at its destination with
   // the current bytes, so a re-run of `setup host` has nothing to install and
@@ -2475,10 +1678,6 @@ export function planHostRuntime(
   noteDrift(join(unitDir, RECOVER_SERVICE_NAME), recoverUnitContent);
   noteDrift(recoverScriptInstallPath, recoverScriptContent);
   if (herdrUnit !== undefined) noteDrift(installedHerdr, herdrUnit.content);
-  // The harness binding's own unit: a host whose mount unit is missing or
-  // rewritten by a release is not a current install, however current every
-  // other destination is (#828).
-  if (harnessMount !== undefined) noteDrift(join(unitDir, HARNESS_MOUNT_UNIT_NAME), harnessMount.content);
   // The pane-shell file is a destination like the units: a plan with all
   // units current but the config merge still pending must not report
   // "nothing to install" and skip the very write it exists to make.
@@ -2486,22 +1685,24 @@ export function planHostRuntime(
   // Same for the herdr-conductor config.env: a pending env merge is pending
   // work, not an already-current install.
   if (herdrEnv !== undefined) noteDrift(herdrEnvTarget, herdrEnv.content);
-  // A pending worker identity is pending work like any drifted file: the
-  // install gate must not call a host "current" whose worker sessions would
-  // fail closed the moment they dispatch (#798).
-  const currentInstall = drift.length === 0 && (identityPlan?.current ?? true);
+  // Owed retirement is pending work like any drifted file (#895): a host whose
+  // obsolete mount is still enabled has something left to do, and a re-run that
+  // reported "already current" there would be the half-applied retirement this
+  // slice exists to prevent.
+  const currentInstall = drift.length === 0 && retire === undefined;
   return {
     service,
     // The herdr unit and pane-shell config stand and fall together: no herdr, no
     // session to supervise, nothing for a pane shell to belong to. (The pane
     // shell is omitted too when the login shell is unusable or the rendered
     // config would not parse — those plans carry {@link herdrConfigProblem}.)
-    ...(herdrUnit === undefined ? {} : { herdrUnit }),
+    ...(herdrUnit === undefined
+      ? {}
+      : { herdrUnit, herdrSession: runtime.herdrSession ?? DEFAULT_HERDR_SESSION }),
     ...(herdrConfig === undefined ? {} : { herdrConfig, herdrConfigTarget }),
     ...(herdrConfigProblem === undefined ? {} : { herdrConfigProblem }),
     ...(herdrConfigWarning === undefined ? {} : { herdrConfigWarning }),
     ...(herdrEnv === undefined ? {} : { herdrEnv, herdrEnvTarget }),
-    ...(harnessMount === undefined ? {} : { harnessMount }),
     recoverUnit,
     recoverScript,
     ...(project === undefined
@@ -2544,7 +1745,7 @@ export function planHostRuntime(
     installedPath,
     installedAction,
     drift,
-    ...(identityPlan === undefined ? {} : { workerIdentity: identityPlan }),
+    ...(retire === undefined ? {} : { retire }),
     currentInstall,
   };
 }
@@ -2556,9 +1757,12 @@ export function formatHostRuntimePlan(plan: HostRuntimePlan): string {
     `  daemon entry   ${plan.cliSource === "global" ? "installed omp-conductor CLI" : "current installed plugin"}`,
     `  recovery       ${plan.recoverUnit.action} ${plan.recoverUnit.path}`,
     `  recovery exec  ${plan.recoverScript.action} ${plan.recoverScript.path} -> ${RECOVER_SCRIPT_INSTALL_PATH}`,
-    ...(plan.harnessMount === undefined
+    ...(plan.retire === undefined
       ? []
-      : [`  harness bind   ${plan.harnessMount.action} ${plan.harnessMount.path} -> ${WORKER_HARNESS_NODE_MODULES}`]),
+      : [
+          `  retire         ${[...plan.retire.units, ...plan.retire.staged].join(", ")}`,
+          `                 (the ${HARNESS_MOUNT_UNIT_NAME.replace(/\\x2d/g, "-")} bind an earlier release installed; worker sessions run as the fleet account)`,
+        ]),
     ...(plan.herdrUnit === undefined
       ? ["  herdr session  skipped — herdr not installed on this host"]
       : [
@@ -2598,27 +1802,10 @@ export function formatHostRuntimePlan(plan: HostRuntimePlan): string {
         : `  brief link     ${plan.briefLink.action} ${plan.briefLink.path} -> ${plan.briefLink.target}`,
     );
   }
-  if (plan.workerIdentity !== undefined) {
-    lines.push(
-      plan.workerIdentity.current
-        ? `  worker identity ${plan.workerIdentity.account} (home ${plan.workerIdentity.home}) — present, worker paths granted`
-        : `  worker identity ${plan.workerIdentity.account} (home ${plan.workerIdentity.home}) — pending: ${plan.workerIdentity.pending.join("; ")}`,
-    );
-  }
   lines.push("  install        staged only; the final result prints the systemd install commands");
   return lines.join("\n");
 }
 
-/** The node_modules root an installed package CLI lives under — the ancestor
- *  of `packageCli` named `node_modules`. This is the root the worker needs
- *  search access to and the source of its harness binding; granting the one
- *  package dir would miss its dependency tree, and granting the parent of
- *  node_modules would grant far more. A source checkout has no such ancestor,
- *  and the package's own directory is the closest honest answer. */
-function packageRootOf(packageCli: string): string {
-  return packageNodeModulesRoot(packageCli) ?? dirname(resolve(packageCli));
-}
-
 function atomicWrite(path: string, content: string, mode: number): void {
   mkdirSync(dirname(path), { recursive: true });
   const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
@@ -2652,10 +1839,6 @@ export function writeHostRuntime(plan: HostRuntimePlan): HostRuntimeWrite {
     atomicWrite(plan.herdrUnit.path, plan.herdrUnit.content, 0o644);
     wrote.push(plan.herdrUnit.path);
   }
-  if (plan.harnessMount !== undefined && plan.harnessMount.action !== "keep") {
-    atomicWrite(plan.harnessMount.path, plan.harnessMount.content, 0o644);
-    wrote.push(plan.harnessMount.path);
-  }
   if (plan.herdrConfig !== undefined && plan.herdrConfig.action !== "keep") {
     atomicWrite(plan.herdrConfig.path, plan.herdrConfig.content, 0o644);
     wrote.push(plan.herdrConfig.path);