supipowers 2.2.1 → 2.2.2

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "supipowers",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "Workflow extension for OMP coding agents.",
   "type": "module",
   "scripts": {
-    "test": "bun test --timeout 20000 tests/",
+    "test": "bun test --timeout 60000 --parallel tests/",
     "typecheck": "tsc --noEmit",
-    "test:watch": "bun test --timeout 20000 --watch tests/",
-    "test:evals": "bun test --timeout 20000 tests/evals/",
+    "test:watch": "bun test --timeout 60000 --parallel --watch tests/",
+    "test:evals": "bun test --timeout 60000 --parallel tests/evals/",
     "build": "tsc -p tsconfig.build.json",
     "ci": "bun run typecheck && bun run test",
     "install:visual-server": "npm --prefix src/visual/scripts ci --ignore-scripts --no-audit --no-fund",
@@ -16,7 +16,7 @@
     "dev-install": "bun run bin/dev-install.ts"
   },
   "engines": {
-    "bun": ">=1.3.10"
+    "bun": ">=1.3.13"
   },
   "keywords": [
     "omp",
@@ -65,7 +65,7 @@
     ]
   },
   "dependencies": {
-    "@clack/prompts": "^0.10.0",
+    "@clack/prompts": "^1.4.0",
     "handlebars": "^4.7.8",
     "yaml": "^2.8.3",
     "zod": "^4.3.0"
@@ -90,8 +90,8 @@
     "@oh-my-pi/pi-ai": "latest",
     "@oh-my-pi/pi-coding-agent": "latest",
     "@oh-my-pi/pi-tui": "latest",
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.8.0",
     "bun-types": "^1.3.11",
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.3"
   }
 }

package/src/bootstrap.ts

@@ -12,6 +12,7 @@ import { registerAiReviewCommand, handleAiReview } from "./commands/ai-review.js
 import { registerQaCommand } from "./commands/qa.js";
 import { registerReleaseCommand, handleRelease } from "./commands/release.js";
 import { registerUpdateCommand, handleUpdate } from "./commands/update.js";
+import { execCli } from "./utils/exec-cli.js";
 import { registerDoctorCommand, handleDoctor } from "./commands/doctor.js";
 import { registerModelCommand, handleModel } from "./commands/model.js";
 import { registerFixPrCommand } from "./commands/fix-pr.js";
@@ -175,7 +176,7 @@ export function bootstrap(platform: Platform): void {
     const currentVersion = getInstalledVersion(platform);
     if (!currentVersion) return;
 
-    platform.exec("npm", ["view", "supipowers", "version"], { cwd: tmpdir() })
+    execCli((cmd, args, opts) => platform.exec(cmd, args, opts), "npm", ["view", "supipowers", "version"], { cwd: tmpdir() })
       .then((result) => {
         if (result.code !== 0) return;
         const latest = result.stdout.trim();

package/src/commands/doctor.ts

@@ -11,6 +11,7 @@ import { formatReliabilitySection, loadReliabilitySummaries } from "../storage/r
 import { getMetricsStore, getSessionId } from "../context-mode/hooks.js";
 import { getProjectStatePath, getProjectStateDir } from "../workspace/state-paths.js";
 import { basename } from "node:path";
+import { execCli } from "../utils/exec-cli.js";
 
 export interface CheckResult {
   name: string;
@@ -435,14 +436,14 @@ export function checkMetrics(
 
 export async function checkNpm(platform: Platform): Promise<CheckResult> {
   try {
-    const vResult = await platform.exec("npm", ["--version"]);
+    const vResult = await execCli((cmd, args, opts) => platform.exec(cmd, args, opts), "npm", ["--version"]);
     if (vResult.code !== 0) {
       return { name: "npm", presence: { ok: false, detail: "npm not found" } };
     }
     const version = vResult.stdout.trim();
     const presence = { ok: true, detail: `v${version}` };
 
-    const pingResult = await platform.exec("npm", ["ping"]);
+    const pingResult = await execCli((cmd, args, opts) => platform.exec(cmd, args, opts), "npm", ["ping"]);
     if (pingResult.code === 0) {
       return { name: "npm", presence, functional: { ok: true, detail: "Registry reachable" } };
     }

package/src/commands/plan.ts

@@ -19,6 +19,7 @@ import { loadModelConfig } from "../config/model-config.js";
 import { getProjectStatePath } from "../workspace/state-paths.js";
 import { cancelPlanTracking, startPlanTracking } from "../planning/approval-flow.js";
 import { stopVisualServer } from "../visual/stop-server.js";
+import { execCli } from "../utils/exec-cli.js";
 
 modelRegistry.register({
   id: "plan",
@@ -111,7 +112,7 @@ export function registerPlanCommand(platform: Platform): void {
             const nodeModules = path.join(scriptsDir, "node_modules");
             if (!fs.existsSync(nodeModules)) {
               notifyInfo(ctx, "Installing visual companion dependencies...");
-              const installResult = await platform.exec("npm", ["install", "--production"], { cwd: scriptsDir });
+              const installResult = await execCli((cmd, args, opts) => platform.exec(cmd, args, opts), "npm", ["install", "--production"], { cwd: scriptsDir });
               if (installResult.code !== 0) {
                 notifyError(ctx, "Failed to install visual companion dependencies", installResult.stderr);
                 debugLogger.log("visual_companion_dependency_install_failed", {

package/src/commands/update.ts

@@ -11,6 +11,7 @@ import {
   steerMempalaceInitialization,
 } from "../mempalace/installer-helper.js";
 import { loadConfig } from "../config/loader.js";
+import { execCli, wrapExecForCli } from "../utils/exec-cli.js";
 
 // ── Options builder ──────────────────────────────────────
 
@@ -59,7 +60,7 @@ async function updateSupipowers(
   ctx.ui.notify(`Current version: v${currentVersion}`, "info");
 
   // Check latest version on npm
-  const checkResult = await platform.exec("npm", ["view", "supipowers", "version"], { cwd: tmpdir() });
+  const checkResult = await execCli((cmd, args, opts) => platform.exec(cmd, args, opts), "npm", ["view", "supipowers", "version"], { cwd: tmpdir() });
   if (checkResult.code !== 0) {
     ctx.ui.notify("Failed to check for updates — npm view failed", "error");
     return null;
@@ -78,7 +79,8 @@ async function updateSupipowers(
   mkdirSync(tempDir, { recursive: true });
 
   try {
-    const installResult = await platform.exec(
+    const installResult = await execCli(
+      (cmd, args, opts) => platform.exec(cmd, args, opts),
       "npm", ["install", "--prefix", tempDir, `supipowers@${latestVersion}`],
       { cwd: tempDir },
     );
@@ -130,10 +132,10 @@ async function updateSupipowers(
     // Install runtime dependencies (handlebars, etc.)
     // Without this, the extension fails to load because node_modules/ was deleted above.
     ctx.ui.notify("Installing dependencies...", "info");
-    const bunInstall = await platform.exec("bun", ["install", "--production"], { cwd: extDir });
+    const bunInstall = await execCli((cmd, args, opts) => platform.exec(cmd, args, opts), "bun", ["install", "--production"], { cwd: extDir });
     if (bunInstall.code !== 0) {
       // Fallback to npm if bun is not available (e.g. Windows without global bun)
-      const npmInstall = await platform.exec("npm", ["install", "--omit=dev"], { cwd: extDir });
+      const npmInstall = await execCli((cmd, args, opts) => platform.exec(cmd, args, opts), "npm", ["install", "--omit=dev"], { cwd: extDir });
       if (npmInstall.code !== 0) {
         ctx.ui.notify(
           "Could not install extension dependencies.\n" +
@@ -177,7 +179,7 @@ async function updateSupipowers(
 
 export function handleUpdate(platform: Platform, ctx: PlatformContext): void {
   void (async () => {
-    const exec = (cmd: string, args: string[]) => platform.exec(cmd, args);
+    const exec = wrapExecForCli((cmd: string, args: string[]) => platform.exec(cmd, args));
 
     // 1. Scan all dependencies
     const allStatuses = await scanAll(exec);

package/src/harness/anti_slop/fallow-adapter.ts

@@ -25,6 +25,7 @@ import {
   type SlopBackendResult,
   type SlopFinding,
 } from "./backend.js";
+import { execCli } from "../../utils/exec-cli.js";
 
 const DEFAULT_TIMEOUT_MS = 60_000;
 
@@ -149,7 +150,7 @@ async function resolveInvocation(
   }
 
   try {
-    const probe = await platform.exec("npx", ["--no-install", "fallow", "--version"], { timeout: 5000 });
+    const probe = await execCli((cmd, args, opts) => platform.exec(cmd, args, opts), "npx", ["--no-install", "fallow", "--version"], { timeout: 5000 });
     if (probe.code === 0) {
       availabilityCache = { ok: true, via: "npx" };
       return { ok: true, cmd: "npx", baseArgs: ["--no-install", "fallow"], via: "npx" };
@@ -187,7 +188,7 @@ async function runFallow(
   const startedAt = Date.now();
   let result;
   try {
-    result = await platform.exec(invocation.cmd, args, {
+    result = await execCli((cmd, args, opts) => platform.exec(cmd, args, opts), invocation.cmd, args, {
       cwd: opts.cwd,
       timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
     });
@@ -269,7 +270,7 @@ export class FallowAdapter implements SlopBackend {
     if (opts.subtree) args.push("--path", opts.subtree);
 
     try {
-      const result = await platform.exec(invocation.cmd, args, {
+      const result = await execCli((cmd, args, opts) => platform.exec(cmd, args, opts), invocation.cmd, args, {
         cwd: opts.cwd,
         timeout: opts.timeoutMs ?? DEFAULT_TIMEOUT_MS,
       });

package/src/harness/command.ts

@@ -45,7 +45,6 @@ import {
 import { computeScore } from "./anti_slop/score.js";
 import {
   type BuildRunnerInput,
-  type HarnessPipelineProgressEvent,
   type PipelineRunOutcome,
   HARNESS_STAGE_ORDER,
   runHarnessPipelineUntilGate,
@@ -58,7 +57,7 @@ import { DEFAULT_HARNESS_CONFIG } from "./hooks/register.js";
 import { handlePrComment } from "./pr-comment/handler.js";
 import { runGitVerificationQa } from "./git-verify-qa.js";
 import { getHarnessSessionDir } from "./project-paths.js";
-import type { HarnessDesignSpec, HarnessGateMode, HarnessSession, HarnessStage } from "../types.js";
+import type { HarnessDesignSpec, HarnessGateMode, HarnessPipelineProgressEvent, HarnessSession, HarnessStage } from "../types.js";
 
 modelRegistry.register({
   id: "harness",
@@ -133,9 +132,11 @@ function createHarnessProgress(ctx: HarnessCommandContext) {
   let done = 0;
   let cur: HarnessStage | null = null;
   const completed: string[] = [];
+  let liveDetail: string | null = null;
 
   function refresh() {
-    const label = cur ? HARNESS_STAGE_LABELS[cur] : "Complete";
+    const baseLabel = cur ? HARNESS_STAGE_LABELS[cur] : "Complete";
+    const label = cur && liveDetail ? `${baseLabel} — ${liveDetail}` : baseLabel;
     const spinner = cur ? "\u25cc" : "\u2713";
     (ctx.ui as any).setStatus?.("supi-harness", `  ${spinner} harness: ${label} (${done}/${SO.length})`);
   }
@@ -147,22 +148,26 @@ function createHarnessProgress(ctx: HarnessCommandContext) {
         case "stage-started":
           cur = event.stage;
           break;
+        case "stage-progress":
+          cur = event.stage;
+          liveDetail = event.detail;
+          break;
         case "stage-completed": {
-          done += 1; cur = null;
+          done += 1; cur = null; liveDetail = null;
           const mark = "\u2713";
           completed.push(`${mark} ${HARNESS_STAGE_LABELS[event.stage]}: ${event.detail || "done"}`);
           break;
         }
         case "stage-skipped":
-          done += 1; cur = null;
+          done += 1; cur = null; liveDetail = null;
           completed.push(`\u2013 ${HARNESS_STAGE_LABELS[event.stage]}: skipped`);
           break;
         case "awaiting-user":
-          done += 1; cur = null;
+          done += 1; cur = null; liveDetail = null;
           completed.push(`\u25cb ${HARNESS_STAGE_LABELS[event.stage]}: ${event.detail || "awaiting review"}`);
           break;
         case "stage-failed": case "stage-blocked":
-          cur = null;
+          cur = null; liveDetail = null;
           completed.push(`\u2717 ${HARNESS_STAGE_LABELS[event.stage]}: ${event.detail || "failed"}`);
           break;
       }

package/src/harness/pipeline.ts

@@ -14,6 +14,7 @@ import * as path from "node:path";
 import type { Platform, PlatformPaths } from "../platform/types.js";
 import type {
   HarnessGateMode,
+  HarnessPipelineProgressEvent,
   HarnessStage,
   ModelConfig,
 } from "../types.js";
@@ -38,14 +39,6 @@ import { buildBackendAdapter } from "./anti_slop/backend-factory.js";
 import { DEFAULT_HARNESS_CONFIG } from "./hooks/register.js";
 import { getProjectStatePath } from "../workspace/state-paths.js";
 
-/** Progress event emitted by the pipeline driver for UI feedback. */
-export type HarnessPipelineProgressEvent =
-  | { type: "stage-started"; stage: HarnessStage }
-  | { type: "stage-skipped"; stage: HarnessStage }
-  | { type: "stage-completed"; stage: HarnessStage; detail?: string }
-  | { type: "stage-blocked"; stage: HarnessStage; detail: string }
-  | { type: "stage-failed"; stage: HarnessStage; detail: string }
-  | { type: "awaiting-user"; stage: HarnessStage; detail?: string };
 
 const STAGE_ORDER: readonly HarnessStage[] = [
   "discover",
@@ -301,6 +294,7 @@ export async function runHarnessPipelineUntilGate(
       sessionId: input.sessionId,
       modelConfig: input.modelConfig,
       gateMode: input.gates,
+      onProgress: (event) => input.onProgress?.(event),
     };
 
     const result = await runner.run(ctx);

package/src/harness/stage-runner.ts

@@ -21,6 +21,7 @@
 import type { Platform, PlatformPaths } from "../platform/types.js";
 import type {
   HarnessGateMode,
+  HarnessPipelineProgressEvent,
   HarnessStage,
   HarnessStageStatus,
   ModelConfig,
@@ -46,6 +47,8 @@ export interface HarnessStageRunnerContext {
   now?: () => string;
   /** Optional override for the agent session model. Tests use this to bypass resolution. */
   modelOverride?: { model: string; thinkingLevel: string | null };
+  /** Live progress sink for long-running stage internals such as subagent turns. */
+  onProgress?: (event: HarnessPipelineProgressEvent) => void;
 }
 
 export type HarnessStageRunStatus =

package/src/harness/stages/docs.ts

@@ -90,6 +90,7 @@ export interface DocsStageInput {
 }
 
 interface AgentSessionLike {
+  subscribe?: (handler: (event: unknown) => void) => () => void;
   prompt(text: string, opts?: { expandPromptTemplates?: boolean }): Promise<void>;
   dispose(): Promise<void>;
 }
@@ -536,6 +537,60 @@ async function orchestrateLayerSubagent(input: OrchestrateLayerInput): Promise<O
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key];
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function nestedStringField(record: Record<string, unknown>, objectKey: string, fieldKey: string): string | null {
+  const nested = record[objectKey];
+  if (!isRecord(nested)) return null;
+  return stringField(nested, fieldKey);
+}
+
+function compactDetail(value: string, maxChars = 180): string {
+  const compact = value.replace(/\s+/g, " ").trim();
+  if (compact.length <= maxChars) return compact;
+  return `${compact.slice(0, maxChars - 1).trimEnd()}…`;
+}
+
+function summarizeAgentSessionEvent(event: unknown): string | null {
+  if (!isRecord(event)) return null;
+  const type = stringField(event, "type") ?? stringField(event, "kind") ?? stringField(event, "event");
+  const lowerType = type?.toLowerCase() ?? "";
+  const toolName =
+    stringField(event, "toolName") ??
+    stringField(event, "tool") ??
+    stringField(event, "name") ??
+    nestedStringField(event, "toolCall", "name") ??
+    nestedStringField(event, "tool_call", "name");
+  if (toolName && (lowerType.includes("tool") || lowerType.includes("call"))) {
+    return `tool ${compactDetail(toolName, 80)}`;
+  }
+
+  const text =
+    stringField(event, "text") ??
+    stringField(event, "delta") ??
+    stringField(event, "thought") ??
+    stringField(event, "content") ??
+    nestedStringField(event, "message", "text") ??
+    nestedStringField(event, "message", "content");
+  if (text) {
+    const prefix = lowerType.includes("thought") || lowerType.includes("reason")
+      ? "thought"
+      : lowerType.includes("tool")
+        ? "tool"
+        : "agent";
+    return `${prefix} ${compactDetail(text)}`;
+  }
+
+  return type ? compactDetail(type, 80) : null;
+}
+
 async function dispatchSubagent(input: {
   platform: Platform;
   ctx: HarnessStageRunnerContext;
@@ -548,7 +603,13 @@ async function dispatchSubagent(input: {
   const agentDisplayName = buildHarnessAgentDisplayName("docs", input.entry.layer.layer);
 
   let session: AgentSessionLike | null = null;
+  let unsubscribe: (() => void) | null = null;
   try {
+    input.ctx.onProgress?.({
+      type: "stage-progress",
+      stage: "docs",
+      detail: `${agentDisplayName}: starting attempt ${input.attempt}`,
+    });
     if (input.factory) {
       session = await input.factory(input.platform, {
         cwd: input.ctx.cwd,
@@ -562,7 +623,21 @@ async function dispatchSubagent(input: {
         agentDisplayName,
       });
     }
+    unsubscribe = session.subscribe?.((event) => {
+      const summary = summarizeAgentSessionEvent(event);
+      if (!summary) return;
+      input.ctx.onProgress?.({
+        type: "stage-progress",
+        stage: "docs",
+        detail: `${agentDisplayName}: ${summary}`,
+      });
+    }) ?? null;
     await session.prompt(input.assignment, { expandPromptTemplates: false });
+    input.ctx.onProgress?.({
+      type: "stage-progress",
+      stage: "docs",
+      detail: `${agentDisplayName}: attempt ${input.attempt} complete`,
+    });
   } catch (error) {
     return {
       ok: false,
@@ -571,6 +646,13 @@ async function dispatchSubagent(input: {
       ],
     };
   } finally {
+    if (unsubscribe) {
+      try {
+        unsubscribe();
+      } catch {
+        /* best-effort */
+      }
+    }
     if (session) {
       try {
         await session.dispose();

package/src/mempalace/uv.ts

@@ -49,17 +49,22 @@ export function uvTargetFor(uvPlatform: UvPlatform): UvTarget {
     case "linux-arm64":
       return target("aarch64-unknown-linux-gnu", ".tar.gz", "uv");
     case "win32-x64":
-      return target("x86_64-pc-windows-msvc", ".zip", "uv.exe");
+      return target("x86_64-pc-windows-msvc", ".zip", "uv.exe", "uv.exe");
   }
 }
 
-function target(triple: string, archiveSuffix: string, binary: string): UvTarget {
+function target(
+  triple: string,
+  archiveSuffix: string,
+  binary: string,
+  archiveBinaryRelativePath = path.join(`uv-${triple}`, binary),
+): UvTarget {
   const archive = `uv-${triple}${archiveSuffix}`;
   return {
     triple,
     archive,
     binary,
-    archiveBinaryRelativePath: path.join(`uv-${triple}`, binary),
+    archiveBinaryRelativePath,
   };
 }
 
@@ -226,11 +231,14 @@ export async function ensureUv(options: EnsureUvOptions): Promise<EnsureUvResult
     };
   }
 
-  // Replace any pre-existing managed binary atomically-ish.
-  if (fs.existsSync(managedPath)) {
-    try { fs.unlinkSync(managedPath); } catch { /* best effort */ }
+  // Replace any pre-existing managed binary atomically-ish. Windows uv zips place
+  // uv.exe at the archive root, which is already `managedPath` after extraction.
+  if (path.resolve(extractedBinary) !== path.resolve(managedPath)) {
+    if (fs.existsSync(managedPath)) {
+      try { fs.unlinkSync(managedPath); } catch { /* best effort */ }
+    }
+    fs.renameSync(extractedBinary, managedPath);
   }
-  fs.renameSync(extractedBinary, managedPath);
   if (process.platform !== "win32") {
     fs.chmodSync(managedPath, 0o755);
   }

package/src/planning/approval-flow.ts

@@ -278,7 +278,7 @@ async function executeApproveFlow(
       debugLogger?.log("execution_handoff_new_session_cancelled", {
         planPath,
       });
-      ctx.ui.notify("Session start cancelled. Plan saved; run /supi:plan again to execute.");
+      ctx.ui?.notify?.("Session start cancelled. Plan saved; run /supi:plan again to execute.");
       return;
     }
     platform.sendUserMessage(prompt);
@@ -298,7 +298,7 @@ async function executeApproveFlow(
     debugLogger?.log("execution_handoff_same_session_steer_sent", {
       planPath,
     });
-    ctx.ui.notify("Plan approved — starting execution");
+    ctx.ui?.notify?.("Plan approved — starting execution");
   }
 }
 
@@ -408,25 +408,23 @@ export function registerPlanApprovalHook(platform: Platform): void {
       });
     } catch {}
     if (!ctx?.hasUI) {
-      const message = [
-        `Plan saved to \`${planPath}\`.`,
-        "Interactive approval is unavailable in this runtime, so no execution was started.",
-        `To continue manually, explicitly send: \`Execute the saved plan at ${planPath} step by step; verify each step before proceeding.\``,
-      ].join("\n");
-      debugLogger?.log("approval_flow_no_ui", {
+      debugLogger?.log("approval_flow_no_ui_auto_execute", {
         planName,
         planPath,
       });
-      ctx?.ui?.notify?.("Plan saved; interactive approval is required before execution.", "warning");
-      platform.sendMessage(
-        {
-          customType: "supi-plan-awaiting-interactive-approval",
-          content: [{ type: "text", text: message }],
-          display: true,
-        },
-        { deliverAs: "steer", triggerTurn: false },
-      );
+      const executionNewSession = capturedNewSession;
+      const executionModel = capturedResolvedModel;
       cancelPlanTracking();
+      await executeApproveFlow(
+        platform,
+        ctx,
+        canonicalContent,
+        planPath,
+        executionNewSession,
+        executionModel,
+        debugLogger,
+        parsedPlan,
+      );
       return;
     }
 

package/src/types.ts

@@ -1550,6 +1550,16 @@ export type HarnessStage =
   | "docs"
   | "validate";
 
+/** Progress event emitted by harness pipeline drivers and long-running stages. */
+export type HarnessPipelineProgressEvent =
+  | { type: "stage-started"; stage: HarnessStage }
+  | { type: "stage-progress"; stage: HarnessStage; detail: string }
+  | { type: "stage-skipped"; stage: HarnessStage }
+  | { type: "stage-completed"; stage: HarnessStage; detail?: string }
+  | { type: "stage-blocked"; stage: HarnessStage; detail: string }
+  | { type: "stage-failed"; stage: HarnessStage; detail: string }
+  | { type: "awaiting-user"; stage: HarnessStage; detail?: string };
+
 /** Operational status of a harness stage. Mirrors UltraPlanAuthoringStageStatus. */
 export type HarnessStageStatus =
   | "pending"

package/src/utils/exec-cli.ts

@@ -0,0 +1,106 @@
+import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
+
+import type { ExecOptions, ExecResult } from "../platform/types.js";
+import { findExecutable } from "./executable.js";
+
+/**
+ * Cross-platform invocation for npm/npx that survives Windows `.cmd` shims.
+ *
+ * OMP's `platform.exec` is a thin wrapper over libuv's `uv_spawn`. On Windows
+ * that exposes two distinct bugs when the target is an npm-shipped CLI:
+ *
+ *   1. libuv does not consult `PATHEXT`, so spawning `"npm"` fails with
+ *      `ENOENT: uv_spawn 'npm'` because the on-disk file is `npm.cmd`.
+ *   2. Even when callers resolve the absolute path, Node ≥18.20.2 hard-rejects
+ *      spawning `.cmd`/`.bat` shims without `shell: true` (CVE-2024-27980).
+ *      `ExecOptions` does not expose `shell`.
+ *
+ * Wrapping in `cmd.exe /d /s /c` is the canonical workaround, but only safe
+ * when the spawner sets `windowsVerbatimArguments: true` — Node's default
+ * CRT escaping double-quotes the command line and cmd's `/s` only strips one
+ * pair. We don't control the spawner, so we sidestep the whole problem by
+ * resolving the shim to the real `node <cli.js>` invocation, which is exactly
+ * what `npm.cmd` does internally. `node.exe` is a plain binary that libuv
+ * spawns without ceremony.
+ *
+ * Non-shim binaries (`bun`, `git`, `node`, `gh`, `rustup`, `go`, `pip`, …
+ * all ship as `.exe` on Windows) pass through untouched; POSIX always passes
+ * through.
+ */
+
+export type ExecFn = (
+  cmd: string,
+  args: string[],
+  opts?: ExecOptions,
+) => Promise<ExecResult>;
+
+interface ResolvedInvocation {
+  cmd: string;
+  prefixArgs: string[];
+}
+
+const NODE_SHIMS = new Set<string>(["npm", "npx"]);
+const resolutionCache = new Map<string, ResolvedInvocation>();
+
+function resolveNodeShim(command: string): ResolvedInvocation | null {
+  if (!NODE_SHIMS.has(command)) return null;
+
+  // node.exe is the executor; npm-cli.js / npx-cli.js sits next to it under
+  // node_modules/npm/bin/. We deliberately key off node's location (not the
+  // shim's) because `npm.cmd` can live in a user-global dir (e.g. nvm,
+  // %AppData%\npm) while the actual CLI bundle stays alongside node.
+  const nodeBin = findExecutable("node");
+  if (!nodeBin) return null;
+
+  const cliJs = join(
+    dirname(nodeBin),
+    "node_modules",
+    "npm",
+    "bin",
+    `${command}-cli.js`,
+  );
+  if (!existsSync(cliJs)) return null;
+
+  return { cmd: nodeBin, prefixArgs: [cliJs] };
+}
+
+function resolveInvocation(command: string): ResolvedInvocation {
+  if (process.platform !== "win32") {
+    return { cmd: command, prefixArgs: [] };
+  }
+  const cached = resolutionCache.get(command);
+  if (cached) return cached;
+
+  const resolved = resolveNodeShim(command) ?? { cmd: command, prefixArgs: [] };
+  resolutionCache.set(command, resolved);
+  return resolved;
+}
+
+/**
+ * Drop-in replacement for `platform.exec` callers that invoke npm/npx by name.
+ * Other commands pass through unchanged.
+ */
+export function execCli(
+  exec: ExecFn,
+  command: string,
+  args: string[],
+  opts?: ExecOptions,
+): Promise<ExecResult> {
+  const resolved = resolveInvocation(command);
+  return exec(resolved.cmd, [...resolved.prefixArgs, ...args], opts);
+}
+
+/**
+ * Wrap an `ExecFn` so every call routes through `execCli`. Use when threading
+ * an exec callback into helpers that dispatch arbitrary tools by string name
+ * (e.g. the deps installer which splits install-command strings).
+ */
+export function wrapExecForCli(exec: ExecFn): ExecFn {
+  return (cmd, args, opts) => execCli(exec, cmd, args, opts);
+}
+
+/** Clears cached CLI resolutions after PATH or tooling changes. */
+export function clearExecCliResolutionCache(): void {
+  resolutionCache.clear();
+}