gsd-pi 2.78.1-dev.84a383f51 → 2.78.1-dev.9d08d820b

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;
       }

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/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-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(

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -165,6 +165,12 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `skip_reassess`: boolean — force-disable roadmap reassessment even if `reassess_after_slice` is enabled. Default: `false`.
   - `skip_slice_research`: boolean — skip per-slice research. Default: `false`.
 
+- `reactive_execution`: controls automatic parallel task dispatch inside a slice. Reactive execution is enabled by default when omitted; set `enabled: false` to opt out. With default-on behavior, GSD only attempts a reactive batch when at least three ready tasks are available and the task-plan IO graph is non-ambiguous. If you set `enabled: true` explicitly, GSD uses the earlier opt-in threshold of two ready tasks. Keys:
+  - `enabled`: boolean — set `false` to force sequential task execution. Default: `true`.
+  - `max_parallel`: number — maximum tasks to dispatch in one batch, range `1`-`8`. Default: `2`.
+  - `isolation_mode`: `"same-tree"` — currently the only supported value.
+  - `subagent_model`: string — optional model override for reactive task subagents. Falls back to the `models.subagent` routing when omitted.
+
 - `remote_questions`: route interactive questions to Slack/Discord for headless auto-mode. Keys:
   - `channel`: `"slack"` or `"discord"` — channel type.
   - `channel_id`: string or number — channel ID.

package/src/resources/extensions/gsd/doctor-providers.ts

@@ -17,6 +17,7 @@ import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY, type ProviderCategory } from "./key-manager.js";
+import { getHomeDir } from "./home-dir.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
@@ -194,7 +195,7 @@ function isCliBinaryInPath(providerId: string): boolean {
 }
 
 function modelsJsonPaths(): string[] {
-  const home = process.env.HOME ?? "~";
+  const home = getHomeDir();
   return [
     join(home, ".gsd", "agent", "models.json"),
     // Keep parity with custom-provider discovery during auto bootstrap.

package/src/resources/extensions/gsd/forensics.ts

@@ -12,7 +12,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
+import { getHomeDir } from "./home-dir.js";
 
 import { extractTrace, type ExecutionTrace } from "./session-forensics.js";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
@@ -244,7 +244,7 @@ export async function handleForensics(
   // when import.meta.url resolves to the npm-global install path (Windows).
   let gsdSourceDir = dirname(fileURLToPath(import.meta.url));
   if (!existsSync(join(gsdSourceDir, "prompts"))) {
-    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+    const gsdHome = process.env.GSD_HOME || join(getHomeDir(), ".gsd");
     const fallback = join(gsdHome, "agent", "extensions", "gsd");
     if (existsSync(join(fallback, "prompts"))) gsdSourceDir = fallback;
   }
@@ -1299,10 +1299,15 @@ function formatReportForPrompt(report: ForensicReport): string {
 function redactForGitHub(text: string, basePath: string): string {
   let result = text;
 
+  // Build regex that matches both / and \ separator variants (Windows)
+  // Normalize to / first, escape for regex, then replace each / with [/\\]
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pathRe = (p: string) =>
+    new RegExp(esc(p.replace(/\\/g, "/")).replace(/\//g, "[/\\\\]"), "gi");
+
   // Replace absolute paths
-  result = result.replaceAll(basePath, ".");
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  if (home) result = result.replaceAll(home, "~");
+  result = result.replace(pathRe(basePath), ".");
+  result = result.replace(pathRe(getHomeDir()), "~");
 
   // Strip API key patterns
   result = result.replace(/sk-[a-zA-Z0-9]{20,}/g, "sk-***");

package/src/resources/extensions/gsd/guided-flow.ts

@@ -25,6 +25,7 @@ import {
 } from "./interrupted-session.js";
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
+import { getHomeDir } from "./home-dir.js";
 import {
   gsdRoot, milestonesDir, resolveMilestoneFile, resolveMilestonePath,
   resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile,
@@ -607,7 +608,7 @@ async function dispatchWorkflow(
     });
   }
 
-  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(

package/src/resources/extensions/gsd/home-dir.ts

@@ -0,0 +1,19 @@
+/**
+ * Cross-platform home directory resolution.
+ *
+ * `process.env.HOME` is not set on Windows (CMD/PowerShell).
+ * Falls back to USERPROFILE, then os.homedir(), then throws.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/5015
+ */
+import { homedir } from "node:os";
+
+export function getHomeDir(): string {
+  const home = process.env.HOME || process.env.USERPROFILE || homedir();
+  if (!home) {
+    throw new Error(
+      "Cannot resolve home directory. Set HOME or USERPROFILE environment variable.",
+    );
+  }
+  return home;
+}

package/src/resources/extensions/gsd/journal.ts

@@ -60,7 +60,10 @@ export type JournalEventType =
   | "canonical-root-redirect"
   // #4765 — slice-cadence collapse
   | "slice-merged"
-  | "milestone-resquash";
+  | "milestone-resquash"
+  // dispatch telemetry — measure agent/subagent invocation frequency and shape
+  | "subagent-invoked"
+  | "subagent-completed";
 
 /** A single structured event in the journal. */
 export interface JournalEntry {

package/src/resources/extensions/gsd/key-manager.ts

@@ -17,6 +17,7 @@ import { existsSync, statSync, chmodSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { mkdirSync } from "node:fs";
 import { getErrorMessage } from "./error-utils.js";
+import { getHomeDir } from "./home-dir.js";
 
 // ─── Provider Registry ─────────────────────────────────────────────────────────
 
@@ -122,7 +123,7 @@ export function describeCredential(cred: AuthCredential): string {
  * Get the auth.json path.
  */
 export function getAuthPath(): string {
-  return join(process.env.HOME ?? "~", ".gsd", "agent", "auth.json");
+  return join(getHomeDir(), ".gsd", "agent", "auth.json");
 }
 
 /**

package/src/resources/extensions/gsd/migrate/command.ts

@@ -15,6 +15,7 @@ import { resolve, join, dirname } from "node:path";
 import { gsdRoot } from "../paths.js";
 import { fileURLToPath } from "node:url";
 import { showNextAction } from "../../shared/tui.js";
+import { getHomeDir } from "../home-dir.js";
 import {
   validatePlanningDirectory,
   parsePlanningDirectory,
@@ -85,9 +86,9 @@ export async function handleMigrate(
   // Default to cwd when no args given; expand ~ to HOME
   let rawPath = args.trim() || ".";
   if (rawPath.startsWith("~/")) {
-    rawPath = join(process.env.HOME ?? "~", rawPath.slice(2));
+    rawPath = join(getHomeDir(), rawPath.slice(2));
   } else if (rawPath === "~") {
-    rawPath = process.env.HOME ?? "~";
+    rawPath = getHomeDir();
   }
 
   let sourcePath = resolve(process.cwd(), rawPath);

package/src/resources/extensions/gsd/prompts/complete-milestone.md

@@ -16,6 +16,16 @@ Start with what the excerpts give you. Read full files when the section heads si
 
 **On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. For non-trivial milestones, delegate before drafting LEARNINGS:
+
+- **Cross-slice integrations or new public APIs** → dispatch the **reviewer** agent with the milestone diff and roadmap; treat its findings as input to your Decision Re-evaluation and LEARNINGS sections.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit across the merged slices.
+- **Significant test surface added or changed** → dispatch the **tester** agent to assess coverage gaps relative to the milestone success criteria.
+
+Subagents read the diff and report findings — they do **not** write user source. Apply their feedback into the milestone summary and any captured decisions before calling `gsd_complete_milestone`.
+
 {{inlinedContext}}
 
 Then:

package/src/resources/extensions/gsd/prompts/complete-slice.md

@@ -20,6 +20,16 @@ All relevant context has been preloaded below — the slice plan, all task summa
 
 **Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
 
+### Delegate Review Work
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate review work that benefits from a fresh context window. Strongly consider delegating when the slice is non-trivial:
+
+- **Cross-cutting code or new abstractions** → dispatch the **reviewer** agent with the slice diff and plan; apply High/Critical findings before completing.
+- **Touched auth, network, parsing, file IO, shell exec, or crypto** → dispatch the **security** agent for an OWASP-style audit.
+- **Added or modified tests** → dispatch the **tester** agent to assess coverage gaps relative to the slice plan.
+
+Subagents read the diff and report findings — they do **not** write user source. You remain responsible for acting on their feedback before calling `gsd_complete_slice` with `milestoneId` and `sliceId`.
+
 Then:
 1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
 2. {{skillActivation}}

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -20,6 +20,16 @@ Pay particular attention to **Forward Intelligence** sections — they contain h
 
 You have full tool access. Before decomposing, explore the relevant code to ground your plan in reality.
 
+### Delegate Recon and Sub-Decomposition When Useful
+
+This unit runs under the `planning-dispatch` tools-policy: you may use the `subagent` tool to delegate work that benefits from an isolated context window. Prefer delegation over inline work when:
+
+- You'd otherwise read more than ~3 files to understand a subsystem → dispatch the **scout** agent for codebase recon and work from its compressed report.
+- The slice spans multiple subsystems and the decomposition isn't obvious → dispatch the **planner** agent or use the **decompose-into-slices** skill on a focused sub-area, then integrate.
+- You need current external information (library docs, API behavior, recent changes) → dispatch the **researcher** agent.
+
+**Do not** dispatch implementation-tier agents (`worker`, `refactorer`, `tester`) from this unit — they would write user source and bypass this unit's write isolation. Implementation belongs in `execute-task`.
+
 ### Verify Roadmap Assumptions (JIT Reassessment — ADR-003 §4)
 
 Before planning this slice, verify that the roadmap's assumptions still hold given prior slice summaries. Check inlined dependency summaries (below) for discovered constraints, changed approaches, or flagged fragility.