jeo-code 0.12.21 → 0.12.22

package/src/commands/doctor.ts

@@ -14,6 +14,9 @@ import { visibleWidth, truncateToWidth } from "../tui/components/width";
 import chalk from "chalk";
 import { extractChatgptAccountId, CODEX_RESPONSES_URL } from "../ai/providers/openai-responses";
 import { resolveTierModel, tierModelPool, cheapestCredentialed } from "../agent/prompt-router";
+import { DEFAULT_SIZE_CAP_MS, collectSharedInstallReport, type SharedInstallReport } from "../util/shared-install-report";
+import { formatBytes } from "../tui/components/session-picker";
+import { compareVersions } from "./update";
 
 interface ProbeResult {
   status: "ok" | "fail" | "skipped";
@@ -219,7 +222,93 @@ function providerTableLines(
   return renderMarkdownTables(md, { unicode, maxColWidth: detailBudget }).split("\n");
 }
 
-export async function runDoctorCommand(args: string[] = []): Promise<void> {
+export interface DoctorDeps {
+  /** Produces the shared bun global report; tests inject it, the default scans the real machine (memoized). */
+  sharedInstall?: () => SharedInstallReport | Promise<SharedInstallReport>;
+}
+
+const SHARED_INSTALL_TTL_MS = 30_000;
+let sharedInstallMemo: { key: string; at: number; report: SharedInstallReport } | undefined;
+
+/** The real scan, memoized for 30 s per environment so repeated doctor runs in one process walk the global dir once. */
+function defaultSharedInstall(): SharedInstallReport {
+  const key = [process.env.HOME, process.env.BUN_INSTALL, process.env.BUN_INSTALL_GLOBAL_DIR, process.env.XDG_CONFIG_HOME, process.env.PATH, process.platform].join("|");
+  if (sharedInstallMemo?.key === key && Date.now() - sharedInstallMemo.at < SHARED_INSTALL_TTL_MS) return sharedInstallMemo.report;
+  const report = collectSharedInstallReport();
+  sharedInstallMemo = { key, at: Date.now(), report };
+  return report;
+}
+
+const ORPHAN_KIND_NOTE: Record<"directory" | "symlink" | "dangling-symlink", string> = {
+  directory: "possible orphan",
+  symlink: "possible orphan, symlink",
+  "dangling-symlink": "possible orphan, dangling symlink",
+};
+
+/** Human text for the shared install section. Warnings are yellow, an ok lockfile green; paths are never truncated. */
+function sharedInstallLines(report: SharedInstallReport): string[] {
+  const lines: string[] = [];
+  const { manifest, lockfile, leftovers, sizes } = report;
+  if (report.skipped !== null) {
+    lines.push(`Shared install: no usable bun global (${report.skipped}); lockfile, leftover and size checks skipped.`);
+  } else {
+    lines.push(`Shared install (${report.globalDir ?? "unknown"}):`);
+  }
+  if (manifest !== null) lines.push(`  packages:  ${manifest.dependencies} in manifest (${manifest.external} besides jeo-code)`);
+  if (lockfile !== null) {
+    if (lockfile.status === "ok") {
+      const total = manifest?.external ?? lockfile.uncovered.length;
+      lines.push(chalk.green(`  bun.lock:  ok (${total - lockfile.uncovered.length} of ${total} covered)`));
+    } else if (lockfile.status === "not-required") {
+      lines.push("  bun.lock:  not required (jeo-code is the only package)");
+    } else if (lockfile.status === "missing") {
+      lines.push(chalk.yellow("  bun.lock:  MISSING - jeo update will refuse until it is restored (or pass --allow-unlocked-global)"));
+    } else if (lockfile.status === "incomplete") {
+      lines.push(chalk.yellow(`  bun.lock:  INCOMPLETE - no resolved entry for: ${lockfile.uncovered.join(", ")}`));
+    } else {
+      lines.push(chalk.yellow(`  bun.lock:  UNREADABLE${lockfile.detail ? ` (${lockfile.detail})` : ""}`));
+    }
+  }
+  if (report.jeoOnPath.length === 0) {
+    lines.push("  jeo on PATH: none found");
+  } else {
+    const activeVersion = report.jeoOnPath.find(entry => entry.active)?.version ?? null;
+    lines.push("  jeo on PATH (first = active):");
+    for (const entry of report.jeoOnPath) {
+      const marker = entry.active ? "*" : " ";
+      const text = `    ${marker} ${entry.path}  ${entry.version ?? "(version unknown)"}${entry.active ? " (active)" : ""}`;
+      if (entry.stale && entry.version !== null && activeVersion !== null) {
+        const direction = compareVersions(entry.version, activeVersion) < 0 ? "older" : "newer";
+        lines.push(chalk.yellow(`${text} [stale: ${direction} than active ${activeVersion}]`));
+      } else {
+        lines.push(text);
+      }
+    }
+  }
+  if (leftovers !== null) {
+    if (leftovers.backupFiles.length === 0 && leftovers.possibleOrphans.length === 0 && leftovers.orphanScanComplete) {
+      lines.push("  leftovers: none");
+    } else {
+      lines.push("  leftovers (not touched):");
+      for (const file of leftovers.backupFiles) lines.push(chalk.yellow(`    file    ${file}`));
+      for (const orphan of leftovers.possibleOrphans) lines.push(chalk.yellow(`    orphan  ${orphan.name} (${ORPHAN_KIND_NOTE[orphan.kind]})`));
+      if (!leftovers.orphanScanComplete) lines.push(chalk.yellow("    orphan scan stopped at its cap; no orphans reported"));
+    }
+  }
+  if (sizes !== null) {
+    const top = `top ${sizes.top.length}: ${sizes.top.map(p => `${p.name} ${formatBytes(p.bytes)}`).join(", ")}`;
+    if (sizes.capped === null) {
+      lines.push(`  size: ${formatBytes(sizes.totalBytes)} total${sizes.top.length > 0 ? `; ${top}` : ""}`);
+    } else {
+      const cap = sizes.capped === "time" ? `time cap (${DEFAULT_SIZE_CAP_MS} ms)` : `entry cap (${sizes.scannedEntries} entries)`;
+      lines.push(chalk.yellow(`  size scan stopped at the ${cap}; figures are lower bounds`));
+      lines.push(`    at least ${formatBytes(sizes.totalBytes)} scanned${sizes.top.length > 0 ? `; ${top}` : ""}`);
+    }
+  }
+  return lines;
+}
+
+export async function runDoctorCommand(args: string[] = [], deps: DoctorDeps = {}): Promise<void> {
   const strict = args.includes("--strict");
   const json = args.includes("--json");
   const config = await readGlobalConfig();
@@ -379,6 +468,14 @@ export async function runDoctorCommand(args: string[] = []): Promise<void> {
     ? defaultProbe?.result.status === "skipped"
     : defaultProbe?.result.status === "ok";
 
+  // Shared bun global diagnostics: read-only, never affects `ready` or the exit code.
+  let sharedInstall: SharedInstallReport | { error: string };
+  try {
+    sharedInstall = await (deps.sharedInstall ?? defaultSharedInstall)();
+  } catch (err) {
+    sharedInstall = { error: err instanceof Error ? err.message : String(err) };
+  }
+
   // --- JSON output mode (CI / scripting) ---
   if (json) {
     const report = {
@@ -402,6 +499,7 @@ export async function runDoctorCommand(args: string[] = []): Promise<void> {
       oauth: oauthHealth,
       ready,
       ...(routingEnabled ? { routing: { enabled: true, smolConfigured, preview: routingPreview, ...(routingNotes.length ? { notes: routingNotes } : {}) } } : {}),
+      sharedInstall,
 
     };
     console.log(JSON.stringify(report, null, 2));
@@ -490,6 +588,13 @@ export async function runDoctorCommand(args: string[] = []): Promise<void> {
     console.log("");
   }
 
+  if ("error" in sharedInstall) {
+    console.log(chalk.yellow(`Shared install: check failed (${sharedInstall.error})`));
+  } else {
+    for (const line of sharedInstallLines(sharedInstall)) console.log(line);
+  }
+  console.log("");
+
   // Final verdict
   if (ready) {
     console.log(`${chalk.green("[READY]")} Default model '${config.defaultModel}' is reachable.`);

package/src/commands/update.ts

@@ -1,6 +1,22 @@
 import { existsSync } from "node:fs";
 import pkg from "../../package.json";
 import { messengerProfilesPath } from "../messenger/runtime";
+import {
+  checkLockCoverage,
+  detectInstallOrigin,
+  diffInstalled,
+  formatChangeLine,
+  formatRestoreCommands,
+  formatUnchangedSummary,
+  locateSharedGlobal,
+  readManifestDeps,
+  snapshotInstalled,
+  type ExternalChange,
+  type InstalledSnapshot,
+  type InstallOrigin,
+  type LocatedGlobal,
+  type LockStatus,
+} from "../util/shared-global";
 
 /**
  * Compares two semver-ish version strings.
@@ -34,10 +50,18 @@ export function compareVersions(a: string, b: string): -1 | 0 | 1 {
   return 0;
 }
 
+/** Outcome of one self-install. `manual` carries the commands to run by hand when no automatic attempt worked. */
+export interface InstallResult {
+  success: boolean;
+  stdout?: string;
+  stderr?: string;
+  manual?: string[];
+}
+
 export interface UpdateDeps {
   fetchJson: (url: string, options?: { signal?: AbortSignal }) => Promise<any>;
   localVersion: () => string;
-  install: (version?: string) => Promise<{ success: boolean; stdout?: string; stderr?: string }>;
+  install: (version?: string) => Promise<InstallResult>;
   /** Display release notes after a successful self-update (best-effort, no-op in tests). */
   showWhatsNew?: () => void;
   /**
@@ -50,6 +74,11 @@ export interface UpdateDeps {
   /** Version of the `jeo` actually on PATH, read after install to catch a silent no-op
    *  (installed but PATH still points at a different/older binary). Optional in tests. */
   activeVersion?: () => string | null;
+  /**
+   * Where the shared bun global lives, so an update can refuse before any installer could re-resolve packages
+   * jeo does not own and can report any that moved. Optional: absent = no inspection (every existing test).
+   */
+  sharedGlobal?: { locate: () => LocatedGlobal };
 }
 
 /**
@@ -58,16 +87,72 @@ export interface UpdateDeps {
  * `bun install -g` alone is not enough in practice: right after a publish bun can
  * still hold a stale registry manifest and fail with `No version matching "<v>"
  * found ... (but package exists)`. `--force` re-resolves against the registry and
- * is what actually recovers that state. npm remains the last resort for
- * npm-installed globals. Pure so the policy is unit-testable without spawning.
+ * is what actually recovers that state. npm is the last resort only for an active jeo that
+ * lives under npm's global root (`origin` 'npm-global'): from a bun-global or unknown location
+ * an npm install would create a stale second copy, so it is never attempted there. `origin`
+ * undefined keeps the legacy three attempts. Pure so the policy is unit-testable without spawning.
  */
-export function installCandidates(target: string): string[][] {
-  return [
+export function installCandidates(target: string, origin?: InstallOrigin): string[][] {
+  const candidates = [
     ["bun", "install", "-g", target],
     // Cache-buster: bun's resolver held a stale manifest for a just-published version.
     ["bun", "install", "-g", target, "--force"],
-    ["npm", "install", "-g", target],
   ];
+  if (origin === undefined || origin === "npm-global") candidates.push(["npm", "install", "-g", target]);
+  return candidates;
+}
+
+/** What to tell the user to run when every automatic attempt failed and npm was deliberately not tried. */
+export function manualInstallLines(target: string, origin: InstallOrigin): string[] {
+  if (origin === "npm-global") return [];
+  return [
+    `bun install -g ${target} --force`,
+    origin === "bun-global"
+      ? "(npm was not tried: the active jeo is under the bun global install)"
+      : `(npm was not tried: the active jeo is not under the npm global root; if it came from npm run: npm install -g ${target})`,
+  ];
+}
+
+/** Side effects `runInstall` needs, injected so the attempt policy is testable without spawning. */
+export interface InstallIo {
+  spawn: (cmd: string[]) => { success: boolean; exitCode?: number | null };
+  activeVersion: () => string | null;
+  origin: () => InstallOrigin;
+}
+
+function errorText(err: unknown): string {
+  const message = err !== null && typeof err === "object" && "message" in err ? err.message : undefined;
+  return message ? String(message) : String(err);
+}
+
+/**
+ * Self-update the global install via the toolchain it was installed with. jeo ships as a
+ * `#!/usr/bin/env bun` script so bun is the common case; npm is tried last, and only when the
+ * active jeo lives under npm's global root (see installCandidates). The origin is resolved once,
+ * before the first spawn.
+ */
+export function runInstall(version: string | undefined, io: InstallIo): InstallResult {
+  const target = `jeo-code@${version ?? "latest"}`;
+  const origin = io.origin();
+  let lastErr = "";
+  for (const cmd of installCandidates(target, origin)) {
+    try {
+      const proc = io.spawn(cmd);
+      if (proc.success) {
+        // A zero exit is NOT proof the user's `jeo` moved: npm's global prefix is
+        // often a different directory than the bun prefix PATH actually resolves,
+        // so an npm fallback can "succeed" while the active binary is untouched.
+        // Only stop once the binary on PATH really reports the requested version.
+        if (!version || io.activeVersion() === version) return { success: true };
+        lastErr = `${cmd[0]} reported success but the active 'jeo' is still ${io.activeVersion() ?? "unknown"}`;
+        continue;
+      }
+      lastErr = `${cmd[0]} exited with code ${proc.exitCode}`;
+    } catch (err) {
+      lastErr = `${cmd[0]} unavailable: ${errorText(err)}`;
+    }
+  }
+  return { success: false, stderr: lastErr, manual: manualInstallLines(target, origin) };
 }
 
 /** Version of the `jeo` binary PATH actually resolves, or null when unreadable. */
@@ -100,32 +185,13 @@ export const defaultDeps: UpdateDeps = {
   localVersion: () => {
     return pkg.version;
   },
-  install: async (version?: string) => {
-    // Self-update the global install via the SAME toolchain it was installed with. jeo
-    // ships as a `#!/usr/bin/env bun` script so bun is the common case, but npm-installed
-    // globals exist too — try bun first, fall back to npm (and tolerate either missing).
-    const target = `jeo-code@${version ?? "latest"}`;
-    let lastErr = "";
-    for (const cmd of installCandidates(target)) {
-      try {
-        const proc = Bun.spawnSync(cmd, { stdout: "inherit", stderr: "inherit" });
-        if (proc.success) {
-          // A zero exit is NOT proof the user's `jeo` moved: npm's global prefix is
-          // often a different directory than the bun prefix PATH actually resolves,
-          // so an npm fallback can "succeed" while the active binary is untouched.
-          // Only stop once the binary on PATH really reports the requested version.
-          if (!version || readActiveVersion() === version) return { success: true };
-          lastErr = `${cmd[0]} reported success but the active 'jeo' is still ${readActiveVersion() ?? "unknown"}`;
-          continue;
-        }
-        lastErr = `${cmd[0]} exited with code ${proc.exitCode}`;
-      } catch (err: any) {
-        lastErr = `${cmd[0]} unavailable: ${err?.message ?? String(err)}`;
-      }
-    }
-    return { success: false, stderr: lastErr };
-  }
-,
+  sharedGlobal: { locate: locateSharedGlobal },
+  install: async (version?: string) =>
+    runInstall(version, {
+      spawn: cmd => Bun.spawnSync(cmd, { stdout: "inherit", stderr: "inherit" }),
+      activeVersion: readActiveVersion,
+      origin: () => detectInstallOrigin().origin,
+    }),
   // Version of the `jeo` actually on PATH — may differ from this process's bundled
   // version after a self-update (e.g. npm installed into a prefix PATH does not
   // resolve). Detects the silent "installed but PATH unchanged" no-op.
@@ -159,14 +225,143 @@ export async function runUpdateCommand(args: string[] = []): Promise<void> {
   return runUpdateCommandWith(args, defaultDeps);
 }
 
+/** What the guard found in the shared bun global before the installer ran (the `preflight` JSON key). */
+interface SharedPreflight {
+  globalDir: string;
+  externalCount: number;
+  lockfile: LockStatus;
+  uncovered: string[];
+  allowedUnlocked: boolean;
+}
+
+interface SharedArmed {
+  kind: "armed";
+  dir: string;
+  /** Manifest dependency names other than jeo-code, as they were before the install. */
+  beforeNames: string[];
+  /** Installed versions captured BEFORE the install; settle never re-reads them from disk. */
+  before: InstalledSnapshot;
+  /** Null when the manifest has no packages besides jeo-code (nothing to guard, nothing to report). */
+  preflight: SharedPreflight | null;
+}
+
+type SharedArm = { kind: "off" } | SharedArmed;
+type SharedBegin = SharedArm | { kind: "refused"; preflight: SharedPreflight; error: string; lines: string[] };
+
+interface SharedSettled {
+  dir: string;
+  changes: ExternalChange[];
+  /** `shared global unchanged: ...`, only when a shared global with external packages was inspected and nothing moved. */
+  summary: string | null;
+  preflight: SharedPreflight | null;
+  driftError: string | null;
+}
+
+function skipShared(hasJson: boolean, reason: string): SharedBegin {
+  if (!hasJson) console.log(`Shared bun global not inspected (${reason}); the isolation check is skipped.`);
+  return { kind: "off" };
+}
+
+/**
+ * Runs at the start of the install branch, before any installer. Refuses when the shared bun global lists
+ * packages besides jeo-code and its bun.lock cannot pin them (bun would re-resolve and could move them);
+ * otherwise captures the installed versions that settleShared compares against after the install.
+ */
+function beginShared(deps: UpdateDeps, opts: { hasJson: boolean; allowUnlocked: boolean }): SharedBegin {
+  if (!deps.sharedGlobal) return { kind: "off" };
+  const located = deps.sharedGlobal.locate();
+  if (!located.ok) return skipShared(opts.hasJson, located.reason);
+  const manifest = readManifestDeps(located.dir);
+  if (!manifest.ok) return skipShared(opts.hasJson, "manifest-unreadable");
+  const dir = located.dir;
+  const external = manifest.deps.external;
+  const before = snapshotInstalled(dir, external);
+  if (external.length === 0) return { kind: "armed", dir, beforeNames: external, before, preflight: null };
+  const lock = checkLockCoverage(dir, external);
+  const unlocked = lock.status !== "ok";
+  const preflight: SharedPreflight = {
+    globalDir: dir,
+    externalCount: external.length,
+    lockfile: lock.status,
+    uncovered: lock.uncovered,
+    allowedUnlocked: unlocked && opts.allowUnlocked,
+  };
+  if (!unlocked) return { kind: "armed", dir, beforeNames: external, before, preflight };
+  const names = lock.uncovered.join(", ");
+  if (!opts.allowUnlocked) {
+    const problem =
+      lock.status === "missing"
+        ? "is missing"
+        : lock.status === "incomplete"
+          ? `has no resolved entry for ${names}`
+          : `could not be read${lock.detail ? ` (${lock.detail})` : ""}`;
+    return {
+      kind: "refused",
+      preflight,
+      error: `shared bun global lockfile ${lock.status} (${names}); refusing to run any installer, re-run with --allow-unlocked-global to override`,
+      lines: [
+        `[REFUSED] jeo update did not run: the shared bun global at ${dir} has packages besides jeo-code but its bun.lock ${problem}.`,
+        `  bun would re-resolve every package in that directory and could move: ${names}`,
+        "  Nothing was installed or changed.",
+        `  Restore ${lock.path} (for example from a backup), or accept the re-resolution with: jeo update --allow-unlocked-global`,
+        ...(lock.legacyBinaryLock ? ["  (a binary bun.lockb is not accepted)"] : []),
+      ],
+    };
+  }
+  if (!opts.hasJson) console.warn(`Warning: bun.lock ${lock.status} for: ${names}; --allow-unlocked-global lets bun re-resolve them, drift will be reported.`);
+  return { kind: "armed", dir, beforeNames: external, before, preflight };
+}
+
+/**
+ * Runs exactly once, right after the installer returned or threw. The before map is the one captured by
+ * beginShared (re-reading it here would see post-install versions and could never show drift); only the
+ * after map is read from disk.
+ */
+function settleShared(arm: SharedArm): SharedSettled {
+  if (arm.kind === "off") return { dir: "", changes: [], summary: null, preflight: null, driftError: null };
+  const manifest = readManifestDeps(arm.dir);
+  const afterNames = manifest.ok ? manifest.deps.external : arm.beforeNames;
+  const names = [...new Set([...arm.beforeNames, ...afterNames])];
+  const before: InstalledSnapshot = Object.fromEntries(names.map(name => [name, Object.hasOwn(arm.before, name) ? arm.before[name] : null]));
+  const after = snapshotInstalled(arm.dir, names, new Set(afterNames));
+  const changes = diffInstalled(before, after);
+  return {
+    dir: arm.dir,
+    changes,
+    summary: changes.length === 0 && arm.preflight !== null ? formatUnchangedSummary(after) : null,
+    preflight: arm.preflight,
+    driftError: changes.length > 0 ? `shared bun global changed: ${changes.map(formatChangeLine).join("; ")}` : null,
+  };
+}
+
+/** `externalChanges` and `preflight` JSON keys, present only when a shared global with external packages was inspected. */
+function sharedJson(s: SharedSettled): { externalChanges?: ExternalChange[]; preflight?: SharedPreflight } {
+  if (s.preflight === null && s.changes.length === 0) return {};
+  return { externalChanges: s.changes, ...(s.preflight === null ? {} : { preflight: s.preflight }) };
+}
+
+/** The human drift report: what moved and the commands that would put it back. They are printed, never run. */
+function printSharedDrift(s: SharedSettled, version: string | null, installed: boolean): void {
+  console.error(
+    installed
+      ? `[FAILED] jeo-code@${version} was installed, but the shared bun global at ${s.dir} changed other packages:`
+      : `[FAILED] the install of jeo-code@${version} did not finish cleanly, and the shared bun global at ${s.dir} changed other packages:`,
+  );
+  for (const change of s.changes) console.error(`  ${formatChangeLine(change)}`);
+  console.error("jeo does not repair these. To put them back run:");
+  for (const command of formatRestoreCommands(s.changes)) console.error(`  ${command}`);
+  if (installed) console.error("Messenger runtimes were not refreshed; run 'jeo messenger update' after restoring.");
+}
+
 export async function runUpdateCommandWith(args: string[], deps: UpdateDeps): Promise<void> {
   const isHelp = args.includes("--help") || args.includes("-h");
   const hasInstall = args.includes("--install");
   const hasCheck = args.includes("--check");
   const hasJson = args.includes("--json");
   const hasStrict = args.includes("--strict");
+  const allowUnlocked = args.includes("--allow-unlocked-global");
 
-  const KNOWN_FLAGS = new Set(["--check", "--install", "--json", "--strict", "--version", "-h", "--help"]);
+  const KNOWN_FLAGS = new Set(["--check", "--install", "--json", "--strict", "--allow-unlocked-global", "--version", "-h", "--help"]);
   // A semver-ish shape: MAJOR.MINOR.PATCH with optional -prerelease and/or +build metadata,
   // matching what the npm registry actually publishes (and what activeVersion() parses back out).
   const SEMVER_RE = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
@@ -317,13 +512,35 @@ export async function runUpdateCommandWith(args: string[], deps: UpdateDeps): Pr
           : `jeo-code is already up-to-date (${current}).`);
       }
     } else {
+      const shared = beginShared(deps, { hasJson, allowUnlocked });
+      if (shared.kind === "refused") {
+        if (hasJson) {
+          console.log(JSON.stringify({
+            current,
+            latest,
+            upToDate: false,
+            installed: false,
+            error: shared.error,
+            preflight: shared.preflight
+          }));
+        } else {
+          for (const line of shared.lines) console.error(line);
+        }
+        process.exitCode = 1;
+        return;
+      }
       if (!hasJson) {
         console.log(pinnedVersion
           ? `Installing pinned version: ${current} -> ${latest}...`
           : `Installing update: ${current} -> ${latest}...`);
       }
+      // Settled exactly once: right after the installer returns, or in the catch when it threw
+      // (a throwing installer may have half-run). Messenger refresh never happens before this.
+      let settled: SharedSettled | null = null;
       try {
         const result = await deps.install(latest ?? undefined);
+        settled = settleShared(shared);
+        const drift = settled.changes.length > 0;
         if (result.success) {
           // A package manager's zero exit does not prove the user's `jeo` moved: npm's
           // global prefix is frequently a different directory than the one PATH resolves,
@@ -333,25 +550,33 @@ export async function runUpdateCommandWith(args: string[], deps: UpdateDeps): Pr
           const active = deps.activeVersion?.();
           const stale = !!(active && latest && compareVersions(active, latest) < 0);
           if (hasJson) {
-            const messengersRefreshed = stale ? null : (deps.refreshMessengers?.(true) ?? null);
+            const messengersRefreshed = stale || drift ? null : (deps.refreshMessengers?.(true) ?? null);
             console.log(JSON.stringify({
               current,
               latest,
               upToDate: false,
               installed: !stale,
               ...(messengersRefreshed === null ? {} : { messengersRefreshed }),
-              ...(stale ? { activeVersion: active, error: "active jeo still reports an older version" } : {}),
+              ...(stale
+                ? { activeVersion: active, error: "active jeo still reports an older version" }
+                : drift ? { error: settled.driftError } : {}),
+              ...sharedJson(settled),
             }));
-            if (stale) process.exitCode = 1;
+            if (stale || drift) process.exitCode = 1;
           } else if (stale) {
             console.error(`[FAILED] Installed jeo-code@${latest}, but the active 'jeo' on PATH still reports ${active}.`);
             console.error(`The install landed in a prefix your PATH does not use. Fix it with one of:`);
             console.error(`  bun install -g jeo-code@${latest} --force`);
             console.error(`  npm install -g jeo-code@${latest}`);
             console.error(`Then confirm with: jeo --version`);
+            if (drift) printSharedDrift(settled, latest, true);
+            process.exitCode = 1;
+          } else if (drift) {
+            printSharedDrift(settled, latest, true);
             process.exitCode = 1;
           } else {
             console.log(`Successfully installed jeo-code@${latest}`);
+            if (settled.summary) console.log(settled.summary);
             deps.refreshMessengers?.(false);
             deps.showWhatsNew?.();
           }
@@ -363,17 +588,24 @@ export async function runUpdateCommandWith(args: string[], deps: UpdateDeps): Pr
           const recovered = deps.activeVersion?.();
           if (recovered && latest && compareVersions(recovered, latest) >= 0) {
             if (hasJson) {
-              const messengersRefreshed = deps.refreshMessengers?.(true) ?? null;
+              const messengersRefreshed = drift ? null : (deps.refreshMessengers?.(true) ?? null);
               console.log(JSON.stringify({
                 current,
                 latest,
                 upToDate: false,
                 installed: true,
                 recovered: true,
-                ...(messengersRefreshed === null ? {} : { messengersRefreshed })
+                ...(messengersRefreshed === null ? {} : { messengersRefreshed }),
+                ...(drift ? { error: settled.driftError } : {}),
+                ...sharedJson(settled),
               }));
+              if (drift) process.exitCode = 1;
+            } else if (drift) {
+              printSharedDrift(settled, latest, true);
+              process.exitCode = 1;
             } else {
               console.log(`Successfully installed jeo-code@${latest} (package manager reported an error, but the runtime verified clean).`);
+              if (settled.summary) console.log(settled.summary);
               deps.refreshMessengers?.(false);
               deps.showWhatsNew?.();
             }
@@ -384,26 +616,35 @@ export async function runUpdateCommandWith(args: string[], deps: UpdateDeps): Pr
                 latest,
                 upToDate: false,
                 installed: false,
-                error: "Installation failed"
+                error: "Installation failed",
+                ...sharedJson(settled),
               }));
             } else {
               console.error("Failed to install update.");
+              if (result.manual && result.manual.length > 0) {
+                console.error("Try manually:");
+                for (const line of result.manual) console.error(`  ${line}`);
+              }
+              if (drift) printSharedDrift(settled, latest, false);
             }
             process.exitCode = 1;
           }
         }
-      } catch (installErr: any) {
-        const installErrMsg = installErr.message || String(installErr);
+      } catch (installErr) {
+        settled ??= settleShared(shared);
+        const installErrMsg = errorText(installErr);
         if (hasJson) {
           console.log(JSON.stringify({
             current,
             latest,
             upToDate: false,
             installed: false,
-            error: `Installation error: ${installErrMsg}`
+            error: `Installation error: ${installErrMsg}`,
+            ...sharedJson(settled),
           }));
         } else {
           console.error(`Failed to install update: ${installErrMsg}`);
+          if (settled.changes.length > 0) printSharedDrift(settled, latest, false);
         }
         process.exitCode = 1;
       }
@@ -454,5 +695,6 @@ function printUsage() {
   console.log("                      (e.g. --version 1.2.3); combine with --install to apply it");
   console.log("  --json       Output result in JSON format");
   console.log("  --strict     Exit with code 1 on network/registry errors");
+  console.log("  --allow-unlocked-global  Proceed even if the shared bun global bun.lock does not cover its other packages (drift is still reported)");
   console.log("  -h, --help   Show this help message");
 }