skillrepo 3.1.0 → 3.1.2

package/src/lib/global-install.mjs

@@ -0,0 +1,387 @@
+/**
+ * `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. Same pattern as
+  // `binaryLocator` ("which" vs "where").
+  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,
+  });
+}

package/src/lib/mcp-merge.mjs

@@ -75,16 +75,27 @@ import { validationError } from "./errors.mjs";
  * @param {object} [options.io] - Injected streams for testability
  * @param {NodeJS.WritableStream} [options.io.stdout=process.stdout]
  * @param {NodeJS.WritableStream} [options.io.stderr=process.stderr]
- * @param {(prompt: string, defaultYes?: boolean) => Promise<boolean>} [options.confirmFn]
+ * @param {object} [options.deps] - Test-only dependency injection.
+ *        Production callers leave this empty. Standardized name
+ *        across CLI commands (init, init-session-sync, etc.) so all
+ *        injection points live under a single `deps` namespace.
+ * @param {(prompt: string, defaultYes?: boolean) => Promise<boolean>} [options.deps.confirmFn]
  *        Optional injection point for the y/n prompt. Defaults to
  *        the real `confirm` from prompt.mjs. Tests pass a stub to
- *        avoid spawning a readline interface. This dependency is
- *        injected rather than monkey-patched because ESM module
- *        exports are frozen and cannot be reassigned.
+ *        avoid spawning a readline interface. ESM module exports
+ *        are frozen and cannot be reassigned, so dependency
+ *        injection is the only clean way to substitute.
  * @returns {Promise<McpMergeResult[]>}
  */
 export async function mergeMcpForVendors(options) {
-  const { vendors, mcpUrl, yes = false, io = {}, confirmFn = realConfirm } = options;
+  const {
+    vendors,
+    mcpUrl,
+    yes = false,
+    io = {},
+    deps = {},
+  } = options;
+  const confirmFn = deps.confirmFn ?? realConfirm;
   const stdout = io.stdout ?? process.stdout;
   const stderr = io.stderr ?? process.stderr;
 

package/src/lib/mergers/session-hook.mjs

@@ -70,7 +70,6 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { execFileSync } from "node:child_process";
 import { writeFileAtomic } from "../fs-utils.mjs";
 import { SESSION_HOOK_FINGERPRINT } from "../artifact-registry.mjs";
 import {
@@ -79,54 +78,109 @@ import {
 } from "../paths.mjs";
 import { diskError, validationError } from "../errors.mjs";
 import { removeSettingsSessionHook } from "../removers/settings.mjs";
+import { resolveBinaryOnPath } from "../binary-locator.mjs";
+import { platformConventions } from "../platform.mjs";
 
 /**
  * Build the hook command string for a given absolute path. Exported
  * so tests can assert the exact bytes the installer writes.
  *
+ * Shell shape is platform-specific — see `platform.mjs` for the full
+ * rationale. Summary:
+ *
+ *   - **POSIX** (macOS, Linux): `'<path>' update --session-hook 2>&1 || true`.
+ *     `|| true` catches any non-zero exit at the shell level; primary
+ *     defense is the `--session-hook` flag contract in the Node process.
+ *   - **Windows** (cmd.exe / PowerShell): `"<path>" update --session-hook 2>&1`.
+ *     `|| true` omitted because cmd.exe doesn't know the `true` builtin.
+ *     `--session-hook` contract is the only defense; consequences of
+ *     binary-vanished scenarios are slightly noisier in Claude Code's
+ *     session log but still non-blocking.
+ *
+ * Path quoting is mandatory: real-world install paths contain spaces
+ * (`C:\Program Files\nodejs\skillrepo.cmd`, `/Users/First Last/.npm-global/bin/skillrepo`)
+ * and parentheses (`C:\Program Files (x86)\...`). An unquoted path
+ * makes the shell parse the command as multiple arguments and the
+ * hook silently fails on session start.
+ *
+ * The fingerprint constant (`SESSION_HOOK_FINGERPRINT` =
+ * ` update --session-hook` with leading space) MUST appear in the
+ * resulting command for the uninstaller and idempotency walks to
+ * find it. Single/double quotes don't break the fingerprint because
+ * the leading space sits between the closing quote and `update`.
+ * Backward-compat: existing v3.1.0/v3.1.1 hooks with unquoted paths
+ * also match the fingerprint (the space sits between the path and
+ * `update`), so re-running init detects them and updates in place
+ * to the new quoted shape.
+ *
+ * The suffix is supplied by `platformConventions().hookShellSuffix` —
+ * this function doesn't know which OS it's targeting, it just
+ * concatenates the convention's suffix.
+ *
  * @param {string} binaryPath - Absolute path to the `skillrepo` binary.
+ * @param {object} [options]
+ * @param {NodeJS.Platform} [options.platform] - Override for testing.
+ *        Default: `os.platform()`.
  * @returns {string} The full shell command string.
  */
-export function buildHookCommand(binaryPath) {
+export function buildHookCommand(binaryPath, { platform: platformOverride } = {}) {
   if (typeof binaryPath !== "string" || binaryPath.length === 0) {
     throw validationError(
       "buildHookCommand: binaryPath must be a non-empty string.",
     );
   }
-  return `${binaryPath} update --session-hook 2>&1 || true`;
+  const conv = platformConventions({ platform: platformOverride });
+  const quotedPath = quoteShellPath(binaryPath, conv.family);
+  return `${quotedPath} update --session-hook 2>&1${conv.hookShellSuffix}`;
 }
 
 /**
- * Resolve the absolute path of the `skillrepo` binary via `which`.
- * Returns null if resolution fails (e.g. user ran `npx skillrepo init`
- * without a global install) — the caller should skip hook installation
- * with a clear warning rather than fail init.
+ * Quote a filesystem path for inclusion in a shell command, using the
+ * conventions of the target shell family.
  *
- * @returns {string | null}
+ *   - **POSIX**: wrap in single quotes; escape any embedded single
+ *     quote with the standard `'\''` trick (close quote, escaped
+ *     literal quote, reopen quote). Single quotes suppress ALL shell
+ *     interpretation, so spaces, `$`, `*`, parens, double quotes,
+ *     backticks, and backslashes pass through verbatim.
+ *
+ *   - **Windows** (cmd.exe): wrap in double quotes; escape any
+ *     embedded double quote with `\"`. Backslashes inside the path
+ *     pass through unchanged (cmd.exe does not interpret backslashes
+ *     as escapes inside double quotes). Filesystem rules forbid
+ *     literal `"` in NTFS path components, so the `\"` escape is
+ *     defensive — paths in the wild won't contain it.
+ *
+ * @param {string} path
+ * @param {"posix" | "windows"} family
+ * @returns {string} The quoted path, ready to be interpolated into
+ *          a shell command.
  */
-export function resolveSkillrepoBinary() {
-  try {
-    // 3-second timeout — `which` typically returns in milliseconds,
-    // but a PATH that includes a network filesystem or a `which`
-    // alias that does I/O could hang indefinitely. Bounding the
-    // call ensures `skillrepo init` never stalls on binary
-    // resolution. Per code-reviewer round-1 LOW finding.
-    const result = execFileSync("which", ["skillrepo"], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 3000,
-    }).trim();
-    if (!result) return null;
-    // Sanity: the resolved path must be absolute. A relative result
-    // would be meaningless at session-start time because the Claude
-    // Code hook runner's cwd is undefined.
-    if (!result.startsWith("/")) return null;
-    return result;
-  } catch {
-    // `which` exits non-zero if the binary isn't found. Treat as
-    // "no global install, skip session-sync" — caller handles.
-    return null;
+function quoteShellPath(path, family) {
+  if (family === "windows") {
+    return `"${path.replace(/"/g, '\\"')}"`;
   }
+  // POSIX
+  return `'${path.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Resolve the absolute path of the `skillrepo` binary on PATH,
+ * skipping resolution entirely when the current process is itself
+ * a transient-runner invocation (npx, pnpx, yarn dlx, bunx) — those
+ * cache paths must not be baked into the long-lived hook command.
+ *
+ * Thin wrapper over `resolveBinaryOnPath` with the
+ * `skipIfTransient` flag preset. Kept as a named export for
+ * call-site readability and so existing tests keep working.
+ *
+ * @returns {string | null}
+ */
+export function resolveSkillrepoBinary({ platform: platformOverride } = {}) {
+  return resolveBinaryOnPath("skillrepo", {
+    skipIfTransient: true,
+    platform: platformOverride,
+  });
 }
 
 /**
@@ -140,6 +194,16 @@ export function resolveSkillrepoBinary() {
  * @param {boolean} [options.global=false] - When true, installs to the
  *        user-global `~/.claude/settings.local.json` instead of the
  *        project-local file.
+ * @param {NodeJS.Platform} [options.platform] - Override for testing.
+ *        Propagated to both `resolveSkillrepoBinary` and
+ *        `buildHookCommand` so a test can exercise the full
+ *        installer path under simulated Windows semantics on a
+ *        non-Windows host. Production callers leave this unset so
+ *        both helpers see the real `os.platform()`. This option is
+ *        the mechanism that closes the architect's round-3 HIGH
+ *        finding — without it, a Windows-shaped `binaryPath` passed
+ *        in the test still got a POSIX-shaped command back because
+ *        `buildHookCommand` read `os.platform()` directly.
  * @returns {{
  *   path: string;
  *   action: "installed" | "updated" | "unchanged" | "skipped";
@@ -158,23 +222,51 @@ export function resolveSkillrepoBinary() {
 export function mergeSessionHook({
   binaryPath: binaryPathOpt,
   global = false,
+  platform: platformOverride,
 } = {}) {
   const filePath = global ? claudeSettingsLocalGlobal() : claudeSettingsLocal();
   const displayPath = global
     ? "~/.claude/settings.local.json"
     : ".claude/settings.local.json";
 
-  const binaryPath = binaryPathOpt ?? resolveSkillrepoBinary();
+  const binaryPath =
+    binaryPathOpt ?? resolveSkillrepoBinary({ platform: platformOverride });
   if (!binaryPath) {
+    // Two reasons binaryPath can be null:
+    //   1. `isNpxInvocation()` returned true — the user ran
+    //      `npx skillrepo ...`. The npx cache path is transient and
+    //      unsuitable for baking into a long-lived hook command.
+    //   2. `which skillrepo` returned nothing — no global install
+    //      exists at all.
+    // Both are the same problem from the hook's perspective: we
+    // can't produce a command that will still work later.
+    //
+    // v3.1.2 (#894): `init` bypasses this path under npx by running
+    // `npm install -g skillrepo@<version>` itself and then calling
+    // `mergeSessionHook` with the resulting `binaryPath` explicitly.
+    // The remaining callers that hit this branch are:
+    //   - `skillrepo session-sync enable` invoked under npx (does
+    //     not auto-install — a deliberate, explicit user invocation
+    //     should not silently mutate global package state).
+    //   - The rare bare-install case where `which skillrepo` fails
+    //     even though we're not under npx (PATH misconfiguration).
+    //
+    // Both cases get the same actionable hint pointing the user at
+    // `skillrepo init`, which DOES auto-install under npx.
     return {
       path: displayPath,
       action: "skipped",
       reason:
-        "Could not resolve a stable path for `skillrepo`. Session sync requires a global install. Run `npm install -g skillrepo` and re-run `skillrepo session-sync enable`.",
+        "Session sync requires a stable `skillrepo` binary on PATH. " +
+        "Run `npm install -g skillrepo` (or use `skillrepo init`, " +
+        "which offers to install globally for you under npx), then " +
+        "re-run `skillrepo session-sync enable`.",
     };
   }
 
-  const desiredCommand = buildHookCommand(binaryPath);
+  const desiredCommand = buildHookCommand(binaryPath, {
+    platform: platformOverride,
+  });
 
   // Parse existing file (or start fresh). A corrupt-but-present file
   // is a hard error: silently overwriting it would destroy any user-