@mutmutco/installer-launcher 1.2.5 → 1.3.1

package/README.md

@@ -21,6 +21,7 @@ launcher status [--json]                            read-only: launcher, payload
 launcher doctor                                     launcher report (no network), then the payload's doctor
 launcher autoupdate on|off|status                   hourly per-user schedule (hidden via wscript on Windows)
 launcher <verb> [args…]                             forwarded untouched when payload.json declares it
+launcher [-p …|--model …]                           no verb: starts the product's session; leading flags the launcher does not own pass through
 launcher --run <file> [args…]                       run a payload ESM file with the launcher's own runtime
 launcher --version                                  `<bin> <payload version> (launcher <version>)`
 ```
@@ -244,7 +245,7 @@ atomically only after convergence succeeds. On failure or interrupted startup it
 consumer rollback before allowing another install or forwarding. Failed rollback stays pending.
 A crash after shared commit completes the receipt instead of reverting the committed product.
 Host registration is not atomic: failures can leave host references to retained candidates.
-Candidates are deliberately retained until product-owned reference evidence can permit cleanup.
+After a committed promotion the launcher removes candidate folders `state.json` no longer references (the active one is kept; symlinks and junctions are skipped; a failed delete is logged). A failed activation keeps its candidate.
 An orphan lock-recovery guard fails closed and needs operator diagnosis.
 
 For already-shipped old launchers, copy the exact file exported by

package/dist/launcher.js

@@ -6,7 +6,7 @@ import { randomUUID as randomUUID4 } from "node:crypto";
 
 // src/acquisition.ts
 import { createHash as createHash3, randomUUID as randomUUID3 } from "node:crypto";
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4, unlinkSync, realpathSync as realpathSync2 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4, unlinkSync, realpathSync as realpathSync2, readdirSync, lstatSync, rmSync as rmSync4 } from "node:fs";
 import { join as join4, resolve, relative as relative2, isAbsolute as isAbsolute2, dirname as dirname2 } from "node:path";
 
 // src/runtime.ts
@@ -617,6 +617,28 @@ async function recoverAcquisition(dir, run2, env) {
   else if (existsSync5(statePath(dir))) unlinkSync(statePath(dir));
   unlinkSync(pendingPath(dir));
 }
+function reapCandidates(dir) {
+  const keep = readState(dir)?.acquired?.candidate;
+  if (!keep) return;
+  const base = join4(dir, "candidates");
+  let names;
+  try {
+    names = readdirSync(base);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (name === keep || !/^[a-zA-Z0-9_-]+$/.test(name)) continue;
+    try {
+      const path = join4(base, name);
+      const info = lstatSync(path);
+      if (!info.isDirectory() || info.isSymbolicLink()) continue;
+      rmSync4(path, { recursive: true, force: true });
+    } catch (error) {
+      console.error(`launcher: could not remove old candidate ${name}: ${error.message}`);
+    }
+  }
+}
 async function installAcquisition(dir, candidate, version, acquisition, options) {
   if (!acquisition.platforms.includes(`${process.platform}-${process.arch}`)) throw new Error("this product does not support this platform");
   const root = candidateRoot(dir, candidate);
@@ -673,13 +695,14 @@ async function installAcquisition(dir, candidate, version, acquisition, options)
     throw error;
   }
   unlinkSync(pendingPath(dir));
+  reapCandidates(dir);
 }
 
 // src/index.ts
 import { spawn as spawn2, spawnSync as spawnSync4 } from "node:child_process";
-import { existsSync as existsSync8, readFileSync as readFileSync8, statSync, mkdtempSync as mkdtempSync2, unlinkSync as unlinkSync2, rmdirSync, mkdirSync as mkdirSync6, renameSync as renameSync5, rmSync as rmSync6, writeFileSync as writeFileSync8 } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync8, statSync as statSync2, mkdtempSync as mkdtempSync2, unlinkSync as unlinkSync2, rmdirSync, mkdirSync as mkdirSync6, renameSync as renameSync5, rmSync as rmSync7, writeFileSync as writeFileSync8 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
-import { dirname as dirname4, join as join7, resolve as resolve2 } from "node:path";
+import { dirname as dirname4, join as join7, resolve as resolve3 } from "node:path";
 import { isSea } from "node:sea";
 import { fileURLToPath, pathToFileURL as pathToFileURL2 } from "node:url";
 
@@ -1554,7 +1577,7 @@ var rowTitle = (row) => `${row.surface}${row.aspect ? ` ${row.aspect}` : ""}${ro
 
 // src/autoupdate.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync6, rmSync as rmSync4, writeFileSync as writeFileSync6 } from "node:fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync6, rmSync as rmSync5, writeFileSync as writeFileSync6 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
 import { join as join5 } from "node:path";
 function schedulePlatform(override) {
@@ -1649,20 +1672,20 @@ function disableSchedule(config, options = {}) {
     if (result.code !== 0 && !/cannot find|does not exist/i.test(`${result.stdout} ${result.stderr}`)) {
       throw new Error(`Could not turn auto-update off: ${firstLine(result.stdout || result.stderr) || `exit ${result.code}`}`);
     }
-    rmSync4(join5(options.stateDir ?? defaultProductDir(config.product), HIDDEN_SCRIPT), { force: true });
+    rmSync5(join5(options.stateDir ?? defaultProductDir(config.product), HIDDEN_SCRIPT), { force: true });
     return;
   }
   if (platform === "darwin") {
     const label2 = scheduleLabel(config);
     exec("launchctl", ["bootout", `gui/${process.getuid?.() ?? 501}/${label2}`]);
-    rmSync4(join5(home, "Library", "LaunchAgents", `${label2}.plist`), { force: true });
+    rmSync5(join5(home, "Library", "LaunchAgents", `${label2}.plist`), { force: true });
     return;
   }
   const label = scheduleLabel(config);
   const dir = join5(home, ".config", "systemd", "user");
   exec("systemctl", ["--user", "disable", "--now", `${label}.timer`]);
-  rmSync4(join5(dir, `${label}.service`), { force: true });
-  rmSync4(join5(dir, `${label}.timer`), { force: true });
+  rmSync5(join5(dir, `${label}.service`), { force: true });
+  rmSync5(join5(dir, `${label}.timer`), { force: true });
 }
 function querySchedule(config, options = {}) {
   const platform = schedulePlatform(options.platform);
@@ -1744,7 +1767,7 @@ function firstLine(text) {
 
 // src/login-github.ts
 import { spawn, spawnSync as spawnSync3 } from "node:child_process";
-var realSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+var realSleep = (ms) => new Promise((resolve4) => setTimeout(resolve4, ms));
 function openBrowser(url) {
   if (process.env.LAUNCHER_NO_OPEN === "1") return;
   const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
@@ -1898,7 +1921,7 @@ async function loginGoogle(options) {
   const server = options.host.replace(/\/+$/, "");
   const timeoutMs = options.timeoutMs ?? 5 * 6e4;
   const listener = createServer();
-  await new Promise((resolve3) => listener.listen(0, "127.0.0.1", resolve3));
+  await new Promise((resolve4) => listener.listen(0, "127.0.0.1", resolve4));
   const port = listener.address().port;
   const redirectUri = `http://127.0.0.1:${port}/callback`;
   try {
@@ -1925,7 +1948,7 @@ async function loginGoogle(options) {
       code_challenge: challenge,
       code_challenge_method: "S256"
     }).toString();
-    const code = await new Promise((resolve3, reject) => {
+    const code = await new Promise((resolve4, reject) => {
       const timer = setTimeout(() => reject(new Error("sign-in timed out \u2014 run login again.")), timeoutMs);
       listener.on("request", (req, res) => {
         const url = new URL(req.url ?? "/", redirectUri);
@@ -1943,7 +1966,7 @@ async function loginGoogle(options) {
         }
         res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page("Signed in.", "You can close this tab and go back to the terminal."));
         clearTimeout(timer);
-        resolve3(received);
+        resolve4(received);
       });
       const print = options.print ?? ((line) => process.stderr.write(`${line}
 `));
@@ -2041,9 +2064,9 @@ async function ensureFreshToken(config, dir, fetchImpl = fetch) {
 
 // src/refresh.ts
 import { execFile } from "node:child_process";
-import { chmodSync, existsSync as existsSync7, lstatSync, readdirSync, readFileSync as readFileSync7, renameSync as renameSync4, rmSync as rmSync5, writeFileSync as writeFileSync7 } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync as existsSync7, lstatSync as lstatSync2, readdirSync as readdirSync2, readFileSync as readFileSync7, realpathSync as realpathSync3, renameSync as renameSync4, rmSync as rmSync6, statSync, writeFileSync as writeFileSync7 } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname as dirname3, join as join6 } from "node:path";
+import { basename, dirname as dirname3, join as join6, resolve as resolve2 } from "node:path";
 var LAUNCHER_RECORD_FILE = "launcher.json";
 var RECORD_TIMEOUT_MS = 1e4;
 function platformKey(platform, arch) {
@@ -2102,15 +2125,54 @@ function recordedPath(productDir) {
 function installedPath(target, productDir, platform) {
   return platform === "win32" ? join6(productDir, "bin", `${target.bin}.exe`) : join6(homedir(), ".local", "bin", target.bin);
 }
+function onPath(bin, platform, env) {
+  const win = platform === "win32";
+  const read = (name) => env[name] ?? env[Object.keys(env).find((key) => key.toLowerCase() === name.toLowerCase()) ?? ""];
+  const exts = win ? ["", ...(read("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""];
+  const found = [];
+  for (const dir of (read("PATH") ?? "").split(win ? ";" : ":").filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = join6(dir.replace(/^"|"$/gu, ""), `${bin}${ext}`);
+      try {
+        if (!statSync(candidate).isFile()) continue;
+        if (!win) accessSync(candidate, constants.X_OK);
+        found.push(candidate);
+      } catch {
+      }
+    }
+  }
+  return found;
+}
+function findPathShadow(bin, file, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const same = (a, b) => {
+    const real = (path) => {
+      try {
+        return realpathSync3(path);
+      } catch {
+        return resolve2(path);
+      }
+    };
+    const [x, y] = [real(a), real(b)];
+    return platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y;
+  };
+  const hits = onPath(bin, platform, options.env ?? process.env);
+  const other = hits.find((hit) => !same(hit, file));
+  if (!other) return null;
+  if (hits.findIndex((hit) => same(hit, file)) === 0) {
+    return { state: "shadowing", other, line: `Warning: ${file} shadows another ${bin} on PATH: ${other}.` };
+  }
+  return { state: "shadowed", other, line: `Warning: ${file} is shadowed by another ${bin} earlier on PATH: ${other}.` };
+}
 function parseLauncherVersion(stdout, bin) {
   const text = String(stdout).trim();
   if (!text.startsWith(`${bin} `)) return null;
   return text.match(/launcher (\d+\.\d+\.\d+[^\s)]*)/u)?.[1] ?? null;
 }
 function runVersion(path, bin) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     execFile(path, ["--version"], { timeout: 3e4, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
-      resolve3(error ? null : parseLauncherVersion(stdout, bin));
+      resolve4(error ? null : parseLauncherVersion(stdout, bin));
     });
   });
 }
@@ -2118,14 +2180,14 @@ function removeStale(file) {
   const prefix = `${basename(file)}.old-`;
   let names;
   try {
-    names = readdirSync(dirname3(file));
+    names = readdirSync2(dirname3(file));
   } catch {
     return;
   }
   for (const name of names) {
     if (!name.startsWith(prefix)) continue;
     try {
-      rmSync5(join6(dirname3(file), name), { force: true });
+      rmSync6(join6(dirname3(file), name), { force: true });
     } catch {
     }
   }
@@ -2138,11 +2200,12 @@ async function refreshLauncher(target, options = {}) {
   const productDir = options.productDir ?? defaultProductDir(target.product);
   const recorded = recordedPath(productDir);
   const file = options.path ?? (recorded && existsSync7(recorded) ? recorded : installedPath(target, productDir, platform));
-  if (!existsSync7(file) || lstatSync(file).isSymbolicLink()) return null;
+  if (!existsSync7(file) || lstatSync2(file).isSymbolicLink()) return null;
   if (!options.dryRun) removeStale(file);
   const from = await (options.readVersion ?? ((path) => runVersion(path, target.bin)))(file);
   if (!from) return null;
-  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail, durationMs: Date.now() - started });
+  const shadow = findPathShadow(target.bin, file, { platform, ...options.env ? { env: options.env } : {} });
+  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail: [detail, shadow?.line].filter(Boolean).join(" "), durationMs: Date.now() - started });
   const record = await fetchRecord(target, options);
   if (record === "bad-signature") return arm("fail", from, "The launcher record failed its signature check.");
   const entry2 = record?.files.find((candidate) => candidate.path === key);
@@ -2186,7 +2249,7 @@ async function refreshLauncher(target, options = {}) {
         if (moved && !existsSync7(file)) renameSync4(moved, file);
       } catch {
       }
-      rmSync5(next, { force: true });
+      rmSync6(next, { force: true });
       return arm("fail", from, "The launcher could not be replaced.");
     }
     return arm("ok", record.version, "");
@@ -2196,7 +2259,7 @@ async function refreshLauncher(target, options = {}) {
 }
 
 // src/index.ts
-var LAUNCHER_VERSION = true ? "1.2.5" : readVersionFromPackage();
+var LAUNCHER_VERSION = true ? "1.3.1" : readVersionFromPackage();
 function defaultPrint(message) {
   process.stdout.write(`${message}
 `);
@@ -2246,7 +2309,13 @@ function parseArgv(argv2) {
       parsed.run = { file: argv2[i + 1], args: argv2.slice(i + 2) };
       return parsed;
     }
-    i = skip(i);
+    const next = flag(i);
+    if (next < 0) {
+      parsed.unknownFlag ??= argv2[i];
+      parsed.forward = argv2.slice(i);
+      return parsed;
+    }
+    i = next;
   }
   parsed.command = argv2[i];
   if (parsed.command === void 0) return parsed;
@@ -2302,12 +2371,19 @@ async function run(rawOptions = {}) {
   const dir = resolveProductDir(config.product, rawOptions.dir ?? parsed.flags.dir);
   const ui = screensFor(faceProduct(config), config.binName, render, rawOptions);
   if ((parsed.command === "install" || parsed.command === "update") && !parsed.flags.version) recordSelf(dir);
+  const leadingForeign = parsed.forward !== void 0 && parsed.unknownFlag === parsed.forward[0] && !parsed.flags.help && !parsed.flags.version;
+  if (leadingForeign && entryFor(dir).target) {
+    return doForward(config, dir, rawOptions, void 0, parsed.forward, ui, () => void 0);
+  }
   if (parsed.unknownFlag) return ui.refuse(`Unknown option: ${parsed.unknownFlag}.`, `${ui.bin} --help`, 2);
   if (parsed.flags.version) {
     print(renderVersion(ui.bin, readState(dir)?.version ?? "not installed", LAUNCHER_VERSION));
     return 0;
   }
   const command2 = parsed.command;
+  if (!parsed.flags.help && command2 === void 0 && entryFor(dir).target) {
+    return doForward(config, dir, rawOptions, void 0, [], ui, () => void 0);
+  }
   if (parsed.flags.help || command2 === void 0) {
     ui.show(usage(config, dir, render));
     return parsed.flags.help ? 0 : 2;
@@ -2397,7 +2473,7 @@ async function runFile(file, args, printErr) {
     printErr("launcher --run needs a file to run.");
     return 1;
   }
-  const abs = resolve2(process.cwd(), file);
+  const abs = resolve3(process.cwd(), file);
   if (!existsSync8(abs)) {
     printErr(`cannot run ${file}: no such file.`);
     return 1;
@@ -2705,7 +2781,7 @@ async function installOrUpdateRun(config, dir, options, print, update, flags2, m
       }
       const target = join7(dir, "payload");
       mkdirSync6(dir, { recursive: true });
-      rmSync6(target, { recursive: true, force: true });
+      rmSync7(target, { recursive: true, force: true });
       renameSync5(join7(candidateDir, "payload"), target);
       writeState(dir, { version, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
       installer.phase("download", { seconds: (Date.now() - started) / 1e3 });
@@ -2753,7 +2829,7 @@ function payloadFileAsCommand(entry2, payload) {
   if (NEVER_A_PROGRAM.test(first)) return first;
   if (process.platform === "win32") return null;
   try {
-    return (statSync(candidate).mode & 73) === 0 ? first : null;
+    return (statSync2(candidate).mode & 73) === 0 ? first : null;
   } catch {
     return null;
   }
@@ -2828,7 +2904,7 @@ async function runInstallEntry(entry2, cwd, env, installer, tokens = null) {
   let progressError;
   const redact = (text) => secrets.reduce((safe, value) => safe.replaceAll(value, "[redacted]"), text);
   try {
-    const result = await new Promise((resolve3) => {
+    const result = await new Promise((resolve4) => {
       const child = spawn2(shell ? [command2, ...args].map(quoteForShell).join(" ") : command2, shell ? [] : args, {
         cwd,
         shell,
@@ -2885,8 +2961,8 @@ async function runInstallEntry(entry2, cwd, env, installer, tokens = null) {
         channel.setEncoding("utf8");
         channel.on("data", receive);
       }
-      child.on("error", (error) => resolve3({ ok: false, error: error.message }));
-      child.on("close", (code) => resolve3({
+      child.on("error", (error) => resolve4({ ok: false, error: error.message }));
+      child.on("close", (code) => resolve4({
         ok: code === 0,
         ...code !== null ? { code } : {},
         ...code !== 0 ? { error: `exit code ${code}` } : {}
@@ -2911,16 +2987,19 @@ function armState(arm) {
   if (arm.verdict === "skip") return "kept";
   return arm.from === arm.to ? "current" : "updated";
 }
+function entryFor(dir) {
+  const acquired = readState(dir)?.acquired;
+  return { acquired, target: acquired ? [acquired.node, acquired.entry] : readPayloadRun(dir) };
+}
 function doForward(config, dir, options, command2, rest, ui, unlock) {
-  if (existsSync8(command2)) {
+  if (command2 !== void 0 && existsSync8(command2)) {
     return ui.refuse(`${command2} is a file, not a command.`, `${ui.bin} --run ${command2}`, 2);
   }
-  const acquired = readState(dir)?.acquired;
-  const target = acquired ? [acquired.node, acquired.entry] : readPayloadRun(dir);
+  const { acquired, target } = entryFor(dir);
   const verbs = readPayloadVerbs(dir);
-  const declared = verbs === "*" || Array.isArray(verbs) && verbs.includes(command2);
+  const declared = command2 === void 0 || verbs === "*" || Array.isArray(verbs) && verbs.includes(command2);
   if (!target || !declared) return ui.refuse(`Unknown command: ${command2}.`, `${ui.bin} --help`, 2);
-  const forwarded = [...resolveEntry(target), command2, ...rest];
+  const forwarded = [...resolveEntry(target), ...command2 === void 0 ? [] : [command2], ...rest];
   const cwd = payloadDir(dir);
   const inherited = payloadEnv(dir);
   const env = acquired ? runtimeEnvironment(acquired.node, inherited ?? process.env) : inherited;
@@ -3019,6 +3098,8 @@ async function doStatus(config, dir, options, ui, print, json) {
 function doDoctor(config, dir, options, ui) {
   const local = localFacts(config, dir, options);
   const verdict = verdictFor(ui, local, false, `${ui.bin} status`);
+  const shadowFile = options.shadow?.file ?? (isSea() ? process.execPath : void 0);
+  const shadow = shadowFile ? findPathShadow(config.binName, shadowFile, options.shadow ?? {}) : null;
   ui.show(renderReport(ui.product, {
     rows: [
       { surface: "launcher", state: LAUNCHER_VERSION, mark: "ok" },
@@ -3027,7 +3108,7 @@ function doDoctor(config, dir, options, ui) {
       autoUpdateRow(local.schedule)
     ],
     // Paths belong in the receipt, never a row.
-    verdict: { ...verdict, facts: [`Folder: ${dir}`, `Release host: ${config.host}`] }
+    verdict: { ...verdict, facts: [`Folder: ${dir}`, `Release host: ${config.host}`, ...shadow ? [shadow.line] : []] }
   }, ui.render));
   const own = verdict.state === "fail" ? 1 : 0;
   const acquired = readState(dir)?.acquired;

package/dist/launcher.sea.cjs

@@ -650,6 +650,28 @@ async function recoverAcquisition(dir, run2, env) {
   else if ((0, import_node_fs5.existsSync)(statePath(dir))) (0, import_node_fs5.unlinkSync)(statePath(dir));
   (0, import_node_fs5.unlinkSync)(pendingPath(dir));
 }
+function reapCandidates(dir) {
+  const keep = readState(dir)?.acquired?.candidate;
+  if (!keep) return;
+  const base = (0, import_node_path4.join)(dir, "candidates");
+  let names;
+  try {
+    names = (0, import_node_fs5.readdirSync)(base);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (name === keep || !/^[a-zA-Z0-9_-]+$/.test(name)) continue;
+    try {
+      const path = (0, import_node_path4.join)(base, name);
+      const info = (0, import_node_fs5.lstatSync)(path);
+      if (!info.isDirectory() || info.isSymbolicLink()) continue;
+      (0, import_node_fs5.rmSync)(path, { recursive: true, force: true });
+    } catch (error) {
+      console.error(`launcher: could not remove old candidate ${name}: ${error.message}`);
+    }
+  }
+}
 async function installAcquisition(dir, candidate, version, acquisition, options) {
   if (!acquisition.platforms.includes(`${process.platform}-${process.arch}`)) throw new Error("this product does not support this platform");
   const root = candidateRoot(dir, candidate);
@@ -706,6 +728,7 @@ async function installAcquisition(dir, candidate, version, acquisition, options)
     throw error;
   }
   (0, import_node_fs5.unlinkSync)(pendingPath(dir));
+  reapCandidates(dir);
 }
 
 // src/index.ts
@@ -1777,7 +1800,7 @@ function firstLine(text) {
 
 // src/login-github.ts
 var import_node_child_process3 = require("node:child_process");
-var realSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+var realSleep = (ms) => new Promise((resolve4) => setTimeout(resolve4, ms));
 function openBrowser(url) {
   if (process.env.LAUNCHER_NO_OPEN === "1") return;
   const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
@@ -1931,7 +1954,7 @@ async function loginGoogle(options) {
   const server = options.host.replace(/\/+$/, "");
   const timeoutMs = options.timeoutMs ?? 5 * 6e4;
   const listener = (0, import_node_http.createServer)();
-  await new Promise((resolve3) => listener.listen(0, "127.0.0.1", resolve3));
+  await new Promise((resolve4) => listener.listen(0, "127.0.0.1", resolve4));
   const port = listener.address().port;
   const redirectUri = `http://127.0.0.1:${port}/callback`;
   try {
@@ -1958,7 +1981,7 @@ async function loginGoogle(options) {
       code_challenge: challenge,
       code_challenge_method: "S256"
     }).toString();
-    const code = await new Promise((resolve3, reject) => {
+    const code = await new Promise((resolve4, reject) => {
       const timer = setTimeout(() => reject(new Error("sign-in timed out \u2014 run login again.")), timeoutMs);
       listener.on("request", (req, res) => {
         const url = new URL(req.url ?? "/", redirectUri);
@@ -1976,7 +1999,7 @@ async function loginGoogle(options) {
         }
         res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page("Signed in.", "You can close this tab and go back to the terminal."));
         clearTimeout(timer);
-        resolve3(received);
+        resolve4(received);
       });
       const print = options.print ?? ((line) => process.stderr.write(`${line}
 `));
@@ -2135,15 +2158,54 @@ function recordedPath(productDir) {
 function installedPath(target, productDir, platform) {
   return platform === "win32" ? (0, import_node_path6.join)(productDir, "bin", `${target.bin}.exe`) : (0, import_node_path6.join)((0, import_node_os4.homedir)(), ".local", "bin", target.bin);
 }
+function onPath(bin, platform, env) {
+  const win = platform === "win32";
+  const read = (name) => env[name] ?? env[Object.keys(env).find((key) => key.toLowerCase() === name.toLowerCase()) ?? ""];
+  const exts = win ? ["", ...(read("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""];
+  const found = [];
+  for (const dir of (read("PATH") ?? "").split(win ? ";" : ":").filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = (0, import_node_path6.join)(dir.replace(/^"|"$/gu, ""), `${bin}${ext}`);
+      try {
+        if (!(0, import_node_fs11.statSync)(candidate).isFile()) continue;
+        if (!win) (0, import_node_fs11.accessSync)(candidate, import_node_fs11.constants.X_OK);
+        found.push(candidate);
+      } catch {
+      }
+    }
+  }
+  return found;
+}
+function findPathShadow(bin, file, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const same = (a, b) => {
+    const real = (path) => {
+      try {
+        return (0, import_node_fs11.realpathSync)(path);
+      } catch {
+        return (0, import_node_path6.resolve)(path);
+      }
+    };
+    const [x, y] = [real(a), real(b)];
+    return platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y;
+  };
+  const hits = onPath(bin, platform, options.env ?? process.env);
+  const other = hits.find((hit) => !same(hit, file));
+  if (!other) return null;
+  if (hits.findIndex((hit) => same(hit, file)) === 0) {
+    return { state: "shadowing", other, line: `Warning: ${file} shadows another ${bin} on PATH: ${other}.` };
+  }
+  return { state: "shadowed", other, line: `Warning: ${file} is shadowed by another ${bin} earlier on PATH: ${other}.` };
+}
 function parseLauncherVersion(stdout, bin) {
   const text = String(stdout).trim();
   if (!text.startsWith(`${bin} `)) return null;
   return text.match(/launcher (\d+\.\d+\.\d+[^\s)]*)/u)?.[1] ?? null;
 }
 function runVersion(path, bin) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     (0, import_node_child_process4.execFile)(path, ["--version"], { timeout: 3e4, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
-      resolve3(error ? null : parseLauncherVersion(stdout, bin));
+      resolve4(error ? null : parseLauncherVersion(stdout, bin));
     });
   });
 }
@@ -2175,7 +2237,8 @@ async function refreshLauncher(target, options = {}) {
   if (!options.dryRun) removeStale(file);
   const from = await (options.readVersion ?? ((path) => runVersion(path, target.bin)))(file);
   if (!from) return null;
-  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail, durationMs: Date.now() - started });
+  const shadow = findPathShadow(target.bin, file, { platform, ...options.env ? { env: options.env } : {} });
+  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail: [detail, shadow?.line].filter(Boolean).join(" "), durationMs: Date.now() - started });
   const record = await fetchRecord(target, options);
   if (record === "bad-signature") return arm("fail", from, "The launcher record failed its signature check.");
   const entry2 = record?.files.find((candidate) => candidate.path === key);
@@ -2229,7 +2292,7 @@ async function refreshLauncher(target, options = {}) {
 }
 
 // src/index.ts
-var LAUNCHER_VERSION = true ? "1.2.5" : readVersionFromPackage();
+var LAUNCHER_VERSION = true ? "1.3.1" : readVersionFromPackage();
 function defaultPrint(message) {
   process.stdout.write(`${message}
 `);
@@ -2279,7 +2342,13 @@ function parseArgv(argv2) {
       parsed.run = { file: argv2[i + 1], args: argv2.slice(i + 2) };
       return parsed;
     }
-    i = skip(i);
+    const next = flag(i);
+    if (next < 0) {
+      parsed.unknownFlag ??= argv2[i];
+      parsed.forward = argv2.slice(i);
+      return parsed;
+    }
+    i = next;
   }
   parsed.command = argv2[i];
   if (parsed.command === void 0) return parsed;
@@ -2335,12 +2404,19 @@ async function run(rawOptions = {}) {
   const dir = resolveProductDir(config.product, rawOptions.dir ?? parsed.flags.dir);
   const ui = screensFor(faceProduct(config), config.binName, render, rawOptions);
   if ((parsed.command === "install" || parsed.command === "update") && !parsed.flags.version) recordSelf(dir);
+  const leadingForeign = parsed.forward !== void 0 && parsed.unknownFlag === parsed.forward[0] && !parsed.flags.help && !parsed.flags.version;
+  if (leadingForeign && entryFor(dir).target) {
+    return doForward(config, dir, rawOptions, void 0, parsed.forward, ui, () => void 0);
+  }
   if (parsed.unknownFlag) return ui.refuse(`Unknown option: ${parsed.unknownFlag}.`, `${ui.bin} --help`, 2);
   if (parsed.flags.version) {
     print(renderVersion(ui.bin, readState(dir)?.version ?? "not installed", LAUNCHER_VERSION));
     return 0;
   }
   const command2 = parsed.command;
+  if (!parsed.flags.help && command2 === void 0 && entryFor(dir).target) {
+    return doForward(config, dir, rawOptions, void 0, [], ui, () => void 0);
+  }
   if (parsed.flags.help || command2 === void 0) {
     ui.show(usage(config, dir, render));
     return parsed.flags.help ? 0 : 2;
@@ -2861,7 +2937,7 @@ async function runInstallEntry(entry2, cwd, env, installer, tokens = null) {
   let progressError;
   const redact = (text) => secrets.reduce((safe, value) => safe.replaceAll(value, "[redacted]"), text);
   try {
-    const result = await new Promise((resolve3) => {
+    const result = await new Promise((resolve4) => {
       const child = (0, import_node_child_process5.spawn)(shell ? [command2, ...args].map(quoteForShell).join(" ") : command2, shell ? [] : args, {
         cwd,
         shell,
@@ -2918,8 +2994,8 @@ async function runInstallEntry(entry2, cwd, env, installer, tokens = null) {
         channel.setEncoding("utf8");
         channel.on("data", receive);
       }
-      child.on("error", (error) => resolve3({ ok: false, error: error.message }));
-      child.on("close", (code) => resolve3({
+      child.on("error", (error) => resolve4({ ok: false, error: error.message }));
+      child.on("close", (code) => resolve4({
         ok: code === 0,
         ...code !== null ? { code } : {},
         ...code !== 0 ? { error: `exit code ${code}` } : {}
@@ -2944,16 +3020,19 @@ function armState(arm) {
   if (arm.verdict === "skip") return "kept";
   return arm.from === arm.to ? "current" : "updated";
 }
+function entryFor(dir) {
+  const acquired = readState(dir)?.acquired;
+  return { acquired, target: acquired ? [acquired.node, acquired.entry] : readPayloadRun(dir) };
+}
 function doForward(config, dir, options, command2, rest, ui, unlock) {
-  if ((0, import_node_fs12.existsSync)(command2)) {
+  if (command2 !== void 0 && (0, import_node_fs12.existsSync)(command2)) {
     return ui.refuse(`${command2} is a file, not a command.`, `${ui.bin} --run ${command2}`, 2);
   }
-  const acquired = readState(dir)?.acquired;
-  const target = acquired ? [acquired.node, acquired.entry] : readPayloadRun(dir);
+  const { acquired, target } = entryFor(dir);
   const verbs = readPayloadVerbs(dir);
-  const declared = verbs === "*" || Array.isArray(verbs) && verbs.includes(command2);
+  const declared = command2 === void 0 || verbs === "*" || Array.isArray(verbs) && verbs.includes(command2);
   if (!target || !declared) return ui.refuse(`Unknown command: ${command2}.`, `${ui.bin} --help`, 2);
-  const forwarded = [...resolveEntry(target), command2, ...rest];
+  const forwarded = [...resolveEntry(target), ...command2 === void 0 ? [] : [command2], ...rest];
   const cwd = payloadDir(dir);
   const inherited = payloadEnv(dir);
   const env = acquired ? runtimeEnvironment(acquired.node, inherited ?? process.env) : inherited;
@@ -3052,6 +3131,8 @@ async function doStatus(config, dir, options, ui, print, json) {
 function doDoctor(config, dir, options, ui) {
   const local = localFacts(config, dir, options);
   const verdict = verdictFor(ui, local, false, `${ui.bin} status`);
+  const shadowFile = options.shadow?.file ?? ((0, import_node_sea2.isSea)() ? process.execPath : void 0);
+  const shadow = shadowFile ? findPathShadow(config.binName, shadowFile, options.shadow ?? {}) : null;
   ui.show(renderReport(ui.product, {
     rows: [
       { surface: "launcher", state: LAUNCHER_VERSION, mark: "ok" },
@@ -3060,7 +3141,7 @@ function doDoctor(config, dir, options, ui) {
       autoUpdateRow(local.schedule)
     ],
     // Paths belong in the receipt, never a row.
-    verdict: { ...verdict, facts: [`Folder: ${dir}`, `Release host: ${config.host}`] }
+    verdict: { ...verdict, facts: [`Folder: ${dir}`, `Release host: ${config.host}`, ...shadow ? [shadow.line] : []] }
   }, ui.render));
   const own = verdict.state === "fail" ? 1 : 0;
   const acquired = readState(dir)?.acquired;

package/dist/refresh.js

@@ -1,12 +1,12 @@
 // src/refresh.ts
 import { execFile } from "node:child_process";
-import { chmodSync, existsSync as existsSync2, lstatSync, readdirSync, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync as existsSync2, lstatSync as lstatSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, realpathSync as realpathSync2, renameSync, rmSync as rmSync2, statSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname as dirname2, join as join3 } from "node:path";
+import { basename, dirname as dirname2, join as join3, resolve as resolve2 } from "node:path";
 
 // src/acquisition.ts
 import { createHash as createHash2, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, realpathSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, realpathSync, readdirSync, lstatSync, rmSync } from "node:fs";
 import { join as join2, resolve, relative, isAbsolute, dirname } from "node:path";
 
 // src/download.ts
@@ -235,15 +235,54 @@ function recordedPath(productDir) {
 function installedPath(target, productDir, platform) {
   return platform === "win32" ? join3(productDir, "bin", `${target.bin}.exe`) : join3(homedir(), ".local", "bin", target.bin);
 }
+function onPath(bin, platform, env) {
+  const win = platform === "win32";
+  const read = (name) => env[name] ?? env[Object.keys(env).find((key) => key.toLowerCase() === name.toLowerCase()) ?? ""];
+  const exts = win ? ["", ...(read("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""];
+  const found = [];
+  for (const dir of (read("PATH") ?? "").split(win ? ";" : ":").filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = join3(dir.replace(/^"|"$/gu, ""), `${bin}${ext}`);
+      try {
+        if (!statSync(candidate).isFile()) continue;
+        if (!win) accessSync(candidate, constants.X_OK);
+        found.push(candidate);
+      } catch {
+      }
+    }
+  }
+  return found;
+}
+function findPathShadow(bin, file, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const same = (a, b) => {
+    const real = (path) => {
+      try {
+        return realpathSync2(path);
+      } catch {
+        return resolve2(path);
+      }
+    };
+    const [x, y] = [real(a), real(b)];
+    return platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y;
+  };
+  const hits = onPath(bin, platform, options.env ?? process.env);
+  const other = hits.find((hit) => !same(hit, file));
+  if (!other) return null;
+  if (hits.findIndex((hit) => same(hit, file)) === 0) {
+    return { state: "shadowing", other, line: `Warning: ${file} shadows another ${bin} on PATH: ${other}.` };
+  }
+  return { state: "shadowed", other, line: `Warning: ${file} is shadowed by another ${bin} earlier on PATH: ${other}.` };
+}
 function parseLauncherVersion(stdout, bin) {
   const text = String(stdout).trim();
   if (!text.startsWith(`${bin} `)) return null;
   return text.match(/launcher (\d+\.\d+\.\d+[^\s)]*)/u)?.[1] ?? null;
 }
 function runVersion(path, bin) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     execFile(path, ["--version"], { timeout: 3e4, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
-      resolve2(error ? null : parseLauncherVersion(stdout, bin));
+      resolve3(error ? null : parseLauncherVersion(stdout, bin));
     });
   });
 }
@@ -251,14 +290,14 @@ function removeStale(file) {
   const prefix = `${basename(file)}.old-`;
   let names;
   try {
-    names = readdirSync(dirname2(file));
+    names = readdirSync2(dirname2(file));
   } catch {
     return;
   }
   for (const name of names) {
     if (!name.startsWith(prefix)) continue;
     try {
-      rmSync(join3(dirname2(file), name), { force: true });
+      rmSync2(join3(dirname2(file), name), { force: true });
     } catch {
     }
   }
@@ -271,11 +310,12 @@ async function refreshLauncher(target, options = {}) {
   const productDir = options.productDir ?? defaultProductDir(target.product);
   const recorded = recordedPath(productDir);
   const file = options.path ?? (recorded && existsSync2(recorded) ? recorded : installedPath(target, productDir, platform));
-  if (!existsSync2(file) || lstatSync(file).isSymbolicLink()) return null;
+  if (!existsSync2(file) || lstatSync2(file).isSymbolicLink()) return null;
   if (!options.dryRun) removeStale(file);
   const from = await (options.readVersion ?? ((path) => runVersion(path, target.bin)))(file);
   if (!from) return null;
-  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail, durationMs: Date.now() - started });
+  const shadow = findPathShadow(target.bin, file, { platform, ...options.env ? { env: options.env } : {} });
+  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail: [detail, shadow?.line].filter(Boolean).join(" "), durationMs: Date.now() - started });
   const record = await fetchRecord(target, options);
   if (record === "bad-signature") return arm("fail", from, "The launcher record failed its signature check.");
   const entry = record?.files.find((candidate) => candidate.path === key);
@@ -319,7 +359,7 @@ async function refreshLauncher(target, options = {}) {
         if (moved && !existsSync2(file)) renameSync(moved, file);
       } catch {
       }
-      rmSync(next, { force: true });
+      rmSync2(next, { force: true });
       return arm("fail", from, "The launcher could not be replaced.");
     }
     return arm("ok", record.version, "");
@@ -330,6 +370,7 @@ async function refreshLauncher(target, options = {}) {
 export {
   LAUNCHER_RECORD_FILE,
   compareVersions,
+  findPathShadow,
   parseLauncherVersion,
   readLauncherRecord,
   refreshLauncher

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/installer-launcher",
-  "version": "1.2.5",
+  "version": "1.3.1",
   "description": "Single-executable (SEA) launcher: sign-in, gated payload fetch, self-update. One copy ships per product.",
   "type": "module",
   "license": "UNLICENSED",