gsd-pi 2.70.1-dev.ec24142 → 2.71.0-dev.06b86c6

package/README.md

@@ -27,36 +27,43 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.68
+## What's New in v2.71
 
-### MCP Workflow Tools
+### MCP Secure Env Collect
 
-- **Full workflow over MCP** — slice replanning, milestone management, slice completion, task completion, and core planning tools are now exposed over MCP for external integrations.
-- **Transport-gated MCP** — workflow tool availability adapts to provider transport capabilities automatically.
-- **Write gate enforcement** — workflow MCP respects write gates, preventing unauthorized state mutations from external clients.
+- **Secure credential collection over MCP** — the new `secure_env_collect` tool uses MCP form elicitation to collect secrets (API keys, tokens) from external clients without exposing values in tool output. Masks input in interactive mode.
+- **Hardened elicitation schema** — MCP elicitation schema handling is stricter, with proper validation and fallback for providers that don't support forms.
 
-### Reliability & Recovery
+### MCP Reliability
 
-- **False degraded-mode fix** — eliminates spurious degraded-mode warnings when the DB hasn't been initialized yet.
-- **Stale session resume suppression** — prevents stale interrupted-session resume prompts from hijacking fresh sessions.
-- **Merge conflict recovery** — `autoCommitDirtyState` guarded with cwd restore on `MergeConflictError`.
-- **Auto-resume hardening** — `autoStartTime` restored on resume, managed resources resynced on auto resume.
+- **Stream ordering preserved** — MCP tool output now renders in the correct order, fixing interleaved output in Claude Code and other MCP clients.
+- **isError flag propagation** — workflow tool execution failures now correctly return `isError: true`, so MCP clients can distinguish success from failure.
+- **Multi-round discuss questions** — new-project discuss phase supports multi-round questioning with structured question gates.
 
-### TUI & Developer Experience
+### TUI Fixes
 
-- **Contextual tips system** — TUI and web terminal now surface contextual tips based on workflow state.
-- **Claude Code MCP streaming** — real-time streaming and tool output rendering for Claude Code MCP connections.
+- **Pinned output restored** — pinned output bar displays above the editor during tool execution again.
+- **Turn completion cleanup** — pinned latest output is cleared on turn completion, preventing stale output from persisting.
+- **Secure input masking** — extension input values are masked in interactive mode when collecting secrets.
 
-### Infrastructure
+### Reliability & Internals
 
-- **Weekly model registry refresh** — CI workflow auto-regenerates the model registry on a weekly schedule.
-- **Codebase cache auto-refresh** — stale codebase cache is refreshed automatically without manual intervention.
+- **TOCTOU file locking** — race conditions in event log and custom workflow graph file locking are fixed with proper atomic lock acquisition.
+- **State derive refactor** — `deriveStateFromDb` god function extracted into composable, testable helpers.
+- **Windows portability** — hardened cross-platform portability across runtime, tooling, and CI.
+- **Model routing transparency** — dynamic routing is skipped for interactive dispatches; model changes are always shown in the banner.
+- **Capability-aware routing (ADR-004)** — full implementation of capability scoring, `before_model_select` hook, and task metadata extraction.
+- **Multi-model provider strategy (ADR-005)** — infrastructure for multi-provider model selection wired into live paths.
 
 See the full [Changelog](./CHANGELOG.md) for details on every release.
 
 <details>
-<summary>Previous highlights (v2.67 and earlier)</summary>
+<summary>Previous highlights (v2.70 and earlier)</summary>
 
+- **Full workflow over MCP (v2.68)** — slice replanning, milestone management, slice completion, task completion, and core planning tools exposed over MCP
+- **Transport-gated MCP (v2.68)** — workflow tool availability adapts to provider transport capabilities automatically
+- **Contextual tips system (v2.68)** — TUI and web terminal surface contextual tips based on workflow state
+- **Ask user questions over MCP (v2.70)** — interactive questions exposed via elicitation for external integrations
 - **Tiered Context Injection (M005)** — relevance-scoped context with 65%+ token reduction
 - **Resilient transient error recovery** — defers to Core RetryHandler and fixes cmdCtx race conditions
 - **Anthropic subscription routing** — auto-routed through Claude Code CLI provider with proper display names

package/dist/cli.js

@@ -7,6 +7,7 @@ import { ensureManagedTools } from './tool-bootstrap.js';
 import { loadStoredEnvKeys } from './wizard.js';
 import { migratePiCredentials } from './pi-migration.js';
 import { validateConfiguredModel } from './startup-model-validation.js';
+import { shouldMigrateAnthropicToClaudeCode } from './provider-migrations.js';
 import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 import chalk from 'chalk';
 import { checkForUpdates } from './update-check.js';
@@ -285,7 +286,7 @@ const { resolveModelsJsonPath } = await import('./models-resolver.js');
 const modelsJsonPath = resolveModelsJsonPath();
 const modelRegistry = new ModelRegistry(authStorage, modelsJsonPath);
 markStartup('ModelRegistry');
-const settingsManager = SettingsManager.create(agentDir);
+const settingsManager = SettingsManager.create(process.cwd(), agentDir);
 applySecurityOverrides(settingsManager);
 markStartup('SettingsManager.create');
 // Run onboarding wizard on first launch (no LLM provider configured)
@@ -401,7 +402,11 @@ if (isPrintMode) {
     // Migrate anthropic OAuth users to claude-code provider when CLI is available (#3772).
     // Anthropic blocks third-party apps from using subscription quotas — routing through
     // the local claude CLI binary is TOS-compliant.
-    if (modelRegistry.isProviderRequestReady('claude-code') && settingsManager.getDefaultProvider() === 'anthropic') {
+    if (shouldMigrateAnthropicToClaudeCode({
+        authStorage,
+        isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'),
+        defaultProvider: settingsManager.getDefaultProvider(),
+    })) {
         const currentModelId = settingsManager.getDefaultModel();
         if (currentModelId) {
             const ccModel = modelRegistry.find('claude-code', currentModelId);
@@ -576,7 +581,11 @@ markStartup('createAgentSession');
 // Migrate anthropic OAuth users to claude-code provider when CLI is available (#3772).
 // Anthropic blocks third-party apps from using subscription quotas — routing through
 // the local claude CLI binary is TOS-compliant.
-if (modelRegistry.isProviderRequestReady('claude-code') && settingsManager.getDefaultProvider() === 'anthropic') {
+if (shouldMigrateAnthropicToClaudeCode({
+    authStorage,
+    isClaudeCodeReady: modelRegistry.isProviderRequestReady('claude-code'),
+    defaultProvider: settingsManager.getDefaultProvider(),
+})) {
     const currentModelId = settingsManager.getDefaultModel();
     if (currentModelId) {
         const ccModel = modelRegistry.find('claude-code', currentModelId);

package/dist/mcp-server.js

@@ -1,10 +1,10 @@
 // MCP SDK subpath imports use wildcard exports (./*) that NodeNext resolves
 // at runtime but TypeScript cannot statically type-check. We construct the
 // specifiers dynamically so tsc treats them as `any`.
-// Use createRequire to resolve wildcard subpaths — CJS resolver auto-appends
-// .js, which the ESM wildcard export map does not (#3603).
-import { createRequire } from 'node:module';
-const _require = createRequire(import.meta.url);
+//
+// Use explicit .js subpaths for modules that are loaded dynamically at runtime.
+// Recent Node / SDK combinations do not reliably resolve the extensionless
+// wildcard targets for `server/stdio` and `types` (#3914).
 const MCP_PKG = '@modelcontextprotocol/sdk';
 /**
  * Starts a native MCP (Model Context Protocol) server over stdin/stdout.
@@ -23,8 +23,8 @@ const MCP_PKG = '@modelcontextprotocol/sdk';
 export async function startMcpServer(options) {
     const { tools, version = '0.0.0' } = options;
     const serverMod = await import(`${MCP_PKG}/server`);
-    const stdioMod = await import(_require.resolve(`${MCP_PKG}/server/stdio`));
-    const typesMod = await import(_require.resolve(`${MCP_PKG}/types`));
+    const stdioMod = await import(`${MCP_PKG}/server/stdio.js`);
+    const typesMod = await import(`${MCP_PKG}/types.js`);
     const Server = serverMod.Server;
     const StdioServerTransport = stdioMod.StdioServerTransport;
     const { ListToolsRequestSchema, CallToolRequestSchema } = typesMod;

package/dist/provider-migrations.d.ts

@@ -0,0 +1,10 @@
+import type { AuthStorage } from "@gsd/pi-coding-agent";
+type AnthropicMigrationDeps = {
+    authStorage: Pick<AuthStorage, "getCredentialsForProvider">;
+    isClaudeCodeReady: boolean;
+    defaultProvider: string | undefined;
+    env?: NodeJS.ProcessEnv;
+};
+export declare function hasDirectAnthropicApiKey(authStorage: Pick<AuthStorage, "getCredentialsForProvider">, env?: NodeJS.ProcessEnv): boolean;
+export declare function shouldMigrateAnthropicToClaudeCode({ authStorage, isClaudeCodeReady, defaultProvider, env, }: AnthropicMigrationDeps): boolean;
+export {};

package/dist/provider-migrations.js

@@ -0,0 +1,12 @@
+export function hasDirectAnthropicApiKey(authStorage, env = process.env) {
+    if ((env.ANTHROPIC_API_KEY ?? "").trim()) {
+        return true;
+    }
+    return authStorage.getCredentialsForProvider("anthropic").some((credential) => credential?.type === "api_key" && typeof credential?.key === "string" && credential.key.trim().length > 0);
+}
+export function shouldMigrateAnthropicToClaudeCode({ authStorage, isClaudeCodeReady, defaultProvider, env = process.env, }) {
+    if (!isClaudeCodeReady || defaultProvider !== "anthropic") {
+        return false;
+    }
+    return !hasDirectAnthropicApiKey(authStorage, env);
+}

package/dist/resource-loader.js

@@ -2,7 +2,7 @@ import { DefaultResourceLoader, sortExtensionPaths } from '@gsd/pi-coding-agent'
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
 import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readlinkSync, readdirSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { compareSemver } from './update-check.js';
 import { discoverExtensionEntryPaths } from './extension-discovery.js';
@@ -254,34 +254,157 @@ function copyDirRecursive(src, dest) {
  * ~/.gsd/agent/extensions/ have no ancestor node_modules, so imports of
  * @gsd/* packages fail. The symlink makes Node's standard resolution find
  * them without requiring every call site to use jiti.
+ *
+ * Layout differences by install method:
+ * - Source/monorepo: packageRoot/node_modules has everything → simple symlink
+ * - npm/bun global: deps hoisted to dirname(packageRoot), including @gsd/* → simple symlink
+ * - pnpm global: external deps hoisted, but @gsd/* stays in packageRoot/node_modules
+ *   → merged directory with symlinks from both roots (#3529, #3564)
  */
 function ensureNodeModulesSymlink(agentDir) {
     const agentNodeModules = join(agentDir, 'node_modules');
-    const gsdNodeModules = join(packageRoot, 'node_modules');
+    const internalNodeModules = join(packageRoot, 'node_modules');
+    const hoistedNodeModules = dirname(packageRoot);
+    const isGlobalInstall = basename(hoistedNodeModules) === 'node_modules';
+    if (!isGlobalInstall) {
+        // Source/monorepo: internal node_modules has everything
+        reconcileSymlink(agentNodeModules, internalNodeModules);
+        return;
+    }
+    // Global install: check if workspace scopes (@gsd/*) are hoisted.
+    // npm/bun hoist everything; pnpm keeps workspace packages internal.
+    if (!hasMissingWorkspaceScopes(hoistedNodeModules, internalNodeModules)) {
+        // Everything is hoisted — simple symlink to parent node_modules
+        reconcileSymlink(agentNodeModules, hoistedNodeModules);
+        return;
+    }
+    // pnpm-style layout: create a real directory merging both roots
+    reconcileMergedNodeModules(agentNodeModules, hoistedNodeModules, internalNodeModules);
+}
+/** Check if any @gsd* scopes exist in internal but not in hoisted node_modules */
+function hasMissingWorkspaceScopes(hoisted, internal) {
+    if (!existsSync(internal))
+        return false;
     try {
-        const stat = lstatSync(agentNodeModules);
+        for (const entry of readdirSync(internal, { withFileTypes: true })) {
+            if (entry.isDirectory() && entry.name.startsWith('@gsd') &&
+                !existsSync(join(hoisted, entry.name))) {
+                return true;
+            }
+        }
+    }
+    catch { /* non-fatal */ }
+    return false;
+}
+/** Ensure a symlink at `link` points to `target`, fixing stale/wrong entries */
+function reconcileSymlink(link, target) {
+    try {
+        const stat = lstatSync(link);
         if (stat.isSymbolicLink()) {
-            const existing = readlinkSync(agentNodeModules);
-            // Symlink exists — verify it points to the correct, existing target
-            if (existing === gsdNodeModules && existsSync(agentNodeModules))
+            const existing = readlinkSync(link);
+            if (existing === target && existsSync(link))
                 return; // correct and target exists
-            // Stale or wrong target — remove and recreate
+            unlinkSync(link);
+        }
+        else {
+            // Real directory (or merged dir from previous pnpm fix) — remove it
+            rmSync(link, { recursive: true, force: true });
+        }
+    }
+    catch {
+        // lstatSync throws if path doesn't exist — fine, we'll create below
+    }
+    try {
+        symlinkSync(target, link, 'junction');
+    }
+    catch (err) {
+        console.error(`[gsd] WARN: Failed to symlink ${link} → ${target}: ${err instanceof Error ? err.message : err}`);
+    }
+}
+/**
+ * Create a real node_modules directory containing symlinks from both the
+ * hoisted root (external deps) and internal root (@gsd/* workspace packages).
+ * Used for pnpm global installs where @gsd/* isn't hoisted.
+ */
+function reconcileMergedNodeModules(agentNodeModules, hoisted, internal) {
+    // Fast path: if already merged for this packageRoot + same directory contents, skip.
+    // The fingerprint includes entry names from both roots so `pnpm add/remove` triggers rebuild.
+    const marker = join(agentNodeModules, '.gsd-merged');
+    const fingerprint = mergedFingerprint(hoisted, internal);
+    try {
+        if (existsSync(marker) && readFileSync(marker, 'utf-8').trim() === fingerprint)
+            return;
+    }
+    catch { /* rebuild */ }
+    // Remove any existing symlink or stale merged directory
+    try {
+        const stat = lstatSync(agentNodeModules);
+        if (stat.isSymbolicLink()) {
             unlinkSync(agentNodeModules);
         }
         else {
-            // Real directory (not a symlink) is blocking — remove it
             rmSync(agentNodeModules, { recursive: true, force: true });
         }
     }
-    catch {
-        // lstatSync throws if path doesn't exist — that's fine, we'll create below
+    catch { /* doesn't exist */ }
+    mkdirSync(agentNodeModules, { recursive: true });
+    let linkedCount = 0;
+    // Symlink entries from the hoisted node_modules (external deps)
+    try {
+        for (const entry of readdirSync(hoisted, { withFileTypes: true })) {
+            // Skip the gsd-pi package itself and dotfiles
+            if (entry.name === basename(packageRoot))
+                continue;
+            if (entry.name.startsWith('.'))
+                continue;
+            try {
+                symlinkSync(join(hoisted, entry.name), join(agentNodeModules, entry.name));
+                linkedCount++;
+            }
+            catch { /* skip individual */ }
+        }
     }
+    catch (err) {
+        console.error(`[gsd] WARN: Failed to read hoisted node_modules at ${hoisted}: ${err instanceof Error ? err.message : err}`);
+    }
+    // Overlay @gsd* workspace scopes from internal node_modules
     try {
-        symlinkSync(gsdNodeModules, agentNodeModules, 'junction');
+        for (const entry of readdirSync(internal, { withFileTypes: true })) {
+            if (!entry.name.startsWith('@gsd'))
+                continue;
+            const link = join(agentNodeModules, entry.name);
+            try {
+                lstatSync(link);
+                unlinkSync(link);
+            }
+            catch { /* didn't exist */ }
+            try {
+                symlinkSync(join(internal, entry.name), link);
+                linkedCount++;
+            }
+            catch { /* skip individual */ }
+        }
     }
     catch (err) {
-        // This failure makes GSD non-functional — extensions can't resolve @gsd/* packages
-        console.error(`[gsd] WARN: Failed to symlink ${agentNodeModules} → ${gsdNodeModules}: ${err instanceof Error ? err.message : err}`);
+        console.error(`[gsd] WARN: Failed to read internal node_modules at ${internal}: ${err instanceof Error ? err.message : err}`);
+    }
+    // Only stamp marker if we actually linked something — avoids caching a broken state
+    if (linkedCount > 0) {
+        try {
+            writeFileSync(marker, fingerprint);
+        }
+        catch { /* non-fatal */ }
+    }
+}
+/** Build a cache fingerprint from packageRoot + sorted entry names of both directories */
+function mergedFingerprint(hoisted, internal) {
+    try {
+        const h = readdirSync(hoisted).sort().join(',');
+        const i = readdirSync(internal).sort().join(',');
+        return `${packageRoot}\n${h}\n${i}`;
+    }
+    catch {
+        return packageRoot; // fallback: at least invalidate on version change
     }
 }
 /**

package/dist/resources/GSD-WORKFLOW.md

@@ -275,7 +275,7 @@ Work flows through these phases. Each phase produces a file.
 **How to do it manually:**
 1. Read the roadmap to understand the scope.
 2. Identify 3-5 gray areas — implementation decisions the user cares about.
-3. Use `ask_user_questions` to discuss each area.
+3. Use `ask_user_questions` to discuss each area, one round at a time. Never fabricate user input; wait for the user's actual response before the next round.
 4. Write decisions to the appropriate context file (`M###-CONTEXT.md` or `S##-CONTEXT.md`).
 5. Do NOT discuss how to implement — only what the user wants.
 

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

@@ -523,7 +523,7 @@ export async function bootstrapAutoSession(s, ctx, pi, base, verboseMode, reques
             }
         }
         // ── DB lifecycle ──
-        const gsdDbPath = join(s.basePath, ".gsd", "gsd.db");
+        const gsdDbPath = resolveProjectRootDbPath(s.basePath);
         const gsdDirPath = join(s.basePath, ".gsd");
         if (existsSync(gsdDirPath) && !existsSync(gsdDbPath)) {
             const hasDecisions = existsSync(join(gsdDirPath, "DECISIONS.md"));

package/dist/resources/extensions/gsd/auto-tool-tracking.js

@@ -82,7 +82,7 @@ export function clearInFlightTools() {
  * handler. When these errors occur, retrying the same unit will produce the same
  * failure, so the retry loop must be broken.
  */
-const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Expected ',' or '\}' in JSON|Unexpected end of JSON|Unexpected token.*in JSON/i;
+const TOOL_INVOCATION_ERROR_RE = /Validation failed for tool|Expected ',' or '\}'(?: after property value)?(?: in JSON)?|Unexpected end of JSON|Unexpected token.*in JSON/i;
 /**
  * Returns true if the error message indicates a tool invocation failure due to
  * malformed/truncated arguments (as opposed to a normal tool execution error).

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -111,6 +111,8 @@ export function registerHooks(pi) {
             return { cancel: true };
         }
         const basePath = process.cwd();
+        const { ensureDbOpen } = await import("./dynamic-tools.js");
+        await ensureDbOpen();
         const state = await deriveState(basePath);
         if (!state.activeMilestone || !state.activeSlice || !state.activeTask)
             return;

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -257,6 +257,10 @@ function buildWorktreeContextBlock() {
  */
 const RESUME_INTENT_PATTERNS = /^(continue|resume|ok|go|go ahead|proceed|keep going|carry on|next|yes|yeah|yep|sure|do it|let's go|pick up where you left off)$/;
 async function buildGuidedExecuteContextInjection(prompt, basePath) {
+    const ensureStateDbOpen = async () => {
+        const { ensureDbOpen } = await import("./dynamic-tools.js");
+        await ensureDbOpen();
+    };
     const executeMatch = prompt.match(/Execute the next task:\s+(T\d+)\s+\("([^"]+)"\)\s+in slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
     if (executeMatch) {
         const [, taskId, taskTitle, sliceId, milestoneId] = executeMatch;
@@ -265,6 +269,7 @@ async function buildGuidedExecuteContextInjection(prompt, basePath) {
     const resumeMatch = prompt.match(/Resume interrupted work\.[\s\S]*?slice\s+(S\d+)\s+of milestone\s+(M\d+(?:-[a-z0-9]{6})?)/i);
     if (resumeMatch) {
         const [, sliceId, milestoneId] = resumeMatch;
+        await ensureStateDbOpen();
         const state = await deriveState(basePath);
         if (state.activeMilestone?.id === milestoneId && state.activeSlice?.id === sliceId && state.activeTask) {
             return buildTaskExecutionContextInjection(basePath, milestoneId, sliceId, state.activeTask.id, state.activeTask.title);
@@ -279,6 +284,7 @@ async function buildGuidedExecuteContextInjection(prompt, basePath) {
     // replanning, gate evaluation, or other non-execution phases.
     const trimmed = prompt.trim().toLowerCase().replace(/[.!?,]+$/g, "");
     if (RESUME_INTENT_PATTERNS.test(trimmed)) {
+        await ensureStateDbOpen();
         const state = await deriveState(basePath);
         if (state.phase === "executing" && state.activeTask && state.activeMilestone && state.activeSlice) {
             return buildTaskExecutionContextInjection(basePath, state.activeMilestone.id, state.activeSlice.id, state.activeTask.id, state.activeTask.title);

package/dist/resources/extensions/gsd/commands/context.js

@@ -1,8 +1,18 @@
 import { checkRemoteAutoSession, isAutoActive, isAutoPaused, stopAutoRemote } from "../auto.js";
-import { assertSafeDirectory } from "../validate-directory.js";
+import { validateDirectory } from "../validate-directory.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { showNextAction } from "../../shared/tui.js";
 import { handleStatus } from "./handlers/core.js";
+/**
+ * Typed error for when GSD is run outside a valid project directory.
+ * Command handlers catch this to show a friendly message instead of a raw exception.
+ */
+export class GSDNoProjectError extends Error {
+    constructor(reason) {
+        super(reason);
+        this.name = "GSDNoProjectError";
+    }
+}
 export function projectRoot() {
     let cwd;
     try {
@@ -13,11 +23,10 @@ export function projectRoot() {
         cwd = process.env.HOME ?? "/";
     }
     const root = resolveProjectRoot(cwd);
-    if (root !== cwd) {
-        assertSafeDirectory(cwd);
-    }
-    else {
-        assertSafeDirectory(root);
+    const pathToCheck = root !== cwd ? cwd : root;
+    const result = validateDirectory(pathToCheck);
+    if (result.severity === "blocked") {
+        throw new GSDNoProjectError(result.reason ?? "GSD must be run inside a project directory.");
     }
     return root;
 }

package/dist/resources/extensions/gsd/commands/dispatcher.js

@@ -1,3 +1,4 @@
+import { GSDNoProjectError } from "./context.js";
 import { handleAutoCommand } from "./handlers/auto.js";
 import { handleCoreCommand } from "./handlers/core.js";
 import { handleOpsCommand } from "./handlers/ops.js";
@@ -12,10 +13,19 @@ export async function handleGSDCommand(args, ctx, pi) {
         () => handleWorkflowCommand(trimmed, ctx, pi),
         () => handleOpsCommand(trimmed, ctx, pi),
     ];
-    for (const handler of handlers) {
-        if (await handler()) {
+    try {
+        for (const handler of handlers) {
+            if (await handler()) {
+                return;
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof GSDNoProjectError) {
+            ctx.ui.notify(`${err.message} \`cd\` into a project directory first.`, "warning");
             return;
         }
+        throw err;
     }
     ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning");
 }

package/dist/resources/extensions/gsd/custom-workflow-engine.js

@@ -17,6 +17,7 @@ import { parse } from "yaml";
 import { readGraph, writeGraph, getNextPendingStep, markStepComplete, expandIteration, } from "./graph.js";
 import { injectContext } from "./context-injector.js";
 import { parseUnitId } from "./unit-id.js";
+import { withFileLock } from "./file-lock.js";
 /** Read and parse the frozen DEFINITION.yaml from a run directory. */
 export function readFrozenDefinition(runDir) {
     const defPath = join(runDir, "DEFINITION.yaml");
@@ -135,18 +136,21 @@ export class CustomWorkflowEngine {
      * Returns "milestone-complete" when all steps are now done, "continue" otherwise.
      */
     async reconcile(state, completedStep) {
-        // Re-read the graph from disk so we do not overwrite concurrent
-        // workflow edits with a stale in-memory snapshot from deriveState().
-        const graph = readGraph(this.runDir);
-        // Extract stepId from "<workflowName>/<stepId>"
-        const { milestone, slice, task } = parseUnitId(completedStep.unitId);
-        const stepId = task ?? slice ?? milestone;
-        const updatedGraph = markStepComplete(graph, stepId);
-        writeGraph(this.runDir, updatedGraph);
-        const allDone = updatedGraph.steps.every((s) => s.status === "complete" || s.status === "expanded");
-        return {
-            outcome: allDone ? "milestone-complete" : "continue",
-        };
+        const graphPath = join(this.runDir, "GRAPH.yaml");
+        return await withFileLock(graphPath, () => {
+            // Re-read the graph from disk so we do not overwrite concurrent
+            // workflow edits with a stale in-memory snapshot from deriveState().
+            const graph = readGraph(this.runDir);
+            // Extract stepId from "<workflowName>/<stepId>"
+            const { milestone, slice, task } = parseUnitId(completedStep.unitId);
+            const stepId = task ?? slice ?? milestone;
+            const updatedGraph = markStepComplete(graph, stepId);
+            writeGraph(this.runDir, updatedGraph);
+            const allDone = updatedGraph.steps.every((s) => s.status === "complete" || s.status === "expanded");
+            return {
+                outcome: allDone ? "milestone-complete" : "continue",
+            };
+        });
     }
     /**
      * Return UI-facing metadata for progress display.

package/dist/resources/extensions/gsd/dispatch-guard.js

@@ -102,10 +102,27 @@ export function getPriorSliceCompletionBlocker(base, _mainBranch, unitType, unit
             }
         }
         else {
+            // Positional fallback is only a heuristic for legacy slices with no
+            // declared dependencies. Skip any earlier slice that depends on the
+            // target, directly or transitively, or we can deadlock a valid zero-dep
+            // slice behind its own downstream dependents (#3720).
+            const reverseDependents = new Set();
+            let changed = true;
+            while (changed) {
+                changed = false;
+                for (const slice of slices) {
+                    if (reverseDependents.has(slice.id))
+                        continue;
+                    if (slice.depends.some((depId) => depId === targetSid || reverseDependents.has(depId))) {
+                        reverseDependents.add(slice.id);
+                        changed = true;
+                    }
+                }
+            }
             const targetIndex = slices.findIndex((slice) => slice.id === targetSid);
             const incomplete = slices
                 .slice(0, targetIndex)
-                .find((slice) => !slice.done);
+                .find((slice) => !slice.done && !reverseDependents.has(slice.id));
             if (incomplete) {
                 return `Cannot dispatch ${unitType} ${unitId}: earlier slice ${targetMid}/${incomplete.id} is not complete.`;
             }

package/dist/resources/extensions/gsd/error-classifier.js

@@ -23,7 +23,7 @@ const RATE_LIMIT_RE = /rate.?limit|too many requests|429/i;
 const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns/i;
 const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
-const CONNECTION_RE = /terminated|connection.?refused|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
+const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
 // Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".
 // This eliminates the need to enumerate every error message variant individually.
 const STREAM_RE = /in JSON at position \d+|Unexpected end of JSON|SyntaxError.*JSON/i;

package/dist/resources/extensions/gsd/file-lock.js

@@ -0,0 +1,60 @@
+import { existsSync } from "node:fs";
+function _require(name) {
+    try {
+        return require(name);
+    }
+    catch {
+        try {
+            const gsdPiRequire = require("module").createRequire(require("path").join(process.cwd(), "node_modules", "gsd-pi", "index.js"));
+            return gsdPiRequire(name);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+export function withFileLockSync(filePath, fn) {
+    const lockfile = _require("proper-lockfile");
+    if (!lockfile)
+        return fn();
+    if (!existsSync(filePath))
+        return fn();
+    try {
+        const release = lockfile.lockSync(filePath, { retries: 5, stale: 10000 });
+        try {
+            return fn();
+        }
+        finally {
+            release();
+        }
+    }
+    catch (err) {
+        if (err.code === "ELOCKED") {
+            // Could not get lock after retries, let's fallback to un-locked instead of crashing the whole state machine
+            return fn();
+        }
+        throw err;
+    }
+}
+export async function withFileLock(filePath, fn) {
+    const lockfile = _require("proper-lockfile");
+    if (!lockfile)
+        return await fn();
+    if (!existsSync(filePath))
+        return await fn();
+    try {
+        const release = await lockfile.lock(filePath, { retries: 5, stale: 10000 });
+        try {
+            return await fn();
+        }
+        finally {
+            await release();
+        }
+    }
+    catch (err) {
+        if (err.code === "ELOCKED") {
+            return await fn();
+        }
+        throw err;
+    }
+}