@blackbelt-technology/pi-agent-dashboard 0.3.0 → 0.4.0

package/packages/server/src/package-manager-wrapper.ts

@@ -2,12 +2,118 @@
  * Thin adapter around pi's DefaultPackageManager.
  * Serializes operations (one at a time), forwards progress events,
  * and triggers session reload on success.
+ *
+ * Pi module resolution is delegated to the shared `ToolRegistry`
+ * (`resolveModule("pi-coding-agent")`). All strategy chains, caching,
+ * and diagnostic trails live there — see change: consolidate-tool-resolution.
  */
 import * as os from "node:os";
 import * as path from "node:path";
 import * as crypto from "node:crypto";
-import { pathToFileURL } from "node:url";
-import { execSync } from "node:child_process";
+import {
+  getDefaultRegistry,
+  ModuleResolutionError,
+  type ToolRegistry,
+  type Resolution,
+} from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
+import {
+  getDefaultSubprocessAdapter,
+  type SubprocessAdapter,
+} from "@blackbelt-technology/pi-dashboard-shared/platform/subprocess-adapter.js";
+
+/**
+ * Resolve a command name through the tool registry's executor API.
+ * If the name is registered (e.g. "npm", "openspec", "pi"), returns
+ * the full executor argv — on Windows this is `[node.exe, <script>.js]`
+ * bypassing .cmd shims. Otherwise returns `[command, ...args]` verbatim
+ * so callers fall through to buildSafeArgv's generic handling.
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+function resolveViaRegistry(
+  registry: ToolRegistry,
+  command: string,
+  args: readonly string[],
+): string[] {
+  if (registry.has(command)) {
+    const exec = registry.resolveExecutor(command);
+    if (exec.ok && exec.argv.length > 0) {
+      return [...exec.argv, ...args];
+    }
+  }
+  return [command, ...args];
+}
+
+/**
+ * Subclass of pi's `DefaultPackageManager` that routes every subprocess
+ * through our OS-aware `SubprocessAdapter`. Pi's upstream implementation
+ * spawns with `shell: process.platform === "win32"` and no `windowsHide`,
+ * which on Windows triggers Node issue #21825 — flashing cmd console
+ * every time pi shells out to npm / git / etc.
+ *
+ * This class overrides the three spawn methods pi exposes on its own
+ * class (`spawnCommand`, `spawnCaptureCommand`, `runCommandSync`) and
+ * delegates them to the adapter. Other methods inherit unchanged;
+ * pi's internal `runCommand` / `runCommandCapture` call the overridden
+ * methods via `this.spawnCommand(...)` so they pick up the safe
+ * behaviour automatically.
+ *
+ * Constructor factory takes the base `DefaultPackageManager` class as
+ * input so we can extend it dynamically at runtime (pi is loaded via
+ * the tool registry's `resolveModule`, not a static import).
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+function createSafePackageManagerClass(
+  BaseClass: new (...args: any[]) => any,
+  adapter: SubprocessAdapter,
+  registry: ToolRegistry,
+): new (...args: any[]) => any {
+  return class SafePackageManager extends BaseClass {
+    // `spawnCommand` — used by pi for fire-and-forget installs where
+    // stdout/stderr are inherited (or piped for capture). Returns the
+    // live ChildProcess.
+    //
+    // Registry resolution: `command` arrives as "npm" / "git" etc.
+    // For registered executor tools this becomes `[node.exe, cli.js]`
+    // on Windows, bypassing .cmd entirely.
+    spawnCommand(command: string, args: readonly string[], options?: { cwd?: string; env?: NodeJS.ProcessEnv }) {
+      const [cmd, ...finalArgs] = resolveViaRegistry(registry, command, args);
+      return adapter.spawn(cmd, finalArgs, {
+        cwd: options?.cwd,
+        stdio: "inherit",
+      });
+    }
+
+    // `spawnCaptureCommand` — used by pi when it wants to read stdout /
+    // stderr programmatically (e.g. `npm root -g`, `npm view <pkg>`).
+    spawnCaptureCommand(command: string, args: readonly string[], options?: { cwd?: string; env?: NodeJS.ProcessEnv }) {
+      const [cmd, ...finalArgs] = resolveViaRegistry(registry, command, args);
+      return adapter.spawn(cmd, finalArgs, {
+        cwd: options?.cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: options?.env ? { ...process.env, ...options.env } : process.env,
+      });
+    }
+
+    // `runCommandSync` — used for quick synchronous checks.
+    runCommandSync(command: string, args: readonly string[]) {
+      const [cmd, ...finalArgs] = resolveViaRegistry(registry, command, args);
+      const result = adapter.spawnSync<string>(cmd, finalArgs, {
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+      });
+      if (result.status !== 0) {
+        const stderr = typeof result.stderr === "string" ? result.stderr : String(result.stderr ?? "");
+        const stdout = typeof result.stdout === "string" ? result.stdout : String(result.stdout ?? "");
+        throw new Error(`Failed to run ${command} ${args.join(" ")}: ${stderr || stdout}`);
+      }
+      const stdout = typeof result.stdout === "string" ? result.stdout : String(result.stdout ?? "");
+      return stdout.trim();
+    }
+  };
+}
+
 export interface ProgressEvent {
   type: "start" | "progress" | "complete" | "error";
   action: "install" | "remove" | "update" | "clone" | "pull";
@@ -15,52 +121,35 @@ export interface ProgressEvent {
   message?: string;
 }
 
-/** Lazily import pi's PackageManager (optional peer dependency). */
-let piModuleCache: { DefaultPackageManager: any; SettingsManager: any } | null = null;
-
-async function loadPiPackageManager() {
-  if (piModuleCache) return piModuleCache;
-
-  // Try direct import first (works if installed as a dependency)
-  try {
-    const mod = await import("@mariozechner/pi-coding-agent") as any;
-    if (mod.DefaultPackageManager) {
-      piModuleCache = { DefaultPackageManager: mod.DefaultPackageManager, SettingsManager: mod.SettingsManager };
-      return piModuleCache;
-    }
-  } catch { /* fall through to global resolution */ }
-
-  // Try managed install at ~/.pi-dashboard/node_modules/ (Electron portable/standalone)
-  const managedDir = path.join(os.homedir(), ".pi-dashboard");
-  for (const pkgName of ["@mariozechner/pi-coding-agent", "@oh-my-pi/pi-coding-agent"]) {
-    try {
-      const entryPath = path.join(managedDir, "node_modules", pkgName, "dist", "index.js");
-      const mod = await import(pathToFileURL(entryPath).href);
-      if (mod.DefaultPackageManager) {
-        piModuleCache = { DefaultPackageManager: mod.DefaultPackageManager, SettingsManager: mod.SettingsManager };
-        return piModuleCache;
-      }
-    } catch { /* fall through */ }
-  }
+/** Pi-coding-agent's public surface, as consumed by this wrapper. */
+interface PiModule {
+  DefaultPackageManager: any;
+  SettingsManager: any;
+}
 
-  // Resolve from global npm install (pi is typically installed globally)
-  for (const pkgName of ["@mariozechner/pi-coding-agent", "@oh-my-pi/pi-coding-agent"]) {
-    try {
-      const npmRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 10_000 }).trim();
-      const entryPath = path.join(npmRoot, pkgName, "dist", "index.js");
-      const mod = await import(pathToFileURL(entryPath).href);
-      if (mod.DefaultPackageManager) {
-        piModuleCache = { DefaultPackageManager: mod.DefaultPackageManager, SettingsManager: mod.SettingsManager };
-        return piModuleCache;
-      }
-    } catch { /* fall through */ }
+/**
+ * Resolve pi's package-manager API via the ToolRegistry. Surface the
+ * diagnostic trail on failure so callers (routes) can show the real
+ * reason instead of a generic "not installed" message.
+ */
+async function loadPiPackageManager(registry: ToolRegistry = getDefaultRegistry()): Promise<PiModule> {
+  const { module } = await registry.resolveModule<PiModule>("pi-coding-agent");
+  if (!module.DefaultPackageManager) {
+    throw new Error(
+      "pi-coding-agent resolved but does not export DefaultPackageManager (unexpected package version)",
+    );
   }
+  return module;
+}
 
-  throw new Error(
-    "pi-coding-agent is not installed. Package management requires pi to be installed (globally or as a dependency)."
-  );
+/** Debug helper: expose the raw Resolution for diagnostic surfaces. */
+export function diagnosePiPackageManager(registry: ToolRegistry = getDefaultRegistry()): Resolution {
+  return registry.resolve("pi-coding-agent");
 }
 
+/** Re-export so route handlers can `instanceof`-check for the rich error. */
+export { ModuleResolutionError };
+
 export type PackageScope = "global" | "local";
 export type PackageAction = "install" | "remove" | "update";
 
@@ -78,6 +167,8 @@ export interface OperationResult {
   scope: PackageScope;
   success: boolean;
   error?: string;
+  /** On failure: full resolution trail if pi couldn't be loaded. */
+  diagnostics?: Resolution;
 }
 
 export type ProgressListener = (operationId: string, event: ProgressEvent) => void;
@@ -91,6 +182,11 @@ export class PackageManagerWrapper {
   private onComplete: CompleteListener | undefined;
   /** Called after successful operation; returns number of sessions reloaded. */
   private reloadSessions: (() => Promise<number>) | undefined;
+  private readonly registry: ToolRegistry;
+
+  constructor(registry: ToolRegistry = getDefaultRegistry()) {
+    this.registry = registry;
+  }
 
   setProgressListener(listener: ProgressListener | undefined) {
     this.onProgress = listener;
@@ -167,11 +263,63 @@ export class PackageManagerWrapper {
 
   // ── Internal ────────────────────────────────────────────────────
 
+  /**
+   * Per-cwd cache of DefaultPackageManager instances. Each instance holds
+   * its own SettingsManager + filesystem state; on Windows
+   * `listConfiguredPackages` can take several seconds on cold
+   * instantiation, so reusing the same instance across repeat calls
+   * (same cwd) eliminates the cost of the `/api/packages/recommended` +
+   * `/api/packages/installed` flows firing back-to-back.
+   *
+   * We also dedupe *in-flight* instantiations via `pmPending`: if two
+   * concurrent callers both ask for the same cwd before the first
+   * instantiation resolves, they share the same Promise instead of
+   * spawning parallel `DefaultPackageManager` constructions (which
+   * compete for the event loop and can double cold-start latency).
+   *
+   * `run()` invalidates the relevant entry after an install/remove/update
+   * so stale state never persists past a mutation.
+   */
+  private readonly pmCache = new Map<string, unknown>();
+  private readonly pmPending = new Map<string, Promise<unknown>>();
+
   private async createPackageManager(cwd?: string) {
-    const { DefaultPackageManager, SettingsManager } = await loadPiPackageManager();
     const effectiveCwd = cwd ?? process.cwd();
-    const settingsManager = SettingsManager.create(effectiveCwd, AGENT_DIR);
-    return new DefaultPackageManager({ cwd: effectiveCwd, agentDir: AGENT_DIR, settingsManager });
+    const cached = this.pmCache.get(effectiveCwd);
+    if (cached) return cached as any;
+    const inflight = this.pmPending.get(effectiveCwd);
+    if (inflight) return inflight as any;
+
+    const promise = (async () => {
+      const { DefaultPackageManager, SettingsManager } = await loadPiPackageManager(this.registry);
+      const settingsManager = SettingsManager.create(effectiveCwd, AGENT_DIR);
+      // Wrap pi's DefaultPackageManager in our SafePackageManager so
+      // every internal `spawn` / `spawnSync` / `runCommandSync` call
+      // routes through the OS-aware SubprocessAdapter. This is THE
+      // fix for cmd.exe flashes on Windows caused by pi's upstream
+      // `shell: true + no windowsHide` spawn pattern.
+      const SafePM = createSafePackageManagerClass(
+        DefaultPackageManager,
+        getDefaultSubprocessAdapter(),
+        this.registry,
+      );
+      const pm = new SafePM({ cwd: effectiveCwd, agentDir: AGENT_DIR, settingsManager });
+      this.pmCache.set(effectiveCwd, pm);
+      return pm;
+    })();
+    this.pmPending.set(effectiveCwd, promise);
+    try {
+      return await promise;
+    } finally {
+      this.pmPending.delete(effectiveCwd);
+    }
+  }
+
+  /** Drop the cached package manager for a cwd (after install/remove/update). */
+  private invalidatePackageManager(cwd?: string): void {
+    const effectiveCwd = cwd ?? process.cwd();
+    this.pmCache.delete(effectiveCwd);
+    this.pmPending.delete(effectiveCwd);
   }
 
   private async executeOperation(operationId: string, req: OperationRequest): Promise<void> {
@@ -205,6 +353,10 @@ export class PackageManagerWrapper {
 
       result.success = true;
 
+      // Invalidate the cached package manager for this cwd so future
+      // listInstalled() calls see the mutated settings.json.
+      this.invalidatePackageManager(req.cwd);
+
       // Reload all sessions after successful operation
       if (this.reloadSessions) {
         try {
@@ -215,7 +367,15 @@ export class PackageManagerWrapper {
         }
       }
     } catch (err: any) {
-      result.error = err?.message ?? String(err);
+      // Pi-not-found: surface the full Resolution trail to the caller
+      // so the UI can render per-strategy failure reasons instead of
+      // the old opaque "pi-coding-agent is not installed" message.
+      if (err instanceof ModuleResolutionError) {
+        result.error = err.message;
+        result.diagnostics = err.resolution;
+      } else {
+        result.error = err?.message ?? String(err);
+      }
     } finally {
       this.busy = false;
       this.onComplete?.(result);

package/packages/server/src/pi-core-checker.ts

@@ -16,7 +16,7 @@
  * Version fetch reuses `fetchPackageMeta()` from the npm-search proxy.
  * Results are cached for 5 minutes.
  */
-import { execFile } from "node:child_process";
+import { execFile } from "node:child_process"; // ban:child_process-ok pi-core check uses execFile + promisify for `npm list -g --json` output capture; refactoring to platform/spawn's Recipe engine is tracked tech debt
 import { promisify } from "node:util";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";

package/packages/server/src/pi-core-updater.ts

@@ -6,7 +6,7 @@
  * Coordinates with PackageManagerWrapper's busy-lock so extension
  * operations and core updates can't run concurrently.
  */
-import { spawn } from "node:child_process";
+import { spawn } from "node:child_process"; // ban:child_process-ok npm-update streams stdout/stderr via pipe for progress events; refactor to platform/spawn Recipe is tracked tech debt
 import path from "node:path";
 import os from "node:os";
 import { existsSync } from "node:fs";
@@ -50,10 +50,16 @@ function defaultRunNpmUpdate(
 			return;
 		}
 
+		// On Windows, system npm is npm.cmd (batch wrapper) — spawn("npm")
+		// without the .cmd extension fails with ENOENT. shell:true routes
+		// the invocation through cmd.exe which resolves via PATHEXT.
+		// See change: route-kill-paths-through-platform (same class of bug).
 		const child = spawn("npm", args, {
 			cwd,
 			stdio: ["ignore", "pipe", "pipe"],
 			env: process.env,
+			shell: process.platform === "win32", // platform-branch-ok: shell:true required on Windows so PATHEXT resolves npm.cmd (spawn('npm') without .cmd ENOENTs)
+			windowsHide: true,
 		});
 
 		const timer = setTimeout(() => {

package/packages/server/src/pi-resource-scanner.ts

@@ -5,7 +5,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import { execSync } from "node:child_process";
+import * as npm from "@blackbelt-technology/pi-dashboard-shared/platform/npm.js";
 import type { PiResource, PiResourceScope, PiPackageInfo, PiResourcesResult } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
 
 // ── Frontmatter Parsing ─────────────────────────────────────────────
@@ -179,13 +179,10 @@ let cachedNpmGlobalRoot: string | null = null;
 
 function getNpmGlobalRoot(): string | null {
   if (cachedNpmGlobalRoot !== null) return cachedNpmGlobalRoot;
-  try {
-    cachedNpmGlobalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 10_000 }).trim();
-    return cachedNpmGlobalRoot;
-  } catch {
-    cachedNpmGlobalRoot = "";
-    return null;
-  }
+  // Delegate to shared npm module which caches the result itself and
+  // handles windowsHide / timeout. See change: platform-command-executor.
+  cachedNpmGlobalRoot = npm.rootGlobalOr("");
+  return cachedNpmGlobalRoot || null;
 }
 
 /** Visible for testing — reset cached npm root */

package/packages/server/src/pi-version-skew.ts

@@ -0,0 +1,196 @@
+/**
+ * Version-skew detection for pi-coding-agent.
+ *
+ * Reads `piCompatibility` from `packages/server/package.json` and the
+ * currently-resolved pi version from its `package.json`, then populates
+ * `bootstrapState.compatibility` with hints the UI banner uses to show
+ * upgrade suggestions.
+ *
+ * See change: unified-bootstrap-install \u00a79.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import type { BootstrapCompatibility, BootstrapStateStore } from "./bootstrap-state.js";
+import { getDefaultRegistry, type ToolRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
+
+/**
+ * Parse a semver-ish string into its three numeric segments. Returns
+ * null when the string doesn't match `<n>.<n>.<n>` (with optional
+ * pre-release / build suffix which we ignore for comparison). This is
+ * deliberately minimal \u2014 pi versions have always been `0.x.y` and we
+ * don't want to pull in the `semver` dep.
+ */
+export function parseVersion(v: string): [number, number, number] | null {
+  const m = v.trim().replace(/^v/, "").match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
+}
+
+/**
+ * Compare two version strings. Returns -1 if `a < b`, 0 if equal, 1 if
+ * `a > b`. Unparseable strings sort as equal (conservative \u2014 don't flag
+ * weird versions as outdated).
+ */
+export function compareVersions(a: string, b: string): -1 | 0 | 1 {
+  const A = parseVersion(a);
+  const B = parseVersion(b);
+  if (!A || !B) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (A[i] < B[i]) return -1;
+    if (A[i] > B[i]) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Return true if `version` is less than `threshold`. Delegates to
+ * `compareVersions` so unparseable strings never flag as "too old".
+ */
+export function isBelow(version: string, threshold: string): boolean {
+  return compareVersions(version, threshold) < 0;
+}
+
+/**
+ * Return true if `version` is strictly above `threshold`. `threshold`
+ * may include a `.x` wildcard in the patch slot (e.g. `"0.9.x"`); in
+ * that case the wildcard matches any patch, so `"0.9.5"` is NOT above
+ * `"0.9.x"` but `"0.10.0"` is.
+ */
+export function isAbove(version: string, threshold: string): boolean {
+  const thresholdClean = threshold.replace(/\.x$/i, ".99999");
+  return compareVersions(version, thresholdClean) > 0;
+}
+
+/**
+ * Read the server's declared compatibility range from its own package.json.
+ * Falls back to the hard-coded defaults when the field is missing or
+ * malformed (shouldn't happen in practice).
+ */
+export function readPiCompatibility(serverPkgJsonPath: string): Pick<
+  BootstrapCompatibility,
+  "minimum" | "recommended" | "maximum"
+> {
+  try {
+    const raw = fs.readFileSync(serverPkgJsonPath, "utf8");
+    const parsed = JSON.parse(raw) as {
+      piCompatibility?: { minimum?: string; recommended?: string; maximum?: string | null };
+    };
+    const c = parsed.piCompatibility;
+    if (c && typeof c.minimum === "string" && typeof c.recommended === "string") {
+      return {
+        minimum: c.minimum,
+        recommended: c.recommended,
+        maximum: c.maximum ?? null,
+      };
+    }
+  } catch {
+    /* fall through */
+  }
+  return { minimum: "0.6.7", recommended: "0.6.7", maximum: null };
+}
+
+/**
+ * Read the currently-resolved pi version from `<pi-module>/../package.json`.
+ * Returns undefined when pi isn't resolvable or the package.json can't
+ * be parsed.
+ */
+export function readCurrentPiVersion(registry: ToolRegistry = getDefaultRegistry()): string | undefined {
+  try {
+    const req = createRequire(import.meta.url);
+    const pkgJson = req.resolve("@mariozechner/pi-coding-agent/package.json");
+    const raw = fs.readFileSync(pkgJson, "utf8");
+    const parsed = JSON.parse(raw) as { version?: string };
+    if (typeof parsed.version === "string") return parsed.version;
+  } catch {
+    /* not resolvable yet */
+  }
+  // Fall back to the registry's resolved path + ../package.json.
+  try {
+    const res = registry.resolve("pi");
+    if (res.ok && res.path) {
+      const candidate = path.join(path.dirname(path.dirname(res.path)), "package.json");
+      if (fs.existsSync(candidate)) {
+        const raw = fs.readFileSync(candidate, "utf8");
+        const parsed = JSON.parse(raw) as { version?: string };
+        if (typeof parsed.version === "string") return parsed.version;
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return undefined;
+}
+
+/**
+ * Compute the `compatibility` snapshot from a compatibility range and
+ * the current pi version (or undefined when not yet installed). Pure
+ * function \u2014 all I/O is done by callers.
+ */
+export function computeCompatibility(
+  range: Pick<BootstrapCompatibility, "minimum" | "recommended" | "maximum">,
+  current: string | undefined,
+): BootstrapCompatibility {
+  const out: BootstrapCompatibility = { ...range, current };
+  if (!current) return out;
+  if (isBelow(current, range.minimum)) {
+    // Minimum-violated is signalled by leaving `upgradeRecommended` true
+    // AND letting callers populate `bootstrapState.error` with the
+    // block-ops message.
+    out.upgradeRecommended = true;
+    return out;
+  }
+  if (isBelow(current, range.recommended)) {
+    out.upgradeRecommended = true;
+  }
+  if (range.maximum && isAbove(current, range.maximum)) {
+    out.upgradeDashboard = true;
+  }
+  return out;
+}
+
+interface CacheEntry {
+  value: BootstrapCompatibility;
+  /** Milliseconds epoch when this entry should be discarded. */
+  expiresAt: number;
+}
+
+let cached: CacheEntry | undefined;
+const CACHE_TTL_MS = 60_000;
+
+/**
+ * Convenience wrapper: read range + current version, compute result,
+ * cache for 60 s. `store` is called with a structured compatibility
+ * update and (when minimum is violated) a blocking `error` message.
+ */
+export function updateBootstrapCompatibility(
+  store: BootstrapStateStore,
+  serverPkgJsonPath: string,
+  registry: ToolRegistry = getDefaultRegistry(),
+  now: () => number = Date.now,
+): BootstrapCompatibility {
+  const t = now();
+  if (cached && t < cached.expiresAt) {
+    store.set({ compatibility: cached.value });
+    return cached.value;
+  }
+  const range = readPiCompatibility(serverPkgJsonPath);
+  const current = readCurrentPiVersion(registry);
+  const computed = computeCompatibility(range, current);
+  cached = { value: computed, expiresAt: t + CACHE_TTL_MS };
+  store.set({ compatibility: computed });
+  // Minimum-violated → block pi-dependent ops by setting `error`.
+  if (current && isBelow(current, range.minimum)) {
+    store.set({
+      error: {
+        message: `pi version ${current} is below minimum ${range.minimum}. Please run \`pi-dashboard upgrade-pi\`.`,
+      },
+    });
+  }
+  return computed;
+}
+
+/** Test helper: clear the 60-second cache between runs. */
+export function _resetVersionSkewCache(): void {
+  cached = undefined;
+}

package/packages/server/src/preferences-store.ts

@@ -7,6 +7,7 @@ import path from "node:path";
 import { CONFIG_DIR } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { readJsonFile, writeJsonFile } from "./json-store.js";
 import { safeRealpathSync } from "./resolve-path.js";
+import { normalizePath } from "@blackbelt-technology/pi-dashboard-shared/platform/paths.js";
 
 export const PREFERENCES_FILE = path.join(CONFIG_DIR, "preferences.json");
 
@@ -32,10 +33,23 @@ const DEBOUNCE_MS = 1000;
 export function createPreferencesStore(filePath: string = PREFERENCES_FILE): PreferencesStore {
   const data: PreferencesData = readJsonFile<PreferencesData>(filePath, { sessionOrder: {}, pinnedDirectories: [] });
   let sessionOrder: Record<string, string[]> = data.sessionOrder ?? {};
-  // Resolve symlinks in stored pinned paths on load
+  // Normalize + resolve symlinks in stored pinned paths on load. Normalize
+  // FIRST so cosmetic drift (trailing separator, mixed separators,
+  // drive-letter case on Windows) collapses before realpath — then
+  // realpath handles symlinks. Order matters: realpath can fail for
+  // not-yet-existing paths, so we keep its best-effort fallback.
+  // See change: platform-path-normalization.
   const rawPinned = data.pinnedDirectories ?? [];
-  let pinnedDirectories: string[] = rawPinned.map(safeRealpathSync);
-  // Deduplicate in case symlinks resolved to the same path
+  // IMPORTANT: wrap in arrow fn — `Array.prototype.map` passes `(element,
+  // index, array)`, and `normalizePath`'s 2nd param is a `platform:
+  // NodeJS.Platform`. Passing the index (a number) silently disables the
+  // Windows branch at runtime.
+  let pinnedDirectories: string[] = rawPinned
+    .map((p) => normalizePath(p))
+    .map((p) => safeRealpathSync(p));
+  // Deduplicate post-normalization. Two previously-different entries that
+  // collapse to the same canonical form (e.g., with and without trailing
+  // slash) become one stored entry.
   pinnedDirectories = [...new Set(pinnedDirectories)];
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
   let dirty = pinnedDirectories.length !== rawPinned.length || pinnedDirectories.some((p, i) => p !== rawPinned[i]);