skillrepo 3.1.1 → 3.1.3

package/src/lib/binary-locator.mjs

@@ -0,0 +1,126 @@
+/**
+ * Cross-platform binary locator with optional transient-runner
+ * filtering (#894 / v3.1.2, fixed in v3.1.3).
+ *
+ * ## v3.1.3 fix history
+ *
+ * v3.1.2 used `execFileSync("which" or "where", [name])` to find
+ * the binary. That broke under `npx`: POSIX `which` returns ONLY
+ * the FIRST match. The npx-launched process has the npx-cache bin
+ * dir at the front of PATH, so `which skillrepo` returns the npx
+ * cache copy. With `filterTransient: true`, we filter that out and
+ * return null — even though a stable global IS on PATH at a later
+ * entry. The user-visible symptom: `npm install -g skillrepo`
+ * succeeds, but `installSkillrepoGlobally`'s post-install
+ * verification reports "binary not found on PATH" and init shows
+ * the auto-install as failed when it actually worked.
+ *
+ * The fix: scan PATH directly in Node, returning the FIRST
+ * non-transient match. We see ALL candidates the way Windows
+ * `where.exe` does, so we can correctly reject transient cache
+ * paths in favor of stable global installs that appear later in
+ * PATH. No shell-out, faster, deterministic.
+ *
+ * ## Two flag knobs
+ *
+ *   - `skipIfTransient`: short-circuit to null if the CURRENT
+ *     process is itself a transient-runner invocation. Used by
+ *     callers that bake the resolved path into long-lived state
+ *     (e.g. a SessionStart hook command) when the running process
+ *     ITSELF can't supply a stable absolute path.
+ *
+ *   - `filterTransient`: ignore PATH entries that point inside a
+ *     transient runner's cache directory. Used by callers that
+ *     explicitly want a STABLE global install at a non-cache path
+ *     even when running under a transient runner (typically
+ *     post-`npm install -g`, looking for the just-installed
+ *     binary).
+ *
+ * Both flags default to false so the function behaves like a plain
+ * PATH lookup unless the caller opts into the extra semantics.
+ */
+
+import { existsSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
+import { platformConventions } from "./platform.mjs";
+import {
+  isTransientCachePath,
+  isTransientRunnerInvocation,
+} from "./transient-runners.mjs";
+
+/**
+ * Resolve the absolute path of `binaryName` on PATH.
+ *
+ * @param {string} binaryName - The bare command name (e.g.
+ *        `"skillrepo"`). On Windows we also probe for `<name>.cmd`
+ *        and `<name>.exe` since npm-installed CLIs land as `.cmd`
+ *        shims there.
+ * @param {object} [options]
+ * @param {boolean} [options.skipIfTransient=false] - When true,
+ *        return `null` immediately if the current process is itself
+ *        a transient-runner invocation.
+ * @param {boolean} [options.filterTransient=false] - When true,
+ *        ignore matches inside a transient runner's cache directory.
+ * @param {NodeJS.Platform} [options.platform] - Override for tests.
+ *        Production callers leave unset.
+ * @param {string} [options.path] - Override for tests. Defaults to
+ *        `process.env.PATH`. Tests use this to construct
+ *        deterministic PATH layouts (e.g. "an _npx cache entry
+ *        FIRST followed by a stable shim").
+ * @returns {string | null}
+ */
+export function resolveBinaryOnPath(
+  binaryName,
+  {
+    skipIfTransient = false,
+    filterTransient = false,
+    platform: platformOverride,
+    path: pathOverride,
+  } = {},
+) {
+  if (skipIfTransient && isTransientRunnerInvocation()) {
+    return null;
+  }
+
+  const conv = platformConventions({ platform: platformOverride });
+  const pathStr = pathOverride ?? process.env.PATH ?? "";
+  // Drop empty entries AND relative paths in one pass — relative
+  // PATH entries are meaningless for baking into a long-lived hook
+  // command (cwd-dependent), and empty entries (from `::` or a
+  // trailing delimiter) are no-ops we don't want to stat.
+  const dirs = pathStr
+    .split(delimiter)
+    .filter((d) => d && isAbsolute(d));
+
+  // On Windows, npm installs global CLIs as `<name>.cmd` shims
+  // (and very occasionally `<name>.exe` for native binaries).
+  // Order matters: `.cmd` is what npm always emits, so check it
+  // first to short-circuit the lookup. Bare `<name>` is included
+  // as a defensive fallback for unusual installer layouts (Git
+  // Bash on Windows, MSYS2, etc., where POSIX-style shims may
+  // accompany the .cmd ones).
+  // POSIX has no extension convention; the bare name suffices.
+  const candidates =
+    conv.family === "windows"
+      ? [`${binaryName}.cmd`, `${binaryName}.exe`, binaryName]
+      : [binaryName];
+
+  for (const dir of dirs) {
+    for (const name of candidates) {
+      const full = join(dir, name);
+      let exists;
+      try {
+        exists = existsSync(full);
+      } catch {
+        // Unreadable directory or transient FS error — treat as
+        // "not here" and move on. Without this guard a single
+        // bad PATH entry would crash the lookup.
+        continue;
+      }
+      if (!exists) continue;
+      if (filterTransient && isTransientCachePath(full)) continue;
+      return full;
+    }
+  }
+  return null;
+}

package/src/lib/cli-config.mjs

@@ -1,11 +1,6 @@
 /**
  * Shared credential + flag resolution for command modules.
  *
- * Also houses process-environment helpers that multiple command
- * modules need — specifically `isNpxInvocation()` which several
- * surfaces use to decide whether the user has a stable global
- * install or is running a transient npx download.
- *
  * Every command needs to:
  *   1. Resolve `--key`/`--url`/`--ide`/`--global`/`--json` flags
  *   2. Fall back to ~/.claude/skillrepo/config.json
@@ -13,9 +8,13 @@
  *   4. Hard-error with an actionable hint pointing at `init` if no
  *      key is configured
  *
- * Centralizing this here keeps the four command modules thin and
- * means a future change to credential resolution (e.g., adding a
- * keychain backend) is a single edit instead of four.
+ * Centralizing this here keeps the command modules thin and means
+ * a future change to credential resolution (e.g., adding a keychain
+ * backend) is a single edit instead of N.
+ *
+ * Process-environment helpers for transient package-runner detection
+ * (npx, pnpm dlx, yarn dlx, bunx) live in `lib/transient-runners.mjs`
+ * and `lib/binary-locator.mjs` — import from there directly.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -26,70 +25,6 @@ import { authError, validationError } from "./errors.mjs";
 const VALID_VENDORS = new Set(["claudeCode", "cursor", "windsurf", "vscode"]);
 const VENDOR_ALIASES = { claude: "claudeCode" };
 
-/**
- * True when the current process was launched via `npx skillrepo ...`
- * rather than from a stable global install.
- *
- * Why this matters:
- *
- *   - `npx skillrepo init` downloads the package into `~/.npm/_npx/<hash>/`
- *     and exposes its `.bin/skillrepo` on PATH for the subprocess only.
- *     `execFileSync("which", ["skillrepo"])` DOES find that path, but it
- *     is a transient cache location. npm eviction, a version bump, or
- *     `npm cache clean` later invalidates the absolute path, so any
- *     on-disk reference to it (e.g. a SessionStart hook command baked
- *     in at install time) silently breaks.
- *
- *   - The architect design for #884 explicitly specified that npx
- *     users should skip the session-sync step with a "requires a global
- *     install" warning. The `which`-based resolver in
- *     `mergers/session-hook.mjs` alone is too permissive — it finds the
- *     npx cache path and treats it as stable. This helper closes that
- *     gap by detecting npx unambiguously.
- *
- *   - `init`'s "Next steps" output also needs to know: under npx, the
- *     right hint is `npx skillrepo list` (or "install globally first"),
- *     not bare `skillrepo list` (which would fail for the user).
- *
- * Detection uses two signals, either one sufficient:
- *
- *   1. `process.argv[1]` contains `/_npx/` (or Windows `\_npx\`) —
- *      the primary signal. npx-launched scripts literally live inside
- *      `~/.npm/_npx/<hash>/node_modules/.bin/...` so the executable
- *      path itself names the cache directory. Highest reliability,
- *      no false-positive surface.
- *
- *   2. `process.env._` ends with `/npx` (or `\npx` on Windows) —
- *      legacy fallback for shells that set `_` to the launched
- *      command. Defensive against shim layouts where argv[1] has
- *      been symlinked through a path that doesn't contain `_npx`.
- *
- * Why NOT `process.env.npm_command === "exec"`: this signal was
- * considered but rejected in v3.1.1 review. `npm_command=exec` is
- * also set when a stable-install user runs `skillrepo init` from a
- * `package.json` lifecycle script (e.g. `"postinstall": "skillrepo
- * init --yes"`) or invokes `npm exec skillrepo ...` directly. In
- * those cases the user has a real global install and should NOT
- * have session-sync skipped or see `npx skillrepo` in Next Steps.
- * The argv[1] signal already catches real npx invocations
- * unambiguously; adding npm_command trades a minor coverage gain
- * (shim layouts) for a false-positive surface that affects real
- * users. See v3.1.1 PR review cycle for the full discussion.
- *
- * @returns {boolean}
- */
-export function isNpxInvocation() {
-  const execPath = process.argv[1] ?? "";
-  if (execPath.includes("/_npx/") || execPath.includes("\\_npx\\")) {
-    return true;
-  }
-  const underscore = process.env._ ?? "";
-  if (underscore.endsWith("/npx") || underscore.endsWith("\\npx")) {
-    return true;
-  }
-  return false;
-}
-
 /**
  * @typedef {Object} ResolvedFlags
  * @property {string} serverUrl

package/src/lib/cli-version.mjs

@@ -0,0 +1,56 @@
+/**
+ * Read the running CLI's own version from the package.json that ships
+ * with the tarball.
+ *
+ * Why a dedicated module
+ * ----------------------
+ * v3.1.2's init auto-install feature needs to run
+ * `npm install -g skillrepo@<version>` with the SAME version as the
+ * CLI currently running init. Pinning is what keeps the fresh global
+ * install in lockstep with the npx-cache copy that just executed init,
+ * so there's no silent version drift between the two.
+ *
+ * `process.env.npm_package_version` is NOT reliable here — it's only
+ * set when npm itself spawns the process (e.g. `npm run`), not under
+ * a plain `npx skillrepo ...` or `node ./bin/skillrepo.mjs` run. So
+ * we read the package.json off disk.
+ *
+ * The read is relative to `import.meta.url`, which resolves to this
+ * module's own file URL. From `src/lib/cli-version.mjs`, two levels
+ * up is the package root — the `"files"` array in package.json
+ * includes `bin/` and `src/` alongside the package.json itself, so
+ * the file is always present in the shipped tarball.
+ *
+ * A failed read is a programming error (missing or malformed
+ * package.json in a shipped tarball means the build pipeline broke
+ * invariants). The function throws rather than soft-handling; there
+ * is no meaningful user recovery path.
+ */
+
+import { readFileSync } from "node:fs";
+
+/**
+ * Return the CLI's own semver version as a string (e.g. "3.1.2").
+ *
+ * @returns {string}
+ * @throws {Error} if the package.json cannot be read or parsed, or
+ *         if the `version` field is missing or not a string.
+ */
+export function getCliVersion() {
+  // Resolve `../../package.json` relative to THIS file. This module
+  // lives at `packages/cli/src/lib/cli-version.mjs`, so two `..`
+  // segments land at the package root. Using `import.meta.url` means
+  // the resolution is invariant under tarball/symlink layout — it
+  // always points to where THIS source file actually lives on disk
+  // at runtime.
+  const pkgUrl = new URL("../../package.json", import.meta.url);
+  const raw = readFileSync(pkgUrl, "utf-8");
+  const pkg = JSON.parse(raw);
+  if (typeof pkg.version !== "string" || pkg.version.length === 0) {
+    throw new Error(
+      "cli-version: package.json has no valid `version` string. " +
+        "This indicates a broken build/publish pipeline.",
+    );
+  }
+  return pkg.version;
+}

package/src/lib/global-install.mjs

@@ -0,0 +1,386 @@
+/**
+ * `npm install -g skillrepo@<version>` wrapper for v3.1.2 init's
+ * auto-install-global feature (#894).
+ *
+ * Why this exists
+ * ---------------
+ * Under `npx skillrepo init`, the v3.1.0/v3.1.1 SessionStart hook
+ * design fails because the npx cache path is transient and unsuitable
+ * for a long-lived hook command. v3.1.1 worked around this by
+ * skipping the hook with a "install globally first" warning — the
+ * prompt-then-fail UX bug that v3.1.2 fixes.
+ *
+ * v3.1.2 fixes it by having init OFFER to run the global install
+ * itself when invoked under npx. This module is the spawn wrapper
+ * that runs `npm install -g skillrepo@<version>` and reports a
+ * structured result.
+ *
+ * Design constraints
+ * ------------------
+ *   1. **No new runtime dependencies.** The CLI's only dep is
+ *      `cli-table3`. This module uses Node built-ins (`child_process`,
+ *      `path`) only.
+ *
+ *   2. **Spawn is injectable.** Tests pass a stub spawn so they
+ *      never actually shell out to npm. Production callers leave
+ *      `spawn` unset and get the real `child_process.spawn`.
+ *
+ *   3. **Cross-platform spawn shape.** On Windows, `npm` is a
+ *      `.cmd` script, not a native binary. `spawn("npm", ...)` on
+ *      Windows without `shell: true` throws ENOENT. The locator
+ *      name comes from `platformConventions()` so we don't sprinkle
+ *      `process.platform === "win32"` checks across the codebase.
+ *      We use `shell: false` on both platforms — it sidesteps the
+ *      argument-quoting surprises `shell: true` introduces on Windows
+ *      and is unnecessary because we control all spawn args.
+ *
+ *   4. **`stdio` mode is caller-controlled.** Default is `inherit`
+ *      so npm's progress output streams to the user's terminal during
+ *      the install (the install can take 10-30 seconds — silent would
+ *      look hung). `--json` mode passes `outputMode: "silent"` to
+ *      suppress npm output that would otherwise pollute the JSON
+ *      stdout.
+ *
+ *   5. **Always returns a result, never throws on user-recoverable
+ *      failure.** Init must continue past auto-install failures —
+ *      the rest of init (config, MCP, first sync) succeeded and the
+ *      user's library is on disk. Throwing here would abort init.
+ *      Programmer errors (e.g. missing version arg) DO throw.
+ *
+ *   6. **5-minute timeout.** Slow registries and corporate proxies
+ *      can take longer than the typical 10-30 seconds. 5 minutes is
+ *      well past any reasonable network worst-case but bounds the
+ *      hang time so init can never wait forever.
+ *
+ *   7. **Verify success post-install.** A 0 exit code from npm is
+ *      necessary but not sufficient — the user's npm prefix bin
+ *      directory might not be on PATH (a common nvm misconfiguration).
+ *      We re-resolve the binary via `where`/`which`, filtering out
+ *      `_npx` cache paths, to confirm the install actually produced
+ *      a usable binary at a stable location.
+ *
+ * Result enum
+ * -----------
+ *   - `success: true` — npm exited 0 AND the resulting binary is at
+ *     a stable absolute path. `binaryPath` is set.
+ *   - `errorCode: "eacces"` — permission denied on the npm prefix.
+ *     User needs sudo (or to fix npm prefix). `error` carries the
+ *     actionable message.
+ *   - `errorCode: "enoent-npm"` — `npm` itself not found on PATH.
+ *     User needs to install Node or fix PATH.
+ *   - `errorCode: "npm-nonzero"` — npm ran but exited non-zero for
+ *     some other reason (network, registry 500, package not found).
+ *     `error` includes the first ~200 chars of stderr.
+ *   - `errorCode: "timeout"` — exceeded the 5-minute deadline. We
+ *     killed the child.
+ *   - `errorCode: "path-not-updated"` — npm exited 0 but the binary
+ *     isn't on PATH at a stable location. Either the install actually
+ *     failed silently or the user's npm prefix bin dir isn't on PATH.
+ */
+
+import { spawn as defaultSpawn } from "node:child_process";
+import { platformConventions } from "./platform.mjs";
+import { resolveBinaryOnPath } from "./binary-locator.mjs";
+
+/**
+ * @typedef {Object} GlobalInstallResult
+ * @property {boolean} success
+ * @property {string | null} binaryPath - Absolute path to the resulting
+ *           global `skillrepo` binary on success; null on failure.
+ * @property {string} [error] - Human-readable failure reason. Set
+ *           when `success` is false.
+ * @property {"eacces" | "enoent-npm" | "npm-nonzero" | "timeout" | "path-not-updated"} [errorCode]
+ *           Categorized failure code. Set when `success` is false.
+ */
+
+/**
+ * Default timeout for `npm install -g`. 5 minutes covers the worst
+ * case of slow registries, corporate proxies, or first-time cache
+ * population without letting init hang indefinitely.
+ */
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * Run `npm install -g skillrepo@<version>` and return a structured
+ * result. Never throws on user-recoverable failure (npm exit codes,
+ * permission errors, missing npm) — those are reported via the
+ * `errorCode` field. Programmer errors (missing args) DO throw.
+ *
+ * @param {object} options
+ * @param {string} options.version - Semver string to pin
+ *        (e.g. "3.1.2"). Required.
+ * @param {"inherit" | "silent"} [options.outputMode="inherit"] -
+ *        How to handle npm's stdout/stderr.
+ *          - "inherit": stream npm output through this process's
+ *            stdio (the user sees install progress in real time).
+ *          - "silent": capture and discard. Used in `--json` mode
+ *            so npm output doesn't pollute the JSON stdout.
+ * @param {Function} [options.spawn] - Injected for tests. Defaults
+ *        to the real `child_process.spawn`. Tests pass a stub so the
+ *        suite never actually shells out to npm.
+ * @param {NodeJS.Platform} [options.platform] - Override for tests
+ *        that need to exercise Windows spawn semantics on a non-Windows
+ *        host. Production callers leave this unset.
+ * @param {number} [options.timeoutMs=300000] - Maximum time to wait
+ *        before killing the child and returning `errorCode: "timeout"`.
+ * @returns {Promise<GlobalInstallResult>}
+ */
+export async function installSkillrepoGlobally({
+  version,
+  outputMode = "inherit",
+  spawn = defaultSpawn,
+  platform: platformOverride,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  if (typeof version !== "string" || version.length === 0) {
+    // Programmer error — no recovery, throw.
+    throw new Error(
+      "installSkillrepoGlobally: `version` must be a non-empty string.",
+    );
+  }
+
+  const conv = platformConventions({ platform: platformOverride });
+  // Windows `npm` ships as `npm.cmd` — a batch script. spawn() with
+  // `shell: false` requires the literal name on disk, which is
+  // `npm.cmd` on Windows and `npm` everywhere else.
+  const npmCmd = conv.family === "windows" ? "npm.cmd" : "npm";
+  const args = ["install", "-g", `skillrepo@${version}`];
+
+  // stdio mapping:
+  //   - inherit: npm output streams to user's terminal in real time.
+  //   - silent (--json mode): pipe stdout/stderr so we can capture
+  //     them for error categorization, but don't let them touch the
+  //     terminal. The captured stderr is useful for the
+  //     "first 200 chars of stderr" failure message.
+  const stdio = outputMode === "silent"
+    ? ["ignore", "pipe", "pipe"]
+    : "inherit";
+
+  // ── Spawn the child ─────────────────────────────────────────────
+  // We use `shell: false` (the spawn default) on both platforms.
+  // shell: true on Windows introduces argument-quoting surprises
+  // (cmd.exe quoting rules differ from POSIX shells in subtle ways);
+  // we control all args, so we don't need shell expansion.
+  let child;
+  try {
+    child = spawn(npmCmd, args, { stdio });
+  } catch (err) {
+    // Synchronous spawn failure (rare; some Node versions surface
+    // ENOENT this way instead of via the `error` event). Treat
+    // identically to the async ENOENT path.
+    if (err && err.code === "ENOENT") {
+      return {
+        success: false,
+        binaryPath: null,
+        errorCode: "enoent-npm",
+        error:
+          "`npm` was not found on PATH. Install Node.js " +
+          "(which bundles npm) or ensure npm is on your PATH, " +
+          "then re-run init.",
+      };
+    }
+    // Any other synchronous spawn failure is unexpected — surface
+    // as npm-nonzero with the message.
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "npm-nonzero",
+      error: `Failed to spawn npm: ${err?.message ?? String(err)}`,
+    };
+  }
+
+  // ── Capture output (silent mode) ───────────────────────────────
+  // Buffer stderr for failure-message extraction. stdout is captured
+  // too in case we need it later, but we don't currently use it.
+  let stderrChunks = [];
+  if (outputMode === "silent") {
+    if (child.stderr) {
+      child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    }
+    if (child.stdout) {
+      // Drain to prevent backpressure; we don't actually need the
+      // content. Discarding is the goal of silent mode.
+      child.stdout.on("data", () => {});
+    }
+  }
+
+  // ── Wait for completion or timeout ─────────────────────────────
+  const result = await new Promise((resolve) => {
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    const timer = setTimeout(() => {
+      // The `kill()` may not immediately stop a child that's
+      // doing network I/O on a slow socket. We don't await child
+      // exit after kill — the timeout result is what we report;
+      // the OS reaps the child whenever it actually exits.
+      try {
+        child.kill();
+      } catch {
+        // Already exited — fine.
+      }
+      settle({ kind: "timeout" });
+    }, timeoutMs);
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      // Async spawn errors. ENOENT here means `npm` not on PATH.
+      if (err && err.code === "ENOENT") {
+        settle({ kind: "enoent-npm" });
+        return;
+      }
+      // EACCES at spawn time (rare, usually surfaces in npm output
+      // instead). Treat as npm-nonzero with the error message.
+      settle({ kind: "spawn-error", message: err?.message ?? String(err) });
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      settle({ kind: "exit", code });
+    });
+  });
+
+  if (result.kind === "timeout") {
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "timeout",
+      error:
+        `npm install -g skillrepo@${version} did not complete within ` +
+        `${Math.round(timeoutMs / 1000)} seconds. Check your network ` +
+        "connection or npm registry status, then re-run init.",
+    };
+  }
+
+  if (result.kind === "enoent-npm") {
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "enoent-npm",
+      error:
+        "`npm` was not found on PATH. Install Node.js " +
+        "(which bundles npm) or ensure npm is on your PATH, " +
+        "then re-run init.",
+    };
+  }
+
+  if (result.kind === "spawn-error") {
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "npm-nonzero",
+      error: `Failed to run npm: ${result.message}`,
+    };
+  }
+
+  // result.kind === "exit"
+  const exitCode = result.code;
+  // Only build the stderr string when we actually captured it
+  // (silent mode). In inherit mode, `stderrChunks` is always empty
+  // because the stream wasn't piped to us.
+  const stderrText =
+    outputMode === "silent"
+      ? Buffer.concat(stderrChunks).toString("utf-8")
+      : "";
+
+  if (exitCode !== 0) {
+    // EACCES is a common case worth distinguishing — the actionable
+    // remediation differs (sudo or fix prefix vs check the npm
+    // output). We have two signals available:
+    //   1. stderr text contains "EACCES" — only available in silent
+    //      mode (`--json`) where we capture stderr.
+    //   2. exit code 243 — npm's exit code for EACCES on POSIX.
+    //      Documented in npm's source as the dedicated permission-
+    //      error code. Available in BOTH inherit and silent modes
+    //      because exit code is always observable.
+    // Trying both gives the user a categorized error in both modes.
+    if (stderrText.includes("EACCES") || exitCode === 243) {
+      return {
+        success: false,
+        binaryPath: null,
+        errorCode: "eacces",
+        error:
+          "npm reported a permissions error (EACCES). Run with sudo " +
+          "or fix npm's prefix to a writable location: " +
+          "https://docs.npmjs.com/resolving-eacces-permissions-errors",
+      };
+    }
+    // Generic npm failure. In silent mode (--json) we have stderr
+    // text and include the first 200 chars for diagnosis. In inherit
+    // mode the user already saw npm's real output stream past, so
+    // we add a short hint pointing at the two most common
+    // remediations (permissions, network) without trying to guess
+    // which applies.
+    const trimmedStderr =
+      stderrText.length > 0 ? ` ${stderrText.slice(0, 200).trim()}` : "";
+    const inheritHint =
+      stderrText.length === 0
+        ? " Common causes: permissions (try sudo, or fix npm's prefix) " +
+          "or network/registry issues (check your internet connection)."
+        : "";
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "npm-nonzero",
+      error: `npm install -g exited with code ${exitCode}.${trimmedStderr}${inheritHint}`,
+    };
+  }
+
+  // ── Verify the install actually produced a usable binary ──────
+  const binaryPath = resolveGlobalBinary({ platform: platformOverride });
+  if (!binaryPath) {
+    const isWindows = conv.family === "windows";
+    // Windows-specific addendum: PATH changes from `npm install -g`
+    // are NOT visible in the current terminal session — the user
+    // has to open a new terminal for the change to propagate. POSIX
+    // shells inherit the new PATH naturally because npm writes to
+    // a directory the user's shell already has on PATH.
+    const platformAddendum = isWindows
+      ? " On Windows, `npm install -g` does not refresh PATH in the " +
+        "current terminal. Open a new PowerShell or cmd.exe window, " +
+        "then run `skillrepo session-sync enable`."
+      : "";
+    return {
+      success: false,
+      binaryPath: null,
+      errorCode: "path-not-updated",
+      error:
+        "npm install -g succeeded but `skillrepo` was not found on " +
+        "PATH. Your npm prefix bin directory may not be on PATH. " +
+        "Run `npm config get prefix` and add `<prefix>/bin` to PATH, " +
+        "then run `skillrepo session-sync enable`." +
+        platformAddendum,
+    };
+  }
+
+  return {
+    success: true,
+    binaryPath,
+  };
+}
+
+/**
+ * Resolve the absolute path of a STABLE (non-cache) `skillrepo`
+ * binary on PATH. Used after `npm install -g` to confirm the install
+ * produced a usable binary at a path safe to bake into the
+ * SessionStart hook command.
+ *
+ * Thin wrapper over `resolveBinaryOnPath` with `filterTransient: true`
+ * preset. The `skipIfTransient` flag is intentionally false — we
+ * WANT to find the newly-installed global even when we're running
+ * under a transient runner ourselves.
+ *
+ * @param {object} [options]
+ * @param {NodeJS.Platform} [options.platform] - Override for tests.
+ * @returns {string | null}
+ */
+export function resolveGlobalBinary({ platform: platformOverride } = {}) {
+  return resolveBinaryOnPath("skillrepo", {
+    filterTransient: true,
+    platform: platformOverride,
+  });
+}