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

package/packages/shared/src/browser-protocol.ts

@@ -125,6 +125,21 @@ export interface SpawnResultBrowserMessage {
   message: string;
 }
 
+/**
+ * Emitted when a session spawn fails — either because `spawnPiSession` threw,
+ * returned `{ success: false }`, or the spawned child crashed immediately.
+ * Carries enough context for the UI to render a retryable error banner
+ * instead of leaving the user staring at a silent empty state.
+ */
+export interface SpawnErrorMessage {
+  type: "spawn_error";
+  cwd: string;
+  strategy: string;
+  message: string;
+  /** Up to ~2 KB tail of stderr captured from the failed child, if any. */
+  stderr?: string;
+}
+
 export interface SessionsReorderedMessage {
   type: "sessions_reordered";
   cwd: string;
@@ -226,6 +241,58 @@ export interface PiCoreUpdateCompleteMessage {
   sessionsReloaded: number;
 }
 
+/**
+ * Bootstrap state snapshot. Mirrors `BootstrapState` in
+ * `packages/server/src/bootstrap-state.ts` but kept as a structural
+ * subset here so the shared package doesn't take a runtime dependency
+ * on the server package.
+ *
+ * See change: unified-bootstrap-install.
+ */
+export interface BootstrapStateSnapshot {
+  status: "ready" | "installing" | "failed";
+  progress?: { step: string; pct?: number; output?: string };
+  error?: { message: string; stack?: string };
+  version?: { pi?: string; openspec?: string; tsx?: string };
+  compatibility?: {
+    minimum: string;
+    recommended: string;
+    maximum: string | null;
+    current?: string;
+    upgradeRecommended?: boolean;
+    upgradeDashboard?: boolean;
+  };
+  bridgeRegistrationError?: string;
+}
+
+/**
+ * Broadcast on every bootstrap-state transition. Browsers use this to
+ * render the first-run install banner, the upgrade-pi progress display,
+ * and version-skew hints.
+ */
+export interface BootstrapStatusUpdateMessage {
+  type: "bootstrap_status_update";
+  state: BootstrapStateSnapshot;
+}
+
+/**
+ * Broadcast when a queued pi-dependent operation (e.g. a session-spawn
+ * request accepted with 202 during "installing") finishes running after
+ * the bootstrap transitioned to "ready". Clients that stored a ticketId
+ * from the 202 response can correlate the outcome via this message.
+ *
+ * `success` is true when the queued handler resolved without throwing;
+ * `error` carries the thrown message string when `success` is false.
+ *
+ * See change: unified-bootstrap-install.
+ */
+export interface BootstrapTicketCompleteMessage {
+  type: "bootstrap_ticket_complete";
+  ticketId: string;
+  success: boolean;
+  error?: string;
+}
+
 /** Sent when a package operation finishes (success or failure). */
 export interface PackageOperationCompleteMessage {
   type: "package_operation_complete";
@@ -255,6 +322,7 @@ export type ServerToBrowserMessage =
   | SessionsListBrowserMessage
   | ResumeResultBrowserMessage
   | SpawnResultBrowserMessage
+  | SpawnErrorMessage
   | SessionsReorderedMessage
   | PinnedDirsUpdatedMessage
   | TerminalAddedMessage
@@ -274,7 +342,9 @@ export type ServerToBrowserMessage =
   | BrowserPromptRequestMessage
   | BrowserPromptDismissMessage
   | BrowserPromptCancelMessage
-  | ModelsRefreshedMessage;
+  | ModelsRefreshedMessage
+  | BootstrapStatusUpdateMessage
+  | BootstrapTicketCompleteMessage;
 
 // ── Browser → Server ────────────────────────────────────────────────
 

package/packages/shared/src/config.ts

@@ -41,6 +41,24 @@ export const DEFAULT_MEMORY_LIMITS: MemoryLimitsConfig = {
   maxWsBufferBytes: 4 * 1024 * 1024,
 };
 
+export interface OpenSpecPollConfig {
+  /** Poll interval in seconds. Default 30. Clamped to [5, 3600]. */
+  pollIntervalSeconds: number;
+  /** Max concurrent `openspec` CLI invocations across all dirs. Default 3. Clamped to [1, 16]. */
+  maxConcurrentSpawns: number;
+  /** `"mtime"` skips re-polling unchanged changes; `"always"` polls unconditionally. Default `"mtime"`. */
+  changeDetection: "mtime" | "always";
+  /** Max per-directory phase jitter in seconds. 0 disables jitter. Default 5. Clamped to [0, 60]. */
+  jitterSeconds: number;
+}
+
+export const DEFAULT_OPENSPEC_POLL: OpenSpecPollConfig = {
+  pollIntervalSeconds: 30,
+  maxConcurrentSpawns: 3,
+  changeDetection: "mtime",
+  jitterSeconds: 5,
+};
+
 export interface EditorConfig {
   /** Override path to code-server binary */
   binary?: string;
@@ -75,6 +93,8 @@ export interface DashboardConfig {
   defaultModel: string;
   memoryLimits: MemoryLimitsConfig;
   editor: EditorConfig;
+  /** OpenSpec background polling behavior (interval, concurrency, change detection, jitter) */
+  openspec: OpenSpecPollConfig;
   /** Networks trusted for full access without authentication (CIDR, wildcard, exact IP) */
   trustedNetworks: string[];
   /** Merged trustedNetworks + auth.bypassHosts (deduplicated). Computed at load time. */
@@ -108,6 +128,7 @@ const DEFAULTS: DashboardConfig = {
   defaultModel: "",
   memoryLimits: { ...DEFAULT_MEMORY_LIMITS },
   editor: { ...DEFAULT_EDITOR_CONFIG },
+  openspec: { ...DEFAULT_OPENSPEC_POLL },
   trustedNetworks: [],
   resolvedTrustedNetworks: [],
   cors: { allowedOrigins: [] },
@@ -117,28 +138,57 @@ const DEFAULTS: DashboardConfig = {
 
 /**
  * Parse and validate the auth config section.
- * Returns undefined if auth is not configured or has no providers.
+ *
+ * Returns undefined ONLY when nothing auth-relevant is configured — that is,
+ * when none of `providers`, `bypassHosts`, or `bypassUrls` has any content.
+ *
+ * When providers is empty but bypassHosts or bypassUrls is populated, this
+ * function returns a valid AuthConfig with an empty providers map. The auth
+ * plugin already no-ops in that case (providerRegistry.size === 0 → skip
+ * OAuth route + cookie plugin registration), so no OAuth flow activates
+ * accidentally. But returning an object here lets the caller populate
+ * resolvedTrustedNetworks from auth.bypassHosts — which is the entire
+ * point of allowing this shape. Before this change, parseAuthConfig
+ * returned undefined on empty-providers, which nuked auth.bypassHosts
+ * before the resolvedTrustedNetworks merge could read it, and users
+ * without OAuth lost remote network access after the UI started writing
+ * to auth.bypassHosts. See openspec/changes/fix-trusted-networks-no-oauth.
  */
 function parseAuthConfig(raw: any): AuthConfig | undefined {
   if (!raw || typeof raw !== "object") return undefined;
   const providers = raw.providers;
-  if (!providers || typeof providers !== "object" || Object.keys(providers).length === 0) {
-    return undefined;
-  }
-  // Validate each provider has at least clientId and clientSecret
+  const hasProviders =
+    providers && typeof providers === "object" && Object.keys(providers).length > 0;
+  const hasHosts = Array.isArray(raw.bypassHosts) && raw.bypassHosts.length > 0;
+  const hasUrls = Array.isArray(raw.bypassUrls) && raw.bypassUrls.length > 0;
+  if (!hasProviders && !hasHosts && !hasUrls) return undefined;
+
+  // Validate each provider has at least clientId and clientSecret.
+  // validProviders may end up empty when providers is {} or all entries
+  // are malformed — that's fine, the caller tolerates it as long as
+  // bypassHosts or bypassUrls carries the auth-relevant content.
   const validProviders: Record<string, AuthProviderConfig> = {};
-  for (const [key, value] of Object.entries(providers)) {
-    const p = value as any;
-    if (p && typeof p === "object" && p.clientId && p.clientSecret) {
-      validProviders[key] = {
-        clientId: p.clientId,
-        clientSecret: p.clientSecret,
-        ...(p.issuerUrl ? { issuerUrl: p.issuerUrl } : {}),
-        ...(p.name ? { name: p.name } : {}),
-      };
+  if (hasProviders) {
+    for (const [key, value] of Object.entries(providers as Record<string, unknown>)) {
+      const p = value as any;
+      if (p && typeof p === "object" && p.clientId && p.clientSecret) {
+        validProviders[key] = {
+          clientId: p.clientId,
+          clientSecret: p.clientSecret,
+          ...(p.issuerUrl ? { issuerUrl: p.issuerUrl } : {}),
+          ...(p.name ? { name: p.name } : {}),
+        };
+      }
     }
   }
-  if (Object.keys(validProviders).length === 0) return undefined;
+
+  // If providers was declared but all entries are malformed AND there is no
+  // bypass content, fall back to undefined — same "nothing auth-relevant"
+  // rule as the top-level gate.
+  if (Object.keys(validProviders).length === 0 && !hasHosts && !hasUrls) {
+    return undefined;
+  }
+
   return {
     secret: raw.secret ?? "",
     providers: validProviders,
@@ -157,6 +207,27 @@ function parseEditorConfig(raw: any): EditorConfig {
   };
 }
 
+function clampNumber(raw: any, fallback: number, min: number, max: number): number {
+  const n = typeof raw === "number" && Number.isFinite(raw) ? raw : fallback;
+  if (n < min) return min;
+  if (n > max) return max;
+  return n;
+}
+
+function parseOpenSpecPollConfig(raw: any): OpenSpecPollConfig {
+  if (!raw || typeof raw !== "object") return { ...DEFAULT_OPENSPEC_POLL };
+  const changeDetection =
+    raw.changeDetection === "always" || raw.changeDetection === "mtime"
+      ? raw.changeDetection
+      : DEFAULT_OPENSPEC_POLL.changeDetection;
+  return {
+    pollIntervalSeconds: clampNumber(raw.pollIntervalSeconds, DEFAULT_OPENSPEC_POLL.pollIntervalSeconds, 5, 3600),
+    maxConcurrentSpawns: clampNumber(raw.maxConcurrentSpawns, DEFAULT_OPENSPEC_POLL.maxConcurrentSpawns, 1, 16),
+    changeDetection,
+    jitterSeconds: clampNumber(raw.jitterSeconds, DEFAULT_OPENSPEC_POLL.jitterSeconds, 0, 60),
+  };
+}
+
 function parseMemoryLimits(raw: any): MemoryLimitsConfig {
   if (!raw || typeof raw !== "object") return { ...DEFAULT_MEMORY_LIMITS };
   return {
@@ -217,6 +288,7 @@ export function loadConfig(): DashboardConfig {
       auth: parseAuthConfig(parsed.auth),
       memoryLimits: parseMemoryLimits(parsed.memoryLimits),
       editor: parseEditorConfig(parsed.editor),
+      openspec: parseOpenSpecPollConfig(parsed.openspec),
       trustedNetworks: parseTrustedNetworks(parsed.trustedNetworks),
       resolvedTrustedNetworks: [],
       cors: {

package/packages/shared/src/managed-paths.ts

@@ -1,15 +1,42 @@
 /**
- * Shared constants for the managed install directory (~/.pi-dashboard/).
+ * Shared constants + getters for the managed install directory (~/.pi-dashboard/).
  * Single source of truth — all packages import from here.
+ *
+ * Constants (MANAGED_DIR, MANAGED_BIN, PI_SETTINGS_PATH) reflect the live
+ * environment at module-load time. Production code continues to use them.
+ *
+ * Getters (getManagedDir, getManagedBin, getPiSettingsPath) accept an
+ * optional `{ homedir }` override so tests (and the bootstrap harness)
+ * can reason about alternate HOME directories without mutating globals.
  */
 import path from "node:path";
 import os from "node:os";
 
+/** Env override surface used by the getters (subset of PlatformEnv). */
+export interface ManagedPathsEnv {
+  homedir?: string;
+}
+
+/** Root directory for managed installs (pi, openspec, tsx). */
+export function getManagedDir(env?: ManagedPathsEnv): string {
+  return path.join(env?.homedir ?? os.homedir(), ".pi-dashboard");
+}
+
+/** Bin directory for managed install executables. */
+export function getManagedBin(env?: ManagedPathsEnv): string {
+  return path.join(getManagedDir(env), "node_modules", ".bin");
+}
+
+/** Path to pi's global settings file. */
+export function getPiSettingsPath(env?: ManagedPathsEnv): string {
+  return path.join(env?.homedir ?? os.homedir(), ".pi", "agent", "settings.json");
+}
+
 /** Root directory for managed installs (pi, openspec, tsx). */
-export const MANAGED_DIR = path.join(os.homedir(), ".pi-dashboard");
+export const MANAGED_DIR = getManagedDir();
 
 /** Bin directory for managed install executables. */
-export const MANAGED_BIN = path.join(MANAGED_DIR, "node_modules", ".bin");
+export const MANAGED_BIN = getManagedBin();
 
 /** Path to pi's global settings file. */
-export const PI_SETTINGS_PATH = path.join(os.homedir(), ".pi", "agent", "settings.json");
+export const PI_SETTINGS_PATH = getPiSettingsPath();

package/packages/shared/src/openspec-poller.ts

@@ -1,45 +1,31 @@
 /**
  * Polls the openspec CLI to gather change data for the session's project.
- * Uses async child processes to avoid blocking the event loop.
+ *
+ * This module is a thin aggregator over `platform/openspec.ts`: it
+ * calls the Recipe-based primitives and combines `list` + per-change
+ * `status` into the dashboard's `OpenSpecData` shape.
+ *
+ * Two public flavors:
+ *
+ *   - `pollOpenSpec` (sync) — for the bridge extension where async
+ *     isn't practical. Uses `run()` under the hood; each call blocks
+ *     the event loop for ~200-2000ms per openspec invocation.
+ *
+ *   - `pollOpenSpecAsync` (async) — for the server's directory service.
+ *     Routes through the runner's `runAsync()` so every spawn goes
+ *     through the same binary resolution, `.cmd` shell handling, and
+ *     `windowsHide: true` default as everything else. Status queries
+ *     run in parallel via `Promise.all`, keeping the event loop free
+ *     on Windows where openspec.cmd startup is slow (~2s per call).
+ *
+ * See change: consolidate-tool-resolution.
  */
-import { spawnSync, execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { listOr, statusOr, OPENSPEC_LIST, OPENSPEC_STATUS } from "./platform/openspec.js";
+import { runAsync, unwrap } from "./platform/runner.js";
 import type { OpenSpecData, OpenSpecChange, OpenSpecArtifact } from "./types.js";
 
-const execFileAsync = promisify(execFile);
 const EMPTY_DATA: OpenSpecData = { initialized: false, changes: [] };
 
-/** Synchronous version — only used by bridge extension where async isn't practical */
-function runOpenSpecSync(args: string[], cwd: string): unknown | null {
-  try {
-    const result = spawnSync("openspec", args, {
-      cwd,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"],
-      timeout: 10_000,
-    });
-    if (result.status !== 0 || !result.stdout) return null;
-    return JSON.parse(result.stdout);
-  } catch {
-    return null;
-  }
-}
-
-/** Async version — non-blocking, used by server */
-async function runOpenSpecAsync(args: string[], cwd: string): Promise<unknown | null> {
-  try {
-    const { stdout } = await execFileAsync("openspec", args, {
-      cwd,
-      encoding: "utf-8",
-      timeout: 10_000,
-    });
-    if (!stdout) return null;
-    return JSON.parse(stdout);
-  } catch {
-    return null;
-  }
-}
-
 export function buildOpenSpecData(
   listResult: { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> } | null,
   statusResults: Map<string, { artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null>,
@@ -72,30 +58,61 @@ export function buildOpenSpecData(
   return { initialized: true, changes };
 }
 
-/** Synchronous poll — blocks event loop. Used by bridge extension. */
+/**
+ * Synchronous poll — blocks the event loop. Used by the bridge extension
+ * where async isn't practical (some pi extension hooks are sync).
+ */
 export function pollOpenSpec(cwd: string): OpenSpecData {
-  const listResult = runOpenSpecSync(["list", "--json"], cwd) as any;
+  const listResult = listOr({ cwd }) as any;
   if (!listResult || !Array.isArray(listResult.changes)) return EMPTY_DATA;
 
   const statusResults = new Map<string, any>();
   for (const c of listResult.changes) {
-    statusResults.set(c.name, runOpenSpecSync(["status", "--change", c.name, "--json"], cwd));
+    statusResults.set(c.name, statusOr({ cwd, change: c.name }));
   }
   return buildOpenSpecData(listResult, statusResults);
 }
 
-/** Async poll — non-blocking. Used by server directory service. */
+/**
+ * Run `openspec list --json` for a single cwd. Exposed so callers that
+ * want their own concurrency control or mtime-gate logic can compose
+ * the list + per-change status calls themselves.
+ */
+export async function runOpenSpecList(cwd: string): Promise<
+  | { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> }
+  | null
+> {
+  return unwrap(await runAsync(OPENSPEC_LIST, { cwd }, { cwd }), null) as any;
+}
+
+/**
+ * Run `openspec status --change <name> --json` for a single change.
+ * Exposed for the same reason as `runOpenSpecList`.
+ */
+export async function runOpenSpecStatus(
+  cwd: string,
+  changeName: string,
+): Promise<{ artifacts?: Array<{ id: string; status: string }>; isComplete?: boolean } | null> {
+  return unwrap(await runAsync(OPENSPEC_STATUS, { cwd, change: changeName }, { cwd }), null) as any;
+}
+
+/**
+ * Async poll — genuinely async. Runs per-change status queries in
+ * parallel via the shared `runAsync()`, so each spawn goes through the
+ * central binary resolution + `windowsHide: true` default.
+ */
 export async function pollOpenSpecAsync(cwd: string): Promise<OpenSpecData> {
-  const listResult = await runOpenSpecAsync(["list", "--json"], cwd) as any;
+  const listResult = unwrap(await runAsync(OPENSPEC_LIST, { cwd }, { cwd }), null) as
+    | { changes?: Array<{ name: string; status: string; completedTasks: number; totalTasks: number }> }
+    | null;
   if (!listResult || !Array.isArray(listResult.changes)) return EMPTY_DATA;
 
-  // Run all status queries in parallel
-  const entries = await Promise.all(
-    listResult.changes.map(async (c: any): Promise<[string, any]> => {
-      const status = await runOpenSpecAsync(["status", "--change", c.name, "--json"], cwd);
-      return [c.name, status];
+  const statusEntries = await Promise.all(
+    listResult.changes.map(async (c) => {
+      const result = await runAsync(OPENSPEC_STATUS, { cwd, change: c.name }, { cwd });
+      return [c.name, unwrap(result, null)] as const;
     }),
   );
-  const statusResults = new Map<string, any>(entries);
+  const statusResults = new Map<string, any>(statusEntries);
   return buildOpenSpecData(listResult, statusResults);
 }

package/packages/shared/src/{tool-resolver.ts → platform/binary-lookup.ts}

@@ -3,11 +3,31 @@
  * Replaces scattered whichSync/resolvePiCommand/resolveTsxCommand implementations
  * with a single configurable resolver.
  */
-import { execSync } from "node:child_process";
+import { execSync, spawnSync, buildSafeArgv } from "./exec.js";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
-import { MANAGED_BIN, MANAGED_DIR } from "./managed-paths.js";
+import { MANAGED_BIN, MANAGED_DIR } from "../managed-paths.js";
+
+/**
+ * Well-known globalThis symbol for the default `ToolRegistry`.
+ *
+ * The registry publishes itself here when first constructed (see
+ * `tool-registry/index.ts::getDefaultRegistry`). Delegation avoids a
+ * static import cycle (tool-registry strategies already import from
+ * this file).
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+const GLOBAL_REGISTRY_KEY = Symbol.for("pi-dashboard.tool-registry");
+interface LazyRegistry {
+  has(n: string): boolean;
+  resolveExecutor(n: string): { ok: boolean; argv: string[] };
+}
+function tryGetRegistry(): LazyRegistry | null {
+  const reg = (globalThis as unknown as { [k: symbol]: LazyRegistry | undefined })[GLOBAL_REGISTRY_KEY];
+  return reg ?? null;
+}
 
 export interface ResolverContext {
   /** Extra bin dirs to search before system PATH (e.g., bundled Node dir). */
@@ -59,25 +79,27 @@ export class ToolResolver {
   }
 
   /**
-   * Resolve pi as [cmd, ...prefixArgs].
-   * On Windows, avoids .cmd by returning [node.exe, cli.js].
+   * Resolve pi as spawn-ready argv `[cmd, ...prefixArgs]`.
+   *
+   * Fully delegates to `ToolRegistry.resolveExecutor("pi")`, which
+   * owns per-OS discovery + interpreter assembly (on Windows: find
+   * `pi-coding-agent/dist/cli.js` via managed/bare-import/npm-global
+   * and prepend `node.exe`; on Unix: find `pi` binary on PATH).
+   *
+   * Returns null when the registry is not yet constructed AND pi is
+   * not on PATH (very early boot / standalone tests). Production code
+   * always has the registry available before spawn.
    */
   resolvePi(): string[] | null {
-    if (process.platform === "win32") {
-      // Avoid .cmd — resolve pi's JS entry point directly
-      const piCli = path.join(MANAGED_BIN, "..", "@mariozechner", "pi-coding-agent", "dist", "cli.js");
-      if (existsSync(piCli)) {
-        const node = this.resolveNode();
-        if (node) return [node, piCli];
-      }
-      // Fallback to .cmd
-      const cmd = path.join(MANAGED_BIN, "pi.cmd");
-      if (existsSync(cmd)) return [cmd];
+    const registry = tryGetRegistry();
+    if (registry?.has("pi")) {
+      const exec = registry.resolveExecutor("pi");
+      if (exec.ok && exec.argv.length > 0) return exec.argv;
     }
-
+    // No registry in this process (e.g. legacy bootstrap) — fall back
+    // to PATH lookup so the method still works for non-server callers.
     const piPath = this.which("pi");
-    if (piPath) return [piPath];
-    return null;
+    return piPath ? [piPath] : null;
   }
 
   /**
@@ -160,28 +182,106 @@ export class ToolResolver {
 
 // ── Internal helpers ──────────────────────────────────────────────────────────
 
-/** Resolve a command on the current process PATH via which/where. */
-function whichSync(cmd: string): string | null {
-  const whichCmd = process.platform === "win32" ? "where" : "which";
+/**
+ * Run `where|which <target>` and return ALL stdout lines (trimmed,
+ * non-empty), or `[]`.
+ *
+ * Uses `spawnSync` via `buildSafeArgv` — no shell interpretation at
+ * all. `execSync("where tmux")` used to route through cmd.exe (because
+ * execSync takes a shell command string); spawnSync with argv bypasses
+ * that entirely. Guaranteed no cmd.exe console flash.
+ *
+ * See change: consolidate-windows-spawn-and-platform-handlers.
+ */
+function whereAllLines(whichCmd: string, target: string): string[] {
   try {
-    return execSync(`${whichCmd} ${cmd}`, {
+    const { argv, spawnOptions } = buildSafeArgv(whichCmd, [target]);
+    const result = spawnSync<string>(argv[0], argv.slice(1), {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
-    }).trim().split("\n")[0];
+      ...spawnOptions,
+    });
+    if (result.status !== 0) return [];
+    const text = typeof result.stdout === "string" ? result.stdout : String(result.stdout ?? "");
+    return text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
   } catch {
-    return null;
+    return [];
   }
 }
 
+/** Extract the file extension (lower-cased, including the dot) from a path, or "". */
+function extOf(p: string): string {
+  const slash = Math.max(p.lastIndexOf("\\"), p.lastIndexOf("/"));
+  const dot = p.lastIndexOf(".");
+  return dot > slash ? p.slice(dot).toLowerCase() : "";
+}
+
+/**
+ * Resolve a command on PATH.
+ *
+ * Unix: the first `which <name>` hit is authoritative.
+ *
+ * Windows: `where <name>` lists ALL PATH matches — a directory may contain
+ * both a bash shim (extensionless, e.g. `pi`) and a Windows-native form
+ * (`pi.cmd`). Node's `spawn()` cannot execute extensionless shims on
+ * Windows without `shell: true`, so we pick the first line whose extension
+ * is in PATHEXT. Falls back to the first line if none match (preserves
+ * whatever the user set up).
+ *
+ * Single `where` invocation — no per-extension probe loop — to keep
+ * resolution fast (especially when the command is missing entirely).
+ */
+function whichSync(cmd: string): string | null {
+  const isWin = process.platform === "win32";
+  if (!isWin) {
+    const lines = whereAllLines("which", cmd);
+    return lines[0] ?? null;
+  }
+
+  const lines = whereAllLines("where", cmd);
+  if (lines.length === 0) return null;
+
+  // If the caller already specified an extension, trust their pick.
+  const callerHasExt = /\.[A-Za-z0-9]+$/.test(cmd);
+  if (callerHasExt) return lines[0];
+
+  // Preference order: PATHEXT (user's actual Windows search path) or a
+  // standard default. Lower-cased for case-insensitive matching.
+  const pathextRaw = process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC;.PS1";
+  const pathext = pathextRaw.split(";").map((e) => e.trim().toLowerCase()).filter(Boolean);
+
+  // Pick the first line whose extension matches PATHEXT, scanning by
+  // preference order (lower index = more preferred).
+  let best: string | null = null;
+  let bestRank = Infinity;
+  for (const line of lines) {
+    const rank = pathext.indexOf(extOf(line));
+    if (rank === -1) continue;
+    if (rank < bestRank) {
+      best = line;
+      bestRank = rank;
+    }
+  }
+  if (best) return best;
+
+  // No PATHEXT-matching entry — fall back to first line (could be a bash
+  // shim). The runner layer handles the `.cmd` / `.bat` spawn-via-shell
+  // case separately; extensionless shims will still ENOENT but that's
+  // the right signal to the caller.
+  return lines[0];
+}
+
 /** Resolve a command via login shell (picks up nvm/volta/homebrew paths). */
 function whichViaLoginShell(cmd: string): string | null {
   const shell = process.env.SHELL || "/bin/zsh";
   try {
-    const output = execSync(`${shell} -ilc "which ${cmd}"`, {
+    const raw = execSync(`${shell} -ilc "which ${cmd}"`, {
       encoding: "utf-8",
       stdio: ["pipe", "pipe", "pipe"],
       timeout: 5000,
-    }).trim();
+      windowsHide: true,
+    });
+    const output = (typeof raw === "string" ? raw : String(raw)).trim();
     // Extract absolute path from potentially noisy login shell output
     const pathLine = output.split("\n").find(l => l.trim().startsWith("/"));
     return pathLine?.trim() || null;