skillrepo 3.1.2 → 3.1.4

package/LICENSE

@@ -0,0 +1,37 @@
+SkillRepo CLI
+Copyright (c) 2026 SkillRepo LLC. All rights reserved.
+
+This software is proprietary and confidential. Its installation, use,
+reproduction, modification, and distribution are governed exclusively by
+the SkillRepo End User License Agreement (the "EULA") available at:
+
+    https://skillrepo.dev/eula
+
+By installing, copying, or otherwise using this software you agree to be
+bound by the EULA. If you do not agree to the EULA, do not install or
+use this software.
+
+No license or right, whether by implication, estoppel, or otherwise, is
+granted except as expressly set forth in the EULA. Without limiting the
+foregoing, you may not:
+
+  - reverse engineer, decompile, disassemble, or otherwise attempt to
+    derive the source code of this software, except to the extent such
+    activity is expressly permitted by applicable law notwithstanding
+    this limitation;
+  - sell, resell, rent, lease, sublicense, distribute, or otherwise
+    transfer this software or access to it to any third party;
+  - use this software, its outputs, or any data obtained through it to
+    build or operate a service that is substantially similar to or
+    competes with the SkillRepo platform; or
+  - remove, alter, or obscure any proprietary notices on or in this
+    software.
+
+THIS SOFTWARE IS PROVIDED "AS IS," WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED. YOUR USE OF THIS SOFTWARE IS SUBJECT TO THE WARRANTY
+DISCLAIMERS, LIMITATION OF LIABILITY, AND ALL OTHER PROVISIONS OF THE
+EULA, WHICH ARE INCORPORATED INTO THIS NOTICE BY REFERENCE.
+
+SkillRepo and the SkillRepo logo are trademarks of SkillRepo LLC.
+
+Contact: hello@skillrepo.dev

package/README.md

@@ -346,4 +346,7 @@ fully overwrites it.
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+Proprietary. Copyright © 2026 SkillRepo LLC. All rights reserved.
+Use of this CLI is governed by the SkillRepo End User License Agreement
+at [https://skillrepo.dev/eula](https://skillrepo.dev/eula). See
+[LICENSE](./LICENSE) for the full notice.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "3.1.2",
+  "version": "3.1.4",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "bin/",
-    "src/"
+    "src/",
+    "LICENSE"
   ],
   "repository": {
     "type": "git",
@@ -16,7 +17,8 @@
     "directory": "packages/cli"
   },
   "keywords": ["skillrepo", "cli", "mcp", "ai-skills"],
-  "license": "MIT",
+  "author": "SkillRepo LLC",
+  "license": "SEE LICENSE IN LICENSE",
   "dependencies": {
     "cli-table3": "^0.6.5"
   }

package/src/lib/binary-locator.mjs

@@ -1,32 +1,47 @@
 /**
  * Cross-platform binary locator with optional transient-runner
- * filtering (#894 / v3.1.2).
+ * filtering (#894 / v3.1.2, fixed in v3.1.3).
  *
- * Wraps `where` (Windows) / `which` (POSIX) to find a named binary
- * on PATH and returns its absolute path. The two flag knobs
- * `skipIfTransient` and `filterTransient` were extracted from the
- * v3.1.2 first cleanup pass: previously two near-identical functions
- * (`resolveSkillrepoBinary` in `mergers/session-hook.mjs`,
- * `resolveGlobalBinary` in `lib/global-install.mjs`) duplicated this
- * logic with the only differences being:
+ * ## v3.1.3 fix history
  *
- *   - `resolveSkillrepoBinary` had an early-return guard against
- *     `isNpxInvocation()` (now `isTransientRunnerInvocation`) — the
- *     `skipIfTransient` flag captures that.
+ * 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.
  *
- *   - `resolveGlobalBinary` filtered `_npx`-cache results from the
- *     locator output — the `filterTransient` flag (powered by
- *     `isTransientCachePath` from `lib/transient-runners.mjs`)
- *     captures that and extends it to all package runners (pnpm
- *     dlx, yarn berry dlx, bunx).
+ * 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
- * `which`/`where` wrapper unless the caller opts into the extra
- * semantics.
+ * PATH lookup unless the caller opts into the extra semantics.
  */
 
-import { execFileSync } from "node:child_process";
-import { isAbsolute } from "node:path";
+import { existsSync } from "node:fs";
+import { delimiter, isAbsolute, join } from "node:path";
 import { platformConventions } from "./platform.mjs";
 import {
   isTransientCachePath,
@@ -37,63 +52,75 @@ import {
  * Resolve the absolute path of `binaryName` on PATH.
  *
  * @param {string} binaryName - The bare command name (e.g.
- *        `"skillrepo"`). Resolved via the platform's binary locator
- *        (`which` on POSIX, `where` on Windows).
+ *        `"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. Used by callers that bake
- *        the resolved path into long-lived state (e.g. a SessionStart
- *        hook command) and must not bind to a transient cache path.
+ *        a transient-runner invocation.
  * @param {boolean} [options.filterTransient=false] - When true,
- *        ignore locator output lines that point inside a transient
- *        runner's cache directory. Used by callers that explicitly
- *        want a STABLE global install at a non-cache path.
+ *        ignore matches inside a transient runner's cache directory.
  * @param {NodeJS.Platform} [options.platform] - Override for tests.
  *        Production callers leave unset.
- * @returns {string | null} The absolute path of the first matching
- *        non-filtered locator output line, or `null` if no match.
+ * @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 } = {},
+  {
+    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));
 
-  let raw;
-  try {
-    // 3-second cap — `which`/`where` typically return in
-    // milliseconds, but a pathological PATH (network filesystem,
-    // hung shell alias) could otherwise stall the whole CLI.
-    raw = execFileSync(conv.binaryLocator, [binaryName], {
-      encoding: "utf-8",
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 3000,
-    });
-  } catch {
-    // Locator exits non-zero when the binary isn't on PATH, OR
-    // throws ENOENT when the locator itself doesn't exist (rare —
-    // a Windows install missing `where.exe`, or a minimal POSIX
-    // image without `which`). Both collapse to "binary not
-    // resolvable" from the caller's perspective.
-    return null;
-  }
+  // 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];
 
-  // Windows `where.exe` returns one match per line; POSIX `which`
-  // returns a single line. Take the first match that survives the
-  // absolute-path and (optional) transient-cache filters.
-  const lines = raw
-    .split(/\r?\n/)
-    .map((s) => s.trim())
-    .filter(Boolean);
-  for (const line of lines) {
-    if (!isAbsolute(line)) continue;
-    if (filterTransient && isTransientCachePath(line)) continue;
-    return line;
+  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/global-install.mjs

@@ -142,8 +142,7 @@ export async function installSkillrepoGlobally({
   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").
+  // `npm.cmd` on Windows and `npm` everywhere else.
   const npmCmd = conv.family === "windows" ? "npm.cmd" : "npm";
   const args = ["install", "-g", `skillrepo@${version}`];
 

package/src/lib/platform.mjs

@@ -8,11 +8,7 @@
  * real platform differences that can't be abstracted away at the
  * Node level:
  *
- *   1. **Binary-locator command**. POSIX provides `which`; Windows
- *      provides `where.exe`. `execFileSync` doesn't spawn a shell,
- *      so the literal name must exist on disk.
- *
- *   2. **Hook shell backstop suffix**. The SessionStart hook command
+ *   1. **Hook shell backstop suffix**. The SessionStart hook command
  *      relies on a shell-level fallback (`|| true`) to guarantee
  *      exit 0 even if the binary vanishes. POSIX shells support it;
  *      cmd.exe doesn't know the `true` builtin and would emit a
@@ -21,14 +17,14 @@
  *      platform; the shell backstop is belt-and-suspenders that we
  *      lose on Windows.
  *
- *   3. **POSIX file permissions**. `chmodSync(0o600)` silently
+ *   2. **POSIX file permissions**. `chmodSync(0o600)` silently
  *      succeeds on Windows but doesn't produce the intended effect —
  *      Windows's ACL model doesn't map to the Unix mode bits. Any
  *      call meant to restrict permissions on credential files must
  *      be guarded so Windows users aren't misled into thinking their
  *      files are access-controlled when they aren't.
  *
- *   4. **Atomic directory replacement semantics**. POSIX's
+ *   3. **Atomic directory replacement semantics**. POSIX's
  *      `renameSync` over an existing directory is atomic on the same
  *      filesystem — the swap is instantaneous from the perspective
  *      of any concurrent reader. Windows fails with EEXIST/EPERM if
@@ -38,6 +34,14 @@
  *      which strategy applies so they can surface a meaningful
  *      recovery hint if the Windows path fails mid-sequence.
  *
+ * The v3.1.2 `binaryLocator` field (used by an earlier
+ * `which`/`where`-based binary locator) was removed in v3.1.3 when
+ * `lib/binary-locator.mjs` switched to scanning PATH directly in
+ * Node — POSIX `which` returns ONLY the first match, which broke
+ * the npx auto-install verification path (the npx cache copy was
+ * the first match and got filtered, so the just-installed global
+ * was never seen).
+ *
  * This module exposes a single `platformConventions()` function that
  * returns a frozen object with every platform-specific value the
  * CLI needs. New platform-specific surfaces should be added here
@@ -54,9 +58,6 @@ import { platform as osPlatform } from "node:os";
 /**
  * @typedef {Object} PlatformConventions
  * @property {"posix" | "windows"} family - High-level family name.
- * @property {string} binaryLocator - Command used to resolve a
- *           binary's absolute path from PATH. `"which"` on POSIX,
- *           `"where"` on Windows.
  * @property {string} hookShellSuffix - Suffix appended to hook
  *           commands to guarantee exit 0 at the shell level. `" || true"`
  *           on POSIX (appended to the base command), empty string on
@@ -81,7 +82,6 @@ import { platform as osPlatform } from "node:os";
 
 const POSIX = Object.freeze({
   family: "posix",
-  binaryLocator: "which",
   hookShellSuffix: " || true",
   supportsPosixPermissions: true,
   supportsAtomicDirectoryRename: true,
@@ -89,7 +89,6 @@ const POSIX = Object.freeze({
 
 const WINDOWS = Object.freeze({
   family: "windows",
-  binaryLocator: "where",
   hookShellSuffix: "",
   supportsPosixPermissions: false,
   supportsAtomicDirectoryRename: false,

package/src/test/commands/init.test.mjs

@@ -25,6 +25,7 @@ import {
   setSandboxHome,
   restoreHome,
 } from "../helpers/sandbox-home.mjs";
+import { isolatePathEnv } from "../helpers/path-isolation.mjs";
 
 let sandbox;
 let server;
@@ -1060,12 +1061,23 @@ describe("runInit — v3.1.1 Next steps prefix (bug 1)", () => {
 // no test ever shells out to `npm install -g`.
 
 describe("runInit — v3.1.2 step 6 auto-install (npx)", () => {
-  // Process-state isolation: same as the v3.1.1 npx prefix tests
-  // above. We control isNpxInvocation()'s output via process.argv[1]
-  // and process.env._.
+  // Process-state isolation:
+  //   - We control isTransientRunnerInvocation()'s output via
+  //     process.argv[1] and process.env._.
+  //   - We CLEAR PATH so resolveGlobalBinary() genuinely returns
+  //     null (otherwise the developer's locally-installed `skillrepo`
+  //     makes Branch 4 fire when the test expects Branch 6). This
+  //     matters even more in v3.1.3+ which scans PATH directly in
+  //     Node — any pre-existing skillrepo on the dev's PATH would
+  //     be visible to the locator.
+  // Tests that DO want a "global on PATH" scenario explicitly install
+  // a shim via `installShim` in their body (see Branch 4 + idempotency
+  // tests below); the shim helper prepends its own bin dir to PATH
+  // so it survives the cleared baseline.
   let originalArgv;
   let originalUnderscore;
   let originalNpmCommand;
+  let restorePath;
   let shimSandbox;
   let shimHandle;
 
@@ -1074,6 +1086,7 @@ describe("runInit — v3.1.2 step 6 auto-install (npx)", () => {
     originalArgv = process.argv;
     originalUnderscore = process.env._;
     originalNpmCommand = process.env.npm_command;
+    restorePath = isolatePathEnv();
     shimSandbox = null;
     shimHandle = null;
   });
@@ -1089,6 +1102,11 @@ describe("runInit — v3.1.2 step 6 auto-install (npx)", () => {
       uninstallShim(shimHandle);
     }
     if (shimSandbox) rmSync(shimSandbox, { recursive: true, force: true });
+    // Restore PATH last (after uninstallShim, which restores PATH
+    // to its pre-shim state — usually our cleared baseline). The
+    // outer restore puts the dev's real PATH back for the next
+    // test suite.
+    restorePath();
     await teardown();
   });
 

package/src/test/helpers/path-isolation.mjs

@@ -0,0 +1,65 @@
+/**
+ * Test helper: isolate `process.env.PATH` for the duration of a
+ * test (introduced in v3.1.3 alongside the binary-locator rewrite).
+ *
+ * Why this exists
+ * ---------------
+ * `lib/binary-locator.mjs` (introduced in v3.1.3) scans
+ * `process.env.PATH` directly to find the `skillrepo` binary.
+ * Tests that exercise the "no skillrepo on PATH" branch — e.g.
+ * the auto-install Branch 6 in `init`, the null-binary skipped
+ * branch in `mergeSessionHook` — would otherwise be non-
+ * deterministic on developer machines where `skillrepo` IS
+ * already globally installed: the locator would find the dev's
+ * real binary and the test would take the wrong code branch.
+ *
+ * Pre-v3.1.3 the same tests relied on `which`/`where` returning
+ * null for missing binaries, which gave them implicit isolation
+ * because `which` only returned the first match. The pure-Node
+ * scan removed that incidental isolation, so we make it explicit.
+ *
+ * Usage
+ * -----
+ *
+ *   import { isolatePathEnv } from "../helpers/path-isolation.mjs";
+ *
+ *   beforeEach(() => {
+ *     restorePath = isolatePathEnv();
+ *   });
+ *   afterEach(() => {
+ *     restorePath();
+ *   });
+ *
+ * Or scoped to a single test:
+ *
+ *   it("...", () => {
+ *     const restore = isolatePathEnv();
+ *     try {
+ *       // ... test body
+ *     } finally {
+ *       restore();
+ *     }
+ *   });
+ */
+
+/**
+ * Replace `process.env.PATH` with a known-empty value and return
+ * a restore function that puts the original value back. Handles
+ * the `undefined` case correctly: setting `process.env.PATH =
+ * undefined` produces the literal string `"undefined"`, so the
+ * restore must `delete` the key in that case.
+ *
+ * @returns {() => void} Restore function. Idempotent — calling it
+ *          twice is a no-op on the second call.
+ */
+export function isolatePathEnv() {
+  const originalPath = process.env.PATH;
+  process.env.PATH = "/nonexistent-test-isolation-dir";
+  let restored = false;
+  return function restore() {
+    if (restored) return;
+    restored = true;
+    if (originalPath === undefined) delete process.env.PATH;
+    else process.env.PATH = originalPath;
+  };
+}

package/src/test/lib/binary-locator.test.mjs

@@ -0,0 +1,223 @@
+/**
+ * Unit tests for src/lib/binary-locator.mjs (#894 / v3.1.3).
+ *
+ * The most important test here is the **v3.1.2 regression guard**:
+ * a PATH with a transient (_npx) skillrepo entry FIRST followed by
+ * a stable skillrepo entry must resolve to the STABLE one when
+ * `filterTransient: true` is passed.
+ *
+ * v3.1.2 used `which`/`where` to look up the binary. POSIX `which`
+ * returns ONLY the first match, so the npx cache copy was returned,
+ * filtered as transient, and the function returned null — even
+ * though a stable global was on PATH. The user's symptom: `npm
+ * install -g skillrepo` succeeds, but init reports the install
+ * as failed because the post-install verification couldn't see
+ * the just-installed binary.
+ *
+ * v3.1.3 scans PATH directly in Node so it sees ALL candidates
+ * and can pick the first non-transient one. This test reproduces
+ * the exact PATH layout that broke v3.1.2 and proves the fix.
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  writeFileSync,
+  chmodSync,
+} from "node:fs";
+import { join, delimiter } from "node:path";
+import { tmpdir } from "node:os";
+
+import { resolveBinaryOnPath } from "../../lib/binary-locator.mjs";
+
+// Helper: create a directory with a `skillrepo` executable inside.
+// Returns the directory path.
+function makeBinDir(parent, name) {
+  const dir = join(parent, name);
+  mkdirSync(dir, { recursive: true });
+  const binPath = join(dir, "skillrepo");
+  writeFileSync(binPath, "#!/bin/sh\nexit 0\n");
+  chmodSync(binPath, 0o755);
+  return dir;
+}
+
+describe("resolveBinaryOnPath — v3.1.3 regression guard for v3.1.2 bug", () => {
+  let sandbox;
+  let originalArgv;
+  let originalUnderscore;
+
+  beforeEach(() => {
+    sandbox = mkdtempSync(join(tmpdir(), "binary-locator-test-"));
+    // Clear transient-runner signals so isTransientRunnerInvocation
+    // doesn't trip on the dev's actual environment.
+    originalArgv = process.argv;
+    originalUnderscore = process.env._;
+    process.argv = ["/usr/local/bin/node", "/usr/local/bin/test"];
+    delete process.env._;
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+    if (originalUnderscore === undefined) delete process.env._;
+    else process.env._ = originalUnderscore;
+    if (sandbox) rmSync(sandbox, { recursive: true, force: true });
+  });
+
+  it("v3.1.2 BUG REPRODUCTION: with `filterTransient: true`, returns the STABLE binary even when a transient cache entry comes FIRST on PATH", () => {
+    // This is the EXACT layout that broke v3.1.2:
+    //   PATH = /tmp/xyz/_npx/abc123/.bin : /tmp/xyz/.npm-global/bin
+    //   /tmp/xyz/_npx/abc123/.bin/skillrepo  EXISTS  (transient cache)
+    //   /tmp/xyz/.npm-global/bin/skillrepo   EXISTS  (stable global)
+    //
+    // v3.1.2: `which skillrepo` returned only the FIRST match (the
+    // _npx one), filterTransient stripped it, function returned null.
+    // v3.1.3: pure-Node PATH scan sees both, returns the stable one.
+    //
+    // Construct the PATH layout. `isTransientCachePath` matches
+    // any path with `/_npx/` (or `\_npx\` on Windows) as a path
+    // component, so the parent must be literally named `_npx`.
+    const npxParent = join(sandbox, "_npx", "abc123", "bin");
+    mkdirSync(npxParent, { recursive: true });
+    const transientBin = join(npxParent, "skillrepo");
+    writeFileSync(transientBin, "#!/bin/sh\nexit 0\n");
+    chmodSync(transientBin, 0o755);
+
+    const stableDir = makeBinDir(sandbox, "stable-global-bin");
+
+    // PATH = transient FIRST (the v3.1.2-breaking ordering),
+    // stable SECOND.
+    const fakePath = [npxParent, stableDir].join(delimiter);
+
+    const result = resolveBinaryOnPath("skillrepo", {
+      filterTransient: true,
+      path: fakePath,
+    });
+
+    assert.ok(
+      result !== null,
+      `expected to find the stable skillrepo binary, got null. ` +
+        `This is the v3.1.2 shipped bug — pre-fix, which/where returned ` +
+        `only the first match (the _npx one), got filtered, returned null. ` +
+        `Pure-Node PATH scan must see ALL candidates and pick the first ` +
+        `non-transient.`,
+    );
+    assert.equal(
+      result,
+      join(stableDir, "skillrepo"),
+      "expected the STABLE-bin path, not the transient cache path",
+    );
+    // Triple-check: the result must NOT be the transient path.
+    assert.ok(
+      !result.includes("_npx"),
+      `result must not be a _npx cache path, got: ${result}`,
+    );
+  });
+
+  it("with `filterTransient: false`, returns the FIRST match including transient paths (legacy behavior)", () => {
+    // The default behavior (no flag) should return the first match
+    // regardless of whether it's transient — same semantic as a
+    // plain `which` call.
+    const npxParent = join(sandbox, "_npx", "abc123", "bin");
+    mkdirSync(npxParent, { recursive: true });
+    const transientBin = join(npxParent, "skillrepo");
+    writeFileSync(transientBin, "#!/bin/sh\nexit 0\n");
+    chmodSync(transientBin, 0o755);
+
+    const stableDir = makeBinDir(sandbox, "stable-global-bin");
+    const fakePath = [npxParent, stableDir].join(delimiter);
+
+    const result = resolveBinaryOnPath("skillrepo", {
+      filterTransient: false,
+      path: fakePath,
+    });
+
+    // First match wins — and the first dir on PATH IS the transient.
+    assert.equal(result, transientBin);
+  });
+
+  it("with both `filterTransient: true` AND no stable binary on PATH, returns null", () => {
+    // Edge case: only transient binaries exist. Caller asked for
+    // stable-only, so null is correct.
+    const npxParent = join(sandbox, "_npx", "abc123", "bin");
+    mkdirSync(npxParent, { recursive: true });
+    const transientBin = join(npxParent, "skillrepo");
+    writeFileSync(transientBin, "#!/bin/sh\nexit 0\n");
+    chmodSync(transientBin, 0o755);
+
+    const result = resolveBinaryOnPath("skillrepo", {
+      filterTransient: true,
+      path: npxParent,
+    });
+    assert.equal(result, null);
+  });
+
+  it("with empty PATH, returns null without throwing", () => {
+    assert.equal(
+      resolveBinaryOnPath("skillrepo", { path: "" }),
+      null,
+    );
+  });
+
+  it("with PATH containing only relative entries, returns null", () => {
+    // Relative PATH entries are skipped — they're meaningless for
+    // baking into a long-lived hook command.
+    assert.equal(
+      resolveBinaryOnPath("skillrepo", {
+        path: ["./node_modules/.bin", "../tools"].join(delimiter),
+      }),
+      null,
+    );
+  });
+
+  it("`skipIfTransient: true` short-circuits to null when current process IS a transient invocation", () => {
+    // Even if a real binary is on PATH, callers that pass
+    // skipIfTransient: true (e.g. the SessionStart hook installer)
+    // must get null when running under a transient runner — they
+    // shouldn't bake the current-process state into long-lived
+    // artifacts.
+    const stableDir = makeBinDir(sandbox, "stable-bin");
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.npm/_npx/abc/.bin/skillrepo",
+    ];
+    const result = resolveBinaryOnPath("skillrepo", {
+      skipIfTransient: true,
+      path: stableDir,
+    });
+    assert.equal(result, null);
+  });
+
+  it("Windows platform override probes for .cmd and .exe extensions in addition to bare name", () => {
+    // npm install -g on Windows lands as `<name>.cmd`. The
+    // candidate list for win32 must include .cmd FIRST so the
+    // common case is fast.
+    const dir = join(sandbox, "win-bin");
+    mkdirSync(dir, { recursive: true });
+    const cmdShim = join(dir, "skillrepo.cmd");
+    writeFileSync(cmdShim, "@exit 0\r\n");
+
+    const result = resolveBinaryOnPath("skillrepo", {
+      platform: "win32",
+      path: dir,
+    });
+    assert.equal(result, cmdShim);
+  });
+
+  it("POSIX platform override probes ONLY the bare name (no extension)", () => {
+    // POSIX has no PATHEXT. Even if a `skillrepo.cmd` happens to
+    // exist on a Linux dev box, the bare-name search shouldn't
+    // pick it up under platform: "linux".
+    const dir = join(sandbox, "posix-bin");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, "skillrepo.cmd"), "@exit 0\n"); // Decoy
+    // No bare `skillrepo` file in this dir.
+    const result = resolveBinaryOnPath("skillrepo", {
+      platform: "linux",
+      path: dir,
+    });
+    assert.equal(result, null);
+  });
+});

package/src/test/lib/platform.test.mjs

@@ -17,14 +17,12 @@ import { platformConventions, isWindows } from "../../lib/platform.mjs";
 
 describe("platformConventions", () => {
   it("returns POSIX conventions on macOS (darwin)", () => {
-    // INTENT: macOS is a POSIX family platform. `which` is the
-    // binary locator; shell supports `|| true` backstop; chmod
-    // works meaningfully; atomic directory rename works. A refactor
-    // that treats macOS as a special case would break every
-    // developer on the team.
+    // INTENT: macOS is a POSIX family platform. Shell supports
+    // `|| true` backstop; chmod works meaningfully; atomic directory
+    // rename works. A refactor that treats macOS as a special case
+    // would break every developer on the team.
     const conv = platformConventions({ platform: "darwin" });
     assert.equal(conv.family, "posix");
-    assert.equal(conv.binaryLocator, "which");
     assert.equal(conv.hookShellSuffix, " || true");
     assert.equal(conv.supportsPosixPermissions, true);
     assert.equal(conv.supportsAtomicDirectoryRename, true);
@@ -33,28 +31,29 @@ describe("platformConventions", () => {
   it("returns POSIX conventions on Linux", () => {
     const conv = platformConventions({ platform: "linux" });
     assert.equal(conv.family, "posix");
-    assert.equal(conv.binaryLocator, "which");
     assert.equal(conv.hookShellSuffix, " || true");
     assert.equal(conv.supportsPosixPermissions, true);
     assert.equal(conv.supportsAtomicDirectoryRename, true);
   });
 
   it("returns Windows conventions on win32", () => {
-    // INTENT: Windows has four material differences that can't be
+    // INTENT: Windows has three material differences that can't be
     // abstracted away:
-    //   1. `where.exe` instead of `which` (no shell binary lookup)
-    //   2. no `|| true` (cmd.exe doesn't know the `true` builtin)
-    //   3. chmod mode bits don't map to the ACL model — applying
+    //   1. no `|| true` (cmd.exe doesn't know the `true` builtin)
+    //   2. chmod mode bits don't map to the ACL model — applying
     //      0o600 on Windows looks like it worked but doesn't
     //      restrict access the way a POSIX 0600 does
-    //   4. renameSync fails on existing directory targets, so
+    //   3. renameSync fails on existing directory targets, so
     //      directory replacement needs a remove-then-rename dance
     //      with a small non-atomic window
-    // This test locks all four values for Windows — a refactor
+    // This test locks all three values for Windows — a refactor
     // that breaks any one of them breaks every Windows user.
+    //
+    // Pre-v3.1.3 there was a fourth (`binaryLocator`: which/where);
+    // it was removed when `lib/binary-locator.mjs` switched to a
+    // pure-Node PATH scan, eliminating the shell-out entirely.
     const conv = platformConventions({ platform: "win32" });
     assert.equal(conv.family, "windows");
-    assert.equal(conv.binaryLocator, "where");
     assert.equal(conv.hookShellSuffix, "");
     assert.equal(conv.supportsPosixPermissions, false);
     assert.equal(conv.supportsAtomicDirectoryRename, false);
@@ -68,7 +67,7 @@ describe("platformConventions", () => {
     // matches how `node:path` / `node:fs` handle the same cases.
     const conv = platformConventions({ platform: "aix" });
     assert.equal(conv.family, "posix");
-    assert.equal(conv.binaryLocator, "which");
+    assert.equal(conv.hookShellSuffix, " || true");
   });
 
   it("uses os.platform() when called without an override", () => {
@@ -94,7 +93,7 @@ describe("platformConventions", () => {
     assert.ok(Object.isFrozen(conv), "conventions object must be frozen");
     assert.throws(
       () => {
-        conv.binaryLocator = "pwned";
+        conv.hookShellSuffix = "pwned";
       },
       /Cannot assign to read only property/,
       "attempting to mutate a frozen convention must throw in strict mode",

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

@@ -40,6 +40,7 @@ import {
   restoreHome,
   assertHomeIsolated,
 } from "../helpers/sandbox-home.mjs";
+import { isolatePathEnv } from "../helpers/path-isolation.mjs";
 
 let sandbox;
 let originalCwd;
@@ -238,66 +239,67 @@ describe("buildHookCommand", () => {
   });
 });
 
-describe("resolveSkillrepoBinary — v3.1.1 Windows support", () => {
-  // These tests exercise the platform-specific locator branch
-  // (`where` on Windows, `which` elsewhere) and the Windows
-  // absolute-path check (`C:\...` not `/`). They use the
-  // `{ platform }` option to avoid relying on the host OS.
+describe("resolveSkillrepoBinary — Windows platform support", () => {
+  // These tests exercise the Windows-shaped lookup (Windows uses
+  // `<name>.cmd` and `<name>.exe` extensions; npm installs CLIs
+  // as `.cmd` shims). They use the `{ platform }` option to
+  // simulate Windows on a non-Windows host.
   //
-  // IMPORTANT: these tests DO NOT run a real `where.exe` subprocess
-  // on Linux/macOS CI (there is no `where` to run). Instead they
-  // verify the LOCATOR-SELECTION logic by checking that calling
-  // with `platform: "win32"` on a Unix host produces a null return
-  // (because `where` doesn't exist there) rather than a thrown
-  // error. That's sufficient to prove the platform branch works;
-  // actual Windows binary resolution is tested by the Windows CI
-  // smoke job added in .github/workflows/.
+  // **Process-state isolation matters here.** v3.1.3 switched
+  // `resolveBinaryOnPath` from a `which`/`where` shell-out to a
+  // pure-Node PATH scan. The pre-v3.1.3 tests relied on
+  // `where.exe` being absent on a Unix host to force the null
+  // return; with the pure-Node lookup, the test instead clears
+  // PATH so no candidate matches. Same outcome (null), different
+  // mechanism.
   //
-  // Behavioral coverage requires beforeEach/afterEach to clear npx
-  // signals (the function returns null early on npx regardless of
-  // platform). Reuses the isolate-process-state pattern from the
-  // isNpxInvocation tests.
+  // We also clear npx signals (argv[1], _) since the function
+  // returns null early on a transient-runner invocation
+  // regardless of platform.
   let originalArgv;
   let originalUnderscore;
+  let restorePath;
 
   beforeEach(() => {
     originalArgv = process.argv;
     originalUnderscore = process.env._;
     process.argv = ["/usr/local/bin/node", "/usr/local/bin/skillrepo"];
     delete process.env._;
+    restorePath = isolatePathEnv();
   });
 
   afterEach(() => {
     process.argv = originalArgv;
     if (originalUnderscore === undefined) delete process.env._;
     else process.env._ = originalUnderscore;
+    restorePath();
   });
 
-  it("does not throw when called with platform: 'win32' on a non-Windows host", async () => {
-    // On Linux/macOS there is no `where.exe` on PATH, so the
-    // execFileSync throws ENOENT. Our try/catch returns null —
-    // the same safe-skip path that fires when the binary isn't
-    // on PATH. Verifies the platform branch compiles cleanly
-    // without requiring a real Windows environment.
+  it("returns null under platform: 'win32' when no skillrepo.cmd/.exe is on PATH", async () => {
+    // The pure-Node PATH scan probes for `skillrepo.cmd`,
+    // `skillrepo.exe`, then bare `skillrepo` in each PATH
+    // directory. With PATH cleared to a non-existent dir, none
+    // exist, so we get null. This proves the Windows
+    // candidate-list branch behaves correctly on hosts that
+    // don't have a real Windows skillrepo install.
     const { resolveSkillrepoBinary } = await import(
-      "../../lib/mergers/session-hook.mjs?v311-win-test=" + Date.now()
+      "../../lib/mergers/session-hook.mjs?v313-win-test=" + Date.now()
     );
     const result = resolveSkillrepoBinary({ platform: "win32" });
     assert.equal(
       result,
       null,
-      "on a Unix host with platform:'win32', where.exe isn't available → null return (not throw)",
+      "platform:'win32' with no .cmd/.exe on PATH must return null",
     );
   });
 
-  it("mergeSessionHook under platform:'win32' routes to the architect's skipped path when binary can't be resolved", async () => {
-    // End-to-end test of the Windows binary-resolution path. When
-    // `where` isn't available (simulating a Windows environment
-    // where the user hasn't installed skillrepo globally), the
-    // installer must skip gracefully with the architect-specified
-    // reason — same as the Unix "no global install" fallback.
+  it("mergeSessionHook under platform:'win32' routes to the actionable skipped reason when binary can't be resolved", async () => {
+    // End-to-end test of the Windows binary-resolution path.
+    // With PATH cleared, no skillrepo.cmd is visible, so the
+    // installer must skip gracefully with the actionable reason —
+    // same as the Unix "no global install" fallback.
     const { mergeSessionHook: mergeFresh } = await import(
-      "../../lib/mergers/session-hook.mjs?v311-win-integration=" + Date.now()
+      "../../lib/mergers/session-hook.mjs?v313-win-integration=" + Date.now()
     );
     const tmpSandbox = mkdtempSync(join(tmpdir(), "cli-win-test-"));
     const originalCwd = process.cwd();
@@ -911,13 +913,24 @@ describe("mergeSessionHook — failure modes", () => {
     // gracefully with an actionable reason. Init bypasses this path
     // in v3.1.2 by passing the post-auto-install absolute path
     // explicitly via `binaryPath`.
+    //
+    // PATH isolation: v3.1.3's `resolveBinaryOnPath` scans PATH
+    // directly. If the dev's machine has skillrepo installed (most
+    // SkillRepo developers do), the scan would find it and the
+    // null-fallback wouldn't fire. Clear PATH for the duration of
+    // this test so the lookup genuinely returns null.
     ASSERT_HOME_ISOLATED();
-    const result = mergeSessionHook({ binaryPath: null });
-    assert.equal(result.action, "skipped");
-    assert.ok(result.reason);
-    // The remediation hint must mention `npm install -g` so the user
-    // has a copy-pasteable next step.
-    assert.match(result.reason, /npm install -g/);
+    const restorePath = isolatePathEnv();
+    try {
+      const result = mergeSessionHook({ binaryPath: null });
+      assert.equal(result.action, "skipped");
+      assert.ok(result.reason);
+      // The remediation hint must mention `npm install -g` so the user
+      // has a copy-pasteable next step.
+      assert.match(result.reason, /npm install -g/);
+    } finally {
+      restorePath();
+    }
   });
 
   it("v3.1.1 fix: returns 'skipped' under npx invocation even when `which skillrepo` would succeed", async () => {