fix(cli): explain how npm users update the t3 command

apps/server/src/cli/invocation.ts

@@ -49,22 +49,24 @@ const decodeInstallManifest = Schema.decodeUnknownEffect(Schema.fromJsonString(I
  * `T3CODE_NPM_LAUNCHER_PATH` is inherited by child shells, so accept it only for this package
  * version to avoid claiming another `t3` invocation is the npm install.
  */
-export const resolveEntryPath = Effect.gen(function* () {
+export const resolveNpmLauncherPath = Effect.gen(function* () {
   const npmLauncher = (yield* HostProcess.Environment).T3CODE_NPM_LAUNCHER_PATH?.trim();
-  if (npmLauncher) {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const manifest = yield* fs
-      .readFileString(path.join(path.dirname(npmLauncher), "../package.json"))
-      .pipe(Effect.flatMap(decodeInstallManifest), Effect.option);
-    if (
-      Option.isSome(manifest) &&
-      manifest.value.name === "t3" &&
-      manifest.value.version === packageJson.version
-    ) {
-      return npmLauncher;
-    }
-  }
+  if (!npmLauncher) return Option.none<string>();
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const manifest = yield* fs
+    .readFileString(path.join(path.dirname(npmLauncher), "../package.json"))
+    .pipe(Effect.flatMap(decodeInstallManifest), Effect.option);
+  return Option.isSome(manifest) &&
+    manifest.value.name === "t3" &&
+    manifest.value.version === packageJson.version
+    ? Option.some(npmLauncher)
+    : Option.none<string>();
+});
+
+export const resolveEntryPath = Effect.gen(function* () {
+  const npmLauncher = yield* resolveNpmLauncherPath;
+  if (Option.isSome(npmLauncher)) return npmLauncher.value;
   if (yield* HostProcess.IsExecutable) return yield* HostProcess.ExecutablePath;
   return (yield* HostProcess.Arguments)[1] ?? "";
 });
@@ -153,6 +155,25 @@ export const resolveCliCommand = (subcommand: string) =>
 const shellWord = (value: string) =>
   /^[\w@%+=:,./-]+$/.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
 
+/** The npm launcher starts the runtime named by its package version, so only the package manager moves it. */
+export function packageUpdateCommand(
+  installation: ServerInstallation,
+  version: string,
+): string | null {
+  const spec = `t3@${version}`;
+  switch (installation.kind) {
+    case "npm-global":
+      return `npm install --global --prefix ${shellWord(installation.prefix)} ${spec}`;
+    case "pnpm-dlx":
+      return `pnpm dlx ${spec}`;
+    case "npx":
+    case "bunx":
+      return `${installation.kind} ${spec}`;
+    case "t3-launcher":
+      return null;
+  }
+}
+
 /** PowerShell also treats typographic quotes as delimiters; escape them and suppress expansion. */
 const powershellWord = (value: string) =>
   `"${value

apps/server/src/cli/update.test.ts

@@ -607,3 +607,135 @@ it.layer(NodeServices.layer)("t3 update with a background service", (it) => {
     ),
   );
 });
+
+it.layer(NodeServices.layer)("t3 update closing hint", (it) => {
+  it.effect("tells npm users how to move the t3 their package still pins", () =>
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-update-" });
+      const baseDir = path.join(root, "home");
+      const prefix = path.join(root, "node");
+      const npmGlobal = path.join(prefix, "lib/node_modules/t3/bin/t3.mjs");
+      const npx = path.join(root, ".npm/_npx/abc/node_modules/t3/bin/t3.mjs");
+      const projectLocal = path.join(root, "project/node_modules/t3/bin/t3.mjs");
+      for (const launcher of [npmGlobal, npx, projectLocal]) {
+        yield* fs.makeDirectory(path.dirname(launcher), { recursive: true });
+        yield* fs.writeFileString(launcher, "");
+        yield* fs.writeFileString(
+          path.join(path.dirname(launcher), "../package.json"),
+          `{"name":"t3","version":"${packageJson.version}","bin":{"t3":"./bin/t3.mjs"}}`,
+        );
+      }
+      yield* fs.makeDirectory(path.join(prefix, "bin"));
+      const platform = yield* HostProcess.Platform;
+      if (platform !== "win32") yield* fs.symlink(npmGlobal, path.join(prefix, "bin/t3"));
+      const realPrefix = yield* fs.realPath(prefix);
+      // Cached runtimes avoid network downloads; the runner below validates their version.
+      const entryFor = (version: string) =>
+        path.join(baseDir, "runtime/versions", version, platform === "win32" ? "t3.exe" : "t3");
+      for (const version of ["9.9.9", packageJson.version]) {
+        yield* fs.makeDirectory(path.dirname(entryFor(version)), { recursive: true });
+        yield* fs.writeFileString(entryFor(version), "");
+        yield* fs.writeFileString(
+          path.join(path.dirname(entryFor(version)), ".install-complete"),
+          version,
+        );
+      }
+
+      const update = (
+        version: string,
+        launcher: string | undefined,
+        status: BootService.BootServiceStatus,
+      ) => {
+        const service = Layer.mock(BootService.BootService, {
+          status: Effect.succeed(status),
+          install: () =>
+            Effect.succeed({
+              program: [entryFor(version), "__service-launcher"],
+              baseDir,
+              unitPath: status.unitPath,
+              logPath: status.logPath,
+            }),
+        });
+        vi.spyOn(BootService, "layer").mockReturnValue(service);
+        const runner = ProcessRunner.ProcessRunner.of({
+          run: (input) => {
+            assert.equal(input.command, entryFor(version));
+            assert.deepStrictEqual(input.args, ["--version"]);
+            return unrelatedLsof
+              .run(input)
+              .pipe(Effect.map((result) => ({ ...result, stdout: `t3 v${version}\n` })));
+          },
+        });
+        return runUpdate({
+          baseDir,
+          logsDir: baseDir,
+          serverRuntimeStatePath: path.join(baseDir, "server-runtime.json"),
+          channel: undefined,
+          requestedVersion: version,
+          allowDowngrade: false,
+          assumeYes: true,
+        }).pipe(
+          Effect.andThen(TestConsole.logLines),
+          Effect.map((lines) => lines.join("\n")),
+          Effect.provideService(
+            HostProcess.Environment,
+            launcher === undefined ? {} : { T3CODE_NPM_LAUNCHER_PATH: launcher },
+          ),
+          Effect.provideService(HostProcess.IsExecutable, false),
+          Effect.provideService(HostProcess.Arguments, ["node", path.join(root, "missing.mjs")]),
+          Effect.provideService(HostProcess.HomeDirectory, root),
+          Effect.provide(
+            Layer.mergeAll(
+              service,
+              Layer.succeed(ProcessRunner.ProcessRunner, runner),
+              ManagedPolicy.layerTest(),
+              Layer.succeed(
+                HttpClient.HttpClient,
+                HttpClient.make(() => Effect.die("unexpected release lookup")),
+              ),
+              Layer.fresh(TestConsole.layer),
+            ),
+          ),
+        );
+      };
+      const noService = {
+        supported: true,
+        installed: false,
+        current: false,
+        unitPath: path.join(root, "t3code.service"),
+        logPath: path.join(root, "boot-service.log"),
+      } as const;
+      const stillRuns = `The t3 npm package still runs ${packageJson.version}.`;
+
+      for (const [launcher, expected] of [
+        [
+          npmGlobal,
+          platform === "win32"
+            ? `${stillRuns} Update it to t3@9.9.9 with the package manager that installed it.`
+            : `${stillRuns} Run \`npm install --global --prefix ${realPrefix} t3@9.9.9\` to move to 9.9.9.`,
+        ],
+        [npx, `${stillRuns} Run \`npx t3@9.9.9\` to move to 9.9.9.`],
+        [
+          projectLocal,
+          `${stillRuns} Update it to t3@9.9.9 with the package manager that installed it.`,
+        ],
+        [undefined, `Run ${entryFor("9.9.9")}\n`],
+      ] as const) {
+        const output = yield* update("9.9.9", launcher, noService);
+        assert.include(output, `  ${expected}`, launcher ?? "standalone");
+      }
+
+      // Updating only the service to the package's own version needs no package update.
+      const output = yield* update(packageJson.version, npmGlobal, {
+        ...noService,
+        installed: true,
+        installedVersion: "0.0.1",
+        installedBaseDir: baseDir,
+      });
+      assert.include(output, `  Run ${entryFor(packageJson.version)}\n`);
+      assert.notInclude(output, stillRuns);
+    }).pipe(Effect.scoped),
+  );
+});

apps/server/src/cli/update.ts

@@ -43,6 +43,11 @@ import { managedUpdateMirror, managedUpdateRefusal } from "../policy/managedUpda
 import * as ProcessRunner from "../processRunner.ts";
 import { isProcessAlive, readPersistedServerRuntimeState } from "../serverRuntimeState.ts";
 import { projectLocationFlags, resolveCliAuthConfig } from "./config.ts";
+import {
+  packageUpdateCommand,
+  resolveNpmLauncherPath,
+  resolveServerInstallation,
+} from "./invocation.ts";
 import { createUpdateProgress } from "./updateProgress.ts";
 import * as CliService from "./service.ts";
 
@@ -224,6 +229,27 @@ export const findWindowsShim = Effect.fn("cli.update.find_windows_shim")(functio
   return undefined;
 });
 
+/** npm's `t3` keeps starting the runtime its package version names, not the one just downloaded. */
+const resolveNextStep = Effect.fn("cli.update.resolve_next_step")(function* (input: {
+  readonly repointed: boolean;
+  readonly entryPath: string;
+  readonly targetVersion: string;
+}) {
+  if (input.repointed) return "Run t3 to get started.";
+  if (input.targetVersion === packageJson.version) return `Run ${input.entryPath}`;
+  const stillRuns = `The t3 npm package still runs ${packageJson.version}.`;
+  const installation = yield* resolveServerInstallation;
+  const command =
+    installation === null ? null : packageUpdateCommand(installation, input.targetVersion);
+  if (command !== null) {
+    return `${stillRuns} Run \`${command}\` to move to ${input.targetVersion}.`;
+  }
+  if (Option.isSome(yield* resolveNpmLauncherPath)) {
+    return `${stillRuns} Update it to t3@${input.targetVersion} with the package manager that installed it.`;
+  }
+  return `Run ${input.entryPath}`;
+});
+
 const updateFlags = {
   ...projectLocationFlags,
   channel: Flag.Literals("channel", CLI_RELEASE_CHANNELS).pipe(
@@ -571,11 +597,12 @@ export const runUpdate = Effect.fn("cli.update.run")(function* (input: {
   }
 
   progress.success(`Installed T3 Code ${targetVersion}`);
-  if (Option.isSome(repointed)) {
-    yield* Console.log("  Run t3 to get started.\n");
-  } else {
-    yield* Console.log(`  Run ${runtime.entryPath}\n`);
-  }
+  const nextStep = yield* resolveNextStep({
+    repointed: Option.isSome(repointed),
+    entryPath: runtime.entryPath,
+    targetVersion,
+  });
+  yield* Console.log(`  ${nextStep}\n`);
   if (servicePlan?.handedOff === true) {
     yield* Console.log(
       `  Background service switching to ${targetVersion} outside this session, since this session runs inside it and disconnects when it restarts. Result: ${servicePlan.logPath}`,