gsd-pi 2.80.0-dev.3065f7bfa → 2.80.0-dev.488219eb6

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Auto-mode orchestration, session lifecycle, and stop handling.
 /**
  * GSD Auto Mode — Fresh Session Per Unit
  *
@@ -354,6 +356,14 @@ function restoreProjectRootEnv(): void {
   s.projectRootEnvCaptured = false;
 }
 
+export function _captureProjectRootEnvForTest(projectRoot: string): void {
+  captureProjectRootEnv(projectRoot);
+}
+
+export function _restoreProjectRootEnvForTest(): void {
+  restoreProjectRootEnv();
+}
+
 function captureMilestoneLockEnv(milestoneId: string | null): void {
   if (!s.milestoneLockEnvCaptured) {
     s.hadMilestoneLockEnv = Object.prototype.hasOwnProperty.call(process.env, "GSD_MILESTONE_LOCK");
@@ -442,6 +452,16 @@ export function _synthesizePausedSessionRecoveryForTest(
   return synthesizePausedSessionRecovery(basePath, unitType, unitId, sessionFile);
 }
 
+export function _resolvePausedResumeBasePathForTest(
+  basePath: string,
+  pausedWorktreePath: string | null | undefined,
+  pathExists: (path: string) => boolean = existsSync,
+): string {
+  return pausedWorktreePath && pathExists(pausedWorktreePath)
+    ? pausedWorktreePath
+    : basePath;
+}
+
 const DETACHED_AUTO_KEEPALIVE_INTERVAL_MS = 30_000;
 
 function withDetachedAutoKeepalive<T>(run: Promise<T>): Promise<T> {
@@ -673,6 +693,30 @@ export function isAutoPaused(): boolean {
   return s.paused;
 }
 
+export interface ResumeResourceRefreshDeps {
+  env?: NodeJS.ProcessEnv;
+  importModule?: (specifier: string) => Promise<any>;
+  openProjectDb?: (basePath: string) => Promise<void>;
+}
+
+export async function refreshResumeResourcesAndDb(
+  basePath: string,
+  deps: ResumeResourceRefreshDeps = {},
+): Promise<void> {
+  const env = deps.env ?? process.env;
+  const importModule = deps.importModule ?? ((specifier: string) => import(specifier));
+  const agentDir = env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
+  const pkgRoot = env.GSD_PKG_ROOT;
+  const resourceLoaderPath = pkgRoot
+    ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href
+    : new URL("../../../resource-loader.js", import.meta.url).href;
+  const { initResources } = await importModule(resourceLoaderPath);
+  initResources(agentDir);
+  const { primeCache } = await importModule("./prompt-loader.js");
+  primeCache();
+  await (deps.openProjectDb ?? openProjectDbIfPresent)(basePath);
+}
+
 export function setActiveEngineId(id: string | null): void {
   s.activeEngineId = id;
 }
@@ -927,7 +971,23 @@ function handleLostSessionLock(
  * the stale unit state, progress widget, status badge, and restores CWD so
  * the dashboard does not show an orphaned timer and the shell is usable.
  */
-function cleanupAfterLoopExit(ctx: ExtensionContext): void {
+export async function rerootCommandSession(
+  cmdCtx: Pick<ExtensionCommandContext, "newSession"> | null | undefined,
+  workspaceRoot: string,
+): Promise<{ status: "skipped" | "ok" | "cancelled" | "failed"; error?: string }> {
+  if (!cmdCtx || !workspaceRoot) return { status: "skipped" };
+  try {
+    const result = await cmdCtx.newSession({ workspaceRoot });
+    return result.cancelled ? { status: "cancelled" } : { status: "ok" };
+  } catch (err) {
+    return {
+      status: "failed",
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+export async function cleanupAfterLoopExit(ctx: ExtensionContext): Promise<void> {
   s.currentUnit = null;
   s.active = false;
   deactivateGSD();
@@ -965,6 +1025,34 @@ function cleanupAfterLoopExit(ctx: ExtensionContext): void {
       logWarning("engine", `chdir failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
   }
+
+  if (s.originalBasePath && s.cmdCtx) {
+    const result = await rerootCommandSession(s.cmdCtx, s.basePath);
+    if (result.status === "cancelled") {
+      logWarning("engine", "post-loop session re-root was cancelled", { file: "auto.ts", basePath: s.basePath });
+    } else if (result.status === "failed") {
+      logWarning("engine", `post-loop session re-root failed: ${result.error ?? "unknown"}`, { file: "auto.ts", basePath: s.basePath });
+    }
+  }
+}
+
+export function _cleanupAfterLoopExitForTest(ctx: ExtensionContext): Promise<void> {
+  return cleanupAfterLoopExit(ctx);
+}
+
+export type AutoWorktreeExitAction = "skip" | "merge" | "preserve";
+
+export function _resolveAutoWorktreeExitActionForTest(
+  currentMilestoneId: string | null | undefined,
+  milestoneMergedInPhases: boolean,
+  milestoneComplete: boolean,
+): AutoWorktreeExitAction {
+  const action = _selectStopAutoWorktreeExit({
+    currentMilestoneId: currentMilestoneId ?? null,
+    milestoneComplete,
+    milestoneMergedInPhases,
+  });
+  return action === "none" ? "skip" : action;
 }
 
 export async function stopAuto(
@@ -1118,10 +1206,16 @@ export async function stopAuto(
           logWarning("engine", `milestone summary check failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
         }
 
-        if (milestoneComplete) {
+        const exitAction = _selectStopAutoWorktreeExit({
+          currentMilestoneId: s.currentMilestoneId,
+          milestoneComplete,
+          milestoneMergedInPhases: s.milestoneMergedInPhases,
+        });
+
+        if (exitAction === "merge") {
           // Milestone is complete — merge worktree branch back to main
           resolver.mergeAndExit(s.currentMilestoneId, notifyCtx);
-        } else {
+        } else if (exitAction === "preserve") {
           // Milestone still in progress — preserve branch for later resumption
           resolver.exitMilestone(s.currentMilestoneId, notifyCtx, {
             preserveBranch: true,
@@ -1129,6 +1223,10 @@ export async function stopAuto(
         }
       }
     } catch (e) {
+      ctx?.ui.notify(
+        `Worktree cleanup failed for ${s.currentMilestoneId ?? "current milestone"}: ${e instanceof Error ? e.message : String(e)}. Resolve the preserved branch/worktree and run /gsd auto to resume.`,
+        "warning",
+      );
       debugLog("stop-cleanup-worktree", { error: e instanceof Error ? e.message : String(e) });
     }
 
@@ -1179,13 +1277,11 @@ export async function stopAuto(
     // its own cwd for tools and system prompt; refresh it before returning to the
     // user so follow-up commands do not target a removed milestone worktree.
     if (s.originalBasePath && ctx && s.cmdCtx) {
-      try {
-        const result = await s.cmdCtx.newSession({ workspaceRoot: s.basePath });
-        if (result.cancelled) {
-          logWarning("engine", "post-stop session re-root was cancelled", { file: "auto.ts", basePath: s.basePath });
-        }
-      } catch (err) {
-        logWarning("engine", `post-stop session re-root failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts", basePath: s.basePath });
+      const result = await rerootCommandSession(s.cmdCtx, s.basePath);
+      if (result.status === "cancelled") {
+        logWarning("engine", "post-stop session re-root was cancelled", { file: "auto.ts", basePath: s.basePath });
+      } else if (result.status === "failed") {
+        logWarning("engine", `post-stop session re-root failed: ${result.error ?? "unknown"}`, { file: "auto.ts", basePath: s.basePath });
       }
     }
 
@@ -1317,6 +1413,17 @@ export async function stopAuto(
   }
 }
 
+export type StopAutoWorktreeExitAction = "none" | "merge" | "preserve";
+
+export function _selectStopAutoWorktreeExit(args: {
+  currentMilestoneId: string | null;
+  milestoneComplete: boolean;
+  milestoneMergedInPhases: boolean;
+}): StopAutoWorktreeExitAction {
+  if (!args.currentMilestoneId || args.milestoneMergedInPhases) return "none";
+  return args.milestoneComplete ? "merge" : "preserve";
+}
+
 /**
  * Pause auto-mode without destroying state. Context is preserved.
  * The user can interact with the agent, then `/gsd auto` resumes
@@ -1995,9 +2102,7 @@ export async function startAuto(
         { file: "auto.ts", milestoneId: s.currentMilestoneId ?? "" },
       );
     }
-    if (resumeWorktreePath && existsSync(resumeWorktreePath)) {
-      s.basePath = resumeWorktreePath;
-    }
+    s.basePath = _resolvePausedResumeBasePathForTest(base, resumeWorktreePath);
     // Rebuild scope now that s.basePath reflects the actual worktree (or project root).
     rebuildScope(s.basePath, s.currentMilestoneId);
     // Ensure the workflow-logger audit log is pinned to the project root
@@ -2049,20 +2154,7 @@ export async function startAuto(
     // tree; deployed extensions live at ~/.gsd/agent/extensions/gsd/ where the
     // relative path resolves to ~/.gsd/agent/resource-loader.js which doesn't exist.
     // Using GSD_PKG_ROOT constructs a correct absolute path in both contexts (#3949).
-    const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
-    const pkgRoot = process.env.GSD_PKG_ROOT;
-    const resourceLoaderPath = pkgRoot
-      ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href
-      : new URL("../../../resource-loader.js", import.meta.url).href;
-    const { initResources } = await import(resourceLoaderPath);
-    initResources(agentDir);
-    // initResources() uses synchronous fs APIs, so the prompt-template cache
-    // can be primed immediately — no need for the legacy 1s setTimeout deferral.
-    const { primeCache } = await import("./prompt-loader.js");
-    primeCache();
-    // Open the project DB before rebuild/derive so resume uses DB-backed
-    // state instead of falling back to stale markdown parsing (#2940).
-    await openProjectDbIfPresent(s.basePath);
+    await refreshResumeResourcesAndDb(s.basePath);
     try {
       await rebuildState(s.basePath);
       pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "sync" as const, preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, state: await deriveState(s.basePath) });
@@ -2134,7 +2226,7 @@ export async function startAuto(
       runKernelLoop: runUokKernelLoop,
       runLegacyLoop: runLegacyAutoLoop,
     });
-    cleanupAfterLoopExit(ctx);
+    await cleanupAfterLoopExit(ctx);
     return;
   }
 
@@ -2194,7 +2286,7 @@ export async function startAuto(
     runKernelLoop: runUokKernelLoop,
     runLegacyLoop: runLegacyAutoLoop,
   });
-  cleanupAfterLoopExit(ctx);
+  await cleanupAfterLoopExit(ctx);
 }
 
 // describeNextUnit is imported from auto-dashboard.ts and re-exported

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -15,7 +15,12 @@ import { clearPathCache } from "../paths.js";
 import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
-import { isSessionSwitchInFlight, resolveAgentEnd, resolveAgentEndCancelled } from "../auto/resolve.js";
+import {
+  isSessionSwitchAbortGraceActive,
+  isSessionSwitchInFlight,
+  resolveAgentEnd,
+  resolveAgentEndCancelled,
+} from "../auto/resolve.js";
 import { resolveModelId } from "../auto-model-selection.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
@@ -77,6 +82,42 @@ export function isUserInitiatedAbortMessage(message: string | undefined | null):
   return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user)\b/i.test(message);
 }
 
+function isBareClaudeCodeSessionSwitchAbortMarker(message: string | undefined | null): boolean {
+  if (!message) return false;
+  const normalized = message.trim().replace(/\s+/g, " ").toLowerCase();
+  return normalized === "claude code process aborted by user"
+    || normalized === "request aborted by user"
+    || normalized === "process aborted by user"
+    || normalized === "claude code stream aborted by caller";
+}
+
+function readAssistantTextContent(content: unknown): string {
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) => {
+      if (!block || typeof block !== "object") return "";
+      const text = (block as { text?: unknown }).text;
+      return typeof text === "string" ? text : "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function isClaudeCodeSessionSwitchAbortMessage(lastMsg: unknown): boolean {
+  if (!lastMsg || typeof lastMsg !== "object") return false;
+  const m = lastMsg as { stopReason?: unknown; errorMessage?: unknown; content?: unknown };
+  const carriers = [
+    m.errorMessage ? String(m.errorMessage) : "",
+    readAssistantTextContent(m.content),
+  ].filter((value) => value.trim().length > 0);
+
+  if ((m.stopReason === "error" || m.stopReason === "aborted") && carriers.length > 0) {
+    return carriers.every(isBareClaudeCodeSessionSwitchAbortMarker);
+  }
+
+  return false;
+}
+
 /**
  * Resolve an agent_end event observed while a session switch is in flight.
  *
@@ -89,10 +130,11 @@ export function isUserInitiatedAbortMessage(message: string | undefined | null):
  * "Auto-mode stopped — Unit aborted: Claude Code process aborted by user"
  * even though no user input occurred.
  *
- * The user-abort branch is intentionally ignored when the abort fires while
- * the session-switch is in flight: the abort is the expected side-effect of
- * the transition, not a user signal. Other branches (genuine `stopReason ===
- * "aborted"` with content/errorMessage) preserve the prior behavior.
+ * Claude Code abort markers are intentionally ignored when the abort fires
+ * while the session-switch is in flight: the abort is the expected side-effect
+ * of the transition, not a user signal. Other branches (genuine `stopReason
+ * === "aborted"` with diagnostic content/errorMessage) preserve the prior
+ * behavior.
  */
 export function _handleSessionSwitchAgentEnd(
   lastMsg: unknown,
@@ -101,9 +143,14 @@ export function _handleSessionSwitchAgentEnd(
   if (!lastMsg || typeof lastMsg !== "object") return;
   const m = lastMsg as { stopReason?: unknown; errorMessage?: unknown; content?: unknown };
 
+  if (isClaudeCodeSessionSwitchAbortMessage(m)) {
+    // Internal abort from in-flight session transition — drop on the floor.
+    return;
+  }
+
   if (m.stopReason === "error") {
     const rawErrorMsg = m.errorMessage ? String(m.errorMessage) : "";
-    if (isUserInitiatedAbortMessage(rawErrorMsg)) {
+    if (isBareClaudeCodeSessionSwitchAbortMarker(rawErrorMsg)) {
       // Internal abort from in-flight session transition — drop on the floor.
       return;
     }
@@ -120,6 +167,18 @@ export function _handleSessionSwitchAgentEnd(
   }
 }
 
+export function resolveAgentEndErrorDisplay(
+  rawErrorMsg: string,
+  content: unknown,
+): string {
+  const isUseless = !rawErrorMsg || /^(success|ok|true|error|unknown)$/i.test(rawErrorMsg.trim());
+  if (isUseless && Array.isArray(content)) {
+    const textBlock = content.find((b: any) => b.type === "text" && b.text);
+    if (textBlock) return (textBlock as any).text.slice(0, 300);
+  }
+  return rawErrorMsg;
+}
+
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
   pi: ExtensionAPI,
@@ -204,6 +263,13 @@ export async function handleAgentEnd(
     return;
   }
 
+  if (isSessionSwitchAbortGraceActive() && isClaudeCodeSessionSwitchAbortMessage(lastMsg)) {
+    // Claude Code can report the abort from `newSession()` a few hundred ms
+    // after the guard drops. That event belongs to the old turn; do not let it
+    // cancel the freshly-dispatched unit.
+    return;
+  }
+
   if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") {
     // Empty content with aborted stopReason is a non-fatal agent stop (the LLM
     // chose to end without producing output). Only pause on genuine fatal aborts
@@ -243,15 +309,13 @@ export async function handleAgentEnd(
       });
       return;
     }
-    const isUseless = !rawErrorMsg || /^(success|ok|true|error|unknown)$/i.test(rawErrorMsg.trim());
     // #3588: When errorMessage is uninformative, extract the real error from
     // the assistant message text content for display purposes only.
     // Classification still uses rawErrorMsg to avoid false positives from prose.
-    let displayMsg = rawErrorMsg;
-    if (isUseless && "content" in lastMsg && Array.isArray(lastMsg.content)) {
-      const textBlock = lastMsg.content.find((b: any) => b.type === "text" && b.text);
-      if (textBlock) displayMsg = (textBlock as any).text.slice(0, 300);
-    }
+    const displayMsg = resolveAgentEndErrorDisplay(
+      rawErrorMsg,
+      "content" in lastMsg ? lastMsg.content : undefined,
+    );
     const errorDetail = displayMsg ? `: ${displayMsg}` : "";
     const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number") ? lastMsg.retryAfterMs : undefined;
 

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -5,7 +5,7 @@ import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { Text } from "@gsd/pi-tui";
 
 import { loadEffectiveGSDPreferences } from "../preferences.js";
-import { ensureDbOpen } from "./dynamic-tools.js";
+import { ensureDbOpen, resolveCtxCwd } from "./dynamic-tools.js";
 import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./write-gate.js";
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
@@ -16,12 +16,6 @@ async function loadWorkflowExecutors(): Promise<typeof import("../tools/workflow
   return import("../tools/workflow-tool-executors.js");
 }
 
-function toolWorkspaceRoot(ctx: unknown): string {
-  if (ctx && typeof ctx === "object" && typeof (ctx as { cwd?: unknown }).cwd === "string") {
-    return (ctx as { cwd: string }).cwd;
-  }
-  return process.cwd();
-}
 
 /**
  * Register an alias tool that shares the same execute function as its canonical counterpart.
@@ -72,7 +66,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_decision_save (formerly gsd_save_decision) ─────────────────────
 
   const decisionSaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
-    const basePath = toolWorkspaceRoot(_ctx);
+    const basePath = resolveCtxCwd(_ctx);
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
@@ -160,7 +154,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_requirement_update (formerly gsd_update_requirement) ───────────
 
   const requirementUpdateExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
-    const basePath = toolWorkspaceRoot(_ctx);
+    const basePath = resolveCtxCwd(_ctx);
     const gateBlock = requirementRootWriteGuard("update_requirement", basePath);
     if (gateBlock) return gateBlock;
     const dbAvailable = await ensureDbOpen(basePath);
@@ -241,7 +235,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_requirement_save ─────────────────────────────────────────────
 
   const requirementSaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
-    const basePath = toolWorkspaceRoot(_ctx);
+    const basePath = resolveCtxCwd(_ctx);
     const gateBlock = requirementRootWriteGuard("save_requirement", basePath);
     if (gateBlock) return gateBlock;
     const dbAvailable = await ensureDbOpen(basePath);
@@ -345,7 +339,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const summarySaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     const { executeSummarySave } = await loadWorkflowExecutors();
-    return executeSummarySave(params, toolWorkspaceRoot(_ctx));
+    return executeSummarySave(params, resolveCtxCwd(_ctx));
   };
 
   const summarySaveTool = {
@@ -396,7 +390,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const milestoneGenerateIdExecute = async (_toolCallId: string, _params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     try {
-      const basePath = toolWorkspaceRoot(_ctx);
+      const basePath = resolveCtxCwd(_ctx);
       // Claim a reserved ID if the guided-flow already previewed one to the user.
       // This guarantees the ID shown in the UI matches the one materialised on disk.
       const { claimReservedId, findMilestoneIds, getReservedMilestoneIds, nextMilestoneId } = await import("../guided-flow.js");
@@ -481,7 +475,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const planMilestoneExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     const { executePlanMilestone } = await loadWorkflowExecutors();
-    return executePlanMilestone(params, toolWorkspaceRoot(_ctx));
+    return executePlanMilestone(params, resolveCtxCwd(_ctx));
   };
 
   const planMilestoneTool = {
@@ -551,7 +545,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const planSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     const { executePlanSlice } = await loadWorkflowExecutors();
-    return executePlanSlice(params, toolWorkspaceRoot(_ctx));
+    return executePlanSlice(params, resolveCtxCwd(_ctx));
   };
 
   const planSliceTool = {
@@ -600,7 +594,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_plan_task (gsd_task_plan alias) ───────────────────────────────
 
   const planTaskExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
-    const basePath = toolWorkspaceRoot(_ctx);
+    const basePath = resolveCtxCwd(_ctx);
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
@@ -675,7 +669,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const taskCompleteExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     const { executeTaskComplete } = await loadWorkflowExecutors();
-    return executeTaskComplete(params, toolWorkspaceRoot(_ctx));
+    return executeTaskComplete(params, resolveCtxCwd(_ctx));
   };
 
   const taskCompleteTool = {
@@ -746,7 +740,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const sliceCompleteExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     const { executeSliceComplete } = await loadWorkflowExecutors();
-    return executeSliceComplete(params, toolWorkspaceRoot(_ctx));
+    return executeSliceComplete(params, resolveCtxCwd(_ctx));
   };
 
   const sliceCompleteTool = {
@@ -846,7 +840,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_skip_slice (#3477 / #3487) ───────────────────────────────────
 
   const skipSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
-    const basePath = toolWorkspaceRoot(_ctx);
+    const basePath = resolveCtxCwd(_ctx);
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
@@ -939,7 +933,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const milestoneCompleteExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     const { executeCompleteMilestone } = await loadWorkflowExecutors();
-    return executeCompleteMilestone(params, toolWorkspaceRoot(_ctx));
+    return executeCompleteMilestone(params, resolveCtxCwd(_ctx));
   };
 
   const milestoneCompleteTool = {
@@ -985,7 +979,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const milestoneValidateExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     const { executeValidateMilestone } = await loadWorkflowExecutors();
-    return executeValidateMilestone(params, toolWorkspaceRoot(_ctx));
+    return executeValidateMilestone(params, resolveCtxCwd(_ctx));
   };
 
   const milestoneValidateTool = {
@@ -1023,7 +1017,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const replanSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     const { executeReplanSlice } = await loadWorkflowExecutors();
-    return executeReplanSlice(params, toolWorkspaceRoot(_ctx));
+    return executeReplanSlice(params, resolveCtxCwd(_ctx));
   };
 
   const replanSliceTool = {
@@ -1074,7 +1068,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const reassessRoadmapExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     const { executeReassessRoadmap } = await loadWorkflowExecutors();
-    return executeReassessRoadmap(params, toolWorkspaceRoot(_ctx));
+    return executeReassessRoadmap(params, resolveCtxCwd(_ctx));
   };
 
   const reassessRoadmapTool = {
@@ -1133,7 +1127,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // Single-writer v3, Stream 3: reversibility tools for closed units.
 
   const reopenTaskExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
-    const basePath = toolWorkspaceRoot(_ctx);
+    const basePath = resolveCtxCwd(_ctx);
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
@@ -1200,7 +1194,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_slice_reopen (gsd_reopen_slice alias) ─────────────────────────
 
   const reopenSliceExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
-    const basePath = toolWorkspaceRoot(_ctx);
+    const basePath = resolveCtxCwd(_ctx);
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
@@ -1267,7 +1261,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_milestone_reopen (gsd_reopen_milestone alias) ─────────────────
 
   const reopenMilestoneExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
-    const basePath = toolWorkspaceRoot(_ctx);
+    const basePath = resolveCtxCwd(_ctx);
     const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
@@ -1333,7 +1327,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const saveGateResultExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     const { executeSaveGateResult } = await loadWorkflowExecutors();
-    return executeSaveGateResult(params, toolWorkspaceRoot(_ctx));
+    return executeSaveGateResult(params, resolveCtxCwd(_ctx));
   };
 
   const saveGateResultTool = {

package/src/resources/extensions/gsd/bootstrap/dynamic-tools.ts

@@ -1,4 +1,7 @@
+// Project/App: GSD-2
+// File Purpose: Registers workspace-aware dynamic filesystem and shell tools.
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname } from "node:path";
 
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
@@ -8,11 +11,22 @@ import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
 import { setLogBasePath, logWarning } from "../workflow-logger.js";
 import { resolveGsdPathContract } from "../paths.js";
 
-function resolveToolWorkspaceRoot(ctx?: unknown): string {
+export function safeWorkspaceCwd(): string {
+  try {
+    return process.cwd();
+  } catch {
+    const projectRoot = process.env.GSD_PROJECT_ROOT;
+    if (projectRoot && existsSync(projectRoot)) return projectRoot;
+    return homedir();
+  }
+}
+
+export function resolveCtxCwd(ctx?: unknown): string {
   if (ctx && typeof ctx === "object" && typeof (ctx as { cwd?: unknown }).cwd === "string") {
-    return (ctx as { cwd: string }).cwd;
+    const cwd = (ctx as { cwd: string }).cwd;
+    if (existsSync(cwd)) return cwd;
   }
-  return process.cwd();
+  return safeWorkspaceCwd();
 }
 
 /**
@@ -25,7 +39,7 @@ export function resolveProjectRootDbPath(basePath: string): string {
   return resolveGsdPathContract(basePath).projectDb;
 }
 
-export async function ensureDbOpen(basePath: string = process.cwd()): Promise<boolean> {
+export async function ensureDbOpen(basePath: string = safeWorkspaceCwd()): Promise<boolean> {
   try {
     const db = await import("../gsd-db.js");
     const contract = resolveGsdPathContract(basePath);
@@ -57,7 +71,8 @@ export async function ensureDbOpen(basePath: string = process.cwd()): Promise<bo
 }
 
 export function registerDynamicTools(pi: ExtensionAPI): void {
-  const baseBash = createBashTool(process.cwd(), {
+  const fallbackRoot = safeWorkspaceCwd();
+  const baseBash = createBashTool(fallbackRoot, {
     spawnHook: (ctx) => ctx,
   });
   const dynamicBash = {
@@ -69,7 +84,7 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
       onUpdate?: unknown,
       ctx?: unknown,
     ) => {
-      const basePath = resolveToolWorkspaceRoot(ctx);
+      const basePath = resolveCtxCwd(ctx);
       const fresh = createBashTool(basePath, {
         spawnHook: (spawnCtx) => ({ ...spawnCtx, cwd: basePath }),
       });
@@ -82,7 +97,7 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
   };
   pi.registerTool(dynamicBash as any);
 
-  const baseWrite = createWriteTool(process.cwd());
+  const baseWrite = createWriteTool(fallbackRoot);
   pi.registerTool({
     ...baseWrite,
     execute: async (
@@ -92,12 +107,12 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
       onUpdate?: unknown,
       ctx?: unknown,
     ) => {
-      const fresh = createWriteTool(resolveToolWorkspaceRoot(ctx));
+      const fresh = createWriteTool(resolveCtxCwd(ctx));
       return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
     },
   } as any);
 
-  const baseRead = createReadTool(process.cwd());
+  const baseRead = createReadTool(fallbackRoot);
   pi.registerTool({
     ...baseRead,
     execute: async (
@@ -107,12 +122,12 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
       onUpdate?: unknown,
       ctx?: unknown,
     ) => {
-      const fresh = createReadTool(resolveToolWorkspaceRoot(ctx));
+      const fresh = createReadTool(resolveCtxCwd(ctx));
       return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
     },
   } as any);
 
-  const baseEdit = createEditTool(process.cwd());
+  const baseEdit = createEditTool(fallbackRoot);
   pi.registerTool({
     ...baseEdit,
     execute: async (
@@ -122,7 +137,7 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
       onUpdate?: unknown,
       ctx?: unknown,
     ) => {
-      const fresh = createEditTool(resolveToolWorkspaceRoot(ctx));
+      const fresh = createEditTool(resolveCtxCwd(ctx));
       return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
     },
   } as any);