fix(npm): resolve latest bootstrap for upgrades

Author: morluto

npm/README.md

@@ -53,7 +53,7 @@ jacobian setup [--client <id>...] [--all] [--yes] [--dry-run] [--json]
                [--source <checkout> --state-dir <path> --profile <name>]
   Configure MCP clients to use Jacobian.
 jacobian upgrade
-  Refresh the launcher-managed Python package.
+  Resolve the latest npm bootstrap, then refresh the launcher-managed Python package.
 jacobian doctor [--json]
   Verify the MCP handshake and tool catalog.
 jacobian remove [--client <id>...] [--all] [--yes] [--json]
@@ -83,6 +83,8 @@ state initialization, source doctor, and client configuration workflow.
 - `JACOBIAN_STATE_DIR` — state directory (default: `./.jacobian`)
 - `JACOBIAN_PACKAGE` — Python package spec override (default: the Python package
   version matching the installed npm launcher)
+- `JACOBIAN_NPM_UPGRADE_HANDOFF` — internal one-time guard used while `upgrade`
+  resolves `jacobian@latest`
 - `JACOBIAN_DATA_DIR` — guided installer release data root
 - `JACOBIAN_BIN_DIR` — guided installer directory for the stable command
 

npm/bin/jacobian.cjs

@@ -3,6 +3,9 @@
 "use strict";
 
 const { stderr } = require("node:process");
+const { spawn } = require("node:child_process");
+
+const NPM_UPGRADE_HANDOFF = "JACOBIAN_NPM_UPGRADE_HANDOFF";
 
 /**
  * Jacobian CLI entry point.
@@ -58,6 +61,62 @@ function reportSetupFailure(error) {
   process.exitCode = 1;
 }
 
+/**
+ * Resolve the latest npm bootstrap before upgrading the managed Python package.
+ *
+ * An unqualified npx invocation can execute an older cached launcher. The
+ * handoff guard lets the latest package enter the pinned-runtime path once.
+ *
+ * @param {string[]} args
+ */
+function resolveLatestUpgrade(args) {
+  const executable =
+    process.env.JACOBIAN_NPX_EXECUTABLE ||
+    (process.platform === "win32" ? "npx.cmd" : "npx");
+  const child = spawn(
+    executable,
+    ["--yes", "--prefer-online", "jacobian@latest", "upgrade", ...args.slice(1)],
+    {
+      env: { ...process.env, [NPM_UPGRADE_HANDOFF]: "1" },
+      shell: process.platform === "win32",
+      stdio: "inherit",
+    },
+  );
+  const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+  const handlers = new Map(
+    signals.map((signal) => [
+      signal,
+      () => {
+        if (!child.killed) child.kill(signal);
+      },
+    ]),
+  );
+  for (const [signal, handler] of handlers) process.on(signal, handler);
+
+  const removeSignalHandlers = () => {
+    for (const [signal, handler] of handlers) {
+      process.removeListener(signal, handler);
+    }
+  };
+
+  child.once("error", (error) => {
+    removeSignalHandlers();
+    stderr.write(
+      `Jacobian could not resolve its latest npm bootstrap: ${error.message}\n` +
+        "Run `npx jacobian@latest upgrade` after checking that npx is available.\n",
+    );
+    process.exitCode = 1;
+  });
+  child.once("exit", (code, signal) => {
+    removeSignalHandlers();
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exitCode = code ?? 1;
+  });
+}
+
 function main() {
   const args = process.argv.slice(2);
   const command = args[0];
@@ -152,6 +211,13 @@ function main() {
   }
 
   if (command === "upgrade") {
+    if (process.env[NPM_UPGRADE_HANDOFF] !== "1") {
+      stderr.write(
+        "Resolving the latest Jacobian bootstrap before upgrading the managed Python runtime.\n",
+      );
+      resolveLatestUpgrade(args);
+      return;
+    }
     const { PACKAGE_SPEC, upgrade } = require("./launcher.cjs");
     try {
       upgrade();

npm/cli-e2e.test.mjs

@@ -237,6 +237,7 @@ if (process.argv[2] === "--version") {
 
       const result = await runNpx(tarball, ["upgrade"], base, {
         FAKE_UV_LOG: uvLog,
+        JACOBIAN_NPM_UPGRADE_HANDOFF: "1",
         JACOBIAN_PACKAGE: `jacobian==${packageMetadata.version}`,
         PATH: `${dirname(uv)}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`,
         XDG_DATA_HOME: xdgDataHome,
@@ -264,3 +265,38 @@ if (process.argv[2] === "--version") {
     }
   },
 );
+
+test(
+  "npx jacobian upgrade resolves the latest npm bootstrap before Python upgrade",
+  { skip: process.platform === "win32" },
+  async () => {
+    const base = await mkdtemp(join(tmpdir(), "jacobian-npx-upgrade-handoff-"));
+    try {
+      const tarball = await packNpmPackage(base);
+      const npx = join(base, "bin", "npx");
+      const handoffLog = join(base, "handoff.json");
+      await writeExecutable(
+        npx,
+        `#!/usr/bin/env node
+const fs = require("node:fs");
+fs.writeFileSync(process.env.JACOBIAN_HANDOFF_LOG, JSON.stringify({
+  args: process.argv.slice(2),
+  marker: process.env.JACOBIAN_NPM_UPGRADE_HANDOFF,
+}));
+`,
+      );
+
+      const result = await runNpx(tarball, ["upgrade", "--yes"], base, {
+        JACOBIAN_HANDOFF_LOG: handoffLog,
+        JACOBIAN_NPX_EXECUTABLE: npx,
+      });
+      assert.equal(result.status, 0, result.stderr);
+      assert.deepEqual(JSON.parse(await readFile(handoffLog, "utf8")), {
+        args: ["--yes", "--prefer-online", "jacobian@latest", "upgrade", "--yes"],
+        marker: "1",
+      });
+    } finally {
+      await rm(base, { recursive: true, force: true });
+    }
+  },
+);