gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.2203010a0

package/src/resources/extensions/gsd/health-widget-core.ts

@@ -61,9 +61,10 @@ function truncateMessage(msg: string, maxLen: number): string {
 
 /**
  * Build compact health lines for the widget.
- * Returns a string array suitable for setWidget().
+ * When `width` is provided, system + budget render left and last-commit
+ * right-aligned. Without width, all parts are joined inline (RPC fallback).
  */
-export function buildHealthLines(data: HealthWidgetData): string[] {
+export function buildHealthLines(data: HealthWidgetData, width?: number): string[] {
   if (data.projectState === "none") {
     return ["  GSD  No project loaded — run /gsd to start"];
   }
@@ -72,40 +73,68 @@ export function buildHealthLines(data: HealthWidgetData): string[] {
     return ["  GSD  Project initialized — run /gsd to continue setup"];
   }
 
-  const parts: string[] = [];
+  const leftParts: string[] = [];
 
   const totalIssues = data.environmentErrorCount + data.environmentWarningCount + (data.providerIssue ? 1 : 0);
   if (totalIssues === 0) {
-    parts.push("● System OK");
+    leftParts.push("● System OK");
   } else if (data.environmentErrorCount > 0 || data.providerIssue?.includes("✗")) {
-    parts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
+    leftParts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
   } else {
-    parts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
+    leftParts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
   }
 
   if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
     const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
-    parts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
+    leftParts.push(`Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`);
   } else if (data.budgetSpent > 0) {
-    parts.push(`Spent: ${formatCost(data.budgetSpent)}`);
+    leftParts.push(`Spent: ${formatCost(data.budgetSpent)}`);
   }
 
   if (data.providerIssue) {
-    parts.push(data.providerIssue);
+    leftParts.push(data.providerIssue);
   }
 
   if (data.environmentErrorCount > 0) {
-    parts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
+    leftParts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
   } else if (data.environmentWarningCount > 0) {
-    parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
+    leftParts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
   }
 
-  // Always-on last commit display — shows relative time + truncated message
+  // Last commit goes on the right-hand side when width is known.
+  let rightText = "";
   if (data.lastCommitEpoch !== null && data.lastCommitEpoch > 0) {
     const relTime = formatRelativeTime(data.lastCommitEpoch);
     const msg = data.lastCommitMessage ? ` — ${truncateMessage(data.lastCommitMessage, 50)}` : "";
-    parts.push(`Last commit: ${relTime}${msg}`);
+    rightText = `Last commit: ${relTime}${msg}`;
   }
 
-  return [`  ${parts.join("  │  ")}`];
+  const leftText = leftParts.join("  │  ");
+
+  if (width === undefined) {
+    const inline = rightText ? `${leftText}  │  ${rightText}` : leftText;
+    return [`  ${inline}`];
+  }
+
+  const prefix = "  ";
+  const innerWidth = Math.max(0, width - prefix.length);
+  const leftVis = leftText.length;
+  const rightVis = rightText.length;
+
+  if (!rightText) return [`${prefix}${truncateMessage(leftText, innerWidth)}`];
+  const MIN_GAP = 2;
+  if (leftVis + MIN_GAP + rightVis > innerWidth) {
+    // Preserve the left (status + budget) and truncate the right side
+    // (last commit) with an ellipsis so the combined line never exceeds
+    // innerWidth. If even the left alone overflows, clamp it too.
+    const leftRoom = Math.max(1, Math.min(leftVis, innerWidth - MIN_GAP - 1));
+    const clampedLeft = truncateMessage(leftText, leftRoom);
+    const rightRoom = Math.max(0, innerWidth - clampedLeft.length - MIN_GAP);
+    const clampedRight = rightRoom > 0 ? truncateMessage(rightText, rightRoom) : "";
+    if (!clampedRight) return [`${prefix}${clampedLeft}`];
+    const pad = " ".repeat(Math.max(MIN_GAP, innerWidth - clampedLeft.length - clampedRight.length));
+    return [`${prefix}${clampedLeft}${pad}${clampedRight}`];
+  }
+  const padding = " ".repeat(innerWidth - leftVis - rightVis);
+  return [`${prefix}${leftText}${padding}${rightText}`];
 }

package/src/resources/extensions/gsd/health-widget.ts

@@ -129,12 +129,16 @@ export function initHealthWidget(ctx: ExtensionContext): void {
       void refresh();
     }, REFRESH_INTERVAL_MS);
 
+    let cachedWidth: number | undefined;
     return {
-      render(_width: number): string[] {
-        if (!cachedLines) cachedLines = buildHealthLines(data);
+      render(width: number): string[] {
+        if (!cachedLines || cachedWidth !== width) {
+          cachedLines = buildHealthLines(data, width);
+          cachedWidth = width;
+        }
         return cachedLines;
       },
-      invalidate(): void { cachedLines = undefined; },
+      invalidate(): void { cachedLines = undefined; cachedWidth = undefined; },
       dispose(): void {
         clearInterval(refreshTimer);
       },

package/src/resources/extensions/gsd/init-wizard.ts

@@ -17,6 +17,7 @@ import { assertSafeDirectory } from "./validate-directory.js";
 import type { ProjectDetection, ProjectSignals } from "./detection.js";
 import { runSkillInstallStep } from "./skill-catalog.js";
 import { generateCodebaseMap, writeCodebaseMap } from "./codebase-generator.js";
+import { handlePrefsWizard, writePreferencesFile } from "./commands-prefs-wizard.js";
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -232,8 +233,53 @@ export async function showProjectInit(
     // Non-fatal — skill installation failure should never block project init
   }
 
-  // ── Step 9: Bootstrap .gsd/ ────────────────────────────────────────────────
-  bootstrapGsdDirectory(basePath, prefs, signals);
+  // ── Step 9: Optional full-prefs review ─────────────────────────────────────
+  // Ask BEFORE bootstrapping so a defer (`not_yet`) leaves the project untouched.
+  // Once the user commits, we bootstrap and route preferences through the unified
+  // writer (commands-prefs-wizard.writePreferencesFile) so init and the prefs
+  // wizard share one serializer. The "Open full wizard" branch surfaces every
+  // configurable preference, prefilled with the init answers.
+  const reviewChoice = await showNextAction(ctx, {
+    title: "GSD — Review All Preferences (Optional)",
+    summary: [
+      "Open the full preferences wizard now? It includes models, timeouts,",
+      "budget, notifications, and skills — all pre-filled with your answers.",
+      "",
+      "Skip if you just want sensible defaults; you can always run /gsd prefs project later.",
+    ],
+    actions: [
+      { id: "skip", label: "Skip — use defaults", description: "Save preferences and continue", recommended: true },
+      { id: "review", label: "Open full wizard", description: "Tweak any category before saving" },
+    ],
+    notYetMessage: "Run /gsd init when ready.",
+  });
+
+  if (reviewChoice === "not_yet") {
+    // User deferred — don't create .gsd/ or persist preferences. Pre-step state
+    // (e.g. git init from Step 2) remains as-is, matching prior step semantics.
+    return { completed: false, bootstrapped: false };
+  }
+
+  // ── Step 10: Bootstrap .gsd/ + write preferences ───────────────────────────
+  bootstrapGsdDirectoryStructure(basePath, signals);
+  const prefillPrefs = mapInitPrefsToWizardShape(prefs);
+  // Always derive the preferences path from basePath so init writing the
+  // structure to one location and preferences to another (cwd-derived) is
+  // impossible — see #4457 codex review.
+  const projectPrefsPath = join(gsdRoot(basePath), "PREFERENCES.md");
+
+  if (reviewChoice === "review") {
+    // Wizard writes via writePreferencesFile internally; pass pathOverride so it
+    // targets basePath rather than cwd.
+    await handlePrefsWizard(ctx, "project", prefillPrefs, { pathOverride: projectPrefsPath });
+  } else {
+    // Direct path: write the init-collected prefs through the unified writer.
+    await writePreferencesFile(projectPrefsPath, prefillPrefs, ctx, {
+      scope: "project",
+      defaultBody: buildInitPreferencesBody(),
+      notifyOnSave: false,
+    });
+  }
 
   // Initialize SQLite database so GSD starts in full-capability mode (#3880).
   // Without this, isDbAvailable() returns false and GSD enters degraded
@@ -453,11 +499,13 @@ async function customizeAdvancedPrefs(
 
 // ─── Bootstrap ──────────────────────────────────────────────────────────────────
 
-function bootstrapGsdDirectory(
-  basePath: string,
-  prefs: ProjectPreferences,
-  signals: ProjectSignals,
-): void {
+/**
+ * Create .gsd/ directory structure and seed CONTEXT.md.
+ *
+ * Preferences are written separately by the caller via the unified
+ * writePreferencesFile helper so init and the prefs wizard share one path.
+ */
+function bootstrapGsdDirectoryStructure(basePath: string, signals: ProjectSignals): void {
   // Final safety check before writing any files
   assertSafeDirectory(basePath);
 
@@ -465,10 +513,6 @@ function bootstrapGsdDirectory(
   mkdirSync(join(gsd, "milestones"), { recursive: true });
   mkdirSync(join(gsd, "runtime"), { recursive: true });
 
-  // Write PREFERENCES.md from wizard answers
-  const preferencesContent = buildPreferencesFile(prefs);
-  writeFileSync(join(gsd, "PREFERENCES.md"), preferencesContent, "utf-8");
-
   // Seed CONTEXT.md with detected project signals
   const contextContent = buildContextSeed(signals);
   if (contextContent) {
@@ -476,60 +520,49 @@ function bootstrapGsdDirectory(
   }
 }
 
-function buildPreferencesFile(prefs: ProjectPreferences): string {
-  const lines: string[] = ["---"];
-  lines.push("version: 1");
-  lines.push(`mode: ${prefs.mode}`);
-
-  // Git preferences
-  lines.push("git:");
-  lines.push(`  isolation: ${prefs.gitIsolation}`);
-  lines.push(`  main_branch: ${prefs.mainBranch}`);
-  lines.push(`  auto_push: ${prefs.autoPush}`);
+/**
+ * Map init wizard's typed ProjectPreferences to the prefs-wizard's
+ * Record<string, unknown> shape, matching the keys serializePreferencesToFrontmatter
+ * expects (mode, git.{isolation,main_branch,auto_push}, verification_commands, etc.).
+ *
+ * Exported for testing; init-wizard uses it inline.
+ */
+export function mapInitPrefsToWizardShape(prefs: ProjectPreferences): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    mode: prefs.mode,
+    git: {
+      isolation: prefs.gitIsolation,
+      main_branch: prefs.mainBranch,
+      auto_push: prefs.autoPush,
+    },
+  };
 
-  // Verification commands
   if (prefs.verificationCommands.length > 0) {
-    lines.push("verification_commands:");
-    for (const cmd of prefs.verificationCommands) {
-      lines.push(`  - "${cmd}"`);
-    }
+    out.verification_commands = prefs.verificationCommands;
   }
-
-  // Custom instructions
   if (prefs.customInstructions.length > 0) {
-    lines.push("custom_instructions:");
-    for (const inst of prefs.customInstructions) {
-      lines.push(`  - "${inst.replace(/"/g, '\\"')}"`);
-    }
+    out.custom_instructions = prefs.customInstructions;
   }
-
-  // Token profile (only if non-default)
   if (prefs.tokenProfile !== "balanced") {
-    lines.push(`token_profile: ${prefs.tokenProfile}`);
+    out.token_profile = prefs.tokenProfile;
   }
-
-  // Phase skips
   if (prefs.skipResearch) {
-    lines.push("phases:");
-    lines.push("  skip_research: true");
+    out.phases = { skip_research: true };
   }
 
-  // Defaults for wizard-generated files
-  lines.push("always_use_skills: []");
-  lines.push("prefer_skills: []");
-  lines.push("avoid_skills: []");
-  lines.push("skill_rules: []");
-
-  lines.push("---");
-  lines.push("");
-  lines.push("# GSD Project Preferences");
-  lines.push("");
-  lines.push("Generated by `/gsd init`. Edit directly or use `/gsd prefs project` to modify.");
-  lines.push("");
-  lines.push("See `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation.");
-  lines.push("");
+  return out;
+}
 
-  return lines.join("\n");
+function buildInitPreferencesBody(): string {
+  return [
+    "",
+    "# GSD Project Preferences",
+    "",
+    "Generated by `/gsd init`. Edit directly or use `/gsd prefs project` to modify.",
+    "",
+    "See `~/.gsd/agent/extensions/gsd/docs/preferences-reference.md` for full field documentation.",
+    "",
+  ].join("\n");
 }
 
 function buildContextSeed(signals: ProjectSignals): string | null {

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -169,7 +169,7 @@ function renderRoadmapMarkdown(milestone: MilestoneRow, slices: SliceRow[]): str
   lines.push("## Slices");
   lines.push("");
   for (const slice of slices) {
-    const done = slice.status === "complete" ? "x" : " ";
+    const done = isClosedStatus(slice.status) ? "x" : " ";
     const depends = `[${(slice.depends ?? []).join(",")}]`;
     lines.push(`- [${done}] **${slice.id}: ${slice.title}** \`risk:${slice.risk}\` \`depends:${depends}\``);
     lines.push(`  > After this: ${slice.demo}`);
@@ -496,7 +496,7 @@ export async function renderRoadmapCheckboxes(
   // Apply checkbox patches for each slice
   let updated = content;
   for (const slice of slices) {
-    const isDone = slice.status === "complete";
+    const isDone = isClosedStatus(slice.status);
     const sid = slice.id;
 
     if (isDone) {
@@ -821,19 +821,19 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
         const parsed = parseRoadmap(content);
 
         for (const slice of slices) {
-          const isCompleteInDb = slice.status === "complete";
+          const isCompleteInDb = isClosedStatus(slice.status);
           const roadmapSlice = parsed.slices.find((s: { id: string }) => s.id === slice.id);
           if (!roadmapSlice) continue;
 
           if (isCompleteInDb && !roadmapSlice.done) {
             stale.push({
               path: roadmapPath,
-              reason: `${slice.id} is complete in DB but unchecked in roadmap`,
+              reason: `${slice.id} is closed in DB but unchecked in roadmap`,
             });
           } else if (!isCompleteInDb && roadmapSlice.done) {
             stale.push({
               path: roadmapPath,
-              reason: `${slice.id} is not complete in DB but checked in roadmap`,
+              reason: `${slice.id} is not closed in DB but checked in roadmap`,
             });
           }
         }

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

@@ -90,6 +90,7 @@ export function classifyUnitPhase(unitType: string): MetricsPhase {
       return "discussion";
     case "plan-milestone":
     case "plan-slice":
+    case "refine-slice":
       return "planning";
     case "execute-task":
       return "execution";

package/src/resources/extensions/gsd/model-cost-table.ts

@@ -22,7 +22,8 @@ export interface ModelCostEntry {
  */
 export const BUNDLED_COST_TABLE: ModelCostEntry[] = [
   // Anthropic
-  { id: "claude-opus-4-6", inputPer1k: 0.015, outputPer1k: 0.075, updatedAt: "2025-03-15" },
+  { id: "claude-opus-4-6", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
+  { id: "claude-opus-4-7", inputPer1k: 0.005, outputPer1k: 0.025, updatedAt: "2026-04-16" },
   { id: "claude-sonnet-4-6", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },
   { id: "claude-haiku-4-5", inputPer1k: 0.0008, outputPer1k: 0.004, updatedAt: "2025-03-15" },
   { id: "claude-sonnet-4-5-20250514", inputPer1k: 0.003, outputPer1k: 0.015, updatedAt: "2025-03-15" },
@@ -55,6 +56,7 @@ export const BUNDLED_COST_TABLE: ModelCostEntry[] = [
   { id: "gpt-5.3-codex", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" },
   { id: "gpt-5.3-codex-spark", inputPer1k: 0.0003, outputPer1k: 0.0012, updatedAt: "2026-03-29" },
   { id: "gpt-5.4", inputPer1k: 0.005, outputPer1k: 0.02, updatedAt: "2026-03-29" },
+  { id: "gpt-5.4-mini", inputPer1k: 0.00075, outputPer1k: 0.0045, updatedAt: "2026-04-18" },
 
   // Google
   { id: "gemini-2.0-flash", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },

package/src/resources/extensions/gsd/model-router.ts

@@ -23,6 +23,14 @@ export interface DynamicRoutingConfig {
   budget_pressure?: boolean;       // default: true
   cross_provider?: boolean;        // default: true
   hooks?: boolean;                 // default: true
+  /**
+   * Opt into dynamic routing for flat-rate providers (e.g. claude-code,
+   * GitHub Copilot). Default false preserves the #3453 bypass that skips
+   * routing when the subscription makes per-request cost identical.
+   * Enable only when you want per-task model selection across a flat-rate
+   * subscription (e.g. haiku for research, opus for architecture). (#4386)
+   */
+  allow_flat_rate_providers?: boolean;
 }
 
 export interface RoutingDecision {
@@ -73,6 +81,7 @@ export const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
   "gpt-4.1-nano": "light",
   "gpt-5-mini": "light",
   "gpt-5-nano": "light",
+  "gpt-5.4-mini": "light",
   "gpt-5.1-codex-mini": "light",
   "gpt-5.3-codex-spark": "light",
   "gemini-2.0-flash": "light",
@@ -90,6 +99,7 @@ export const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
 
   // Heavy-tier models (most capable)
   "claude-opus-4-6": "heavy",
+  "claude-opus-4-7": "heavy",
   "claude-3-opus-latest": "heavy",
   "gpt-4-turbo": "heavy",
   "gpt-5": "heavy",
@@ -114,7 +124,8 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
   "claude-3-5-haiku-latest": 0.0008,
   "claude-sonnet-4-6": 0.003,
   "claude-sonnet-4-5-20250514": 0.003,
-  "claude-opus-4-6": 0.015,
+  "claude-opus-4-6": 0.005,
+  "claude-opus-4-7": 0.005,
   "gpt-4o-mini": 0.00015,
   "gpt-4o": 0.0025,
   "gpt-4.1": 0.002,
@@ -123,6 +134,7 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
   "gpt-5": 0.01,
   "gpt-5-mini": 0.0003,
   "gpt-5-nano": 0.0001,
+  "gpt-5.4-mini": 0.00075,
   "gpt-5-pro": 0.015,
   "gpt-5.1": 0.005,
   "gpt-5.1-codex-max": 0.003,
@@ -146,6 +158,7 @@ const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
 export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
   // ── Anthropic ──────────────────────────────────────────────────────────────
   "claude-opus-4-6":              { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
+  "claude-opus-4-7":              { coding: 95, debugging: 90, research: 85, reasoning: 95, speed: 30, longContext: 80, instruction: 90 },
   "claude-sonnet-4-6":            { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
   "claude-sonnet-4-5-20250514":   { coding: 85, debugging: 80, research: 75, reasoning: 80, speed: 60, longContext: 75, instruction: 85 },
   "claude-3-5-sonnet-latest":     { coding: 82, debugging: 78, research: 72, reasoning: 78, speed: 62, longContext: 70, instruction: 82 },
@@ -164,6 +177,7 @@ export const MODEL_CAPABILITY_PROFILES: Record<string, ModelCapabilities> = {
   "gpt-5":                        { coding: 92, debugging: 88, research: 85, reasoning: 92, speed: 40, longContext: 85, instruction: 90 },
   "gpt-5-mini":                   { coding: 62, debugging: 52, research: 48, reasoning: 52, speed: 88, longContext: 52, instruction: 74 },
   "gpt-5-nano":                   { coding: 42, debugging: 32, research: 28, reasoning: 32, speed: 95, longContext: 32, instruction: 62 },
+  "gpt-5.4-mini":                 { coding: 70, debugging: 60, research: 55, reasoning: 60, speed: 84, longContext: 60, instruction: 78 },
   "gpt-5-pro":                    { coding: 94, debugging: 90, research: 88, reasoning: 94, speed: 35, longContext: 88, instruction: 92 },
   "gpt-5.1":                      { coding: 93, debugging: 89, research: 86, reasoning: 93, speed: 42, longContext: 86, instruction: 91 },
   "gpt-5.1-codex-max":            { coding: 90, debugging: 85, research: 70, reasoning: 85, speed: 55, longContext: 75, instruction: 85 },

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

@@ -6,7 +6,7 @@
 // execSync calls because git2 credential handling is too complex.
 
 import { execSync, execFileSync } from "node:child_process";
-import { existsSync, readFileSync, unlinkSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, unlinkSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { GSDError, GSD_GIT_ERROR } from "./errors.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
@@ -690,6 +690,134 @@ export function nativeAddTracked(basePath: string): void {
   gitFileExec(basePath, ["add", "-u"]);
 }
 
+function isDotGsdIgnored(basePath: string): boolean {
+  for (const path of [".gsd", ".gsd/"]) {
+    try {
+      execFileSync("git", ["check-ignore", "-q", path], {
+        cwd: basePath,
+        stdio: "pipe",
+        env: GIT_NO_PROMPT_ENV,
+      });
+      return true;
+    } catch {
+      // exit 1 means this form is not ignored; try the next variant
+    }
+  }
+  return false;
+}
+
+/**
+ * Determine whether the project opts out of GSD-managed `.gitignore` via
+ * `git.manage_gitignore: false` in `.gsd/PREFERENCES.md`. Uses a minimal
+ * inline parser to avoid importing the full preferences module (which would
+ * introduce a circular dependency back into this low-level bridge).
+ *
+ * Returns true when management is disabled. Any parse failure or missing
+ * file returns false (default: GSD may manage `.gitignore`).
+ */
+function isGitignoreManagementDisabled(basePath: string): boolean {
+  const prefsPath = join(basePath, ".gsd", "PREFERENCES.md");
+  if (!existsSync(prefsPath)) return false;
+  try {
+    const content = readFileSync(prefsPath, "utf-8");
+    // Look for `manage_gitignore: false` under a `git:` block. The preference
+    // is indented; a loose regex is sufficient since we only care about the
+    // explicit opt-out case.
+    return /^\s*manage_gitignore\s*:\s*false\s*$/m.test(content);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Self-heal path for the symlinked-`.gsd` staging failure: append `.gsd` to
+ * `.gitignore` so subsequent `git add -A` calls succeed without the symlink
+ * pathspec error. Honors the `git.manage_gitignore: false` opt-out.
+ *
+ * Returns true when `.gitignore` now contains an entry covering `.gsd`
+ * (either pre-existing or newly appended). Returns false when the opt-out
+ * is set or the write fails.
+ */
+function trySelfHealGsdGitignore(basePath: string): boolean {
+  if (isGitignoreManagementDisabled(basePath)) return false;
+
+  const gitignorePath = join(basePath, ".gitignore");
+  try {
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+    const lines = new Set(
+      existing.split("\n").map(l => l.trim()).filter(l => l && !l.startsWith("#")),
+    );
+    if (lines.has(".gsd") || lines.has(".gsd/")) return true;
+
+    const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    const block = `${prefix}\n# ── GSD self-heal: .gsd is a symlink to external state ──\n.gsd\n`;
+    writeFileSync(gitignorePath, existing + block, "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Stage untracked files individually while skipping anything under `.gsd`.
+ * Used as a last-resort when `.gsd` is a symlink, not gitignored, and
+ * `git.manage_gitignore: false` forbids the self-heal path. Protects user
+ * work by never silently dropping new real files.
+ */
+function stageUntrackedExcludingDotGsd(basePath: string): void {
+  // Stage tracked modifications first. `git add -u` never fails on pathspec
+  // issues because it doesn't walk untracked trees.
+  gitFileExec(basePath, ["add", "-u"]);
+
+  // Enumerate untracked paths via porcelain output. `?? ` prefix marks
+  // untracked files (status respects `.gitignore`).
+  const status = gitFileExec(basePath, ["status", "--porcelain=v1", "-z"], true);
+  if (!status) return;
+
+  const untracked: string[] = [];
+  for (const entry of status.split("\0")) {
+    if (!entry) continue;
+    // Porcelain format: "XY path" where XY is the 2-char status code.
+    if (entry.length < 4) continue;
+    const code = entry.slice(0, 2);
+    const path = entry.slice(3);
+    if (code !== "??") continue;
+    // Skip GSD runtime artifacts. Under `manage_gitignore: false` the user
+    // may not have these in `.gitignore`, so we filter explicitly to avoid
+    // committing transient state (.gsd external link, migration lock,
+    // background shell scratch dir).
+    if (path === ".gsd" || path.startsWith(".gsd/")) continue;
+    if (path === ".gsd-id" || path === ".gsd.migrating") continue;
+    if (path === ".bg-shell" || path.startsWith(".bg-shell/")) continue;
+    untracked.push(path);
+  }
+
+  if (untracked.length === 0) return;
+  // Stage in chunks to avoid exceeding ARG_MAX on large change sets.
+  const CHUNK = 200;
+  for (let i = 0; i < untracked.length; i += CHUNK) {
+    gitFileExec(basePath, ["add", "--", ...untracked.slice(i, i + CHUNK)]);
+  }
+}
+
+/**
+ * Handle `nativeAddAllWithExclusions` failing with "beyond a symbolic link"
+ * when `.gsd` is a symlink. Self-heals by adding `.gsd` to `.gitignore`, or
+ * falls back to explicit per-file staging so user work is never dropped.
+ */
+function fallbackStageWithSymlinkedDotGsd(basePath: string): void {
+  if (isDotGsdIgnored(basePath)) {
+    gitFileExec(basePath, ["add", "-A"]);
+    return;
+  }
+  if (trySelfHealGsdGitignore(basePath)) {
+    gitFileExec(basePath, ["add", "-A"]);
+    return;
+  }
+  // `manage_gitignore: false` — protect work by staging files explicitly.
+  stageUntrackedExcludingDotGsd(basePath);
+}
+
 /**
  * Stage all files with pathspec exclusions (git add -A -- ':!pattern' ...).
  * Excluded paths are never hashed by git, preventing hangs on large
@@ -724,12 +852,12 @@ export function nativeAddAllWithExclusions(basePath: string, exclusions: readonl
       return;
     }
     // When .gsd is a symlink, git rejects `:!.gsd/...` pathspecs with
-    // "beyond a symbolic link". Fall back to `git add -u` which only
-    // stages changes to already-tracked files — O(tracked) not O(filesystem).
-    // Using `git add -A` here would traverse the entire working tree,
-    // hanging indefinitely on repos with large untracked data dirs. (#1977)
+    // "beyond a symbolic link". Hand off to the self-heal fallback which
+    // either adds `.gsd` to `.gitignore` and retries `git add -A`, or stages
+    // real files explicitly when `git.manage_gitignore: false` forbids the
+    // self-heal path. Either way, user work is protected from silent drops.
     if (stderr.includes("beyond a symbolic link")) {
-      gitFileExec(basePath, ["add", "-u"]);
+      fallbackStageWithSymlinkedDotGsd(basePath);
       return;
     }
     throw new GSDError(GSD_GIT_ERROR, `git add -A with exclusions failed in ${basePath}: ${getErrorMessage(err)}`);