@opengsd/gsd-pi 1.2.0-dev.0b870afa → 1.2.0-dev.23d85b63

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

@@ -218,52 +218,54 @@ export function createWorktreeSafetyModule(
       }
 
       let registered: readonly RegisteredWorktree[] | undefined;
-      try {
-        registered = deps.listRegisteredWorktrees?.(projectRoot);
-      } catch (error) {
-        return failure(
-          "worktree-git-probe-failed",
-          `Unable to list registered worktrees for project root ${projectRoot}.`,
-          "Recover or recreate the milestone worktree before dispatching the source-writing Unit.",
-          { projectRoot, error: errorMessage(error) },
-        );
-      }
-      if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
-        const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
-        let attemptedPrune = false;
+      if (isolationMode === "worktree") {
+        try {
+          registered = deps.listRegisteredWorktrees?.(projectRoot);
+        } catch (error) {
+          return failure(
+            "worktree-git-probe-failed",
+            `Unable to list registered worktrees for project root ${projectRoot}.`,
+            "Recover or recreate the milestone worktree before dispatching the source-writing Unit.",
+            { projectRoot, error: errorMessage(error) },
+          );
+        }
+        if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
+          const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
+          let attemptedPrune = false;
 
-        if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
-          attemptedPrune = true;
-          try {
-            deps.pruneRegisteredWorktrees(projectRoot);
-            const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
-            if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
-              unregisteredRecoveryFailed.delete(unitRoot);
-              registered = rechecked;
-            } else {
+          if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
+            attemptedPrune = true;
+            try {
+              deps.pruneRegisteredWorktrees(projectRoot);
+              const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
+              if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
+                unregisteredRecoveryFailed.delete(unitRoot);
+                registered = rechecked;
+              } else {
+                unregisteredRecoveryFailed.add(unitRoot);
+              }
+            } catch (error) {
               unregisteredRecoveryFailed.add(unitRoot);
+              return failure(
+                "worktree-git-probe-failed",
+                `Unable to recover unregistered worktree root ${unitRoot}.`,
+                "Run 'git worktree prune', then recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
+                { projectRoot, unitRoot, error: errorMessage(error) },
+              );
             }
-          } catch (error) {
-            unregisteredRecoveryFailed.add(unitRoot);
+          }
+
+          if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
             return failure(
-              "worktree-git-probe-failed",
-              `Unable to recover unregistered worktree root ${unitRoot}.`,
-              "Run 'git worktree prune', then recreate the milestone worktree before dispatching the source-writing Unit.",
-              { projectRoot, unitRoot, error: errorMessage(error) },
+              "worktree-unregistered",
+              `Worktree root ${unitRoot} is not registered with git worktree list.`,
+              attemptedPrune || wasPreviouslyTracked
+                ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
+                : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
+              { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) },
             );
           }
         }
-
-        if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
-          return failure(
-            "worktree-unregistered",
-            `Worktree root ${unitRoot} is not registered with git worktree list.`,
-            attemptedPrune || wasPreviouslyTracked
-              ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
-              : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
-            { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) },
-          );
-        }
       }
 
       if (input.emptyWorktreeWithProjectContent) {

package/src/resources/extensions/gsd/worktree-shell-guard.ts

@@ -0,0 +1,123 @@
+// Project/App: gsd-pi
+// File Purpose: Detect shell commands that reference the project root from a milestone worktree.
+
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+import { projectRootFromWorktreePath } from "./worktree-root.js";
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function normalizeScanPath(value: string): string {
+  const normalized = value.replace(/\\/g, "/").replace(/\/+$/, "");
+  return normalized.startsWith("/private/var/")
+    ? normalized.slice("/private".length)
+    : normalized;
+}
+
+function parseWorktreeBase(baseDir: string): { originalRoot: string; worktreeRoot: string } | null {
+  const normalizedBase = normalizeScanPath(baseDir);
+  const originalRoot = projectRootFromWorktreePath(normalizedBase);
+  if (!originalRoot) return null;
+  return { originalRoot, worktreeRoot: normalizedBase };
+}
+
+function pathInside(parent: string, target: string): boolean {
+  const parentWithSep = parent.endsWith("/") ? parent : `${parent}/`;
+  return target === parent || target.startsWith(parentWithSep);
+}
+
+function comparablePathVariants(value: string): string[] {
+  const variants = new Set<string>();
+  const normalized = normalizeScanPath(path.resolve(value));
+  variants.add(normalized);
+  try {
+    variants.add(normalizeScanPath(realpathSync(normalized)));
+  } catch {
+    // Nonexistent paths are still compared lexically.
+  }
+  if (normalized.startsWith("/private/var/")) {
+    variants.add(normalized.replace(/^\/private\/var\//, "/var/"));
+  } else if (normalized.startsWith("/var/")) {
+    variants.add(`/private${normalized}`);
+  }
+  return [...variants];
+}
+
+function pathInsideAny(parents: readonly string[], targets: readonly string[]): boolean {
+  return targets.some((target) => parents.some((parent) => pathInside(parent, target)));
+}
+
+function stripWrappingQuotes(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length < 2) return trimmed;
+  const first = trimmed[0];
+  const last = trimmed[trimmed.length - 1];
+  if ((first === "'" || first === '"' || first === "`") && last === first) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+function extractPathLikeValues(script: string): string[] {
+  const values: string[] = [];
+  const push = (candidate: string) => {
+    const cleaned = stripWrappingQuotes(candidate).trim();
+    if (!cleaned) return;
+    values.push(cleaned);
+  };
+  const pushQuotedLiterals = (source: string, depth = 0) => {
+    for (const match of source.matchAll(/(["'`])((?:\\.|(?!\1).)*)\1/g)) {
+      push(match[2]);
+      if (depth < 2 && /["'`]/.test(match[2])) {
+        pushQuotedLiterals(match[2], depth + 1);
+      }
+    }
+  };
+
+  for (const match of script.matchAll(/(?:^|[;\n\r]|\&\&|\|\|)\s*cd\s+([^\n\r;|&]+)/g)) {
+    push(match[1]);
+  }
+  for (const match of script.matchAll(/process\.chdir\(\s*([^\n\r;]+?)\s*\)/g)) {
+    push(match[1]);
+    pushQuotedLiterals(match[1]);
+  }
+  pushQuotedLiterals(script);
+  return values;
+}
+
+export function resolvesToOriginalRootOutsideWorktree(script: string, baseDir: string): boolean {
+  const parsed = parseWorktreeBase(baseDir);
+  if (!parsed) return false;
+
+  const normalizedWorktree = normalizeScanPath(path.resolve(parsed.worktreeRoot));
+  const normalizedOriginalRoot = normalizeScanPath(path.resolve(parsed.originalRoot));
+  const worktreeRoots = comparablePathVariants(normalizedWorktree);
+  const originalRoots = comparablePathVariants(normalizedOriginalRoot);
+  for (const value of extractPathLikeValues(script)) {
+    const resolved = comparablePathVariants(path.resolve(normalizedWorktree, value));
+    if (pathInsideAny(originalRoots, resolved) && !pathInsideAny(worktreeRoots, resolved)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+export function scriptReferencesOriginalRootFromWorktree(script: string, baseDir: string): boolean {
+  const parsed = parseWorktreeBase(baseDir);
+  if (!parsed) return false;
+  const normalizedScript = script.replace(/\\/g, "/");
+  return comparablePathVariants(parsed.originalRoot).some((originalRoot) => {
+    const originalRootPattern = new RegExp(
+      `${escapeRegExp(originalRoot)}(?=$|[\\s'"\\\`;)&|<>]|/(?!\\.gsd(?:-worktrees|/worktrees)(?:/|$)))`,
+    );
+    return originalRootPattern.test(normalizedScript);
+  });
+}
+
+export function bashReferencesProjectRootOutsideWorktree(script: string, baseDir: string): boolean {
+  return resolvesToOriginalRootOutsideWorktree(script, baseDir)
+    || scriptReferencesOriginalRootFromWorktree(script, baseDir);
+}

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

@@ -224,7 +224,13 @@ export function resolveGitHeadPath(dir: string): string | null {
  */
 export function nudgeGitBranchCache(previousCwd: string): void {
   const now = new Date();
-  for (const dir of [previousCwd, process.cwd()]) {
+  let currentCwd: string | null = null;
+  try {
+    currentCwd = process.cwd();
+  } catch {
+    currentCwd = null;
+  }
+  for (const dir of [previousCwd, currentCwd].filter((dir): dir is string => Boolean(dir))) {
     try {
       const headPath = resolveGitHeadPath(dir);
       if (headPath) utimesSync(headPath, now, now);

package/src/resources/extensions/mcp-client/manager.ts

@@ -105,6 +105,9 @@ const CHILD_ENV_ALLOWLIST = new Set([
 
 const MCP_STDERR_MAX_BYTES = 4096;
 
+/** Short-lived stdio probes must not register/kill production MCP PIDs (see probe-mode.ts). */
+export const GSD_MCP_PROBE_ENV = "GSD_MCP_PROBE";
+
 let cachedStatus: ManagedMcpStatus | null = null;
 let cachedStatusKey = "";
 
@@ -385,7 +388,10 @@ export async function testMcpServerConnection(
 			transport = new StdioClientTransport({
 				command: config.command ?? "",
 				args: config.args,
-				env: buildMcpChildEnv(config.env),
+				env: {
+					...buildMcpChildEnv(config.env),
+					[GSD_MCP_PROBE_ENV]: "1",
+				},
 				cwd: config.cwd,
 				stderr: "pipe",
 			});

package/src/resources/extensions/search-the-web/index.ts

@@ -3,38 +3,74 @@
  *
  * Native Anthropic hooks stay eager. Heavy tool registration is deferred in
  * interactive mode so startup is not blocked on the full search tool stack.
+ *
+ * Provider gating: the Brave/Tavily/Ollama-backed tools (search-the-web,
+ * search_and_read) are only registered when a provider API key is actually
+ * configured (resolveSearchProvider() !== null). Without a key these tools can
+ * only return an auth error, so presenting them to the model is pure confusion
+ * — the agent reaches for a tool that cannot work. fetch_page is always
+ * registered because it works key-free via Jina Reader.
  */
 
 import { importExtensionModule, type ExtensionAPI } from "@gsd/pi-coding-agent";
 import { registerSearchProviderCommand } from "./command-search-provider.js";
 import { registerNativeSearchHooks } from "./native-search.js";
+import { resolveSearchProvider } from "./provider.js";
 
-let toolsPromise: Promise<void> | null = null;
+// fetch_page registration — always available (key-free via Jina Reader).
+let fetchToolPromise: Promise<void> | null = null;
+// search-the-web + search_and_read registration — gated on provider key.
+let searchToolsPromise: Promise<void> | null = null;
 let resetSearchLoopGuardStateRef: (() => void) | null = null;
 
-async function registerSearchTools(pi: ExtensionAPI): Promise<void> {
-  if (!toolsPromise) {
-    toolsPromise = (async () => {
+async function registerFetchTool(pi: ExtensionAPI): Promise<void> {
+  if (!fetchToolPromise) {
+    fetchToolPromise = (async () => {
+      const { registerFetchPageTool } = await importExtensionModule<typeof import("./tool-fetch-page.js")>(
+        import.meta.url,
+        "./tool-fetch-page.js",
+      );
+      registerFetchPageTool(pi);
+    })().catch((error) => {
+      fetchToolPromise = null;
+      throw error;
+    });
+  }
+
+  return fetchToolPromise;
+}
+
+/**
+ * Register the provider-backed search tools, but only when a search provider
+ * key is configured. Memoized so it registers at most once per process; the
+ * guard is re-evaluated on each session_start so a key added before a later
+ * session is picked up without a restart.
+ */
+async function registerProviderSearchTools(pi: ExtensionAPI): Promise<void> {
+  if (resolveSearchProvider() === null) return;
+  if (!searchToolsPromise) {
+    searchToolsPromise = (async () => {
       const [
         { registerSearchTool, resetSearchLoopGuardState },
-        { registerFetchPageTool },
         { registerLLMContextTool },
       ] = await Promise.all([
         importExtensionModule<typeof import("./tool-search.js")>(import.meta.url, "./tool-search.js"),
-        importExtensionModule<typeof import("./tool-fetch-page.js")>(import.meta.url, "./tool-fetch-page.js"),
         importExtensionModule<typeof import("./tool-llm-context.js")>(import.meta.url, "./tool-llm-context.js"),
       ]);
       resetSearchLoopGuardStateRef = resetSearchLoopGuardState;
       registerSearchTool(pi);
-      registerFetchPageTool(pi);
       registerLLMContextTool(pi);
     })().catch((error) => {
-      toolsPromise = null;
+      searchToolsPromise = null;
       throw error;
     });
   }
 
-  return toolsPromise;
+  return searchToolsPromise;
+}
+
+async function registerSearchTools(pi: ExtensionAPI): Promise<void> {
+  await Promise.all([registerFetchTool(pi), registerProviderSearchTools(pi)]);
 }
 
 export default function (pi: ExtensionAPI) {

package/src/resources/extensions/search-the-web/native-search.ts

@@ -7,6 +7,7 @@
 
 import { isAnthropicApi } from "@gsd/pi-ai";
 import { resolveSearchProviderFromPreferences } from "../gsd/preferences.js";
+import { resolveSearchProvider } from "./provider.js";
 
 /** Tool names for the Brave-backed custom search tools */
 export const BRAVE_TOOL_NAMES = ["search-the-web", "search_and_read"];
@@ -194,11 +195,22 @@ export function registerNativeSearchHooks(pi: NativeSearchPI): { getIsAnthropic:
         active.filter((t: string) => !CUSTOM_SEARCH_TOOL_NAMES.includes(t))
       );
     } else if (!isAnthropicProvider && wasAnthropic) {
-      // Switching away from Anthropic — re-enable custom search tools (they
-      // were disabled while native search was active). If keys are missing,
-      // user sees the error rather than tools silently vanishing.
+      // Switching away from Anthropic — re-enable custom search tools that were
+      // disabled while native search was active. Only re-add the Brave/Tavily/
+      // Ollama-backed tools when a provider key is actually configured: without
+      // a key they can only return an auth error, and re-adding their names
+      // would advertise a tool the model cannot use (and, when unregistered,
+      // leak a schema-less phantom name into the tool surface). google_search
+      // is owned by its own extension (which now gates its registration on
+      // Gemini creds); re-adding its name here is harmless either way — it
+      // activates if registered, or is dropped as a no-op if not.
       const active = pi.getActiveTools();
-      const toAdd = CUSTOM_SEARCH_TOOL_NAMES.filter((t) => !active.includes(t));
+      const providerConfigured = resolveSearchProvider() !== null;
+      const toAdd = CUSTOM_SEARCH_TOOL_NAMES.filter((t) => {
+        if (active.includes(t)) return false;
+        if (BRAVE_TOOL_NAMES.includes(t)) return providerConfigured;
+        return true;
+      });
       if (toAdd.length > 0) {
         pi.setActiveTools([...active, ...toAdd]);
       }

package/src/resources/extensions/shared/gsd-browser-cli.ts

@@ -117,15 +117,48 @@ function resolvePathGsdBrowserVersion(env: NodeJS.ProcessEnv): string | null {
   return cachedPathProbeVersion;
 }
 
+function resolveGsdBrowserNativeBinaryPath(launcherPath: string, platform: NodeJS.Platform = process.platform): string {
+  const binDir = resolve(launcherPath, "..");
+  const nativeName = platform === "win32" ? "gsd-browser.exe" : "gsd-browser-bin";
+  return resolve(binDir, nativeName);
+}
+
+function isNodeShLauncher(launcherPath: string): boolean {
+  try {
+    return readFileSync(launcherPath, "utf-8").startsWith("#!");
+  } catch {
+    // Non-text launchers (native binaries) are runnable without a sibling shim.
+    return false;
+  }
+}
+
+/**
+ * The npm package ships a node launcher that execs `gsd-browser-bin` beside it.
+ * pnpm can skip postinstall, leaving only the launcher — which exits immediately
+ * and surfaces as MCP "Connection closed". Treat that layout as unavailable.
+ */
+function isGsdBrowserPackageLauncherRunnable(launcherPath: string): boolean {
+  if (!existsSync(launcherPath)) return false;
+  const nativePath = resolveGsdBrowserNativeBinaryPath(launcherPath);
+  if (existsSync(nativePath)) return true;
+  return !isNodeShLauncher(launcherPath);
+}
+
 function shouldPreferPathGsdBrowser(env: NodeJS.ProcessEnv): boolean {
   const pathVersion = resolvePathGsdBrowserVersion(env);
   if (!pathVersion) return false;
 
   const bundledVersion = resolveBundledGsdBrowserPackageVersion();
-  return !bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0;
+  if (!bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0) {
+    return true;
+  }
+
+  // Same or newer bundled semver still loses when the package launcher cannot run.
+  const bundledLauncher = resolveBundledGsdBrowserLauncherPath(env);
+  return bundledLauncher !== null && !isGsdBrowserPackageLauncherRunnable(bundledLauncher);
 }
 
-export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
+function resolveBundledGsdBrowserLauncherPath(env: NodeJS.ProcessEnv = process.env): string | null {
   const explicit = resolveExplicitGsdBrowserCliPath(env);
   if (explicit) return explicit;
 
@@ -150,6 +183,12 @@ export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process
   return null;
 }
 
+export function resolveBundledGsdBrowserCliPath(env: NodeJS.ProcessEnv = process.env): string | null {
+  const launcher = resolveBundledGsdBrowserLauncherPath(env);
+  if (!launcher || !isGsdBrowserPackageLauncherRunnable(launcher)) return null;
+  return launcher;
+}
+
 export type GsdBrowserCliAvailability =
   | { available: true; via: "explicit-env" | "bundled" | "path"; detail: string }
   | { available: false; detail: string };

package/src/resources/extensions/subagent/index.ts

@@ -45,6 +45,7 @@ import {
 	type SubagentContextMode,
 	type SubagentSessionArgs,
 } from "./launch.js";
+import { resolveSubagentWorktreeCwd } from "./worktree-cwd.js";
 import {
 	SubagentRunStore,
 	createInitialRunRecord,
@@ -1003,16 +1004,19 @@ export default function (pi: ExtensionAPI) {
 					: hasTasks && taskParams.some((task) => (task.context ?? contextMode) === "fork")
 						? "fork"
 						: contextMode;
-			const dispatchChildren = dispatchAgents.map((agent, index) => ({
-				agent,
-				trackingName: dispatchTrackingNames[index],
-				task: dispatchTasks[index] ?? "",
-				cwd: hasChain
+			const dispatchChildren = dispatchAgents.map((agent, index) => {
+				const rawCwd = hasChain
 					? chainParams[index]?.cwd
 					: hasTasks
 						? taskParams[index]?.cwd
-						: params.cwd,
-			}));
+						: params.cwd;
+				return {
+					agent,
+					trackingName: dispatchTrackingNames[index],
+					task: dispatchTasks[index] ?? "",
+					cwd: resolveSubagentWorktreeCwd(ctx.cwd, rawCwd),
+				};
+			});
 			try {
 				runStore.create(createInitialRunRecord({
 					runId: dispatchId,
@@ -1240,7 +1244,7 @@ export default function (pi: ExtensionAPI) {
 				void (async () => {
 					let isolation: IsolationEnvironment | null = null;
 					try {
-						const effectiveCwd = params.cwd ?? ctx.cwd;
+						const effectiveCwd = resolveSubagentWorktreeCwd(ctx.cwd, params.cwd);
 						if (useIsolation) {
 							const taskId = crypto.randomUUID();
 							isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
@@ -1250,7 +1254,7 @@ export default function (pi: ExtensionAPI) {
 							agents,
 							params.agent!,
 							params.task!,
-							isolation ? isolation.workDir : params.cwd,
+							isolation ? isolation.workDir : effectiveCwd,
 							undefined,
 							undefined,
 							(partial) => {
@@ -1321,12 +1325,13 @@ export default function (pi: ExtensionAPI) {
 						}
 					};
 
+					const stepCwd = resolveSubagentWorktreeCwd(ctx.cwd, step.cwd);
 					const result = await runSingleAgent(
 						ctx.cwd,
 						agents,
 						step.agent,
 						taskWithContext,
-						step.cwd,
+						stepCwd,
 						i + 1,
 						signal,
 						chainUpdate,
@@ -1464,14 +1469,14 @@ export default function (pi: ExtensionAPI) {
 							);
 					const runTask = async () => {
 						let isolation: IsolationEnvironment | null = null;
-						const effectiveCwd = t.cwd ?? ctx.cwd;
+						const effectiveCwd = resolveSubagentWorktreeCwd(ctx.cwd, t.cwd);
 						try {
 							if (useIsolation) {
 								const taskId = crypto.randomUUID();
 								isolation = await createIsolation(effectiveCwd, taskId, isolationMode);
 							}
 
-							const result = await executeOnce(isolation ? isolation.workDir : t.cwd);
+							const result = await executeOnce(isolation ? isolation.workDir : effectiveCwd);
 							if (isolation && result.exitCode === 0) {
 								const patches = await isolation.captureDelta();
 								const mergeResult = patches.length > 0
@@ -1530,7 +1535,7 @@ export default function (pi: ExtensionAPI) {
 				let isolation: IsolationEnvironment | null = null;
 				let mergeResult: MergeResult | undefined;
 				try {
-					const effectiveCwd = params.cwd ?? ctx.cwd;
+					const effectiveCwd = resolveSubagentWorktreeCwd(ctx.cwd, params.cwd);
 
 					if (useIsolation) {
 						const taskId = crypto.randomUUID();
@@ -1549,7 +1554,7 @@ export default function (pi: ExtensionAPI) {
 							agents,
 							params.agent,
 							params.task,
-							isolation ? isolation.workDir : params.cwd,
+							isolation ? isolation.workDir : effectiveCwd,
 							undefined,
 							signal,
 							singleUpdate,
@@ -1566,7 +1571,7 @@ export default function (pi: ExtensionAPI) {
 							agents,
 							params.agent,
 							params.task,
-							isolation ? isolation.workDir : params.cwd,
+							isolation ? isolation.workDir : effectiveCwd,
 							undefined,
 							signal,
 							singleUpdate,

package/src/resources/extensions/subagent/tests/worktree-cwd.test.ts

@@ -0,0 +1,57 @@
+// Project/App: gsd-pi
+// File Purpose: Regression tests for subagent cwd pinning inside milestone worktrees.
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { resolveSubagentWorktreeCwd } from "../worktree-cwd.js";
+
+test("resolveSubagentWorktreeCwd defaults to parent when task cwd is omitted in worktree", () => {
+	const root = mkdtempSync(join(tmpdir(), "subagent-cwd-"));
+	const worktree = join(root, ".gsd-worktrees", "M007");
+	try {
+		mkdirSync(worktree, { recursive: true });
+		assert.equal(resolveSubagentWorktreeCwd(worktree), worktree);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("resolveSubagentWorktreeCwd pins project-root cwd to parent worktree", () => {
+	const root = mkdtempSync(join(tmpdir(), "subagent-cwd-"));
+	const worktree = join(root, ".gsd-worktrees", "M007");
+	try {
+		mkdirSync(worktree, { recursive: true });
+		assert.equal(resolveSubagentWorktreeCwd(worktree, root), worktree);
+		assert.equal(resolveSubagentWorktreeCwd(worktree, join(root, "app.js")), worktree);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("resolveSubagentWorktreeCwd allows relative paths inside the worktree", () => {
+	const root = mkdtempSync(join(tmpdir(), "subagent-cwd-"));
+	const worktree = join(root, ".gsd-worktrees", "M007");
+	const nested = join(worktree, "src");
+	try {
+		mkdirSync(nested, { recursive: true });
+		assert.equal(resolveSubagentWorktreeCwd(worktree, "src"), nested);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});
+
+test("resolveSubagentWorktreeCwd leaves non-worktree parents unchanged", () => {
+	const root = mkdtempSync(join(tmpdir(), "subagent-cwd-"));
+	const nested = join(root, "packages", "app");
+	try {
+		mkdirSync(nested, { recursive: true });
+		assert.equal(resolveSubagentWorktreeCwd(root), root);
+		assert.equal(resolveSubagentWorktreeCwd(root, "packages/app"), nested);
+	} finally {
+		rmSync(root, { recursive: true, force: true });
+	}
+});

package/src/resources/extensions/subagent/worktree-cwd.ts

@@ -0,0 +1,35 @@
+// Project/App: gsd-pi
+// File Purpose: Pin subagent cwd to the parent milestone worktree so parallel
+// reactive-execute children cannot spawn at the project root.
+
+import path from "node:path";
+
+import { isGsdWorktreePath } from "../gsd/worktree-root.js";
+
+function pathInside(parent: string, target: string): boolean {
+	const parentWithSep = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`;
+	return target === parent || target.startsWith(parentWithSep);
+}
+
+/**
+ * Resolve the cwd for a subagent child. When the parent is already inside a GSD
+ * milestone worktree, children must stay in that worktree — even if the model
+ * omits `cwd` or passes the project root (the root-write leak vector for
+ * reactive-execute).
+ */
+export function resolveSubagentWorktreeCwd(parentCwd: string, taskCwd?: string): string {
+	const resolvedParent = path.resolve(parentCwd);
+	if (!isGsdWorktreePath(resolvedParent)) {
+		return taskCwd ? path.resolve(resolvedParent, taskCwd) : resolvedParent;
+	}
+	if (!taskCwd) {
+		return resolvedParent;
+	}
+	const resolvedTask = path.isAbsolute(taskCwd)
+		? path.resolve(taskCwd)
+		: path.resolve(resolvedParent, taskCwd);
+	if (pathInside(resolvedParent, resolvedTask)) {
+		return resolvedTask;
+	}
+	return resolvedParent;
+}

package/src/resources/skills/create-skill/SKILL.md

@@ -174,6 +174,9 @@ description: ...          # What it does AND when to use it (third person)
 ---
 ```
 
+Frontmatter must parse as YAML. Quote description values containing `:` or use
+a folded block (`description: >`) for longer trigger descriptions.
+
 Name conventions: `create-*`, `manage-*`, `setup-*`, `generate-*`, `build-*`
 </yaml_requirements>
 

package/src/resources/skills/create-skill/references/skill-structure.md

@@ -109,6 +109,7 @@ description: What it does and when to use it (third person, specific triggers)
 - No XML tags
 - Third person (never first or second person)
 - Include what it does AND when to use it
+- Must parse as YAML; quote values containing `:` or use `description: >`
 
 **Critical rule**: Always write in third person.
 - ✅ "Processes Excel files and generates reports"