@openparachute/hub 0.5.14-rc.2 → 0.5.14-rc.21

package/src/commands/migrate.ts

@@ -1,50 +1,108 @@
 import { existsSync, mkdirSync, readdirSync, renameSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { CONFIG_DIR } from "../config.ts";
-import { knownServices } from "../service-spec.ts";
+import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import { HUB_SVC } from "../hub-control.ts";
+import { type AliveFn, defaultAlive, processState } from "../process-state.ts";
+import { knownServices, shortNameForManifest } from "../service-spec.ts";
+import { readManifestLenient } from "../services-manifest.ts";
 
 /**
- * `parachute migrate` — sweep unrecognized entries at the ecosystem root
+ * `parachute migrate` — sweep known-cruft entries at the ecosystem root
  * (`~/.parachute/`) into a dated archive directory so pre-restructure cruft
  * doesn't confuse beta installs.
  *
+ * Allowlist-of-what-to-archive (the original 2026-05-27 redesign closed
+ * the prior blocklist-with-safelist shape, hub#440). The risk with the
+ * older shape: anything new appearing at the ecosystem root (a future
+ * module's dir, `hub.db`, a user's own dotfile, etc.) would get swept by
+ * default unless someone remembered to add it to the safelist. Aaron
+ * caught a near-miss where `hub.db` was missing from the safelist; that
+ * was the trigger for flipping the model.
+ *
+ * The new model:
+ *
+ *   - `KNOWN_CRUFT` is the *actual archive criterion* — only entries that
+ *     match a rule there get archived.
+ *   - `KNOWN_ARCHIVABLE_DIRS` covers directories we explicitly sweep (the
+ *     `lens` legacy dir from the Notes→Lens→Notes rename round-trip).
+ *   - Everything else — including new modules' dirs, future state files,
+ *     and the user's own stray files — gets a `[unknown — skipping]`
+ *     annotation and is left in place. The user can remove unknowns
+ *     manually if they want.
+ *
  * Archive, never delete: moved under `.archive-<YYYY-MM-DD>/` so anything
- * swept is recoverable. Dotfiles and the recognized top-level entries
- * (service dirs, services.json, expose-state.json, well-known/) are left
- * alone. Content *inside* service dirs is owned by that service's own
- * migration.
+ * swept is recoverable. Dotfiles at root are still left alone (the user's
+ * own `.env`, `.DS_Store`, prior `.archive-*` dirs).
+ *
+ * Cut-2 safety procedures (also 2026-05-27):
+ *
+ *   - Refuses to sweep while any service in `services.json` (plus the hub)
+ *     is currently running — moving a path a daemon owns would corrupt
+ *     state.
+ *   - SQLite-shaped files (`*.db`, `*.db-wal`, `*.db-shm`) get a `[live-db]`
+ *     risk label and trigger an extra confirmation noting wal/shm
+ *     consistency.
+ *   - The printed plan annotates each item `[safe]` / `[live-db]` /
+ *     `[unknown — skipping]`, sorts skipped items last.
+ *   - Non-TTY invocations refuse without `--yes` so a pipe from CI can't
+ *     accidentally archive a real install.
+ *   - `--list` shows what would happen without prompting (friendlier
+ *     phrasing of `--dry-run`).
  */
 
 export const ARCHIVE_PREFIX = ".archive-";
 
 /**
- * Top-level names we keep in place. Service dirs derive from
- * `knownServices()` so adding a service doesn't require touching migrate;
- * `hub` is added explicitly since it's an internal-only lifecycle dir not
- * in SERVICE_SPECS.
+ * Top-level names we leave in place. Service dirs derive from
+ * `knownServices()`; `hub` is added explicitly since it's an internal-only
+ * lifecycle dir not in SERVICE_SPECS. Stays in step with the rest of the
+ * hub's view of what belongs at the root, so `migrateNotice` and
+ * `parachute install`'s post-install hint don't false-positive on the
+ * latest legitimate root entries.
  *
- * `lens` is kept across the Notes→Lens→Notes rename round-trip
- * (Apr 19 → Apr 22): users who installed during the brief Lens window
- * have `~/.parachute/lens/` dirs that shouldn't get swept into
- * `.archive-*` on upgrade. Safe to remove once launch users have all
- * had a chance to re-install under the restored name.
+ * Note: under the allowlist model the safelist is now informational —
+ * archiving only ever happens for entries that match an explicit rule
+ * (`KNOWN_CRUFT` / `KNOWN_ARCHIVABLE_DIRS`). The safelist is still
+ * retained so `migrateNotice`'s count of "things at the root that aren't
+ * recognized" stays meaningful, and so safelisted entries don't show up
+ * as `[unknown — skipping]` noise in the plan.
  */
 export function safelistEntries(): Set<string> {
   return new Set<string>([
     ...knownServices(),
-    "lens",
     "hub",
     "services.json",
     "expose-state.json",
+    "cloudflared-state.json",
+    "hub.db",
+    "hub.db-wal",
+    "hub.db-shm",
     "well-known",
+    "cloudflared",
   ]);
 }
 
 /**
- * Friendly labels for entries we've seen in the wild. Matched by exact name
- * or (for sqlite companion files) by prefix. Purely cosmetic — drives the
- * annotation column in the plan printout.
+ * Allowlist of known-archivable directories. Distinct from `KNOWN_CRUFT`
+ * (which matches by name/prefix predicate) — directories listed here are
+ * always treated as `safe` to archive.
+ *
+ * `lens` is the only entry: a legacy directory left over from the brief
+ * Notes→Lens→Notes rename round-trip (2026-04-19 → 2026-04-22). Users who
+ * installed during that window have `~/.parachute/lens/` dirs that should
+ * be archived now that the rename is finished. Safe to drop from this
+ * list once enough operator cycles have passed to be confident no
+ * install is still on the Lens-era code path.
+ */
+export const KNOWN_ARCHIVABLE_DIRS: ReadonlySet<string> = new Set<string>(["lens"]);
+
+/**
+ * Known-cruft rules. Each rule names a label (the friendly description in
+ * the plan) and a predicate that matches by name or prefix. Under the
+ * 2026-05-27 redesign this is the *primary* archive criterion: an entry
+ * at the ecosystem root that doesn't match here (or `KNOWN_ARCHIVABLE_DIRS`)
+ * is treated as unknown and left in place.
  */
 const KNOWN_CRUFT: Array<{ match: (name: string) => boolean; label: string }> = [
   {
@@ -61,24 +119,49 @@ const KNOWN_CRUFT: Array<{ match: (name: string) => boolean; label: string }> =
   },
 ];
 
-function annotationFor(name: string): string | undefined {
+function cruftLabel(name: string): string | undefined {
   for (const rule of KNOWN_CRUFT) if (rule.match(name)) return rule.label;
   return undefined;
 }
 
-export interface ArchiveItem {
+/**
+ * SQLite shape — `.db` plus its WAL/SHM companions. Files with this shape
+ * carry the `live-db` risk label and pull a second confirmation in the
+ * interactive path because the three files are only consistent as a set.
+ */
+function isSqliteShape(name: string): boolean {
+  return /\.db(?:-wal|-shm)?$/.test(name);
+}
+
+export type RiskLabel = "safe" | "live-db" | "unknown";
+
+export interface PlanItem {
   name: string;
   absPath: string;
   kind: "file" | "dir";
   bytes: number;
+  /** Friendly description (e.g. "legacy parachute-daily state"). */
   annotation?: string;
+  risk: RiskLabel;
+  /** True iff this item will actually be moved into the archive. */
+  archive: boolean;
 }
 
+/**
+ * Kept as an alias for back-compat with callers / older tests that import
+ * `ArchiveItem`. Same shape as `PlanItem`.
+ */
+export type ArchiveItem = PlanItem;
+
 export interface ArchivePlan {
   archiveDirName: string;
   archiveDir: string;
-  items: ArchiveItem[];
+  /** Every entry encountered at the root (archivable + skipped). */
+  items: PlanItem[];
+  /** Total bytes across `archive: true` items only. */
   totalBytes: number;
+  /** True iff at least one `archive: true` item is a SQLite-shape file. */
+  hasLiveDb: boolean;
 }
 
 function sizeOf(path: string): number {
@@ -95,12 +178,36 @@ function archiveDirName(now: Date): string {
   return `${ARCHIVE_PREFIX}${now.toISOString().slice(0, 10)}`;
 }
 
+/**
+ * Classify a single root entry against the allowlist + known-cruft rules.
+ * `safelist` is the recognized-and-leave-alone set; nothing on it ever
+ * reaches the plan at all (filtered out upstream).
+ */
+function classify(name: string): { risk: RiskLabel; annotation?: string; archive: boolean } {
+  const cruft = cruftLabel(name);
+  if (cruft) {
+    const risk: RiskLabel = isSqliteShape(name) ? "live-db" : "safe";
+    return { risk, annotation: cruft, archive: true };
+  }
+  if (KNOWN_ARCHIVABLE_DIRS.has(name)) {
+    return { risk: "safe", annotation: "legacy directory", archive: true };
+  }
+  return { risk: "unknown", archive: false };
+}
+
 /**
  * Inspect the ecosystem root and build a plan. Pure-ish: reads filesystem
- * but never mutates. Returns zero-length items when nothing is archivable.
+ * but never mutates. Returns zero-length items when nothing is at the root
+ * beyond the safelist.
  *
  * Rule: skip anything starting with "." (dotfiles are the user's — `.env`,
  * `.DS_Store`, prior `.archive-*` dirs, etc.) and anything in the safelist.
+ * Everything else goes into the plan with a classification; only items
+ * with `archive: true` are actually swept.
+ *
+ * Sort order: archivable items first (alphabetical), then skipped items
+ * last — keeps the "what will happen" reading at the top of the plan
+ * printout.
  */
 export function planArchive(configDir: string, now: Date): ArchivePlan {
   const dirName = archiveDirName(now);
@@ -110,6 +217,7 @@ export function planArchive(configDir: string, now: Date): ArchivePlan {
     archiveDir,
     items: [],
     totalBytes: 0,
+    hasLiveDb: false,
   };
   if (!existsSync(configDir)) return plan;
 
@@ -117,35 +225,50 @@ export function planArchive(configDir: string, now: Date): ArchivePlan {
   const entries = readdirSync(configDir, { withFileTypes: true }).sort((a, b) =>
     a.name.localeCompare(b.name),
   );
+  const collected: PlanItem[] = [];
   for (const entry of entries) {
     if (entry.name.startsWith(".")) continue;
     if (safelist.has(entry.name)) continue;
     const abs = join(configDir, entry.name);
+    const cls = classify(entry.name);
     // Dirent.isDirectory() follows symlinks on macOS/Linux — so a link
     // pointing at an external tree would get sized via sizeOf() (bogus
     // byte count, and potentially a slow walk through /mnt/... or similar).
     // Classify the link itself as a zero-byte "file"; renameSync moves the
     // link, not the target, which is the behavior we want.
     if (entry.isSymbolicLink()) {
-      plan.items.push({
+      const item: PlanItem = {
         name: entry.name,
         absPath: abs,
         kind: "file",
         bytes: 0,
-        annotation: annotationFor(entry.name),
-      });
+        risk: cls.risk,
+        archive: cls.archive,
+      };
+      if (cls.annotation !== undefined) item.annotation = cls.annotation;
+      collected.push(item);
       continue;
     }
-    const bytes = sizeOf(abs);
-    plan.items.push({
+    const bytes = cls.archive ? sizeOf(abs) : 0;
+    const item: PlanItem = {
       name: entry.name,
       absPath: abs,
       kind: entry.isDirectory() ? "dir" : "file",
       bytes,
-      annotation: annotationFor(entry.name),
-    });
-    plan.totalBytes += bytes;
+      risk: cls.risk,
+      archive: cls.archive,
+    };
+    if (cls.annotation !== undefined) item.annotation = cls.annotation;
+    collected.push(item);
+    if (cls.archive) plan.totalBytes += bytes;
   }
+  // Sort: archivable first (alpha), then skipped (alpha). Stable across runs.
+  collected.sort((a, b) => {
+    if (a.archive !== b.archive) return a.archive ? -1 : 1;
+    return a.name.localeCompare(b.name);
+  });
+  plan.items = collected;
+  plan.hasLiveDb = collected.some((i) => i.archive && i.risk === "live-db");
   return plan;
 }
 
@@ -161,15 +284,35 @@ function formatBytes(bytes: number): string {
   return `${v.toFixed(1)} ${units[i]}`;
 }
 
+function riskTag(item: PlanItem): string {
+  if (!item.archive) return "[unknown — skipping]";
+  if (item.risk === "live-db") return "[live-db]";
+  return "[safe]";
+}
+
 function formatPlan(plan: ArchivePlan): string[] {
   const lines: string[] = [];
+  const archivable = plan.items.filter((i) => i.archive);
+  const skipped = plan.items.filter((i) => !i.archive);
   lines.push(
-    `Will archive: ${plan.items.length} item${plan.items.length === 1 ? "" : "s"} (${formatBytes(plan.totalBytes)}) → ${plan.archiveDirName}/`,
+    `Will archive: ${archivable.length} item${archivable.length === 1 ? "" : "s"} (${formatBytes(plan.totalBytes)}) → ${plan.archiveDirName}/`,
   );
-  for (const item of plan.items) {
+  for (const item of archivable) {
     const kindMark = item.kind === "dir" ? "/" : "";
     const note = item.annotation ? `  — ${item.annotation}` : "";
-    lines.push(`  ${item.name}${kindMark}  (${formatBytes(item.bytes)})${note}`);
+    lines.push(`  ${riskTag(item)} ${item.name}${kindMark}  (${formatBytes(item.bytes)})${note}`);
+  }
+  if (skipped.length > 0) {
+    lines.push("");
+    lines.push(
+      `Leaving alone: ${skipped.length} unknown entr${skipped.length === 1 ? "y" : "ies"} at the root.`,
+    );
+    lines.push("  (I don't recognize these — they may be from a module hub doesn't know about,");
+    lines.push("   or from your own setup. If they're safe to remove, you can do it manually.)");
+    for (const item of skipped) {
+      const kindMark = item.kind === "dir" ? "/" : "";
+      lines.push(`  ${riskTag(item)} ${item.name}${kindMark}`);
+    }
   }
   return lines;
 }
@@ -192,24 +335,91 @@ export async function defaultPrompt(question: string): Promise<string> {
   return answer;
 }
 
+/**
+ * Probe whether any managed service (or the hub) is currently running.
+ * Returns the list of short names that are live; an empty list means the
+ * sweep is safe to proceed.
+ *
+ * Reads services.json leniently so a malformed entry doesn't block the
+ * pre-flight (better to surface "running: vault" + a corrupt-entry warning
+ * elsewhere than to refuse migration on an unrelated parsing problem).
+ */
+export function listRunningServices(
+  configDir: string,
+  manifestPath: string,
+  alive: AliveFn,
+): string[] {
+  const running: string[] = [];
+  const hubState = processState(HUB_SVC, configDir, alive);
+  if (hubState.status === "running") running.push(HUB_SVC);
+  let manifest: ReturnType<typeof readManifestLenient>;
+  try {
+    manifest = readManifestLenient(manifestPath);
+  } catch {
+    return running;
+  }
+  for (const entry of manifest.services) {
+    const short = shortNameForManifest(entry.name) ?? entry.name;
+    if (running.includes(short)) continue;
+    const state = processState(short, configDir, alive);
+    if (state.status === "running") running.push(short);
+  }
+  return running;
+}
+
 export interface MigrateOpts {
   configDir?: string;
+  manifestPath?: string;
   now?: () => Date;
   log?: (line: string) => void;
   prompt?: (question: string) => Promise<string>;
   dryRun?: boolean;
   yes?: boolean;
+  /** `--list` — synonym for `--dry-run` with a more discoverable flag name. */
+  list?: boolean;
+  /** Test seam: process-liveness check used by `listRunningServices`. */
+  alive?: AliveFn;
+  /**
+   * Test seam: override the TTY check. Production reads
+   * `process.stdin.isTTY`; tests pass `true`/`false` to drive the
+   * non-interactive guard without manipulating real fds.
+   */
+  isTty?: boolean;
 }
 
 export async function migrate(opts: MigrateOpts = {}): Promise<number> {
   const configDir = opts.configDir ?? CONFIG_DIR;
+  const manifestPath = opts.manifestPath ?? SERVICES_MANIFEST_PATH;
   const now = (opts.now ?? (() => new Date()))();
   const log = opts.log ?? ((line) => console.log(line));
   const prompt = opts.prompt ?? defaultPrompt;
-  const dryRun = opts.dryRun ?? false;
+  const dryRun = (opts.dryRun ?? false) || (opts.list ?? false);
   const yes = opts.yes ?? false;
+  const alive = opts.alive ?? defaultAlive;
+  const isTty = opts.isTty ?? Boolean(process.stdin.isTTY);
+
+  // Refuse-while-running: archiving a path a live daemon owns can corrupt
+  // its state. Print the runners and bail before we read the directory.
+  // `--list` and `--dry-run` are read-only and skip this guard; the
+  // operator may explicitly want to see what would move while things are
+  // up.
+  if (!dryRun) {
+    const running = listRunningServices(configDir, manifestPath, alive);
+    if (running.length > 0) {
+      log("parachute migrate: services are currently running — refusing to sweep:");
+      for (const short of running) log(`  - ${short}`);
+      log("");
+      log("Stop them first, then re-run:");
+      log("  parachute stop");
+      log("");
+      log("Or preview the plan without changing anything:");
+      log("  parachute migrate --list");
+      return 1;
+    }
+  }
 
   const plan = planArchive(configDir, now);
+  const archivable = plan.items.filter((i) => i.archive);
   if (plan.items.length === 0) {
     log(`Nothing to archive. ${configDir} is already clean.`);
     return 0;
@@ -217,26 +427,63 @@ export async function migrate(opts: MigrateOpts = {}): Promise<number> {
 
   for (const line of formatPlan(plan)) log(line);
 
+  if (archivable.length === 0) {
+    // Only unknowns at the root; nothing to do.
+    log("");
+    log("Nothing recognized to archive.");
+    return 0;
+  }
+
   if (dryRun) {
-    log("(dry-run — no changes made)");
+    log("");
+    log(opts.list ? "(--list — no changes made)" : "(dry-run — no changes made)");
     return 0;
   }
 
+  // Non-TTY without `--yes` is a hard refuse. A pipe from CI or a launchd
+  // wrapper that lost its terminal shouldn't be able to silently archive
+  // user state — prefer an actionable error.
+  if (!isTty && !yes) {
+    log("");
+    log("parachute migrate: refusing to sweep without a TTY.");
+    log("Run interactively, or pass `--yes` if you're certain. To preview:");
+    log("  parachute migrate --list");
+    return 1;
+  }
+
   if (!yes) {
     const answer = (await prompt("Proceed? [y/N] ")).trim().toLowerCase();
     if (answer !== "y" && answer !== "yes") {
       log("Aborted.");
       return 1;
     }
+    // Extra confirmation when a SQLite-shape file is in the plan. The
+    // wal/shm companions are only consistent with their .db when the
+    // owning process is stopped (we already refused-while-running above,
+    // so they are), but operators sometimes have ad-hoc backup tooling
+    // that watches these — extra y/N is a cheap insurance against
+    // surprise.
+    if (plan.hasLiveDb) {
+      log("");
+      log("⚠ The plan includes SQLite-shape files (`*.db`, `*.db-wal`, `*.db-shm`).");
+      log("  These three are only consistent as a set — the archive moves them together,");
+      log("  but if anything outside Parachute is reading them (backup tooling, etc.),");
+      log("  that consumer will see a missing file after the sweep.");
+      const dbAnswer = (await prompt("Archive the live-db files too? [y/N] ")).trim().toLowerCase();
+      if (dbAnswer !== "y" && dbAnswer !== "yes") {
+        log("Aborted.");
+        return 1;
+      }
+    }
   }
 
   mkdirSync(plan.archiveDir, { recursive: true });
-  for (const item of plan.items) {
+  for (const item of archivable) {
     const dest = resolveDest(plan.archiveDir, item.name, now);
     renameSync(item.absPath, dest);
   }
   log(
-    `✓ Archived ${plan.items.length} item${plan.items.length === 1 ? "" : "s"} to ${plan.archiveDirName}/`,
+    `✓ Archived ${archivable.length} item${archivable.length === 1 ? "" : "s"} to ${plan.archiveDirName}/`,
   );
   return 0;
 }
@@ -245,9 +492,14 @@ export async function migrate(opts: MigrateOpts = {}): Promise<number> {
  * One-line notice for contexts where migrate is *not* what the user
  * asked for (e.g., after `parachute install`). Returns undefined when
  * there's nothing archivable so callers can branch on truthy/falsy.
+ *
+ * Counts only `archive: true` items — unknowns at the root don't trip
+ * the notice (they're not actually candidates for sweeping; the user
+ * sees them only when they explicitly run `parachute migrate`).
  */
 export function migrateNotice(configDir: string, now: Date): string | undefined {
   const plan = planArchive(configDir, now);
-  if (plan.items.length === 0) return undefined;
-  return `parachute migrate: ${plan.items.length} unrecognized entr${plan.items.length === 1 ? "y" : "ies"} at ecosystem root — run 'parachute migrate' to archive.`;
+  const archivable = plan.items.filter((i) => i.archive);
+  if (archivable.length === 0) return undefined;
+  return `parachute migrate: ${archivable.length} archivable entr${archivable.length === 1 ? "y" : "ies"} at ecosystem root — run 'parachute migrate' to archive.`;
 }

package/src/commands/status.ts

@@ -146,6 +146,14 @@ interface StatusRow {
    * stale-after-rebuild row without comparing columns by eye.
    */
   staleNote?: string;
+  /**
+   * Persisted last-start failure (`lastStartError`, written by the lifecycle
+   * start preflight when a startCmd binary is missing). Surfaced on a
+   * continuation line so a *later* `parachute status` explains why the row
+   * isn't active — "failed to start: <binary> not installed" — rather than
+   * just showing it inactive. Cleared on the next successful start.
+   */
+  startErrorNote?: string;
 }
 
 /**
@@ -264,6 +272,17 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
         ? `STALE: services.json cached ${entry.version}; live package.json ${source.livePackageVersion}`
         : undefined;
 
+      // Persisted last-start failure (lifecycle preflight wrote a missing-
+      // dependency wire). Surface a one-line summary; the full install recipe
+      // lives in services.json + the admin SPA card. Keeps `parachute status`
+      // scannable while still telling the operator "this is why it's down."
+      const startErrorNote =
+        entry.lastStartError !== undefined
+          ? entry.lastStartError.binary !== undefined
+            ? `failed to start: ${entry.lastStartError.binary} not installed — run \`parachute status\` detail or see /admin/modules for install steps`
+            : `failed to start: ${entry.lastStartError.error_description.split("\n")[0]}`
+          : undefined;
+
       // Only skip probe when we know the process is dead (PID file was
       // present but kill(pid, 0) failed). "unknown" status (no PID file)
       // still probes — externally-managed services should report health.
@@ -287,6 +306,7 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
           skipped: true,
           driftWarning,
           staleNote,
+          startErrorNote,
         };
       }
 
@@ -324,6 +344,7 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
         skipped: false,
         driftWarning,
         staleNote,
+        startErrorNote,
       };
     }),
   );
@@ -378,6 +399,7 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
     }
     if (row.driftWarning) print(`  ! ${row.driftWarning}`);
     if (row.staleNote) print(`  ! ${row.staleNote}`);
+    if (row.startErrorNote) print(`  ! ${row.startErrorNote}`);
   }
 
   /**

package/src/commands/upgrade.ts

@@ -72,25 +72,69 @@ export interface UpgradeRunner {
   ): Promise<{ code: number; stdout: string }>;
 }
 
+/**
+ * Exit code we synthesize when a binary can't be spawned at all. 127 is the
+ * POSIX shell convention for "command not found" — it lets every git call
+ * degrade to a normal non-zero result instead of crashing the whole command.
+ */
+const SPAWN_NOT_FOUND_CODE = 127;
+
+/**
+ * True when an error thrown by `Bun.spawn` means "the executable doesn't
+ * exist on this host" (ENOENT). On a minimal server with no `git` installed —
+ * a legitimate, common shape for a published-npm install on the canonical
+ * install path — `Bun.spawn(["git", ...])` throws *synchronously* with this
+ * shape. We catch it so `parachute upgrade` degrades to the npm path rather
+ * than dying with an uncaught `Executable not found in $PATH: "git"`.
+ */
+function isSpawnNotFound(err: unknown): boolean {
+  if (typeof err !== "object" || err === null) return false;
+  const code = (err as { code?: unknown }).code;
+  const message = (err as { message?: unknown }).message;
+  return (
+    code === "ENOENT" ||
+    (typeof message === "string" && message.includes("Executable not found in $PATH"))
+  );
+}
+
 export const defaultRunner: UpgradeRunner = {
   async run(cmd, opts) {
     // Inherit env so `bun add -g` etc. see TMPDIR, BUN_INSTALL, PATH, HOME.
     // Bun.spawn defaults to empty env — see api-modules-ops.ts:defaultRun.
-    const proc = Bun.spawn([...cmd], {
-      cwd: opts?.cwd,
-      stdio: ["inherit", "inherit", "inherit"],
-      env: process.env,
-    });
+    let proc: Bun.Subprocess;
+    try {
+      proc = Bun.spawn([...cmd], {
+        cwd: opts?.cwd,
+        stdio: ["inherit", "inherit", "inherit"],
+        env: process.env,
+      });
+    } catch (err) {
+      // Binary not on this host (e.g. no `git` on a minimal server). Degrade
+      // to a non-zero exit rather than letting the throw crash the command.
+      if (isSpawnNotFound(err)) return SPAWN_NOT_FOUND_CODE;
+      throw err;
+    }
     return await proc.exited;
   },
   async capture(cmd, opts) {
     // Inherit env — same rationale as `run` above.
-    const proc = Bun.spawn([...cmd], {
-      cwd: opts?.cwd,
-      stdout: "pipe",
-      stderr: "pipe",
-      env: process.env,
-    });
+    let proc: Bun.Subprocess<"ignore", "pipe", "pipe">;
+    try {
+      proc = Bun.spawn([...cmd], {
+        cwd: opts?.cwd,
+        stdout: "pipe",
+        stderr: "pipe",
+        env: process.env,
+      });
+    } catch (err) {
+      // See `run` above: ENOENT (binary-not-found) becomes a captured
+      // non-zero result so every git call degrades to "command failed".
+      if (isSpawnNotFound(err)) {
+        const bin = cmd[0] ?? "command";
+        return { code: SPAWN_NOT_FOUND_CODE, stdout: `${bin}: not found on this host\n` };
+      }
+      throw err;
+    }
     const [stdout, stderr] = await Promise.all([
       new Response(proc.stdout).text(),
       new Response(proc.stderr).text(),