@openparachute/hub 0.7.0 → 0.7.2-rc.1

package/src/commands/lifecycle.ts

@@ -1,4 +1,4 @@
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { rethrowIfMissing } from "@openparachute/depcheck";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
@@ -609,6 +609,74 @@ export interface LogsOpts {
    * Defaults to the group-aware `defaultAlive` (hub#88).
    */
   alive?: AliveFn;
+  /**
+   * Filtered-follow source seam (hub#652) — the byte stream of lines appended
+   * to the hub log from attach onward. The production default spawns
+   * `tail -n 0 -f <hub.log>` with piped stdout so the `[<svc>] ` filter runs
+   * in-process; tests inject a deterministic stream.
+   */
+  followStream?: (path: string) => ReadableStream<Uint8Array>;
+}
+
+/** Default `followStream`: tail the file from its end, stdout piped to us. */
+function defaultFollowStream(path: string): ReadableStream<Uint8Array> {
+  try {
+    // Inherit env so `tail` sees PATH, etc. Bun.spawn defaults to empty
+    // env — see api-modules-ops.ts:defaultRun.
+    const proc = Bun.spawn(["tail", "-n", "0", "-f", path], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "inherit",
+      env: process.env,
+    });
+    return proc.stdout;
+  } catch (err) {
+    // A missing `tail` (minimal container without coreutils) surfaces the
+    // friendly install UX instead of a raw spawn throw (cli.ts top-level
+    // catch renders the MissingDependencyError).
+    rethrowIfMissing(err, "tail");
+    throw err;
+  }
+}
+
+/**
+ * Pump a byte stream line-by-line, emitting only lines that carry `prefix`
+ * (stripped). Line-buffered the same way the supervisor's `pumpLines` is, so
+ * chunk boundaries inside a line don't drop or split matches.
+ */
+async function pumpFilteredLines(
+  stream: ReadableStream<Uint8Array>,
+  prefix: string,
+  output: (line: string) => void,
+): Promise<void> {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  const emit = (line: string): void => {
+    if (line.startsWith(prefix)) output(line.slice(prefix.length));
+  };
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      let nl = buf.indexOf("\n");
+      while (nl !== -1) {
+        emit(buf.slice(0, nl));
+        buf = buf.slice(nl + 1);
+        nl = buf.indexOf("\n");
+      }
+    }
+    if (buf.length > 0) emit(buf);
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+/** Split a log file's content into lines, dropping the trailing newline. */
+function splitLogLines(content: string): string[] {
+  const trimmed = content.replace(/\n$/, "");
+  return trimmed === "" ? [] : trimmed.split("\n");
 }
 
 export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
@@ -620,11 +688,12 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
   const alive = opts.alive ?? defaultAlive;
 
   // logs only needs a valid short name to find the log file. First-party
-  // wins via the spec lookup; third-party rows match by `entry.name`; the
-  // internal hub is a known short outside of services.json. installDir is
-  // irrelevant here — the log file is keyed by short name and exists once
-  // the service has run, regardless of how it was registered. We just need
-  // to confirm the name maps to something the CLI manages.
+  // wins via the spec lookup; third-party rows match by `entry.name` (the
+  // same token the supervisor uses as its log prefix); the internal hub is
+  // a known short outside of services.json. installDir is irrelevant here —
+  // the log file is keyed by short name and exists once the service has
+  // run, regardless of how it was registered. We just need to confirm the
+  // name maps to something the CLI manages.
   const isFirstParty = getSpec(svc) !== undefined;
   if (!isFirstParty && svc !== HUB_SVC) {
     const entry = readManifest(manifestPath).services.find((s) => s.name === svc);
@@ -634,19 +703,111 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
     }
   }
 
-  const path = logPathFor(svc, configDir);
-  if (!existsSync(path)) {
-    // Distinguish "daemon never started" from "daemon is running but the
-    // log file is missing" (hub#335). The latter shape surfaces when a
-    // module self-registers + spawns its own logger without going through
-    // `parachute start <svc>` (no hub-managed log file), or when an
-    // operator deletes the log mid-run. Previously both shapes printed the
-    // same `parachute start ${svc}` hint, leading operators to think their
-    // running daemon hadn't started.
+  // Per-file plain reader (the pre-#652 behavior): tail/print one log file.
+  const readPlain = async (path: string): Promise<number> => {
+    if (follow) {
+      const spawner = opts.tailSpawner ?? {
+        spawn(cmd) {
+          // Inherit env so `tail` sees PATH, etc. Bun.spawn defaults to empty
+          // env — see api-modules-ops.ts:defaultRun.
+          try {
+            const proc = Bun.spawn([...cmd], {
+              stdio: ["ignore", "inherit", "inherit"],
+              env: process.env,
+            });
+            return proc.pid;
+          } catch (err) {
+            // A missing `tail` (minimal container without coreutils) surfaces
+            // the friendly install UX instead of a raw spawn throw. The CLI
+            // top-level catch in cli.ts renders the MissingDependencyError.
+            rethrowIfMissing(err, "tail");
+            throw err;
+          }
+        },
+      };
+      spawner.spawn(["tail", "-n", String(lines), "-f", path], path);
+      // tail runs until user Ctrl-C; block this process until it exits.
+      // When called from the real CLI, process.exit wraps us; in tests a
+      // stub spawner returns immediately and we fall through.
+      return 0;
+    }
+    // Non-follow path: read last N lines synchronously for a clean one-shot.
+    const tail = splitLogLines(await Bun.file(path).text()).slice(-lines);
+    for (const line of tail) log(line);
+    return 0;
+  };
+
+  const legacyPath = logPathFor(svc, configDir);
+  const hubLogPath = logPathFor(HUB_SVC, configDir);
+  const legacyExists = svc !== HUB_SVC && existsSync(legacyPath);
+  const hubLogExists = existsSync(hubLogPath);
+
+  // Source selection (hub#652): under hub-as-supervisor (Phase 5b) a module's
+  // stdout/stderr is multiplexed into the HUB log with a `[<svc>] ` line
+  // prefix (supervisor.ts pipeOutput) — the per-service file stops advancing
+  // at the cutover. Prefer whichever file is fresher: a pre-supervised
+  // install is still actively writing the per-service file (it wins); on a
+  // supervised box the hub log is the live stream and the per-service file
+  // is a stale remnant (it loses). `logs hub` always reads the hub log
+  // unfiltered — the interleaved prefixed stream IS the hub's own log.
+  const useHubStream =
+    svc !== HUB_SVC &&
+    hubLogExists &&
+    (!legacyExists || statSync(hubLogPath).mtimeMs >= statSync(legacyPath).mtimeMs);
+
+  if (!useHubStream) {
+    if (!existsSync(legacyPath)) {
+      // Distinguish "daemon never started" from "daemon is running but the
+      // log file is missing" (hub#335). The latter shape surfaces when a
+      // module self-registers + spawns its own logger without going through
+      // the hub (no hub-managed log file), or when an operator deletes the
+      // log mid-run. Previously both shapes printed the same
+      // `parachute start ${svc}` hint, leading operators to think their
+      // running daemon hadn't started.
+      const state = processState(svc, configDir, alive);
+      if (state.status === "running") {
+        const whereabouts =
+          svc === HUB_SVC
+            ? `no log file at ${legacyPath}`
+            : `no log file at ${legacyPath} and no hub log at ${hubLogPath}`;
+        log(
+          `${svc} is running (pid ${state.pid}) but ${whereabouts}. The daemon may be writing logs elsewhere — check its stdout/stderr or its own log destination.`,
+        );
+        return 0;
+      }
+      log(`no logs yet for ${svc}. \`parachute start ${svc}\` to begin.`);
+      return 0;
+    }
+    return readPlain(legacyPath);
+  }
+
+  // Supervised path (hub#652): the service's lines in the hub log, prefix
+  // stripped. Stripped rather than kept: every line would otherwise repeat
+  // the name the operator just typed, while the module's own output shape
+  // (e.g. surface's `[app-dcr]` sub-prefixes) stays intact — the same shape
+  // its per-service file had pre-cutover.
+  const prefix = `[${svc}] `;
+  const matched = splitLogLines(await Bun.file(hubLogPath).text())
+    .filter((l) => l.startsWith(prefix))
+    .map((l) => l.slice(prefix.length));
+
+  if (matched.length === 0 && !follow) {
+    if (legacyExists) {
+      // Transitional shape: nothing for this service in the hub log, but a
+      // (staler) per-service file exists — e.g. the module last ran detached,
+      // pre-cutover. Show it, with a note so a stale file isn't mistaken for
+      // the live stream (the exact hub#652 trap).
+      log(
+        `note: no ${svc} lines in the hub log (${hubLogPath}); showing the per-service log at ${legacyPath}.`,
+      );
+      return readPlain(legacyPath);
+    }
+    // Keep the hub#335 shapes coherent with the hub-stream source: a live
+    // pidfile here means a daemon the hub isn't logging for.
     const state = processState(svc, configDir, alive);
     if (state.status === "running") {
       log(
-        `${svc} is running (pid ${state.pid}) but no log file at ${path}. The daemon may be writing logs elsewhere — check its stdout/stderr or its own log destination.`,
+        `${svc} is running (pid ${state.pid}) but has no lines in the hub log (${hubLogPath}) and no log file at ${legacyPath}. The daemon may be writing logs elsewhere — check its stdout/stderr or its own log destination.`,
       );
       return 0;
     }
@@ -654,38 +815,17 @@ export async function logs(svc: string, opts: LogsOpts = {}): Promise<number> {
     return 0;
   }
 
+  for (const line of matched.slice(-lines)) log(line);
+
   if (follow) {
-    const spawner = opts.tailSpawner ?? {
-      spawn(cmd) {
-        // Inherit env so `tail` sees PATH, etc. Bun.spawn defaults to empty
-        // env — see api-modules-ops.ts:defaultRun.
-        try {
-          const proc = Bun.spawn([...cmd], {
-            stdio: ["ignore", "inherit", "inherit"],
-            env: process.env,
-          });
-          return proc.pid;
-        } catch (err) {
-          // A missing `tail` (minimal container without coreutils) surfaces
-          // the friendly install UX instead of a raw spawn throw. The CLI
-          // top-level catch in cli.ts renders the MissingDependencyError.
-          rethrowIfMissing(err, "tail");
-          throw err;
-        }
-      },
-    };
-    spawner.spawn(["tail", "-n", String(lines), "-f", path], path);
-    // tail runs until user Ctrl-C; block this process until it exits.
-    // When called from the real CLI, process.exit wraps us; in tests a
-    // stub spawner returns immediately and we fall through.
-    return 0;
+    // Print the filtered backlog above, then follow new hub-log lines through
+    // the same filter. Runs until the tail is killed (Ctrl-C takes down the
+    // whole foreground process group); in tests the injected stream closes.
+    if (matched.length === 0) {
+      log(`(no prior ${svc} lines — waiting for new output…)`);
+    }
+    const source = opts.followStream ?? defaultFollowStream;
+    await pumpFilteredLines(source(hubLogPath), prefix, log);
   }
-
-  // Non-follow path: read last N lines synchronously for a clean one-shot.
-  const content = await Bun.file(path).text();
-  const trimmed = content.replace(/\n$/, "");
-  const allLines = trimmed === "" ? [] : trimmed.split("\n");
-  const tail = allLines.slice(-lines);
-  for (const line of tail) log(line);
   return 0;
 }

package/src/commands/serve-boot.ts

@@ -78,12 +78,13 @@ export interface BuildSpawnRequestOpts {
  *
  * Why (channel#41): the hub is the port authority, and a first-party module
  * with a compiled-in canonical port (`canonicalPortForManifest` ≠ undefined —
- * vault / scribe / surface / channel / notes / runner) has exactly ONE correct
+ * vault / scribe / surface / agent / notes / runner) has exactly ONE correct
  * port: its canonical one. The injected `PORT`, the supervisor's readiness
  * probe, and the reverse-proxy target are ALL derived from the services.json
- * row's `port`. So once a transiently-wrong port lands in that row (the channel
- * row was observed live carrying `19415` instead of `1941`), it self-perpetuates:
- * the supervisor probes/proxies the wrong port forever and `/channel/*` routes
+ * row's `port`. So once a transiently-wrong port lands in that row (the agent
+ * row — then named channel — was observed live carrying `19415` instead of
+ * `1941`), it self-perpetuates:
+ * the supervisor probes/proxies the wrong port forever and `/agent/*` routes
  * to a dead port. The canonical port is authoritative, so we reconcile the row
  * before spawn rather than honoring the drift.
  *

package/src/commands/serve.ts

@@ -38,6 +38,7 @@ import { createDbHolder, defaultStatInode, startDbPathLivenessTimer } from "../h
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { hubFetch } from "../hub-server.ts";
 import { writeHubFile } from "../hub.ts";
+import { createWsBridgeHandlers } from "../ws-bridge.ts";
 import { enrichedPath } from "../spawn-path.ts";
 import { Supervisor } from "../supervisor.ts";
 import { createUser, userCount } from "../users.ts";
@@ -45,6 +46,35 @@ import { sanitizePublicOrigin } from "../vault-hub-origin-env.ts";
 import { WELL_KNOWN_DIR } from "../well-known.ts";
 import { bootSupervisedModules } from "./serve-boot.ts";
 
+/**
+ * Build the `Bun.serve` options for the hub listener. Extracted (pure) so the
+ * load-bearing wiring — crucially the `websocket` bridge handler — is unit-
+ * testable and can't silently drift from the other `Bun.serve` in
+ * `hub-server.ts`. That drift is exactly how the in-page-terminal WS upgrade
+ * started 500ing: the bridge was wired into hub-server.ts's serve but NOT this
+ * production `parachute serve` path, so `server.upgrade()` (in `hubFetch`'s
+ * `maybeUpgradeWebSocket`) threw "set the websocket object in Bun.serve({})".
+ */
+export function hubServeOptions(args: {
+  port: number;
+  hostname: string;
+  fetch: ReturnType<typeof hubFetch>;
+}) {
+  return {
+    port: args.port,
+    hostname: args.hostname,
+    // Hold idle keep-alive connections for Bun's maximum 255s so reverse-proxy
+    // edges (Render, Cloudflare, fly.io) don't race us reusing pooled
+    // connections (hub#399).
+    idleTimeout: 255,
+    fetch: args.fetch,
+    // The WebSocket upgrade bridge. `maybeUpgradeWebSocket` (in `hubFetch`) calls
+    // `server.upgrade()`, which THROWS unless the server declares this handler —
+    // so it MUST be present on every Bun.serve that runs `hubFetch`.
+    websocket: createWsBridgeHandlers(),
+  };
+}
+
 export interface ServeOpts {
   /** Override PORT (test-only). Real callers thread env via process.env. */
   port?: number;
@@ -456,26 +486,22 @@ export async function serve(opts: ServeOpts = {}): Promise<{
   // fail fast and cleanly, leaving the live hub's children untouched.
   let server: ReturnType<typeof Bun.serve>;
   try {
-    server = Bun.serve({
-      port,
-      hostname,
-      // Hold idle keep-alive connections for Bun's maximum 255s so reverse-
-      // proxy edges (Render, Cloudflare, fly.io) don't race us when reusing
-      // pooled connections. See `src/hub-server.ts` for the full rationale —
-      // this is the active code path for `bun src/cli.ts serve` (the Docker
-      // CMD), so the fix has to land here too. Closes hub#399.
-      idleTimeout: 255,
-      fetch: hubFetch(WELL_KNOWN_DIR, {
-        getDb: () => dbHolder.get(),
-        onDbError: (err) => dbHolder.healOrExit(err),
-        // #610: /health's db check probes the path so monitoring + the #591
-        // adoption probe see a wipe instead of the ghost-fd lie.
-        probeDbPath: () => dbHolder.probePath(),
-        issuer,
-        loopbackPort: port,
-        supervisor,
+    server = Bun.serve(
+      hubServeOptions({
+        port,
+        hostname,
+        fetch: hubFetch(WELL_KNOWN_DIR, {
+          getDb: () => dbHolder.get(),
+          onDbError: (err) => dbHolder.healOrExit(err),
+          // #610: /health's db check probes the path so monitoring + the #591
+          // adoption probe see a wipe instead of the ghost-fd lie.
+          probeDbPath: () => dbHolder.probePath(),
+          issuer,
+          loopbackPort: port,
+          supervisor,
+        }),
       }),
-    });
+    );
   } catch (err) {
     const conflict = hubPortConflictMessage(err, port);
     if (conflict) throw new Error(conflict);

package/src/commands/setup.ts

@@ -109,13 +109,13 @@ function defaultAvailability(): InteractiveAvailability {
 
 /**
  * Survey the eligible services. We include the four first-party shortnames
- * (vault / notes / scribe / channel + runner) but flag channel as exploratory
+ * (vault / notes / scribe / agent + runner) but flag agent as exploratory
  * in the blurb so operators don't grab it by reflex. `installed` is true when
  * the service has a row in services.json.
  *
  * The full ServiceSpec is only available pre-install for FIRST_PARTY_FALLBACKS
  * shorts (notes — it carries a vendored manifest). KNOWN_MODULES shorts
- * (vault / scribe / runner / channel / surface) ship `.parachute/module.json`
+ * (vault / scribe / runner / agent / surface) ship `.parachute/module.json`
  * and self-register; pre-install we know manifestName + the urlForEntry quirk
  * from `KNOWN_MODULES[short].extras`, which is all the survey/summary needs.
  */
@@ -155,7 +155,8 @@ const BLURBS: Record<string, string> = {
   notes: "Notes PWA — web/mobile UI on top of vault (notes-daemon; superseded by `app`)",
   scribe: "audio transcription for dictation + recordings",
   runner: "vault-as-job-substrate — scheduled claude -p against vault job notes",
-  channel: "(exploratory — may retire) notification fan-out across modules",
+  agent:
+    "(exploratory) chat with your Claude Code sessions — a channel per session (renamed from channel)",
 };
 
 function blurbFor(choice: ServiceChoice): string {

package/src/commands/upgrade.ts

@@ -44,6 +44,26 @@
  * downgrades: if `npm view <pkg>@<channel> version` resolves to something
  * lower than what's installed, we abort with an actionable message
  * (override with `--allow-downgrade`).
+ *
+ * RC-channel best-of resolution (hub#659). Channel preservation (#332) made
+ * the rc channel sticky — `parachute upgrade` follows `@rc`. But the rc
+ * channel is a *canary*: when a train ships stable-direct without cutting an
+ * rc (the common case under the post-#332 governance where trains start at
+ * stable), `@rc` doesn't advance and the box strands BELOW `@latest` with no
+ * visible path forward (the live case: friends.parachute.computer pinned at
+ * 0.6.5-rc.8 while @latest moved to 0.7.1). The fix: on the rc channel we
+ * resolve the target to the HIGHEST version above installed across BOTH `@rc`
+ * AND `@latest`.
+ *   - mid-chain (a newer rc exists) → take the rc; the canary stays ahead
+ *     (UNCHANGED — this is the #332 behavior).
+ *   - end-of-chain / skipped-rc train (no newer rc, but @latest > installed)
+ *     → CONVERGE to @latest, with a loud log line. The operator stays ON the
+ *     rc channel (the install/config notion of channel is unchanged) — only
+ *     the resolved VERSION changes; they pick up the next rc when it ships.
+ *   - nothing newer anywhere → the existing up-to-date no-op.
+ * The `@latest` (stable) channel path is UNCHANGED — stable never reaches for
+ * `@rc`. `--channel rc|latest` explicit overrides and `--allow-downgrade`
+ * keep working.
  */
 
 import { existsSync, readFileSync, realpathSync } from "node:fs";
@@ -689,10 +709,102 @@ function pickChannel(installedVersion: string | null, r: Resolved): string {
   return "latest";
 }
 
+/**
+ * The dist-tag / version `upgradeNpm` will hand to `bun add -g`, after the
+ * rc-channel best-of resolution (hub#659). `installSpec` is what follows the
+ * `@` in `bun add -g <pkg>@<installSpec>` — usually a dist-tag (`rc` /
+ * `latest`), but a pinned concrete version when we converge an rc-channel box
+ * onto stable (so a moving `@latest` can't race the resolution). `channel` is
+ * the dist-tag we resolved against, used by the downgrade-guard messaging.
+ */
+interface ResolvedNpmTarget {
+  installSpec: string;
+  channel: string;
+}
+
+/**
+ * Resolve which version the rc channel should actually move to (hub#659).
+ *
+ * Channel preservation (#332) keeps an rc operator following `@rc`. But `@rc`
+ * is a canary that only advances when a train cuts an rc; a stable-direct
+ * train leaves it stranded below `@latest`. So on the rc channel we look at
+ * BOTH dist-tags and take the highest one that's actually ABOVE installed:
+ *   - a newer `@rc` exists → stay on rc (mid-chain canary; UNCHANGED).
+ *   - no newer rc but `@latest` > installed → converge to `@latest`, pinned to
+ *     the concrete resolved version, with a LOUD log. The operator stays ON
+ *     the rc channel; only this upgrade's resolved version changes.
+ *   - neither tag is above installed → fall through to the rc tag and let the
+ *     normal "already at <v>" no-op fire after `bun add -g`.
+ *
+ * Returns the original `{ installSpec: "rc" }` unchanged whenever we can't read
+ * the installed version or can't resolve a higher stable (fail-open: never
+ * block a legitimate `@rc` upgrade on a flaky probe).
+ */
+async function resolveRcBestOf(
+  target: ResolvedTarget,
+  beforeVersion: string | null,
+  r: Resolved,
+): Promise<ResolvedNpmTarget> {
+  const rcTarget: ResolvedNpmTarget = { installSpec: "rc", channel: "rc" };
+  if (!beforeVersion) return rcTarget;
+
+  const [rcVersion, latestVersion] = await Promise.all([
+    r.resolveChannelVersion(target.packageName, "rc"),
+    r.resolveChannelVersion(target.packageName, "latest"),
+  ]);
+
+  const rcAbove = rcVersion !== null && (compareVersions(rcVersion, beforeVersion) ?? -1) > 0;
+  if (rcAbove) {
+    // A newer rc exists — the canary stays ahead (the #332 mid-chain path).
+    return rcTarget;
+  }
+
+  const latestAbove =
+    latestVersion !== null && (compareVersions(latestVersion, beforeVersion) ?? -1) > 0;
+  // (`latestVersion !== null` already guaranteed by `latestAbove`; the second
+  // term only narrows it for TS.)
+  if (latestAbove && latestVersion) {
+    // End-of-chain / skipped-rc train: nothing newer on @rc, but stable moved
+    // ahead. Converge to @latest — pinned to the concrete version so a moving
+    // dist-tag can't race us — and say so LOUDLY (the hub#659 stranding fix).
+    r.log(
+      `${target.short}: the rc channel has nothing newer than ${beforeVersion}; ` +
+        `converging to stable ${latestVersion} — you'll pick up the next rc when it ships.`,
+    );
+    return { installSpec: latestVersion, channel: "latest" };
+  }
+
+  // Neither tag is above installed — stay on @rc and let the post-install
+  // "already at <v>" no-op fire (handled in upgradeNpm). When both probes
+  // resolved and both are ≤ installed, name that explicitly.
+  if (rcVersion !== null && latestVersion !== null) {
+    r.log(
+      `${target.short}: on the rc channel — @rc (${rcVersion}) and @latest (${latestVersion}) ` +
+        `are both at or below installed ${beforeVersion}.`,
+    );
+  }
+  return rcTarget;
+}
+
 async function upgradeNpm(target: ResolvedTarget, sourceDir: string, r: Resolved): Promise<number> {
   r.log(`${target.short}: npm-installed (${sourceDir})`);
   const beforeVersion = readPackageVersion(join(sourceDir, "package.json"));
-  const channel = pickChannel(beforeVersion, r);
+  const pickedChannel = pickChannel(beforeVersion, r);
+
+  // RC-channel best-of resolution (hub#659). On the rc channel, resolve to the
+  // highest version above installed across @rc AND @latest — so an end-of-chain
+  // box converges to stable instead of stranding below it. The stable channel
+  // and explicit programmatic `--tag` are UNCHANGED: only an *auto-detected or
+  // --channel-rc* resolution reaches for stable. An explicit `--channel rc`
+  // ALSO flows through best-of (a deliberate rc operator still gets converge);
+  // `r.tag` (programmatic pin) and `--channel latest` both leave it untouched.
+  let installSpec = pickedChannel;
+  let channel = pickedChannel;
+  if (pickedChannel === "rc" && !r.tag) {
+    const resolved = await resolveRcBestOf(target, beforeVersion, r);
+    installSpec = resolved.installSpec;
+    channel = resolved.channel;
+  }
 
   // Downgrade guard: refuse to silently move backward. Only applies when
   // we can read both sides — beforeVersion from disk, targetVersion via
@@ -700,6 +812,10 @@ async function upgradeNpm(target: ResolvedTarget, sourceDir: string, r: Resolved
   // behavior: just run `bun add -g`). This is the load-bearing fix for
   // hub#332 — Aaron got `0.5.13-rc.13` → `0.5.10` because the implicit
   // `@latest` resolved to a prior stable while he was on the rc chain.
+  //
+  // After hub#659's best-of resolution `channel` is already the tag we're
+  // actually shipping (rc on the canary path, latest on the converge path), so
+  // the guard checks the version we'll really install.
   if (beforeVersion && !r.allowDowngrade) {
     const targetVersion = await r.resolveChannelVersion(target.packageName, channel);
     if (targetVersion) {
@@ -725,7 +841,7 @@ async function upgradeNpm(target: ResolvedTarget, sourceDir: string, r: Resolved
     }
   }
 
-  const spec = `${target.packageName}@${channel}`;
+  const spec = `${target.packageName}@${installSpec}`;
   r.log(`${target.short}: bun add -g ${spec}`);
   const code = await r.runner.run(["bun", "add", "-g", spec]);
   if (code !== 0) {