gsd-pi 2.80.0 → 2.81.0

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

@@ -1,5 +1,8 @@
+// GSD-2 + src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts - Handles provider and agent-end recovery for GSD auto-mode.
+
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
+import type { AgentEndEvent, ErrorContext } from "../auto/types.js";
 import { logWarning } from "../workflow-logger.js";
 import {
   checkDeepProjectSetupAfterTurn,
@@ -12,7 +15,13 @@ 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 } from "../auto/resolve.js";
+import {
+  isSessionSwitchAbortGraceActive,
+  isSessionSwitchInFlight,
+  resolveAgentEnd,
+  resolveAgentEndCancelled,
+} from "../auto/resolve.js";
+import { shouldIgnoreAgentEndForActiveUnit } from "../auto/unit-runner-events.js";
 import { resolveModelId } from "../auto-model-selection.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
@@ -28,6 +37,10 @@ import { blockModel, isModelBlocked } from "../blocked-models.js";
 
 const retryState = createRetryState();
 const MAX_NETWORK_RETRIES = 2;
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object";
+}
 /**
  * Cap on auto-resume attempts for sustained transient-provider errors.
  *
@@ -69,6 +82,116 @@ export function _buildAbortedPauseContext(lastMsg: { errorMessage?: unknown }):
   };
 }
 
+export function isUserInitiatedAbortMessage(message: string | undefined | null): boolean {
+  if (!message) return false;
+  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;
+}
+
+export function isBareClaudeCodeStreamAbortPlaceholder(lastMsg: unknown): boolean {
+  if (!lastMsg || typeof lastMsg !== "object") return false;
+  const m = lastMsg as { stopReason?: unknown; errorMessage?: unknown; content?: unknown };
+  if (m.stopReason !== "aborted" || m.errorMessage) return false;
+  const text = readAssistantTextContent(m.content).trim().replace(/\s+/g, " ").toLowerCase();
+  return text === "claude code stream aborted by caller";
+}
+
+/**
+ * Resolve an agent_end event observed while a session switch is in flight.
+ *
+ * #5538-followup: When `newSession()` aborts an in-flight stream as part of a
+ * session transition (run-unit.ts:63 → _settleCurrentTurnForSessionTransition
+ * → agent.abort()), the SDK emits "Claude Code process aborted by user" or
+ * "Request aborted by user" against the previous unit's turn. The previous
+ * code path treated that as a user cancellation and propagated it to the next
+ * unit via the pending-switch-cancellation queue, killing auto-mode with
+ * "Auto-mode stopped — Unit aborted: Claude Code process aborted by user"
+ * even though no user input occurred.
+ *
+ * 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,
+  resolveCancelled: (ctx: ErrorContext) => boolean,
+): void {
+  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 (isBareClaudeCodeSessionSwitchAbortMarker(rawErrorMsg)) {
+      // Internal abort from in-flight session transition — drop on the floor.
+      return;
+    }
+    return;
+  }
+
+  if (m.stopReason === "aborted") {
+    const content = m.content;
+    const hasEmptyContent = Array.isArray(content) && content.length === 0;
+    const hasErrorMessage = !!m.errorMessage;
+    if (!hasEmptyContent || hasErrorMessage) {
+      resolveCancelled(_buildAbortedPauseContext(m as { errorMessage?: unknown }));
+    }
+  }
+}
+
+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,
@@ -105,7 +228,7 @@ async function pauseTransientWithBackoff(
 
 export async function handleAgentEnd(
   pi: ExtensionAPI,
-  event: { messages: any[] },
+  event: AgentEndEvent,
   ctx: ExtensionContext,
 ): Promise<void> {
   // #4648 — Invalidate the directory-listing cache before any artifact-existence
@@ -146,10 +269,32 @@ export async function handleAgentEnd(
   if (maybeHandleEmptyIntentTurn(event, isAutoActive())) return;
 
   if (!isAutoActive()) return;
-  if (isSessionSwitchInFlight()) return;
+
+  if (shouldIgnoreAgentEndForActiveUnit(event)) {
+    return;
+  }
 
   const lastMsg = event.messages[event.messages.length - 1];
-  if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "aborted") {
+  if (isSessionSwitchInFlight()) {
+    _handleSessionSwitchAgentEnd(lastMsg, resolveAgentEndCancelled);
+    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 (isBareClaudeCodeStreamAbortPlaceholder(lastMsg)) {
+    // The Claude Code adapter can emit this placeholder after a prior turn has
+    // already completed and the next unit is active. It has no user/provider
+    // diagnostic value and must not cancel the newly-dispatched unit.
+    return;
+  }
+
+  if (isObjectRecord(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
     // that carry error context — e.g. errorMessage field or non-empty content
@@ -175,20 +320,26 @@ export async function handleAgentEnd(
     await pauseAuto(ctx, pi, _buildAbortedPauseContext(lastMsg as { errorMessage?: unknown }));
     return;
   }
-  if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {
+  if (isObjectRecord(lastMsg) && "stopReason" in lastMsg && lastMsg.stopReason === "error") {
     // #3588: errorMessage can be useless (e.g. "success") while the real error
     // is in the assistant message text content. Fall back to content when
     // errorMessage looks uninformative.
     const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
-    const isUseless = !rawErrorMsg || /^(success|ok|true|error|unknown)$/i.test(rawErrorMsg.trim());
+    if (isUserInitiatedAbortMessage(rawErrorMsg)) {
+      resolveAgentEndCancelled({
+        message: rawErrorMsg,
+        category: "aborted",
+        isTransient: false,
+      });
+      return;
+    }
     // #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

@@ -1,34 +1,46 @@
+// Project/App: GSD-2
+// File Purpose: Registers DB-backed GSD workflow tools and compatibility aliases.
 import { Type } from "@sinclair/typebox";
 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";
 import { getErrorMessage } from "../error-utils.js";
+import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
 
 async function loadWorkflowExecutors(): Promise<typeof import("../tools/workflow-tool-executors.js")> {
   return import("../tools/workflow-tool-executors.js");
 }
 
+
 /**
  * Register an alias tool that shares the same execute function as its canonical counterpart.
  * The alias description and promptGuidelines direct the LLM to prefer the canonical name.
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- toolDef shape matches ToolDefinition but typing it fully requires generics
 function registerAlias(pi: ExtensionAPI, toolDef: any, aliasName: string, canonicalName: string): void {
+  const execute = typeof toolDef.execute === "function"
+    ? async (...args: any[]) => {
+        incrementLegacyTelemetry("legacy.mcpAliasUsed");
+        return toolDef.execute(...args);
+      }
+    : toolDef.execute;
+
   pi.registerTool({
     ...toolDef,
     name: aliasName,
     description: toolDef.description + ` (alias for ${canonicalName} — prefer the canonical name)`,
     promptGuidelines: [`Alias for ${canonicalName} — prefer the canonical name.`],
+    execute,
   });
 }
 
-function requirementRootWriteGuard(operation: string): { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown>; isError: true } | null {
-  const guard = shouldBlockRootArtifactSaveInSnapshot(loadWriteGateSnapshot(process.cwd()), "REQUIREMENTS");
+function requirementRootWriteGuard(operation: string, basePath: string): { content: Array<{ type: "text"; text: string }>; details: Record<string, unknown>; isError: true } | null {
+  const guard = shouldBlockRootArtifactSaveInSnapshot(loadWriteGateSnapshot(basePath), "REQUIREMENTS");
   if (!guard.block) return null;
   return {
     content: [{ type: "text", text: `Error ${operation} requirement: ${guard.reason ?? "requirements write blocked"}` }],
@@ -54,7 +66,8 @@ 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 dbAvailable = await ensureDbOpen();
+    const basePath = resolveCtxCwd(_ctx);
+    const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
         content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save decision." }],
@@ -73,7 +86,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
           when_context: params.when_context,
           made_by: params.made_by,
         },
-        process.cwd(),
+        basePath,
       );
       return {
         content: [{ type: "text" as const, text: `Saved decision ${id}` }],
@@ -141,9 +154,10 @@ 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 gateBlock = requirementRootWriteGuard("update_requirement");
+    const basePath = resolveCtxCwd(_ctx);
+    const gateBlock = requirementRootWriteGuard("update_requirement", basePath);
     if (gateBlock) return gateBlock;
-    const dbAvailable = await ensureDbOpen();
+    const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
         content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot update requirement." }],
@@ -159,7 +173,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
       if (params.description !== undefined) updates.description = params.description;
       if (params.primary_owner !== undefined) updates.primary_owner = params.primary_owner;
       if (params.supporting_slices !== undefined) updates.supporting_slices = params.supporting_slices;
-      await updateRequirementInDb(params.id, updates, process.cwd());
+      await updateRequirementInDb(params.id, updates, basePath);
       return {
         content: [{ type: "text" as const, text: `Updated requirement ${params.id}` }],
         details: { operation: "update_requirement", id: params.id } as any,
@@ -221,9 +235,10 @@ export function registerDbTools(pi: ExtensionAPI): void {
   // ─── gsd_requirement_save ─────────────────────────────────────────────
 
   const requirementSaveExecute = async (_toolCallId: string, params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
-    const gateBlock = requirementRootWriteGuard("save_requirement");
+    const basePath = resolveCtxCwd(_ctx);
+    const gateBlock = requirementRootWriteGuard("save_requirement", basePath);
     if (gateBlock) return gateBlock;
-    const dbAvailable = await ensureDbOpen();
+    const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
         content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot save requirement." }],
@@ -244,7 +259,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
           validation: params.validation,
           notes: params.notes,
         },
-        process.cwd(),
+        basePath,
       );
       return {
         content: [{ type: "text" as const, text: `Saved requirement ${result.id}` }],
@@ -324,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, process.cwd());
+    return executeSummarySave(params, resolveCtxCwd(_ctx));
   };
 
   const summarySaveTool = {
@@ -375,24 +390,24 @@ export function registerDbTools(pi: ExtensionAPI): void {
 
   const milestoneGenerateIdExecute = async (_toolCallId: string, _params: any, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: unknown) => {
     try {
+      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");
       const reserved = claimReservedId();
       if (reserved) {
-        await ensureMilestoneDbRow(reserved);
+        await ensureMilestoneDbRow(reserved, basePath);
         return {
           content: [{ type: "text" as const, text: reserved }],
           details: { operation: "generate_milestone_id", id: reserved, source: "reserved" } as any,
         };
       }
 
-      const basePath = process.cwd();
       const existingIds = findMilestoneIds(basePath);
-      const uniqueEnabled = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
+      const uniqueEnabled = !!loadEffectiveGSDPreferences(basePath)?.preferences?.unique_milestone_ids;
       const allIds = [...new Set([...existingIds, ...getReservedMilestoneIds()])];
       const newId = nextMilestoneId(allIds, uniqueEnabled);
-      await ensureMilestoneDbRow(newId);
+      await ensureMilestoneDbRow(newId, basePath);
       return {
         content: [{ type: "text" as const, text: newId }],
         details: { operation: "generate_milestone_id", id: newId, existingCount: existingIds.length, uniqueEnabled } as any,
@@ -412,8 +427,8 @@ export function registerDbTools(pi: ExtensionAPI): void {
    * later writes the full row. Silently skips if the DB isn't available yet
    * (pre-migration).
    */
-  async function ensureMilestoneDbRow(milestoneId: string): Promise<void> {
-    const dbAvailable = await ensureDbOpen();
+  async function ensureMilestoneDbRow(milestoneId: string, basePath: string): Promise<void> {
+    const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) return;
     try {
       const { insertMilestone } = await import("../gsd-db.js");
@@ -460,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, process.cwd());
+    return executePlanMilestone(params, resolveCtxCwd(_ctx));
   };
 
   const planMilestoneTool = {
@@ -530,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, process.cwd());
+    return executePlanSlice(params, resolveCtxCwd(_ctx));
   };
 
   const planSliceTool = {
@@ -579,7 +594,8 @@ 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 dbAvailable = await ensureDbOpen();
+    const basePath = resolveCtxCwd(_ctx);
+    const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
         content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot plan task." }],
@@ -588,7 +604,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     }
     try {
       const { handlePlanTask } = await import("../tools/plan-task.js");
-      const result = await handlePlanTask(params, process.cwd());
+      const result = await handlePlanTask(params, basePath);
       if ("error" in result) {
         return {
           content: [{ type: "text" as const, text: `Error planning task: ${result.error}` }],
@@ -653,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, process.cwd());
+    return executeTaskComplete(params, resolveCtxCwd(_ctx));
   };
 
   const taskCompleteTool = {
@@ -724,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, process.cwd());
+    return executeSliceComplete(params, resolveCtxCwd(_ctx));
   };
 
   const sliceCompleteTool = {
@@ -824,7 +840,8 @@ 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 dbAvailable = await ensureDbOpen();
+    const basePath = resolveCtxCwd(_ctx);
+    const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
         content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot skip slice." }],
@@ -857,7 +874,6 @@ export function registerDbTools(pi: ExtensionAPI): void {
       // Rebuild STATE.md so it reflects the skip immediately (#3477).
       // Without this, /gsd auto reads stale STATE.md and resumes the skipped slice.
       try {
-        const basePath = process.cwd();
         const { rebuildState } = await import("../doctor.js");
         await rebuildState(basePath);
       } catch (err) {
@@ -917,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, process.cwd());
+    return executeCompleteMilestone(params, resolveCtxCwd(_ctx));
   };
 
   const milestoneCompleteTool = {
@@ -963,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, process.cwd());
+    return executeValidateMilestone(params, resolveCtxCwd(_ctx));
   };
 
   const milestoneValidateTool = {
@@ -1001,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, process.cwd());
+    return executeReplanSlice(params, resolveCtxCwd(_ctx));
   };
 
   const replanSliceTool = {
@@ -1052,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, process.cwd());
+    return executeReassessRoadmap(params, resolveCtxCwd(_ctx));
   };
 
   const reassessRoadmapTool = {
@@ -1111,7 +1127,8 @@ 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 dbAvailable = await ensureDbOpen();
+    const basePath = resolveCtxCwd(_ctx);
+    const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
         content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot reopen task." }],
@@ -1120,7 +1137,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     }
     try {
       const { handleReopenTask } = await import("../tools/reopen-task.js");
-      const result = await handleReopenTask(params, process.cwd());
+      const result = await handleReopenTask(params, basePath);
       if ("error" in result) {
         return {
           content: [{ type: "text" as const, text: `Error reopening task: ${result.error}` }],
@@ -1177,7 +1194,8 @@ 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 dbAvailable = await ensureDbOpen();
+    const basePath = resolveCtxCwd(_ctx);
+    const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
         content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot reopen slice." }],
@@ -1186,7 +1204,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     }
     try {
       const { handleReopenSlice } = await import("../tools/reopen-slice.js");
-      const result = await handleReopenSlice(params, process.cwd());
+      const result = await handleReopenSlice(params, basePath);
       if ("error" in result) {
         return {
           content: [{ type: "text" as const, text: `Error reopening slice: ${result.error}` }],
@@ -1243,7 +1261,8 @@ 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 dbAvailable = await ensureDbOpen();
+    const basePath = resolveCtxCwd(_ctx);
+    const dbAvailable = await ensureDbOpen(basePath);
     if (!dbAvailable) {
       return {
         content: [{ type: "text" as const, text: "Error: GSD database is not available. Cannot reopen milestone." }],
@@ -1252,7 +1271,7 @@ export function registerDbTools(pi: ExtensionAPI): void {
     }
     try {
       const { handleReopenMilestone } = await import("../tools/reopen-milestone.js");
-      const result = await handleReopenMilestone(params, process.cwd());
+      const result = await handleReopenMilestone(params, basePath);
       if ("error" in result) {
         return {
           content: [{ type: "text" as const, text: `Error reopening milestone: ${result.error}` }],
@@ -1308,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, process.cwd());
+    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,6 +11,24 @@ import { DEFAULT_BASH_TIMEOUT_SECS } from "../constants.js";
 import { setLogBasePath, logWarning } from "../workflow-logger.js";
 import { resolveGsdPathContract } from "../paths.js";
 
+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") {
+    const cwd = (ctx as { cwd: string }).cwd;
+    if (existsSync(cwd)) return cwd;
+  }
+  return safeWorkspaceCwd();
+}
+
 /**
  * Resolve the correct DB path for the current working directory.
  * If `basePath` is inside a `.gsd/worktrees/<MID>/` directory, returns
@@ -18,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);
@@ -50,8 +71,9 @@ export async function ensureDbOpen(basePath: string = process.cwd()): Promise<bo
 }
 
 export function registerDynamicTools(pi: ExtensionAPI): void {
-  const baseBash = createBashTool(process.cwd(), {
-    spawnHook: (ctx) => ({ ...ctx, cwd: process.cwd() }),
+  const fallbackRoot = safeWorkspaceCwd();
+  const baseBash = createBashTool(fallbackRoot, {
+    spawnHook: (ctx) => ctx,
   });
   const dynamicBash = {
     ...baseBash,
@@ -62,16 +84,20 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
       onUpdate?: unknown,
       ctx?: unknown,
     ) => {
+      const basePath = resolveCtxCwd(ctx);
+      const fresh = createBashTool(basePath, {
+        spawnHook: (spawnCtx) => ({ ...spawnCtx, cwd: basePath }),
+      });
       const paramsWithTimeout = {
         ...params,
         timeout: params.timeout ?? DEFAULT_BASH_TIMEOUT_SECS,
       };
-      return (baseBash as any).execute(toolCallId, paramsWithTimeout, signal, onUpdate, ctx);
+      return (fresh as any).execute(toolCallId, paramsWithTimeout, signal, onUpdate, ctx);
     },
   };
   pi.registerTool(dynamicBash as any);
 
-  const baseWrite = createWriteTool(process.cwd());
+  const baseWrite = createWriteTool(fallbackRoot);
   pi.registerTool({
     ...baseWrite,
     execute: async (
@@ -81,12 +107,12 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
       onUpdate?: unknown,
       ctx?: unknown,
     ) => {
-      const fresh = createWriteTool(process.cwd());
+      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 (
@@ -96,12 +122,12 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
       onUpdate?: unknown,
       ctx?: unknown,
     ) => {
-      const fresh = createReadTool(process.cwd());
+      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 (
@@ -111,7 +137,7 @@ export function registerDynamicTools(pi: ExtensionAPI): void {
       onUpdate?: unknown,
       ctx?: unknown,
     ) => {
-      const fresh = createEditTool(process.cwd());
+      const fresh = createEditTool(resolveCtxCwd(ctx));
       return (fresh as any).execute(toolCallId, params, signal, onUpdate, ctx);
     },
   } as any);