gsd-pi 2.75.0 → 2.76.0

package/dist/resources/extensions/gsd/memory-store.js

@@ -2,7 +2,8 @@
 //
 // Storage layer for auto-learned project memories. Follows context-store.ts patterns.
 // All functions degrade gracefully: return empty results when DB unavailable, never throw.
-import { isDbAvailable, _getAdapter, transaction, insertMemoryRow, rewriteMemoryId, updateMemoryContentRow, incrementMemoryHitCount, supersedeMemoryRow, markMemoryUnitProcessed, decayMemoriesBefore, supersedeLowestRankedMemories, } from './gsd-db.js';
+import { isDbAvailable, _getAdapter, transaction, insertMemoryRow, rewriteMemoryId, updateMemoryContentRow, incrementMemoryHitCount, supersedeMemoryRow, markMemoryUnitProcessed, decayMemoriesBefore, supersedeLowestRankedMemories, deleteMemoryEmbedding, deleteMemoryRelationsFor, } from './gsd-db.js';
+import { createMemoryRelation, isValidRelation } from './memory-relations.js';
 // ─── Category Display Order ─────────────────────────────────────────────────
 const CATEGORY_PRIORITY = {
     gotcha: 0,
@@ -26,8 +27,21 @@ function rowToMemory(row) {
         updated_at: row['updated_at'],
         superseded_by: row['superseded_by'] ?? null,
         hit_count: row['hit_count'],
+        scope: row['scope'] ?? 'project',
+        tags: parseTags(row['tags']),
     };
 }
+function parseTags(raw) {
+    if (typeof raw !== 'string' || raw.length === 0)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed.filter((t) => typeof t === 'string') : [];
+    }
+    catch {
+        return [];
+    }
+}
 // ─── Query Functions ────────────────────────────────────────────────────────
 /**
  * Get all memories where superseded_by IS NULL.
@@ -68,6 +82,245 @@ export function getActiveMemoriesRanked(limit = 30) {
         return [];
     }
 }
+export function queryMemoriesRanked(opts) {
+    if (!isDbAvailable())
+        return [];
+    const adapter = _getAdapter();
+    if (!adapter)
+        return [];
+    const k = clampLimit(opts.k, 10);
+    const rrfK = opts.rrfK ?? 60;
+    const activeClause = opts.include_superseded === true ? '' : 'WHERE superseded_by IS NULL';
+    const trimmedQuery = (opts.query ?? '').trim();
+    // 1) Keyword hits — try FTS5 first, fall back to LIKE when unavailable.
+    const keywordHits = trimmedQuery ? keywordSearch(adapter, trimmedQuery, activeClause, 50) : [];
+    // 2) Semantic hits — cosine over memory_embeddings. Requires opts.queryVector.
+    const semanticHits = opts.queryVector
+        ? semanticSearch(adapter, opts.queryVector, activeClause, 50)
+        : [];
+    if (keywordHits.length === 0 && semanticHits.length === 0 && !trimmedQuery) {
+        // No query at all — fall back to the existing ranked-by-score listing.
+        return getActiveMemoriesRanked(k).map((memory) => ({
+            memory,
+            score: memory.confidence * (1 + memory.hit_count * 0.1),
+            keywordRank: null,
+            semanticRank: null,
+            confidenceBoost: memory.confidence * (1 + memory.hit_count * 0.1),
+            reason: 'ranked',
+        })).filter((hit) => passesFilters(hit.memory, opts));
+    }
+    // 3) Reciprocal rank fusion — each hit contributes 1/(rrfK + rank).
+    const fused = new Map();
+    for (let i = 0; i < keywordHits.length; i++) {
+        const hit = keywordHits[i];
+        const existing = fused.get(hit.id);
+        const rrf = 1 / (rrfK + i + 1);
+        if (existing) {
+            existing.kwRank = i + 1;
+            existing.score += rrf;
+        }
+        else {
+            fused.set(hit.id, { memory: hit, kwRank: i + 1, semRank: null, score: rrf });
+        }
+    }
+    for (let i = 0; i < semanticHits.length; i++) {
+        const hit = semanticHits[i];
+        const existing = fused.get(hit.id);
+        const rrf = 1 / (rrfK + i + 1);
+        if (existing) {
+            existing.semRank = i + 1;
+            existing.score += rrf;
+        }
+        else {
+            fused.set(hit.id, { memory: hit, kwRank: null, semRank: i + 1, score: rrf });
+        }
+    }
+    // 4) Apply filters + confidence boost, then sort.
+    const ranked = [];
+    for (const entry of fused.values()) {
+        if (!passesFilters(entry.memory, opts))
+            continue;
+        const boost = entry.memory.confidence * (1 + entry.memory.hit_count * 0.1);
+        const reason = entry.kwRank != null && entry.semRank != null
+            ? 'both'
+            : entry.kwRank != null
+                ? 'keyword'
+                : 'semantic';
+        ranked.push({
+            memory: entry.memory,
+            score: entry.score * boost,
+            keywordRank: entry.kwRank,
+            semanticRank: entry.semRank,
+            confidenceBoost: boost,
+            reason,
+        });
+    }
+    ranked.sort((a, b) => b.score - a.score);
+    return ranked.slice(0, k);
+}
+function clampLimit(value, fallback) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return fallback;
+    if (value < 1)
+        return 1;
+    if (value > 100)
+        return 100;
+    return Math.floor(value);
+}
+function passesFilters(memory, filters) {
+    if (filters.category && memory.category.toLowerCase() !== filters.category.toLowerCase())
+        return false;
+    if (filters.scope && memory.scope !== filters.scope)
+        return false;
+    if (filters.tag) {
+        const needle = filters.tag.toLowerCase();
+        if (!memory.tags.map((t) => t.toLowerCase()).includes(needle))
+            return false;
+    }
+    return true;
+}
+function keywordSearch(adapter, rawQuery, activeClause, limit) {
+    const ftsAvailable = isFtsAvailable(adapter);
+    if (ftsAvailable) {
+        try {
+            const matchExpr = toFtsMatchExpr(rawQuery);
+            if (!matchExpr)
+                return [];
+            const activePart = activeClause ? `AND m.${activeClause.replace(/^WHERE\s+/i, '')}` : '';
+            const rows = adapter.prepare(`SELECT m.*
+         FROM memories_fts f
+         JOIN memories m ON m.seq = f.rowid
+         WHERE memories_fts MATCH :match
+         ${activePart}
+         ORDER BY bm25(memories_fts)
+         LIMIT :limit`).all({ ':match': matchExpr, ':limit': limit });
+            return rows.map(rowToMemory);
+        }
+        catch {
+            // fall through to LIKE
+        }
+    }
+    // LIKE fallback — scans the candidate pool.
+    const terms = rawQuery
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/)
+        .filter((t) => t.length >= 2);
+    if (terms.length === 0)
+        return [];
+    const rows = adapter.prepare(`SELECT * FROM memories ${activeClause}`).all();
+    const scored = [];
+    for (const row of rows) {
+        const memory = rowToMemory(row);
+        const lower = memory.content.toLowerCase();
+        let score = 0;
+        for (const term of terms) {
+            const idx = lower.indexOf(term);
+            if (idx === -1)
+                continue;
+            score += 1 + (term.length >= 5 ? 0.5 : 0);
+        }
+        if (score > 0)
+            scored.push({ memory, score });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit).map((s) => s.memory);
+}
+function isFtsAvailable(adapter) {
+    try {
+        const row = adapter
+            .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='memories_fts'")
+            .get();
+        return !!row;
+    }
+    catch {
+        return false;
+    }
+}
+function toFtsMatchExpr(query) {
+    // Build a tolerant AND expression: quote each bare term with a trailing *.
+    const tokens = query
+        .toLowerCase()
+        .split(/[^a-z0-9_]+/)
+        .filter((t) => t.length >= 2)
+        .slice(0, 8);
+    if (tokens.length === 0)
+        return null;
+    return tokens.map((t) => `"${t.replace(/"/g, '""')}"*`).join(' OR ');
+}
+function semanticSearch(adapter, queryVector, activeClause, limit) {
+    try {
+        const rows = adapter
+            .prepare(`SELECT m.*, e.vector as embedding_vector, e.dim as embedding_dim
+         FROM memories m
+         JOIN memory_embeddings e ON e.memory_id = m.id
+         ${activeClause}`)
+            .all();
+        const scored = [];
+        for (const row of rows) {
+            const dim = row['embedding_dim'];
+            if (dim !== queryVector.length)
+                continue;
+            const vector = unpackVector(row['embedding_vector'], dim);
+            if (!vector)
+                continue;
+            const sim = cosine(queryVector, vector);
+            if (sim <= 0)
+                continue;
+            scored.push({ memory: rowToMemory(row), sim });
+        }
+        scored.sort((a, b) => b.sim - a.sim);
+        return scored.slice(0, limit).map((s) => s.memory);
+    }
+    catch {
+        return [];
+    }
+}
+function unpackVector(blob, dim) {
+    if (!blob)
+        return null;
+    try {
+        let view = null;
+        if (blob instanceof Float32Array)
+            return blob;
+        if (blob instanceof Uint8Array)
+            view = blob;
+        else if (blob instanceof ArrayBuffer)
+            view = new Uint8Array(blob);
+        else if (blob.buffer && blob.byteLength != null) {
+            const buf = blob;
+            view = new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        }
+        else if (Array.isArray(blob)) {
+            return new Float32Array(blob);
+        }
+        if (!view || view.byteLength % 4 !== 0)
+            return null;
+        const aligned = new ArrayBuffer(view.byteLength);
+        new Uint8Array(aligned).set(view);
+        const f32 = new Float32Array(aligned);
+        return f32.length === dim ? f32 : null;
+    }
+    catch {
+        return null;
+    }
+}
+function cosine(a, b) {
+    if (a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let na = 0;
+    let nb = 0;
+    for (let i = 0; i < a.length; i++) {
+        const x = a[i];
+        const y = b[i];
+        dot += x * y;
+        na += x * x;
+        nb += y * y;
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
 /**
  * Generate the next memory ID: MEM + zero-padded 3-digit from MAX(seq).
  * Returns MEM001 if no memories exist.
@@ -121,6 +374,8 @@ export function createMemory(fields) {
             sourceUnitId: fields.source_unit_id ?? null,
             createdAt: now,
             updatedAt: now,
+            scope: fields.scope ?? 'project',
+            tags: fields.tags ?? [],
         });
         // Derive the real ID from the assigned seq (SELECT is still fine via adapter)
         const row = adapter.prepare('SELECT seq FROM memories WHERE id = :id').get({ ':id': placeholder });
@@ -213,29 +468,34 @@ export function markUnitProcessed(unitKey, activityFile) {
 /**
  * Reduce confidence for memories not updated within the last N processed units.
  * "Stale" = updated_at is older than the Nth most recent processed_at.
+ * Returns the number of decayed memory IDs for observability.
  */
 export function decayStaleMemories(thresholdUnits = 20) {
     if (!isDbAvailable())
-        return;
+        return [];
     const adapter = _getAdapter();
     if (!adapter)
-        return;
+        return [];
     try {
         // Find the timestamp of the Nth most recent processed unit (read-only SELECT)
         const row = adapter.prepare(`SELECT processed_at FROM memory_processed_units
        ORDER BY processed_at DESC
        LIMIT 1 OFFSET :offset`).get({ ':offset': thresholdUnits - 1 });
         if (!row)
-            return; // not enough processed units yet
+            return []; // not enough processed units yet
         const cutoff = row['processed_at'];
+        const affected = adapter.prepare(`SELECT id FROM memories
+       WHERE superseded_by IS NULL AND updated_at < :cutoff AND confidence > 0.1`).all({ ':cutoff': cutoff }).map((r) => r['id']);
         decayMemoriesBefore(cutoff, new Date().toISOString());
+        return affected;
     }
     catch {
-        // non-fatal
+        return [];
     }
 }
 /**
- * Supersede lowest-ranked memories when count exceeds cap.
+ * Supersede lowest-ranked memories when count exceeds cap. Cascades to the
+ * embedding and relation rows so those tables don't grow unboundedly.
  */
 export function enforceMemoryCap(max = 50) {
     if (!isDbAvailable())
@@ -249,7 +509,24 @@ export function enforceMemoryCap(max = 50) {
         if (count <= max)
             return;
         const excess = count - max;
+        // Capture the about-to-be-superseded IDs first so we can cascade cleanup.
+        const victims = adapter.prepare(`SELECT id FROM memories
+       WHERE superseded_by IS NULL
+       ORDER BY (confidence * (1.0 + hit_count * 0.1)) ASC
+       LIMIT :limit`).all({ ':limit': excess }).map((row) => row['id']);
         supersedeLowestRankedMemories(excess, new Date().toISOString());
+        if (victims.length === 0)
+            return;
+        for (const id of victims) {
+            try {
+                deleteMemoryEmbedding(id);
+            }
+            catch { /* non-fatal */ }
+            try {
+                deleteMemoryRelationsFor(id);
+            }
+            catch { /* non-fatal */ }
+        }
     }
     catch {
         // non-fatal
@@ -274,6 +551,8 @@ export function applyMemoryActions(actions, unitType, unitId) {
                             confidence: action.confidence,
                             source_unit_type: unitType,
                             source_unit_id: unitId,
+                            scope: action.scope,
+                            tags: action.tags,
                         });
                         break;
                     case 'UPDATE':
@@ -285,6 +564,9 @@ export function applyMemoryActions(actions, unitType, unitId) {
                     case 'SUPERSEDE':
                         supersedeMemory(action.id, action.superseded_by);
                         break;
+                    case 'LINK':
+                        applyLinkAction(action);
+                        break;
                 }
             }
             enforceMemoryCap();
@@ -294,6 +576,17 @@ export function applyMemoryActions(actions, unitType, unitId) {
         // non-fatal — transaction will have rolled back
     }
 }
+// ─── LINK action ────────────────────────────────────────────────────────────
+function applyLinkAction(action) {
+    try {
+        if (!isValidRelation(action.rel))
+            return;
+        createMemoryRelation(action.from, action.to, action.rel, action.confidence);
+    }
+    catch {
+        // Link failures should never break memory extraction.
+    }
+}
 // ─── Prompt Formatting ──────────────────────────────────────────────────────
 /**
  * Format memories as categorized markdown for system prompt injection.

package/dist/resources/extensions/gsd/metrics.js

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

package/dist/resources/extensions/gsd/model-cost-table.js

@@ -10,7 +10,8 @@
  */
 export const BUNDLED_COST_TABLE = [
     // 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" },
@@ -41,6 +42,7 @@ export const BUNDLED_COST_TABLE = [
     { 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" },
     { id: "gemini-flash-2.0", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },

package/dist/resources/extensions/gsd/model-router.js

@@ -17,6 +17,7 @@ export const MODEL_CAPABILITY_TIER = {
     "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",
@@ -32,6 +33,7 @@ export const MODEL_CAPABILITY_TIER = {
     "deepseek-chat": "standard",
     // 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",
@@ -54,7 +56,8 @@ const MODEL_COST_PER_1K_INPUT = {
     "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,
@@ -63,6 +66,7 @@ const MODEL_COST_PER_1K_INPUT = {
     "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,
@@ -84,6 +88,7 @@ const MODEL_COST_PER_1K_INPUT = {
 export const MODEL_CAPABILITY_PROFILES = {
     // ── 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 },
@@ -101,6 +106,7 @@ export const MODEL_CAPABILITY_PROFILES = {
     "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 },
@@ -183,8 +189,9 @@ export function computeTaskRequirements(unitType, metadata) {
  */
 export function scoreEligibleModels(eligibleModelIds, requirements, capabilityOverrides) {
     const scored = eligibleModelIds.map(modelId => {
-        const builtin = MODEL_CAPABILITY_PROFILES[modelId];
-        const override = capabilityOverrides?.[modelId];
+        const bareId = bareModelId(modelId);
+        const builtin = MODEL_CAPABILITY_PROFILES[bareId];
+        const override = capabilityOverrides?.[modelId] ?? capabilityOverrides?.[bareId];
         const profile = builtin
             ? override ? { ...builtin, ...override } : builtin
             : { coding: 50, debugging: 50, research: 50, reasoning: 50, speed: 50, longContext: 50, instruction: 50 };
@@ -394,7 +401,7 @@ export function defaultRoutingConfig() {
 // ─── Internal ────────────────────────────────────────────────────────────────
 function getModelTier(modelId) {
     // Strip provider prefix if present
-    const bareId = modelId.includes("/") ? modelId.split("/").pop() : modelId;
+    const bareId = bareModelId(modelId);
     // Check exact match first
     if (MODEL_CAPABILITY_TIER[bareId])
         return MODEL_CAPABILITY_TIER[bareId];
@@ -408,7 +415,7 @@ function getModelTier(modelId) {
 }
 /** Check if a model ID has a known capability tier mapping. (#2192) */
 function isKnownModel(modelId) {
-    const bareId = modelId.includes("/") ? modelId.split("/").pop() : modelId;
+    const bareId = bareModelId(modelId);
     if (MODEL_CAPABILITY_TIER[bareId])
         return true;
     for (const knownId of Object.keys(MODEL_CAPABILITY_TIER)) {
@@ -418,7 +425,7 @@ function isKnownModel(modelId) {
     return false;
 }
 function getModelCost(modelId) {
-    const bareId = modelId.includes("/") ? modelId.split("/").pop() : modelId;
+    const bareId = bareModelId(modelId);
     if (MODEL_COST_PER_1K_INPUT[bareId] !== undefined) {
         return MODEL_COST_PER_1K_INPUT[bareId];
     }
@@ -430,6 +437,9 @@ function getModelCost(modelId) {
     // Unknown cost — assume expensive to avoid routing to unknown cheap models
     return 999;
 }
+function bareModelId(modelId) {
+    return modelId.includes("/") ? modelId.split("/").pop() : modelId;
+}
 // ─── Tool Compatibility Filter (ADR-005 Phase 3) ───────────────────────────
 /**
  * Check if a tool is compatible with a provider's capabilities.

package/dist/resources/extensions/gsd/native-git-bridge.js

@@ -5,6 +5,8 @@
 // Both READ and WRITE operations are native — push operations remain as
 // execSync calls because git2 credential handling is too complex.
 import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, 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";
 import { getErrorMessage } from "./error-utils.js";
@@ -534,6 +536,136 @@ export function nativeAddAll(basePath) {
 export function nativeAddTracked(basePath) {
     gitFileExec(basePath, ["add", "-u"]);
 }
+function isDotGsdIgnored(basePath) {
+    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) {
+    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) {
+    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) {
+    // 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 = [];
+    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) {
+    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
@@ -569,12 +701,12 @@ export function nativeAddAllWithExclusions(basePath, exclusions) {
             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)}`);