@opengsd/gsd-pi 1.0.2-dev.d456457 → 1.0.2-dev.dbfb371

package/src/resources/extensions/gsd/auto-worktree.ts

@@ -59,6 +59,7 @@ import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
+import { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 import {
   nativeGetCurrentBranch,
   nativeDetectMainBranch,
@@ -912,62 +913,7 @@ export function syncWorktreeStateBack(
 ): { synced: string[] } {
   return _finalizeProjectionForMergeImpl(mainBasePath, worktreePath, milestoneId);
 }
-// ─── Worktree Post-Create Hook (#597) ────────────────────────────────────────
-
-/**
- * Run the user-configured post-create hook script after worktree creation.
- * The script receives SOURCE_DIR and WORKTREE_DIR as environment variables.
- * Failure is non-fatal — returns the error message or null on success.
- *
- * Reads the hook path from git.worktree_post_create in preferences.
- * Pass hookPath directly to bypass preference loading (useful for testing).
- */
-export function runWorktreePostCreateHook(
-  sourceDir: string,
-  worktreeDir: string,
-  hookPath?: string,
-): string | null {
-  if (hookPath === undefined) {
-    const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
-    hookPath = prefs?.worktree_post_create;
-  }
-  if (!hookPath) return null;
-
-  // Resolve relative paths against the source project root.
-  // On Windows, convert 8.3 short paths (e.g. RUNNER~1) to long paths
-  // so execFileSync can locate the file correctly.
-  let resolved = isAbsolute(hookPath) ? hookPath : join(sourceDir, hookPath);
-  if (!existsSync(resolved)) {
-    return `Worktree post-create hook not found: ${resolved}`;
-  }
-  if (process.platform === "win32") {
-    try { resolved = realpathSync.native(resolved); } catch (err) { /* keep original */
-      logWarning("worktree", `realpath failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
-
-  try {
-    // .bat/.cmd files on Windows require shell mode — execFileSync cannot
-    // spawn them directly (EINVAL).
-    const needsShell = process.platform === "win32" && /\.(bat|cmd)$/i.test(resolved);
-    execFileSync(resolved, [], {
-      cwd: worktreeDir,
-      env: {
-        ...process.env,
-        SOURCE_DIR: sourceDir,
-        WORKTREE_DIR: worktreeDir,
-      },
-      stdio: ["ignore", "pipe", "pipe"],
-      encoding: "utf-8",
-      timeout: 30_000, // 30 second timeout
-      shell: needsShell,
-    });
-    return null;
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return `Worktree post-create hook failed: ${msg}`;
-  }
-}
+export { runWorktreePostCreateHook } from "./worktree-post-create-hook.js";
 
 // ─── Auto-Worktree Branch Naming ───────────────────────────────────────────
 

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -507,6 +507,21 @@ function initSessionNotifications(ctx: ExtensionContext): void {
   initNotificationWidget(ctx);
 }
 
+async function prepareWorkflowMcpForHookContext(
+  ctx: ExtensionContext,
+  basePath: string,
+): Promise<void> {
+  // Skip MCP auto-prep when running inside an auto-worktree. The worktree
+  // already has .mcp.json from createAutoWorktree, and re-running the writer
+  // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative
+  // CLI path resolution), dirtying the tree and breaking the milestone merge.
+  const { isInAutoWorktree } = await import("../auto-worktree.js");
+  if (isInAutoWorktree(basePath)) return;
+
+  const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
+  prepareWorkflowMcpForProject(ctx, basePath);
+}
+
 export function registerHooks(
   pi: ExtensionAPI,
   ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[],
@@ -532,12 +547,7 @@ export function registerHooks(
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
     await applyCompactionThresholdOverride(ctx);
-    // Skip MCP auto-prep when running inside an auto-worktree (see session_switch below).
-    const { isInAutoWorktree } = await import("../auto-worktree.js");
-    if (!isInAutoWorktree(basePath)) {
-      const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-      prepareWorkflowMcpForProject(ctx, basePath);
-    }
+    await prepareWorkflowMcpForHookContext(ctx, basePath);
 
     // Apply show_token_cost preference (#1515)
     try {
@@ -563,15 +573,7 @@ export function registerHooks(
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
     await applyCompactionThresholdOverride(ctx);
-    // Skip MCP auto-prep when running inside an auto-worktree. The worktree
-    // already has .mcp.json from createAutoWorktree, and re-running the writer
-    // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative
-    // CLI path resolution), dirtying the tree and breaking the milestone merge.
-    const { isInAutoWorktree } = await import("../auto-worktree.js");
-    if (!isInAutoWorktree(basePath)) {
-      const { prepareWorkflowMcpForProject } = await import("../workflow-mcp-auto-prep.js");
-      prepareWorkflowMcpForProject(ctx, basePath);
-    }
+    await prepareWorkflowMcpForHookContext(ctx, basePath);
     await loadToolApiKeysForSession();
     if (!isAutoActive()) {
       ctx.ui.setWidget("gsd-progress", undefined);
@@ -608,6 +610,11 @@ export function registerHooks(
     }
     clearDeferredApprovalGate(beforeAgentBasePath);
 
+    // session_start can fire before the active provider has settled. By
+    // before_agent_start, Claude Code CLI sessions should get the same
+    // project MCP config that /gsd mcp init would write.
+    await prepareWorkflowMcpForHookContext(ctx, beforeAgentBasePath);
+
     // GSD's own context injection (existing behavior — unchanged).
     const { buildBeforeAgentStartResult } = await import("./system-context.js");
     const gsdResult = await buildBeforeAgentStartResult(event, ctx);

package/src/resources/extensions/gsd/commands-handlers.ts

@@ -26,6 +26,7 @@ import { isAutoActive, checkRemoteAutoSession } from "./auto.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { currentDirectoryRoot, projectRoot } from "./commands/context.js";
 import { loadPrompt } from "./prompt-loader.js";
+import { isPnpmInstall } from "../../shared/package-manager-detection.js";
 import {
   buildDoctorHealIssuePayload,
   buildDoctorHealSummary,
@@ -57,6 +58,7 @@ function isBunInstall(argv1: string | undefined = process.argv[1]): boolean {
 
 function resolveInstallCommand(pkg: string): string {
   if (isBunInstall()) return `bun add -g ${pkg}`;
+  if (isPnpmInstall()) return `pnpm add -g ${pkg}`;
   return `npm install -g ${pkg}`;
 }
 

package/src/resources/extensions/gsd/tests/custom-engine-loop-integration.test.ts

@@ -344,6 +344,70 @@ describe("Custom engine loop integration", () => {
     );
   });
 
+  it("step mode stops after one custom workflow step", async () => {
+    _resetPendingResolve();
+
+    const runDir = makeTmpDir();
+    const graph = makeGraph([
+      makeStep({ id: "step-a" }),
+      makeStep({ id: "step-b", dependsOn: ["step-a"] }),
+      makeStep({ id: "step-c", dependsOn: ["step-b"] }),
+    ], "step-mode-custom");
+    writeGraph(runDir, graph);
+    writeDefinition(runDir, graph.steps, "step-mode-custom");
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const s = makeLoopSession({
+      activeEngineId: "custom",
+      activeRunDir: runDir,
+      basePath: runDir,
+      stepMode: true,
+    });
+
+    const deps = makeMockDeps({
+      stopAuto: async (_ctx, _pi, reason) => {
+        deps.callLog.push(`stopAuto:${reason ?? "no-reason"}`);
+        s.active = false;
+      },
+    });
+
+    const loopPromise = autoLoop(ctx, pi, s, deps);
+    await resolveNextAgentEnd();
+
+    let timeout: NodeJS.Timeout | undefined;
+    try {
+      await Promise.race([
+        loopPromise,
+        new Promise((_, reject) =>
+          timeout = setTimeout(() => {
+            s.active = false;
+            if (_hasPendingResolveForTest()) {
+              resolveAgentEnd({ messages: [{ role: "assistant" }] });
+            }
+            reject(new Error(
+              `step mode did not stop after one custom workflow step; calls=${pi.calls.length}; log=${deps.callLog.join(",")}`,
+            ));
+          }, 1_000),
+        ),
+      ]);
+    } finally {
+      if (timeout) clearTimeout(timeout);
+    }
+
+    const finalGraph = readGraph(runDir);
+    assert.equal(pi.calls.length, 1, "step mode should dispatch exactly one custom step");
+    assert.equal(finalGraph.steps[0]?.status, "complete", "first step should complete");
+    assert.equal(finalGraph.steps[1]?.status, "pending", "second step should wait for the next /gsd next");
+    assert.equal(finalGraph.steps[2]?.status, "pending", "third step should wait for a later step");
+    assert.equal(
+      deps.callLog.some((e: string) => e.startsWith("stopAuto:")),
+      false,
+      "step-mode pause should not complete or stop the whole workflow",
+    );
+    assert.equal(s.preserveStepSurfaceAfterLoopExit, true);
+  });
+
   it("stops when engine reports isComplete on first derive", async () => {
     _resetPendingResolve();
 

package/src/resources/extensions/gsd/tests/workflow-mcp-auto-prep.test.ts

@@ -1,6 +1,11 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
+import { registerHooks } from "../bootstrap/register-hooks.ts";
+import { GSD_WORKFLOW_MCP_SERVER_NAME } from "../mcp-project-config.ts";
 import { prepareWorkflowMcpForProject, shouldAutoPrepareWorkflowMcp } from "../workflow-mcp-auto-prep.ts";
 
 test("shouldAutoPrepareWorkflowMcp enables prep for externalCli local transport", () => {
@@ -74,3 +79,58 @@ test("prepareWorkflowMcpForProject warns with /gsd mcp init guidance when prep f
   assert.equal(notifications[0].level, "warning");
   assert.match(notifications[0].message, /Please run \/gsd mcp init \./);
 });
+
+test("before_agent_start auto-prepares project workflow MCP for Claude Code CLI", async (t) => {
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-before-agent-"));
+  const originalCwd = process.cwd();
+  const notifications: string[] = [];
+  const handlers = new Map<string, Array<(event: any, ctx?: any) => Promise<any> | any>>();
+  const pi = {
+    on(event: string, handler: (event: any, ctx?: any) => Promise<any> | any) {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+    getActiveTools: () => [],
+    getAllTools: () => [],
+    setActiveTools() {},
+  };
+
+  t.after(() => {
+    process.chdir(originalCwd);
+    rmSync(projectRoot, { recursive: true, force: true });
+  });
+
+  process.chdir(projectRoot);
+  registerHooks(pi as any, []);
+
+  const beforeAgentStart = handlers.get("before_agent_start")?.[0];
+  assert.ok(beforeAgentStart, "before_agent_start hook should be registered");
+
+  await beforeAgentStart(
+    { prompt: "hello", systemPrompt: "base" },
+    {
+      cwd: projectRoot,
+      model: { provider: "claude-code", baseUrl: "local://claude-code" },
+      modelRegistry: {
+        getProviderAuthMode: () => "externalCli",
+        isProviderRequestReady: () => true,
+      },
+      ui: {
+        notify(message: string) {
+          notifications.push(message);
+        },
+        setWidget() {},
+      },
+    },
+  );
+
+  const configPath = join(projectRoot, ".mcp.json");
+  assert.equal(existsSync(configPath), true, "Claude Code CLI turns should create project MCP config");
+
+  const parsed = JSON.parse(readFileSync(configPath, "utf-8")) as {
+    mcpServers?: Record<string, unknown>;
+  };
+  assert.ok(parsed.mcpServers?.[GSD_WORKFLOW_MCP_SERVER_NAME]);
+  assert.match(notifications.join("\n"), /Claude Code MCP prepared/);
+});

package/src/resources/extensions/gsd/tests/worktree-post-create-hook.test.ts

@@ -13,7 +13,7 @@ import { mkdtempSync, mkdirSync, rmSync, existsSync, writeFileSync, readFileSync
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { runWorktreePostCreateHook } from "../auto-worktree.ts";
+import { runWorktreePostCreateHook } from "../worktree-post-create-hook.ts";
 
 function makeTmpDir(): string {
   return mkdtempSync(join(tmpdir(), "gsd-wt-hook-test-"));
@@ -45,10 +45,150 @@ function writeNodeHookScript(filePath: string, code: string): void {
 test("returns null when no hook path is provided", () => {
   const src = makeTmpDir();
   const wt = makeTmpDir();
+  const previousGsdHome = process.env.GSD_HOME;
   try {
+    process.env.GSD_HOME = join(src, "empty-gsd-home");
     const result = runWorktreePostCreateHook(src, wt, undefined);
     assert.equal(result, null);
   } finally {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("reads git.worktree_post_create from project preferences without loading auto-worktree", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  const previousGsdHome = process.env.GSD_HOME;
+  try {
+    process.env.GSD_HOME = join(src, "empty-gsd-home");
+    const hooksDir = join(src, ".gsd", "hooks");
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(
+      join(src, ".gsd", "PREFERENCES.md"),
+      [
+        "---",
+        "git:",
+        `  worktree_post_create: ${hookPath(".gsd/hooks/post-create")}`,
+        "---",
+        "",
+      ].join("\n"),
+    );
+    const hookFile = hookPath(join(hooksDir, "post-create"));
+    writeNodeHookScript(
+      hookFile,
+      `require("fs").writeFileSync(require("path").join(process.env.WORKTREE_DIR, "configured-hook-ran"), "ok");`,
+    );
+
+    const result = runWorktreePostCreateHook(src, wt);
+
+    assert.equal(result, null);
+    assert.ok(existsSync(join(wt, "configured-hook-ran")), "configured hook should run");
+  } finally {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("prefers canonical project PREFERENCES.md over legacy lowercase preferences.md", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  const previousGsdHome = process.env.GSD_HOME;
+  try {
+    process.env.GSD_HOME = join(src, "empty-gsd-home");
+    const hooksDir = join(src, ".gsd", "hooks");
+    mkdirSync(hooksDir, { recursive: true });
+    writeFileSync(
+      join(src, ".gsd", "preferences.md"),
+      [
+        "---",
+        "git:",
+        `  worktree_post_create: ${hookPath(".gsd/hooks/legacy")}`,
+        "---",
+        "",
+      ].join("\n"),
+    );
+    writeFileSync(
+      join(src, ".gsd", "PREFERENCES.md"),
+      [
+        "---",
+        "git:",
+        `  worktree_post_create: ${hookPath(".gsd/hooks/canonical")}`,
+        "---",
+        "",
+      ].join("\n"),
+    );
+    writeNodeHookScript(
+      hookPath(join(hooksDir, "canonical")),
+      `require("fs").writeFileSync(require("path").join(process.env.WORKTREE_DIR, "configured-hook-ran"), "canonical");`,
+    );
+    writeNodeHookScript(
+      hookPath(join(hooksDir, "legacy")),
+      `require("fs").writeFileSync(require("path").join(process.env.WORKTREE_DIR, "configured-hook-ran"), "legacy");`,
+    );
+
+    const result = runWorktreePostCreateHook(src, wt);
+
+    assert.equal(result, null);
+    assert.equal(readFileSync(join(wt, "configured-hook-ran"), "utf-8"), "canonical");
+  } finally {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
+    rmSync(src, { recursive: true, force: true });
+    rmSync(wt, { recursive: true, force: true });
+  }
+});
+
+test("prefers canonical global PREFERENCES.md over legacy lowercase preferences.md", () => {
+  const src = makeTmpDir();
+  const wt = makeTmpDir();
+  const previousGsdHome = process.env.GSD_HOME;
+  try {
+    const gsdHomeDir = join(src, "global-gsd-home");
+    process.env.GSD_HOME = gsdHomeDir;
+    const hooksDir = join(src, ".gsd", "hooks");
+    mkdirSync(hooksDir, { recursive: true });
+    mkdirSync(gsdHomeDir, { recursive: true });
+    writeFileSync(
+      join(gsdHomeDir, "preferences.md"),
+      [
+        "---",
+        "git:",
+        `  worktree_post_create: ${hookPath(".gsd/hooks/legacy")}`,
+        "---",
+        "",
+      ].join("\n"),
+    );
+    writeFileSync(
+      join(gsdHomeDir, "PREFERENCES.md"),
+      [
+        "---",
+        "git:",
+        `  worktree_post_create: ${hookPath(".gsd/hooks/canonical")}`,
+        "---",
+        "",
+      ].join("\n"),
+    );
+    writeNodeHookScript(
+      hookPath(join(hooksDir, "canonical")),
+      `require("fs").writeFileSync(require("path").join(process.env.WORKTREE_DIR, "configured-hook-ran"), "canonical");`,
+    );
+    writeNodeHookScript(
+      hookPath(join(hooksDir, "legacy")),
+      `require("fs").writeFileSync(require("path").join(process.env.WORKTREE_DIR, "configured-hook-ran"), "legacy");`,
+    );
+
+    const result = runWorktreePostCreateHook(src, wt);
+
+    assert.equal(result, null);
+    assert.equal(readFileSync(join(wt, "configured-hook-ran"), "utf-8"), "canonical");
+  } finally {
+    if (previousGsdHome === undefined) delete process.env.GSD_HOME;
+    else process.env.GSD_HOME = previousGsdHome;
     rmSync(src, { recursive: true, force: true });
     rmSync(wt, { recursive: true, force: true });
   }

package/src/resources/extensions/gsd/worktree-post-create-hook.ts

@@ -0,0 +1,127 @@
+// Project/App: gsd-pi
+// File Purpose: Lightweight worktree post-create hook runner.
+
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+import { parse as parseYaml } from "yaml";
+
+import { gsdHome } from "./gsd-home.js";
+import { gsdRoot } from "./paths.js";
+
+function readPreferencesObject(path: string): Record<string, unknown> | null {
+  if (!existsSync(path)) return null;
+
+  const content = readFileSync(path, "utf-8");
+  try {
+    const startMarker = content.startsWith("---\r\n") ? "---\r\n" : "---\n";
+    if (content.startsWith(startMarker)) {
+      const searchStart = startMarker.length;
+      const endIdx = content.indexOf("\n---", searchStart);
+      if (endIdx === -1) return null;
+
+      const parsed = parseYaml(content.slice(searchStart, endIdx).replace(/\r/g, ""));
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed as Record<string, unknown>
+        : null;
+    }
+
+    const gitLines: string[] = [];
+    let inGitSection = false;
+    for (const rawLine of content.split("\n")) {
+      const line = rawLine.replace(/\r$/, "");
+      const heading = line.match(/^##\s+(.+)$/);
+      if (heading) {
+        inGitSection = heading[1].trim().toLowerCase().replace(/\s+/g, "_") === "git";
+        continue;
+      }
+      if (inGitSection && line.trim() && !line.trimStart().startsWith("#")) {
+        gitLines.push(line.replace(/^\s*-\s*/, ""));
+      }
+    }
+    if (gitLines.length === 0) return null;
+
+    const parsed = parseYaml(gitLines.join("\n"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? { git: parsed as Record<string, unknown> }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function extractHookPath(preferences: Record<string, unknown> | null): string | null {
+  const git = preferences?.git;
+  if (!git || typeof git !== "object" || Array.isArray(git)) return null;
+  const hookPath = (git as Record<string, unknown>).worktree_post_create;
+  return typeof hookPath === "string" && hookPath.trim() ? hookPath : null;
+}
+
+function resolveConfiguredHookPath(sourceDir: string): string | null {
+  const paths = [
+    join(homedir(), ".pi", "agent", "gsd-preferences.md"),
+    join(gsdHome(), "preferences.md"),
+    join(gsdHome(), "PREFERENCES.md"),
+    join(gsdRoot(sourceDir), "preferences.md"),
+    join(gsdRoot(sourceDir), "PREFERENCES.md"),
+  ];
+
+  let hookPath: string | null = null;
+  for (const path of paths) {
+    hookPath = extractHookPath(readPreferencesObject(path)) ?? hookPath;
+  }
+  return hookPath;
+}
+
+/**
+ * Run the user-configured post-create hook script after worktree creation.
+ * The script receives SOURCE_DIR and WORKTREE_DIR as environment variables.
+ * Failure is non-fatal -- returns the error message or null on success.
+ *
+ * Reads git.worktree_post_create from effective global/project preferences
+ * unless hookPath is provided directly.
+ */
+export function runWorktreePostCreateHook(
+  sourceDir: string,
+  worktreeDir: string,
+  hookPath?: string,
+): string | null {
+  if (hookPath === undefined) {
+    hookPath = resolveConfiguredHookPath(sourceDir) ?? undefined;
+  }
+  if (!hookPath) return null;
+
+  let resolved = isAbsolute(hookPath) ? hookPath : join(sourceDir, hookPath);
+  if (!existsSync(resolved)) {
+    return `Worktree post-create hook not found: ${resolved}`;
+  }
+  if (process.platform === "win32") {
+    try {
+      resolved = realpathSync.native(resolved);
+    } catch {
+      // Keep the original path; the exec error below will include the failure.
+    }
+  }
+
+  try {
+    const needsShell = process.platform === "win32" && /\.(bat|cmd)$/i.test(resolved);
+    execFileSync(resolved, [], {
+      cwd: worktreeDir,
+      env: {
+        ...process.env,
+        SOURCE_DIR: sourceDir,
+        WORKTREE_DIR: worktreeDir,
+      },
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      timeout: 30_000,
+      shell: needsShell,
+    });
+    return null;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return `Worktree post-create hook failed: ${msg}`;
+  }
+}

package/src/resources/shared/package-manager-detection.ts

@@ -0,0 +1,39 @@
+import { homedir } from 'node:os'
+import { join, resolve as resolvePath, sep } from 'node:path'
+
+function hasPnpmPath(value: string | undefined): boolean {
+  if (!value) return false
+  const normalized = value.replace(/\\/g, '/').toLowerCase()
+  return (
+    normalized.includes('/.pnpm/') ||
+    normalized.endsWith('/pnpm') ||
+    normalized.endsWith('/pnpm.cjs') ||
+    normalized.endsWith('/pnpm.js')
+  )
+}
+
+function pathStartsWith(pathValue: string | undefined, dir: string): boolean {
+  if (!pathValue) return false
+  const resolvedPath = resolvePath(pathValue)
+  const resolvedDir = resolvePath(dir)
+  return resolvedPath === resolvedDir || resolvedPath.startsWith(resolvedDir + sep)
+}
+
+// Shared by update-check.ts and gsd command handlers. The JS installer keeps a
+// parallel copy because it runs before TypeScript output exists.
+export function isPnpmInstall(
+  argv1: string | undefined = process.argv[1],
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (env.npm_config_user_agent?.startsWith('pnpm/')) return true
+  if (hasPnpmPath(env.npm_execpath)) return true
+  if (hasPnpmPath(argv1)) return true
+  if (!argv1) return false
+
+  const pnpmBinDirs: string[] = []
+  if (env.PNPM_HOME) pnpmBinDirs.push(env.PNPM_HOME)
+  pnpmBinDirs.push(join(homedir(), 'Library', 'pnpm'))
+  pnpmBinDirs.push(join(homedir(), '.local', 'share', 'pnpm'))
+
+  return pnpmBinDirs.some((dir) => pathStartsWith(argv1, dir) || pathStartsWith(env.npm_execpath, dir))
+}