gsd-pi 2.42.0-dev.97e9e30 → 2.42.0-dev.eedc83f

package/src/resources/extensions/async-jobs/async-bash-timeout.test.ts

@@ -0,0 +1,122 @@
+/**
+ * async-bash-timeout.test.ts — Tests for async_bash timeout behavior.
+ *
+ * Reproduces issue #2186: when an async bash job exceeds its timeout and
+ * the child process ignores SIGTERM, the promise hangs indefinitely.
+ * The fix adds a SIGKILL fallback and a hard deadline that force-resolves
+ * the promise so execution can continue.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createAsyncBashTool } from "./async-bash-tool.ts";
+import { AsyncJobManager } from "./job-manager.ts";
+
+function getTextFromResult(result: { content: Array<{ type: string; text?: string }> }): string {
+	return result.content.map((c) => c.text ?? "").join("\n");
+}
+
+const noopSignal = new AbortController().signal;
+
+test("async_bash with timeout resolves even if process ignores SIGTERM", async () => {
+	const manager = new AsyncJobManager();
+	const tool = createAsyncBashTool(() => manager, () => process.cwd());
+
+	// Start a job that traps SIGTERM (ignores it), with a 2s timeout.
+	// The process installs a SIGTERM trap and sleeps for 60s.
+	// Before the fix, this would hang forever because SIGTERM is ignored
+	// and the close event never fires.
+	const result = await tool.execute(
+		"tc-timeout",
+		{
+			command: "trap '' TERM; sleep 60",
+			timeout: 2,
+			label: "sigterm-resistant",
+		},
+		noopSignal,
+		() => {},
+		undefined as never,
+	);
+
+	const text = getTextFromResult(result);
+	assert.match(text, /sigterm-resistant/);
+
+	const jobId = text.match(/\*\*(bg_[a-f0-9]+)\*\*/)?.[1];
+	assert.ok(jobId, "Should have returned a job ID");
+
+	// Now await the job — it should resolve within a reasonable time
+	// (timeout 2s + SIGKILL grace 5s + buffer = well under 15s)
+	const start = Date.now();
+	const job = manager.getJob(jobId)!;
+	assert.ok(job, "Job should exist");
+
+	await Promise.race([
+		job.promise,
+		new Promise<never>((_, reject) => {
+			const t = setTimeout(() => reject(new Error(
+				`Job promise hung for ${Date.now() - start}ms — ` +
+				`this is the bug from issue #2186: timeout hangs indefinitely`,
+			)), 15_000);
+			if (typeof t === "object" && "unref" in t) t.unref();
+		}),
+	]);
+
+	const elapsed = Date.now() - start;
+	// Should have resolved well within 15s (timeout 2s + kill grace ~5s)
+	assert.ok(elapsed < 15_000, `Job took ${elapsed}ms — expected <15s`);
+
+	// Job should have completed (resolved, not rejected) with timeout message
+	assert.ok(
+		job.status === "completed" || job.status === "failed",
+		`Job status should be completed or failed, got: ${job.status}`,
+	);
+
+	if (job.status === "completed") {
+		assert.ok(
+			job.resultText?.includes("timed out") || job.resultText?.includes("Timed out"),
+			`Result should mention timeout, got: ${job.resultText}`,
+		);
+	}
+
+	manager.shutdown();
+});
+
+test("async_bash with timeout resolves normally when process exits on SIGTERM", async () => {
+	const manager = new AsyncJobManager();
+	const tool = createAsyncBashTool(() => manager, () => process.cwd());
+
+	// Start a normal sleep that will die on SIGTERM, with a 1s timeout
+	const result = await tool.execute(
+		"tc-normal-timeout",
+		{
+			command: "sleep 60",
+			timeout: 1,
+			label: "normal-timeout",
+		},
+		noopSignal,
+		() => {},
+		undefined as never,
+	);
+
+	const text = getTextFromResult(result);
+	const jobId = text.match(/\*\*(bg_[a-f0-9]+)\*\*/)?.[1];
+	assert.ok(jobId, "Should have returned a job ID");
+
+	const job = manager.getJob(jobId)!;
+	const start = Date.now();
+
+	await Promise.race([
+		job.promise,
+		new Promise<never>((_, reject) => {
+			const t = setTimeout(() => reject(new Error("Job hung")), 10_000);
+			if (typeof t === "object" && "unref" in t) t.unref();
+		}),
+	]);
+
+	const elapsed = Date.now() - start;
+	assert.ok(elapsed < 5_000, `Expected quick resolution after SIGTERM, took ${elapsed}ms`);
+	assert.equal(job.status, "completed");
+	assert.ok(job.resultText?.includes("timed out"), `Should mention timeout: ${job.resultText}`);
+
+	manager.shutdown();
+});

package/src/resources/extensions/async-jobs/async-bash-tool.ts

@@ -109,6 +109,10 @@ function executeBashInBackground(
 	timeout?: number,
 ): Promise<string> {
 	return new Promise<string>((resolve, reject) => {
+		let settled = false;
+		const safeResolve = (value: string) => { if (!settled) { settled = true; resolve(value); } };
+		const safeReject = (err: unknown) => { if (!settled) { settled = true; reject(err); } };
+
 		const { shell, args } = getShellConfig();
 		const resolvedCommand = sanitizeCommand(command);
 
@@ -121,11 +125,39 @@ function executeBashInBackground(
 
 		let timedOut = false;
 		let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+		let sigkillHandle: ReturnType<typeof setTimeout> | undefined;
+		let hardDeadlineHandle: ReturnType<typeof setTimeout> | undefined;
+
+		/** Grace period (ms) between SIGTERM and SIGKILL. */
+		const SIGKILL_GRACE_MS = 5_000;
+		/** Hard deadline (ms) after SIGKILL to force-resolve the promise. */
+		const HARD_DEADLINE_MS = 3_000;
 
 		if (timeout !== undefined && timeout > 0) {
 			timeoutHandle = setTimeout(() => {
 				timedOut = true;
 				if (child.pid) killTree(child.pid);
+
+				// If the process ignores SIGTERM, escalate to SIGKILL
+				sigkillHandle = setTimeout(() => {
+					if (child.pid) {
+						try { process.kill(-child.pid, "SIGKILL"); } catch { /* ignore */ }
+						try { process.kill(child.pid, "SIGKILL"); } catch { /* ignore */ }
+					}
+
+					// Hard deadline: if even SIGKILL doesn't trigger 'close',
+					// force-resolve so the job doesn't hang forever (#2186).
+					hardDeadlineHandle = setTimeout(() => {
+						const output = Buffer.concat(chunks).toString("utf-8");
+						safeResolve(
+							output
+								? `${output}\n\nCommand timed out after ${timeout} seconds (force-killed)`
+								: `Command timed out after ${timeout} seconds (force-killed)`,
+						);
+					}, HARD_DEADLINE_MS);
+					if (typeof hardDeadlineHandle === "object" && "unref" in hardDeadlineHandle) hardDeadlineHandle.unref();
+				}, SIGKILL_GRACE_MS);
+				if (typeof sigkillHandle === "object" && "unref" in sigkillHandle) sigkillHandle.unref();
 			}, timeout * 1000);
 		}
 
@@ -168,24 +200,28 @@ function executeBashInBackground(
 
 		child.on("error", (err) => {
 			if (timeoutHandle) clearTimeout(timeoutHandle);
+			if (sigkillHandle) clearTimeout(sigkillHandle);
+			if (hardDeadlineHandle) clearTimeout(hardDeadlineHandle);
 			signal.removeEventListener("abort", onAbort);
-			reject(err);
+			safeReject(err);
 		});
 
 		child.on("close", (code) => {
 			if (timeoutHandle) clearTimeout(timeoutHandle);
+			if (sigkillHandle) clearTimeout(sigkillHandle);
+			if (hardDeadlineHandle) clearTimeout(hardDeadlineHandle);
 			signal.removeEventListener("abort", onAbort);
 			if (spillStream) spillStream.end();
 
 			if (signal.aborted) {
 				const output = Buffer.concat(chunks).toString("utf-8");
-				resolve(output ? `${output}\n\nCommand aborted` : "Command aborted");
+				safeResolve(output ? `${output}\n\nCommand aborted` : "Command aborted");
 				return;
 			}
 
 			if (timedOut) {
 				const output = Buffer.concat(chunks).toString("utf-8");
-				resolve(output ? `${output}\n\nCommand timed out after ${timeout} seconds` : `Command timed out after ${timeout} seconds`);
+				safeResolve(output ? `${output}\n\nCommand timed out after ${timeout} seconds` : `Command timed out after ${timeout} seconds`);
 				return;
 			}
 
@@ -208,7 +244,7 @@ function executeBashInBackground(
 				text += `\n\nCommand exited with code ${code}`;
 			}
 
-			resolve(text);
+			safeResolve(text);
 		});
 	});
 }

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

@@ -986,7 +986,7 @@ export async function buildPlanSlicePrompt(
   const prefs = loadEffectiveGSDPreferences();
   const commitDocsEnabled = prefs?.preferences?.git?.commit_docs !== false;
   const commitInstruction = commitDocsEnabled
-    ? `Commit the plan files only: \`git add ${relSlicePath(base, mid, sid)}/ .gsd/DECISIONS.md .gitignore && git commit -m "docs(${sid}): add slice plan"\`. Do not stage .gsd/STATE.md or other runtime files — the system manages those.`
+    ? `Commit the plan files only: \`git add --force ${relSlicePath(base, mid, sid)}/ .gsd/DECISIONS.md .gitignore && git commit -m "docs(${sid}): add slice plan"\`. Do not stage .gsd/STATE.md or other runtime files — the system manages those.`
     : "Do not commit — planning docs are not tracked in git for this project.";
   return loadPrompt("plan-slice", {
     workingDirectory: base,

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

@@ -20,21 +20,27 @@ import { saveActivityLog } from "../activity-log.js";
 // printed it before the TUI launched. Only re-print on /clear (subsequent sessions).
 let isFirstSession = true;
 
+async function syncServiceTierStatus(ctx: ExtensionContext): Promise<void> {
+  const { getEffectiveServiceTier, formatServiceTierFooterStatus } = await import("../service-tier.js");
+  ctx.ui.setStatus("gsd-fast", formatServiceTierFooterStatus(getEffectiveServiceTier(), ctx.model?.id));
+}
+
 export function registerHooks(pi: ExtensionAPI): void {
   pi.on("session_start", async (_event, ctx) => {
     resetWriteGateState();
     resetToolCallLoopGuard();
+    await syncServiceTierStatus(ctx);
     if (isFirstSession) {
       isFirstSession = false;
     } else {
       try {
         const gsdBinPath = process.env.GSD_BIN_PATH;
         if (gsdBinPath) {
-          const { dirname } = await import('node:path');
+          const { dirname } = await import("node:path");
           const { printWelcomeScreen } = await import(
-            join(dirname(gsdBinPath), 'welcome-screen.js')
+            join(dirname(gsdBinPath), "welcome-screen.js")
           ) as { printWelcomeScreen: (opts: { version: string; modelName?: string; provider?: string }) => void };
-          printWelcomeScreen({ version: process.env.GSD_VERSION || '0.0.0' });
+          printWelcomeScreen({ version: process.env.GSD_VERSION || "0.0.0" });
         }
       } catch { /* non-fatal */ }
     }
@@ -192,8 +198,11 @@ export function registerHooks(pi: ExtensionAPI): void {
     markToolEnd(event.toolCallId);
   });
 
+  pi.on("model_select", async (_event, ctx) => {
+    await syncServiceTierStatus(ctx);
+  });
+
   pi.on("before_provider_request", async (event) => {
-    if (!isAutoActive()) return;
     const modelId = event.model?.id;
     if (!modelId) return;
     const { getEffectiveServiceTier, supportsServiceTier } = await import("../service-tier.js");
@@ -205,4 +214,3 @@ export function registerHooks(pi: ExtensionAPI): void {
     return payload;
   });
 }
-

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

@@ -87,6 +87,18 @@ export const PROJECT_FILES = [
   "mix.exs",
   "deno.json",
   "deno.jsonc",
+  // .NET
+  ".sln",
+  ".csproj",
+  "Directory.Build.props",
+  // Git submodules
+  ".gitmodules",
+  // Xcode
+  "project.yml",
+  ".xcodeproj",
+  ".xcworkspace",
+  // Docker
+  "Dockerfile",
 ] as const;
 
 const LANGUAGE_MAP: Record<string, string> = {
@@ -106,6 +118,13 @@ const LANGUAGE_MAP: Record<string, string> = {
   "mix.exs": "elixir",
   "deno.json": "typescript/deno",
   "deno.jsonc": "typescript/deno",
+  ".sln": "dotnet",
+  ".csproj": "dotnet",
+  "Directory.Build.props": "dotnet",
+  "project.yml": "swift/xcode",
+  ".xcodeproj": "swift/xcode",
+  ".xcworkspace": "swift/xcode",
+  "Dockerfile": "docker",
 };
 
 const MONOREPO_MARKERS = [

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

@@ -2,7 +2,7 @@ import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, rmSync,
 import { basename, dirname, join, sep } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
-import { readRepoMeta, externalProjectsRoot } from "./repo-identity.js";
+import { readRepoMeta, externalProjectsRoot, cleanNumberedGsdVariants } from "./repo-identity.js";
 import { loadFile, parseRoadmap } from "./files.js";
 import { resolveMilestoneFile, milestonesDir, gsdRoot, resolveGsdRootFile, relGsdRootFile } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
@@ -776,6 +776,37 @@ export async function checkRuntimeHealth(
     // Non-fatal — external state check failed
   }
 
+  // ── Numbered .gsd collision variants (#2205) ───────────────────────────
+  // macOS APFS can create ".gsd 2", ".gsd 3" etc. when a directory blocks
+  // symlink creation. These must be removed so the canonical .gsd is used.
+  try {
+    const variantPattern = /^\.gsd \d+$/;
+    const entries = readdirSync(basePath);
+    const variants = entries.filter(e => variantPattern.test(e));
+    if (variants.length > 0) {
+      for (const v of variants) {
+        issues.push({
+          severity: "warning",
+          code: "numbered_gsd_variant",
+          scope: "project",
+          unitId: "project",
+          message: `Found macOS collision variant "${v}" — this can cause GSD state to appear deleted.`,
+          file: v,
+          fixable: true,
+        });
+      }
+
+      if (shouldFix("numbered_gsd_variant")) {
+        const removed = cleanNumberedGsdVariants(basePath);
+        for (const name of removed) {
+          fixesApplied.push(`removed numbered .gsd variant: ${name}`);
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — variant check failed
+  }
+
   // ── Metrics ledger integrity ───────────────────────────────────────────
   try {
     const metricsPath = join(root, "metrics.json");

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

@@ -305,11 +305,24 @@ function checkOptionalProviders(): ProviderCheckResult[] {
   const optional = ["brave", "tavily", "jina", "context7"] as const;
   const results: ProviderCheckResult[] = [];
 
+  // Determine which search providers are configured so we can suppress
+  // "not configured" noise for alternative search providers when at least
+  // one is already active (e.g. don't warn about missing BRAVE_API_KEY
+  // when Tavily is configured).
+  const searchProviderIds = ["brave", "tavily"] as const;
+  const hasAnySearchProvider = searchProviderIds.some(id => resolveKey(id).found);
+
   for (const providerId of optional) {
     const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
     if (!info) continue;
 
     const lookup = resolveKey(providerId);
+
+    // Skip unconfigured search providers when another search provider is active
+    if (!lookup.found && hasAnySearchProvider && info.category === "search") {
+      continue;
+    }
+
     results.push({
       name: providerId,
       label: info.label,

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

@@ -33,6 +33,7 @@ export type DoctorIssueCode =
   | "unresolvable_dependency"
   | "failed_migration"
   | "broken_symlink"
+  | "numbered_gsd_variant"
   // Environment health checks (#1221)
   | "env_node_version"
   | "env_dependencies"

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

@@ -30,6 +30,9 @@ import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
 import { formatDuration } from "../shared/format-utils.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
+import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
+import { showNextAction } from "../shared/tui.js";
+import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -67,6 +70,71 @@ interface ForensicReport {
   recentUnits: { type: string; id: string; cost: number; duration: number; model: string; finishedAt: number }[];
 }
 
+// ─── Duplicate Detection ──────────────────────────────────────────────────────
+
+const DEDUP_PROMPT_SECTION = `
+## Duplicate Detection (REQUIRED before issue creation)
+
+Before offering to create a GitHub issue, you MUST search for existing issues and PRs that may already address this bug. This step uses the user's AI tokens for analysis.
+
+### Search Steps
+
+1. **Search closed issues** for similar keywords from your diagnosis:
+   \`\`\`
+   gh issue list --repo gsd-build/gsd-2 --state closed --search "<keywords from root cause>" --limit 20
+   \`\`\`
+
+2. **Search open PRs** that might contain the fix:
+   \`\`\`
+   gh pr list --repo gsd-build/gsd-2 --state open --search "<keywords>" --limit 10
+   \`\`\`
+
+3. **Search merged PRs** that may have already fixed this:
+   \`\`\`
+   gh pr list --repo gsd-build/gsd-2 --state merged --search "<keywords>" --limit 10
+   \`\`\`
+
+### Analysis
+
+For each result, compare it against your root-cause diagnosis:
+- Does the issue describe the same code path or file?
+- Does the PR modify the same file:line you identified?
+- Is the symptom description semantically similar even if keywords differ?
+
+### Present Findings
+
+If you find potential matches, present them to the user:
+
+1. **"Already fixed by PR #X — skip issue creation"** — when a merged PR or closed issue clearly addresses the same root cause. Explain why you believe it matches.
+2. **"Add my findings to existing issue #Y"** — when an open issue exists for the same bug. Use \`gh issue comment #Y --repo gsd-build/gsd-2\` to add forensic evidence.
+3. **"Create new issue anyway"** — when existing results do not cover this specific failure.
+
+Only proceed to issue creation if no matches were found OR the user explicitly chooses "Create new issue anyway".
+`;
+
+async function writeForensicsDedupPref(ctx: ExtensionCommandContext, enabled: boolean): Promise<void> {
+  const prefsPath = getGlobalGSDPreferencesPath();
+  await ensurePreferencesFile(prefsPath, ctx, "global");
+  const existing = loadGlobalGSDPreferences();
+  const prefs: Record<string, unknown> = existing?.preferences ? { ...existing.preferences } : {};
+  prefs.version = prefs.version || 1;
+  prefs.forensics_dedup = enabled;
+
+  const frontmatter = serializePreferencesToFrontmatter(prefs);
+  const raw = existsSync(prefsPath) ? readFileSync(prefsPath, "utf-8") : "";
+  let body = "\n# GSD Skill Preferences\n\nSee `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation and examples.\n";
+  const start = raw.startsWith("---\n") ? 4 : raw.startsWith("---\r\n") ? 5 : -1;
+  if (start !== -1) {
+    const closingIdx = raw.indexOf("\n---", start);
+    if (closingIdx !== -1) {
+      const after = raw.slice(closingIdx + 4);
+      if (after.trim()) body = after;
+    }
+  }
+
+  writeFileSync(prefsPath, `---\n${frontmatter}---${body}`, "utf-8");
+}
+
 // ─── Entry Point ──────────────────────────────────────────────────────────────
 
 export async function handleForensics(
@@ -98,6 +166,29 @@ export async function handleForensics(
     return;
   }
 
+  // ─── Duplicate detection opt-in ─────────────────────────────────────────────
+  const effectivePrefs = loadEffectiveGSDPreferences()?.preferences;
+  let dedupEnabled = effectivePrefs?.forensics_dedup === true;
+
+  if (effectivePrefs?.forensics_dedup === undefined) {
+    const choice = await showNextAction(ctx, {
+      title: "Duplicate detection available",
+      summary: ["Before filing a GitHub issue, forensics can search existing issues and PRs to avoid duplicates.", "This uses additional AI tokens for analysis."],
+      actions: [
+        { id: "enable", label: "Enable duplicate detection", description: "Search issues/PRs before filing (recommended)", recommended: true },
+        { id: "skip", label: "Skip for now", description: "File without checking for duplicates" },
+      ],
+      notYetMessage: "You can enable this later via preferences (forensics_dedup: true).",
+    });
+
+    if (choice === "enable") {
+      await writeForensicsDedupPref(ctx, true);
+      dedupEnabled = true;
+    }
+  }
+
+  const dedupSection = dedupEnabled ? DEDUP_PROMPT_SECTION : "";
+
   ctx.ui.notify("Building forensic report...", "info");
 
   const report = await buildForensicReport(basePath);
@@ -117,6 +208,7 @@ export async function handleForensics(
     problemDescription,
     forensicData,
     gsdSourceDir,
+    dedupSection,
   });
 
   ctx.ui.notify(`Forensic report saved: ${relative(basePath, savedPath)}`, "info");

package/src/resources/extensions/gsd/git-constants.ts

@@ -8,4 +8,5 @@ export const GIT_NO_PROMPT_ENV = {
   GIT_TERMINAL_PROMPT: "0",
   GIT_ASKPASS: "",
   GIT_SVN_ID: "",
+  LC_ALL: "C", // force English git output so stderr string checks work on all locales (#1997)
 };

package/src/resources/extensions/gsd/git-service.ts

@@ -9,8 +9,8 @@
  */
 
 import { execFileSync, execSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -486,11 +486,80 @@ export class GitServiceImpl {
     // git add -A already skips it and the exclusions are harmless no-ops.
     const allExclusions = [...RUNTIME_EXCLUSION_PATHS, ...extraExclusions];
     nativeAddAllWithExclusions(this.basePath, allExclusions);
+
+    // Force-add .gsd/milestones/ when .gsd is a symlink (#2104).
+    // When .gsd is a symlink (external state projects), ensureGitignore adds
+    // `.gsd` to .gitignore. The nativeAddAllWithExclusions call above falls
+    // back to plain `git add -A` (symlink pathspec rejection), which respects
+    // .gitignore and silently skips new .gsd/milestones/ files.
+    //
+    // `git add -f` also fails with "beyond a symbolic link", so we use
+    // `git hash-object -w` + `git update-index --add --cacheinfo` to bypass
+    // the symlink restriction entirely. This stages each milestone artifact
+    // individually by hashing the file content and updating the index directly.
+    const gsdPath = join(this.basePath, ".gsd");
+    const milestonesDir = join(gsdPath, "milestones");
+    try {
+      if (
+        existsSync(gsdPath) &&
+        lstatSync(gsdPath).isSymbolicLink() &&
+        existsSync(milestonesDir)
+      ) {
+        this._forceAddMilestoneArtifacts(milestonesDir);
+      }
+    } catch {
+      // Non-fatal: if force-add fails, the commit proceeds without these files.
+      // This matches existing behavior where milestone artifacts were silently
+      // omitted — but now we at least attempt to include them.
+    }
   }
 
   /** Tracks whether runtime file cleanup has run this session. */
   private _runtimeFilesCleanedUp = false;
 
+  /**
+   * Recursively collect all files under a directory.
+   * Returns paths relative to `basePath` (e.g. ".gsd/milestones/M009/SUMMARY.md").
+   */
+  private _collectFiles(dir: string): string[] {
+    const files: string[] = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...this._collectFiles(full));
+      } else if (entry.isFile()) {
+        files.push(relative(this.basePath, full));
+      }
+    }
+    return files;
+  }
+
+  /**
+   * Stage milestone artifacts through a symlinked .gsd directory (#2104).
+   *
+   * `git add` (even with `-f`) refuses to stage files "beyond a symbolic link".
+   * This method bypasses that restriction by hashing each file with
+   * `git hash-object -w` and inserting the blob into the index with
+   * `git update-index --add --cacheinfo 100644 <hash> <path>`.
+   */
+  private _forceAddMilestoneArtifacts(milestonesDir: string): void {
+    const files = this._collectFiles(milestonesDir);
+    for (const filePath of files) {
+      const hash = execFileSync("git", ["hash-object", "-w", filePath], {
+        cwd: this.basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      }).trim();
+      execFileSync("git", ["update-index", "--add", "--cacheinfo", "100644", hash, filePath], {
+        cwd: this.basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      });
+    }
+  }
+
   /**
    * Stage files (smart staging) and commit.
    * Returns the commit message string on success, or null if nothing to commit.

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -847,6 +847,7 @@ export function nativeMergeSquash(basePath: string, branch: string): GitMergeRes
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
     });
     return { success: true, conflicts: [] };
   } catch (err: unknown) {

package/src/resources/extensions/gsd/preferences-types.ts

@@ -89,6 +89,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "reactive_execution",
   "github",
   "service_tier",
+  "forensics_dedup",
 ]);
 
 /** Canonical list of all dispatch unit types. */
@@ -223,6 +224,8 @@ export interface GSDPreferences {
   github?: GitHubSyncConfig;
   /** OpenAI service tier preference. "priority" = 2x cost, faster. "flex" = 0.5x cost, slower. Only affects gpt-5.4 models. */
   service_tier?: "priority" | "flex";
+  /** Opt-in: search existing issues and PRs before filing from /gsd forensics. Uses additional AI tokens. */
+  forensics_dedup?: boolean;
 }
 
 export interface LoadedGSDPreferences {