@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -1,21 +1,14 @@
 // GSD Extension — Advisory Sync Lock
 // Prevents concurrent worktree syncs from colliding via a simple file lock.
 // Stale locks (mtime > 60s, owner PID confirmed dead) are overridden. Lock
-// acquisition waits up to 5 seconds then skips non-fatally.
+// acquisition skips non-fatally when a live lock is already held.
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, statSync, unlinkSync, writeSync } from "node:fs";
 import { dirname, join } from "node:path";
 const STALE_THRESHOLD_MS = 60_000; // 60 seconds
-const DEFAULT_TIMEOUT_MS = 5_000; // 5 seconds
-const SPIN_INTERVAL_MS = 100; // 100ms polling interval
-// SharedArrayBuffer for synchronous sleep via Atomics.wait
-const SLEEP_BUFFER = new SharedArrayBuffer(4);
-const SLEEP_VIEW = new Int32Array(SLEEP_BUFFER);
+const DEFAULT_TIMEOUT_MS = 0; // fail fast; sync waits block the JS event loop
 function lockFilePath(basePath) {
     return join(basePath, ".gsd", "sync.lock");
 }
-function sleepSync(ms) {
-    Atomics.wait(SLEEP_VIEW, 0, 0, ms);
-}
 /** True if the given PID is alive in the current process namespace. */
 function isPidAlive(pid) {
     try {
@@ -62,7 +55,7 @@ function tryCreateLockFile(lp, payload) {
 }
 /**
  * Acquire an advisory sync lock for the given basePath.
- * Returns { acquired: true } on success, { acquired: false } after timeout.
+ * Returns { acquired: true } on success, { acquired: false } when a live lock is held.
  *
  * Replaces a non-atomic `existsSync` + `atomicWriteSync` (write-temp+rename,
  * which is not exclusive-create) sequence that allowed two callers to both
@@ -73,10 +66,13 @@ function tryCreateLockFile(lp, payload) {
  * before stealing — prevents a slow event-loop pause (>60s under heavy I/O)
  * from making a legitimately-held lock appear stale and get stolen.
  * (Issue #4980 M-concurrency-3)
+ *
+ * Contended live locks fail fast. A synchronous wait here would freeze timers,
+ * I/O, and UI work on Node's single JS thread. The timeout argument remains
+ * accepted for compatibility but is intentionally not used for sync waiting.
  */
-export function acquireSyncLock(basePath, timeoutMs = DEFAULT_TIMEOUT_MS) {
+export function acquireSyncLock(basePath, _timeoutMs = DEFAULT_TIMEOUT_MS) {
     const lp = lockFilePath(basePath);
-    const deadline = Date.now() + timeoutMs;
     const lockData = JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() }, null, 2);
     while (true) {
         // First try the fast path: atomic create. No check-then-write race.
@@ -88,7 +84,7 @@ export function acquireSyncLock(basePath, timeoutMs = DEFAULT_TIMEOUT_MS) {
         catch {
             /* unexpected — fall through to retry */
         }
-        // File exists. Decide whether to steal (stale + owner dead) or wait.
+        // File exists. Decide whether to steal (stale + owner dead) or skip.
         let canSteal = false;
         try {
             const stat = statSync(lp);
@@ -122,11 +118,8 @@ export function acquireSyncLock(basePath, timeoutMs = DEFAULT_TIMEOUT_MS) {
             // Loop back to retry create.
             continue;
         }
-        // Lock is held and not stale (or owner is alive) — wait or give up.
-        if (Date.now() >= deadline) {
-            return { acquired: false };
-        }
-        sleepSync(SPIN_INTERVAL_MS);
+        // Lock is held and not stale (or owner is alive) — skip non-fatally.
+        return { acquired: false };
     }
 }
 /**

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

@@ -1,6 +1,10 @@
 // Project/App: gsd-pi
 // File Purpose: Tool Contract module's runtime face — verify the live SDK tool surface covers a Unit's required workflow tools.
-import { testMcpServerConnection } from "../mcp-client/manager.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { buildHttpTransportOpts } from "../mcp-client/auth.js";
+import { buildMcpChildEnv, collectMcpEnvWarnings, detectTransport, getMcpServerConfig, GSD_MCP_PROBE_ENV, resolveMcpString, } from "../mcp-client/manager.js";
 import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
 import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
 import { recordWorkflowMcpProbe, WORKFLOW_MCP_PROBE_TIMEOUT_MS, } from "./workflow-mcp-readiness-cache.js";
@@ -13,7 +17,36 @@ import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
  */
 export const TOOL_SURFACE_NOT_READY = "workflow tool surface not ready";
 /** MCP server statuses that will not self-heal within the session. */
-const TERMINAL_MCP_SERVER_STATUSES = new Set(["failed", "needs-auth", "disabled"]);
+export const TERMINAL_MCP_SERVER_STATUSES = new Set(["failed", "needs-auth", "disabled"]);
+/**
+ * Marker embedded in the terminal readiness error message. The readiness layer
+ * appends it to the terminal branch so the classifier can distinguish a
+ * non-self-healing failure (failed/needs-auth/disabled) from the genuinely
+ * transient not-yet-connected branches, which all share the
+ * {@link TOOL_SURFACE_NOT_READY} prefix.
+ */
+export const TOOL_SURFACE_TERMINAL_MARKER = "(terminal)";
+/**
+ * True when a tool-surface readiness error describes a *terminal* MCP server
+ * failure (failed / needs-auth / disabled). These statuses will not self-heal
+ * within the session, so they must not be retried as transient — the caller
+ * should escalate / pause instead of same-model retrying indefinitely.
+ *
+ * Detection is driven by the embedded marker string and the terminal status
+ * set above (single source of truth), not by re-deriving either independently.
+ */
+export function isTerminalToolSurfaceError(errorMsg) {
+    if (!errorMsg || !errorMsg.includes(TOOL_SURFACE_NOT_READY))
+        return false;
+    if (!/\bterminal\b/i.test(errorMsg))
+        return false;
+    // Belt-and-braces: confirm one of the canonical terminal statuses is present
+    // so a stray "(terminal)" in unrelated text doesn't trigger this.
+    return [...TERMINAL_MCP_SERVER_STATUSES].some((status) => new RegExp(`status is "${escapeRegExp(status)}"`, "i").test(errorMsg));
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 export const DEFAULT_WORKFLOW_MCP_PREFLIGHT_TIMEOUT_MS = 30_000;
 export const DEFAULT_WORKFLOW_MCP_PREFLIGHT_POLL_MS = 200;
 const RUN_UAT_PREFLIGHT_TIMEOUT_MS = 90_000;
@@ -25,6 +58,50 @@ function resolveWorkflowMcpPreflightTimeoutMs(unitType) {
 export function probeCoversRequiredWorkflowTools(tools, required) {
     return required.every((tool) => tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)));
 }
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function stringArray(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const strings = value.filter((entry) => typeof entry === "string");
+    return strings.length > 0 ? strings : undefined;
+}
+function stringRecord(value) {
+    if (!isRecord(value))
+        return undefined;
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === "string");
+    return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+function normalizeInlineWorkflowMcpServerConfig(serverName, config) {
+    if (!config)
+        return undefined;
+    const command = typeof config.command === "string" ? config.command : undefined;
+    const url = typeof config.url === "string" ? config.url : undefined;
+    const transport = detectTransport(config);
+    const args = stringArray(config.args);
+    const env = stringRecord(config.env);
+    const headers = stringRecord(config.headers);
+    return {
+        name: serverName,
+        transport,
+        sourcePath: "[inline workflow MCP config]",
+        sourceKind: "project-local",
+        disabled: config.disabled === true,
+        ...(command ? { command } : {}),
+        ...(url ? { url } : {}),
+        ...(args ? { args } : {}),
+        ...(env ? { env } : {}),
+        ...(typeof config.cwd === "string" ? { cwd: config.cwd } : {}),
+        ...(headers ? { headers } : {}),
+        ...(isRecord(config.oauth) ? { oauth: config.oauth } : {}),
+        envWarnings: collectMcpEnvWarnings([
+            ["url", url],
+            ...Object.entries(env ?? {}).map(([key, value]) => [`env.${key}`, value]),
+            ...Object.entries(headers ?? {}).map(([key, value]) => [`headers.${key}`, value]),
+        ]),
+    };
+}
 export async function awaitWorkflowMcpToolRegistration(input) {
     const { unitType, workflowServerName, projectRoot } = input;
     if (!unitType || !workflowServerName)
@@ -32,26 +109,138 @@ export async function awaitWorkflowMcpToolRegistration(input) {
     const required = getRequiredWorkflowToolsForUnit(unitType).filter(isWorkflowToolSurfaceName);
     if (required.length === 0)
         return null;
-    const probe = input.probe ?? (async (serverName, root) => {
-        const result = await testMcpServerConnection(serverName, {
-            projectDir: resolveWorkflowMcpProjectRoot(root),
-            timeoutMs: WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+    let reusableClient;
+    let reusableTransport;
+    let reusableServerConfig;
+    let readReusableStderr;
+    const closeReusableConnection = async () => {
+        if (reusableTransport) {
+            try {
+                await reusableTransport.close();
+            }
+            catch {
+                // Best-effort cleanup after preflight connection probing.
+            }
+        }
+        if (reusableClient) {
+            try {
+                await reusableClient.close();
+            }
+            catch {
+                // Best-effort cleanup after preflight connection probing.
+            }
+        }
+        reusableClient = undefined;
+        reusableTransport = undefined;
+        readReusableStderr = undefined;
+    };
+    const formatProbeError = (error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        const stderr = readReusableStderr?.() ?? "";
+        return stderr ? `${message}\nStderr:\n${stderr}` : message;
+    };
+    const captureReusableStderr = (transport) => {
+        const maxBytes = 4096;
+        const chunks = [];
+        let totalBytes = 0;
+        transport.stderr?.on("data", (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+            totalBytes += buffer.byteLength;
+            chunks.push(buffer);
+            while (chunks.reduce((sum, entry) => sum + entry.byteLength, 0) > maxBytes) {
+                chunks.shift();
+            }
         });
-        return { ok: result.ok, tools: result.tools };
+        return () => {
+            const captured = Buffer.concat(chunks).toString("utf-8").trim();
+            if (!captured)
+                return "";
+            return totalBytes > maxBytes ? `[stderr truncated to last ${maxBytes} bytes]\n${captured}` : captured;
+        };
+    };
+    const probe = input.probe ?? (async (serverName, root, workflowServerConfig) => {
+        reusableServerConfig ??=
+            normalizeInlineWorkflowMcpServerConfig(serverName, workflowServerConfig) ??
+                getMcpServerConfig(serverName, {
+                    projectDir: resolveWorkflowMcpProjectRoot(root),
+                    includeDisabled: true,
+                });
+        const config = reusableServerConfig;
+        if (!config)
+            return { ok: false, tools: [], error: "Unknown MCP server." };
+        if (config.disabled)
+            return { ok: false, tools: [], error: "MCP server is disabled." };
+        if (config.transport === "unsupported")
+            return { ok: false, tools: [], error: "MCP server transport is unsupported." };
+        if (config.envWarnings.length > 0) {
+            return { ok: false, tools: [], error: "MCP server config references unset environment variables." };
+        }
+        try {
+            if (!reusableClient) {
+                reusableClient = new Client({ name: "gsd", version: "1.0.0" });
+                let transport;
+                if (config.transport === "stdio") {
+                    transport = new StdioClientTransport({
+                        command: config.command ?? "",
+                        args: config.args,
+                        env: {
+                            ...buildMcpChildEnv(config.env),
+                            [GSD_MCP_PROBE_ENV]: "1",
+                        },
+                        cwd: config.cwd,
+                        stderr: "pipe",
+                    });
+                    readReusableStderr = captureReusableStderr(transport);
+                }
+                else {
+                    const resolvedUrl = resolveMcpString(config.url ?? "");
+                    transport = new StreamableHTTPClientTransport(new URL(resolvedUrl), buildHttpTransportOpts({ headers: config.headers, oauth: config.oauth }));
+                }
+                reusableTransport = transport;
+                await reusableClient.connect(transport, {
+                    signal: input.signal,
+                    timeout: WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+                });
+            }
+            const result = await reusableClient.listTools(undefined, {
+                signal: input.signal,
+                timeout: WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+            });
+            return { ok: true, tools: (result.tools ?? []).map((tool) => tool.name) };
+        }
+        catch (error) {
+            const formatted = formatProbeError(error);
+            await closeReusableConnection();
+            return { ok: false, tools: [], error: formatted };
+        }
     });
     const deadline = Date.now() + (input.timeoutMs ?? resolveWorkflowMcpPreflightTimeoutMs(unitType));
     const pollMs = input.pollMs ?? DEFAULT_WORKFLOW_MCP_PREFLIGHT_POLL_MS;
-    while (Date.now() < deadline) {
-        throwIfAborted(input.signal);
-        const result = await probe(workflowServerName, projectRoot);
-        throwIfAborted(input.signal);
-        if (result.ok && probeCoversRequiredWorkflowTools(result.tools, required)) {
-            recordWorkflowMcpProbe(projectRoot, workflowServerName, result.tools);
-            return null;
+    let lastProbeError;
+    try {
+        while (Date.now() < deadline) {
+            throwIfAborted(input.signal);
+            const result = await probe(workflowServerName, projectRoot, input.workflowServerConfig).catch((err) => {
+                if (input.signal?.aborted)
+                    throw err;
+                lastProbeError = err instanceof Error ? err.message : String(err);
+                return undefined;
+            });
+            throwIfAborted(input.signal);
+            if (result)
+                lastProbeError = result.error;
+            if (result?.ok && probeCoversRequiredWorkflowTools(result.tools, required)) {
+                recordWorkflowMcpProbe(projectRoot, workflowServerName, result.tools);
+                return null;
+            }
+            await sleep(pollMs, input.signal);
         }
-        await sleep(pollMs, input.signal);
     }
-    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" did not register required tools before session start: ${required.join(", ")}`;
+    finally {
+        await closeReusableConnection();
+    }
+    const probeError = lastProbeError ? `; last probe error: ${lastProbeError}` : "";
+    return `${TOOL_SURFACE_NOT_READY} for ${unitType}: MCP server "${workflowServerName}" did not register required tools before session start: ${required.join(", ")}${probeError}`;
 }
 function makeAbortError() {
     const error = new Error("AbortError: The operation was aborted");

package/dist/resources/extensions/gsd/tools/complete-milestone.js

@@ -11,9 +11,9 @@
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { transaction, getMilestone, getMilestoneSlices, getSliceTasks, getLatestAssessmentByScope, updateMilestoneStatus, } from "../gsd-db.js";
-import { gsdProjectionRoot, clearPathCache } from "../paths.js";
+import { clearPathCache, relMilestoneFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
-import { isClosedStatus } from "../status-guards.js";
+import { isClosedStatus, isDeferredStatus } from "../status-guards.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { stripIdPrefix } from "../workflow-projections.js";
@@ -118,7 +118,7 @@ export async function handleCompleteMilestone(params, basePath) {
             guardError = `no slices found for milestone ${params.milestoneId}`;
             return;
         }
-        const incompleteSlices = slices.filter(s => !isClosedStatus(s.status));
+        const incompleteSlices = slices.filter(s => !isClosedStatus(s.status) && !isDeferredStatus(s.status));
         if (incompleteSlices.length > 0) {
             const incompleteIds = incompleteSlices.map(s => `${s.id} (status: ${s.status})`).join(", ");
             guardError = `incomplete slices: ${incompleteIds}`;
@@ -126,6 +126,8 @@ export async function handleCompleteMilestone(params, basePath) {
         }
         // Deep check: verify all tasks in all slices are complete
         for (const slice of slices) {
+            if (isDeferredStatus(slice.status))
+                continue;
             const tasks = getSliceTasks(params.milestoneId, slice.id);
             const incompleteTasks = tasks.filter(t => !isClosedStatus(t.status));
             if (incompleteTasks.length > 0) {
@@ -142,7 +144,9 @@ export async function handleCompleteMilestone(params, basePath) {
     }
     // ── Filesystem operations (outside transaction) ─────────────────────────
     const summaryMd = renderMilestoneSummaryMarkdown(params, completedAt);
-    const summaryPath = join(gsdProjectionRoot(artifactBasePath), "milestones", params.milestoneId, `${params.milestoneId}-SUMMARY.md`);
+    // Layout-aware: flat-phase → phases/NN-slug/NN-SUMMARY.md;
+    // legacy → milestones/MID/MID-SUMMARY.md.
+    const summaryPath = join(artifactBasePath, relMilestoneFile(artifactBasePath, params.milestoneId, "SUMMARY"));
     // Guard (#4598): if SUMMARY.md already exists on disk, do not overwrite it.
     // This handles re-dispatch scenarios (DB/disk state divergence) where a prior
     // completion already wrote the file. Overwriting would silently destroy the

package/dist/resources/extensions/gsd/tools/complete-slice.js

@@ -13,7 +13,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { completeSliceCascade, setSliceSummaryMd, saveGateResult, getPendingGatesForTurn, } from "../gsd-db.js";
 import { getGatesForTurn } from "../gate-registry.js";
-import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile } from "../paths.js";
+import { gsdProjectionRoot, clearPathCache, resolveMilestoneFile, relSliceFile } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, sliceUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
@@ -21,7 +21,7 @@ import { classifyUatContent, escalatesArtifactUatToBrowser } from "../uat-policy
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, roadmapRenderMarksSliceDone } from "../markdown-renderer.js";
 import { isStaleWrite } from "../auto/turn-epoch.js";
-import { flushWorkflowProjections } from "../projection-flush.js";
+import { renderMilestoneShellProjections } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -39,7 +39,11 @@ function sliceGateFieldForId(id, params) {
     }
 }
 function sliceSummaryPath(basePath, milestoneId, sliceId) {
-    return join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, `${sliceId}-SUMMARY.md`);
+    // Layout-aware: flat-phase projects use NN-MM-SUMMARY.md inside the phase dir;
+    // legacy projects use milestones/MID/slices/SID/SID-SUMMARY.md.
+    // relSliceFile returns a path relative to basePath (e.g. ".gsd/phases/01-test/01-01-SUMMARY.md"),
+    // so join with basePath (not gsdProjectionRoot which would double the ".gsd/" segment).
+    return join(basePath, relSliceFile(basePath, milestoneId, sliceId, "SUMMARY"));
 }
 function hasCompleteSliceArtifactContract(basePath, milestoneId, sliceId) {
     clearPathCache();
@@ -397,6 +401,12 @@ export async function handleCompleteSlice(params, basePath) {
         await saveFile(uatPath, uatMd);
         const roadmap = await renderRoadmapFromDb(artifactBasePath, params.milestoneId);
         clearParseCache();
+        // complete-slice runs after a slice is committed in the DB, so the milestone
+        // always has ≥1 slice — the skipped (unplanned) branch is unreachable. Guard
+        // for type-safety so a future invariant surfaces a clear error.
+        if ("skipped" in roadmap) {
+            throw new Error(`roadmap render skipped: milestone ${params.milestoneId} has no planned slices`);
+        }
         // Render verification (ADR-017): confirms the just-written projection
         // reflects the DB completion; the DB row is already committed.
         if (!roadmapRenderMarksSliceDone(roadmap.content, params.sliceId)) {
@@ -448,7 +458,7 @@ export async function handleCompleteSlice(params, basePath) {
     // Separate try/catch per step so a projection failure doesn't prevent
     // the event log entry (critical for worktree reconciliation).
     try {
-        await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
+        await renderMilestoneShellProjections(artifactBasePath, params.milestoneId);
     }
     catch (projErr) {
         logWarning("tool", `complete-slice projection warning for ${params.milestoneId}/${params.sliceId}: ${projErr.message}`);

package/dist/resources/extensions/gsd/tools/complete-task.js

@@ -5,22 +5,23 @@
  *
  * Validates inputs, writes task row and rendered SUMMARY.md to DB in a
  * transaction, then renders projections to disk and invalidates caches.
- * Projection write failures are reported as stale projections and do not roll
- * back committed DB state.
+ * If the critical task summary / plan projection write fails, the DB
+ * completion is compensated back to pending so DB state does not drift ahead
+ * of PLAN.md.
  */
-import { existsSync } from "node:fs";
+import { existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { isClosedStatus } from "../status-guards.js";
 import { transaction, insertMilestone, insertSlice, insertTask, insertVerificationEvidence, getMilestone, getSlice, getTask, updateTaskStatus, deleteVerificationEvidence, saveGateResult, getPendingGatesForTurn, } from "../gsd-db.js";
+import { getWorkflowDatabasePath, ensureWorkflowDbAtPath } from "../db-workspace.js";
 import { getGatesForTurn } from "../gate-registry.js";
-import { gsdProjectionRoot, clearPathCache } from "../paths.js";
+import { gsdProjectionRoot, clearPathCache, resolveMilestonePath, resolveSlicePath } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
 import { checkOwnership, taskUnitKey } from "../unit-ownership.js";
 import { saveFile, clearParseCache } from "../files.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanCheckboxes } from "../markdown-renderer.js";
-import { renderSummaryContent } from "../workflow-projections.js";
-import { flushWorkflowProjections } from "../projection-flush.js";
+import { renderMilestoneShellProjections, renderSummaryContent, } from "../workflow-projections.js";
 import { writeManifest } from "../workflow-manifest.js";
 import { appendEvent } from "../workflow-events.js";
 import { logWarning, logError } from "../workflow-logger.js";
@@ -28,6 +29,20 @@ import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { isStaleWrite } from "../auto/turn-epoch.js";
 import { buildEscalationArtifact, writeEscalationArtifact } from "../escalation.js";
 function taskSummaryPath(basePath, milestoneId, sliceId, taskId) {
+    // Layout-aware: avoid creating a milestones/ directory for flat-phase projects.
+    // When that directory is created as a side effect, milestonesDir() detects it as
+    // a legacy layout and breaks all subsequent path resolution for the session.
+    const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
+    const phaseDir = resolveMilestonePath(basePath, milestoneId);
+    if (slicePath && phaseDir && slicePath !== phaseDir) {
+        // Legacy layout: the slice has its own slices/SID/ subdir → tasks/ subdir
+        return join(slicePath, "tasks", `${taskId}-SUMMARY.md`);
+    }
+    if (phaseDir) {
+        // Flat-phase: task summaries go in the phase dir (no tasks/ subdir)
+        return join(phaseDir, `${taskId}-SUMMARY.md`);
+    }
+    // Fallback: legacy hardcoded path (milestone/slice dir not on disk yet)
     return join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks", `${taskId}-SUMMARY.md`);
 }
 async function repairMissingTaskSummaryProjection(artifactBasePath, taskRow) {
@@ -46,7 +61,7 @@ async function repairMissingTaskSummaryProjection(artifactBasePath, taskRow) {
     clearPathCache();
     clearParseCache();
     try {
-        await flushWorkflowProjections(artifactBasePath, { milestoneId: taskRow.milestone_id });
+        await renderMilestoneShellProjections(artifactBasePath, taskRow.milestone_id);
     }
     catch (projErr) {
         logWarning("tool", `complete-task repair projection warning: ${projErr.message}`);
@@ -167,6 +182,7 @@ export async function handleCompleteTask(params, basePath) {
     let guardError = null;
     let summaryMd = "";
     let repairTaskSummaryRow = null;
+    const rollbackDbPath = getWorkflowDatabasePath();
     // ── ADR-011 Phase 2: validate escalation payload BEFORE any side effects ─
     // Building the artifact runs the full shape validation (2-4 options, unique
     // ids, recommendation references a real id). If the payload is malformed
@@ -303,20 +319,48 @@ export async function handleCompleteTask(params, basePath) {
     if (guardError) {
         return { error: guardError };
     }
-    let projectionStale = false;
     // Resolve and write summary to disk
     const summaryPath = taskSummaryPath(artifactBasePath, params.milestoneId, params.sliceId, params.taskId);
     try {
         await saveFile(summaryPath, summaryMd);
         // Toggle or regenerate the plan projection from DB. Missing projection
         // files are rebuilt by the renderer instead of being skipped.
-        await renderPlanCheckboxes(artifactBasePath, params.milestoneId, params.sliceId);
+        if (!ensureWorkflowDbAtPath(rollbackDbPath)) {
+            throw new Error(`database unavailable before plan projection render for ${params.milestoneId}/${params.sliceId}`);
+        }
+        const wrotePlan = await renderPlanCheckboxes(artifactBasePath, params.milestoneId, params.sliceId);
+        if (!wrotePlan) {
+            throw new Error(`plan projection write returned false for ${params.milestoneId}/${params.sliceId}`);
+        }
     }
     catch (renderErr) {
-        projectionStale = true;
-        logWarning("projection", `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; DB completion remains committed`, {
-            error: renderErr.message,
-        });
+        logWarning("projection", `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}`, { error: renderErr.message });
+        let rollbackSucceeded = false;
+        try {
+            ensureWorkflowDbAtPath(rollbackDbPath);
+            deleteVerificationEvidence(params.milestoneId, params.sliceId, params.taskId);
+            updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, "pending");
+            invalidateStateCache();
+            rollbackSucceeded = true;
+        }
+        catch (rollbackErr) {
+            logWarning("projection", `complete_task rollback failed after projection write failure for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${rollbackErr.message}`);
+        }
+        try {
+            if (existsSync(summaryPath))
+                unlinkSync(summaryPath);
+        }
+        catch (summaryErr) {
+            logWarning("projection", `complete_task could not remove SUMMARY.md after projection write failure for ${params.milestoneId}/${params.sliceId}/${params.taskId}: ${summaryErr.message}`);
+        }
+        // Clear path/parse caches regardless of rollback outcome so stale
+        // entries from the failed write attempt don't leak into subsequent calls.
+        clearPathCache();
+        clearParseCache();
+        const returnMsg = rollbackSucceeded
+            ? `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; rolled completion back to pending`
+            : `complete_task projection write failed for ${params.milestoneId}/${params.sliceId}/${params.taskId}; rollback also failed — task may remain complete with stale plan`;
+        return { error: returnMsg };
     }
     // ── Close gates owned by execute-task (Q5/Q6/Q7) for this task ────────
     // Each gate id maps to a specific params field via taskGateFieldForId.
@@ -421,7 +465,7 @@ export async function handleCompleteTask(params, basePath) {
     // Separate try/catch per step so a projection failure doesn't prevent
     // the event log entry (critical for worktree reconciliation).
     try {
-        await flushWorkflowProjections(artifactBasePath, { milestoneId: params.milestoneId });
+        await renderMilestoneShellProjections(artifactBasePath, params.milestoneId);
     }
     catch (projErr) {
         logWarning("tool", `complete-task projection warning: ${projErr.message}`);
@@ -451,6 +495,5 @@ export async function handleCompleteTask(params, basePath) {
         milestoneId: params.milestoneId,
         summaryPath,
         ...(escalationMetadata ? { escalation: escalationMetadata } : {}),
-        ...(projectionStale ? { stale: true } : {}),
     };
 }

package/dist/resources/extensions/gsd/tools/exec-tool.js

@@ -144,7 +144,7 @@ export async function executeGsdExec(params, deps) {
     if (bashReferencesProjectRootOutsideWorktree(script, deps.baseDir)) {
         return paramError("script references the original project root while running inside a milestone worktree; use the active worktree path or relative paths");
     }
-    const opts = buildExecOptions(deps.baseDir, deps.preferences?.context_mode, { env: deps.env, now: deps.now, generateId: deps.generateId });
+    const opts = buildExecOptions(deps.baseDir, deps.preferences?.context_mode, { env: deps.env, now: deps.now, generateId: deps.generateId, signal: deps.signal });
     const run = deps.run ?? runExecSandbox;
     try {
         const result = await run({
@@ -235,6 +235,7 @@ function formatResult(result) {
             exit_code: result.exit_code,
             signal: result.signal,
             timed_out: result.timed_out,
+            aborted: result.aborted === true,
             force_resolved: result.force_resolved,
             duration_ms: result.duration_ms,
             stdout_bytes: result.stdout_bytes,
@@ -245,12 +246,16 @@ function formatResult(result) {
             stderr_path: result.stderr_path,
             meta_path: result.meta_path,
         },
-        isError: result.timed_out || result.signal !== null || result.exit_code !== 0,
+        isError: result.aborted === true || result.timed_out || result.signal !== null || result.exit_code !== 0,
     };
 }
 function formatExit(result) {
     // force_resolved means a non-closing (D-state) child was force-resolved past its
     // hard deadline rather than observed exiting; distinguish it from a clean timeout.
+    if (result.aborted && result.force_resolved)
+        return "aborted(force-killed)";
+    if (result.aborted)
+        return "aborted";
     if (result.force_resolved)
         return "timeout(force-killed)";
     if (result.timed_out)