omp-conductor 0.15.11 → 0.15.12

package/src/setup-host.ts

@@ -27,6 +27,7 @@ import {
   tickConfigMatchesProject,
   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 +91,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 +127,45 @@ 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;
   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 +183,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 +243,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 +460,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 +513,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 +541,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 +561,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,17 +594,30 @@ 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('"', '\\"')}"`;
   const text = existing ?? "";
+  if (!usableHerdrShell(shell)) return 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 real 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;
+  if (keyLine.test(text)) {
+    return text.replace(keyLine, `$1${quoted}`);
   }
 
   const lines = text.split("\n");
@@ -671,7 +762,14 @@ function planTick(project: ProjectConfig, telegramStateDir: string): PlannedWrit
 }
 
 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 +777,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 +799,16 @@ 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");
   let herdrUnit: PlannedWrite<string> | undefined;
   let herdrConfig: PlannedWrite<string> | undefined;
+  let herdrConfigTarget: string | undefined;
+  let herdrConfigProblem: 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 +837,52 @@ 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 configContent = renderHerdrConfig(runtime.shell, existing);
+      // 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;
+    }
   }
-  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 +895,103 @@ 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,
+                },
+              ]),
+          { 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");
   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 }),
     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"
+            ? { tick: planTick(project, telegramStateDir) }
+            : {}),
+        }),
+    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 +1006,9 @@ 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)`]),
         ]),
   ];
   if (plan.tick !== undefined) {
@@ -804,11 +1021,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");
 }
@@ -868,7 +1093,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 });