@openparachute/hub 0.5.7 → 0.5.10-rc.10

package/src/commands/serve-boot.ts

@@ -0,0 +1,133 @@
+/**
+ * Container-mode module boot helpers, separated from `serve.ts` so
+ * tests can drive the supervisor wiring without standing up
+ * `Bun.serve`.
+ *
+ * `bootSupervisedModules` reads services.json, resolves each
+ * first-party module's `startCmd` from `SERVICE_SPECS`, and calls
+ * `Supervisor.start` for each. Third-party modules with `installDir`
+ * but no first-party fallback are also picked up via the same
+ * `getSpecFromInstallDir` path that `commands/lifecycle.ts` uses, so
+ * a hub-installed `@third-party/foo` boots the same way `vault` does.
+ *
+ * Idempotent: re-calling boot when modules are already running is a
+ * no-op (supervisor's own idempotent `start`). Missing-startCmd rows
+ * are logged + skipped, not fatal — the operator may have installed a
+ * module that doesn't expose a daemon (e.g. CLI-only).
+ */
+
+import { join } from "node:path";
+import { readEnvFileValues } from "../env-file.ts";
+import { HUB_ORIGIN_ENV } from "../hub-origin.ts";
+import { ModuleManifestError } from "../module-manifest.ts";
+import {
+  type ServiceSpec,
+  getSpec,
+  getSpecFromInstallDir,
+  shortNameForManifest,
+} from "../service-spec.ts";
+import { type ServiceEntry, readManifest } from "../services-manifest.ts";
+import type { Supervisor } from "../supervisor.ts";
+
+export interface BootOpts {
+  /** Path to services.json. */
+  readonly manifestPath: string;
+  /** Config dir ($PARACHUTE_HOME). Used to read per-module .env. */
+  readonly configDir: string;
+  /** Canonical OAuth issuer / hub origin. Forwarded to child env as PARACHUTE_HUB_ORIGIN. */
+  readonly hubOrigin?: string;
+  /** Logger seam. */
+  readonly log?: (line: string) => void;
+}
+
+export interface BootedModule {
+  readonly short: string;
+  readonly entryName: string;
+  readonly status: "started" | "skipped";
+  readonly reason?: string;
+}
+
+/**
+ * Walk services.json, spawn every manageable module via the
+ * supervisor. Returns a per-module decision log so the caller can
+ * surface a startup summary.
+ */
+export async function bootSupervisedModules(
+  supervisor: Supervisor,
+  opts: BootOpts,
+): Promise<BootedModule[]> {
+  const log = opts.log ?? (() => {});
+  const manifest = readManifest(opts.manifestPath);
+  const results: BootedModule[] = [];
+
+  for (const entry of manifest.services) {
+    const short = shortNameForManifest(entry.name) ?? entry.name;
+    const spec = await resolveSpec(short, entry);
+    if (!spec) {
+      // Row exists but no first-party fallback and no installDir-derived
+      // manifest. `parachute start` would print the same hint; the
+      // container path just logs + carries on.
+      log(`[supervisor] ${short}: no startCmd resolvable (services.json entry exists, no spec).`);
+      results.push({
+        short,
+        entryName: entry.name,
+        status: "skipped",
+        reason: "no-spec",
+      });
+      continue;
+    }
+
+    const cmd = spec.startCmd?.(entry);
+    if (!cmd || cmd.length === 0) {
+      log(`[supervisor] ${short}: spec resolved but no startCmd — skipping (CLI-only module).`);
+      results.push({
+        short,
+        entryName: entry.name,
+        status: "skipped",
+        reason: "no-start-cmd",
+      });
+      continue;
+    }
+
+    // Per-module .env layers under HUB_ORIGIN (hub-origin wins on
+    // collision — it's the canonical issuer source, and a stale .env
+    // shouldn't override the live `parachute serve` env).
+    const fileEnv = readEnvFileValues(join(opts.configDir, short, ".env"));
+    const env: Record<string, string> = { ...fileEnv };
+    if (opts.hubOrigin) env[HUB_ORIGIN_ENV] = opts.hubOrigin;
+
+    const req: {
+      short: string;
+      cmd: readonly string[];
+      cwd?: string;
+      env?: Record<string, string>;
+    } = {
+      short,
+      cmd,
+    };
+    // Third-party modules ship clean relative startCmds — cwd:
+    // installDir makes them resolve. First-party fallbacks use
+    // absolute / PATH binaries so cwd is a no-op there.
+    if (entry.installDir) req.cwd = entry.installDir;
+    if (Object.keys(env).length > 0) req.env = env;
+
+    await supervisor.start(req);
+    log(`[supervisor] ${short}: started (cmd=${cmd.join(" ")}).`);
+    results.push({ short, entryName: entry.name, status: "started" });
+  }
+
+  return results;
+}
+
+async function resolveSpec(short: string, entry: ServiceEntry): Promise<ServiceSpec | undefined> {
+  const firstParty = getSpec(short);
+  if (firstParty) return firstParty;
+  if (!entry.installDir) return undefined;
+  try {
+    const spec = await getSpecFromInstallDir(entry.installDir, entry.name);
+    return spec ?? undefined;
+  } catch (err) {
+    if (err instanceof ModuleManifestError) return undefined;
+    throw err;
+  }
+}

package/src/commands/serve.ts

@@ -0,0 +1,214 @@
+/**
+ * `parachute serve` — long-running hub HTTP server, foregrounded.
+ *
+ * The on-box CLI flow (`parachute expose`) spawns hub-server detached and
+ * tracks it via pidfile. Container hosts (Docker, Render) need the inverse
+ * shape: the hub process IS PID 1 of the container, lives in the
+ * foreground, and exits with the container.
+ *
+ * This subcommand wires that path:
+ *
+ *   - Reads `PORT` (default 1939) and `PARACHUTE_HUB_ORIGIN` (the canonical
+ *     public origin Render exposes via custom domain) from env.
+ *   - Auto-writes `hub.html` into `~/.parachute/well-known/` so `/` serves a
+ *     real discovery page on a fresh disk without the operator having to
+ *     run `parachute expose` first.
+ *   - Seeds an initial admin from `PARACHUTE_INITIAL_ADMIN_USERNAME` +
+ *     `PARACHUTE_INITIAL_ADMIN_PASSWORD` on first boot when no admin
+ *     exists, so the wizard isn't a hard precondition.
+ *   - Starts the hub-server fetch loop bound to `0.0.0.0` (container hosts
+ *     need to accept the platform's HTTP forwarder, not just localhost).
+ *
+ * Stays out of pidfile/log-rotation logic — those are for the detached
+ * `parachute start hub` flow. A container supervisor (Docker, systemd,
+ * Render) owns process lifecycle; this command only owns the fetch loop.
+ */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+// NOTE: CONFIG_DIR/WELL_KNOWN_DIR/SERVICES_MANIFEST_PATH are evaluated at
+// import time from process.env.PARACHUTE_HOME. The `env` parameter on
+// `serve()` cannot reroute them — set PARACHUTE_HOME before importing for
+// path isolation.
+import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import { hubDbPath, openHubDb } from "../hub-db.ts";
+import { hubFetch } from "../hub-server.ts";
+import { writeHubFile } from "../hub.ts";
+import { Supervisor } from "../supervisor.ts";
+import { createUser, userCount } from "../users.ts";
+import { WELL_KNOWN_DIR } from "../well-known.ts";
+import { bootSupervisedModules } from "./serve-boot.ts";
+
+export interface ServeOpts {
+  /** Override PORT (test-only). Real callers thread env via process.env. */
+  port?: number;
+  /** Override PARACHUTE_HUB_ORIGIN (test-only). */
+  issuer?: string;
+  /** Override the env source (test-only). */
+  env?: NodeJS.ProcessEnv;
+  /** Logger seam (test-only). */
+  log?: (line: string) => void;
+  /**
+   * Inject a pre-built Supervisor (test-only). Production constructs
+   * one internally with default options; tests pass in a Supervisor
+   * with stubbed spawn/sleep/now so the boot path doesn't try to
+   * `Bun.spawn` real children.
+   */
+  supervisor?: Supervisor;
+  /** Skip the services.json boot pass (test-only). */
+  skipModuleBoot?: boolean;
+}
+
+export interface ServeResult {
+  port: number;
+  issuer?: string;
+  /**
+   * "seeded" — initial admin created from env vars.
+   * "exists" — admin row already present, env vars ignored.
+   * "needs-setup" — no admin and no env-var seed; wizard mode (the
+   * setup-placeholder redirect in hub-server.ts takes over).
+   */
+  adminBootstrap: "seeded" | "exists" | "needs-setup";
+  /** The supervisor instance — exposed so callers (tests) can introspect / drive it. */
+  supervisor: Supervisor;
+}
+
+const DEFAULT_PORT = 1939;
+
+function parsePort(raw: string | undefined): number | undefined {
+  if (raw === undefined || raw === "") return undefined;
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isInteger(n) || n <= 0 || n > 65535) {
+    throw new Error(`PORT must be 1..65535, got "${raw}"`);
+  }
+  return n;
+}
+
+/**
+ * Seed the initial admin from env vars when no admin exists. Returns the
+ * bootstrap state so the caller can log it for operator visibility.
+ *
+ * Boot-time idempotent: if an admin already exists, we leave it alone —
+ * `PARACHUTE_INITIAL_ADMIN_*` is a first-boot seed, not a reset switch.
+ * That keeps a container restart with the env vars still set from
+ * clobbering an admin who has since rotated their password.
+ */
+export async function seedInitialAdminIfNeeded(
+  db: ReturnType<typeof openHubDb>,
+  env: NodeJS.ProcessEnv,
+  log: (line: string) => void = () => {},
+): Promise<"seeded" | "exists" | "needs-setup"> {
+  if (userCount(db) > 0) return "exists";
+  const username = env.PARACHUTE_INITIAL_ADMIN_USERNAME?.trim();
+  const password = env.PARACHUTE_INITIAL_ADMIN_PASSWORD;
+  if (!username || !password) return "needs-setup";
+  await createUser(db, username, password);
+  log(`parachute serve: seeded initial admin "${username}" from PARACHUTE_INITIAL_ADMIN_*`);
+  return "seeded";
+}
+
+/**
+ * Run the hub fetch loop in the foreground. Resolves when `Bun.serve` is
+ * bound; the returned `stop()` shuts the server down for tests.
+ *
+ * The CLI dispatcher calls this without awaiting completion — `Bun.serve`
+ * runs the listener and the runtime keeps the process alive until a
+ * signal. Tests pass `port: 0` so the kernel picks an ephemeral port.
+ */
+export async function serve(opts: ServeOpts = {}): Promise<{
+  result: ServeResult;
+  stop: () => Promise<void>;
+}> {
+  const env = opts.env ?? process.env;
+  const log = opts.log ?? ((line) => console.log(line));
+
+  const envPort = parsePort(env.PORT);
+  const port = opts.port ?? envPort ?? DEFAULT_PORT;
+  const issuer = (opts.issuer ?? env.PARACHUTE_HUB_ORIGIN)?.replace(/\/+$/, "") || undefined;
+  // Containers default to 0.0.0.0 so the platform's HTTP forwarder can
+  // reach us; the `--hostname` flag / PARACHUTE_BIND_HOST is the escape
+  // hatch for setups that want loopback-only inside a sidecar.
+  const hostname = env.PARACHUTE_BIND_HOST || "0.0.0.0";
+
+  // Ensure the well-known dir exists, and seed a static hub.html so `/`
+  // serves something coherent on a fresh disk (the dynamic path through
+  // `hubFetch` takes over once a DB row exists; the disk file is the
+  // signed-out fallback).
+  if (!existsSync(WELL_KNOWN_DIR)) mkdirSync(WELL_KNOWN_DIR, { recursive: true });
+  const hubHtmlPath = join(WELL_KNOWN_DIR, "hub.html");
+  if (!existsSync(hubHtmlPath)) writeHubFile(hubHtmlPath);
+
+  const dbPath = hubDbPath();
+  const db = openHubDb(dbPath);
+  const adminBootstrap = await seedInitialAdminIfNeeded(db, env, log);
+
+  if (adminBootstrap === "needs-setup") {
+    log(
+      "parachute serve: no admin account configured. Set PARACHUTE_INITIAL_ADMIN_USERNAME + PARACHUTE_INITIAL_ADMIN_PASSWORD, or visit /admin/setup once the hub is reachable.",
+    );
+  }
+
+  const supervisor = opts.supervisor ?? new Supervisor();
+
+  // Boot already-installed modules from services.json. In a container,
+  // this is the path that re-spawns vault / notes / scribe after a
+  // restart — the persistent disk preserved both the install (in
+  // `$BUN_INSTALL/install/global/node_modules`) and the row that says
+  // "this module is registered + active." Idempotent: the supervisor
+  // skips modules that are already running.
+  if (!opts.skipModuleBoot) {
+    try {
+      const booted = await bootSupervisedModules(supervisor, {
+        manifestPath: SERVICES_MANIFEST_PATH,
+        configDir: CONFIG_DIR,
+        ...(issuer !== undefined ? { hubOrigin: issuer } : {}),
+        log,
+      });
+      const startedCount = booted.filter((b) => b.status === "started").length;
+      if (startedCount > 0) {
+        log(`parachute serve: supervisor booted ${startedCount} module(s) from services.json.`);
+      }
+    } catch (err) {
+      // A malformed services.json or a single module-spec read failure
+      // shouldn't keep the hub HTTP server from coming up — the
+      // operator can still hit /admin/modules to remediate.
+      log(
+        `parachute serve: module boot failed (${err instanceof Error ? err.message : String(err)}). The hub HTTP server is still starting; visit /admin/modules to remediate.`,
+      );
+    }
+  }
+
+  const server = Bun.serve({
+    port,
+    hostname,
+    fetch: hubFetch(WELL_KNOWN_DIR, {
+      getDb: () => db,
+      issuer,
+      loopbackPort: port,
+      supervisor,
+    }),
+  });
+
+  log(
+    `parachute serve: listening on http://${hostname}:${port} (PARACHUTE_HOME=${CONFIG_DIR}, db=${dbPath}, issuer=${issuer ?? "<request-origin>"}, admin=${adminBootstrap})`,
+  );
+
+  return {
+    result: {
+      port,
+      ...(issuer !== undefined ? { issuer } : {}),
+      adminBootstrap,
+      supervisor,
+    },
+    stop: async () => {
+      // Stop supervised children first so they get a clean SIGTERM
+      // before the HTTP server (which they may depend on for hub-issued
+      // tokens) goes away.
+      for (const state of supervisor.list()) {
+        await supervisor.stop(state.short);
+      }
+      await server.stop();
+      db.close();
+    },
+  };
+}

package/src/commands/status.ts

@@ -1,5 +1,12 @@
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { HUB_SVC, readHubPort } from "../hub-control.ts";
+import {
+  type DetectInstallSourceDeps,
+  detectHubInstallSource,
+  detectInstallSource,
+  formatInstallSourceLabel,
+  isStale,
+} from "../install-source.ts";
 import { type AliveFn, defaultAlive, formatUptime, processState } from "../process-state.ts";
 import { canonicalPortForManifest, getSpec, shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifest } from "../services-manifest.ts";
@@ -14,6 +21,19 @@ export interface StatusOpts {
   configDir?: string;
   alive?: AliveFn;
   now?: () => Date;
+  /**
+   * Test seam for install-source detection. Production reads the filesystem
+   * + shells out to git; tests inject stubs so each case (npm / bun-linked /
+   * unknown / stale) is exercised deterministically without depending on
+   * the operator's actual bun globals.
+   */
+  installSourceDeps?: DetectInstallSourceDeps;
+  /**
+   * Directory containing the running hub source. Defaults to `import.meta.dir`
+   * (the directory of this file). Tests override so the hub row's install
+   * source classification doesn't depend on the test runner's location.
+   */
+  hubSrcDir?: string;
 }
 
 export interface ProbeResult {
@@ -71,6 +91,7 @@ interface StatusRow {
   uptimeLabel: string;
   healthLabel: string;
   latencyLabel: string;
+  sourceLabel: string;
   url: string | undefined;
   healthy: boolean;
   skipped: boolean;
@@ -82,6 +103,13 @@ interface StatusRow {
    * hard-erroring on a deliberate operator port change.
    */
   driftWarning?: string;
+  /**
+   * Version-drift indicator (hub#243). Set when a bun-linked service's
+   * `services.json.version` lags the live `package.json` version at its
+   * checkout. Surfaced as a continuation line so operators can spot a
+   * stale-after-rebuild row without comparing columns by eye.
+   */
+  staleNote?: string;
 }
 
 /**
@@ -98,7 +126,13 @@ function urlForEntry(entry: ServiceEntry, short: string | undefined): string | u
   return `http://127.0.0.1:${entry.port}${first}`;
 }
 
-function hubRow(configDir: string, alive: AliveFn, nowDate: Date): StatusRow | undefined {
+function hubRow(
+  configDir: string,
+  alive: AliveFn,
+  nowDate: Date,
+  hubSrcDir: string,
+  installSourceDeps: DetectInstallSourceDeps,
+): StatusRow | undefined {
   const proc = processState(HUB_SVC, configDir, alive);
   if (proc.status === "unknown") return undefined;
   const port = readHubPort(configDir);
@@ -107,15 +141,17 @@ function hubRow(configDir: string, alive: AliveFn, nowDate: Date): StatusRow | u
   const pidLabel = proc.status === "running" && proc.pid !== undefined ? String(proc.pid) : "-";
   const uptimeLabel =
     proc.status === "running" && proc.startedAt ? formatUptime(proc.startedAt, nowDate) : "-";
+  const source = detectHubInstallSource(hubSrcDir, installSourceDeps);
   return {
     service: "parachute-hub (internal)",
     port: portLabel,
-    version: "-",
+    version: source.livePackageVersion ?? "-",
     processLabel,
     pidLabel,
     uptimeLabel,
     healthLabel: "-",
     latencyLabel: "-",
+    sourceLabel: formatInstallSourceLabel(source),
     url: port !== undefined ? `http://127.0.0.1:${port}` : undefined,
     healthy: true,
     skipped: true,
@@ -130,6 +166,8 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
   const configDir = opts.configDir ?? CONFIG_DIR;
   const alive = opts.alive ?? defaultAlive;
   const now = opts.now ?? (() => new Date());
+  const installSourceDeps = opts.installSourceDeps ?? {};
+  const hubSrcDir = opts.hubSrcDir ?? import.meta.dir;
 
   const manifest = readManifest(manifestPath);
   if (manifest.services.length === 0) {
@@ -178,6 +216,17 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
           ? `canonical port is ${canonical}`
           : undefined;
 
+      // Install-source detection (hub#243). One filesystem walk + maybe one
+      // `git rev-parse` per row. Failures degrade silently to `unknown` —
+      // status output should never error out on a missing checkout dir.
+      const detectArgs: { entryName: string; installDir?: string } = { entryName: entry.name };
+      if (entry.installDir !== undefined) detectArgs.installDir = entry.installDir;
+      const source = detectInstallSource(detectArgs, installSourceDeps);
+      const sourceLabel = formatInstallSourceLabel(source);
+      const staleNote = isStale(entry.version, source)
+        ? `STALE: services.json cached ${entry.version}; live package.json ${source.livePackageVersion}`
+        : 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.
@@ -191,10 +240,12 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
           uptimeLabel,
           healthLabel: "-",
           latencyLabel: "-",
+          sourceLabel,
           url,
           healthy: false,
           skipped: true,
           driftWarning,
+          staleNote,
         };
       }
 
@@ -213,20 +264,32 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
         uptimeLabel,
         healthLabel,
         latencyLabel: `${p.latencyMs}ms`,
+        sourceLabel,
         url,
         healthy: p.healthy,
         skipped: false,
         driftWarning,
+        staleNote,
       };
     }),
   );
 
   // Hub is an internal service — not in services.json, but users notice
   // when it's dead. Only show it if we've seen it run.
-  const hub = hubRow(configDir, alive, nowDate);
+  const hub = hubRow(configDir, alive, nowDate, hubSrcDir, installSourceDeps);
   if (hub) rows.push(hub);
 
-  const header = ["SERVICE", "PORT", "VERSION", "PROCESS", "PID", "UPTIME", "HEALTH", "LATENCY"];
+  const header = [
+    "SERVICE",
+    "PORT",
+    "VERSION",
+    "PROCESS",
+    "PID",
+    "UPTIME",
+    "HEALTH",
+    "LATENCY",
+    "SOURCE",
+  ];
   const textRows = rows.map((r) => [
     r.service,
     r.port,
@@ -236,14 +299,17 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
     r.uptimeLabel,
     r.healthLabel,
     r.latencyLabel,
+    r.sourceLabel,
   ]);
   const widths = header.map((_, i) =>
     Math.max(header[i]?.length ?? 0, ...textRows.map((r) => r[i]?.length ?? 0)),
   );
   print(formatRow(header, widths));
-  // URL stays on a continuation line rather than a column. URLs are long
-  // (vault's MCP path runs ~40 chars), and a ninth column would push the
-  // table past 80 cols on every install. The "  → " prefix groups visually
+  // URL, drift, and stale notes stay on continuation lines rather than
+  // columns. URLs are long (vault's MCP path runs ~40 chars); SOURCE labels
+  // can be long for bun-linked rows. Spreading them across columns would
+  // push the table well past 80 cols on every install — continuation lines
+  // keep the table scannable. The "  → " / "  ! " prefixes group visually
   // with the row above without misleading the table widths.
   for (let i = 0; i < textRows.length; i++) {
     const cells = textRows[i];
@@ -251,10 +317,8 @@ export async function status(opts: StatusOpts = {}): Promise<number> {
     if (!cells || !row) continue;
     print(formatRow(cells, widths));
     if (row.url) print(`  → ${row.url}`);
-    // Drift warning rides as its own continuation line. Plain ASCII (no
-    // emoji / unicode glyphs) for terminal compatibility — the same
-    // surface that prints to scripts piping `parachute status`.
     if (row.driftWarning) print(`  ! ${row.driftWarning}`);
+    if (row.staleNote) print(`  ! ${row.staleNote}`);
   }
 
   /**

package/src/commands/upgrade.ts

@@ -38,6 +38,7 @@ import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
+import { HUB_PACKAGE, HUB_SVC } from "../hub-control.ts";
 import { ModuleManifestError } from "../module-manifest.ts";
 import {
   type ServiceSpec,
@@ -149,16 +150,38 @@ function resolve(opts: UpgradeOpts): Resolved {
   };
 }
 
+/**
+ * Synthetic services.json row for the hub. The hub isn't in services.json
+ * (it's an implementation detail of `parachute expose`, not a user-facing
+ * service), so callers passing `hub` as the upgrade target need a fabricated
+ * `ResolvedTarget`. Only `installDir` is read downstream — left undefined so
+ * `findGlobalInstall("@openparachute/hub")` is the sole locate path, which
+ * works the same for npm installs and `bun link` checkouts.
+ */
+function hubTarget(): ResolvedTarget {
+  const entry: ServiceEntry = {
+    name: HUB_PACKAGE,
+    port: 0,
+    paths: [],
+    health: "",
+    version: "",
+  };
+  return { short: HUB_SVC, entry, spec: undefined, packageName: HUB_PACKAGE };
+}
+
 async function resolveTargets(
   svc: string | undefined,
   manifestPath: string,
 ): Promise<{ targets: ResolvedTarget[] } | { error: string }> {
   const manifest = readManifest(manifestPath);
-  if (manifest.services.length === 0) {
-    return { error: "No services installed yet. Try: parachute install <service>" };
-  }
 
   if (svc !== undefined) {
+    if (svc === HUB_SVC) return { targets: [hubTarget()] };
+
+    if (manifest.services.length === 0) {
+      return { error: "No services installed yet. Try: parachute install <service>" };
+    }
+
     const firstPartySpec = getSpec(svc);
     if (firstPartySpec) {
       const entry = manifest.services.find((s) => s.name === firstPartySpec.manifestName);
@@ -183,10 +206,15 @@ async function resolveTargets(
         throw err;
       }
     }
-    return { error: `unknown service "${svc}". known: ${knownServices().join(", ")}` };
+    return {
+      error: `unknown service "${svc}". known: ${[HUB_SVC, ...knownServices()].join(", ")}`,
+    };
   }
 
-  const targets: ResolvedTarget[] = [];
+  // Sweep mode: hub first, then everything in services.json. Hub-first means a
+  // dispatcher upgrade can't be undermined mid-sweep by a service upgrade that
+  // restarts hub for reasons unrelated to its own code change.
+  const targets: ResolvedTarget[] = [hubTarget()];
   for (const entry of manifest.services) {
     const short = shortNameForManifest(entry.name);
     if (short) {
@@ -209,7 +237,6 @@ async function resolveTargets(
       }
     }
   }
-  if (targets.length === 0) return { error: "No upgradeable services in services.json." };
   return { targets };
 }