@opengsd/gsd-pi 1.2.0-dev.955e4da0 → 1.2.0-dev.a6376d75

package/dist/resources/extensions/gsd/workflow-event-ledger.js

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+import { resolveGsdPathContract } from "./paths.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
+import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
+import { normalizeWorkflowEventCommand } from "./workflow-event-vocabulary.js";
+export const WORKFLOW_EVENT_LOG_FILENAME = "event-log.jsonl";
+export function resolveWorkflowEventLedgerLocation(basePath, originalProjectRoot) {
+    const contract = resolveGsdPathContract(basePath, originalProjectRoot);
+    return {
+        projectRoot: contract.projectRoot,
+        workRoot: contract.workRoot,
+        projectGsd: contract.projectGsd,
+        worktreeGsd: contract.worktreeGsd,
+        projectLogPath: join(contract.projectGsd, WORKFLOW_EVENT_LOG_FILENAME),
+        worktreeLogPath: contract.worktreeGsd
+            ? join(contract.worktreeGsd, WORKFLOW_EVENT_LOG_FILENAME)
+            : null,
+        isWorktree: contract.isWorktree,
+    };
+}
+export function workflowEventLogPath(basePath) {
+    return resolveWorkflowEventLedgerLocation(basePath).projectLogPath;
+}
+export function workflowEventArchivePath(basePath, milestoneId) {
+    const location = resolveWorkflowEventLedgerLocation(basePath);
+    return join(location.projectGsd, `event-log-${milestoneId}.jsonl.archived`);
+}
+export function readWorktreeEventLogPath(worktreeBasePath) {
+    const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+    return location.worktreeLogPath ?? location.projectLogPath;
+}
+export function buildWorkflowEvent(event, sessionId) {
+    const hash = createHash("sha256")
+        .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
+        .digest("hex")
+        .slice(0, 16);
+    return {
+        v: 2,
+        ...event,
+        hash,
+        session_id: sessionId,
+    };
+}
+export function appendWorkflowEvent(basePath, event, sessionId) {
+    const fullEvent = buildWorkflowEvent(event, sessionId);
+    const location = resolveWorkflowEventLedgerLocation(basePath);
+    mkdirSync(location.projectGsd, { recursive: true });
+    appendFileSync(location.projectLogPath, `${JSON.stringify(fullEvent)}\n`, "utf-8");
+    emitWorkflowEventAudit(location.projectRoot, fullEvent);
+    return fullEvent;
+}
+export function writeWorkflowEventLog(basePath, events) {
+    const location = resolveWorkflowEventLedgerLocation(basePath);
+    mkdirSync(location.projectGsd, { recursive: true });
+    const content = events.map((event) => JSON.stringify(event)).join("\n") + (events.length > 0 ? "\n" : "");
+    atomicWriteSync(location.projectLogPath, content);
+}
+export function writeWorktreeEventLog(worktreeBasePath, events) {
+    const location = resolveWorkflowEventLedgerLocation(worktreeBasePath);
+    const logPath = location.worktreeLogPath ?? location.projectLogPath;
+    mkdirSync(dirname(logPath), { recursive: true });
+    const content = events.map((event) => JSON.stringify(event)).join("\n") + (events.length > 0 ? "\n" : "");
+    atomicWriteSync(logPath, content);
+}
+function emitWorkflowEventAudit(basePath, event) {
+    if (!isUnifiedAuditEnabled())
+        return;
+    try {
+        const normalized = normalizeWorkflowEventCommand(event.cmd) ?? "unknown";
+        emitUokAuditEvent(basePath, buildAuditEnvelope({
+            traceId: event.session_id,
+            category: "orchestration",
+            type: `workflow-event-${normalized}`,
+            payload: {
+                cmd: event.cmd,
+                params: event.params,
+                actor: event.actor,
+                actorName: event.actor_name,
+                triggerReason: event.trigger_reason,
+                eventTs: event.ts,
+                hash: event.hash,
+            },
+        }));
+    }
+    catch {
+        // Best-effort: audit projection must never block the workflow event ledger.
+    }
+}

package/dist/resources/extensions/gsd/workflow-event-vocabulary.js

@@ -0,0 +1,46 @@
+export function normalizeWorkflowEventCommand(cmd) {
+    return typeof cmd === "string" ? cmd.replace(/-/g, "_") : null;
+}
+/**
+ * Workflow progress events are keyed by the domain entity they mutate.
+ * Keep command aliases and conflict identity in this module so replay,
+ * conflict detection, and tests do not each grow their own vocabulary.
+ */
+export function workflowEventEntityKey(event) {
+    const p = event.params;
+    const cmd = normalizeWorkflowEventCommand(event.cmd);
+    if (!cmd)
+        return null;
+    switch (cmd) {
+        case "complete_task":
+        case "start_task":
+        case "skip_task":
+        case "report_blocker":
+        case "record_verification":
+        case "plan_task":
+            return typeof p["taskId"] === "string"
+                ? { type: "task", id: p["taskId"] }
+                : null;
+        case "complete_slice":
+        case "replan_slice":
+            return typeof p["sliceId"] === "string"
+                ? { type: "slice", id: p["sliceId"] }
+                : null;
+        case "plan_slice":
+            return typeof p["sliceId"] === "string"
+                ? { type: "slice_plan", id: p["sliceId"] }
+                : null;
+        case "complete_milestone":
+        case "plan_milestone":
+            return typeof p["milestoneId"] === "string"
+                ? { type: "milestone", id: p["milestoneId"] }
+                : null;
+        case "save_decision":
+            if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
+                return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
+            }
+            return null;
+        default:
+            return null;
+    }
+}

package/dist/resources/extensions/gsd/workflow-events.js

@@ -1,8 +1,8 @@
-import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { withFileLockSync } from "./file-lock.js";
+import { appendWorkflowEvent, workflowEventArchivePath, workflowEventLogPath, } from "./workflow-event-ledger.js";
 import { logWarning } from "./workflow-logger.js";
 // ─── Session ID ───────────────────────────────────────────────────────────
 /**
@@ -20,19 +20,7 @@ export function getSessionId() {
  * Creates .gsd directory if needed.
  */
 export function appendEvent(basePath, event) {
-    const hash = createHash("sha256")
-        .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
-        .digest("hex")
-        .slice(0, 16);
-    const fullEvent = {
-        v: 2,
-        ...event,
-        hash,
-        session_id: ENGINE_SESSION_ID,
-    };
-    const dir = join(basePath, ".gsd");
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(join(dir, "event-log.jsonl"), JSON.stringify(fullEvent) + "\n", "utf-8");
+    appendWorkflowEvent(basePath, event, ENGINE_SESSION_ID);
 }
 // ─── readEvents ──────────────────────────────────────────────────────────
 /**
@@ -87,8 +75,8 @@ export function findForkPoint(logA, logB) {
  * @returns { archived: number } — count of events moved to archive
  */
 export function compactMilestoneEvents(basePath, milestoneId) {
-    const logPath = join(basePath, ".gsd", "event-log.jsonl");
-    const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`);
+    const logPath = workflowEventLogPath(basePath);
+    const archivePath = workflowEventArchivePath(basePath, milestoneId);
     return withFileLockSync(logPath, () => {
         const allEvents = readEvents(logPath);
         // Single-pass partition to halve the work (per reviewer agent)

package/dist/resources/extensions/gsd/workflow-mcp-auto-prep.js

@@ -1,4 +1,5 @@
 import { ensureProjectWorkflowMcpConfig, } from "./mcp-project-config.js";
+import { warmWorkflowMcpProbeInBackground } from "./workflow-mcp-readiness-cache.js";
 import { usesWorkflowMcpTransport } from "./workflow-mcp.js";
 function withModelOverride(ctx, modelOverride) {
     if (!modelOverride)
@@ -46,6 +47,7 @@ export function prepareWorkflowMcpForProject(ctx, projectRoot, modelOverride) {
         if (result.status !== "unchanged") {
             prepCtx.ui?.notify?.(`GSD MCP Server Prepared at ${result.configPath}`, "info");
         }
+        warmWorkflowMcpProbeInBackground(projectRoot);
         return result;
     }
     catch (err) {

package/dist/resources/extensions/gsd/workflow-mcp-readiness-cache.js

@@ -0,0 +1,105 @@
+// Project/App: gsd-pi
+// File Purpose: Share recent workflow MCP probe results across guided-flow and Claude Code SDK preflight.
+import { testMcpServerConnection } from "../mcp-client/manager.js";
+import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import { detectWorkflowMcpLaunchConfig, resolveWorkflowMcpProjectRoot, } from "./workflow-mcp.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+/** Reuse a recent successful probe instead of spawning another stdio server. */
+export const WORKFLOW_MCP_PROBE_CACHE_TTL_MS = 120_000;
+/** Per-probe connect + tools/list budget (server typically ready in ~1–2s). */
+export const WORKFLOW_MCP_PROBE_TIMEOUT_MS = 5_000;
+const cacheByProject = new Map();
+const probeInFlightByProject = new Map();
+let activeWorkflowMcpSdkSessions = 0;
+function cacheKey(projectRoot) {
+    return resolveWorkflowMcpProjectRoot(projectRoot);
+}
+export function beginWorkflowMcpSdkSession() {
+    activeWorkflowMcpSdkSessions++;
+}
+export function endWorkflowMcpSdkSession() {
+    activeWorkflowMcpSdkSessions = Math.max(0, activeWorkflowMcpSdkSessions - 1);
+}
+export function getCachedWorkflowMcpProbe(projectRoot) {
+    const entry = cacheByProject.get(cacheKey(projectRoot));
+    if (!entry)
+        return null;
+    if (Date.now() - entry.probedAt > WORKFLOW_MCP_PROBE_CACHE_TTL_MS) {
+        cacheByProject.delete(cacheKey(projectRoot));
+        return null;
+    }
+    return entry;
+}
+export function recordWorkflowMcpProbe(projectRoot, serverName, tools) {
+    cacheByProject.set(cacheKey(projectRoot), {
+        serverName,
+        tools: [...tools],
+        probedAt: Date.now(),
+    });
+}
+export function clearWorkflowMcpProbeCache(projectRoot) {
+    if (projectRoot === undefined) {
+        cacheByProject.clear();
+        probeInFlightByProject.clear();
+        activeWorkflowMcpSdkSessions = 0;
+        return;
+    }
+    const key = cacheKey(projectRoot);
+    cacheByProject.delete(key);
+    probeInFlightByProject.delete(key);
+}
+export function workflowMcpProbeAdvertisesSurface(tools) {
+    return tools.some((tool) => isWorkflowToolSurfaceName(tool));
+}
+export function cachedWorkflowMcpCoversRequired(projectRoot, serverName, required) {
+    const entry = getCachedWorkflowMcpProbe(projectRoot);
+    if (!entry || entry.serverName !== serverName)
+        return false;
+    return required.every((tool) => entry.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)));
+}
+async function runProbeAndCacheWorkflowMcp(projectRoot, options = {}) {
+    const root = cacheKey(projectRoot);
+    const launch = detectWorkflowMcpLaunchConfig(root);
+    const serverName = launch?.name ?? "gsd-workflow";
+    const cached = getCachedWorkflowMcpProbe(projectRoot);
+    if (cached && workflowMcpProbeAdvertisesSurface(cached.tools)) {
+        return { ok: true, tools: cached.tools, serverName: cached.serverName };
+    }
+    const result = await testMcpServerConnection(serverName, {
+        projectDir: root,
+        timeoutMs: options.timeoutMs ?? WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+    });
+    if (result.ok && workflowMcpProbeAdvertisesSurface(result.tools)) {
+        recordWorkflowMcpProbe(projectRoot, serverName, result.tools);
+    }
+    return {
+        ok: result.ok,
+        tools: result.tools,
+        serverName,
+        error: result.error,
+    };
+}
+export async function probeAndCacheWorkflowMcp(projectRoot, options = {}) {
+    const key = cacheKey(projectRoot);
+    const inFlight = probeInFlightByProject.get(key);
+    if (inFlight)
+        return inFlight;
+    const promise = runProbeAndCacheWorkflowMcp(projectRoot, options).finally(() => {
+        probeInFlightByProject.delete(key);
+    });
+    probeInFlightByProject.set(key, promise);
+    return promise;
+}
+/** Fire-and-forget probe so /gsd dispatch often hits a warm cache. */
+export function warmWorkflowMcpProbeInBackground(projectRoot) {
+    if (activeWorkflowMcpSdkSessions > 0)
+        return;
+    const key = cacheKey(projectRoot);
+    if (getCachedWorkflowMcpProbe(projectRoot))
+        return;
+    if (probeInFlightByProject.has(key))
+        return;
+    void probeAndCacheWorkflowMcp(projectRoot).catch(() => {
+        // Background warm is best-effort.
+    });
+}

package/dist/resources/extensions/gsd/workflow-reconcile.js

@@ -2,6 +2,8 @@ import { join } from "node:path";
 import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readEvents, findForkPoint, getSessionId } from "./workflow-events.js";
+import { normalizeWorkflowEventCommand, workflowEventEntityKey, } from "./workflow-event-vocabulary.js";
+import { readWorktreeEventLogPath, workflowEventLogPath, writeWorkflowEventLog, writeWorktreeEventLog, } from "./workflow-event-ledger.js";
 import { transaction, updateTaskStatus, updateSliceStatus, updateMilestoneStatus, getSliceTasks, insertMilestone, getMilestoneSlices, insertVerificationEvidence, upsertDecision, setTaskBlockerDiscovered, insertOrIgnoreSlice, insertOrIgnoreTask, } from "./gsd-db.js";
 import { openWorkflowDatabasePath } from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
@@ -48,14 +50,11 @@ function replayEvents(events) {
     transaction(() => {
         for (const event of events) {
             const p = event.params;
-            // Normalize cmd format: completion tools write hyphens ("complete-task"),
-            // legacy logs use underscores ("complete_task"). Accept both formats.
-            // Type guard: malformed event lines with non-string cmd are skipped.
-            if (typeof event.cmd !== "string") {
+            const cmd = normalizeWorkflowEventCommand(event.cmd);
+            if (!cmd) {
                 logWarning("reconcile", `Event with non-string cmd skipped: ${JSON.stringify(event.cmd)}`);
                 continue;
             }
-            const cmd = event.cmd.replace(/-/g, "_");
             switch (cmd) {
                 case "complete_task": {
                     const milestoneId = p["milestoneId"];
@@ -199,43 +198,7 @@ function replayEvents(events) {
  * (e.g. unknown or future cmds).
  */
 export function extractEntityKey(event) {
-    const p = event.params;
-    // Normalize cmd format: accept both hyphens and underscores
-    if (typeof event.cmd !== "string")
-        return null;
-    const cmd = event.cmd.replace(/-/g, "_");
-    switch (cmd) {
-        case "complete_task":
-        case "start_task":
-        case "skip_task":
-        case "report_blocker":
-        case "record_verification":
-        case "plan_task":
-            return typeof p["taskId"] === "string"
-                ? { type: "task", id: p["taskId"] }
-                : null;
-        case "complete_slice":
-        case "replan_slice":
-            return typeof p["sliceId"] === "string"
-                ? { type: "slice", id: p["sliceId"] }
-                : null;
-        case "plan_slice":
-            return typeof p["sliceId"] === "string"
-                ? { type: "slice_plan", id: p["sliceId"] }
-                : null;
-        case "complete_milestone":
-        case "plan_milestone":
-            return typeof p["milestoneId"] === "string"
-                ? { type: "milestone", id: p["milestoneId"] }
-                : null;
-        case "save_decision":
-            if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
-                return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
-            }
-            return null;
-        default:
-            return null;
-    }
+    return workflowEventEntityKey(event);
 }
 // ─── detectConflicts ──────────────────────────────────────────────────────────
 /**
@@ -302,12 +265,6 @@ function rewriteDivergedEventsForEntity(divergedEvents, entityType, entityId, re
     }
     return rewritten;
 }
-function writeEventLog(basePath, events) {
-    const dir = join(basePath, ".gsd");
-    mkdirSync(dir, { recursive: true });
-    const content = events.map((e) => JSON.stringify(e)).join("\n") + (events.length > 0 ? "\n" : "");
-    atomicWriteSync(join(dir, "event-log.jsonl"), content);
-}
 // ─── writeConflictsFile ───────────────────────────────────────────────────────
 /**
  * Write a human-readable CONFLICTS.md to basePath/.gsd/CONFLICTS.md.
@@ -375,10 +332,15 @@ export function reconcileWorktreeLogs(mainBasePath, worktreeBasePath) {
 }
 function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     // Step 1: Read both logs
-    const mainLogPath = join(mainBasePath, ".gsd", "event-log.jsonl");
-    const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+    const mainLogPath = workflowEventLogPath(mainBasePath);
+    const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
     const mainEvents = readEvents(mainLogPath);
     const wtEvents = readEvents(wtLogPath);
+    // Canonical worktree appends are already durable in the project ledger.
+    // Empty/missing worktree shards are legacy-only absence, not divergence.
+    if (wtEvents.length === 0) {
+        return { autoMerged: 0, conflicts: [] };
+    }
     // Step 2: Find fork point
     const forkPoint = findForkPoint(mainEvents, wtEvents);
     // Step 3: Slice diverged sets
@@ -412,9 +374,7 @@ function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     }
     const baseEvents = mainEvents.slice(0, forkPoint + 1);
     const mergedLog = baseEvents.concat(merged);
-    const logContent = mergedLog.map((e) => JSON.stringify(e)).join("\n") + (mergedLog.length > 0 ? "\n" : "");
-    mkdirSync(join(mainBasePath, ".gsd"), { recursive: true });
-    atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
+    writeWorkflowEventLog(mainBasePath, mergedLog);
     // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
     openWorkflowDatabasePath(resolveGsdPathContract(mainBasePath).projectDb);
     replayEvents(merged);
@@ -533,8 +493,8 @@ pick) {
         throw new Error(`No conflict found for entity ${entityKey}`);
     const conflict = conflicts[idx];
     const eventsToReplay = pick === "main" ? conflict.mainSideEvents : conflict.worktreeSideEvents;
-    const mainLogPath = join(basePath, ".gsd", "event-log.jsonl");
-    const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+    const mainLogPath = workflowEventLogPath(basePath);
+    const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
     const mainEvents = readEvents(mainLogPath);
     const wtEvents = readEvents(wtLogPath);
     const forkPoint = findForkPoint(mainEvents, wtEvents);
@@ -547,7 +507,12 @@ pick) {
         : rewriteDivergedEventsForEntity(mainDiverged, entityType, entityId, eventsToReplay);
     const targetBasePath = pick === "main" ? worktreeBasePath : basePath;
     const targetBaseEvents = pick === "main" ? wtBaseEvents : mainBaseEvents;
-    writeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+    if (pick === "main") {
+        writeWorktreeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+    }
+    else {
+        writeWorkflowEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+    }
     // Replay resolved events through the DB (updates DB state)
     openWorkflowDatabasePath(resolveGsdPathContract(basePath).projectDb);
     replayEvents(eventsToReplay);

package/dist/resources/extensions/gsd/workflow-tool-surface.js

@@ -8,7 +8,7 @@ export const WORKFLOW_TOOL_ALIAS_NAMES = CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES;
 export const DB_WORKFLOW_TOOL_NAMES = CONTRACT_WORKFLOW_TOOL_NAMES;
 export const WORKFLOW_TOOL_ALIAS_PAIRS = WORKFLOW_TOOL_CONTRACTS.flatMap((tool) => tool.aliases.map((alias) => ({ canonical: tool.canonicalName, alias })));
 export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL = Object.fromEntries(WORKFLOW_TOOL_ALIAS_PAIRS.map(({ alias, canonical }) => [alias, canonical]));
-const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
+export const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
     "gsd_cancel",
     "gsd_captures",
     "ask_user_questions",

package/dist/resources/extensions/gsd/worktree-git-recovery.js

@@ -7,8 +7,9 @@
  * git operations during worktree transitions:
  *
  *   - `checkoutBranchWithStashGuard` — branch switch with stash protection,
- *     including the stash-pop EEXIST collision recovery for `.gsd/` runtime
- *     files (force-checkout + targeted stash drop).
+ *     including the stash-pop EEXIST collision recovery for untracked files
+ *     (force-checkout + targeted stash drop; #645 broadened it beyond `.gsd/`,
+ *     guarded by "no non-.gsd unmerged entries remain").
  *   - `removeMergeStateFiles` — clears SQUASH_MSG / MERGE_HEAD / etc. left by
  *     a failed merge so subsequent merges don't fail on stale state.
  *   - `cleanupConflictState` — merge-abort + index reset + state-file cleanup
@@ -240,20 +241,25 @@ export function checkoutBranchWithStashGuard(basePath, branch, reason) {
                     : "";
             const stashPopMessage = `${stderrText}\n${msg}`.trim();
             const alreadyExists = stashAlreadyExistsFilesFromError(popErr);
-            const gsdAlreadyExists = alreadyExists.filter((f) => f.startsWith(".gsd/"));
-            const nonGsdAlreadyExists = alreadyExists.filter((f) => !f.startsWith(".gsd/"));
             const isUntrackedRestoreFailure = stashPopMessage.includes("could not restore untracked files from stash");
             const stashRefForDrop = stashRefFromError(popErr);
-            const nonGsdUnmerged = nativeConflictFiles(basePath).filter((f) => !f.startsWith(".gsd/"));
+            const allConflictFiles = nativeConflictFiles(basePath);
+            const nonGsdUnmerged = allConflictFiles.filter((f) => !f.startsWith(".gsd/"));
+            const gsdUnmerged = allConflictFiles.filter((f) => f.startsWith(".gsd/"));
             const gsdContentConflicts = isUntrackedRestoreFailure
                 ? gsdJsonlFilesWithConflictMarkers(basePath)
                 : [];
-            const gsdConflictFiles = [...new Set([...gsdAlreadyExists, ...gsdContentConflicts])];
+            // Resolve ALL untracked-collision files by accepting HEAD — files in
+            // alreadyExists were untracked on the source branch by definition of the
+            // "already exists, no checkout" failure, so target HEAD is authoritative.
+            // gsdUnmerged: .gsd/ index conflicts left by the partial stash pop are
+            // also resolved via HEAD — .gsd/ runtime state is always authoritative
+            // on the target branch, so accepting HEAD is safe here too.
+            const resolvable = [...new Set([...alreadyExists, ...gsdContentConflicts, ...gsdUnmerged])];
             if (isUntrackedRestoreFailure &&
-                gsdConflictFiles.length > 0 &&
-                nonGsdAlreadyExists.length === 0 &&
+                resolvable.length > 0 &&
                 nonGsdUnmerged.length === 0) {
-                for (const f of gsdConflictFiles) {
+                for (const f of resolvable) {
                     execFileSync("git", ["checkout", "HEAD", "--", f], {
                         cwd: basePath,
                         stdio: ["ignore", "pipe", "pipe"],

package/dist/resources/extensions/gsd/worktree-lifecycle.js

@@ -32,6 +32,7 @@ import { getCollapseCadence, getMilestoneResquash, resquashMilestoneOnMain, } fr
 // callers — production wiring previously injected them via deps; the seam
 // added type churn without enabling test variation.
 import { loadEffectiveGSDPreferences, getIsolationMode } from "./preferences.js";
+import { isolationDegradedFallbackGuidance, worktreeCreationFailedGuidance } from "./guidance.js";
 import { invalidateAllCaches } from "./cache.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { getMilestone, insertMilestone, isDbAvailable, updateMilestoneStatus } from "./gsd-db.js";
@@ -343,7 +344,7 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx, opts = {}) {
                 s.basePath = basePath;
                 rebuildGitService(s, deps);
                 invalidateAllCaches();
-                ctx.notify(`Worktree isolation is degraded. Fell back to branch milestone/${milestoneId}.`, "warning");
+                ctx.notify(isolationDegradedFallbackGuidance(milestoneId), "warning");
                 return { ok: true, mode: "branch", path: basePath };
             }
             catch (err) {
@@ -517,7 +518,7 @@ export function _enterMilestoneCore(s, deps, milestoneId, ctx, opts = {}) {
             eventType: "worktree-create-failed",
             data: { milestoneId, error: msg, fallback: "project-root" },
         });
-        ctx.notify(`Auto-worktree creation for ${milestoneId} failed: ${msg}. Continuing in project root.`, "warning");
+        ctx.notify(worktreeCreationFailedGuidance(milestoneId, msg), "warning");
         // Degrade isolation for the rest of this session so mergeAndExit
         // doesn't try to merge a nonexistent worktree branch (#2483)
         s.isolationDegraded = true;

package/dist/resources/extensions/gsd/worktree-manager.js

@@ -528,7 +528,13 @@ export function removeWorktree(basePath, name, opts = {}) {
     // inside .gsd/worktrees/ — a symlink inside the directory could point out.
     const resolvedPathSafe = isInsideWorktreesDir(basePath, resolvedWtPath);
     // If we're inside the worktree, move out first — git can't remove an in-use directory
-    const cwd = process.cwd();
+    let cwd;
+    try {
+        cwd = process.cwd();
+    }
+    catch {
+        cwd = basePath;
+    }
     const resolvedCwd = existsSync(cwd) ? realpathSync(cwd) : cwd;
     if (resolvedCwd === resolvedWtPath || resolvedCwd.startsWith(resolvedWtPath + sep)) {
         process.chdir(basePath);

package/dist/resources/extensions/gsd/worktree-root.js

@@ -57,6 +57,17 @@ export function findWorktreeSegment(normalizedPath) {
 export function isGsdWorktreePath(path) {
     return findWorktreeSegment(path.replaceAll("\\", "/")) !== null;
 }
+/**
+ * Project-root prefix of a GSD worktree path, or null when the path is not
+ * inside a recognized worktree layout. Pure string split — no env handling,
+ * HOME guard, or filesystem fallbacks (resolveWorktreeProjectRoot adds
+ * those). Separator normalization is 1:1 on characters, so the prefix is
+ * sliced from the ORIGINAL string and keeps its separators.
+ */
+export function projectRootFromWorktreePath(path) {
+    const segment = findWorktreeSegment(path.replaceAll("\\", "/"));
+    return segment ? path.slice(0, segment.gsdIdx) : null;
+}
 /**
  * When a milestone worktree lives under the external-state layout
  * (`<gsdHome>/projects/<hash>/worktrees/<MID>/`, or the `GSD_STATE_DIR`

package/dist/resources/extensions/gsd/worktree-safety.js

@@ -90,38 +90,40 @@ export function createWorktreeSafetyModule(deps = defaultDeps) {
                 return failure("worktree-git-marker-not-file", `Worktree root ${unitRoot} has a .git directory, not a registered worktree .git file.`, "Use a registered GSD worktree instead of a copied or nested repository.", { gitMarker });
             }
             let registered;
-            try {
-                registered = deps.listRegisteredWorktrees?.(projectRoot);
-            }
-            catch (error) {
-                return failure("worktree-git-probe-failed", `Unable to list registered worktrees for project root ${projectRoot}.`, "Recover or recreate the milestone worktree before dispatching the source-writing Unit.", { projectRoot, error: errorMessage(error) });
-            }
-            if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
-                const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
-                let attemptedPrune = false;
-                if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
-                    attemptedPrune = true;
-                    try {
-                        deps.pruneRegisteredWorktrees(projectRoot);
-                        const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
-                        if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
-                            unregisteredRecoveryFailed.delete(unitRoot);
-                            registered = rechecked;
+            if (isolationMode === "worktree") {
+                try {
+                    registered = deps.listRegisteredWorktrees?.(projectRoot);
+                }
+                catch (error) {
+                    return failure("worktree-git-probe-failed", `Unable to list registered worktrees for project root ${projectRoot}.`, "Recover or recreate the milestone worktree before dispatching the source-writing Unit.", { projectRoot, error: errorMessage(error) });
+                }
+                if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
+                    const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
+                    let attemptedPrune = false;
+                    if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
+                        attemptedPrune = true;
+                        try {
+                            deps.pruneRegisteredWorktrees(projectRoot);
+                            const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
+                            if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
+                                unregisteredRecoveryFailed.delete(unitRoot);
+                                registered = rechecked;
+                            }
+                            else {
+                                unregisteredRecoveryFailed.add(unitRoot);
+                            }
                         }
-                        else {
+                        catch (error) {
                             unregisteredRecoveryFailed.add(unitRoot);
+                            return failure("worktree-git-probe-failed", `Unable to recover unregistered worktree root ${unitRoot}.`, "Run 'git worktree prune', then recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { projectRoot, unitRoot, error: errorMessage(error) });
                         }
                     }
-                    catch (error) {
-                        unregisteredRecoveryFailed.add(unitRoot);
-                        return failure("worktree-git-probe-failed", `Unable to recover unregistered worktree root ${unitRoot}.`, "Run 'git worktree prune', then recreate the milestone worktree before dispatching the source-writing Unit.", { projectRoot, unitRoot, error: errorMessage(error) });
+                    if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
+                        return failure("worktree-unregistered", `Worktree root ${unitRoot} is not registered with git worktree list.`, attemptedPrune || wasPreviouslyTracked
+                            ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
+                            : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) });
                     }
                 }
-                if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
-                    return failure("worktree-unregistered", `Worktree root ${unitRoot} is not registered with git worktree list.`, attemptedPrune || wasPreviouslyTracked
-                        ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
-                        : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.", { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) });
-                }
             }
             if (input.emptyWorktreeWithProjectContent) {
                 return failure("empty-worktree-with-project-content", `Worktree root ${unitRoot} has no project content, but the project root does.`, "Resolve untracked project-root content or recreate the worktree so source writes stay isolated.", { unitRoot, projectRoot });

package/dist/resources/extensions/gsd/worktree-session-state.js

@@ -1,5 +1,5 @@
 // GSD worktree session state
-import { findWorktreeSegment } from "./worktree-root.js";
+import { findWorktreeSegment, projectRootFromWorktreePath } from "./worktree-root.js";
 let originalCwd = null;
 export function getWorktreeOriginalCwd() {
     return originalCwd;
@@ -13,10 +13,9 @@ export function clearWorktreeOriginalCwd() {
 export function ensureWorktreeOriginalCwdFromPath(cwd = process.cwd()) {
     if (originalCwd)
         return originalCwd;
-    const segment = findWorktreeSegment(cwd.replaceAll("\\", "/"));
-    if (segment) {
-        originalCwd = cwd.slice(0, segment.gsdIdx);
-    }
+    const root = projectRootFromWorktreePath(cwd);
+    if (root)
+        originalCwd = root;
     return originalCwd;
 }
 export function getActiveWorktreeName() {