gsd-pi 2.32.0-dev.d792ba5 → 2.32.0-dev.f3d5d53

package/dist/resource-loader.js

@@ -1,7 +1,7 @@
 import { DefaultResourceLoader } from '@gsd/pi-coding-agent';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
-import { chmodSync, copyFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
@@ -118,7 +118,12 @@ export function getNewerManagedResourceVersion(agentDir, currentVersion) {
 function makeTreeWritable(dirPath) {
     if (!existsSync(dirPath))
         return;
-    const stats = statSync(dirPath);
+    // Use lstatSync to avoid following symlinks into immutable filesystems
+    // (e.g., Nix store on NixOS/nix-darwin). Symlinks don't carry their own
+    // permissions and their targets may be read-only by design (#1298).
+    const stats = lstatSync(dirPath);
+    if (stats.isSymbolicLink())
+        return;
     const isDir = stats.isDirectory();
     const currentMode = stats.mode & 0o777;
     // Ensure owner-write; for directories also ensure owner-exec so they remain traversable.
@@ -127,7 +132,12 @@ function makeTreeWritable(dirPath) {
         newMode |= 0o100;
     }
     if (newMode !== currentMode) {
-        chmodSync(dirPath, newMode);
+        try {
+            chmodSync(dirPath, newMode);
+        }
+        catch {
+            // Non-fatal — may fail on read-only filesystems or insufficient permissions
+        }
     }
     if (isDir) {
         for (const entry of readdirSync(dirPath, { withFileTypes: true })) {

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

@@ -189,30 +189,52 @@ export async function inlineGsdRootFile(
 // ─── DB-Aware Inline Helpers ──────────────────────────────────────────────
 
 /**
- * Inline decisions with optional milestone scoping from the DB.
- * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ * Shared DB-fallback pattern: attempt a DB query via the context-store, format
+ * the result, and fall back to the filesystem file when the DB is unavailable
+ * or the query yields no results.
+ *
+ * @param base       Project root for filesystem fallback
+ * @param label      Section heading (e.g. "Decisions")
+ * @param filename   Filesystem fallback file (e.g. "decisions.md")
+ * @param queryDb    Async callback receiving the dynamically-imported
+ *                   context-store module. Returns formatted markdown or null.
  */
-export async function inlineDecisionsFromDb(
-  base: string, milestoneId?: string, scope?: string, level?: InlineLevel,
+async function inlineFromDbOrFile(
+  base: string,
+  label: string,
+  filename: string,
+  queryDb: (cs: typeof import("./context-store.js")) => string | null,
 ): Promise<string | null> {
-  const inlineLevel = level ?? resolveInlineLevel();
   try {
     const { isDbAvailable } = await import("./gsd-db.js");
     if (isDbAvailable()) {
-      const { queryDecisions, formatDecisionsForPrompt } = await import("./context-store.js");
-      const decisions = queryDecisions({ milestoneId, scope });
-      if (decisions.length > 0) {
-        // Use compact format for non-full levels to save ~35% tokens
-        const formatted = inlineLevel !== "full"
-          ? formatDecisionsCompact(decisions)
-          : formatDecisionsForPrompt(decisions);
-        return `### Decisions\nSource: \`.gsd/DECISIONS.md\`\n\n${formatted}`;
+      const contextStore = await import("./context-store.js");
+      const content = queryDb(contextStore);
+      if (content) {
+        return `### ${label}\nSource: \`.gsd/${filename.toUpperCase().replace(/\.MD$/i, "")}.md\`\n\n${content}`;
       }
     }
   } catch {
     // DB not available — fall through to filesystem
   }
-  return inlineGsdRootFile(base, "decisions.md", "Decisions");
+  return inlineGsdRootFile(base, filename, label);
+}
+
+/**
+ * Inline decisions with optional milestone scoping from the DB.
+ * Falls back to filesystem via inlineGsdRootFile when DB unavailable or empty.
+ */
+export async function inlineDecisionsFromDb(
+  base: string, milestoneId?: string, scope?: string, level?: InlineLevel,
+): Promise<string | null> {
+  const inlineLevel = level ?? resolveInlineLevel();
+  return inlineFromDbOrFile(base, "Decisions", "decisions.md", (cs) => {
+    const decisions = cs.queryDecisions({ milestoneId, scope });
+    if (decisions.length === 0) return null;
+    return inlineLevel !== "full"
+      ? formatDecisionsCompact(decisions)
+      : cs.formatDecisionsForPrompt(decisions);
+  });
 }
 
 /**
@@ -223,23 +245,13 @@ export async function inlineRequirementsFromDb(
   base: string, sliceId?: string, level?: InlineLevel,
 ): Promise<string | null> {
   const inlineLevel = level ?? resolveInlineLevel();
-  try {
-    const { isDbAvailable } = await import("./gsd-db.js");
-    if (isDbAvailable()) {
-      const { queryRequirements, formatRequirementsForPrompt } = await import("./context-store.js");
-      const requirements = queryRequirements({ sliceId });
-      if (requirements.length > 0) {
-        // Use compact format for non-full levels to save ~40% tokens
-        const formatted = inlineLevel !== "full"
-          ? formatRequirementsCompact(requirements)
-          : formatRequirementsForPrompt(requirements);
-        return `### Requirements\nSource: \`.gsd/REQUIREMENTS.md\`\n\n${formatted}`;
-      }
-    }
-  } catch {
-    // DB not available — fall through to filesystem
-  }
-  return inlineGsdRootFile(base, "requirements.md", "Requirements");
+  return inlineFromDbOrFile(base, "Requirements", "requirements.md", (cs) => {
+    const requirements = cs.queryRequirements({ sliceId });
+    if (requirements.length === 0) return null;
+    return inlineLevel !== "full"
+      ? formatRequirementsCompact(requirements)
+      : cs.formatRequirementsForPrompt(requirements);
+  });
 }
 
 /**
@@ -249,19 +261,9 @@ export async function inlineRequirementsFromDb(
 export async function inlineProjectFromDb(
   base: string,
 ): Promise<string | null> {
-  try {
-    const { isDbAvailable } = await import("./gsd-db.js");
-    if (isDbAvailable()) {
-      const { queryProject } = await import("./context-store.js");
-      const content = queryProject();
-      if (content) {
-        return `### Project\nSource: \`.gsd/PROJECT.md\`\n\n${content}`;
-      }
-    }
-  } catch {
-    // DB not available — fall through to filesystem
-  }
-  return inlineGsdRootFile(base, "project.md", "Project");
+  return inlineFromDbOrFile(base, "Project", "project.md", (cs) => {
+    return cs.queryProject();
+  });
 }
 
 // ─── Skill Discovery ──────────────────────────────────────────────────────

package/dist/resources/extensions/gsd/auto-start.ts

@@ -63,6 +63,7 @@ import { debugLog, enableDebug, isDebugEnabled, getDebugLogPath } from "./debug-
 import type { AutoSession } from "./auto/session.js";
 import { existsSync, mkdirSync, readdirSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
+import { getErrorMessage } from "./error-utils.js";
 
 export interface BootstrapDeps {
   shouldUseWorktreeIsolation: () => boolean;
@@ -201,11 +202,11 @@ export async function bootstrapAutoSession(
         if (!midMatch) continue;
         const mid = midMatch[1];
         if (resolveMilestoneFile(base, mid, "SUMMARY")) {
-          try { unlinkSync(join(runtimeUnitsDir, file)); } catch (e) { debugLog("stale-unit-cleanup-failed", { file, error: e instanceof Error ? e.message : String(e) }); }
+          try { unlinkSync(join(runtimeUnitsDir, file)); } catch (e) { debugLog("stale-unit-cleanup-failed", { file, error: getErrorMessage(e) }); }
         }
       }
     }
-  } catch (e) { debugLog("stale-unit-dir-cleanup-failed", { error: e instanceof Error ? e.message : String(e) }); }
+  } catch (e) { debugLog("stale-unit-dir-cleanup-failed", { error: getErrorMessage(e) }); }
 
   let state = await deriveState(base);
 
@@ -343,7 +344,7 @@ export async function bootstrapAutoSession(
       registerSigtermHandler(s.originalBasePath);
     } catch (err) {
       ctx.ui.notify(
-        `Auto-worktree setup failed: ${err instanceof Error ? err.message : String(err)}. Continuing in project root.`,
+        `Auto-worktree setup failed: ${getErrorMessage(err)}. Continuing in project root.`,
         "warning",
       );
     }
@@ -435,7 +436,7 @@ export async function bootstrapAutoSession(
     }
   } catch (err) {
     ctx.ui.notify(
-      `Secrets check error: ${err instanceof Error ? err.message : String(err)}. Continuing without secrets.`,
+      `Secrets check error: ${getErrorMessage(err)}. Continuing without secrets.`,
       "warning",
     );
   }
@@ -453,7 +454,7 @@ export async function bootstrapAutoSession(
         ctx.ui.notify("Removed stale .git/index.lock from prior crash.", "info");
       }
     }
-  } catch (e) { debugLog("git-lock-cleanup-failed", { error: e instanceof Error ? e.message : String(e) }); }
+  } catch (e) { debugLog("git-lock-cleanup-failed", { error: getErrorMessage(e) }); }
 
   // Pre-flight: validate milestone queue
   try {

package/dist/resources/extensions/gsd/auto-timers.ts

@@ -20,6 +20,7 @@ import { closeoutUnit, type CloseoutOptions } from "./auto-unit-closeout.js";
 import { saveActivityLog } from "./activity-log.js";
 import { recoverTimedOutUnit, type RecoveryContext } from "./auto-timeout-recovery.js";
 import type { AutoSession } from "./auto/session.js";
+import { getErrorMessage } from "./error-utils.js";
 
 export interface SupervisionContext {
   s: AutoSession;
@@ -127,7 +128,7 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
       );
       await pauseAuto(ctx, pi);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+      const message = getErrorMessage(err);
       console.error(`[idle-watchdog] Unhandled error: ${message}`);
       try {
         ctx.ui.notify(`Idle watchdog error: ${message}`, "warning");
@@ -159,7 +160,7 @@ export function startUnitSupervision(sctx: SupervisionContext): void {
       );
       await pauseAuto(ctx, pi);
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+      const message = getErrorMessage(err);
       console.error(`[hard-timeout] Unhandled error: ${message}`);
       try {
         ctx.ui.notify(`Hard timeout error: ${message}`, "warning");

package/dist/resources/extensions/gsd/auto-verification.ts

@@ -24,6 +24,7 @@ import { writeVerificationJSON } from "./verification-evidence.js";
 import { removePersistedKey } from "./auto-recovery.js";
 import type { AutoSession, PendingVerificationRetry } from "./auto/session.js";
 import { join } from "node:path";
+import { getErrorMessage } from "./error-utils.js";
 
 export interface VerificationContext {
   s: AutoSession;
@@ -204,7 +205,7 @@ export async function runPostUnitVerification(
       try {
         await dispatchNextUnit(ctx, pi);
       } catch (retryDispatchErr) {
-        const msg = retryDispatchErr instanceof Error ? retryDispatchErr.message : String(retryDispatchErr);
+        const msg = getErrorMessage(retryDispatchErr);
         ctx.ui.notify(`Verification retry dispatch error: ${msg}`, "error");
         startDispatchGapWatchdog(ctx, pi);
       }

package/dist/resources/extensions/gsd/auto-worktree.ts

@@ -38,6 +38,7 @@ import {
   nativeBranchDelete,
   nativeBranchExists,
 } from "./native-git-bridge.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Module State ──────────────────────────────────────────────────────────
 
@@ -81,7 +82,7 @@ export function runWorktreePostCreateHook(sourceDir: string, worktreeDir: string
     });
     return null;
   } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
+    const msg = getErrorMessage(err);
     return `Worktree post-create hook failed: ${msg}`;
   }
 }
@@ -141,7 +142,7 @@ export function createAutoWorktree(basePath: string, milestoneId: string): strin
     // Don't store originalBase -- caller can retry or clean up.
     throw new GSDError(
       GSD_IO_ERROR,
-      `Auto-worktree created at ${info.path} but chdir failed: ${err instanceof Error ? err.message : String(err)}`,
+      `Auto-worktree created at ${info.path} but chdir failed: ${getErrorMessage(err)}`,
     );
   }
 
@@ -168,7 +169,7 @@ export function teardownAutoWorktree(
   } catch (err) {
     throw new GSDError(
       GSD_IO_ERROR,
-      `Failed to chdir back to ${originalBasePath} during teardown: ${err instanceof Error ? err.message : String(err)}`,
+      `Failed to chdir back to ${originalBasePath} during teardown: ${getErrorMessage(err)}`,
     );
   }
 
@@ -274,7 +275,7 @@ export function enterAutoWorktree(basePath: string, milestoneId: string): string
   } catch (err) {
     throw new GSDError(
       GSD_IO_ERROR,
-      `Failed to enter auto-worktree at ${p}: ${err instanceof Error ? err.message : String(err)}`,
+      `Failed to enter auto-worktree at ${p}: ${getErrorMessage(err)}`,
     );
   }
 

package/dist/resources/extensions/gsd/auto.ts

@@ -189,6 +189,7 @@ import {
   NEW_SESSION_TIMEOUT_MS, DISPATCH_HANG_TIMEOUT_MS,
 } from "./auto/session.js";
 import type { CompletedUnit, CurrentUnit, UnitRouting, StartModel, PendingVerificationRetry } from "./auto/session.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
@@ -428,7 +429,7 @@ function startDispatchGapWatchdog(ctx: ExtensionContext, pi: ExtensionAPI): void
     try {
       await dispatchNextUnit(ctx, pi);
     } catch (retryErr) {
-      const message = retryErr instanceof Error ? retryErr.message : String(retryErr);
+      const message = getErrorMessage(retryErr);
       await stopAuto(ctx, pi, `Dispatch gap recovery failed: ${message}`);
       return;
     }
@@ -458,14 +459,14 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
   // ── Auto-worktree: exit worktree and reset s.basePath on stop ──
   if (s.currentMilestoneId && isInAutoWorktree(s.basePath)) {
     try {
-      try { autoCommitCurrentBranch(s.basePath, "stop", s.currentMilestoneId); } catch (e) { debugLog("stop-auto-commit-failed", { error: e instanceof Error ? e.message : String(e) }); }
+      try { autoCommitCurrentBranch(s.basePath, "stop", s.currentMilestoneId); } catch (e) { debugLog("stop-auto-commit-failed", { error: getErrorMessage(e) }); }
       teardownAutoWorktree(s.originalBasePath, s.currentMilestoneId, { preserveBranch: true });
       s.basePath = s.originalBasePath;
       s.gitService = createGitService(s.basePath);
       ctx?.ui.notify("Exited auto-worktree (branch preserved for resume).", "info");
     } catch (err) {
       ctx?.ui.notify(
-        `Auto-worktree teardown failed: ${err instanceof Error ? err.message : String(err)}`,
+        `Auto-worktree teardown failed: ${getErrorMessage(err)}`,
         "warning",
       );
     }
@@ -476,7 +477,7 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
     try {
       const { closeDatabase } = await import("./gsd-db.js");
       closeDatabase();
-    } catch (e) { debugLog("db-close-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    } catch (e) { debugLog("db-close-failed", { error: getErrorMessage(e) }); }
   }
 
   if (s.originalBasePath) {
@@ -496,7 +497,7 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
   }
 
   if (s.basePath) {
-    try { await rebuildState(s.basePath); } catch (e) { debugLog("stop-rebuild-state-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    try { await rebuildState(s.basePath); } catch (e) { debugLog("stop-rebuild-state-failed", { error: getErrorMessage(e) }); }
   }
 
   if (isDebugEnabled()) {
@@ -635,7 +636,7 @@ export async function startAuto(
         }
       } catch (err) {
         ctx.ui.notify(
-          `Auto-worktree re-entry failed: ${err instanceof Error ? err.message : String(err)}. Continuing at current path.`,
+          `Auto-worktree re-entry failed: ${getErrorMessage(err)}. Continuing at current path.`,
           "warning",
         );
       }
@@ -647,13 +648,13 @@ export async function startAuto(
     ctx.ui.setFooter(hideFooter);
     ctx.ui.notify(s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", "info");
     restoreHookState(s.basePath);
-    try { await rebuildState(s.basePath); } catch (e) { debugLog("resume-rebuild-state-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    try { await rebuildState(s.basePath); } catch (e) { debugLog("resume-rebuild-state-failed", { error: getErrorMessage(e) }); }
     try {
       const report = await runGSDDoctor(s.basePath, { fix: true });
       if (report.fixesApplied.length > 0) {
         ctx.ui.notify(`Resume: applied ${report.fixesApplied.length} fix(es) to state.`, "info");
       }
-    } catch (e) { debugLog("resume-doctor-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    } catch (e) { debugLog("resume-doctor-failed", { error: getErrorMessage(e) }); }
     await selfHealRuntimeRecords(s.basePath, ctx, s.completedKeySet);
     invalidateAllCaches();
 
@@ -700,7 +701,7 @@ export async function startAuto(
         }
       } catch (err) {
         ctx.ui.notify(
-          `Secrets check error: ${err instanceof Error ? err.message : String(err)}. Continuing without secrets.`,
+          `Secrets check error: ${getErrorMessage(err)}. Continuing without secrets.`,
           "warning",
         );
       }
@@ -807,7 +808,7 @@ export async function handleAgentEnd(
   try {
     await dispatchNextUnit(ctx, pi);
   } catch (dispatchErr) {
-    const message = dispatchErr instanceof Error ? dispatchErr.message : String(dispatchErr);
+    const message = getErrorMessage(dispatchErr);
     ctx.ui.notify(
       `Dispatch error after unit completion: ${message}. Retrying in ${DISPATCH_GAP_TIMEOUT_MS / 1000}s.`,
       "error",
@@ -838,7 +839,7 @@ export async function handleAgentEnd(
       clearDispatchGapWatchdog();
       setImmediate(() => {
         handleAgentEnd(ctx, pi).catch((err) => {
-          const msg = err instanceof Error ? err.message : String(err);
+          const msg = getErrorMessage(err);
           ctx.ui.notify(`Deferred agent_end retry failed: ${msg}`, "error");
           pauseAuto(ctx, pi).catch(() => {});
         });
@@ -1086,7 +1087,7 @@ async function dispatchNextUnit(
         );
       } catch (err) {
         ctx.ui.notify(
-          `Report generation failed: ${err instanceof Error ? err.message : String(err)}`,
+          `Report generation failed: ${getErrorMessage(err)}`,
           "warning",
         );
       }
@@ -1102,7 +1103,7 @@ async function dispatchNextUnit(
         atomicWriteSync(file, JSON.stringify([]));
       }
       s.completedKeySet.clear();
-    } catch (e) { debugLog("completed-keys-reset-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    } catch (e) { debugLog("completed-keys-reset-failed", { error: getErrorMessage(e) }); }
 
     // ── Worktree lifecycle on milestone transition (#616) ──
     if (isInAutoWorktree(s.basePath) && s.originalBasePath && shouldUseWorktreeIsolation()) {
@@ -1121,7 +1122,7 @@ async function dispatchNextUnit(
         }
       } catch (err) {
         ctx.ui.notify(
-          `Milestone merge failed during transition: ${err instanceof Error ? err.message : String(err)}`,
+          `Milestone merge failed during transition: ${getErrorMessage(err)}`,
           "warning",
         );
         if (s.originalBasePath) {
@@ -1146,7 +1147,7 @@ async function dispatchNextUnit(
           ctx.ui.notify(`Created auto-worktree for ${mid} at ${wtPath}`, "info");
         } catch (err) {
           ctx.ui.notify(
-            `Auto-worktree creation for ${mid} failed: ${err instanceof Error ? err.message : String(err)}. Continuing in project root.`,
+            `Auto-worktree creation for ${mid} failed: ${getErrorMessage(err)}. Continuing in project root.`,
             "warning",
           );
         }
@@ -1190,7 +1191,7 @@ async function dispatchNextUnit(
           }
         } catch (err) {
           ctx.ui.notify(
-            `Milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
+            `Milestone merge failed: ${getErrorMessage(err)}`,
             "warning",
           );
           if (s.originalBasePath) {
@@ -1216,7 +1217,7 @@ async function dispatchNextUnit(
           }
         } catch (err) {
           ctx.ui.notify(
-            `Milestone merge failed (branch mode): ${err instanceof Error ? err.message : String(err)}`,
+            `Milestone merge failed (branch mode): ${getErrorMessage(err)}`,
             "warning",
           );
         }
@@ -1276,7 +1277,7 @@ async function dispatchNextUnit(
         atomicWriteSync(file, JSON.stringify([]));
       }
       s.completedKeySet.clear();
-    } catch (e) { debugLog("completed-keys-reset-failed", { error: e instanceof Error ? e.message : String(e) }); }
+    } catch (e) { debugLog("completed-keys-reset-failed", { error: getErrorMessage(e) }); }
     // ── Milestone merge ──
     if (s.currentMilestoneId && isInAutoWorktree(s.basePath) && s.originalBasePath) {
       try {
@@ -1292,7 +1293,7 @@ async function dispatchNextUnit(
         );
       } catch (err) {
         ctx.ui.notify(
-          `Milestone merge failed: ${err instanceof Error ? err.message : String(err)}`,
+          `Milestone merge failed: ${getErrorMessage(err)}`,
           "warning",
         );
         if (s.originalBasePath) {
@@ -1318,7 +1319,7 @@ async function dispatchNextUnit(
         }
       } catch (err) {
         ctx.ui.notify(
-          `Milestone merge failed (branch mode): ${err instanceof Error ? err.message : String(err)}`,
+          `Milestone merge failed (branch mode): ${getErrorMessage(err)}`,
           "warning",
         );
       }
@@ -1417,7 +1418,7 @@ async function dispatchNextUnit(
       }
     } catch (err) {
       ctx.ui.notify(
-        `Secrets collection error: ${err instanceof Error ? err.message : String(err)}. Continuing with next task.`,
+        `Secrets collection error: ${getErrorMessage(err)}. Continuing with next task.`,
         "warning",
       );
     }
@@ -1628,7 +1629,7 @@ async function dispatchNextUnit(
     );
     result = await Promise.race([sessionPromise, timeoutPromise]);
   } catch (sessionErr) {
-    const msg = sessionErr instanceof Error ? sessionErr.message : String(sessionErr);
+    const msg = getErrorMessage(sessionErr);
     ctx.ui.notify(`Session creation failed: ${msg}. Retrying via watchdog.`, "error");
     throw new Error(`newSession() failed: ${msg}`);
   }
@@ -1704,7 +1705,7 @@ async function dispatchNextUnit(
     const { reorderForCaching } = await import("./prompt-ordering.js");
     finalPrompt = reorderForCaching(finalPrompt);
   } catch (reorderErr) {
-    const msg = reorderErr instanceof Error ? reorderErr.message : String(reorderErr);
+    const msg = getErrorMessage(reorderErr);
     process.stderr.write(`[gsd] prompt reorder failed (non-fatal): ${msg}\n`);
   }
 

package/dist/resources/extensions/gsd/commands-inspect.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { getErrorMessage } from "./error-utils.js";
 
 export interface InspectData {
   schemaVersion: number | null;
@@ -84,7 +85,7 @@ export async function handleInspect(ctx: ExtensionCommandContext): Promise<void>
 
     ctx.ui.notify(formatInspectOutput(data), "info");
   } catch (err) {
-    process.stderr.write(`gsd-db: /gsd inspect failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.stderr.write(`gsd-db: /gsd inspect failed: ${getErrorMessage(err)}\n`);
     ctx.ui.notify("Failed to inspect GSD database. Check stderr for details.", "error");
   }
 }

package/dist/resources/extensions/gsd/commands-workflow-templates.ts

@@ -21,6 +21,7 @@ import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
 import { createGitService, runGit } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -439,7 +440,7 @@ export async function handleStart(
         branchCreated = true;
       }
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
+      const message = getErrorMessage(err);
       ctx.ui.notify(
         `Could not create branch ${branchName}: ${message}. Working on current branch.`,
         "warning",

package/dist/resources/extensions/gsd/error-utils.ts

@@ -0,0 +1,6 @@
+/**
+ * Extract a human-readable message from an unknown caught value.
+ */
+export function getErrorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/dist/resources/extensions/gsd/export.ts

@@ -12,6 +12,7 @@ import {
 import type { UnitMetrics } from "./metrics.js";
 import { gsdRoot } from "./paths.js";
 import { formatDuration, fileLink } from "../shared/mod.js";
+import { getErrorMessage } from "./error-utils.js";
 
 /**
  * Open a file in the user's default browser.
@@ -226,7 +227,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
       }
     } catch (err) {
       ctx.ui.notify(
-        `HTML export failed: ${err instanceof Error ? err.message : String(err)}`,
+        `HTML export failed: ${getErrorMessage(err)}`,
         "error",
       );
     }

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

@@ -33,6 +33,7 @@ import {
   nativeAddPaths,
 } from "./native-git-bridge.js";
 import { GSDError, GSD_MERGE_CONFLICT, GSD_GIT_ERROR } from "./errors.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -281,7 +282,7 @@ export function runGit(basePath: string, args: string[], options: { allowFailure
     }).trim();
   } catch (error) {
     if (options.allowFailure) return "";
-    const message = error instanceof Error ? error.message : String(error);
+    const message = getErrorMessage(error);
     throw new GSDError(GSD_GIT_ERROR, `git ${args.join(" ")} failed in ${basePath}: ${filterGitSvnNoise(message)}`);
   }
 }
@@ -533,7 +534,7 @@ export class GitServiceImpl {
       execSync(command, { cwd: this.basePath, stdio: "pipe", encoding: "utf-8" });
       return { passed: true, skipped: false, command };
     } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
+      const msg = getErrorMessage(err);
       return { passed: false, skipped: false, command, error: msg };
     }
   }

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

@@ -44,6 +44,7 @@ export {
   showQueue, handleQueueReorder, showQueueAdd,
   buildExistingMilestonesContext,
 } from "./guided-flow-queue.js";
+import { getErrorMessage } from "./error-utils.js";
 
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 
@@ -158,9 +159,9 @@ export function checkAutoStartAfterDiscuss(): boolean {
 
   pendingAutoStart = null;
   startAuto(ctx, pi, basePath, false, { step }).catch((err) => {
-    ctx.ui.notify(`Auto-start failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+    ctx.ui.notify(`Auto-start failed: ${getErrorMessage(err)}`, "error");
     if (process.env.GSD_DEBUG) console.error('[gsd] auto start error:', err);
-    debugLog("auto-start-failed", { error: err instanceof Error ? err.message : String(err) });
+    debugLog("auto-start-failed", { error: getErrorMessage(err) });
   });
   return true;
 }

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

@@ -64,6 +64,7 @@ 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";
+import { getErrorMessage } from "./error-utils.js";
 
 /**
  * Ensure the GSD database is available, auto-initializing if needed.
@@ -374,7 +375,7 @@ export default function (pi: ExtensionAPI) {
           details: { operation: "save_decision", id },
         };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = getErrorMessage(err);
         process.stderr.write(`gsd-db: gsd_save_decision tool failed: ${msg}\n`);
         return {
           content: [{ type: "text" as const, text: `Error saving decision: ${msg}` }],
@@ -445,7 +446,7 @@ export default function (pi: ExtensionAPI) {
           details: { operation: "update_requirement", id: params.id },
         };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = getErrorMessage(err);
         process.stderr.write(`gsd-db: gsd_update_requirement tool failed: ${msg}\n`);
         return {
           content: [{ type: "text" as const, text: `Error updating requirement: ${msg}` }],
@@ -525,7 +526,7 @@ export default function (pi: ExtensionAPI) {
           details: { operation: "save_summary", path: relativePath, artifact_type: params.artifact_type },
         };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = getErrorMessage(err);
         process.stderr.write(`gsd-db: gsd_save_summary tool failed: ${msg}\n`);
         return {
           content: [{ type: "text" as const, text: `Error saving artifact: ${msg}` }],
@@ -574,7 +575,7 @@ export default function (pi: ExtensionAPI) {
           details: { operation: "generate_milestone_id", id: newId, existingCount: existingIds.length, reservedCount: reservedMilestoneIds.size, uniqueEnabled },
         };
       } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
+        const msg = getErrorMessage(err);
         return {
           content: [{ type: "text" as const, text: `Error generating milestone ID: ${msg}` }],
           isError: true,
@@ -993,7 +994,7 @@ export default function (pi: ExtensionAPI) {
     } catch (err) {
       // Safety net: if handleAgentEnd throws despite its internal try-catch,
       // ensure auto-mode stops gracefully instead of silently stalling (#381).
-      const message = err instanceof Error ? err.message : String(err);
+      const message = getErrorMessage(err);
       ctx.ui.notify(
         `Auto-mode error in agent_end handler: ${message}. Stopping auto-mode.`,
         "error",