@holmes-lab/holmes-kit 0.1.16 → 0.1.17

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.1.17] - 2026-08-23
+
+The two `main` lines — the Windows-compatibility line (12 commits, verified on Windows 11 and
+independently re-verified on macOS 26.5/APFS: 156/156 suites, gate probes over the `/tmp` →
+`/private/tmp` link spelling all as expected) and the mac release line (0.1.10–0.1.16) — are merged
+into one linear history in this release. Full suite on the merged tree: 191/191.
+
+### Added
+- **Windows Bootstrap Installer (REQ-253)**: `scripts/install.ps1`, a pure Windows PowerShell 5.1 script that runs *before* `npm install` and fixes what npm cannot — relocates out of protected directories (an elevated PowerShell opens in `C:\WINDOWS\System32`, where `npm install` fails with `EPERM`), substitutes a per-user `--prefix` when npm's global prefix is under `C:\Program Files\nodejs` (a second, distinct `EPERM`), gates on `engines.node`, and classifies native-build failures (`msbuild` / `python` / `node-gyp` / `network`) into the one `winget` command that fixes them. Non-interactive, idempotent, no persistent changes. Shipped in the package and documented as the recommended Windows install path. Measured end-to-end on a Windows 11 machine from `System32`: exit 0, no user input.
+
+### Fixed
+- **Path identity is canonical on every filesystem**: `resolveProjectRoot`, the containment gate, the store/derived checks and `resolveRmSignals` all canonicalise through `canonicalPath` (`fs.realpathSync.native`), closing an 8.3-short-name bypass on Windows while keeping the macOS `/tmp → /private/tmp` and case-folding behaviour — measured on both platforms, including mixed link/real spellings against the shipped hook.
+- **Drive-letter paths are absolute**: project containment no longer asks "is this POSIX-absolute" while meaning "is this absolute", so `C:\…` targets are governed on native Windows.
+- **Antigravity hook commands quote their paths**: a space in the install path no longer splits the command and silently disables the gate.
+- **Parser suites run on Windows**: `tsc`/`node` are spawned via `process.execPath`, `dist` is rebuilt only when stale, and `__test-support__` is excluded from `dist` and the npm package.
+- **Suites repaired for fresh checkouts**: the read-compat baseline fixture is tracked through a `.gitignore` re-inclusion chain, and `packaging.test.ts` asserts the CHANGELOG section of the *current* version instead of a stale literal.
+
+### Changed
+- **Spec renumbering**: the Windows installer slice had claimed REQ/H/A/T-SPEC-220, an id family the mac line had already assigned to *Windows Native Tier 1 Governance Parity*; the installer family is renumbered to REQ/H/A/T-SPEC-253 and re-sealed.
+
 ## [0.1.16] - 2026-08-23
 
 Predictable spec numbering — enforced at the door, and the corpus cleaned to match.

package/README.md

@@ -56,6 +56,16 @@ Holmes-Kit prioritizes **CLI-based AI Coding Agents** where OS-level process hoo
 The same wrong command was run three times by a real adopter before the right one; a table beats
 prose read top-to-bottom.
 
+**Windows (recommended)** — a bootstrap installer that runs *before* npm and fixes what npm cannot: it relocates out of protected folders (an elevated PowerShell opens in `C:\WINDOWS\System32`, where `npm install` fails with `EPERM`), checks the Node.js version, and, if a native module fails to build, prints the one `winget` command that installs the missing C++ toolchain instead of raw compiler output. Pure Windows PowerShell 5.1; no prompts; nothing persistent is changed.
+```powershell
+# From a downloaded copy of the package (e.g. after `npm pack`, or from a checkout):
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1
+
+# One-liner (once hosted):
+# irm https://<host>/install.ps1 | iex
+```
+Add `-DryRun` to see what it would do without installing. Exit codes: `0` ok / already installed · `2` bad argument · `3` Node.js too old · `4` npm failed (remediation printed) · `5` installed but not on `PATH` (prefix printed).
+
 | Which situation are you in? | Privileges | Command |
 |---|---|---|
 | **Using it in one project** (most people) | none | `npm install --save-dev @holmes-lab/holmes-kit` |

package/dist/.build-id

@@ -1 +1 @@
-3c84046-mt5fni4h
+e6199ca-mt5qbc5d

package/dist/holmes/cli/agents.js

@@ -93,19 +93,25 @@ const mcpConfig = (packageRoot, specsDir, launcher) => {
  * (Claude 배선이 `guardrail` 모드에서 좁은 매처를 쓰는 것과 다른 선택인데, 그쪽은 그 좁힘이
  * 무엇을 뜻하는지 문서화된 모드 선택이고 여기는 기본 배선이기 때문이다.)
  */
+// A hook `command` is ONE shell string, so the path must be quoted — `buildHookPlan` in init.ts has
+// always done this for the Claude wiring, and this one did not. Measured 2026-08-23 on a machine
+// whose home directory contains a space: the shell split the path, the hook never ran, and the
+// Antigravity gate was silently off. (The MCP config above is different: it passes `args` as an
+// array, where quoting would put literal quote characters into the path.)
+const hookCommand = (packageRoot, script) => `node "${path.join(packageRoot, 'bin', script)}"`;
 const hooksJson = (packageRoot) => `${JSON.stringify({
     'holmes-kit': {
         PreToolUse: [{
                 matcher: '*',
                 hooks: [{
                         type: 'command',
-                        command: `node ${path.join(packageRoot, 'bin', 'holmes-hook-antigravity.js')}`,
+                        command: hookCommand(packageRoot, 'holmes-hook-antigravity.js'),
                         timeout: 30,
                     }],
             }],
         Stop: [{
                 type: 'command',
-                command: `node ${path.join(packageRoot, 'bin', 'holmes-stop-antigravity.js')}`,
+                command: hookCommand(packageRoot, 'holmes-stop-antigravity.js'),
                 timeout: 30,
             }],
     },

package/dist/holmes/hooks/pre-tool-use.js

@@ -90,11 +90,14 @@ function resolveRmSignals(command, cwd) {
     let repoRoot;
     let baseReal;
     try {
-        repoRoot = (0, node_child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], { cwd, stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() })
-            .toString().trim();
-        // git realpaths the toplevel (resolves symlinks like macOS /var -> /private/var); resolve the
-        // cwd the same way so in-project containment comparisons don't spuriously fail on a symlinked path.
-        baseReal = fs.realpathSync(cwd);
+        // Both sides through the ONE canonicaliser. git prints the top-level symlink-resolved, with `/`
+        // separators on Windows and the long name; the JS realpath kept 8.3 aliases and `path.sep`
+        // comparisons below never matched `C:/…` against `C:\…`. Measured 2026-08-23: `rm -rf build`
+        // in a real repo read as inProject=false, so a gitignored build dir was escalated as if it were
+        // outside the project — fail-safe in direction, wrong in fact, and a needless HITL every time.
+        repoRoot = (0, root_1.canonicalPath)((0, node_child_process_1.execFileSync)('git', ['rev-parse', '--show-toplevel'], { cwd, stdio: ['ignore', 'pipe', 'ignore'], env: (0, root_1.cleanSubprocessEnv)() })
+            .toString().trim());
+        baseReal = (0, root_1.canonicalPath)(cwd);
     }
     catch {
         return undefined; // not a git repo / git unavailable -> static fallback
@@ -111,7 +114,7 @@ function resolveRmSignals(command, cwd) {
         // lexical path (nothing to delete yet); realpath errors fail safe to the lexical value.
         try {
             if (fs.existsSync(resolved))
-                resolved = fs.realpathSync(resolved);
+                resolved = (0, root_1.canonicalPath)(resolved);
         }
         catch { /* keep lexical */ }
         const inProject = resolved === repoRoot || resolved.startsWith(repoRoot + path.sep);
@@ -615,12 +618,17 @@ function evaluateHook(input, specsDir, opts) {
     // path under a symlinked ancestor (macOS `/tmp` → `/private/tmp` is the ordinary case) switched
     // the gate off. A bound that runs out must fail toward the gate, not away from it — so the walk
     // is not bounded by a count at all; it ends at the filesystem root, which always terminates.
+    // `canonicalPath` (realpathSync.native), not the JS realpath: the root arrives canonicalised by
+    // root.ts, which expands Windows 8.3 aliases; the JS realpath does not. Measured 2026-08-23 on
+    // the built hook — an in-project target spelled through `%TEMP%`'s alias (`C:\Users\SUNGNA~1\…`)
+    // resolved to a string the long-name root did not contain, and took the "outside → allow" exit
+    // below. Both sides must go through the one canonicaliser, or an alias is a free pass.
     const realOf = (abs) => {
         let head = abs;
         const tail = [];
         for (;;) {
             try {
-                return [fs.realpathSync(head).replace(/\\/g, '/'), ...tail].join('/');
+                return [(0, root_1.canonicalPath)(head).replace(/\\/g, '/'), ...tail].join('/');
             }
             catch { /* walk up */ }
             const parent = path.dirname(head);

package/dist/holmes/mcp/handlers.js

@@ -262,13 +262,13 @@ function boundNonceLedger(store) {
         // `--specs-dir docs/specs` an ordinary review_record could still plant `docs/specs/.ax` and move
         // every consumed nonce, every audit line, and spec_approve's notion of "this project" with it.
         const storeReal = (() => { try {
-            return fs.realpathSync(store.specsRoot);
+            return (0, root_2.canonicalPath)(store.specsRoot);
         }
         catch {
             return store.specsRoot;
         } })();
         const derivedReal = (() => { try {
-            return fs.realpathSync(derived);
+            return (0, root_2.canonicalPath)(derived);
         }
         catch {
             return derived;
@@ -301,13 +301,13 @@ function boundFindingsLedger(store, root) {
     try {
         const derived = projectRootOf(store.specsRoot);
         const storeReal = (() => { try {
-            return fs.realpathSync(store.specsRoot);
+            return (0, root_2.canonicalPath)(store.specsRoot);
         }
         catch {
             return store.specsRoot;
         } })();
         const derivedReal = (() => { try {
-            return fs.realpathSync(derived);
+            return (0, root_2.canonicalPath)(derived);
         }
         catch {
             return derived;

package/dist/holmes/project/change-source.js

@@ -189,7 +189,12 @@ class GitChangeSource {
         this.base = base;
         this.head = head;
         this.topLevel = (0, root_1.resolveProjectRoot)(root).git?.topLevel;
-        if (this.topLevel && fs.realpathSync(path.resolve(root)) !== this.topLevel) {
+        // The GIVEN root must be the top-level — `changes()` runs git against it, so a subdirectory
+        // (even one that walks up to the same `.ax`) would tag paths against the wrong base. Both sides
+        // go through ONE canonicaliser: the old `fs.realpathSync(root)` here was the JS realpath, which
+        // keeps Windows 8.3 aliases the top-level side had already expanded — measured 2026-08-23, the
+        // same directory spelled `C:\AI_PRO~1\…` threw as a mismatch.
+        if (this.topLevel && (0, root_1.canonicalPath)(path.resolve(root)) !== this.topLevel) {
             throw new Error(`GitChangeSource: root must be the git top-level (got ${root}, top-level is ${this.topLevel})`);
         }
     }

package/dist/holmes/project/root.d.ts

@@ -31,4 +31,17 @@ export interface ProjectRoot {
 }
 /** The marker directory that makes a directory a Holmes-Kit project. */
 export declare const MARKER = ".ax";
+/**
+ * The one canonical spelling of an existing path.
+ *
+ * `fs.realpathSync.native`, not `fs.realpathSync`. The JS implementation resolves symlinks only;
+ * on Windows it leaves 8.3 short-name aliases (`C:\Users\SUNGNA~1`, which is what `%TEMP%` and
+ * `os.tmpdir()` hand out) exactly as spelled, while `git rev-parse --show-toplevel` prints the
+ * long name. Measured 2026-08-23: `resolveProjectRoot('C:/AI_PRO~1/AX-COD~1')` reported
+ * `root: C:\AI_PRO~1\AX-COD~1` beside `git.topLevel: C:\ai_project\AX-Coding-Project` for ONE
+ * directory, and GitChangeSource refused it as a mismatch. The native call expands both symlinks
+ * and 8.3 names (a strict superset, same ENOENT behaviour), so `root` keeps the promise its type
+ * makes: one spelling per directory, the spelling every path key is built from.
+ */
+export declare const canonicalPath: (p: string) => string;
 export declare function resolveProjectRoot(dir: string): ProjectRoot;

package/dist/holmes/project/root.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MARKER = void 0;
+exports.canonicalPath = exports.MARKER = void 0;
 exports.cleanSubprocessEnv = cleanSubprocessEnv;
 exports.resolveProjectRoot = resolveProjectRoot;
 // @implements A-SPEC-205
@@ -56,6 +56,21 @@ function cleanSubprocessEnv(env = process.env) {
 }
 /** The marker directory that makes a directory a Holmes-Kit project. */
 exports.MARKER = '.ax';
+/**
+ * The one canonical spelling of an existing path.
+ *
+ * `fs.realpathSync.native`, not `fs.realpathSync`. The JS implementation resolves symlinks only;
+ * on Windows it leaves 8.3 short-name aliases (`C:\Users\SUNGNA~1`, which is what `%TEMP%` and
+ * `os.tmpdir()` hand out) exactly as spelled, while `git rev-parse --show-toplevel` prints the
+ * long name. Measured 2026-08-23: `resolveProjectRoot('C:/AI_PRO~1/AX-COD~1')` reported
+ * `root: C:\AI_PRO~1\AX-COD~1` beside `git.topLevel: C:\ai_project\AX-Coding-Project` for ONE
+ * directory, and GitChangeSource refused it as a mismatch. The native call expands both symlinks
+ * and 8.3 names (a strict superset, same ENOENT behaviour), so `root` keeps the promise its type
+ * makes: one spelling per directory, the spelling every path key is built from.
+ */
+const canonicalPath = (p) => fs.realpathSync.native(p);
+exports.canonicalPath = canonicalPath;
+const canonical = exports.canonicalPath;
 function gitTopLevel(dir) {
     try {
         // stderr silenced: "not a git repository" is an expected branch here, not a fault worth printing.
@@ -66,7 +81,7 @@ function gitTopLevel(dir) {
         }).trim();
         // git resolves symlinks in its output; realpath ours too so comparisons are like-for-like
         // (macOS /var -> /private/var otherwise makes an identical directory look like a mismatch).
-        return out ? fs.realpathSync(out) : undefined;
+        return out ? canonical(out) : undefined;
     }
     catch {
         return undefined;
@@ -75,7 +90,7 @@ function gitTopLevel(dir) {
 function resolveProjectRoot(dir) {
     let start;
     try {
-        start = fs.realpathSync(path.resolve(dir));
+        start = canonical(path.resolve(dir));
     }
     catch {
         // @implements A-SPEC-189 §7 (round 11) — this is a POINTED refusal about the caller's own

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",
@@ -13,6 +13,7 @@
     "bin/",
     "dist/",
     "playbooks/",
+    "scripts/install.ps1",
     "docs/install-guide.md",
     "CHANGELOG.md"
   ],

package/scripts/install.ps1

@@ -0,0 +1,297 @@
+<#
+.SYNOPSIS
+  Holmes-Kit bootstrap installer for Windows.  @implements A-SPEC-253
+.DESCRIPTION
+  Runs BEFORE npm to fix what npm cannot: a protected CWD (an elevated PowerShell opens in
+  C:\WINDOWS\System32 and `npm install` dies there with EPERM), an unwritable global prefix
+  (C:\Program Files\nodejs), a too-old Node.js, and native-build failures that print compiler
+  noise instead of the one command that installs the toolchain.  Then it runs
+  `npm install -g @holmes-lab/holmes-kit`.  Windows PowerShell 5.1 only; no prompts; nothing
+  persistent is changed.
+.PARAMETER DryRun   Run every check, print the npm command that WOULD run, exit 0 without running it.
+.PARAMETER Version  Package version to install (default: latest).
+.PARAMETER Prefix   Optional npm --prefix for the global install.
+.EXAMPLE
+  powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1 [-DryRun] [-Version 0.1.9]
+.NOTES
+  Exit codes: 0 ok / already installed, 2 argument error, 3 Node too old, 4 npm failed, 5 not on PATH.
+#>
+# Non-positional on purpose: otherwise `install.ps1 foo` binds `foo` to -Version and runs a REAL
+# `npm install -g @holmes-lab/holmes-kit@foo` from a typo.  Stray tokens land in $Rest -> exit 2.
+[CmdletBinding(PositionalBinding = $false)]
+param(
+  [Parameter(Mandatory = $false)][switch]$DryRun,
+  [Parameter(Mandatory = $false)][string]$Version = 'latest',
+  [Parameter(Mandatory = $false)][string]$Prefix,
+  [Parameter(Mandatory = $false, ValueFromRemainingArguments = $true)][string[]]$Rest
+)
+
+Set-StrictMode -Version 2.0
+$ErrorActionPreference = 'Stop'
+
+# Mirrors package.json#engines.node (">=20").  Bump both together.
+$script:NodeMajorFloor = 20
+$script:PackageName = '@holmes-lab/holmes-kit'
+$script:BinName = 'holmes-kit'
+
+# Failure classifier.  Pure: npm's combined output in, one token out.  Precedence is fixed so the
+# most ACTIONABLE cause wins when several signatures appear in the same transcript - an EPERM in a
+# protected directory also drags node-gyp down with it, and telling the user to install MSVC
+# would send them the wrong way.
+function Get-InstallFailureKind([string]$NpmOutput) {
+  if ($null -eq $NpmOutput) { $NpmOutput = '' }
+  # Two EPERMs, one code.  CWD (System32): relocating fixes it.  GLOBAL PREFIX (C:\Program Files\
+  # nodejs, the Node installer's default): only --prefix fixes it.  Measured 2026-08-23: after the
+  # relocation the install still died on `mkdir 'C:\Program Files\nodejs\node_modules\@holmes-lab'`.
+  # Keyed on the FAILING PATH line, not any mention of that directory: every npm stack trace names
+  # npm's own home under Program Files\nodejs\node_modules\npm, which is not the error.
+  if ($NpmOutput -match 'EPERM' -and $NpmOutput -match "(?m)^npm error path .*Program Files[\\/]+nodejs[\\/]+node_modules[\\/]+(?!npm[\\/])") { return 'eperm-prefix' }
+  if ($NpmOutput -match 'EPERM' -and ($NpmOutput -match 'mkdir' -or $NpmOutput -match 'System32' -or $NpmOutput -match 'Program Files')) { return 'eperm' }
+  if ($NpmOutput -match 'MSB\d{4}' -or $NpmOutput -match 'MSBuild' -or $NpmOutput -match 'Visual Studio' -or $NpmOutput -match 'vcvarsall') { return 'msbuild' }
+  if ($NpmOutput -match 'Could not find any Python' -or $NpmOutput -match 'gyp ERR! find Python') { return 'python' }
+  if ($NpmOutput -match 'node-gyp' -or $NpmOutput -match 'gyp ERR!') { return 'nodegyp-generic' }
+  if ($NpmOutput -match 'ENOTFOUND' -or $NpmOutput -match 'ETIMEDOUT' -or $NpmOutput -match 'ECONNRESET' -or $NpmOutput -match 'EAI_AGAIN') { return 'network' }
+  return 'none'
+}
+
+$script:Remediation = @{
+  'eperm' = @'
+npm was denied permission to create files in the current directory.
+This usually means the shell was opened in a protected system folder (e.g. C:\WINDOWS\System32).
+Re-run this installer (it relocates to your user profile automatically), or `cd` to a folder you own first.
+'@
+  'eperm-prefix' = @'
+npm's GLOBAL prefix is inside C:\Program Files\nodejs, which only an administrator can write.
+This installer passes a per-user prefix automatically; if you ran npm yourself, use one of:
+  npm install -g @holmes-lab/holmes-kit --prefix "$env:APPDATA\npm"      (this install only)
+  npm config set prefix "$env:APPDATA\npm"                                (every global install)
+and make sure that folder is on your user PATH (the Node.js installer normally adds it).
+'@
+  'msbuild' = @'
+A native module needed a C++ compiler and none was found.
+Install the Visual Studio Build Tools with the C++ workload (one command, ~2 GB):
+
+  winget install Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
+
+Then open a NEW terminal and re-run this installer.
+'@
+  'python' = @'
+node-gyp could not find a Python 3 interpreter (it needs one to drive the native build).
+
+  winget install Python.Python.3.12
+
+Then open a NEW terminal and re-run this installer.
+'@
+  'nodegyp-generic' = @'
+A native module failed to build and no prebuilt binary matched your Node.js version.
+Most often the C++ Build Tools are missing:
+  winget install Microsoft.VisualStudio.2022.BuildTools --override "--quiet --wait --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"
+If they are installed, try a current Node.js LTS (prebuilt binaries track LTS releases).
+'@
+  'network' = @'
+npm could not reach the registry (DNS / timeout / connection reset).
+Check your connection and proxy settings (`npm config get proxy`, `npm config get https-proxy`), then re-run.
+'@
+  'none' = @'
+npm exited with an error this installer does not recognise.  The last lines of its output are above.
+'@
+}
+
+# Stage helpers
+function Write-Stage([string]$Text) { Write-Host $Text }
+function Write-Problem([string]$Text) { [Console]::Error.WriteLine($Text) }
+
+function Get-NormalizedPath([string]$P) {
+  if ([string]::IsNullOrWhiteSpace($P)) { return $null }
+  $t = $P.TrimEnd('\', '/')
+  if ($t.Length -eq 2 -and $t[1] -eq ':') { $t = $t + '\' }   # 'C:' -> 'C:\' so the drive root compares as itself
+  return $t.ToLowerInvariant()
+}
+
+function Test-UnderRoot([string]$Candidate, [string]$Root) {
+  if ($null -eq $Root) { return $false }
+  if ($Candidate -eq $Root) { return $true }
+  $prefix = $Root
+  if (-not $prefix.EndsWith('\')) { $prefix = $prefix + '\' }  # separator first: C:\Windowsx is NOT under C:\Windows
+  return $Candidate.StartsWith($prefix)
+}
+
+function Test-ProtectedDirectory([string]$Dir) {
+  $here = Get-NormalizedPath $Dir
+  # The drive root is protected only when $PWD IS the root (C:\) - everything on the drive is
+  # under it, so treating it like the other roots would relocate every project on the machine.
+  $driveRoot = Get-NormalizedPath ([IO.Path]::GetPathRoot($Dir))
+  if ($null -ne $driveRoot -and $here -eq $driveRoot) { return $true }
+  $roots = @($env:SystemRoot, $env:ProgramFiles, ${env:ProgramFiles(x86)}, $env:ProgramData)
+  foreach ($r in $roots) {
+    if (Test-UnderRoot $here (Get-NormalizedPath $r)) { return $true }
+  }
+  return $false
+}
+
+function Test-WritableDirectory([string]$Dir) {
+  $probe = Join-Path $Dir ('.holmes-kit-write-probe-' + [Guid]::NewGuid().ToString('N'))
+  try {
+    New-Item -ItemType File -Path $probe -ErrorAction Stop | Out-Null
+    Remove-Item -LiteralPath $probe -Force -ErrorAction SilentlyContinue
+    return $true
+  } catch {
+    return $false
+  }
+}
+
+function Test-Elevated {
+  try {
+    $id = [Security.Principal.WindowsIdentity]::GetCurrent()
+    $p = New-Object Security.Principal.WindowsPrincipal($id)
+    return $p.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+  } catch { return $false }
+}
+
+function Get-NodeVersionString {
+  $cmd = Get-Command node -ErrorAction SilentlyContinue
+  if ($null -eq $cmd) { return $null }
+  try { return ((& node --version) | Select-Object -First 1).Trim() } catch { return $null }
+}
+
+function Get-InstalledVersion {
+  $cmd = Get-Command $script:BinName -ErrorAction SilentlyContinue
+  if ($null -eq $cmd) { return $null }
+  try {
+    $out = (& $script:BinName --version 2>$null) | Select-Object -First 1
+    if ($out -match '(\d+\.\d+\.\d+[^\s]*)') { return $Matches[1] }
+    return $null
+  } catch { return $null }
+}
+
+function Get-NpmPrefix {
+  # Skipped in -DryRun only when npm is absent; otherwise it is a local config read, no network.
+  $r = Invoke-Npm @('config', 'get', 'prefix')
+  if ($r.Code -ne 0) { return $null }
+  $v = $r.Output.Trim()
+  if ([string]::IsNullOrWhiteSpace($v) -or $v -eq 'undefined') { return $null }
+  return $v
+}
+
+function Invoke-Npm([string[]]$Arguments) {
+  # Array arguments, never one interpolated string; npm is npm.cmd on Windows and needs the
+  # .cmd resolution that `&` performs.  Both streams are merged so the classifier sees everything.
+  $npm = Get-Command npm.cmd -ErrorAction SilentlyContinue
+  if ($null -eq $npm) { $npm = Get-Command npm -ErrorAction SilentlyContinue }
+  if ($null -eq $npm) { return @{ Code = 127; Output = 'npm was not found on PATH' } }
+  $prev = $ErrorActionPreference
+  $ErrorActionPreference = 'Continue'   # a native command writing to stderr must not throw here
+  try {
+    $lines = & $npm.Source @Arguments 2>&1 | ForEach-Object { "$_" }
+    $code = $LASTEXITCODE
+  } finally {
+    $ErrorActionPreference = $prev
+  }
+  return @{ Code = $code; Output = ($lines -join "`n") }
+}
+
+# Pipeline
+function Invoke-Main {
+  # Stage 0 - arguments
+  if ($null -ne $Rest -and $Rest.Count -gt 0) {
+    Write-Problem ("Unrecognised argument(s): " + ($Rest -join ' '))
+    Write-Problem 'Usage: install.ps1 [-DryRun] [-Version <string>] [-Prefix <dir>]'
+    return 2
+  }
+  if ([string]::IsNullOrWhiteSpace($Version)) { $Version = 'latest' }
+
+  # Stage 1 - directory guard.  Relocate, report, never ask.
+  $cwd = (Get-Location).Path
+  $protected = Test-ProtectedDirectory $cwd
+  $writable = $false
+  if (-not $protected) { $writable = Test-WritableDirectory $cwd }
+  if ($protected -or -not $writable) {
+    $home_ = $env:USERPROFILE
+    Write-Stage ("Relocating: {0} is a protected or read-only directory; continuing from {1}" -f $cwd, $home_)
+    Set-Location -LiteralPath $home_
+  }
+
+  # Stage 2 - elevation notice (warn, continue)
+  if (Test-Elevated) {
+    Write-Stage 'Note: this shell is elevated. A global npm install from here may land in a per-machine prefix that your normal (non-admin) terminal does not see. A regular user shell is recommended.'
+  }
+
+  # Stage 3 - Node version gate
+  $nodeV = Get-NodeVersionString
+  $major = -1
+  if ($null -ne $nodeV -and $nodeV -match '^v?(\d+)\.(\d+)\.(\d+)') { $major = [int]$Matches[1] }
+  if ($major -lt $script:NodeMajorFloor) {
+    $found = $nodeV
+    if ($null -eq $found) { $found = 'none' }
+    Write-Problem ("Node.js >= {0} is required (found {1}). Install from https://nodejs.org/" -f $script:NodeMajorFloor, $found)
+    return 3
+  }
+  Write-Stage ("Node.js {0} OK" -f $nodeV)
+
+  # Stage 4 - idempotence
+  $installed = Get-InstalledVersion
+  if ($null -ne $installed) {
+    $want = $Version
+    if ($want -eq 'latest' -and -not $DryRun) {
+      $view = Invoke-Npm @('view', $script:PackageName, 'version')
+      if ($view.Code -eq 0) { $want = $view.Output.Trim() }
+    }
+    if ($want -ne 'latest' -and $installed -eq $want) {
+      Write-Stage ("already installed ({0})" -f $installed)
+      return 0
+    }
+    Write-Stage ("holmes-kit {0} is installed; will install {1}" -f $installed, $Version)
+  }
+
+  # Stage 4b - prefix guard.  A non-elevated shell cannot write the Node installer's default
+  # prefix (C:\Program Files\nodejs) and Stage 1 does not help.  Per-user prefix for THIS call
+  # only; the user's npm config is never modified (REQ-253 Constraint 2).
+  if ([string]::IsNullOrWhiteSpace($Prefix) -and -not (Test-Elevated)) {
+    $cur = Get-NpmPrefix
+    if ($null -ne $cur -and (Test-ProtectedDirectory $cur)) {
+      $Prefix = Join-Path $env:APPDATA 'npm'
+      Write-Stage ("npm's global prefix ({0}) is not writable without elevation; using --prefix {1} for this install" -f $cur, $Prefix)
+    }
+  }
+
+  # Stage 5 - npm install
+  $spec = '{0}@{1}' -f $script:PackageName, $Version
+  $npmArgs = @('install', '-g', $spec)
+  $display = 'npm install -g "{0}"' -f $spec
+  if (-not [string]::IsNullOrWhiteSpace($Prefix)) {
+    $npmArgs += @('--prefix', $Prefix)
+    $display = $display + (' --prefix "{0}"' -f $Prefix)
+  }
+  if ($DryRun) {
+    Write-Stage ('DRY-RUN: ' + $display)
+    return 0
+  }
+  Write-Stage ('Running: ' + $display)
+  $r = Invoke-Npm $npmArgs
+  if ($r.Code -ne 0) {
+    $kind = Get-InstallFailureKind $r.Output
+    $tail = ($r.Output -split "`n") | Select-Object -Last 15
+    Write-Problem '--- npm output (last 15 lines) ---'
+    foreach ($l in $tail) { Write-Problem $l }
+    Write-Problem '--- what to do ---'
+    Write-Problem $script:Remediation[$kind]
+    return 4
+  }
+
+  # Stage 6 - PATH verification
+  $cmd = Get-Command $script:BinName -ErrorAction SilentlyContinue
+  if ($null -eq $cmd) {
+    $pfx = (Invoke-Npm @('config', 'get', 'prefix')).Output.Trim()
+    Write-Problem ("holmes-kit installed but {0} is not on PATH for this shell. Open a new terminal, or add it to your user PATH." -f $pfx)
+    return 5
+  }
+  $v = Get-InstalledVersion
+  Write-Stage ("holmes-kit {0} installed" -f $v)
+  return 0
+}
+
+# Dot-sourcing (`. .\install.ps1`) loads the functions for testing and does NOT run the pipeline.
+if ($MyInvocation.InvocationName -ne '.') {
+  $code = Invoke-Main
+  exit $code
+}