gsd-pi 2.34.0 → 2.35.0-dev.34ce717

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

@@ -8,6 +8,7 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { COMPLETION_TRANSITION_CODES } from "./doctor-types.js";
 import { checkGitHealth, checkRuntimeHealth } from "./doctor-checks.js";
 import { checkEnvironmentHealth } from "./doctor-environment.js";
+import { runProviderChecks } from "./doctor-providers.js";
 export { summarizeDoctorIssues, filterDoctorIssues, formatDoctorReport, formatDoctorIssuesForPrompt } from "./doctor-format.js";
 export { runEnvironmentChecks, runFullEnvironmentChecks, formatEnvironmentReport } from "./doctor-environment.js";
 export { computeProgressScore, computeProgressScoreWithContext, formatProgressLine, formatProgressReport } from "./progress-score.js";
@@ -373,6 +374,41 @@ export async function runGSDDoctor(basePath, options) {
     const requirementsContent = await loadFile(requirementsPath);
     issues.push(...auditRequirements(requirementsContent));
     const state = await deriveState(basePath);
+    // Provider / auth health checks — only relevant when there is active work to dispatch.
+    // Skipped for idle projects (no active milestone) to avoid noise in environments
+    // where CI/test runners have no API key configured.
+    if (state.activeMilestone) {
+        try {
+            const providerResults = runProviderChecks();
+            for (const result of providerResults) {
+                if (!result.required)
+                    continue;
+                if (result.status === "error") {
+                    issues.push({
+                        severity: "warning",
+                        code: "provider_key_missing",
+                        scope: "project",
+                        unitId: "project",
+                        message: result.message + (result.detail ? ` — ${result.detail}` : ""),
+                        fixable: false,
+                    });
+                }
+                else if (result.status === "warning") {
+                    issues.push({
+                        severity: "warning",
+                        code: "provider_key_backedoff",
+                        scope: "project",
+                        unitId: "project",
+                        message: result.message + (result.detail ? ` — ${result.detail}` : ""),
+                        fixable: false,
+                    });
+                }
+            }
+        }
+        catch {
+            // Non-fatal — provider check failure should not block other checks
+        }
+    }
     for (const milestone of state.registry) {
         const milestoneId = milestone.id;
         const milestonePath = resolveMilestonePath(basePath, milestoneId);

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

@@ -509,7 +509,8 @@ export async function loadFile(path) {
         return await fs.readFile(path, 'utf-8');
     }
     catch (err) {
-        if (err.code === 'ENOENT')
+        const code = err.code;
+        if (code === 'ENOENT' || code === 'EISDIR')
             return null;
         throw err;
     }
@@ -704,7 +705,7 @@ export async function inlinePriorMilestoneSummary(mid, base) {
  * Returns `null` when no manifest file exists (path resolution failure or
  * file not on disk) - callers can distinguish "no manifest" from "empty manifest".
  */
-export async function getManifestStatus(base, milestoneId) {
+export async function getManifestStatus(base, milestoneId, projectRoot) {
     const resolvedPath = resolveMilestoneFile(base, milestoneId, 'SECRETS');
     if (!resolvedPath)
         return null;
@@ -713,8 +714,16 @@ export async function getManifestStatus(base, milestoneId) {
         return null;
     const manifest = parseSecretsManifest(content);
     const keys = manifest.entries.map(e => e.key);
+    // Check both the base path .env AND the project root .env (#1387).
+    // In worktree mode, base is the worktree path which may not have .env.
+    // The project root's .env is where the user actually defined their keys.
     const existingKeys = await checkExistingEnvKeys(keys, resolve(base, '.env'));
     const existingSet = new Set(existingKeys);
+    if (projectRoot && projectRoot !== base) {
+        const rootKeys = await checkExistingEnvKeys(keys, resolve(projectRoot, '.env'));
+        for (const k of rootKeys)
+            existingSet.add(k);
+    }
     const result = {
         pending: [],
         collected: [],

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

@@ -6,8 +6,8 @@
  * Both idempotent — non-destructive if already present.
  */
 import { join } from "node:path";
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { nativeRmCached } from "./native-git-bridge.js";
+import { existsSync, lstatSync, readFileSync, writeFileSync } from "node:fs";
+import { nativeRmCached, nativeLsFiles } from "./native-git-bridge.js";
 import { gsdRoot } from "./paths.js";
 /**
  * GSD runtime patterns for git index cleanup.
@@ -67,12 +67,48 @@ const BASELINE_PATTERNS = [
     "tmp/",
 ];
 /**
- * Ensure basePath/.gitignore contains a blanket `.gsd/` ignore.
- * Creates the file if missing; appends `.gsd/` if not present.
+ * Check whether `.gsd/` contains files tracked by git.
+ * If so, the project intentionally keeps `.gsd/` in version control
+ * and we must NOT add `.gsd` to `.gitignore` or attempt migration.
+ *
+ * Returns true if git tracks at least one file under `.gsd/`.
+ * Returns false (safe to ignore) if:
+ *   - Not a git repo
+ *   - `.gsd/` is a symlink (external state, should be ignored)
+ *   - `.gsd/` doesn't exist
+ *   - No tracked files found under `.gsd/`
+ */
+export function hasGitTrackedGsdFiles(basePath) {
+    const localGsd = join(basePath, ".gsd");
+    // If .gsd doesn't exist or is already a symlink, no tracked files concern
+    if (!existsSync(localGsd))
+        return false;
+    try {
+        if (lstatSync(localGsd).isSymbolicLink())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    // Check if git tracks any files under .gsd/
+    try {
+        const tracked = nativeLsFiles(basePath, ".gsd");
+        return tracked.length > 0;
+    }
+    catch {
+        // Not a git repo or git not available — safe to proceed
+        return false;
+    }
+}
+/**
+ * Ensure basePath/.gitignore contains baseline ignore patterns.
+ * Creates the file if missing; appends missing patterns.
  * Returns true if the file was created or modified, false if already complete.
  *
- * `.gsd/` state is managed externally (symlinked to `~/.gsd/projects/<hash>/`),
- * so the entire directory is always gitignored.
+ * **Safety check:** If `.gsd/` contains git-tracked files (i.e., the project
+ * intentionally keeps `.gsd/` in version control), the `.gsd` ignore pattern
+ * is excluded to prevent data loss. Only the `.gsd` pattern is affected —
+ * all other baseline patterns are still applied normally.
  */
 export function ensureGitignore(basePath, options) {
     // If manage_gitignore is explicitly false, do not touch .gitignore at all
@@ -88,8 +124,14 @@ export function ensureGitignore(basePath, options) {
         .split("\n")
         .map((l) => l.trim())
         .filter((l) => l && !l.startsWith("#")));
+    // Determine which patterns to apply. If .gsd/ has tracked files,
+    // exclude the ".gsd" pattern to prevent deleting tracked state.
+    const gsdIsTracked = hasGitTrackedGsdFiles(basePath);
+    const patternsToApply = gsdIsTracked
+        ? BASELINE_PATTERNS.filter((p) => p !== ".gsd")
+        : BASELINE_PATTERNS;
     // Find patterns not yet present
-    const missing = BASELINE_PATTERNS.filter((p) => !existingLines.has(p));
+    const missing = patternsToApply.filter((p) => !existingLines.has(p));
     if (missing.length === 0)
         return false;
     // Build the block to append
@@ -111,6 +153,11 @@ export function ensureGitignore(basePath, options) {
  * already in the index even after .gitignore is updated.
  *
  * Only removes from the index (`--cached`), never from disk. Idempotent.
+ *
+ * Note: These are strictly runtime/ephemeral paths (activity logs, lock files,
+ * metrics, STATE.md). They are always safe to untrack, even when the project
+ * intentionally keeps other `.gsd/` files (like PROJECT.md, milestones/) in
+ * version control.
  */
 export function untrackRuntimeFiles(basePath) {
     const runtimePaths = GSD_RUNTIME_PATTERNS;

package/dist/resources/extensions/gsd/guided-flow.js

@@ -17,6 +17,7 @@ import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
 import { join } from "node:path";
 import { readFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
 import { nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -154,7 +155,7 @@ function parseMilestoneSequenceFromProject(content) {
  * This is the only way the wizard triggers work — everything else is the LLM's job.
  */
 function dispatchWorkflow(pi, note, customType = "gsd-run") {
-    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".pi", "GSD-WORKFLOW.md");
+    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(process.env.HOME ?? "~", ".gsd", "agent", "GSD-WORKFLOW.md");
     const workflow = readFileSync(workflowPath, "utf-8");
     pi.sendMessage({
         customType,
@@ -426,7 +427,12 @@ export async function showDiscuss(ctx, pi, basePath) {
         // If all pending slices are discussed, notify and exit instead of looping
         const allDiscussed = pendingSlices.every(s => discussedMap.get(s.id));
         if (allDiscussed) {
-            ctx.ui.notify(`All ${pendingSlices.length} slices discussed. Run /gsd to start planning.`, "info");
+            const lockData = readSessionLockData(basePath);
+            const remoteAutoRunning = lockData && lockData.pid !== process.pid && isSessionLockProcessAlive(lockData);
+            const nextStep = remoteAutoRunning
+                ? "Auto-mode is already running — use /gsd status to check progress."
+                : "Run /gsd to start planning.";
+            ctx.ui.notify(`All ${pendingSlices.length} slices discussed. ${nextStep}`, "info");
             return;
         }
         // Find the first undiscussed slice to recommend
@@ -661,9 +667,11 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     untrackRuntimeFiles(basePath);
     // ── Self-heal stale runtime records from crashed auto-mode sessions ──
     selfHealRuntimeRecords(basePath, ctx);
-    // Check for crash from previous auto-mode session
+    // Check for crash from previous auto-mode session.
+    // Skip if the lock was written by the current process — acquireSessionLock()
+    // writes to the same file, so we'd always false-positive (#1398).
     const crashLock = readCrashLock(basePath);
-    if (crashLock) {
+    if (crashLock && crashLock.pid !== process.pid) {
         clearLock(basePath);
         // Bootstrap crash with zero completed units = no work was lost.
         // Auto-discard instead of prompting the user — this commonly happens

package/dist/resources/extensions/gsd/health-widget-core.js

@@ -0,0 +1,96 @@
+/**
+ * Pure GSD health widget logic.
+ *
+ * Separates project-state detection and line rendering from the widget's
+ * runtime integrations so the regressions can be tested directly.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { gsdRoot } from "./paths.js";
+import { join } from "node:path";
+export function detectHealthWidgetProjectState(basePath) {
+    const root = gsdRoot(basePath);
+    if (!existsSync(root))
+        return "none";
+    // Lightweight milestone count — avoids the full detectProjectState() scan
+    // (CI markers, Makefile targets, etc.) that is unnecessary on the 60s refresh.
+    try {
+        const milestonesDir = join(root, "milestones");
+        if (existsSync(milestonesDir)) {
+            const entries = readdirSync(milestonesDir, { withFileTypes: true });
+            if (entries.some(e => e.isDirectory()))
+                return "active";
+        }
+    }
+    catch { /* non-fatal */ }
+    return "initialized";
+}
+function formatCost(n) {
+    return n >= 1 ? `$${n.toFixed(2)}` : `${(n * 100).toFixed(1)}¢`;
+}
+function formatProgress(progress) {
+    if (!progress)
+        return null;
+    const parts = [];
+    parts.push(`M ${progress.milestones.done}/${progress.milestones.total}`);
+    if (progress.slices)
+        parts.push(`S ${progress.slices.done}/${progress.slices.total}`);
+    if (progress.tasks)
+        parts.push(`T ${progress.tasks.done}/${progress.tasks.total}`);
+    return parts.length > 0 ? `Progress: ${parts.join(" · ")}` : null;
+}
+function formatEnvironmentSummary(errorCount, warningCount) {
+    if (errorCount <= 0 && warningCount <= 0)
+        return null;
+    const parts = [];
+    if (errorCount > 0)
+        parts.push(`${errorCount} error${errorCount > 1 ? "s" : ""}`);
+    if (warningCount > 0)
+        parts.push(`${warningCount} warning${warningCount > 1 ? "s" : ""}`);
+    return `Env: ${parts.join(", ")}`;
+}
+function formatBudgetSummary(data) {
+    if (data.budgetCeiling !== undefined && data.budgetCeiling > 0) {
+        const pct = Math.min(100, (data.budgetSpent / data.budgetCeiling) * 100);
+        return `Budget: ${formatCost(data.budgetSpent)}/${formatCost(data.budgetCeiling)} (${pct.toFixed(0)}%)`;
+    }
+    if (data.budgetSpent > 0) {
+        return `Spent: ${formatCost(data.budgetSpent)}`;
+    }
+    return null;
+}
+function buildExecutionHeadline(data) {
+    const status = data.executionStatus ?? "Active project";
+    const target = data.executionTarget ?? data.blocker ?? "loading status…";
+    return `  GSD  ${status}${target ? ` - ${target}` : ""}`;
+}
+/**
+ * Build compact health lines for the widget.
+ * Returns a string array suitable for setWidget().
+ */
+export function buildHealthLines(data) {
+    if (data.projectState === "none") {
+        return ["  GSD  No project loaded — run /gsd to start"];
+    }
+    if (data.projectState === "initialized") {
+        return ["  GSD  Project initialized — run /gsd to continue setup"];
+    }
+    const lines = [buildExecutionHeadline(data)];
+    const details = [];
+    const progress = formatProgress(data.progress);
+    if (progress)
+        details.push(progress);
+    if (data.providerIssue)
+        details.push(data.providerIssue);
+    const environment = formatEnvironmentSummary(data.environmentErrorCount, data.environmentWarningCount);
+    if (environment)
+        details.push(environment);
+    const budget = formatBudgetSummary(data);
+    if (budget)
+        details.push(budget);
+    if (data.eta)
+        details.push(data.eta);
+    if (details.length > 0) {
+        lines.push(`  ${details.join("  │  ")}`);
+    }
+    return lines;
+}

package/dist/resources/extensions/gsd/health-widget.js

@@ -11,21 +11,23 @@ import { runProviderChecks, summariseProviderIssues } from "./doctor-providers.j
 import { runEnvironmentChecks } from "./doctor-environment.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadLedgerFromDisk, getProjectTotals } from "./metrics.js";
+import { describeNextUnit, estimateTimeRemaining, updateSliceProgressCache } from "./auto-dashboard.js";
 import { projectRoot } from "./commands.js";
+import { deriveState, invalidateStateCache } from "./state.js";
+import { buildHealthLines, detectHealthWidgetProjectState, } from "./health-widget-core.js";
 // ── Data loader ────────────────────────────────────────────────────────────────
-function loadHealthWidgetData(basePath) {
-    let hasProject = false;
+function loadBaseHealthWidgetData(basePath) {
     let budgetCeiling;
     let budgetSpent = 0;
     let providerIssue = null;
     let environmentErrorCount = 0;
     let environmentWarningCount = 0;
+    const projectState = detectHealthWidgetProjectState(basePath);
     try {
         const prefs = loadEffectiveGSDPreferences();
         budgetCeiling = prefs?.preferences?.budget_ceiling;
         const ledger = loadLedgerFromDisk(basePath);
         if (ledger) {
-            hasProject = true;
             const totals = getProjectTotals(ledger.units ?? []);
             budgetSpent = totals.cost;
         }
@@ -47,7 +49,7 @@ function loadHealthWidgetData(basePath) {
     }
     catch { /* non-fatal */ }
     return {
-        hasProject,
+        projectState,
         budgetCeiling,
         budgetSpent,
         providerIssue,
@@ -56,50 +58,85 @@ function loadHealthWidgetData(basePath) {
         lastRefreshed: Date.now(),
     };
 }
-// ── Rendering ──────────────────────────────────────────────────────────────────
-function formatCost(n) {
-    return n >= 1 ? `$${n.toFixed(2)}` : `${(n * 100).toFixed(1)}¢`;
+function compactText(text, max = 64) {
+    const trimmed = text.replace(/\s+/g, " ").trim();
+    if (trimmed.length <= max)
+        return trimmed;
+    return `${trimmed.slice(0, max - 1).trimEnd()}…`;
 }
-/**
- * Build compact health lines for the widget.
- * Returns a string array suitable for setWidget().
- */
-export function buildHealthLines(data) {
-    if (!data.hasProject) {
-        return ["  GSD  No project loaded — run /gsd to start"];
-    }
-    const parts = [];
-    // System status signal
-    const totalIssues = data.environmentErrorCount + data.environmentWarningCount + (data.providerIssue ? 1 : 0);
-    if (totalIssues === 0) {
-        parts.push("● System OK");
-    }
-    else if (data.environmentErrorCount > 0 || data.providerIssue?.includes("✗")) {
-        parts.push(`✗ ${totalIssues} issue${totalIssues > 1 ? "s" : ""}`);
-    }
-    else {
-        parts.push(`⚠ ${totalIssues} warning${totalIssues > 1 ? "s" : ""}`);
+function summarizeExecutionStatus(state) {
+    switch (state.phase) {
+        case "blocked": return "Blocked";
+        case "paused": return "Paused";
+        case "complete": return "Complete";
+        case "executing": return "Executing";
+        case "planning": return "Planning";
+        case "pre-planning": return "Pre-planning";
+        case "summarizing": return "Summarizing";
+        case "validating-milestone": return "Validating";
+        case "completing-milestone": return "Completing";
+        case "needs-discussion": return "Needs discussion";
+        case "replanning-slice": return "Replanning";
+        default: return "Active";
     }
-    // Budget
-    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)}%)`);
-    }
-    else if (data.budgetSpent > 0) {
-        parts.push(`Spent: ${formatCost(data.budgetSpent)}`);
-    }
-    // Provider issue (if any)
-    if (data.providerIssue) {
-        parts.push(data.providerIssue);
+}
+function summarizeExecutionTarget(state) {
+    switch (state.phase) {
+        case "needs-discussion":
+            return state.activeMilestone ? `Discuss ${state.activeMilestone.id}` : "Discuss milestone draft";
+        case "pre-planning":
+            return state.activeMilestone ? `Plan ${state.activeMilestone.id}` : "Research & plan milestone";
+        case "planning":
+            return state.activeSlice ? `Plan ${state.activeSlice.id}` : "Plan next slice";
+        case "executing":
+            return state.activeTask ? `Execute ${state.activeTask.id}` : "Execute next task";
+        case "summarizing":
+            return state.activeSlice ? `Complete ${state.activeSlice.id}` : "Complete current slice";
+        case "validating-milestone":
+            return state.activeMilestone ? `Validate ${state.activeMilestone.id}` : "Validate milestone";
+        case "completing-milestone":
+            return state.activeMilestone ? `Complete ${state.activeMilestone.id}` : "Complete milestone";
+        case "replanning-slice":
+            return state.activeSlice ? `Replan ${state.activeSlice.id}` : "Replan current slice";
+        case "blocked":
+            return `waiting on ${compactText(state.blockers[0] ?? state.nextAction, 56)}`;
+        case "paused":
+            return compactText(state.nextAction || "waiting to resume", 56);
+        case "complete":
+            return "All milestones complete";
+        default:
+            return compactText(describeNextUnit(state).label, 56);
     }
-    // Environment issues
-    if (data.environmentErrorCount > 0) {
-        parts.push(`Env: ${data.environmentErrorCount} error${data.environmentErrorCount > 1 ? "s" : ""}`);
+}
+async function enrichHealthWidgetData(basePath, baseData) {
+    if (baseData.projectState !== "active")
+        return baseData;
+    try {
+        invalidateStateCache();
+        const state = await deriveState(basePath);
+        if (state.activeMilestone) {
+            // Warm the slice-progress cache so estimateTimeRemaining() has data
+            updateSliceProgressCache(basePath, state.activeMilestone.id, state.activeSlice?.id);
+        }
+        return {
+            ...baseData,
+            executionPhase: state.phase,
+            executionStatus: summarizeExecutionStatus(state),
+            executionTarget: summarizeExecutionTarget(state),
+            nextAction: state.nextAction,
+            blocker: state.blockers[0] ?? null,
+            activeMilestoneId: state.activeMilestone?.id,
+            activeSliceId: state.activeSlice?.id,
+            activeTaskId: state.activeTask?.id,
+            progress: state.progress,
+            eta: state.phase === "blocked" || state.phase === "paused" || state.phase === "complete"
+                ? null
+                : estimateTimeRemaining(),
+        };
     }
-    else if (data.environmentWarningCount > 0) {
-        parts.push(`Env: ${data.environmentWarningCount} warning${data.environmentWarningCount > 1 ? "s" : ""}`);
+    catch {
+        return baseData;
     }
-    return [`  ${parts.join("  │  ")}`];
 }
 // ── Widget init ────────────────────────────────────────────────────────────────
 const REFRESH_INTERVAL_MS = 60_000;
@@ -112,19 +149,33 @@ export function initHealthWidget(ctx) {
         return;
     const basePath = projectRoot();
     // String-array fallback — used in RPC mode (factory is a no-op there)
-    const initialData = loadHealthWidgetData(basePath);
+    const initialData = loadBaseHealthWidgetData(basePath);
     ctx.ui.setWidget("gsd-health", buildHealthLines(initialData), { placement: "belowEditor" });
     // Factory-based widget for TUI mode — replaces the string-array above
     ctx.ui.setWidget("gsd-health", (_tui, _theme) => {
         let data = initialData;
         let cachedLines;
-        const refreshTimer = setInterval(() => {
+        let refreshInFlight = false;
+        const refresh = async () => {
+            if (refreshInFlight)
+                return;
+            refreshInFlight = true;
             try {
-                data = loadHealthWidgetData(basePath);
+                const baseData = loadBaseHealthWidgetData(basePath);
+                data = await enrichHealthWidgetData(basePath, baseData);
                 cachedLines = undefined;
                 _tui.requestRender();
             }
             catch { /* non-fatal */ }
+            finally {
+                refreshInFlight = false;
+            }
+        };
+        // Fire first enrichment immediately. requestRender() inside is a no-op
+        // if the widget has not yet rendered, so this is safe before factory return.
+        void refresh();
+        const refreshTimer = setInterval(() => {
+            void refresh();
         }, REFRESH_INTERVAL_MS);
         return {
             render(_width) {

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

@@ -46,33 +46,21 @@ import { pauseAutoForProviderError, classifyProviderError } from "./provider-err
 import { toPosixPath } from "../shared/mod.js";
 import { isParallelActive, shutdownParallel } from "./parallel-orchestrator.js";
 import { DEFAULT_BASH_TIMEOUT_SECS } from "./constants.js";
-// ── Agent Instructions ────────────────────────────────────────────────────
-// Lightweight "always follow" files injected into every GSD agent session.
-// Global: ~/.gsd/agent-instructions.md   Project: .gsd/agent-instructions.md
-// Both are loaded and concatenated (global first, project appends).
-function loadAgentInstructions() {
-    const parts = [];
-    const globalPath = join(homedir(), ".gsd", "agent-instructions.md");
-    if (existsSync(globalPath)) {
-        try {
-            const content = readFileSync(globalPath, "utf-8").trim();
-            if (content)
-                parts.push(content);
-        }
-        catch { /* non-fatal — skip unreadable file */ }
-    }
-    const projectPath = join(process.cwd(), ".gsd", "agent-instructions.md");
-    if (existsSync(projectPath)) {
-        try {
-            const content = readFileSync(projectPath, "utf-8").trim();
-            if (content)
-                parts.push(content);
+// ── Agent Instructions (DEPRECATED) ──────────────────────────────────────
+// agent-instructions.md is deprecated. Use AGENTS.md or CLAUDE.md instead.
+// Pi core natively supports AGENTS.md (with CLAUDE.md fallback) per directory.
+function warnDeprecatedAgentInstructions() {
+    const paths = [
+        join(homedir(), ".gsd", "agent-instructions.md"),
+        join(process.cwd(), ".gsd", "agent-instructions.md"),
+    ];
+    for (const p of paths) {
+        if (existsSync(p)) {
+            console.warn(`[GSD] DEPRECATED: ${p} is no longer loaded. ` +
+                `Migrate your instructions to AGENTS.md (or CLAUDE.md) in the same directory. ` +
+                `See https://github.com/gsd-build/GSD-2/issues/1492`);
         }
-        catch { /* non-fatal — skip unreadable file */ }
     }
-    if (parts.length === 0)
-        return null;
-    return parts.join("\n\n");
 }
 // ── Depth verification state ──────────────────────────────────────────────
 let depthVerificationDone = false;
@@ -140,7 +128,16 @@ export default function (pi) {
                 // Pipe closed — nothing we can write; just exit cleanly
                 process.exit(0);
             }
-            // Re-throw anything that isn't EPIPE so real crashes still surface
+            if (err.code === "ENOENT" &&
+                err.syscall?.startsWith("spawn")) {
+                // spawn ENOENT — command not found (e.g., npx on Windows).
+                // This surfaces as an uncaught exception from child_process but
+                // is not a fatal process error. Log and continue instead of
+                // crashing auto-mode (#1384).
+                process.stderr.write(`[gsd] spawn ENOENT: ${err.path ?? "unknown"} — command not found\n`);
+                return;
+            }
+            // Re-throw anything that isn't EPIPE/ENOENT so real crashes still surface
             throw err;
         };
         process.on("uncaughtException", _gsdEpipeGuard);
@@ -580,12 +577,8 @@ export default function (pi) {
                 newSkillsBlock = formatSkillsXml(newSkills);
             }
         }
-        // Load agent instructions (global + project)
-        let agentInstructionsBlock = "";
-        const agentInstructions = loadAgentInstructions();
-        if (agentInstructions) {
-            agentInstructionsBlock = `\n\n## Agent Instructions\n\nThe following instructions were provided by the user and must be followed in every session:\n\n${agentInstructions}`;
-        }
+        // Warn if deprecated agent-instructions.md files are still present
+        warnDeprecatedAgentInstructions();
         const injection = await buildGuidedExecuteContextInjection(event.prompt, process.cwd());
         // Worktree context — override the static CWD in the system prompt
         let worktreeBlock = "";
@@ -628,7 +621,7 @@ export default function (pi) {
                 "Write every .gsd artifact in the worktree path above, never in the main project tree.",
             ].join("\n");
         }
-        const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${agentInstructionsBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
+        const fullSystem = `${event.systemPrompt}\n\n[SYSTEM CONTEXT — GSD]\n\n${systemContent}${preferenceBlock}${knowledgeBlock}${memoryBlock}${newSkillsBlock}${worktreeBlock}`;
         stopContextTimer({
             systemPromptSize: fullSystem.length,
             injectionSize: injection?.length ?? 0,