skillrepo 3.1.0 → 3.1.1

package/README.md

@@ -142,7 +142,9 @@ Installs (or removes) a Claude Code [SessionStart hook](https://docs.claude.com/
 
 By default `skillrepo init` prompts you to install this hook. If you said no (or passed `--no-session-sync`), run `session-sync enable` later to turn it on.
 
-**The hook cannot block your session.** The command it runs is `skillrepo update --session-hook 2>&1 || true`. That flag makes `update` exit 0 on every failure — network outage, revoked key, disk error, anything — and print a single-line failure message to your session. The `|| true` shell backstop catches anything that escapes. Session starts are never blocked by sync failures.
+**Requires a stable global install.** The hook is skipped (with a clear warning) when `skillrepo init` is invoked via `npx`, because the npx cache path is transient and the baked-in hook command would break on the next cache eviction. Install globally with `npm install -g skillrepo` before running `session-sync enable`.
+
+**The hook cannot block your session.** The command it runs is `<path-to-skillrepo> update --session-hook 2>&1 [|| true]`. The `--session-hook` flag makes `update` exit 0 on every failure — network outage, revoked key, disk error, anything — and print a single-line failure message to your session. On POSIX systems the `|| true` shell backstop is appended as belt-and-suspenders; on Windows it's omitted because cmd.exe doesn't know the `true` builtin (the `--session-hook` flag's exit-0 contract is the primary defense regardless of platform). Session starts are never blocked by sync failures.
 
 **On 304 (nothing changed) the hook is silent.** You only see output when your library actually syncs or a failure happens. No "Syncing…" noise on every session.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillrepo",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Pull-based CLI for agent skills — init, sync, search, add, remove your library from any IDE",
   "type": "module",
   "bin": {

package/src/commands/init.mjs

@@ -43,7 +43,7 @@
 import { validateAccessKey } from "../lib/http.mjs";
 import { detectIdes, formatDetectedIdes } from "../lib/detect-ides.mjs";
 import { readConfig, writeConfig } from "../lib/config.mjs";
-import { resolveFlags, effectiveVendors } from "../lib/cli-config.mjs";
+import { resolveFlags, effectiveVendors, isNpxInvocation } from "../lib/cli-config.mjs";
 import { mergeMcpForVendors, printManualMcpInstructions } from "../lib/mcp-merge.mjs";
 import { runSync } from "../lib/sync.mjs";
 import { mergeEnvLocal } from "../lib/mergers/env-local.mjs";
@@ -519,16 +519,46 @@ export async function runInit(argv, io = {}) {
       updated: 0,
       removed: 0,
       notModified: false,
+      // On a synthesized failure summary we genuinely don't know
+      // whether the sync WOULD have been full or delta — the network
+      // call never completed. Architect review (v3.1.1) flagged that
+      // emitting `fullSync: false` here is misleading for --json
+      // consumers: it looks like a legitimate "delta sync returned
+      // zero" signal. Using `null` makes the unknown-state
+      // explicit — any typed consumer must handle it separately
+      // from true/false. The always-present `sync.failureReason`
+      // field is still the authoritative "did the sync fail"
+      // indicator; fullSync is just additional context.
+      fullSync: null,
       syncedAt: new Date().toISOString(),
     };
   }
 
+  const zeroDeltas =
+    syncSummary.added + syncSummary.updated + syncSummary.removed === 0;
+
   if (syncFailedReason) {
     // The warning already printed; the step-summary success line
     // would be misleading, so we skip it. Any helpful "next steps"
     // is in the final `SkillRepo is ready` block.
-  } else if (syncSummary.notModified || syncSummary.added + syncSummary.updated + syncSummary.removed === 0) {
+  } else if (syncSummary.notModified) {
+    // 304 Not Modified — the client had the current ETag already.
+    // Definitively "up to date" regardless of whether the library
+    // is empty or populated.
+    p.success("Library is up to date.");
+  } else if (zeroDeltas && syncSummary.fullSync) {
+    // Full sync (no prior .last-sync state existed) with zero
+    // results — the account's library is genuinely empty.
     p.success("No skills in library yet (add some with `skillrepo add @owner/name`)");
+  } else if (zeroDeltas) {
+    // Delta sync with zero results — nothing changed since the
+    // last sync. Could be zero skills total, or N skills all
+    // unchanged. Without a full-sync roundtrip we can't tell, so
+    // the accurate phrasing is "no changes." Before this fix, the
+    // init step-7 message conflated this with the truly-empty
+    // case, which lied to any user who had skills but had already
+    // synced them on a prior run.
+    p.success("Library is up to date (no changes since last sync).");
   } else {
     p.success(
       `${syncSummary.added} added, ${syncSummary.updated} updated, ${syncSummary.removed} removed`,
@@ -581,10 +611,27 @@ export async function runInit(argv, io = {}) {
   }
 
   stdout.write("\n  ✓ SkillRepo is ready.\n\n");
+  // Pick the command prefix the user can actually run. If they
+  // invoked init via `npx skillrepo ...`, bare `skillrepo list` will
+  // fail with "command not found" — they need `npx skillrepo list`.
+  // Under a global install, the bare command is correct. We default
+  // to bare and add the `npx` prefix ONLY when we can detect the
+  // current invocation is npx.
+  const prefix = isNpxInvocation() ? "npx skillrepo" : "skillrepo";
   stdout.write("  Next steps:\n");
-  stdout.write("    • skillrepo list    — see what's in your library\n");
-  stdout.write("    • skillrepo search <query>  — find skills\n");
-  stdout.write("    • skillrepo add @owner/name — add a skill\n\n");
+  stdout.write(`    • ${prefix} list    — see what's in your library\n`);
+  stdout.write(`    • ${prefix} search <query>  — find skills\n`);
+  stdout.write(`    • ${prefix} add @owner/name — add a skill\n`);
+  if (isNpxInvocation()) {
+    // Soft recommendation: running under npx works but every command
+    // re-downloads the package. Global install is faster AND enables
+    // the session-sync feature (which requires a stable binary path).
+    stdout.write(
+      "\n  Tip: `npm install -g skillrepo` for faster commands " +
+        "and to enable session-start sync.\n",
+    );
+  }
+  stdout.write("\n");
 }
 
 /**

package/src/lib/artifact-registry.mjs

@@ -88,8 +88,48 @@ export const VSCODE_INPUT_ID = "skillrepo-api-key";
 /**
  * Substring that identifies a SessionStart hook command entry as
  * SkillRepo-owned. The #884 installer writes a hook whose `command`
- * field contains `skillrepo update --session-hook`; any entry whose
- * command contains this substring is removed by the uninstall path.
+ * field ends with `<binary-path> update --session-hook ...`; any
+ * entry whose command contains ` update --session-hook` (with the
+ * leading space) is removed by the uninstall path.
+ *
+ * The leading space is a lightweight word boundary — it requires
+ * that `update` is preceded by whitespace (i.e. it's an argv token
+ * after the binary path), not a suffix of a longer identifier like
+ * `toolupdate` or `postupdate`. Without the space, a hypothetical
+ * binary at `/usr/local/bin/myapp-update` invoked with
+ * `--session-hook` as `/usr/local/bin/myapp-update --session-hook`
+ * would NOT match (because the substring would be `-update
+ * --session-hook`, not ` update --session-hook`), whereas a naive
+ * `update --session-hook` fingerprint would have.
+ *
+ * The leading space does NOT eliminate all false-positive classes.
+ * A command like `brew update --session-hook` DOES match the
+ * fingerprint — the space between `brew` and `update` is exactly
+ * what we key on. The primary protection against real-world false
+ * positives is the specificity of the two-token combination
+ * `update --session-hook` itself: `--session-hook` is not a
+ * conventional flag name used by tools other than SkillRepo, so the
+ * chance of a coincidental match is astronomically low. The test
+ * at `session-hook.test.mjs` "the fingerprint is specific enough
+ * that innocuous user hooks do NOT match it" enumerates plausible
+ * user-hook commands and confirms none trip the predicate.
+ *
+ * The fingerprint is also deliberately platform-neutral. Earlier
+ * versions matched the longer `skillrepo update --session-hook`
+ * substring, but that pattern silently fails to match Windows hook
+ * commands because npm installs the CLI as a `.cmd` shim — the
+ * absolute path on Windows ends `...\skillrepo.cmd`, which puts the
+ * `.cmd` extension between `skillrepo` and `update` in the command
+ * string. The shorter ` update --session-hook` substring is present
+ * on both:
+ *   POSIX:   `/usr/local/bin/skillrepo update --session-hook 2>&1 || true`
+ *   Windows: `C:\path\skillrepo.cmd update --session-hook 2>&1`
+ *
+ * Backward-compat: any v3.1.0 hook contains
+ * `skillrepo update --session-hook`, which is a strict superset of
+ * ` update --session-hook` (the space between `skillrepo` and `update`
+ * is the space we're matching). So upgrades still correctly identify
+ * and update the old entry in place.
  *
  * Exported so #884's installer can import and use the same constant —
  * this is the module boundary that makes #884 depend on #885 rather
@@ -97,7 +137,7 @@ export const VSCODE_INPUT_ID = "skillrepo-api-key";
  * 5.3) notes the bidirectional-fingerprint requirement; centralizing
  * it here enforces it at the language level.
  */
-export const SESSION_HOOK_FINGERPRINT = "skillrepo update --session-hook";
+export const SESSION_HOOK_FINGERPRINT = " update --session-hook";
 
 // ── Artifact descriptors ────────────────────────────────────────────
 

package/src/lib/cli-config.mjs

@@ -1,6 +1,11 @@
 /**
  * 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
@@ -21,6 +26,70 @@ 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
@@ -85,6 +154,15 @@ export function resolveFlags(argv, opts = {}) {
     } else if (arg === "--help" || arg === "-h") {
       // Dispatcher should have intercepted this. Defensive no-op.
       continue;
+    } else if (arg === "--verbose") {
+      // Global flag set by the dispatcher into SKILLREPO_VERBOSE=1
+      // so http.mjs's retry logger can honor it. It's a first-class
+      // flag, not an unknown arg — accept it silently in every
+      // command that passes through resolveFlags. Before this
+      // branch existed, any command that consumed argv via
+      // resolveFlags rejected `--verbose` with "Unknown argument",
+      // breaking the flag documented in the top-level --help.
+      continue;
     } else {
       // Allow the caller to consume a positional arg before we treat
       // it as unknown. This is how `get @owner/name` and

package/src/lib/config.mjs

@@ -43,10 +43,10 @@ import {
   unlinkSync,
 } from "node:fs";
 import { dirname } from "node:path";
-import { platform } from "node:os";
 
 import { globalConfigPath } from "./paths.mjs";
 import { diskError, validationError } from "./errors.mjs";
+import { platformConventions } from "./platform.mjs";
 
 /**
  * Current schema version. Bump this on any structural change.
@@ -187,8 +187,11 @@ export function writeConfig(config) {
 
   // chmod the temp file before renaming so the destination never
   // exists with world-readable perms (which would be a brief
-  // credential leak window on a shared system).
-  if (platform() !== "win32") {
+  // credential leak window on a shared system). Windows callers
+  // route through platformConventions().supportsPosixPermissions —
+  // see platform.mjs for why we skip chmod there instead of pretend-
+  // applying it.
+  if (platformConventions().supportsPosixPermissions) {
     try {
       chmodSync(tmpPath, 0o600);
     } catch {

package/src/lib/file-write.mjs

@@ -50,7 +50,6 @@ import {
   statSync,
 } from "node:fs";
 import { dirname, join, isAbsolute, relative } from "node:path";
-import { platform } from "node:os";
 
 import { readFileSafe, writeFileSafe } from "./fs-utils.mjs";
 import {
@@ -63,6 +62,7 @@ import {
   gitignorePath,
 } from "./paths.mjs";
 import { CliError, validationError, diskError } from "./errors.mjs";
+import { platformConventions } from "./platform.mjs";
 
 // ── Constants (mirror the server-side validators in src/lib/skills/) ────
 
@@ -562,8 +562,13 @@ function writeSkillToDir(skill, targetDir) {
     }
   }
 
-  // 2 + 3 + 4: rename dance (POSIX atomic on same filesystem; best-effort on Windows)
-  if (platform() === "win32") {
+  // 2 + 3 + 4: rename dance. POSIX is atomic on the same filesystem;
+  // Windows has to do remove-then-rename because renameSync fails on
+  // existing directory targets. The split is named via
+  // platformConventions().supportsAtomicDirectoryRename so the intent
+  // reads as a capability check, not a platform check. See
+  // platform.mjs for the rationale.
+  if (!platformConventions().supportsAtomicDirectoryRename) {
     // Windows: rename fails on existing destinations and locked files,
     // so we fall back to remove-then-rename. There is a window where
     // the live target is gone but the rename has not yet completed.

package/src/lib/fs-utils.mjs

@@ -14,6 +14,7 @@ import {
   unlinkSync,
 } from "node:fs";
 import { dirname } from "node:path";
+import { platformConventions } from "./platform.mjs";
 
 /**
  * Read a file as UTF-8, returning null if it doesn't exist.
@@ -44,15 +45,6 @@ export function writeFileSafe(filePath, content) {
   writeFileSync(filePath, content, "utf-8");
 }
 
-/**
- * Write a file and mark it executable (0o755).
- * Used for the Cursor session hook which is invoked directly via shebang.
- */
-export function writeExecutable(filePath, content) {
-  writeFileSafe(filePath, content);
-  chmodSync(filePath, 0o755);
-}
-
 /**
  * Check if a path exists (file or directory).
  */
@@ -105,7 +97,7 @@ export function writeFileAtomic(filePath, content, { mode } = {}) {
     throw new Error(`Cannot write ${tmpPath}: ${err.message}`, { cause: err });
   }
 
-  if (mode !== undefined && process.platform !== "win32") {
+  if (mode !== undefined && platformConventions().supportsPosixPermissions) {
     try {
       chmodSync(tmpPath, mode);
     } catch {
@@ -115,6 +107,13 @@ export function writeFileAtomic(filePath, content, { mode } = {}) {
       // file after the write.
     }
   }
+  // On Windows we deliberately skip chmod entirely. Node lets the call
+  // succeed on Windows but the mode bits don't map to anything the
+  // ACL layer enforces, so a "success" return would mislead the caller
+  // into thinking the credential file is access-restricted when it
+  // isn't. Windows users needing per-user protection should rely on
+  // %APPDATA%'s inherited ACLs (which default to the current user) or
+  // apply DACL restrictions at the OS level — outside this CLI's scope.
 
   try {
     renameSync(tmpPath, filePath);

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

@@ -71,6 +71,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
+import { isAbsolute } from "node:path";
 import { writeFileAtomic } from "../fs-utils.mjs";
 import { SESSION_HOOK_FINGERPRINT } from "../artifact-registry.mjs";
 import {
@@ -79,21 +80,43 @@ import {
 } from "../paths.mjs";
 import { diskError, validationError } from "../errors.mjs";
 import { removeSettingsSessionHook } from "../removers/settings.mjs";
+import { isNpxInvocation } from "../cli-config.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.
+ *
+ * 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 });
+  return `${binaryPath} update --session-hook 2>&1${conv.hookShellSuffix}`;
 }
 
 /**
@@ -104,27 +127,56 @@ export function buildHookCommand(binaryPath) {
  *
  * @returns {string | null}
  */
-export function resolveSkillrepoBinary() {
+export function resolveSkillrepoBinary({ platform: platformOverride } = {}) {
+  // npx-invocation guard. Returns null early before any OS-specific
+  // logic runs — npx detection is platform-neutral (argv and env
+  // checks only) so it doesn't need the conventions object.
+  if (isNpxInvocation()) {
+    return null;
+  }
+
+  // Platform-specific binary locator name comes from the single
+  // source of truth in platform.mjs. Adding a new locator for a
+  // new platform is one edit in platform.mjs, not a scattered
+  // search for `platform() === "win32"` conditionals. See
+  // platform.mjs for the full rationale.
+  const conv = platformConventions({ platform: platformOverride });
+
   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"], {
+    // 3-second timeout — `which`/`where` typically return in
+    // milliseconds, but a PATH that includes a network filesystem
+    // or a shell alias that does I/O could hang indefinitely.
+    // Bounding the call ensures `skillrepo init` never stalls on
+    // binary resolution.
+    const raw = execFileSync(conv.binaryLocator, ["skillrepo"], {
       encoding: "utf-8",
       stdio: ["ignore", "pipe", "ignore"],
       timeout: 3000,
-    }).trim();
+    });
+    // Windows `where` can return multiple matching paths (one per
+    // PATH entry containing the binary) on separate lines. Take
+    // only the first. `which` always returns a single path but the
+    // split is harmless there. This is the one line where the
+    // platform difference actually leaks through — all platforms
+    // receive potentially-multi-line output that we canonicalize
+    // the same way.
+    const result = raw.split(/\r?\n/)[0].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;
+    // 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. `isAbsolute`
+    // handles both POSIX (`/foo/bar`) and Windows (`C:\foo\bar`)
+    // path styles — it's Node's built-in cross-platform check,
+    // not a platform-conditional we need to own.
+    if (!isAbsolute(result)) 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.
+    // Locator exits non-zero if the binary isn't on PATH, or throws
+    // ENOENT if the locator itself isn't available (e.g. a minimal
+    // container image without `which`, or a Windows system with
+    // `where.exe` missing which is effectively never — but still
+    // safe-handled). Either way: null → caller routes to the
+    // architect-specified "requires stable install" skip message.
     return null;
   }
 }
@@ -140,6 +192,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 +220,41 @@ 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. The
+    // architect's #884 design specified the same warning text for
+    // both cases.
     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. " +
+        "Under `npx skillrepo ...` or without a global install, the " +
+        "hook would bind to a transient path that eventually breaks. " +
+        "Install globally with `npm install -g skillrepo` and 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-