omp-conductor 0.15.11 → 0.15.13

package/src/setup-host.ts

@@ -23,10 +23,13 @@ import {
 import {
   legacyArmedMarkerPath,
   readTickConfig,
+  parseHerdrAgents,
   TICK_CONFIG_FILE,
   tickConfigMatchesProject,
+  type HerdrAgentList,
   type TickConfig,
 } from "./orchestrator-tick.ts";
+import { formatStep, type PrivilegedStep } from "./privileged.ts";
 import type { Caps, ConductorConfig, ProjectConfig } from "./types.ts";
 
 export const DEFAULT_TICK_INTERVAL_SECONDS = 900;
@@ -90,6 +93,17 @@ export interface BriefLinkPlan {
   skippedReason?: string;
 }
 
+/**
+ * Why a host-global install (no `--project`) wrote no per-project tail, and
+ * what the operator does about it.
+ */
+export interface HostRuntimeNoProject {
+  /** The project-scoped files the host-global install deliberately left unwritten. */
+  skipped: readonly string[];
+  /** The command that writes them: `setup host` naming one project. */
+  how: string;
+}
+
 export interface HostRuntimePlan {
   service: PlannedWrite<string>;
   /**
@@ -115,12 +129,71 @@ export interface HostRuntimePlan {
   /**
    * `[terminal] default_shell` staged into the session's herdr config, the
    * belt-and-braces behind the unit's `SHELL=` (see {@link renderHerdrConfig}).
-   * Present exactly when {@link herdrUnit} is.
+   * Present exactly when {@link herdrUnit} is, unless the login shell is not a
+   * usable path ({@link usableHerdrShell}) or the rendered config would not
+   * parse — either one leaves {@link herdrConfigProblem} set and writes
+   * nothing.
+   *
+   * This is the **staged** copy, under the state directory like every other
+   * file the plan writes: herdr's live config is a file conductor does not own,
+   * so it is only replaced post-consent by the install step naming
+   * {@link herdrConfigTarget} (#513).
    */
   herdrConfig?: PlannedWrite<string>;
+  /** The live herdr config {@link herdrConfig} merges into, post-consent. */
+  herdrConfigTarget?: string;
+  /** Why no pane-shell key is planned (unusable login shell, …). */
+  herdrConfigProblem?: string;
+  /**
+   * A loud note when the pane-shell merge kept an explicit
+   * `resume_agents_on_restore = true` — {@link renderHerdrConfig} preserves
+   * that value on purpose (it may be a desktop host), and the plan says so
+   * rather than silently overriding a deliberate choice.
+   */
+  herdrConfigWarning?: string;
+  /**
+   * The herdr-conductor plugin's `config.env`, staged like the pane-shell
+   * config and merged into the live plugin config dir post-consent: the file
+   * recover.sh sources (`herdr/bin/recover.sh`) — TARGET_SESSION, FLEET_CWDS
+   * (derived from every configured project), TELEGRAM_ENV, ACCESS_JSON.
+   * Present exactly when {@link herdrUnit} is; conductor-owned keys are
+   * patched in place, operator keys survive untouched.
+   */
+  herdrEnv?: PlannedWrite<string>;
+  /** The live plugin config.env {@link herdrEnv} merges into, post-consent. */
+  herdrEnvTarget?: string;
+  /**
+   * When {@link planTick} rewrote a shared-default `agentName`, the live herdr
+   * pane still carries the old identity — the ticking decline that names the
+   * fix (`herdr agent rename <pane> <name>`). Setup performs the rename after
+   * the install when the session is reachable and exactly one pane matches;
+   * anything else surfaces the exact command (never guesses a pane).
+   */
+  agentRename?: { session: string; from: string; to: string };
   tick?: PlannedWrite<TickConfig>;
   /** The `AGENTS.md` — composed-brief symlink — placed in the fleet cwd. */
-  briefLink: BriefLinkPlan;
+  briefLink?: BriefLinkPlan;
+  /**
+   * Set when an install ran with no project named (a host-global install):
+   * the per-project tail was deliberately not written. Names the files and
+   * how to write them, so the operator is told what is missing and how to get
+   * it rather than silently installing host-global units that leave a project
+   * brief-less and tick-less.
+   */
+  noProject?: HostRuntimeNoProject;
+  /**
+   * The exact privileged steps this plan will run, in order — recovery first,
+   * so the daemon unit that follows names a recovery unit systemd already has.
+   * This is the single list: {@link installCommands} and `runHostInstall` are
+   * both derived from it, so a step can never appear in the printed plan and
+   * be absent from the run (#509).
+   */
+  steps: readonly PrivilegedStep[];
+  /**
+   * The same steps as `sudo …` shell lines, for humans to read. A projection
+   * of {@link steps} rather than a parallel list, so nothing executes a step
+   * the printed plan does not show.
+   */
   installCommands: readonly string[];
   cliSource: "global" | "plugin";
   /** Absolute path of the unit systemd actually reads. */
@@ -138,6 +211,12 @@ export interface HostRuntimePlan {
    * the installed unit matched.
    */
   installedAction: PlannedWrite<string>["action"];
+  /**
+   * True when every file the privileged install steps would write is already
+   * at its destination with the current bytes. `runHostInstall` uses it to
+   * make a no-op re-run of `setup host` neither restage nor restart anything.
+   */
+  currentInstall: boolean;
 }
 
 export interface ServiceRuntime {
@@ -192,10 +271,6 @@ function systemdPath(value: string): string {
   return value.replaceAll("%", "%%");
 }
 
-function shellQuote(value: string): string {
-  return `'${value.replaceAll("'", "'\\''")}'`;
-}
-
 function actionFor(path: string, content: string): PlannedWrite<string>["action"] {
   if (!existsSync(path)) return "create";
   try {
@@ -413,7 +488,12 @@ export function renderDaemonService(runtime: ServiceRuntime, totalWorkers: numbe
       : [`Environment=${systemdQuote(`HERDR_SESSION=${runtime.herdrSession}`)}`]),
     `WorkingDirectory=${systemdPath(stateDir())}`,
     `ExecStart=${command.map(systemdQuote).join(" ")}`,
-    "Restart=on-failure",
+    // #546: restart on any exit — clean, signalled or crashed — except an
+    // explicit `systemctl stop`, which systemd records as intentional and does
+    // not undo. A stray SIGTERM (a worker's `bun test`) then costs seconds of
+    // downtime instead of leaving the fleet down until a human. A crash loop
+    // still trips the start-limit burst and reaches `OnFailure=` above.
+    "Restart=always",
     "SuccessExitStatus=0 143",
     "MemoryAccounting=yes",
     `MemoryMax=${memoryMax}`,
@@ -461,7 +541,9 @@ export function renderHerdrUnit(runtime: ServiceRuntime): string {
     `Environment=${systemdQuote(`SHELL=${runtime.shell}`)}`,
     `WorkingDirectory=${systemdPath(runtime.conductorHome)}`,
     `ExecStart=${systemdQuote(runtime.herdr)} --session ${systemdQuote(session)} server`,
-    "Restart=on-failure",
+    // #546: same exposure as the daemon — restart on any exit except an
+    // explicit `systemctl stop`; a crash loop still trips the start limit.
+    "Restart=always",
     "RestartSec=5",
     "",
     "[Install]",
@@ -487,7 +569,12 @@ export function renderHerdrUnit(runtime: ServiceRuntime): string {
  * except the two fleet units' failure, so recovery can never re-trigger
  * recovery.
  */
-export function renderRecoverUnit(runtime: ServiceRuntime, projectName: string): string {
+export function renderRecoverUnit(runtime: ServiceRuntime, projectName: string | undefined): string {
+  // `RECOVER_PROJECT` is how the playbook addresses the tier-2 escalation it
+  // enqueues. It is a host-global unit installed once for the whole box, so a
+  // static per-project value is only unambiguous on a single-project host — a
+  // multi-project host (or a no-project, host-global install) leaves it unset
+  // and reports without a `--project` rather than guessing one (#510/#530).
   return [
     "[Unit]",
     "Description=omp-conductor fleet recovery (OnFailure handler)",
@@ -502,12 +589,31 @@ export function renderRecoverUnit(runtime: ServiceRuntime, projectName: string):
     `Environment=${systemdQuote(`PATH=${runtime.path}`)}`,
     `Environment=${systemdQuote(`OMP_CONDUCTOR_HOME=${runtime.conductorHome}`)}`,
     `Environment=${systemdQuote(`RECOVER_STATE_DIR=${stateDir()}`)}`,
-    `Environment=${systemdQuote(`RECOVER_PROJECT=${projectName}`)}`,
+    ...(projectName === undefined ? [] : [`Environment=${systemdQuote(`RECOVER_PROJECT=${projectName}`)}`]),
     `ExecStart=${RECOVER_SCRIPT_INSTALL_PATH}`,
     "",
   ].join("\n");
 }
 
+/**
+ * Whether a login-shell value may be pinned into herdr's config at all.
+ *
+ * `userInfo().shell` degrades to the literal `unknown` where the passwd entry
+ * cannot be read (the same root as #511's drift check), and `unknown` is not a
+ * path — a pane told to exec it dies on start, which is a stopped fleet. Only
+ * an absolute path that exists on this host qualifies; anything else must mean
+ * the caller writes **no** key and lets herdr's own `$SHELL → /bin/sh →
+ * passwd` fallback apply.
+ */
+export function usableHerdrShell(shell: string): boolean {
+  if (!shell.startsWith("/")) return false;
+  try {
+    return existsSync(shell);
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Idempotently put `[terminal] default_shell` into a herdr config, preserving
  * everything else verbatim.
@@ -516,28 +622,280 @@ export function renderRecoverUnit(runtime: ServiceRuntime, projectName: string):
  * account's login shell even if an operator later edits the unit and drops the
  * `SHELL` line. Herdr falls back `$SHELL → /bin/sh` and skips the passwd entry,
  * so without this the only guarantee would be the unit's environment.
+ *
+ * A shell that is not a usable executable path ({@link usableHerdrShell})
+ * writes **no** key at all — the file passes through byte-identical, because
+ * "pin the shell" must never mean "write the word `unknown`".
  */
-export function renderHerdrConfig(shell: string, existing?: string): string {
-  const quoted = `"${shell.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+export interface HerdrConfigRender {
+  content: string;
+  /**
+   * Set when the merged config kept an explicit `resume_agents_on_restore =
+   * true` — preserved on purpose (it may be a deliberate desktop config), but
+   * loudly flagged because the headless shape herdr's own README calls
+   * recoverable requires `false`. When absent, the value is `false` (written
+   * or already present) and nothing needs saying.
+   */
+  warning?: string;
+}
+
+export function renderHerdrConfig(shell: string, existing?: string): HerdrConfigRender {
   const text = existing ?? "";
+  // Unusable login shell → byte-identical pass-through, exactly as before: the
+  // "pin the shell" guarantee is all-or-nothing, and the fleet docs'
+  // `resume_agents_on_restore` key rides in on the same config merge, so an
+  // operator whose passwd entry cannot be resolved still gets nothing written.
+  if (!usableHerdrShell(shell)) return { content: text };
+
+  const quoted = `"${shell.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
   const line = `default_shell = ${quoted}`;
 
-  // Any existing `default_shell = …` gets the new value in place — even when the
-  // value already matches, so a re-run stays idempotent instead of duplicating
-  // the key.
-  if (/\s*default_shell\s*=/.test(text)) {
-    return text.replace(/^(\s*default_shell\s*=\s*).*$/m, `$1${quoted}`);
+  // One anchored, comment-aware match, used for both the guard and the replace
+  // so they can never disagree: a *real* key starts its line (after whitespace),
+  // while `# default_shell = …` starts with a comment and is not a key. The
+  // old guard was unanchored, so it matched a commented line the anchored
+  // replace did not — a config whose only mention was a comment took the
+  // "replace" branch, replaced nothing, and silently wrote nothing at all.
+  // Any existing key keeps its position and gets the new value in place —
+  // even when the value already matches, so a re-run stays idempotent instead
+  // of duplicating the key.
+  const keyLine = /^([ \t]*default_shell[ \t]*=\s*).*$/m;
+  let content: string;
+  if (keyLine.test(text)) {
+    content = text.replace(keyLine, `$1${quoted}`);
+  } else {
+    const lines = text.split("\n");
+    const table = lines.findIndex((l) => /^\[terminal\]\s*$/.test(l));
+    if (table === -1) {
+      const body = text.replace(/\s+$/, "");
+      content = `${body.length > 0 ? body + "\n" : ""}[terminal]\n${line}\n`;
+    } else {
+      // The table exists but has no default_shell; drop the key right under it.
+      lines.splice(table + 1, 0, line);
+      content = lines.join("\n");
+    }
   }
 
-  const lines = text.split("\n");
-  const table = lines.findIndex((l) => /^\[terminal\]\s*$/.test(l));
-  if (table === -1) {
-    const body = text.replace(/\s+$/, "");
-    return `${body.length > 0 ? body + "\n" : ""}[terminal]\n${line}\n`;
+  // [session] resume_agents_on_restore = false, the same anchored, comment-aware
+  // merge as default_shell: a real key is kept at its position, a commented-out
+  // mention is not a key. The one difference is explicit `true` (the value an
+  // operator pinned on a desktop host): it is preserved deliberately, and the
+  // caller warns about it rather than silently flipping a deliberate choice.
+  const resumeLine = "resume_agents_on_restore = false";
+  const resumeKey = /^[ \t]*resume_agents_on_restore[ \t]*=\s*([^#\n]*)/m;
+  const resumeMatch = resumeKey.exec(content);
+  const resumeValue = resumeMatch?.[1]?.trim().split(/\s+/)[0];
+  if (resumeMatch !== null) {
+    if (resumeValue === "false") {
+      content = content.replace(/^([ \t]*resume_agents_on_restore[ \t]*=\s*)[^#\n]*/m, `$1false`);
+    } else if (resumeValue !== undefined && resumeValue.length > 0) {
+      return {
+        content,
+        warning:
+          `explicit resume_agents_on_restore = ${resumeValue} kept as-is (could be a deliberate desktop config); ` +
+          "a headless fleet host leaves no live terminal for restored panes unless it is false",
+      };
+    }
+  } else {
+    const lines = content.split("\n");
+    const sessionTable = lines.findIndex((l) => /^\[session\]\s*$/.test(l));
+    if (sessionTable === -1) {
+      const body = content.replace(/\s+$/, "");
+      content = `${body.length > 0 ? body + "\n" : ""}[session]\n${resumeLine}\n`;
+    } else {
+      // The table exists but has no resume key; drop the key right under it.
+      lines.splice(sessionTable + 1, 0, resumeLine);
+      content = lines.join("\n");
+    }
+  }
+  return { content };
+}
+
+/**
+ * The values `setup host` owns in the herdr-conductor plugin's `config.env`.
+ *
+ * recover.sh sources the file (`herdr/bin/recover.sh`), and conductor writes
+ * exactly the keys that file reads to resolve a fleet. `FLEET_CWDS` is the
+ * multi-fleet form of the legacy single `FLEET_CWD`, so the renderer always
+ * writes the former; the legacy key is an operator key and survives untouched.
+ */
+export interface HerdrConductorEnvValues {
+  /** The Herdr session that owns the fleet: TARGET_SESSION. */
+  targetSession: string;
+  /** Every configured project's fleet cwd, in config order (FLEET_CWDS). */
+  fleetCwds: readonly string[];
+  /** Absolute path of omp-telegram's `.env` (TELEGRAM_ENV). */
+  telegramEnv: string;
+  /** Absolute path of omp-telegram's `access.json` (ACCESS_JSON). */
+  accessJson: string;
+}
+
+/** The keys `setup` patches; every other line in the file is operator-owned. */
+const CONDUCTOR_ENV_KEYS = ["TARGET_SESSION", "FLEET_CWDS", "TELEGRAM_ENV", "ACCESS_JSON"] as const;
+
+const ENV_VALUE_ESCAPE = /[\\"$]/g;
+
+/** One `KEY=value` line, with the value shell-quoted so recover.sh's `.`
+ *  sourcing reads paths with spaces or `$` literally. */
+function envLine(key: string, value: string): string {
+  return `${key}="${value.replace(ENV_VALUE_ESCAPE, "\\$&")}"`;
+}
+
+/**
+ * Render herdr-conductor's `config.env` — create it when missing; when present
+ * patch only conductor-owned keys and pass every other line through verbatim
+ * (an operator's `RECOVER_RECHECK_SECONDS`, `BOOTSTRAP_RESUME`, AGENT_NAME,
+ * FLEET_CWD … must survive a re-run).
+ *
+ * A conductor-owned key that already exists keeps its position and gets the new
+ * value; a missing one is appended at the end. The anchored `^[ \t]*KEY=` guard
+ * mirrors the TOML merge's comment-awareness: a line starting with `#` is a
+ * comment, not a key, so a commented draft is neither patched nor mistaken for
+ * an existing real key (which would block the append).
+ */
+export function renderHerdrConductorEnv(values: HerdrConductorEnvValues, existing?: string): string {
+  const lines = (existing ?? "").split("\n");
+  // The split of a file ending in a newline leaves one empty trailing element
+  // (and a fresh file has exactly one empty element, nothing more); both are
+  // the join's terminator, not file content — the single join below re-adds it.
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  const headers: Record<(typeof CONDUCTOR_ENV_KEYS)[number], string> = {
+    TARGET_SESSION: values.targetSession,
+    FLEET_CWDS: values.fleetCwds.join(":"),
+    TELEGRAM_ENV: values.telegramEnv,
+    ACCESS_JSON: values.accessJson,
+  };
+  const seen = new Set<string>();
+  for (const index of lines.keys()) {
+    const line = lines[index]!;
+    const match = /^([ \t]*)([A-Za-z_][A-Za-z0-9_]*)([ \t]*=[ \t]*).*$/.exec(line);
+    if (match === null) continue;
+    const key = match[2] as (typeof CONDUCTOR_ENV_KEYS)[number];
+    if (!(key in headers)) continue;
+    seen.add(key);
+    lines[index] = `${match[1]}${envLine(key, headers[key])}`;
+  }
+  for (const key of CONDUCTOR_ENV_KEYS) {
+    if (!seen.has(key)) lines.push(envLine(key, headers[key]));
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Decide whether the fleet pane may be renamed, and if so what to run.
+ *
+ * The contract is written for the one-identity case and refuses to guess:
+ * - exactly one pane carries `from` (the restamped-away identity) → rename it;
+ * - zero, several, or an unreadable agent list → surface the exact command
+ *   and the reason; never invent a pane.
+ *
+ * `command` is always the one-line remedy an operator can paste; on ambiguity
+ * it carries the generic pane placeholder because no specific pane may be
+ * guessed. It is the same shape the tick's decline path prints (`herdr agent
+ * rename <pane> <name>`), born from the session so the same command works from
+ * outside herdr too.
+ */
+export type AgentRenameVerdict =
+  | { kind: "rename"; pane: string; command: string }
+  | { kind: "flag"; command: string; reason: string };
+
+export function agentRenameVerdict(
+  list: HerdrAgentList,
+  from: string,
+  to: string,
+  session: string,
+): AgentRenameVerdict {
+  const commandFor = (pane: string): string => `herdr --session ${session} agent rename ${pane} ${to}`;
+  if (list.kind !== "ok") {
+    return {
+      kind: "flag",
+      command: commandFor("<pane>"),
+      reason: `herdr agent list is unreadable (${list.problem}) — cannot verify which pane to rename`,
+    };
+  }
+  const matches = list.agents.filter((a) => a.name === from);
+  if (matches.length === 1) {
+    return { kind: "rename", pane: matches[0]!.paneId, command: commandFor(matches[0]!.paneId) };
+  }
+  if (matches.length === 0) {
+    return {
+      kind: "flag",
+      command: commandFor("<pane>"),
+      reason: `no live pane is registered as agent "${from}" — nothing was renamed (an unregistered fleet pane must be named by hand)`,
+    };
+  }
+  return {
+    kind: "flag",
+    command: commandFor("<pane>"),
+    reason: `${matches.length} panes (${matches.map((a) => a.paneId).join(", ")}) are registered as "${from}" — refusing to guess which is the fleet pane`,
+  };
+}
+
+/** The live herdr CLI seam setup-host shells out for the one-shot rename. */
+export interface AgentRenameDeps {
+  /** `herdr --session <s> agent list`'s one JSON line. */
+  list(session: string): HerdrAgentList;
+  /** `herdr --session <s> agent rename <pane> <name>`. */
+  rename(session: string, pane: string, name: string): { ok: boolean; problem?: string };
+}
+
+/** The production wiring: the same CLI `recover.sh` and the tick both use. */
+export const DEFAULT_AGENT_RENAME_DEPS: AgentRenameDeps = {
+  list: (session) => {
+    const bin = Bun.which("herdr") ?? "herdr";
+    try {
+      const run = spawnSync(bin, ["--session", session, "agent", "list"], {
+        encoding: "utf8",
+        timeout: 3000,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      if (run.error !== undefined) return { kind: "unavailable", problem: run.error.message };
+      if (run.status !== 0) return { kind: "unavailable", problem: `exit ${String(run.status)}: ${(run.stderr ?? "").trim().split("\n")[0] ?? ""}` };
+      return parseHerdrAgents(run.stdout ?? "");
+    } catch (err) {
+      return { kind: "unavailable", problem: err instanceof Error ? err.message : String(err) };
+    }
+  },
+  rename: (session, pane, name) => {
+    const bin = Bun.which("herdr") ?? "herdr";
+    try {
+      const run = spawnSync(bin, ["--session", session, "agent", "rename", pane, name], {
+        encoding: "utf8",
+        timeout: 3000,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      if (run.error !== undefined) return { ok: false, problem: run.error.message };
+      if (run.status !== 0) {
+        return { ok: false, problem: `exit ${String(run.status)}: ${(run.stderr ?? "").trim().split("\n")[0] ?? ""}` };
+      }
+      return { ok: true };
+    } catch (err) {
+      return { ok: false, problem: err instanceof Error ? err.message : String(err) };
+    }
+  },
+};
+
+/** The directory `herdr plugin config-dir herdr-conductor` prints. */
+export function herdrConductorPluginConfigDir(home: string): string {
+  return join(home, ".config", "herdr", "plugins", "config", "herdr-conductor");
+}
+
+/**
+ * The fleet cwd of every configured project, in config order — the FLEET_CWDS
+ * value recover.sh walks to find each fleet's `.conductor-tick.json`.
+ *
+ * Tries the real config first; when it cannot be read (a not-yet-configured
+ * box, install tests staging before a config exists), the named project's own
+ * cwd stands in — the same guarded fallback shape as `hostInstallWorkers` and
+ * `hostMultiProject`. Multi-project hosts get the full list when the config
+ * loads, which is the case the recovery path exists for.
+ */
+export function configuredFleetCwds(project: ProjectConfig | undefined): string[] {
+  try {
+    return loadConfig().projects.map((p) => tickCwdForProject(p));
+  } catch {
+    return project === undefined ? [] : [tickCwdForProject(project)];
   }
-  // The table exists but has no default_shell; drop the key right under it.
-  lines.splice(table + 1, 0, line);
-  return lines.join("\n");
 }
 
 function tickSearchRoots(project: ProjectConfig): string[] {
@@ -639,7 +997,13 @@ function planBriefLink(project: ProjectConfig): BriefLinkPlan {
   };
 }
 
-function planTick(project: ProjectConfig, telegramStateDir: string): PlannedWrite<TickConfig> {
+function planTick(project: ProjectConfig, telegramStateDir: string): {
+  write: PlannedWrite<TickConfig>;
+  /** Set when the config was restamped from the shared default: the live herdr
+   *  pane still carries that old identity, and the plan must rename it
+   *  (or flag the exact command) after the tick lands. */
+  previousAgentName?: string;
+} {
   const found = findProjectTick(project);
   const existing = found === undefined ? undefined : { path: found.path, config: found.config };
 
@@ -667,11 +1031,30 @@ function planTick(project: ProjectConfig, telegramStateDir: string): PlannedWrit
             : existing.config.agentName,
       };
   const content = `${JSON.stringify(config, null, 2)}\n`;
-  return { path, action: actionFor(path, content), content, value: config };
+  return {
+    write: { path, action: actionFor(path, content), content, value: config },
+    // The rename only fires for a *re*-stamp: the old agentName was the shared
+    // default (or absent, which every reader resolves to the same default), and
+    // the new one is the project's own name. An already-project-stamped config
+    // is not a collision and needs no rename. A brand-new config (no existing
+    // tick at all) is not a restamp either: there was no previous identity for
+    // a pane to be stuck with.
+    ...(existing !== undefined &&
+    (existing.config.agentName === undefined || existing.config.agentName === DEFAULT_FLEET_AGENT_NAME)
+      ? { previousAgentName: DEFAULT_FLEET_AGENT_NAME }
+      : {}),
+  };
 }
 
 export function planHostRuntime(
-  project: ProjectConfig,
+  /**
+   * The project the per-project tail (tick config, brief link, the recovery
+   * unit's RECOVER_PROJECT) is planned for. `undefined` plans the host-global
+   * units only — the same staged paths and systemd destinations, one shared
+   * daemon — and a `noProject` note naming the per-project files it left for
+   * a named run (#530).
+   */
+  project: ProjectConfig | undefined,
   _caps: Caps,
   telegramStateDir: string,
   runtime: ServiceRuntime = defaultServiceRuntime(telegramStateDir),
@@ -679,6 +1062,17 @@ export function planHostRuntime(
   // Defaulting through loadConfig() would throw in install tests that stage
   // files before a config exists, and would hide a missing total at the call site.
   totalWorkers: number = 1,
+  // The directory the privileged steps install units into. `runHostInstall`
+  // injects a test-hermetic directory so the executed argv is assertable; the
+  // real install always resolves to `/etc/systemd/system`.
+  unitDir: string = SYSTEMD_UNIT_DIR,
+  // Where the recovery playbook installs; injectable like {@link unitDir} so
+  // the idempotency gate is testable without touching the real `/usr/local/sbin`.
+  recoverScriptInstallPath: string = RECOVER_SCRIPT_INSTALL_PATH,
+  // True when the host configures more than one project. The recovery unit is
+  // 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,
 ): HostRuntimePlan {
   const servicePath = join(stateDir(), STAGED_SERVICE_NAME);
   const serviceContent = renderDaemonService(runtime, totalWorkers);
@@ -690,8 +1084,20 @@ export function planHostRuntime(
   };
   const herdrUnitPath = join(stateDir(), DEFAULT_HERDR_UNIT);
   const herdrConfigPath = join(runtime.home, ".config", "herdr", "config.toml");
+  // The pane-shell config is staged like every other file; the live herdr
+  // config — a file conductor does not own — is only written by the install
+  // step, after consent (#513). A declined `setup host` must leave herdr's
+  // config byte-for-byte untouched, and the merge must land before the unit
+  // restart that accompanies it.
+  const herdrConfigStagedPath = join(stateDir(), "herdr-config.toml");
+  const herdrEnvStagedPath = join(stateDir(), "herdr-conductor.env");
+  const herdrEnvTarget = join(herdrConductorPluginConfigDir(runtime.home), "config.env");
   let herdrUnit: PlannedWrite<string> | undefined;
   let herdrConfig: PlannedWrite<string> | undefined;
+  let herdrConfigTarget: string | undefined;
+  let herdrConfigProblem: string | undefined;
+  let herdrConfigWarning: string | undefined;
+  let herdrEnv: PlannedWrite<string> | undefined;
   // The recovery playbook ships in this package's systemd/ dir; the same
   // bytes go into the staged copy, so version control is the single source.
   const recoverScriptPath = join(stateDir(), RECOVER_SCRIPT_FILE);
@@ -720,18 +1126,85 @@ export function planHostRuntime(
     } catch {
       existing = undefined;
     }
-    const configContent = renderHerdrConfig(runtime.shell, existing);
-    herdrConfig = {
-      path: herdrConfigPath,
-      action: actionFor(herdrConfigPath, configContent),
-      content: configContent,
-      value: configContent,
+    // An unresolvable login shell (userInfo() renders the literal "unknown")
+    // plans nothing and says why: never a placeholder, and never a value that
+    // is not an executable path — herdr's own `$SHELL → /bin/sh → passwd`
+    // fallback applies instead.
+    if (!usableHerdrShell(runtime.shell)) {
+      herdrConfigProblem =
+        `login shell ${JSON.stringify(runtime.shell)} is not an absolute path that exists on this host — ` +
+        "no [terminal] default_shell is written, so herdr's own $SHELL → /bin/sh → passwd fallback applies";
+    } else {
+      const rendered = renderHerdrConfig(runtime.shell, existing);
+      const configContent = rendered.content;
+      if (rendered.warning !== undefined) herdrConfigWarning = rendered.warning;
+      // The rendered file is parse-checked before anything may replace herdr's
+      // live config. An input that is already broken (a duplicated key, say)
+      // renders broken — the replace touches every real key, so two keys stay
+      // two keys — and writing that file is exactly the stopped-fleet outcome
+      // this must prevent. A parse failure aborts the whole plan here, before
+      // a single file has been staged.
+      if (actionFor(herdrConfigPath, configContent) !== "keep") {
+        try {
+          Bun.TOML.parse(configContent);
+        } catch (err) {
+          throw new Error(
+            `refusing to write herdr's config at ${herdrConfigPath}: it would not parse ` +
+              `(${err instanceof Error ? err.message : String(err)}). Nothing has been staged — ` +
+              "fix the file by hand (herdr's `config check` names the line), then re-run setup host.",
+          );
+        }
+      }
+      herdrConfig = {
+        path: herdrConfigStagedPath,
+        action: actionFor(herdrConfigStagedPath, configContent),
+        content: configContent,
+        value: configContent,
+      };
+      herdrConfigTarget = herdrConfigPath;
+    }
+    // The herdr-conductor plugin's config.env (#541): recover.sh sources
+    // `$HERDR_PLUGIN_CONFIG_DIR/config.env` and shrinks to legacy /root paths
+    // when it is missing — on a host whose fleet lives elsewhere the recovery
+    // still runs, only the page silently goes nowhere. Setup owns
+    // TARGET_SESSION/FLEET_CWDS/TELEGRAM_ENV/ACCESS_JSON; the renderer patches
+    // only those keys, so an operator's BOOTSTRAP_RESUME or
+    // RECOVER_RECHECK_SECONDS survive a re-run.
+    let existingEnv: string | undefined;
+    try {
+      existingEnv = readFileSync(herdrEnvTarget, "utf8");
+    } catch {
+      existingEnv = undefined;
+    }
+    const envContent = renderHerdrConductorEnv(
+      {
+        targetSession: runtime.herdrSession ?? DEFAULT_HERDR_SESSION,
+        // Derived from every configured project's tick cwd, not from the
+        // host-global unit the install runs for: FLEET_CWDS is what recover.sh
+        // walks to find each fleet's `.conductor-tick.json`.
+        fleetCwds: configuredFleetCwds(project),
+        telegramEnv: join(telegramStateDir, ".env"),
+        accessJson: join(telegramStateDir, "access.json"),
+      },
+      existingEnv,
+    );
+    herdrEnv = {
+      path: herdrEnvStagedPath,
+      action: actionFor(herdrEnvStagedPath, envContent),
+      content: envContent,
+      value: envContent,
     };
   }
-  const installedPath = join(SYSTEMD_UNIT_DIR, STAGED_SERVICE_NAME);
-  const installedHerdr = join(SYSTEMD_UNIT_DIR, DEFAULT_HERDR_UNIT);
+  const installedPath = join(unitDir, STAGED_SERVICE_NAME);
+  const installedHerdr = join(unitDir, DEFAULT_HERDR_UNIT);
   const recoverUnitPath = join(stateDir(), RECOVER_SERVICE_NAME);
-  const recoverUnitContent = renderRecoverUnit(runtime, project.name);
+  // The recovery unit is host-global: one shared unit, installed once. A
+  // static RECOVER_PROJECT is only legitimate when there is exactly one
+  // project to be unambiguous about — a multi-project host (or a no-project
+  // install) leaves it unset so the escalation reports without attributing a
+  // sibling's crash to one project (#510/#530).
+  const recoverProject = project === undefined || multiProject ? undefined : project.name;
+  const recoverUnitContent = renderRecoverUnit(runtime, recoverProject);
   const recoverUnit: PlannedWrite<string> = {
     path: recoverUnitPath,
     action: actionFor(recoverUnitPath, recoverUnitContent),
@@ -744,39 +1217,139 @@ export function planHostRuntime(
     content: recoverScriptContent,
     value: recoverScriptContent,
   };
+  // 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[] = [
+    {
+      title: "install the recovery playbook",
+      argv: ["install", "-m", "0755", recoverScriptPath, recoverScriptInstallPath],
+    },
+    {
+      title: `install ${RECOVER_SERVICE_NAME}`,
+      argv: ["install", "-m", "0644", recoverUnitPath, join(unitDir, RECOVER_SERVICE_NAME)],
+    },
+    { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
+    {
+      title: `install ${STAGED_SERVICE_NAME}`,
+      argv: ["install", "-m", "0644", servicePath, installedPath],
+    },
+    { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
+    { title: `enable ${STAGED_SERVICE_NAME}`, argv: ["systemctl", "enable", STAGED_SERVICE_NAME] },
+    { title: `restart ${STAGED_SERVICE_NAME}`, argv: ["systemctl", "restart", STAGED_SERVICE_NAME] },
+    // The herdr session server, provisioned alongside the daemon (#456). Only
+    // when herdr is installed and the plan therefore staged a unit.
+    ...(herdrUnit === undefined
+      ? []
+      : [
+          {
+            title: `install ${DEFAULT_HERDR_UNIT}`,
+            argv: ["install", "-m", "0644", herdrUnitPath, installedHerdr],
+          },
+          { title: "reload systemd", argv: ["systemctl", "daemon-reload"] },
+          { title: `enable ${DEFAULT_HERDR_UNIT}`, argv: ["systemctl", "enable", DEFAULT_HERDR_UNIT] },
+          // The pane-shell merge lands *before* the restart it accompanies, so
+          // the session server comes up with the pinned shell, not the stale
+          // config. It runs without sudo on purpose: the file is the fleet
+          // account's own (the escalation guard guarantees setup runs as that
+          // account), and a root-owned copy would break herdr's next rewrite.
+          // Nothing writes herdr's live config until this consent-gated step.
+          ...(herdrConfig === undefined || actionFor(herdrConfigPath, herdrConfig.content) === "keep"
+            ? []
+            : [
+                {
+                  title: `write the pane shell into ${herdrConfigPath}`,
+                  argv: ["install", "-m", "0644", herdrConfigStagedPath, herdrConfigPath],
+                  unprivileged: true,
+                },
+              ]),
+          // The herdr-conductor config.env (#541) rides the same consent-gated,
+          // unprivileged, pre-restart lane: recover.sh sources it on every
+          // startup, so the session server must come up already pointing at
+          // this host's fleet cwds and telegram files.
+          ...(herdrEnv === undefined || actionFor(herdrEnvTarget, herdrEnv.content) === "keep"
+            ? []
+            : [
+                {
+                  title: `write the herdr-conductor config.env into ${herdrEnvTarget}`,
+                  argv: ["install", "-m", "0644", herdrEnvStagedPath, herdrEnvTarget],
+                  unprivileged: true,
+                },
+              ]),
+          { title: `restart ${DEFAULT_HERDR_UNIT}`, argv: ["systemctl", "restart", DEFAULT_HERDR_UNIT] },
+        ]),
+  ];
+  // 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
+  // nothing to restart. The herdr unit is absent on a host without herdr, and
+  // an absent unit that would not be provisioned is nothing to do.
+  const installedAction = actionFor(installedPath, serviceContent);
+  const currentInstall =
+    installedAction === "keep" &&
+    actionFor(join(unitDir, RECOVER_SERVICE_NAME), recoverUnitContent) === "keep" &&
+    actionFor(recoverScriptInstallPath, recoverScriptContent) === "keep" &&
+    (herdrUnit === undefined || actionFor(installedHerdr, herdrUnit.content) === "keep") &&
+    // The pane-shell file is a destination like the units: a re-run with all
+    // units current but the config merge still pending must not report
+    // "nothing to install" and skip the very write the plan exists to make.
+    (herdrConfig === undefined || actionFor(herdrConfigPath, herdrConfig.content) === "keep") &&
+    // Same for the herdr-conductor config.env: pending env merge is pending
+    // work, not an already-current install.
+    (herdrEnv === undefined || actionFor(herdrEnvTarget, herdrEnv.content) === "keep");
   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.
-    ...(herdrUnit === undefined ? {} : { herdrUnit, herdrConfig }),
+    // 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 }),
+    ...(herdrConfig === undefined ? {} : { herdrConfig, herdrConfigTarget }),
+    ...(herdrConfigProblem === undefined ? {} : { herdrConfigProblem }),
+    ...(herdrConfigWarning === undefined ? {} : { herdrConfigWarning }),
+    ...(herdrEnv === undefined ? {} : { herdrEnv, herdrEnvTarget }),
     recoverUnit,
     recoverScript,
-    briefLink: planBriefLink(project),
-    ...(project.escalation.orchestrator === "external"
-      ? { tick: planTick(project, telegramStateDir) }
-      : {}),
-    installCommands: [
-      // Recovery first: the daemon unit that follows names it in OnFailure=,
-      // so the restart below must never point at a unit systemd cannot load.
-      `sudo install -m 0755 ${shellQuote(recoverScriptPath)} ${shellQuote(RECOVER_SCRIPT_INSTALL_PATH)}`,
-      `sudo install -m 0644 ${shellQuote(recoverUnitPath)} ${shellQuote(join(SYSTEMD_UNIT_DIR, RECOVER_SERVICE_NAME))}`,
-      "sudo systemctl daemon-reload",
-      `sudo install -m 0644 ${shellQuote(servicePath)} ${shellQuote(installedPath)}`,
-      "sudo systemctl daemon-reload",
-      `sudo systemctl enable ${STAGED_SERVICE_NAME}`,
-      `sudo systemctl restart ${STAGED_SERVICE_NAME}`,
-      ...(herdrUnit === undefined
-        ? []
-        : [
-            `sudo install -m 0644 ${shellQuote(herdrUnitPath)} ${shellQuote(installedHerdr)}`,
-            "sudo systemctl daemon-reload",
-            `sudo systemctl enable ${DEFAULT_HERDR_UNIT}`,
-            `sudo systemctl restart ${DEFAULT_HERDR_UNIT}`,
-          ]),
-    ],
+    ...(project === undefined
+      ? {
+          // Host-global install: the per-project tail entities are not written,
+          // and the plan says exactly which files and how to write them.
+          noProject: {
+            skipped: [TICK_CONFIG_FILE, AGENTS_BRIEF_NAME],
+            how: "re-run `omp-conductor setup host <NAME>` (or --project NAME) to write them for one project",
+          },
+        }
+      : {
+          briefLink: planBriefLink(project),
+          ...(project.escalation.orchestrator === "external"
+            ? (() => {
+                const planned = planTick(project, telegramStateDir);
+                return {
+                  ...(planned.previousAgentName === undefined || runtime.herdr === undefined
+                    ? {}
+                    : {
+                        // The restamp that made the tick's agentName no longer
+                        // the shared default: the live pane (if any) still
+                        // carries the old name, and setup will rename it after
+                        // the install — or print the exact command.
+                        agentRename: {
+                          session: runtime.herdrSession ?? DEFAULT_HERDR_SESSION,
+                          from: planned.previousAgentName,
+                          to: project.name,
+                        },
+                      }),
+                  tick: planned.write,
+                };
+              })()
+            : {}),
+        }),
+    steps: installSteps,
+    // For humans to read; the executed form is {@link steps}, in argv.
+    installCommands: installSteps.map((s) => formatStep(s)),
     cliSource: runtime.cli === undefined ? "plugin" : "global",
     installedPath,
-    installedAction: actionFor(installedPath, serviceContent),
+    installedAction,
+    currentInstall,
   };
 }
 
@@ -791,7 +1364,16 @@ export function formatHostRuntimePlan(plan: HostRuntimePlan): string {
       ? ["  herdr session  skipped — herdr not installed on this host"]
       : [
           `  herdr session  ${plan.herdrUnit.action} ${plan.herdrUnit.path}`,
-          `  pane shell     ${plan.herdrConfig!.action} ${plan.herdrConfig!.path} ([terminal] default_shell)`,
+          ...(plan.herdrConfig === undefined
+            ? [`  pane shell     skipped — ${plan.herdrConfigProblem ?? "login shell unusable"}`]
+            : [`  pane shell     ${plan.herdrConfig.action} ${plan.herdrConfig.path} ([terminal] default_shell)`]),
+          ...(plan.herdrConfigWarning === undefined ? [] : [`  pane resume    warn — ${plan.herdrConfigWarning}`]),
+          ...(plan.herdrEnv === undefined
+            ? []
+            : [`  herdr env      ${plan.herdrEnv.action} ${plan.herdrEnv.path} -> ${plan.herdrEnvTarget}`]),
+          ...(plan.agentRename === undefined
+            ? []
+            : [`  agent rename   ${plan.agentRename.from} -> ${plan.agentRename.to} in session ${plan.agentRename.session}`]),
         ]),
   ];
   if (plan.tick !== undefined) {
@@ -804,11 +1386,19 @@ export function formatHostRuntimePlan(plan: HostRuntimePlan): string {
   } else {
     lines.push("  heartbeat      embedded orchestrator — no external tick config");
   }
-  lines.push(
-    plan.briefLink.action === "skip"
-      ? `  brief link     ${plan.briefLink.path} — ${plan.briefLink.skippedReason}`
-      : `  brief link     ${plan.briefLink.action} ${plan.briefLink.path} -> ${plan.briefLink.target}`,
-  );
+  if (plan.noProject !== undefined) {
+    lines.push(
+      `  per-project    skipped (no project named): ${plan.noProject.skipped.join(", ")}`,
+      `                 ${plan.noProject.how}`,
+    );
+  }
+  if (plan.briefLink !== undefined) {
+    lines.push(
+      plan.briefLink.action === "skip"
+        ? `  brief link     ${plan.briefLink.path} — ${plan.briefLink.skippedReason}`
+        : `  brief link     ${plan.briefLink.action} ${plan.briefLink.path} -> ${plan.briefLink.target}`,
+    );
+  }
   lines.push("  install        staged only; the final result prints the systemd install commands");
   return lines.join("\n");
 }
@@ -850,6 +1440,10 @@ export function writeHostRuntime(plan: HostRuntimePlan): HostRuntimeWrite {
     atomicWrite(plan.herdrConfig.path, plan.herdrConfig.content, 0o644);
     wrote.push(plan.herdrConfig.path);
   }
+  if (plan.herdrEnv !== undefined && plan.herdrEnv.action !== "keep") {
+    atomicWrite(plan.herdrEnv.path, plan.herdrEnv.content, 0o644);
+    wrote.push(plan.herdrEnv.path);
+  }
   if (plan.recoverUnit.action !== "keep") {
     atomicWrite(plan.recoverUnit.path, plan.recoverUnit.content, 0o644);
     wrote.push(plan.recoverUnit.path);
@@ -868,7 +1462,8 @@ export function writeHostRuntime(plan: HostRuntimePlan): HostRuntimeWrite {
   // (an operator may drop a regular file where a stale symlink was planned for
   // replacement). Re-lstat at write time and act on *current* state, so a file
   // that appears mid-flight is preserved, never unlinked by a stale plan.
-  if (plan.briefLink.action === "create" || plan.briefLink.action === "update") {
+  // A host-global plan (no project) has no briefLink to write at all.
+  if (plan.briefLink !== undefined && (plan.briefLink.action === "create" || plan.briefLink.action === "update")) {
     const { path, target } = plan.briefLink;
     try {
       mkdirSync(dirname(path), { recursive: true });