omp-conductor 0.15.9 → 0.15.11

package/src/setup-host.ts

@@ -1,10 +1,16 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync, type Stats } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { homedir, userInfo } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { configPath, loadConfig, resolveCaps, stateDir } from "./config.ts";
 import { isPaused, runDaemon, statusSnapshot, type StatusSnapshot } from "./daemon.ts";
-import { DEFAULT_FLEET_AGENT_NAME, DEFAULT_HERDR_SESSION, resolveHerdrSessionWithBridge } from "./fleet.ts";
+import { ORCHESTRATOR_BRIEF_NAME } from "./brief-upgrade.ts";
+import {
+  DEFAULT_FLEET_AGENT_NAME,
+  DEFAULT_HERDR_SESSION,
+  DEFAULT_HERDR_UNIT,
+  resolveHerdrSessionWithBridge,
+} from "./fleet.ts";
 import {
   DEFAULT_PORT,
   healthCheck,
@@ -27,6 +33,34 @@ export const DEFAULT_TICK_INTERVAL_SECONDS = 900;
 export const STAGED_SERVICE_NAME = "omp-conductor.service";
 export const SYSTEMD_UNIT_DIR = "/etc/systemd/system";
 
+/**
+ * The one recovery unit every fleet unit's `OnFailure=` points at (#485).
+ *
+ * A plain (non-template) unit on purpose: both fleet units name the same
+ * oneshot, and the playbook it runs determines which unit failed from live
+ * systemd state rather than trusting an instance name it cannot verify. The
+ * unit itself never carries `OnFailure=` — the one hard bound on
+ * recovery-triggering-recovery.
+ */
+export const RECOVER_SERVICE_NAME = "omp-conductor-recover.service";
+
+/** The playbook file shipped in the package's `systemd/` directory. */
+const RECOVER_SCRIPT_FILE = "omp-conductor-recover.sh";
+
+/**
+ * Where `setup host` installs the recovery playbook so the unit's ExecStart is
+ * a stable absolute path that survives package upgrades. /usr/local/sbin is
+ * root-executed operational tooling, on PATH for root on every target host.
+ */
+export const RECOVER_SCRIPT_INSTALL_PATH = "/usr/local/sbin/omp-conductor-recover";
+
+/**
+ * The symlink the session cwd loads as its brief. omp auto-loads `AGENTS.md`
+ * from the session cwd, so the fleet pane's cwd needs a link at this name
+ * resolving to the composed {@link ORCHESTRATOR_BRIEF_NAME}.
+ */
+export const AGENTS_BRIEF_NAME = "AGENTS.md";
+
 export type PlannedWrite<T> = {
   path: string;
   action: "create" | "update" | "keep";
@@ -34,9 +68,59 @@ export type PlannedWrite<T> = {
   value: T;
 };
 
+/**
+ * The `AGENTS.md` symlink setup places in a project's fleet cwd so the pane's
+ * session auto-loads the composed brief instead of staying brief-less.
+ *
+ * {@link action} is what the plan will *do*, compared against what sits at
+ * {@link path}:
+ *  - `create` — no entry yet, link it;
+ *  - `update` — a symlink occupies {@link path} but points elsewhere, replace it;
+ *  - `keep` — an already-correct symlink, leave untouched (idempotent re-run);
+ *  - `skip` — a regular file occupies {@link path}, never overwrite an
+ *    operator's file (see {@link skippedReason}).
+ */
+export interface BriefLinkPlan {
+  /** `AGENTS.md` inside the project's fleet cwd ({@link tickCwdForProject}). */
+  path: string;
+  /** Relative target inside the symlink — what the link resolves to. */
+  target: string;
+  action: "create" | "update" | "keep" | "skip";
+  /** Why {@link action} is `skip`; present only then. */
+  skippedReason?: string;
+}
+
 export interface HostRuntimePlan {
   service: PlannedWrite<string>;
+  /**
+   * The staged Herdr session-server unit. Absent when Herdr is not installed
+   * ({@link ServiceRuntime.herdr} is `undefined`) — a host driving Herdr some
+   * other way must stay supported. `upgrade` and `start` treat
+   * {@link DEFAULT_HERDR_UNIT} as a first-class dependency, and this is the
+   * rendering that provisions it (see {@link renderHerdrUnit}).
+   */
+  herdrUnit?: PlannedWrite<string>;
+  /**
+   * The fleet recovery oneshot (#485): staged always, because the daemon unit
+   * (which every fleet has) carries `OnFailure=` to it. Rendered by
+   * {@link renderRecoverUnit}.
+   */
+  recoverUnit: PlannedWrite<string>;
+  /**
+   * The recovery playbook body, staged from the shipped package file and
+   * installed to {@link RECOVER_SCRIPT_INSTALL_PATH} so the unit's ExecStart
+   * is a stable absolute path.
+   */
+  recoverScript: PlannedWrite<string>;
+  /**
+   * `[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.
+   */
+  herdrConfig?: PlannedWrite<string>;
   tick?: PlannedWrite<TickConfig>;
+  /** The `AGENTS.md` — composed-brief symlink — placed in the fleet cwd. */
+  briefLink: BriefLinkPlan;
   installCommands: readonly string[];
   cliSource: "global" | "plugin";
   /** Absolute path of the unit systemd actually reads. */
@@ -65,6 +149,21 @@ export interface ServiceRuntime {
   packageCli: string;
   conductorHome: string;
   telegramStateDir: string;
+  /**
+   * The account's login shell. Rendered into the Herdr session unit as
+   * `Environment=SHELL=` (and into the herdr config as `[terminal]
+   * default_shell`), so every pane in the fleet session runs this shell instead
+   * of the `/bin/sh` Herdr falls back to when `$SHELL` is unset (the fleet's
+   * dash-pane symptom, #456). A systemd service has no `$SHELL`, so this is
+   * load-bearing, not decoration.
+   */
+  shell: string;
+  /**
+   * Absolute path of the `herdr` binary on this host, or `undefined` when Herdr
+   * is not installed. When absent, setup stages no Herdr unit and no pane-shell
+   * config — a host driving Herdr some other way stays supported (#456).
+   */
+  herdr?: string;
   /**
    * Non-default Herdr session to pin into the unit (#394). Omitted when the
    * host uses {@link DEFAULT_HERDR_SESSION}: an always-present line would show
@@ -252,6 +351,8 @@ function defaultServiceRuntime(
   const home = homedir();
   const bun = process.execPath;
   const globalCli = Bun.which("omp-conductor");
+  const herdr = Bun.which("herdr");
+  const loginShell = userInfo().shell;
   const pathParts = [dirname(bun), ...(process.env["PATH"] ?? "").split(":")].filter(
     (value, index, all) => value.length > 0 && all.indexOf(value) === index,
   );
@@ -264,6 +365,10 @@ function defaultServiceRuntime(
     packageCli: join(import.meta.dir, "cli.ts"),
     conductorHome: dirname(configPath()),
     telegramStateDir,
+    shell: loginShell ?? "/bin/sh",
+    // Only when Herdr is actually installed: a host running Herdr some other
+    // way (or none yet) gets no Herdr unit rendered, ever.
+    ...(herdr === null ? {} : { herdr }),
     // Only pin a non-default session. Default hosts keep a unit with no
     // HERDR_SESSION line so setup/upgrade do not invent drift (#394).
     ...(herdrSession !== DEFAULT_HERDR_SESSION ? { herdrSession } : {}),
@@ -289,6 +394,10 @@ export function renderDaemonService(runtime: ServiceRuntime, totalWorkers: numbe
     "Documentation=https://github.com/TerrifiedBug/conductor",
     "After=network-online.target",
     "Wants=network-online.target",
+    // #485: a crash-looped daemon used to sit in `failed` indefinitely, in
+    // silence — no unit was watching it. The recovery oneshot runs outside
+    // this unit's cgroup, collects evidence durably, and pages tier-2.
+    `OnFailure=${RECOVER_SERVICE_NAME}`,
     "",
     "[Service]",
     "Type=simple",
@@ -315,6 +424,122 @@ export function renderDaemonService(runtime: ServiceRuntime, totalWorkers: numbe
   ].join("\n");
 }
 
+/**
+ * The Herdr session-server unit, in the same shape as the daemon unit.
+ *
+ * The fleet's 24/7 guarantee (`upgrade`'s restart + pane-recovery leg, `start`,
+ * the recovery plugin) treats {@link DEFAULT_HERDR_UNIT} as a first-class
+ * dependency, yet nothing rendered it — every operator hand-wrote it from a bare
+ * `ExecStart=` line. This provisions it, and it is where the dash-pane bug dies:
+ * a systemd service has no `$SHELL`, so without `Environment=SHELL=` Herdr
+ * resolved every pane as `/bin/sh`→dash with no readline and no `.bashrc`. The
+ * account's login shell is pinned here, and again in the herdr config
+ * ({@link renderHerdrConfig}) as belt and braces.
+ */
+export function renderHerdrUnit(runtime: ServiceRuntime): string {
+  if (runtime.herdr === undefined) throw new Error("cannot render a herdr unit without a herdr binary");
+  const session = runtime.herdrSession ?? DEFAULT_HERDR_SESSION;
+  const configPath = join(runtime.home, ".config", "herdr", "config.toml");
+  return [
+    "[Unit]",
+    "Description=herdr fleet session server",
+    "Documentation=https://github.com/TerrifiedBug/conductor",
+    "After=network-online.target",
+    "Wants=network-online.target",
+    // #485: the fleet's two units are each other's only plausible watcher and
+    // neither watched the other. The recovery oneshot is the watcher, and it
+    // must fire for the orchestrator host too — a dead herdr means no tick, so
+    // nobody else would ever report it.
+    `OnFailure=${RECOVER_SERVICE_NAME}`,
+    "",
+    "[Service]",
+    "Type=simple",
+    `User=${runtime.username}`,
+    `Environment=${systemdQuote(`HOME=${runtime.home}`)}`,
+    `Environment=${systemdQuote(`PATH=${runtime.path}`)}`,
+    `Environment=${systemdQuote(`HERDR_CONFIG_PATH=${configPath}`)}`,
+    `Environment=${systemdQuote(`SHELL=${runtime.shell}`)}`,
+    `WorkingDirectory=${systemdPath(runtime.conductorHome)}`,
+    `ExecStart=${systemdQuote(runtime.herdr)} --session ${systemdQuote(session)} server`,
+    "Restart=on-failure",
+    "RestartSec=5",
+    "",
+    "[Install]",
+    "WantedBy=multi-user.target",
+    "",
+  ].join("\n");
+}
+
+/**
+ * The fleet recovery unit (#485): a oneshot every fleet unit's `OnFailure=`
+ * names.
+ *
+ * It runs as root, outside the fleet units' cgroups and process trees, so the
+ * restart it performs can never take it down, and it carries an explicit PATH —
+ * on a typical host the non-interactive ssh PATH lacks `omp`, `herdr` and
+ * `omp-conductor`, and the playbook needs all three.
+ *
+ * The bounds are part of the unit text so `doctor` drift sees them:
+ * `StartLimitIntervalSec`/`StartLimitBurst` cap failed recovery starts at the
+ * systemd layer (the playbook keeps its own durable consecutive-attempt
+ * counter, agreeing on the same window), and there is deliberately **no**
+ * `OnFailure=` of its own and no `[Install]` — nothing activates recovery
+ * except the two fleet units' failure, so recovery can never re-trigger
+ * recovery.
+ */
+export function renderRecoverUnit(runtime: ServiceRuntime, projectName: string): string {
+  return [
+    "[Unit]",
+    "Description=omp-conductor fleet recovery (OnFailure handler)",
+    "Documentation=https://github.com/TerrifiedBug/conductor",
+    // The oneshot bound: a recovery that fails twice in the window stops
+    // trying, and the playbook's durable counter uses the same window.
+    "StartLimitIntervalSec=1800",
+    "StartLimitBurst=2",
+    "",
+    "[Service]",
+    "Type=oneshot",
+    `Environment=${systemdQuote(`PATH=${runtime.path}`)}`,
+    `Environment=${systemdQuote(`OMP_CONDUCTOR_HOME=${runtime.conductorHome}`)}`,
+    `Environment=${systemdQuote(`RECOVER_STATE_DIR=${stateDir()}`)}`,
+    `Environment=${systemdQuote(`RECOVER_PROJECT=${projectName}`)}`,
+    `ExecStart=${RECOVER_SCRIPT_INSTALL_PATH}`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Idempotently put `[terminal] default_shell` into a herdr config, preserving
+ * everything else verbatim.
+ *
+ * Belt-and-braces behind the unit's `Environment=SHELL=`: a pane comes up as the
+ * 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.
+ */
+export function renderHerdrConfig(shell: string, existing?: string): string {
+  const quoted = `"${shell.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+  const text = existing ?? "";
+  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}`);
+  }
+
+  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`;
+  }
+  // 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[] {
   const roots = [stateDir(), dirname(project.workspaceRoot), project.workspaceRoot];
   return roots.filter((root, index) => roots.indexOf(root) === index);
@@ -373,6 +598,47 @@ export function tickCwdForProject(project: ProjectConfig): string {
   }
 }
 
+/**
+ * Where this project's `AGENTS.md` link should point and what setup will do
+ * about it. The link lives in the **fleet cwd** — the directory the pane runs
+ * in — pointing at the composed brief under `workspaceRoot`, by a relative
+ * target so the tree stays movable.
+ *
+ * A fleet whose tick config predates per-project roots keeps its cwd at the
+ * state dir, so the link is `<stateDir>/AGENTS.md -> worktrees/ORCHESTRATOR.md`;
+ * a brand-new project links `AGENTS.md -> ORCHESTRATOR.md` in its own cwd.
+ *
+ * Never a clobber: a symlink already at the brief is left alone, a stale
+ * symlink is replaceable, and a *regular file* is an operator's own brief —
+ * reported and left untouched.
+ */
+function planBriefLink(project: ProjectConfig): BriefLinkPlan {
+  const path = join(tickCwdForProject(project), AGENTS_BRIEF_NAME);
+  const target = relative(dirname(path), join(project.workspaceRoot, ORCHESTRATOR_BRIEF_NAME));
+  let st;
+  try {
+    st = lstatSync(path);
+  } catch {
+    // ENOENT (no link yet) and any unreadable path (no permission on a parent)
+    // both collapse to a best-effort create; a refused filesystem surfaces as
+    // a warning at write time.
+    return { path, target, action: "create" };
+  }
+  if (st.isSymbolicLink()) {
+    return {
+      path,
+      target,
+      action: readlinkSync(path, "utf8") === target ? "keep" : "update",
+    };
+  }
+  return {
+    path,
+    target,
+    action: "skip",
+    skippedReason: `an existing file at ${path} is not ours to overwrite; left untouched`,
+  };
+}
+
 function planTick(project: ProjectConfig, telegramStateDir: string): PlannedWrite<TickConfig> {
   const found = findProjectTick(project);
   const existing = found === undefined ? undefined : { path: found.path, config: found.config };
@@ -422,17 +688,91 @@ export function planHostRuntime(
     content: serviceContent,
     value: serviceContent,
   };
+  const herdrUnitPath = join(stateDir(), DEFAULT_HERDR_UNIT);
+  const herdrConfigPath = join(runtime.home, ".config", "herdr", "config.toml");
+  let herdrUnit: PlannedWrite<string> | undefined;
+  let herdrConfig: 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);
+  let recoverScriptContent: string;
+  try {
+    recoverScriptContent = readFileSync(join(import.meta.dir, "..", "systemd", RECOVER_SCRIPT_FILE), "utf8");
+  } catch (err) {
+    throw new Error(
+      `cannot read the recovery playbook at ${join(import.meta.dir, "..", "systemd", RECOVER_SCRIPT_FILE)} — it ships with this package, and setup cannot stage it without it: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (runtime.herdr !== undefined) {
+    const unitContent = renderHerdrUnit(runtime);
+    herdrUnit = {
+      path: herdrUnitPath,
+      action: actionFor(herdrUnitPath, unitContent),
+      content: unitContent,
+      value: unitContent,
+    };
+    // Belt and braces: read the session's herdr config so `[terminal]
+    // default_shell` merges into whatever the operator already has, preserving
+    // it verbatim. A missing or unreadable config starts from scratch.
+    let existing: string | undefined;
+    try {
+      existing = readFileSync(herdrConfigPath, "utf8");
+    } catch {
+      existing = undefined;
+    }
+    const configContent = renderHerdrConfig(runtime.shell, existing);
+    herdrConfig = {
+      path: herdrConfigPath,
+      action: actionFor(herdrConfigPath, configContent),
+      content: configContent,
+      value: configContent,
+    };
+  }
   const installedPath = join(SYSTEMD_UNIT_DIR, STAGED_SERVICE_NAME);
+  const installedHerdr = join(SYSTEMD_UNIT_DIR, DEFAULT_HERDR_UNIT);
+  const recoverUnitPath = join(stateDir(), RECOVER_SERVICE_NAME);
+  const recoverUnitContent = renderRecoverUnit(runtime, project.name);
+  const recoverUnit: PlannedWrite<string> = {
+    path: recoverUnitPath,
+    action: actionFor(recoverUnitPath, recoverUnitContent),
+    content: recoverUnitContent,
+    value: recoverUnitContent,
+  };
+  const recoverScript: PlannedWrite<string> = {
+    path: recoverScriptPath,
+    action: actionFor(recoverScriptPath, recoverScriptContent),
+    content: recoverScriptContent,
+    value: recoverScriptContent,
+  };
   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 }),
+    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}`,
+          ]),
     ],
     cliSource: runtime.cli === undefined ? "plugin" : "global",
     installedPath,
@@ -445,6 +785,14 @@ export function formatHostRuntimePlan(plan: HostRuntimePlan): string {
     "host runtime",
     `  service        ${plan.service.action} ${plan.service.path}`,
     `  daemon entry   ${plan.cliSource === "global" ? "installed omp-conductor CLI" : "current installed plugin"}`,
+    `  recovery       ${plan.recoverUnit.action} ${plan.recoverUnit.path}`,
+    `  recovery exec  ${plan.recoverScript.action} ${plan.recoverScript.path} -> ${RECOVER_SCRIPT_INSTALL_PATH}`,
+    ...(plan.herdrUnit === undefined
+      ? ["  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)`,
+        ]),
   ];
   if (plan.tick !== undefined) {
     lines.push(
@@ -456,6 +804,11 @@ 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}`,
+  );
   lines.push("  install        staged only; the final result prints the systemd install commands");
   return lines.join("\n");
 }
@@ -474,17 +827,76 @@ function atomicWrite(path: string, content: string, mode: number): void {
   }
 }
 
-export function writeHostRuntime(plan: HostRuntimePlan): string[] {
-  const written: string[] = [];
+/** What {@link writeHostRuntime} wrote, plus anything it could not. */
+export interface HostRuntimeWrite {
+  /** Paths that were (re)written. */
+  wrote: string[];
+  /** Best-effort failures the caller should surface; setup continues regardless. */
+  warnings: string[];
+}
+
+export function writeHostRuntime(plan: HostRuntimePlan): HostRuntimeWrite {
+  const wrote: string[] = [];
+  const warnings: string[] = [];
   if (plan.service.action !== "keep") {
     atomicWrite(plan.service.path, plan.service.content, 0o644);
-    written.push(plan.service.path);
+    wrote.push(plan.service.path);
+  }
+  if (plan.herdrUnit !== undefined && plan.herdrUnit.action !== "keep") {
+    atomicWrite(plan.herdrUnit.path, plan.herdrUnit.content, 0o644);
+    wrote.push(plan.herdrUnit.path);
+  }
+  if (plan.herdrConfig !== undefined && plan.herdrConfig.action !== "keep") {
+    atomicWrite(plan.herdrConfig.path, plan.herdrConfig.content, 0o644);
+    wrote.push(plan.herdrConfig.path);
+  }
+  if (plan.recoverUnit.action !== "keep") {
+    atomicWrite(plan.recoverUnit.path, plan.recoverUnit.content, 0o644);
+    wrote.push(plan.recoverUnit.path);
+  }
+  if (plan.recoverScript.action !== "keep") {
+    atomicWrite(plan.recoverScript.path, plan.recoverScript.content, 0o755);
+    wrote.push(plan.recoverScript.path);
   }
   if (plan.tick !== undefined && plan.tick.action !== "keep") {
     atomicWrite(plan.tick.path, plan.tick.content, 0o600);
-    written.push(plan.tick.path);
+    wrote.push(plan.tick.path);
+  }
+  // `skip` is a regular file the plan already told the operator would be left
+  // alone; `keep` is an already-correct link. Only create/update touch disk —
+  // and never on the plan's word: the entry can change across the consent gap
+  // (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") {
+    const { path, target } = plan.briefLink;
+    try {
+      mkdirSync(dirname(path), { recursive: true });
+      let st: Stats | undefined;
+      try {
+        st = lstatSync(path);
+      } catch {
+        st = undefined; // ENOENT — nothing there yet; also best-effort if a parent refuses.
+      }
+      if (st !== undefined && !st.isSymbolicLink()) {
+        // A regular file occupies the path (present at plan time, appeared, or
+        // swapped in since). Never clobber an operator's file: warn and carry on.
+        warnings.push(`${path} is a regular file, not ours to overwrite; AGENTS.md brief link skipped`);
+      } else if (st !== undefined && readlinkSync(path, "utf8") === target) {
+        // Already the correct link — leave it untouched, however the plan read it.
+      } else {
+        // Missing, or a stale symlink: (re)link it. Only a *current* symlink is
+        // removed; an operator's file that appears mid-flight survives the write.
+        if (st !== undefined) rmSync(path, { force: true });
+        symlinkSync(target, path);
+        wrote.push(path);
+      }
+    } catch (err) {
+      // Best effort: a filesystem that refuses symlinks must not fail setup.
+      warnings.push(`could not link ${path} -> ${target}: ${err instanceof Error ? err.message : String(err)}`);
+    }
   }
-  return written;
+  return { wrote, warnings };
 }
 
 export interface SetupSmokeResult {