@openparachute/hub 0.7.4-rc.17 → 0.7.4-rc.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.4-rc.17",
+  "version": "0.7.4-rc.19",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/api-modules.test.ts

@@ -6,8 +6,10 @@ import {
   API_MODULES_CHANNEL_REQUIRED_SCOPE,
   API_MODULES_REQUIRED_SCOPE,
   _clearLatestVersionCacheForTests,
+  defaultReadInstalledVersion,
   handleApiModules,
   handleApiModulesChannel,
+  isUpgradeAvailable,
 } from "../api-modules.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { getSetting, setModuleInstallChannel } from "../hub-settings.ts";
@@ -491,6 +493,147 @@ describe("GET /api/modules", () => {
     expect(scribe?.installed_version).toBeNull();
   });
 
+  // ── hub#243: upgrade-offer must be semver-aware + installed-version must be live ──
+
+  type UpgradeWire = {
+    short: string;
+    installed_version: string | null;
+    latest_version: string | null;
+    upgrade_available: boolean;
+  };
+
+  async function modulesWith(opts: {
+    installedVersion: string;
+    latest: string | null;
+    readInstalledVersion?: (installDir: string) => string | null;
+  }): Promise<UpgradeWire[]> {
+    writeManifest(h.manifestPath, [
+      {
+        name: "parachute-vault",
+        port: 1940,
+        paths: ["/vault/default"],
+        health: "/vault/default/health",
+        version: opts.installedVersion,
+        installDir: "/install/dir/vault",
+      },
+    ]);
+    const bearer = await mintBearer(h, [API_MODULES_REQUIRED_SCOPE]);
+    const res = await handleApiModules(getReq({ authorization: `Bearer ${bearer}` }), {
+      db: h.db,
+      issuer: ISSUER,
+      manifestPath: h.manifestPath,
+      fetchLatestVersion: async () => opts.latest,
+      // Default: no live read (synthetic install dir has no package.json), so
+      // the services.json cache is used — matching the prior behavior.
+      readInstalledVersion: opts.readInstalledVersion ?? (() => null),
+    });
+    const body = (await res.json()) as { modules: UpgradeWire[] };
+    return body.modules;
+  }
+
+  test("does NOT offer an upgrade when the channel target is OLDER than installed (the live downgrade bug)", async () => {
+    // The exact live shape: rc operator installed 0.6.4-rc.15; channel resolved
+    // latest_version to the OLDER @latest 0.6.3. Strings differ, but it's a
+    // downgrade — upgrade_available MUST be false.
+    const mods = await modulesWith({ installedVersion: "0.6.4-rc.15", latest: "0.6.3" });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.installed_version).toBe("0.6.4-rc.15");
+    expect(vault?.latest_version).toBe("0.6.3");
+    expect(vault?.upgrade_available).toBe(false);
+  });
+
+  test("offers an upgrade for a real rc → newer-rc move", async () => {
+    const mods = await modulesWith({ installedVersion: "0.6.4-rc.15", latest: "0.6.4-rc.16" });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.upgrade_available).toBe(true);
+  });
+
+  test("offers an upgrade for rc → its own stable (stable > its rc per semver)", async () => {
+    const mods = await modulesWith({ installedVersion: "0.6.4-rc.15", latest: "0.6.4" });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.upgrade_available).toBe(true);
+  });
+
+  test("offers an upgrade for a plain stable → newer stable", async () => {
+    const mods = await modulesWith({ installedVersion: "0.4.5", latest: "0.5.0" });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.upgrade_available).toBe(true);
+  });
+
+  test("no upgrade when installed === latest", async () => {
+    const mods = await modulesWith({ installedVersion: "0.5.0", latest: "0.5.0" });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.upgrade_available).toBe(false);
+  });
+
+  test("no upgrade when the npm probe failed (latest_version null)", async () => {
+    const mods = await modulesWith({ installedVersion: "0.5.0", latest: null });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.latest_version).toBeNull();
+    expect(vault?.upgrade_available).toBe(false);
+  });
+
+  test("installed_version reflects the LIVE on-disk version, not a stale services.json cache (hub#243)", async () => {
+    // services.json cache lags the bun-linked checkout: cache says 0.5.4-rc.15
+    // (the live symptom) while package.json on disk is already 0.6.4-rc.15.
+    // The admin view must show what's actually installed.
+    const mods = await modulesWith({
+      installedVersion: "0.5.4-rc.15",
+      latest: "0.6.3",
+      readInstalledVersion: (dir) => (dir === "/install/dir/vault" ? "0.6.4-rc.15" : null),
+    });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.installed_version).toBe("0.6.4-rc.15");
+    // And with the corrected current, @latest 0.6.3 is still a downgrade → no offer.
+    expect(vault?.upgrade_available).toBe(false);
+  });
+
+  test("falls back to the services.json version when the live read returns null", async () => {
+    const mods = await modulesWith({
+      installedVersion: "0.6.4-rc.15",
+      latest: "0.6.4-rc.16",
+      readInstalledVersion: () => null,
+    });
+    const vault = mods.find((m) => m.short === "vault");
+    expect(vault?.installed_version).toBe("0.6.4-rc.15");
+    expect(vault?.upgrade_available).toBe(true);
+  });
+
+  test("isUpgradeAvailable: semver-aware, fail-closed on unparseable + nulls", () => {
+    // strictly-newer → true
+    expect(isUpgradeAvailable("0.4.5", "0.5.0")).toBe(true);
+    expect(isUpgradeAvailable("0.6.4-rc.15", "0.6.4-rc.16")).toBe(true);
+    expect(isUpgradeAvailable("0.6.4-rc.15", "0.6.4")).toBe(true); // stable > its rc
+    // same / older → false
+    expect(isUpgradeAvailable("0.5.0", "0.5.0")).toBe(false);
+    expect(isUpgradeAvailable("0.6.4-rc.15", "0.6.3")).toBe(false); // the live downgrade
+    expect(isUpgradeAvailable("0.6.4", "0.6.4-rc.15")).toBe(false); // stable → its rc
+    // nulls → false (not installed / probe failed)
+    expect(isUpgradeAvailable(null, "0.5.0")).toBe(false);
+    expect(isUpgradeAvailable("0.5.0", null)).toBe(false);
+    // unparseable → false (fail-closed: never offer a move we can't verify)
+    expect(isUpgradeAvailable("not-a-version", "0.5.0")).toBe(false);
+    expect(isUpgradeAvailable("0.5.0", "garbage")).toBe(false);
+  });
+
+  test("defaultReadInstalledVersion reads package.json version + tolerates missing/bad files", () => {
+    const tmp = mkdtempSync(join(tmpdir(), "phub-live-ver-"));
+    try {
+      writeFileSync(join(tmp, "package.json"), JSON.stringify({ version: "0.6.4-rc.15" }));
+      expect(defaultReadInstalledVersion(tmp)).toBe("0.6.4-rc.15");
+      // Missing dir / no package.json → null.
+      expect(defaultReadInstalledVersion(join(tmp, "does-not-exist"))).toBeNull();
+      // Malformed JSON → null (no throw).
+      writeFileSync(join(tmp, "package.json"), "{ not json");
+      expect(defaultReadInstalledVersion(tmp)).toBeNull();
+      // No version field → null.
+      writeFileSync(join(tmp, "package.json"), JSON.stringify({ name: "x" }));
+      expect(defaultReadInstalledVersion(tmp)).toBeNull();
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
   test("includes supervisor status + pid when a supervisor is injected", async () => {
     writeManifest(h.manifestPath, [
       {

package/src/__tests__/doctor.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { type CheckResult, type DoctorDeps, doctor } from "../commands/doctor.ts";
@@ -462,3 +462,294 @@ describe("doctor — version drift (cosmetic; never FAIL)", () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// Canonical-port-drift detection + `doctor --fix` repair (#267 doctor sub-item)
+// ---------------------------------------------------------------------------
+
+/** Write a services.json with the given rows (verbatim — for drift fixtures). */
+function writeManifestRows(manifestPath: string, services: unknown[]): void {
+  writeFileSync(manifestPath, JSON.stringify({ services }, null, 2));
+}
+
+/** Read services.json back as parsed rows for post-fix assertions. */
+function readRows(manifestPath: string): Record<string, unknown>[] {
+  const parsed = JSON.parse(readFileSync(manifestPath, "utf8")) as {
+    services: Record<string, unknown>[];
+  };
+  return parsed.services;
+}
+
+/** Run `doctor --fix`, capturing printed lines + exit code. */
+async function runFix(
+  h: Harness,
+  over: Partial<DoctorDeps> = {},
+  flags: { yes?: boolean } = {},
+): Promise<{ code: number; lines: string[] }> {
+  const lines: string[] = [];
+  const code = await doctor({
+    configDir: h.configDir,
+    manifestPath: h.manifestPath,
+    print: (l) => lines.push(l),
+    fix: true,
+    yes: flags.yes ?? false,
+    deps: healthyDeps(over),
+  });
+  return { code, lines };
+}
+
+describe("doctor — canonical-port-drift detection (read-only)", () => {
+  test("a non-canonical port + a duplicate-port pair → port-drift WARNs naming the services", async () => {
+    const h = makeHarness();
+    try {
+      // scribe drifted off 1943 onto 1944; agent also squats 1944 (a collision).
+      writeManifestRows(h.manifestPath, [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/h",
+          version: "1",
+        },
+        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
+        { name: "parachute-agent", port: 1944, paths: ["/agent"], health: "/h", version: "1" },
+      ]);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(h, healthyDeps());
+      const pd = byName(checks, "port-drift");
+      expect(pd?.status).toBe("warn");
+      // Names the drifted service AND the colliding pair.
+      expect(pd?.detail).toContain("scribe");
+      expect(pd?.detail).toContain("1944");
+      expect(pd?.detail).toContain("parachute-scribe + parachute-agent");
+      expect(pd?.fix).toBe("parachute doctor --fix");
+      // Drift is advisory — exit stays 0 (a WARN, not a FAIL). The duplicate
+      // rows also trip modules-alive (both can't bind 1944) but that's expected
+      // for this fixture; we only assert on port-drift here.
+      expect([0, 1]).toContain(code);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a clean file → port-drift PASSES with no drift", async () => {
+    const h = makeHarness();
+    try {
+      seedCurrentManifest(h.manifestPath);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(h, healthyDeps());
+      const pd = byName(checks, "port-drift");
+      expect(pd?.status).toBe("pass");
+      expect(pd?.detail).toContain("canonical");
+      expect(code).toBe(0);
+      expectNoUnexpectedNonPass(checks, []);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a third-party service with NO canonical port is not flagged", async () => {
+    const h = makeHarness();
+    try {
+      // An unknown module on a non-1939–1949 port — no canonical to drift from.
+      writeManifestRows(h.manifestPath, [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/h",
+          version: "1",
+        },
+        { name: "acme-thing", port: 5000, paths: ["/acme"], health: "/h", version: "1" },
+      ]);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(h, healthyDeps());
+      const pd = byName(checks, "port-drift");
+      expect(pd?.status).toBe("pass");
+      expect(code).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("a named multi-vault row sharing 1940 is NOT flagged (drift or duplicate)", async () => {
+    const h = makeHarness();
+    try {
+      // A legit multi-vault setup: the canonical vault row plus a second named
+      // vault instance, both on 1940 (the documented carve-out). Neither should
+      // be flagged as drifted (named vault rows have no canonical port) nor as a
+      // duplicate-port collision (all-vault-on-1940 is by design).
+      writeManifestRows(h.manifestPath, [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: ["/vault/default"],
+          health: "/h",
+          version: "1",
+        },
+        {
+          name: "parachute-vault-work",
+          port: 1940,
+          paths: ["/vault/work"],
+          health: "/h",
+          version: "1",
+        },
+      ]);
+      seedOperatorToken(h.configDir);
+      const { code, checks } = await runDoctor(h, healthyDeps());
+      const pd = byName(checks, "port-drift");
+      // PASS (clean) — neither flagged as drifted nor as a duplicate collision.
+      expect(pd?.status).toBe("pass");
+      expect(pd?.detail).toContain("canonical");
+      expect(code).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
+describe("doctor --fix — canonical-port repair (confirm-gated, idempotent, non-tty-safe)", () => {
+  test("--fix on a clean file → 'no drift', exit 0, file unchanged (idempotent)", async () => {
+    const h = makeHarness();
+    try {
+      seedCurrentManifest(h.manifestPath);
+      const before = readFileSync(h.manifestPath, "utf8");
+      const { code, lines } = await runFix(h, { isInteractive: () => true }, { yes: true });
+      expect(code).toBe(0);
+      expect(lines.join("\n").toLowerCase()).toContain("nothing to fix");
+      expect(readFileSync(h.manifestPath, "utf8")).toBe(before);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix on an absent services.json (fresh install) → 'nothing to fix', exit 0", async () => {
+    const h = makeHarness();
+    try {
+      // No services.json at all — the truly-fresh case. --fix must NOT report a
+      // corrupt-file error; it's the idempotent no-op path.
+      const { code, lines } = await runFix(h, { isInteractive: () => false }, { yes: false });
+      expect(code).toBe(0);
+      expect(lines.join("\n").toLowerCase()).toContain("nothing to fix");
+      expect(lines.join("\n").toLowerCase()).not.toContain("can't read");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix --yes rewrites the drifted port to canonical + preserves other fields", async () => {
+    const h = makeHarness();
+    try {
+      // scribe drifted onto 1944; carries an optional displayName/tagline that
+      // must survive the rewrite.
+      writeManifestRows(h.manifestPath, [
+        {
+          name: "parachute-scribe",
+          port: 1944,
+          paths: ["/scribe"],
+          health: "/scribe/health",
+          version: "0.7.4",
+          displayName: "Scribe",
+          tagline: "Local audio transcription.",
+          stripPrefix: true,
+        },
+      ]);
+      const { code, lines } = await runFix(h, {}, { yes: true });
+      expect(code).toBe(0);
+      expect(lines.join("\n")).toContain("→ :1943");
+      const rows = readRows(h.manifestPath);
+      const scribe = rows.find((r) => r.name === "parachute-scribe");
+      expect(scribe?.port).toBe(1943);
+      // Optional + unknown fields preserved verbatim.
+      expect(scribe?.displayName).toBe("Scribe");
+      expect(scribe?.tagline).toBe("Local audio transcription.");
+      expect(scribe?.stripPrefix).toBe(true);
+
+      // Re-run → idempotent: now clean, exit 0, nothing to fix.
+      const again = await runFix(h, {}, { yes: true });
+      expect(again.code).toBe(0);
+      expect(again.lines.join("\n").toLowerCase()).toContain("nothing to fix");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix in a TTY without --yes prompts; 'y' applies the rewrite", async () => {
+    const h = makeHarness();
+    try {
+      writeManifestRows(h.manifestPath, [
+        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
+      ]);
+      const { code } = await runFix(
+        h,
+        { isInteractive: () => true, readLine: async () => "y" },
+        { yes: false },
+      );
+      expect(code).toBe(0);
+      expect(readRows(h.manifestPath).find((r) => r.name === "parachute-scribe")?.port).toBe(1943);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix in a TTY answered 'n' → aborts, exit non-zero, file UNCHANGED", async () => {
+    const h = makeHarness();
+    try {
+      writeManifestRows(h.manifestPath, [
+        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
+      ]);
+      const before = readFileSync(h.manifestPath, "utf8");
+      const { code, lines } = await runFix(
+        h,
+        { isInteractive: () => true, readLine: async () => "n" },
+        { yes: false },
+      );
+      expect(code).not.toBe(0);
+      expect(lines.join("\n").toLowerCase()).toContain("unchanged");
+      expect(readFileSync(h.manifestPath, "utf8")).toBe(before);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix in a NON-TTY without --yes → bails, exit non-zero, file UNCHANGED", async () => {
+    const h = makeHarness();
+    try {
+      writeManifestRows(h.manifestPath, [
+        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
+      ]);
+      const before = readFileSync(h.manifestPath, "utf8");
+      const { code, lines } = await runFix(h, { isInteractive: () => false }, { yes: false });
+      expect(code).not.toBe(0);
+      expect(lines.join("\n")).toContain("--yes");
+      // The load-bearing guarantee: no write happened.
+      expect(readFileSync(h.manifestPath, "utf8")).toBe(before);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("--fix reports a duplicate-port collision but does not auto-resolve it", async () => {
+    const h = makeHarness();
+    try {
+      // Two services collide on 1944; neither is on its canonical slot. The
+      // diff fixes the canonical drift; the collision is reported, not guessed.
+      writeManifestRows(h.manifestPath, [
+        { name: "parachute-scribe", port: 1944, paths: ["/scribe"], health: "/h", version: "1" },
+        { name: "parachute-agent", port: 1944, paths: ["/agent"], health: "/h", version: "1" },
+      ]);
+      const { code, lines } = await runFix(h, {}, { yes: true });
+      const text = lines.join("\n");
+      expect(text.toLowerCase()).toContain("shared by");
+      expect(text).toContain("parachute-scribe + parachute-agent");
+      // scribe → 1943 and agent → 1941 are both off 1944, so after the rewrite
+      // they no longer collide; fix applied, exit 0.
+      expect(code).toBe(0);
+      const rows = readRows(h.manifestPath);
+      expect(rows.find((r) => r.name === "parachute-scribe")?.port).toBe(1943);
+      expect(rows.find((r) => r.name === "parachute-agent")?.port).toBe(1941);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

package/src/api-modules.ts

@@ -42,6 +42,9 @@
  */
 
 import type { Database } from "bun:sqlite";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { compareVersions } from "./commands/upgrade.ts";
 import { validateHostAdminToken } from "./host-admin-token-validation.ts";
 import {
   type ModuleInstallChannel,
@@ -178,6 +181,40 @@ export interface ApiModulesDeps {
    * (hub#342 — drives the admin SPA Modules page's "Open" button).
    */
   readModuleManifest?: (installDir: string) => Promise<ModuleManifest | null>;
+  /**
+   * Read the LIVE installed version of a module from its install dir's
+   * `package.json` `version` (hub#243). The services.json `version` field is a
+   * CACHE the module writes on its own boot — on the bun-linked dev path it
+   * goes stale the moment the checkout is rebuilt to a newer version without a
+   * restart that re-stamps services.json. The admin Modules view reads
+   * `installed_version` straight from that cache, so it can show a stale version
+   * (the live symptom: services.json said 0.5.4-rc.15 while the linked checkout
+   * was already 0.6.4-rc.15). When this resolves a version, it WINS over the
+   * services.json cache for the `installed_version` field so the operator sees
+   * what's actually on disk. Returns null on any failure (no install dir,
+   * missing/unreadable package.json, no version) → fall back to the
+   * services.json cache, which is the only source for a not-yet-booted module.
+   *
+   * Production reads `<installDir>/package.json`; tests inject a fake.
+   */
+  readInstalledVersion?: (installDir: string) => string | null;
+}
+
+/**
+ * Default `readInstalledVersion`. Reads `<installDir>/package.json`'s `version`
+ * — the authoritative live version of a module's code on disk, which the
+ * bun-linked dev path keeps current while the services.json cache can lag
+ * (hub#243). Returns null on any failure so the caller falls back to the
+ * services.json `version`.
+ */
+export function defaultReadInstalledVersion(installDir: string): string | null {
+  try {
+    const raw = readFileSync(join(installDir, "package.json"), "utf8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    return typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : null;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -239,6 +276,24 @@ interface ModuleWireShape {
   installed: boolean;
   installed_version: string | null;
   latest_version: string | null;
+  /**
+   * Whether the channel-resolved `latest_version` is a REAL upgrade — i.e.
+   * STRICTLY NEWER than `installed_version` under semver ordering (hub#243).
+   * Computed server-side via `compareVersions` so the rc/prerelease ordering is
+   * correct and there's ONE tested source of truth (the SPA used to derive this
+   * client-side with a string `!==`, which framed a *downgrade* as an upgrade:
+   * an rc operator on `0.6.4-rc.15` was offered an "upgrade" to the older
+   * `@latest` `0.6.3` purely because the two strings differed).
+   *
+   * `false` when: not installed · no `latest_version` (probe failed) · target ≤
+   * installed (same or older — incl. the rc→older-stable downgrade) · either
+   * version is unparseable (`compareVersions` returns null → fail-closed: don't
+   * offer a move we can't verify is forward). `true` ONLY when the target
+   * parses AND sorts strictly above installed — so `0.6.4-rc.15` → stable
+   * `0.6.4` IS an upgrade (stable > its own rc per semver §11.4.3), but
+   * `0.6.4-rc.15` → `0.6.3` is NOT.
+   */
+  upgrade_available: boolean;
   supervisor_status: ModuleState["status"] | null;
   pid: number | null;
   /**
@@ -451,6 +506,8 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
   // Lenient read so a single bad row written by a buggy module install
   // (e.g. app@0.2.0-rc.4) doesn't take down /api/modules — see hub#406.
   const manifest = readManifestLenient(deps.manifestPath);
+  // Live on-disk version reader (hub#243) — see `defaultReadInstalledVersion`.
+  const readInstalledVersion = deps.readInstalledVersion ?? defaultReadInstalledVersion;
   const installedByShort = new Map<
     string,
     {
@@ -476,6 +533,18 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       uis?: Record<string, UiSubUnit>;
       mountPath?: string;
     } = { version: entry.version };
+    // Prefer the LIVE on-disk version over the services.json cache when we can
+    // read it (hub#243). `entry.version` is a cache the module stamps on its own
+    // boot; on the bun-linked dev path it lags after a rebuild-without-restart,
+    // so the admin view shows a stale "current" (the live symptom: cache said
+    // 0.5.4-rc.15 while the linked checkout was already 0.6.4-rc.15). The
+    // module's `<installDir>/package.json` `version` is authoritative for the
+    // code actually on disk. Falls back to the cache when there's no installDir
+    // or the package.json can't be read (e.g. a not-yet-booted seed row).
+    if (entry.installDir !== undefined) {
+      const live = readInstalledVersion(entry.installDir);
+      if (live !== null) value.version = live;
+    }
     if (entry.installDir !== undefined) value.installDir = entry.installDir;
     if (entry.uis !== undefined) value.uis = entry.uis;
     // First non-`.parachute` path is the module's user-facing mount
@@ -622,6 +691,10 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       installed: installed !== undefined,
       installed_version: installed?.version ?? null,
       latest_version: latestByShort.get(short) ?? null,
+      upgrade_available: isUpgradeAvailable(
+        installed?.version ?? null,
+        latestByShort.get(short) ?? null,
+      ),
       supervisor_status: state?.status ?? null,
       pid: state?.pid ?? null,
       supervisor_start_error: state?.startError ?? null,
@@ -644,6 +717,9 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
 
   // Every supervised module's run-state — curated AND non-curated (hub#539).
   // Built from the same supervisor.list() snapshot already in `stateByShort`.
+  // `installed_version` here inherits the live-on-disk override already applied
+  // to `installedByShort[].version` in the manifest loop above (hub#243), so the
+  // `supervised` array reports the same corrected version as the `modules` rows.
   const supervised: SupervisedSnapshotWire[] = Array.from(stateByShort.values()).map((s) => ({
     short: s.short,
     installed: installedByShort.has(s.short),
@@ -842,6 +918,35 @@ function toUisWireShape(uis: Record<string, UiSubUnit> | undefined): UiSubUnitWi
   }));
 }
 
+/**
+ * Whether `latest` is a REAL upgrade over `installed` — strictly newer under
+ * semver ordering (hub#243). The single tested source of truth for the
+ * "upgrade available?" decision, shared by the wire shape's `upgrade_available`
+ * field and (transitively) the admin SPA's Upgrade button.
+ *
+ * Returns `false` unless BOTH versions parse AND `latest` sorts strictly above
+ * `installed`:
+ *   - no installed version (not installed) → false.
+ *   - no latest version (probe failed / unknown package) → false.
+ *   - `compareVersions` can't parse either side → false (FAIL-CLOSED: never
+ *     offer a move we can't prove is forward).
+ *   - target ≤ installed → false. This is the load-bearing downgrade guard:
+ *     an rc operator on `0.6.4-rc.15` whose channel resolves `latest_version`
+ *     to the OLDER `@latest` `0.6.3` is NOT offered an "upgrade" (the live bug
+ *     — a downgrade framed as an upgrade by the old string `!==`).
+ *
+ * Reuses `commands/upgrade.ts:compareVersions`, the same comparator the CLI
+ * `parachute upgrade` downgrade guard uses, so the SPA offer and the CLI guard
+ * can't disagree about rc/prerelease ordering. Note `0.6.4-rc.15` → stable
+ * `0.6.4` IS strictly-newer (stable > its own rc per semver §11.4.3), so a real
+ * rc→its-stable promotion still surfaces as an upgrade.
+ */
+export function isUpgradeAvailable(installed: string | null, latest: string | null): boolean {
+  if (installed === null || latest === null) return false;
+  const cmp = compareVersions(latest, installed);
+  return cmp !== null && cmp > 0;
+}
+
 /**
  * Reset the in-memory `latest_version` cache. Tests call this between
  * runs to prevent state leakage across test cases; production never

package/src/cli.ts

@@ -581,15 +581,26 @@ async function main(argv: string[]): Promise<number> {
         return 0;
       }
       const json = rest.includes("--json");
-      const unknown = rest.find((a) => a !== "--json");
+      const fix = rest.includes("--fix");
+      const yes = rest.includes("--yes") || rest.includes("-y");
+      const known = new Set(["--json", "--fix", "--yes", "-y"]);
+      const unknown = rest.find((a) => !known.has(a));
       if (unknown !== undefined) {
         console.error(`parachute doctor: unknown argument "${unknown}"`);
-        console.error("usage: parachute doctor [--json]");
+        console.error("usage: parachute doctor [--json] [--fix [--yes]]");
+        return 1;
+      }
+      if (json && fix) {
+        console.error("parachute doctor: --json and --fix are mutually exclusive");
+        return 1;
+      }
+      if (yes && !fix) {
+        console.error("parachute doctor: --yes has no effect without --fix");
         return 1;
       }
       const mod = await loadCommand("doctor", () => import("./commands/doctor.ts"));
       if (!mod) return 1;
-      return await mod.doctor({ json });
+      return await mod.doctor({ json, fix, yes });
     }
 
     case "expose": {