skillrepo 3.1.0 → 3.1.2

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

@@ -34,49 +34,67 @@ import {
 } from "../../lib/mergers/session-hook.mjs";
 import { removeSettingsSessionHook } from "../../lib/removers/settings.mjs";
 import { SESSION_HOOK_FINGERPRINT } from "../../lib/artifact-registry.mjs";
+import {
+  captureHome,
+  setSandboxHome,
+  restoreHome,
+  assertHomeIsolated,
+} from "../helpers/sandbox-home.mjs";
 
 let sandbox;
 let originalCwd;
-let originalHome;
+/** @type {import("../helpers/sandbox-home.mjs").HomeEnvSnapshot} */
+let originalHomeEnv;
 const FAKE_BINARY = "/usr/local/bin/skillrepo";
 
 function ASSERT_HOME_ISOLATED() {
-  assert.ok(
-    process.env.HOME && process.env.HOME.startsWith(tmpdir()),
-    `HOME must point inside tmpdir during session-hook tests. ` +
-      `Current HOME="${process.env.HOME}" — setup() forgot the override.`,
-  );
+  // Thin wrapper around the shared helper. Checks BOTH HOME and
+  // USERPROFILE so Windows is actually guarded — `os.homedir()`
+  // reads USERPROFILE on Windows, and an assertion that checked
+  // only HOME would pass while real user state was at risk.
+  assertHomeIsolated(tmpdir(), "session-hook tests");
 }
 
 function setup() {
   sandbox = mkdtempSync(join(tmpdir(), "cli-session-hook-"));
   originalCwd = process.cwd();
-  originalHome = process.env.HOME;
+  originalHomeEnv = captureHome();
   mkdirSync(join(sandbox, "project"), { recursive: true });
   mkdirSync(join(sandbox, "home"), { recursive: true });
   process.chdir(join(sandbox, "project"));
-  process.env.HOME = join(sandbox, "home");
+  setSandboxHome(join(sandbox, "home"));
   ASSERT_HOME_ISOLATED();
 }
 
 function teardown() {
   process.chdir(originalCwd);
-  process.env.HOME = originalHome;
+  restoreHome(originalHomeEnv);
   if (sandbox) rmSync(sandbox, { recursive: true, force: true });
 }
 
 // ──────────────────────────────────────────────────────────────────
 
 describe("buildHookCommand", () => {
-  it("produces the exact command shape Claude Code expects", () => {
-    // INTENT: the shape is load-bearing in three ways (per the
-    // installer's docstring): absolute path, --session-hook flag,
-    // `|| true` backstop. A refactor that drops any of the three
-    // must fail this test loudly.
-    const cmd = buildHookCommand("/usr/local/bin/skillrepo");
+  it("produces the exact command shape Claude Code expects (POSIX)", () => {
+    // INTENT: the shape is load-bearing in four ways (per the
+    // installer's docstring): absolute path, single-quoted to
+    // tolerate spaces/parens, --session-hook flag, `|| true`
+    // backstop. A refactor that drops any of the four must fail
+    // this test loudly.
+    //
+    // The `platform: "linux"` override is explicit because this test
+    // asserts the POSIX command shape. Without it, the test runs
+    // under `os.platform()` — which is `win32` on the Windows CI
+    // runner and correctly drops `|| true`, causing a spurious
+    // failure against an assertion that was written for POSIX.
+    // Platform-specific shapes are covered by the dedicated POSIX/
+    // Windows tests below; this one is the POSIX-shape contract.
+    const cmd = buildHookCommand("/usr/local/bin/skillrepo", {
+      platform: "linux",
+    });
     assert.equal(
       cmd,
-      "/usr/local/bin/skillrepo update --session-hook 2>&1 || true",
+      "'/usr/local/bin/skillrepo' update --session-hook 2>&1 || true",
     );
   });
 
@@ -94,6 +112,121 @@ describe("buildHookCommand", () => {
     );
   });
 
+  it("v3.1.1 Windows support: buildHookCommand OMITS '|| true' on Windows", () => {
+    // INTENT: cmd.exe doesn't understand the `true` builtin. If we
+    // leave `|| true` on Windows, a binary-missing scenario emits a
+    // confusing "'true' is not recognized" error. Windows hook
+    // commands drop the shell backstop; the `--session-hook` flag's
+    // exit-0 contract inside the Node process is the primary
+    // defense regardless of platform.
+    const cmd = buildHookCommand("C:\\Program Files\\node\\skillrepo.cmd", {
+      platform: "win32",
+    });
+    assert.doesNotMatch(
+      cmd,
+      /\|\| true/,
+      "Windows hook command must NOT contain '|| true'",
+    );
+    assert.match(
+      cmd,
+      /skillrepo\.cmd" update --session-hook 2>&1$/,
+      "Windows hook command ends at '2>&1' — no shell backstop, with closing quote on the path",
+    );
+    // Fingerprint still present — remover round-trip must work on
+    // Windows too.
+    assert.ok(cmd.includes(SESSION_HOOK_FINGERPRINT));
+  });
+
+  it("v3.1.1 Windows support: buildHookCommand keeps '|| true' on POSIX", () => {
+    const cmd = buildHookCommand("/usr/local/bin/skillrepo", { platform: "linux" });
+    assert.match(
+      cmd,
+      /\|\| true$/,
+      "POSIX hook command must retain the '|| true' shell backstop",
+    );
+    const cmdDarwin = buildHookCommand("/usr/local/bin/skillrepo", { platform: "darwin" });
+    assert.match(cmdDarwin, /\|\| true$/);
+  });
+
+  it("v3.1.2: POSIX path with spaces is single-quoted", () => {
+    // Real-world case: macOS users with a space in their home dir
+    // (`/Users/First Last/.npm-global/bin/skillrepo`). The unquoted
+    // command would be parsed by the shell as multiple arguments
+    // and silently fail on session start.
+    const cmd = buildHookCommand(
+      "/Users/First Last/.npm-global/bin/skillrepo",
+      { platform: "linux" },
+    );
+    assert.equal(
+      cmd,
+      "'/Users/First Last/.npm-global/bin/skillrepo' update --session-hook 2>&1 || true",
+    );
+    // Fingerprint still present after quoting.
+    assert.ok(cmd.includes(SESSION_HOOK_FINGERPRINT));
+  });
+
+  it("v3.1.2: POSIX path with single quote escapes correctly ('\\\\'')", () => {
+    // Hardcore edge case: a path with a literal single quote. POSIX
+    // shells require closing the quote, escaping the literal `'`,
+    // then reopening — the standard `'\\''` trick.
+    const cmd = buildHookCommand("/Users/J's bin/skillrepo", {
+      platform: "linux",
+    });
+    assert.equal(
+      cmd,
+      "'/Users/J'\\''s bin/skillrepo' update --session-hook 2>&1 || true",
+    );
+    assert.ok(cmd.includes(SESSION_HOOK_FINGERPRINT));
+  });
+
+  it("v3.1.2: Windows path with spaces is double-quoted", () => {
+    // Real-world: `C:\Program Files\nodejs\skillrepo.cmd` and
+    // `C:\Program Files (x86)\...`. cmd.exe needs double quotes;
+    // backslashes inside double quotes are NOT escape characters
+    // (they pass through to the resolved path verbatim).
+    const cmd = buildHookCommand(
+      "C:\\Program Files\\nodejs\\skillrepo.cmd",
+      { platform: "win32" },
+    );
+    assert.equal(
+      cmd,
+      '"C:\\Program Files\\nodejs\\skillrepo.cmd" update --session-hook 2>&1',
+    );
+    assert.ok(cmd.includes(SESSION_HOOK_FINGERPRINT));
+  });
+
+  it("v3.1.2: Windows path with parentheses (Program Files (x86)) is preserved verbatim inside double quotes", () => {
+    const cmd = buildHookCommand(
+      "C:\\Program Files (x86)\\node\\skillrepo.cmd",
+      { platform: "win32" },
+    );
+    assert.ok(cmd.startsWith('"C:\\Program Files (x86)\\node\\skillrepo.cmd"'));
+    assert.ok(cmd.includes(SESSION_HOOK_FINGERPRINT));
+  });
+
+  it("v3.1.2: backward-compat — fingerprint matches both unquoted (v3.1.0/3.1.1) and quoted (v3.1.2+) shapes", () => {
+    // The fingerprint is `" update --session-hook"` with a leading
+    // space. That space sits between the path's closing context
+    // (a `'`/`"` quote in v3.1.2, the bare path char in v3.1.0/3.1.1)
+    // and `update`. Both shapes contain the leading-space substring.
+    // Without this contract, an upgrade from v3.1.1 to v3.1.2 would
+    // duplicate the hook entry instead of updating it in place.
+    const v311Posix =
+      "/usr/local/bin/skillrepo update --session-hook 2>&1 || true";
+    const v312Posix =
+      "'/usr/local/bin/skillrepo' update --session-hook 2>&1 || true";
+    const v311Win =
+      "C:\\path\\skillrepo.cmd update --session-hook 2>&1";
+    const v312Win =
+      '"C:\\path\\skillrepo.cmd" update --session-hook 2>&1';
+    for (const cmd of [v311Posix, v312Posix, v311Win, v312Win]) {
+      assert.ok(
+        cmd.includes(SESSION_HOOK_FINGERPRINT),
+        `fingerprint must match shape: ${cmd}`,
+      );
+    }
+  });
+
   it("rejects empty or non-string binary paths", () => {
     // INTENT: no silent production of a malformed command. The
     // installer upstream should never pass null/empty, but defensive
@@ -105,6 +238,338 @@ 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.
+  //
+  // 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/.
+  //
+  // 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.
+  let originalArgv;
+  let originalUnderscore;
+
+  beforeEach(() => {
+    originalArgv = process.argv;
+    originalUnderscore = process.env._;
+    process.argv = ["/usr/local/bin/node", "/usr/local/bin/skillrepo"];
+    delete process.env._;
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+    if (originalUnderscore === undefined) delete process.env._;
+    else process.env._ = originalUnderscore;
+  });
+
+  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.
+    const { resolveSkillrepoBinary } = await import(
+      "../../lib/mergers/session-hook.mjs?v311-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)",
+    );
+  });
+
+  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.
+    const { mergeSessionHook: mergeFresh } = await import(
+      "../../lib/mergers/session-hook.mjs?v311-win-integration=" + Date.now()
+    );
+    const tmpSandbox = mkdtempSync(join(tmpdir(), "cli-win-test-"));
+    const originalCwd = process.cwd();
+    const originalHomeEnvLocal = captureHome();
+    mkdirSync(join(tmpSandbox, "project"), { recursive: true });
+    mkdirSync(join(tmpSandbox, "home"), { recursive: true });
+    process.chdir(join(tmpSandbox, "project"));
+    setSandboxHome(join(tmpSandbox, "home"));
+
+    try {
+      // Explicitly pass binaryPath: null so the test doesn't rely
+      // on resolveSkillrepoBinary. This is a different check —
+      // verifying the downstream skipped-with-reason path works
+      // identically regardless of what caused the null.
+      const result = mergeFresh({ binaryPath: null });
+      assert.equal(result.action, "skipped");
+      assert.ok(result.reason);
+      assert.match(
+        result.reason,
+        /stable.*skillrepo/i,
+        "Windows skipped path must surface the same user-actionable message as POSIX",
+      );
+    } finally {
+      process.chdir(originalCwd);
+      restoreHome(originalHomeEnvLocal);
+      rmSync(tmpSandbox, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("v3.1.1 Windows hook: fingerprint + round-trip contract", () => {
+  // The fingerprint SESSION_HOOK_FINGERPRINT is the substring that
+  // lets the uninstaller identify SkillRepo-owned hook entries.
+  // These tests lock the contract from BOTH platform ends: the
+  // Windows command shape must contain the fingerprint, and the
+  // remover must strip what the Windows builder produces. If the
+  // refactor that produced platform.mjs ever drifts the two sides,
+  // one of these tests fails before any user ships.
+  beforeEach(setup);
+  afterEach(teardown);
+
+  // A realistic Windows npm-install shim path. `npm install -g` on
+  // Windows drops three launchers into `%AppData%\npm\`:
+  //   skillrepo       (bash shim, used by Git Bash via shell lookup)
+  //   skillrepo.cmd   (cmd.exe shim)
+  //   skillrepo.ps1   (PowerShell shim)
+  //
+  // `where skillrepo` matches files whose extension appears in
+  // `%PATHEXT%`. The default PATHEXT is
+  // `.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC` — `.cmd`
+  // is in that list, `.ps1` usually isn't, and the extension-less
+  // bash shim never appears in `where`'s output because `where`
+  // only matches extensions from PATHEXT. So in practice `where
+  // skillrepo` returns a single line ending in `.cmd` — that's the
+  // path we must exercise. The CLI's resolver takes the first line
+  // regardless, so even on a system with a custom PATHEXT that
+  // surfaces `.ps1` first, the first-line rule still produces a
+  // usable absolute path.
+  const WIN_SHIM_PATH = "C:\\Users\\alice\\AppData\\Roaming\\npm\\skillrepo.cmd";
+
+  it("fingerprint is platform-neutral: POSIX and Windows command shapes both contain it", () => {
+    // This is the test that would have caught the v3.1.1-dev bug
+    // where the fingerprint was `"skillrepo update --session-hook"`
+    // (the longer form) and the Windows `.cmd` path broke the
+    // substring match because the extension intrudes between
+    // `skillrepo` and `update`. If this assertion fires, the
+    // fingerprint has regressed and Windows hook identification is
+    // broken.
+    const posixCmd = buildHookCommand("/usr/local/bin/skillrepo", {
+      platform: "darwin",
+    });
+    const windowsCmd = buildHookCommand(WIN_SHIM_PATH, { platform: "win32" });
+
+    assert.ok(
+      posixCmd.includes(SESSION_HOOK_FINGERPRINT),
+      `POSIX command "${posixCmd}" must include fingerprint "${SESSION_HOOK_FINGERPRINT}"`,
+    );
+    assert.ok(
+      windowsCmd.includes(SESSION_HOOK_FINGERPRINT),
+      `Windows command "${windowsCmd}" must include fingerprint "${SESSION_HOOK_FINGERPRINT}". ` +
+        `The Windows shim path ends in .cmd, which the earlier fingerprint ` +
+        `"skillrepo update --session-hook" failed to match.`,
+    );
+  });
+
+  it("backward compat: pre-v3.1.1 hooks (with longer fingerprint) still match the new shorter fingerprint", () => {
+    // Users who ran `skillrepo init` under v3.1.0 have a hook whose
+    // command contains the LONGER fingerprint "skillrepo update
+    // --session-hook". The shorter v3.1.1 fingerprint "update
+    // --session-hook" must still be a substring of every legacy
+    // command — otherwise upgrading breaks uninstall for every
+    // existing user. This test is the backward-compat gate.
+    const legacyPosixCommand =
+      "/usr/local/bin/skillrepo update --session-hook 2>&1 || true";
+    assert.ok(
+      legacyPosixCommand.includes(SESSION_HOOK_FINGERPRINT),
+      `Legacy v3.1.0 POSIX hook "${legacyPosixCommand}" must still be ` +
+        `identifiable by the v3.1.1 fingerprint "${SESSION_HOOK_FINGERPRINT}" — ` +
+        `if this fires, upgrading breaks uninstall for existing users.`,
+    );
+  });
+
+  it("Windows hook round-trip: installer + remover identify the same .cmd-shim command", () => {
+    // End-to-end proof that on Windows, the hook written by the
+    // installer is the hook found by the remover. We can't spawn a
+    // real where.exe on macOS/Linux CI, so we simulate the Windows
+    // result by (1) asking buildHookCommand for the Windows shape
+    // and (2) writing that exact command into a settings file,
+    // then (3) invoking the remover and verifying the hook is
+    // gone. This exercises the fingerprint match against a real
+    // Windows-shaped command string.
+    ASSERT_HOME_ISOLATED();
+    const windowsCmd = buildHookCommand(WIN_SHIM_PATH, { platform: "win32" });
+
+    mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+    writeFileSync(
+      join(process.cwd(), ".claude", "settings.local.json"),
+      JSON.stringify(
+        {
+          hooks: {
+            SessionStart: [
+              { hooks: [{ type: "command", command: windowsCmd }] },
+            ],
+          },
+        },
+        null,
+        2,
+      ),
+    );
+
+    const removeResult = removeSettingsSessionHook();
+    assert.equal(
+      removeResult.action,
+      "removed",
+      "Remover must identify a Windows-shaped hook command. If this fires, " +
+        "SESSION_HOOK_FINGERPRINT has drifted from what buildHookCommand " +
+        "produces on Windows — the .cmd extension likely intrudes between " +
+        "`skillrepo` and `update`.",
+    );
+  });
+
+  it("mergeSessionHook under platform:'win32' writes a Windows-shaped command end-to-end", () => {
+    // INTENT: the architect's round-3 HIGH finding. mergeSessionHook
+    // must propagate the platform override through to buildHookCommand
+    // so a non-Windows CI host can still prove that a real Windows
+    // user would receive a command WITHOUT `|| true` — cmd.exe
+    // doesn't understand the `true` builtin.
+    //
+    // Before round 3, this test documented its own gap: `mergeSessionHook`
+    // didn't accept a platform option, so passing a Windows-shaped
+    // binaryPath still produced a POSIX command (because buildHookCommand
+    // read os.platform() directly). Passing only the fingerprint check
+    // gave false confidence. Fixing this closes that gap — the assertion
+    // now verifies the Windows command shape end-to-end against real
+    // file I/O.
+    ASSERT_HOME_ISOLATED();
+
+    const installResult = mergeSessionHook({
+      binaryPath: WIN_SHIM_PATH,
+      platform: "win32",
+    });
+    assert.equal(installResult.action, "installed");
+
+    const parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    const cmd = parsed.hooks.SessionStart[0].hooks[0].command;
+
+    // 1. Fingerprint present — installer/remover round-trip works.
+    assert.ok(
+      cmd.includes(SESSION_HOOK_FINGERPRINT),
+      `Hook with Windows-shaped binaryPath must contain the fingerprint. Got: "${cmd}"`,
+    );
+    // 2. No `|| true` backstop — cmd.exe can't execute it.
+    assert.ok(
+      !cmd.includes("|| true"),
+      `Windows hook must NOT contain "|| true" — cmd.exe has no such builtin. Got: "${cmd}"`,
+    );
+    // 3. Command ends exactly at "2>&1" — sanity on the full shape.
+    //    The closing `"` is the path's wrapping quote (v3.1.2:
+    //    paths are quoted to tolerate spaces).
+    assert.ok(
+      cmd.endsWith(`skillrepo.cmd" update --session-hook 2>&1`),
+      `Windows hook command must end at "2>&1". Got: "${cmd}"`,
+    );
+
+    // Remover identifies and strips the Windows-shaped hook.
+    const removeResult = removeSettingsSessionHook();
+    assert.equal(removeResult.action, "removed");
+  });
+
+  it("mergeSessionHook under platform:'linux' still writes the POSIX `|| true` backstop", () => {
+    // Inverse guard: a test that asserts the POSIX path still emits
+    // `|| true` so a refactor that accidentally inverts the platform
+    // check (or a bug in platform.mjs that swaps the conventions)
+    // fails loudly here instead of silently stripping the backstop
+    // from every POSIX user's hook.
+    ASSERT_HOME_ISOLATED();
+
+    const installResult = mergeSessionHook({
+      binaryPath: "/usr/local/bin/skillrepo",
+      platform: "linux",
+    });
+    assert.equal(installResult.action, "installed");
+
+    const parsed = JSON.parse(
+      readFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        "utf-8",
+      ),
+    );
+    const cmd = parsed.hooks.SessionStart[0].hooks[0].command;
+    assert.ok(
+      cmd.endsWith("|| true"),
+      `POSIX hook command must end with "|| true". Got: "${cmd}"`,
+    );
+  });
+
+  it("buildHookCommand contract: Windows command shape has NO `|| true` suffix", () => {
+    // Explicit contract: on Windows, cmd.exe doesn't know `true`,
+    // so the shell backstop MUST be omitted. A regression that
+    // adds `|| true` back to the Windows command would cause every
+    // session with a missing binary to emit "'true' is not
+    // recognized as an internal or external command". The
+    // --session-hook exit-0 contract in the Node process is the
+    // only defense on Windows, by design.
+    const windowsCmd = buildHookCommand(WIN_SHIM_PATH, { platform: "win32" });
+    assert.ok(
+      !windowsCmd.includes("|| true"),
+      `Windows hook command must not contain "|| true" — cmd.exe has no such builtin. ` +
+        `Got: "${windowsCmd}"`,
+    );
+    assert.ok(
+      windowsCmd.endsWith("2>&1"),
+      `Windows command must end at "2>&1" — no backstop appended. Got: "${windowsCmd}"`,
+    );
+  });
+
+  it("the fingerprint is specific enough that innocuous user hooks do NOT match it", () => {
+    // Guard against false-positives on the shorter fingerprint.
+    // User-authored SessionStart hooks shouldn't happen to match
+    // `update --session-hook` by accident. Enumerate a few
+    // plausible user commands and verify they don't trip the
+    // predicate. If a new one starts matching, the fingerprint is
+    // too loose and needs tightening.
+    const plausibleUserCommands = [
+      "echo 'session started'",
+      "/usr/local/bin/claude-sync update",
+      "git status",
+      "npm update --save",
+      "brew update --quiet",
+      "some-other-tool --session-start",
+      // The closest plausible miss: a different CLI whose flags
+      // happen to include `--session-hook`. This is so specific
+      // (two-flag combination with a space between) that inventing
+      // a real conflicting command is hard, but document the limit.
+      "other-tool --session-begin",
+    ];
+    for (const userCmd of plausibleUserCommands) {
+      assert.ok(
+        !userCmd.includes(SESSION_HOOK_FINGERPRINT),
+        `User command "${userCmd}" must NOT match fingerprint ` +
+          `"${SESSION_HOOK_FINGERPRINT}" — false-positive means uninstall ` +
+          `would delete user-authored hooks.`,
+      );
+    }
+  });
+});
+
 describe("mergeSessionHook — install fresh", () => {
   beforeEach(setup);
   afterEach(teardown);
@@ -260,7 +725,13 @@ describe("mergeSessionHook — idempotency", () => {
       1,
       "still exactly one SkillRepo hook (not duplicated)",
     );
-    assert.ok(skillrepoHooks[0].command.startsWith("/new/path/skillrepo"));
+    // Path is shell-quoted (v3.1.2: see buildHookCommand docstring)
+    // so the absolute path appears INSIDE the command rather than
+    // at position 0.
+    assert.ok(
+      skillrepoHooks[0].command.includes("/new/path/skillrepo"),
+      `updated hook must use new path, got: ${skillrepoHooks[0].command}`,
+    );
   });
 });
 
@@ -435,15 +906,65 @@ describe("mergeSessionHook — failure modes", () => {
   afterEach(teardown);
 
   it("returns 'skipped' (not a throw) when the binary cannot be resolved", () => {
-    // INTENT: an npx user without a global install must not have
-    // init abort — skip session sync with a warning, let the rest
-    // of init complete. Passing `binaryPath: null` explicitly
-    // simulates the `which skillrepo` resolution failing.
+    // INTENT: a caller passing `binaryPath: null` (e.g. session-sync
+    // enable under npx) must not have the action throw. Skip
+    // gracefully with an actionable reason. Init bypasses this path
+    // in v3.1.2 by passing the post-auto-install absolute path
+    // explicitly via `binaryPath`.
     ASSERT_HOME_ISOLATED();
     const result = mergeSessionHook({ binaryPath: null });
     assert.equal(result.action, "skipped");
     assert.ok(result.reason);
-    assert.match(result.reason, /global install/i);
+    // The remediation hint must mention `npm install -g` so the user
+    // has a copy-pasteable next step.
+    assert.match(result.reason, /npm install -g/);
+  });
+
+  it("v3.1.1 fix: returns 'skipped' under npx invocation even when `which skillrepo` would succeed", async () => {
+    // Regression guard for the v3.1.0 shipped bug: `which skillrepo`
+    // finds the transient npx cache path and returns it as if it
+    // were a stable install location. The hook command baked in at
+    // install time then points at `~/.npm/_npx/<hash>/.../skillrepo`
+    // which disappears on npm cache eviction or version bump.
+    //
+    // This test exercises the FIX path: `resolveSkillrepoBinary` now
+    // calls `isNpxInvocation()` BEFORE `which`, and returns null if
+    // npx is detected. That null propagates to mergeSessionHook,
+    // which returns `skipped` with the architect's intended reason.
+    ASSERT_HOME_ISOLATED();
+
+    // Simulate the npx invocation via process.argv[1]. The real
+    // invocation would have the npx-cache path as argv[1] and npx
+    // would put its bin dir on PATH — but simulating argv alone is
+    // sufficient to exercise the isNpxInvocation check.
+    const originalArgv = process.argv;
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.npm/_npx/abc123/node_modules/.bin/skillrepo",
+    ];
+
+    try {
+      // Call WITHOUT passing binaryPath explicitly — forces the
+      // resolveSkillrepoBinary() path to run, which must detect npx
+      // and return null.
+      const { mergeSessionHook: mergeFresh } = await import(
+        "../../lib/mergers/session-hook.mjs?v311-npx-test=" + Date.now()
+      );
+      const result = mergeFresh();
+      assert.equal(
+        result.action,
+        "skipped",
+        "npx invocation must skip session-sync install",
+      );
+      assert.ok(result.reason, "skipped action must carry a reason");
+      assert.match(
+        result.reason,
+        /stable.*skillrepo/i,
+        "reason must mention the stable-binary requirement",
+      );
+    } finally {
+      process.argv = originalArgv;
+    }
   });
 
   it("throws diskError on unparseable settings file", () => {
@@ -462,6 +983,185 @@ describe("mergeSessionHook — failure modes", () => {
       /Cannot parse/i,
     );
   });
+
+  it("v3.1.2 bypass: explicit binaryPath under npx → 'updated' when prior _npx-cache hook exists", async () => {
+    // QA gap fix: the bypass-via-binaryPath contract must work
+    // for ALL three success states (installed/updated/unchanged),
+    // not just "installed" (the empty-disk case). This test
+    // exercises "updated" — pre-seed a hook with an _npx cache
+    // path command, then call merge with an explicit non-npx
+    // binaryPath, assert action is "updated" and the new path
+    // replaced the cache path.
+    ASSERT_HOME_ISOLATED();
+
+    const originalArgv = process.argv;
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.npm/_npx/abc123/node_modules/.bin/skillrepo",
+    ];
+
+    try {
+      // Pre-seed a v3.1.0-style hook with an _npx cache path baked
+      // in (the bug v3.1.1 was trying to prevent).
+      mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+      const STALE_NPX_PATH =
+        "/Users/alice/.npm/_npx/abc123/node_modules/.bin/skillrepo";
+      const stalePath = join(
+        process.cwd(),
+        ".claude",
+        "settings.local.json",
+      );
+      writeFileSync(
+        stalePath,
+        JSON.stringify(
+          {
+            hooks: {
+              SessionStart: [
+                {
+                  hooks: [
+                    {
+                      type: "command",
+                      command: `${STALE_NPX_PATH} update --session-hook 2>&1 || true`,
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+          null,
+          2,
+        ),
+      );
+
+      const { mergeSessionHook: mergeFresh } = await import(
+        "../../lib/mergers/session-hook.mjs?v312-updated-test=" + Date.now()
+      );
+      const POST_INSTALL_PATH = "/usr/local/bin/skillrepo";
+      const result = mergeFresh({ binaryPath: POST_INSTALL_PATH });
+
+      assert.equal(
+        result.action,
+        "updated",
+        "stale _npx hook with new binaryPath must be 'updated', not 'installed' or 'skipped'",
+      );
+      // The on-disk file must reflect the new path, not the cache.
+      const written = JSON.parse(readFileSync(stalePath, "utf-8"));
+      const cmd = written.hooks.SessionStart[0].hooks[0].command;
+      assert.ok(
+        cmd.includes(POST_INSTALL_PATH),
+        `updated hook must use new path, got: ${cmd}`,
+      );
+      assert.ok(
+        !cmd.includes("_npx"),
+        "updated hook must NOT leak the prior _npx cache path",
+      );
+    } finally {
+      process.argv = originalArgv;
+    }
+  });
+
+  it("v3.1.2 bypass: explicit binaryPath under npx → 'unchanged' when same hook already present", async () => {
+    // The third success state — repeated init with the same
+    // global. Idempotency: no file write, action is "unchanged".
+    ASSERT_HOME_ISOLATED();
+
+    const originalArgv = process.argv;
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.npm/_npx/abc123/node_modules/.bin/skillrepo",
+    ];
+
+    try {
+      const POST_INSTALL_PATH = "/usr/local/bin/skillrepo";
+      const { buildHookCommand: buildFresh, mergeSessionHook: mergeFresh } =
+        await import(
+          "../../lib/mergers/session-hook.mjs?v312-unchanged-test=" + Date.now()
+        );
+      const expectedCmd = buildFresh(POST_INSTALL_PATH);
+
+      // Pre-seed the EXACT command we'd write — idempotent re-run.
+      mkdirSync(join(process.cwd(), ".claude"), { recursive: true });
+      writeFileSync(
+        join(process.cwd(), ".claude", "settings.local.json"),
+        JSON.stringify(
+          {
+            hooks: {
+              SessionStart: [
+                {
+                  hooks: [{ type: "command", command: expectedCmd }],
+                },
+              ],
+            },
+          },
+          null,
+          2,
+        ),
+      );
+
+      const result = mergeFresh({ binaryPath: POST_INSTALL_PATH });
+      assert.equal(
+        result.action,
+        "unchanged",
+        "identical hook with same binaryPath must be 'unchanged'",
+      );
+      assert.equal(result.command, expectedCmd);
+    } finally {
+      process.argv = originalArgv;
+    }
+  });
+
+  it("v3.1.2: explicit binaryPath bypasses the isNpxInvocation guard", async () => {
+    // INTENT: init's v3.1.2 auto-install flow runs `npm install -g
+    // skillrepo` itself under npx, then calls mergeSessionHook with
+    // the resulting absolute path passed explicitly via `binaryPath`.
+    // The internal `resolveSkillrepoBinary` early-returns under npx —
+    // but when the caller already has the binary path, that guard
+    // must NOT block the install. The `binaryPath` parameter is the
+    // bypass mechanism.
+    //
+    // This test is the lock-in for the v3.1.2 contract: explicit
+    // `binaryPath` short-circuits the npx detection. If a future
+    // refactor moves the npx guard into mergeSessionHook itself
+    // (rather than resolveSkillrepoBinary), this test fails — and
+    // it should.
+    ASSERT_HOME_ISOLATED();
+
+    const originalArgv = process.argv;
+    process.argv = [
+      "/usr/local/bin/node",
+      "/Users/alice/.npm/_npx/abc123/node_modules/.bin/skillrepo",
+    ];
+
+    try {
+      const { mergeSessionHook: mergeFresh, buildHookCommand: buildFresh } =
+        await import(
+          "../../lib/mergers/session-hook.mjs?v312-bypass-test=" + Date.now()
+        );
+      // Pass an absolute, stable path explicitly — the kind init's
+      // auto-install flow obtains from `resolveGlobalBinary()` after
+      // a successful `npm install -g`.
+      const POST_INSTALL_PATH = "/usr/local/bin/skillrepo";
+      const result = mergeFresh({ binaryPath: POST_INSTALL_PATH });
+      assert.equal(
+        result.action,
+        "installed",
+        "explicit binaryPath under npx must succeed, not skip",
+      );
+      // The hook command must contain the explicit path (not the
+      // _npx cache path).
+      assert.equal(result.command, buildFresh(POST_INSTALL_PATH));
+      assert.ok(
+        result.command.includes(POST_INSTALL_PATH),
+        "hook command must use the explicit path verbatim",
+      );
+      assert.ok(
+        !result.command.includes("_npx"),
+        "hook command must NOT leak the _npx cache path",
+      );
+    } finally {
+      process.argv = originalArgv;
+    }
+  });
 });
 
 describe("removeSessionHook — inverse of install", () => {