omp-conductor 0.15.12 → 0.15.13

package/src/setup-host.ts

@@ -23,8 +23,10 @@ import {
 import {
   legacyArmedMarkerPath,
   readTickConfig,
+  parseHerdrAgents,
   TICK_CONFIG_FILE,
   tickConfigMatchesProject,
+  type HerdrAgentList,
   type TickConfig,
 } from "./orchestrator-tick.ts";
 import { formatStep, type PrivilegedStep } from "./privileged.ts";
@@ -142,6 +144,32 @@ export interface HostRuntimePlan {
   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;
@@ -599,9 +627,25 @@ export function usableHerdrShell(shell: string): boolean {
  * 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 {
+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 ?? "";
-  if (!usableHerdrShell(shell)) return text;
+  // 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}`;
@@ -612,23 +656,246 @@ export function renderHerdrConfig(shell: string, existing?: string): string {
   // 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 real key keeps its position and gets the new value in place —
+  // 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)) {
-    return text.replace(keyLine, `$1${quoted}`);
+    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[] {
@@ -730,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 };
 
@@ -758,7 +1031,19 @@ 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(
@@ -805,10 +1090,14 @@ export function planHostRuntime(
   // 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);
@@ -846,7 +1135,9 @@ export function planHostRuntime(
         `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 configContent = renderHerdrConfig(runtime.shell, existing);
+      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
@@ -872,6 +1163,37 @@ export function planHostRuntime(
       };
       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(unitDir, STAGED_SERVICE_NAME);
   const installedHerdr = join(unitDir, DEFAULT_HERDR_UNIT);
@@ -942,6 +1264,19 @@ export function planHostRuntime(
                   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] },
         ]),
   ];
@@ -958,7 +1293,10 @@ export function planHostRuntime(
     // 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");
+    (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
@@ -968,6 +1306,8 @@ export function planHostRuntime(
     ...(herdrUnit === undefined ? {} : { herdrUnit }),
     ...(herdrConfig === undefined ? {} : { herdrConfig, herdrConfigTarget }),
     ...(herdrConfigProblem === undefined ? {} : { herdrConfigProblem }),
+    ...(herdrConfigWarning === undefined ? {} : { herdrConfigWarning }),
+    ...(herdrEnv === undefined ? {} : { herdrEnv, herdrEnvTarget }),
     recoverUnit,
     recoverScript,
     ...(project === undefined
@@ -982,7 +1322,25 @@ export function planHostRuntime(
       : {
           briefLink: planBriefLink(project),
           ...(project.escalation.orchestrator === "external"
-            ? { tick: planTick(project, telegramStateDir) }
+            ? (() => {
+                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,
@@ -1009,6 +1367,13 @@ export function formatHostRuntimePlan(plan: HostRuntimePlan): string {
           ...(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) {
@@ -1075,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);

package/src/setup-install.ts

@@ -19,7 +19,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { platform } from "node:os";
 import { join } from "node:path";
 import { loadConfig, stateDir } from "./config.ts";
-import { pauseInstance, setPaused, statusSnapshot } from "./daemon.ts";
+import { pauseInstance, pauseSourceToken, setPaused, statusSnapshot } from "./daemon.ts";
 import { fleetLayers, DEFAULT_HERDR_UNIT } from "./fleet.ts";
 import { livingDaemon } from "./lifecycle.ts";
 import { dbPath, openStore } from "./store.ts";
@@ -44,13 +44,16 @@ import {
 import { probeCodeGraph, type CodeGraphHealth } from "./graph-health.ts";
 import { runPrivileged, type PrivilegedDeps, type PrivilegedStep } from "./privileged.ts";
 import {
+  agentRenameVerdict,
   checkEscalation,
+  DEFAULT_AGENT_RENAME_DEPS,
   planHostRuntime,
   totalConfiguredWorkers,
   writeHostRuntime,
   STAGED_SERVICE_NAME,
   SYSTEMD_UNIT_DIR,
   RECOVER_SCRIPT_INSTALL_PATH,
+  type AgentRenameDeps,
   type EscalationDeps,
   type ServiceRuntime,
 } from "./setup-host.ts";
@@ -108,6 +111,12 @@ export interface InstallDeps {
      *  attributed before the session host restarts under them. */
     drainStore?: Pick<Store, "liveRuns" | "updateRun">;
   };
+  /**
+   * The live herdr CLI seam for the post-install agent rename (#541).
+   * Injectable so tests pin the verdict without touching the host's herdr; the
+   * default is the same `herdr --session` CLI recover.sh and the tick use.
+   */
+  agentRename?: AgentRenameDeps;
 }
 
 /**
@@ -185,6 +194,7 @@ export async function runHostInstall(
   // No pane-shell key is planned (unusable login shell, unparseable config):
   // the operator hears why before the consent prompt, not after an install
   // that quietly had nothing to say about the shell.
+  if (plan.herdrConfigWarning !== undefined) ui.notify(plan.herdrConfigWarning, "warning");
   if (plan.herdrConfigProblem !== undefined) ui.notify(plan.herdrConfigProblem, "warning");
   // A host-global install (no --project): the per-project tail was
   // deliberately not written, and the operator must be told which files and
@@ -299,6 +309,34 @@ export async function runHostInstall(
   }
   if (fence !== undefined && !fence.initialPaused) drainDeps.setPaused(false, fence.scope.pauseKey);
   ui.notify(`Installed and started ${STAGED_SERVICE_NAME}.`, "info");
+  // #541: the tick plan may have restamped agentName away from the shared
+  // default — the exact moment the live pane is stuck under the old name and
+  // every tick declines with the rename hint. Perform the rename now that the
+  // herdr session has (re)started, safely: exactly one pane carrying the old
+  // identity is renamed; zero, several, or an unreadable agent list prints the
+  // exact command and says why it was not run. Never guesses a pane.
+  if (plan.agentRename !== undefined) {
+    const renameDeps = deps.agentRename ?? DEFAULT_AGENT_RENAME_DEPS;
+    const verdict = agentRenameVerdict(
+      renameDeps.list(plan.agentRename.session),
+      plan.agentRename.from,
+      plan.agentRename.to,
+      plan.agentRename.session,
+    );
+    if (verdict.kind === "rename") {
+      const ran = renameDeps.rename(plan.agentRename.session, verdict.pane, plan.agentRename.to);
+      if (ran.ok) {
+        ui.notify(`Renamed the herdr agent in pane ${verdict.pane} to ${plan.agentRename.to}.`, "info");
+      } else {
+        ui.notify(
+          `The herdr agent rename did not go through (${ran.problem ?? "unknown"}): ${verdict.command} — the pane still carries the old name.`,
+          "warning",
+        );
+      }
+    } else {
+      ui.notify(`${verdict.reason}; run it by hand: ${verdict.command}`, "warning");
+    }
+  }
   return { kind: "installed", wrote };
 }
 
@@ -321,7 +359,7 @@ function hostInstallDrainDeps(ui: WizardUi, deps: InstallDeps): DrainDeps {
         : { running: true, project: daemon.project, generation: `${daemon.pid}@${daemon.startedAt}` };
     },
     pauseState: (project) => pauseInstance(project),
-    setPaused: (v, project) => setPaused(v, { source: "setup host", reason: "setup host, draining" }, project),
+    setPaused: (v, project) => setPaused(v, { source: pauseSourceToken("setup host"), reason: "setup host, draining" }, project),
     sleep: Bun.sleep,
     log: (message) => ui.notify(message, "info"),
   };