gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.8a893322c

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

@@ -46,6 +46,11 @@ import {
   resolveGitHeadPath,
   nudgeGitBranchCache,
 } from "./worktree.js";
+import {
+  isGsdWorktreePath,
+  normalizeWorktreePathForCompare,
+  resolveWorktreeProjectRoot,
+} from "./worktree-root.js";
 import { MergeConflictError, readIntegrationBranch, RUNTIME_EXCLUSION_PATHS } from "./git-service.js";
 import { debugLog } from "./debug-logger.js";
 import { logWarning, logError } from "./workflow-logger.js";
@@ -1202,6 +1207,8 @@ export function createAutoWorktree(
   basePath: string,
   milestoneId: string,
 ): string {
+  basePath = resolveWorktreeProjectRoot(basePath);
+
   // Check if repo has commits — git worktree requires a valid HEAD
   try {
     execFileSync("git", ["rev-parse", "--verify", "HEAD"], { cwd: basePath, stdio: "pipe" });
@@ -1361,6 +1368,8 @@ export function teardownAutoWorktree(
   milestoneId: string,
   opts: { preserveBranch?: boolean } = {},
 ): void {
+  originalBasePath = resolveWorktreeProjectRoot(originalBasePath);
+
   const branch = autoWorktreeBranch(milestoneId);
   const { preserveBranch = false } = opts;
   const previousCwd = process.cwd();
@@ -1412,16 +1421,28 @@ export function teardownAutoWorktree(
 
 /**
  * Detect if the process is currently inside an auto-worktree.
- * Checks both module state and git branch prefix.
+ * Uses the current directory structure plus git branch prefix so detection
+ * still works after process restart when module state has been reset.
  */
 export function isInAutoWorktree(basePath: string): boolean {
-  if (!originalBase) return false;
   const cwd = process.cwd();
-  const resolvedBase = existsSync(basePath) ? realpathSync(basePath) : basePath;
-  const wtDir = join(resolvedBase, ".gsd", "worktrees");
-  if (!cwd.startsWith(wtDir)) return false;
-  const branch = nativeGetCurrentBranch(cwd);
-  return branch.startsWith("milestone/");
+  if (!isGsdWorktreePath(cwd)) return false;
+
+  const projectRoot = resolveWorktreeProjectRoot(basePath, originalBase);
+  const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
+  if (
+    normalizeWorktreePathForCompare(projectRoot) !==
+    normalizeWorktreePathForCompare(cwdProjectRoot)
+  ) {
+    return false;
+  }
+
+  try {
+    const branch = nativeGetCurrentBranch(cwd);
+    return branch.startsWith("milestone/");
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -1436,6 +1457,8 @@ export function getAutoWorktreePath(
   basePath: string,
   milestoneId: string,
 ): string | null {
+  basePath = resolveWorktreeProjectRoot(basePath);
+
   const p = worktreePath(basePath, milestoneId);
   if (!existsSync(p)) return null;
 
@@ -1464,6 +1487,8 @@ export function enterAutoWorktree(
   basePath: string,
   milestoneId: string,
 ): string {
+  basePath = resolveWorktreeProjectRoot(basePath);
+
   const p = worktreePath(basePath, milestoneId);
   if (!existsSync(p)) {
     throw new GSDError(
@@ -1520,6 +1545,10 @@ export function getAutoWorktreeOriginalBase(): string | null {
   return originalBase;
 }
 
+export function _resetAutoWorktreeOriginalBaseForTests(): void {
+  originalBase = null;
+}
+
 export function getActiveAutoWorktreeContext(): {
   originalBase: string;
   worktreeName: string;
@@ -1527,11 +1556,14 @@ export function getActiveAutoWorktreeContext(): {
 } | null {
   if (!originalBase) return null;
   const cwd = process.cwd();
-  const resolvedBase = existsSync(originalBase)
-    ? realpathSync(originalBase)
-    : originalBase;
-  const wtDir = join(resolvedBase, ".gsd", "worktrees");
-  if (!cwd.startsWith(wtDir)) return null;
+  if (!isGsdWorktreePath(cwd)) return null;
+  const cwdProjectRoot = resolveWorktreeProjectRoot(cwd, originalBase);
+  if (
+    normalizeWorktreePathForCompare(cwdProjectRoot) !==
+    normalizeWorktreePathForCompare(originalBase)
+  ) {
+    return null;
+  }
   const worktreeName = detectWorktreeName(cwd);
   if (!worktreeName) return null;
   const branch = nativeGetCurrentBranch(cwd);

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

@@ -22,6 +22,7 @@ import { logWarning as safetyLogWarning } from "../workflow-logger.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
+import { extractSubagentAgentClasses } from "./subagent-input.js";
 
 // Skip the welcome screen on the very first session_start — cli.ts already
 // printed it before the TUI launched. Only re-print on /clear (subsequent sessions).
@@ -390,12 +391,16 @@ export function registerHooks(
       const manifest = resolveManifest(activeUnitType);
       if (manifest) {
         let planningInput = "";
+        let agentClasses: string[] | undefined;
         if (isToolCallEventType("write", event)) {
           planningInput = event.input.path;
         } else if (isToolCallEventType("edit", event)) {
           planningInput = event.input.path;
         } else if (isToolCallEventType("bash", event)) {
           planningInput = event.input.command;
+        } else if (event.toolName === "subagent" || event.toolName === "task") {
+          // Subagent inputs use { agent }, { tasks: [{ agent }] }, or { chain: [{ agent }] }.
+          agentClasses = extractSubagentAgentClasses((event as { input?: unknown }).input);
         }
         const planningGuard = shouldBlockPlanningUnit(
           event.toolName,
@@ -403,6 +408,7 @@ export function registerHooks(
           dash.basePath || discussionBasePath,
           activeUnitType,
           manifest.tools,
+          agentClasses,
         );
         if (planningGuard.block) return planningGuard;
       }
@@ -445,6 +451,19 @@ export function registerHooks(
     markToolStart(event.toolCallId, event.toolName);
     safetyRecordToolCall(event.toolCallId, event.toolName, event.input as Record<string, unknown>);
 
+    // Persist immediately at dispatch so a mid-unit re-dispatch — which calls
+    // resetEvidence() + loadEvidenceFromDisk() in runUnitPhase — cannot wipe
+    // the entry between tool_call and tool_execution_end. Without this, the
+    // race window equals the tool's runtime, producing the "no bash calls"
+    // false positive when the LLM clearly ran a verification command.
+    const callDash = getAutoRuntimeSnapshot();
+    if (callDash.basePath && callDash.currentUnit?.type === "execute-task") {
+      const { milestone: cMid, slice: cSid, task: cTid } = parseUnitId(callDash.currentUnit.id);
+      if (cMid && cSid && cTid) {
+        saveEvidenceToDisk(callDash.basePath, cMid, cSid, cTid);
+      }
+    }
+
     // Destructive command classification (warn only, never block)
     if (isToolCallEventType("bash", event)) {
       const classification = classifyCommand(event.input.command);

package/src/resources/extensions/gsd/bootstrap/subagent-input.ts

@@ -0,0 +1,20 @@
+export function extractSubagentAgentClasses(input: unknown): string[] {
+  if (!input || typeof input !== "object") return [];
+
+  const record = input as Record<string, unknown>;
+  const agentClasses: string[] = [];
+  const addAgentClass = (value: unknown): void => {
+    if (typeof value === "string" && value.trim().length > 0) agentClasses.push(value.trim());
+  };
+  const addFromItems = (value: unknown): void => {
+    if (!Array.isArray(value)) return;
+    for (const item of value) {
+      if (item && typeof item === "object") addAgentClass((item as Record<string, unknown>).agent);
+    }
+  };
+
+  addAgentClass(record.agent);
+  addFromItems(record.tasks);
+  addFromItems(record.chain);
+  return agentClasses;
+}

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -52,6 +52,17 @@ export const BUNDLED_SKILL_TRIGGERS: Array<{ trigger: string; skill: string }> =
   { trigger: "HTTP/REST/GraphQL API design — verbs, status codes, pagination, errors, idempotency, versioning", skill: "api-design" },
   { trigger: "Dependency upgrades — risk-batched, verified between batches, one major per commit", skill: "dependency-upgrade" },
   { trigger: "Agent-first observability — structured logs, persisted failure state, health surfaces, explicit failure modes", skill: "observability" },
+  { trigger: "React/Next.js performance — components, data fetching, bundle optimization, rendering patterns from Vercel Engineering", skill: "react-best-practices" },
+  { trigger: "Core Web Vitals — fix LCP, CLS, INP; layout shifts; page experience optimization", skill: "core-web-vitals" },
+  { trigger: "GitHub Actions CI/CD — write, run, and debug workflow files; live syntax and run monitoring", skill: "github-workflows" },
+  { trigger: "Comprehensive web quality audit — performance, accessibility, SEO, and best-practices (Lighthouse-style)", skill: "web-quality-audit" },
+  { trigger: "Browser automation — open sites, fill forms, click, screenshot, scrape, or test web apps programmatically", skill: "agent-browser" },
+  { trigger: "Review UI code for Web Interface Guidelines compliance — UX, design, and accessibility patterns", skill: "web-design-guidelines" },
+  { trigger: "UI/UX patterns reference — animations, CSS, typography, prefetching, icons (file:line findings)", skill: "userinterface-wiki" },
+  { trigger: "Author or refine a GSD skill — SKILL.md structure, frontmatter, and best practices", skill: "create-skill" },
+  { trigger: "Create or debug a GSD extension — tools, commands, event hooks, custom TUI, providers", skill: "create-gsd-extension" },
+  { trigger: "Author a YAML workflow definition — steps, triggers, and templates", skill: "create-workflow" },
+  { trigger: "Deep code optimization audit — perf anti-patterns, memory leaks, algorithmic complexity, bundle size, I/O, caching, dead code (parallel pattern-based hunt)", skill: "code-optimizer" },
 ];
 
 function buildBundledSkillsTable(): string {

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -4,6 +4,7 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
 
 import type { ToolsPolicy } from "../unit-context-manifest.js";
+import { logWarning } from "../workflow-logger.js";
 
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
@@ -546,6 +547,49 @@ export function shouldBlockQueueExecutionInSnapshot(
 const PLANNING_WRITE_TOOLS = new Set(["write", "edit", "multi_edit", "notebook_edit"]);
 const PLANNING_SUBAGENT_TOOLS = new Set(["subagent", "task"]);
 
+/**
+ * Canonical registry for agents that planning-dispatch may consider. Unit
+ * manifests still declare per-unit subsets via ToolsPolicy.allowedSubagents.
+ */
+const PLANNING_DISPATCH_AGENT_REGISTRY = {
+  scout: { readOnlySpecialist: true },
+  planner: { readOnlySpecialist: true },
+  reviewer: { readOnlySpecialist: true },
+  security: { readOnlySpecialist: true },
+  tester: { readOnlySpecialist: true },
+} as const satisfies Record<string, { readonly readOnlySpecialist: boolean }>;
+
+export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set<string>(
+  Object.entries(PLANNING_DISPATCH_AGENT_REGISTRY)
+    .filter(([, metadata]) => metadata.readOnlySpecialist)
+    .map(([agentId]) => agentId),
+);
+
+let warnedMissingPlanningDispatchAgentClasses = false;
+
+function isReadOnlySpecialist(agentId: string): boolean {
+  const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId as keyof typeof PLANNING_DISPATCH_AGENT_REGISTRY];
+  return metadata?.readOnlySpecialist === true;
+}
+
+function allowedPlanningDispatchAgentsList(): string {
+  return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
+}
+
+function warnMissingPlanningDispatchAgentClasses(unitType: string, mode: string, toolName: string): void {
+  if (warnedMissingPlanningDispatchAgentClasses) return;
+  warnedMissingPlanningDispatchAgentClasses = true;
+  // TODO(#5060): Remove this migration shim once all subagent/task callers are verified to forward agent identities.
+  const message = `[write-gate] planning-dispatch: shouldBlockPlanningUnit called for tool "${toolName}" ` +
+    `on unit "${unitType}" without agentClasses - stale caller; blocking dispatch.`;
+  console.warn(message);
+  logWarning("intercept", message, {
+    unitType,
+    mode,
+    toolName,
+  });
+}
+
 /**
  * Read-only / planning-safe tools that any non-"all" mode allows. Mirrors
  * QUEUE_SAFE_TOOLS / GATE_SAFE_TOOLS but is the inclusive default for
@@ -592,6 +636,10 @@ function blockReason(unitType: string, mode: string, what: string): string {
  *   - "read-only"  → blocks all writes, bash, and subagent dispatch.
  *   - "planning"   → blocks writes to paths outside <basePath>/.gsd/,
  *                    bash that isn't read-only, and subagent dispatch.
+ *   - "planning-dispatch"
+ *                  → like "planning", but permits subagent dispatch only
+ *                    when every forwarded agent class is globally allowed
+ *                    and listed in the policy's allowedSubagents.
  *   - "docs"       → like "planning" but also allows writes to paths
  *                    matching `allowedPathGlobs` relative to basePath.
  *
@@ -601,6 +649,11 @@ function blockReason(unitType: string, mode: string, what: string): string {
  * `policy` of null means "no manifest resolved" — pass-through. Callers
  * that have no active unit (interactive sessions) pass null and this
  * predicate is a no-op.
+ *
+ * `agentClasses` is supplied by the tool hook for subagent-shaped calls. If
+ * absent, planning-dispatch fails closed so stale callers cannot silently
+ * bypass the agent allowlists. An explicitly supplied-but-empty list is
+ * allowed through so the downstream tool call can reject the malformed input.
  */
 export function shouldBlockPlanningUnit(
   toolName: string,
@@ -608,6 +661,7 @@ export function shouldBlockPlanningUnit(
   basePath: string,
   unitType: string,
   policy: ToolsPolicy | null | undefined,
+  agentClasses?: readonly string[],
 ): { block: boolean; reason?: string } {
   if (!policy) return { block: false };
   if (policy.mode === "all") return { block: false };
@@ -625,11 +679,59 @@ export function shouldBlockPlanningUnit(
     return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
   }
 
-  // planning / docs modes share the same surface for safe tools, bash, and subagent.
+  // planning / planning-dispatch / docs modes share the same surface for safe tools, bash, and subagent.
   if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
   if (tool.startsWith("gsd_")) return { block: false };
 
   if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
+    if (policy.mode === "planning-dispatch") {
+      const requested = (agentClasses ?? []).map(a => a.trim()).filter(Boolean);
+      const allowedSubagents = Array.isArray(policy.allowedSubagents) ? policy.allowedSubagents : [];
+      const allowed = new Set(allowedSubagents);
+      // When agentClasses is undefined, the caller has not been updated to extract
+      // agent identities yet. Block and warn so stale callers surface in telemetry
+      // instead of silently bypassing the gate.
+      if (agentClasses === undefined) {
+        warnMissingPlanningDispatchAgentClasses(unitType, policy.mode, tool);
+        return {
+          block: true,
+          reason: blockReason(
+            unitType,
+            policy.mode,
+            `subagent dispatch blocked: stale caller did not supply agent identities for "${tool}"; update extractSubagentAgentClasses to handle this input shape`,
+          ),
+        };
+      }
+      // agentClasses was explicitly provided but resolved to an empty list (for
+      // example, a bare tool call with no agent field). Pass through; no agents
+      // to validate means the downstream tool call itself will fail.
+      if (requested.length === 0) {
+        return { block: false };
+      }
+      const globallyDisallowed = requested.find(a => !isReadOnlySpecialist(a));
+      if (globallyDisallowed) {
+        return {
+          block: true,
+          reason: blockReason(
+            unitType,
+            policy.mode,
+            `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from planning-dispatch units`,
+          ),
+        };
+      }
+      const disallowedByPolicy = requested.find(a => !allowed.has(a));
+      if (disallowedByPolicy) {
+        return {
+          block: true,
+          reason: blockReason(
+            unitType,
+            policy.mode,
+            `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`,
+          ),
+        };
+      }
+      return { block: false };
+    }
     return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
   }
 

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -14,7 +14,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -83,6 +83,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "add-tests", desc: "Generate tests for completed slices" },
   { cmd: "scan", desc: "Rapid codebase assessment — lightweight alternative to full map (--focus tech|arch|quality|concerns|tech+arch)" },
   { cmd: "language", desc: "Set or clear the global response language (e.g. /gsd language Chinese)" },
+  { cmd: "worktree", desc: "Manage worktrees from the TUI (list, merge, clean, remove)" },
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
@@ -299,6 +300,12 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "off",   desc: "Clear the language preference (revert to default)" },
     { cmd: "clear", desc: "Alias for off — clear the language preference" },
   ],
+  worktree: [
+    { cmd: "list",   desc: "Show all worktrees with status" },
+    { cmd: "merge",  desc: "Merge a worktree into main and clean up" },
+    { cmd: "clean",  desc: "Remove all merged/empty worktrees" },
+    { cmd: "remove", desc: "Remove a worktree (--force to skip safety checks)" },
+  ],
 };
 
 function filterOptions(

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

@@ -130,6 +130,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd forensics      Examine execution logs and post-mortem analysis",
     "  /gsd export         Export milestone/slice results  [--json|--markdown|--html] [--all]",
     "  /gsd cleanup        Remove merged branches or snapshots  [branches|snapshots]",
+    "  /gsd worktree       Manage worktrees from the TUI  [list|merge|clean|remove]",
     "  /gsd migrate        Migrate .planning/ (v1) to .gsd/ (v2) format",
     "  /gsd remote         Control remote auto-mode  [slack|discord|status|disconnect]",
     "  /gsd inspect        Show SQLite DB diagnostics (schema, row counts, recent entries)",

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

@@ -262,5 +262,15 @@ Examples:
     await handleScan(trimmed.replace(/^scan\s*/, "").trim(), ctx, pi);
     return true;
   }
+  if (
+    trimmed === "worktree" ||
+    trimmed.startsWith("worktree ") ||
+    trimmed === "wt" ||
+    trimmed.startsWith("wt ")
+  ) {
+    const { handleWorktree } = await import("../../commands-worktree.js");
+    await handleWorktree(trimmed.replace(/^(worktree|wt)\s*/, "").trim(), ctx);
+    return true;
+  }
   return false;
 }

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

@@ -8,6 +8,7 @@ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
+import { getHomeDir } from "./home-dir.js";
 
 /**
  * Tool API key configurations.
@@ -34,7 +35,7 @@ function getStoredToolKey(auth: AuthStorage, providerId: string): string | undef
  */
 export function loadToolApiKeys(): void {
   try {
-    const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+    const authPath = join(getHomeDir(), ".gsd", "agent", "auth.json");
     if (!existsSync(authPath)) return;
 
     const auth = AuthStorage.create(authPath);
@@ -50,7 +51,7 @@ export function loadToolApiKeys(): void {
 }
 
 export function getConfigAuthStorage(): AuthStorage {
-  const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+  const authPath = join(getHomeDir(), ".gsd", "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   return AuthStorage.create(authPath);
 }

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

@@ -12,7 +12,47 @@ import { dirname, join, resolve } from "node:path";
 import { homedir, tmpdir } from "node:os";
 import { execFileSync } from "node:child_process";
 import { lockSync, unlockSync } from "proper-lockfile";
-import semver from "semver";
+
+/**
+ * Strict numeric comparison of two npm-style version strings.
+ *
+ * Returns true when `a` is strictly greater than `b`. Compares the dotted
+ * release components numerically (so `1.10.0` > `1.9.0`) and treats any
+ * prerelease suffix (`-beta.1`, `-rc.2`) as less than the equivalent
+ * release version (`1.0.0` > `1.0.0-beta.1`). Sufficient for npm package
+ * version comparison in the extension installer; we don't need the full
+ * semver range/intersect machinery here.
+ *
+ * Replaces the earlier `import semver from "semver"` — that import broke
+ * `tsc -p tsconfig.json` whenever `@types/semver` failed to install
+ * (Issue #4946) because the file is pulled in transitively despite being
+ * under the `src/resources` exclude.
+ */
+export function isVersionGreater(a: string, b: string): boolean {
+  const split = (v: string): { release: number[]; pre: string | null } => {
+    const dash = v.indexOf("-");
+    const release = (dash === -1 ? v : v.slice(0, dash))
+      .split(".")
+      .map(part => Number.parseInt(part, 10) || 0);
+    const pre = dash === -1 ? null : v.slice(dash + 1);
+    return { release, pre };
+  };
+  const sa = split(a);
+  const sb = split(b);
+  const len = Math.max(sa.release.length, sb.release.length);
+  for (let i = 0; i < len; i++) {
+    const ai = sa.release[i] ?? 0;
+    const bi = sb.release[i] ?? 0;
+    if (ai !== bi) return ai > bi;
+  }
+  // Release components equal — a release version beats any prerelease,
+  // and prerelease strings are compared lexicographically (good enough
+  // for `beta.1` vs `beta.2`, the only realistic case here).
+  if (sa.pre === null && sb.pre !== null) return true;
+  if (sa.pre !== null && sb.pre === null) return false;
+  if (sa.pre !== null && sb.pre !== null) return sa.pre > sb.pre;
+  return false;
+}
 
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
@@ -538,7 +578,7 @@ async function updateSingleExtension(
     return;
   }
 
-  if (semver.gt(latest, current)) {
+  if (isVersionGreater(latest, current)) {
     ctx.ui.notify(`Updating "${id}": v${current} → v${latest}...`, "info");
     await handleInstall(packageName, ctx);
   } else {
@@ -599,7 +639,7 @@ async function updateAllExtensions(
       continue;
     }
 
-    if (semver.gt(latest, current)) {
+    if (isVersionGreater(latest, current)) {
       ctx.ui.notify(`  ${entry.id}: v${current} → v${latest} (updating)`, "info");
       await handleInstall(packageName, ctx);
       updated++;

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

@@ -11,6 +11,7 @@ import { join, resolve as resolvePath, sep } from "node:path";
 import { homedir } from "node:os";
 import { deriveState } from "./state.js";
 import { gsdRoot } from "./paths.js";
+import { getHomeDir } from "./home-dir.js";
 import { appendCapture, hasPendingCaptures, loadPendingCaptures } from "./captures.js";
 import { appendOverride, appendKnowledge } from "./files.js";
 import {
@@ -68,7 +69,7 @@ async function fetchLatestVersionForCommand(): Promise<string | null> {
 }
 
 export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
   const prompt = loadPrompt("doctor-heal", {
     doctorSummary: reportText,
@@ -255,7 +256,7 @@ export async function handleTriage(ctx: ExtensionCommandContext, pi: ExtensionAP
     roadmapContext: roadmapContext || "(no active roadmap)",
   });
 
-  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
+  const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
 
   pi.sendMessage(