gsd-pi 2.41.0-dev.cac69f9 → 2.42.0-dev.1df898f

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/engine-resolver.ts

@@ -0,0 +1,57 @@
+/**
+ * engine-resolver.ts — Route sessions to engine/policy pairs.
+ *
+ * Routes `null` and `"dev"` engine IDs to the DevWorkflowEngine/DevExecutionPolicy
+ * pair. Any other non-null engine ID is treated as a custom workflow engine that
+ * reads its state from an `activeRunDir`. Respects `GSD_ENGINE_BYPASS=1` kill
+ * switch to skip the engine layer entirely.
+ */
+
+import type { WorkflowEngine } from "./workflow-engine.js";
+import type { ExecutionPolicy } from "./execution-policy.js";
+import { DevWorkflowEngine } from "./dev-workflow-engine.js";
+import { DevExecutionPolicy } from "./dev-execution-policy.js";
+import { CustomWorkflowEngine } from "./custom-workflow-engine.js";
+import { CustomExecutionPolicy } from "./custom-execution-policy.js";
+
+/** A resolved engine + policy pair ready for the auto-loop. */
+export interface ResolvedEngine {
+  engine: WorkflowEngine;
+  policy: ExecutionPolicy;
+}
+
+/**
+ * Resolve an engine/policy pair for the given session.
+ *
+ * - `null` or `"dev"` → DevWorkflowEngine + DevExecutionPolicy
+ * - any other non-null ID → CustomWorkflowEngine(activeRunDir) + CustomExecutionPolicy()
+ *   (requires activeRunDir to be a non-empty string)
+ *
+ * Note: `GSD_ENGINE_BYPASS=1` is checked in autoLoop before calling this function.
+ */
+export function resolveEngine(
+  session: { activeEngineId: string | null; activeRunDir?: string | null },
+): ResolvedEngine {
+  const { activeEngineId, activeRunDir } = session;
+
+  if (activeEngineId === null || activeEngineId === "dev") {
+    return {
+      engine: new DevWorkflowEngine(),
+      policy: new DevExecutionPolicy(),
+    };
+  }
+
+  // Any non-null, non-"dev" engine ID is a custom workflow engine.
+  // activeRunDir is required — the engine reads GRAPH.yaml from it.
+  if (!activeRunDir || typeof activeRunDir !== "string") {
+    throw new Error(
+      `Custom engine "${activeEngineId}" requires activeRunDir to be a non-empty string, ` +
+      `got: ${JSON.stringify(activeRunDir)}`,
+    );
+  }
+
+  return {
+    engine: new CustomWorkflowEngine(activeRunDir),
+    policy: new CustomExecutionPolicy(activeRunDir),
+  };
+}

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

@@ -0,0 +1,71 @@
+/**
+ * engine-types.ts — Engine-polymorphic type contracts.
+ *
+ * LEAF NODE: This file must have ZERO imports from any GSD module.
+ * Only `node:` imports are permitted. All engine/policy interfaces
+ * depend on these types; nothing here depends on GSD internals.
+ */
+
+/** Snapshot of engine state at a point in time. */
+export interface EngineState {
+  phase: string;
+  currentMilestoneId: string | null;
+  activeSliceId: string | null;
+  activeTaskId: string | null;
+  isComplete: boolean;
+  /** Opaque engine-specific state — never narrowed to a GSD-specific type. */
+  raw: unknown;
+}
+
+/** A unit of work the engine wants the agent to execute. */
+export interface StepContract {
+  unitType: string;
+  unitId: string;
+  prompt: string;
+}
+
+/** UI-facing metadata for progress display. */
+export interface DisplayMetadata {
+  engineLabel: string;
+  currentPhase: string;
+  progressSummary: string;
+  stepCount: { completed: number; total: number } | null;
+}
+
+/**
+ * Discriminated union: what the engine tells the loop to do next.
+ *
+ * - `dispatch` — execute a step
+ * - `stop` — halt the loop with a reason and severity
+ * - `skip` — nothing to do right now, advance without executing
+ */
+export type EngineDispatchAction =
+  | { action: "dispatch"; step: StepContract }
+  | { action: "stop"; reason: string; level: "info" | "warning" | "error" }
+  | { action: "skip" };
+
+/** Outcome of reconciling state after a step completes. */
+export interface ReconcileResult {
+  outcome: "continue" | "milestone-complete" | "pause" | "stop";
+  reason?: string;
+}
+
+/** Recovery strategy when a step fails. */
+export interface RecoveryAction {
+  outcome: "retry" | "skip" | "stop" | "pause";
+  reason?: string;
+}
+
+/** Result of closing out a completed unit. */
+export interface CloseoutResult {
+  committed: boolean;
+  artifacts: string[];
+}
+
+/** Record of a completed execution step. */
+export interface CompletedStep {
+  unitType: string;
+  unitId: string;
+  startedAt: number;
+  finishedAt: number;
+}

package/src/resources/extensions/gsd/execution-policy.ts

@@ -0,0 +1,43 @@
+/**
+ * execution-policy.ts — ExecutionPolicy interface.
+ *
+ * Defines the policy layer that governs model selection, verification,
+ * recovery, and closeout for each execution step. Imports only from
+ * the leaf-node engine-types.
+ */
+
+import type { RecoveryAction, CloseoutResult } from "./engine-types.js";
+
+/** Policy governing how each step is executed, verified, and closed out. */
+export interface ExecutionPolicy {
+  /** Prepare the workspace before a milestone begins (e.g. worktree setup). */
+  prepareWorkspace(basePath: string, milestoneId: string): Promise<void>;
+
+  /** Select the model tier for a given unit. Returns null to use defaults. */
+  selectModel(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string },
+  ): Promise<{ tier: string; modelDowngraded: boolean } | null>;
+
+  /** Verify unit output. Returns disposition for the loop. */
+  verify(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string },
+  ): Promise<"continue" | "retry" | "pause">;
+
+  /** Determine recovery action when a unit fails. */
+  recover(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string },
+  ): Promise<RecoveryAction>;
+
+  /** Close out a completed unit (commit, snapshot, artifact capture). */
+  closeout(
+    unitType: string,
+    unitId: string,
+    context: { basePath: string; startedAt: number },
+  ): Promise<CloseoutResult>;
+}

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

@@ -245,7 +245,6 @@ export function writeIntegrationBranch(
   basePath: string,
   milestoneId: string,
   branch: string,
-  _options?: { commitDocs?: boolean },
 ): void {
   // Don't record slice branches as the integration target
   if (SLICE_BRANCH_RE.test(branch)) return;

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

@@ -137,7 +137,7 @@ export function hasGitTrackedGsdFiles(basePath: string): boolean {
  */
 export function ensureGitignore(
   basePath: string,
-  options?: { manageGitignore?: boolean; commitDocs?: boolean },
+  options?: { manageGitignore?: boolean },
 ): boolean {
   // If manage_gitignore is explicitly false, do not touch .gitignore at all
   if (options?.manageGitignore === false) return false;