@opengsd/gsd-pi 1.4.0 → 1.5.0-dev.4fb2d460

package/dist/resources/extensions/cursor-cli/stream-adapter.js

@@ -0,0 +1,353 @@
+import { spawn } from "node:child_process";
+import { createAssistantMessageEventStream } from "@gsd/pi-ai";
+import { buildCursorAgentSpawnInvocation } from "./readiness.js";
+const ZERO_USAGE = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+};
+function textBlocks(content) {
+    return content
+        .map((block) => block.type === "text" ? block.text : `[${block.type} omitted]`)
+        .join("\n");
+}
+function messageToText(message) {
+    if (message.role === "user") {
+        const content = typeof message.content === "string" ? message.content : textBlocks(message.content);
+        return `User:\n${content}`;
+    }
+    if (message.role === "assistant") {
+        const text = message.content
+            .map((block) => {
+            if (block.type === "text")
+                return block.text;
+            if (block.type === "thinking")
+                return "[thinking omitted]";
+            if (block.type === "toolCall")
+                return `[tool call: ${block.name}]`;
+            if (block.type === "serverToolUse")
+                return `[server tool: ${block.name}]`;
+            if (block.type === "webSearchResult")
+                return "[web search result omitted]";
+            return `[${block.type} omitted]`;
+        })
+            .join("\n");
+        return `Assistant:\n${text}`;
+    }
+    return `Tool result (${message.toolName}):\n${textBlocks(message.content)}`;
+}
+export function buildCursorPrompt(context) {
+    const parts = [];
+    if (context.systemPrompt?.trim())
+        parts.push(`System instructions:\n${context.systemPrompt.trim()}`);
+    if (context.messages.length > 0)
+        parts.push(context.messages.map(messageToText).join("\n\n"));
+    if (context.tools?.length) {
+        parts.push(`The external Cursor agent may execute its own tools. ` +
+            `GSD will not redispatch Cursor-owned internal tool events locally. ` +
+            `Requested GSD tools: ${context.tools.map((tool) => tool.name).join(", ")}`);
+    }
+    return parts.join("\n\n").trim();
+}
+export function buildCursorSpawnInvocation(command, args, platform = process.platform) {
+    return buildCursorAgentSpawnInvocation(command, args, platform);
+}
+export function buildCursorAgentRunPlan(modelId, prompt, cwd, platform = process.platform) {
+    return buildCursorSpawnInvocation(process.env.CURSOR_AGENT_BIN?.trim() || "cursor-agent", ["-p", prompt, "--output-format", "stream-json", "--model", modelId, "--workspace", cwd, "--trust"], platform);
+}
+function emitCompleteLines(chunk, pending, onLine) {
+    pending.value += chunk;
+    const lines = pending.value.split(/\r?\n/);
+    pending.value = lines.pop() ?? "";
+    for (const line of lines)
+        onLine(line);
+}
+function flushPendingLine(pending, onLine) {
+    if (!pending.value)
+        return;
+    onLine(pending.value);
+    pending.value = "";
+}
+function runCursorAgent(plan, options, onLine) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(plan.command, plan.args, {
+            cwd: options?.cwd || process.cwd(),
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const pendingStdout = { value: "" };
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            options?.signal?.removeEventListener("abort", onAbort);
+            fn();
+        };
+        const onAbort = () => {
+            child.kill("SIGTERM");
+            settle(() => reject(new Error("Request was aborted")));
+        };
+        if (options?.signal?.aborted) {
+            onAbort();
+            return;
+        }
+        options?.signal?.addEventListener("abort", onAbort);
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+            try {
+                emitCompleteLines(chunk, pendingStdout, onLine);
+            }
+            catch (error) {
+                child.kill("SIGTERM");
+                settle(() => reject(error));
+            }
+        });
+        child.stderr?.on("data", (chunk) => { stderr += chunk; });
+        child.on("error", (error) => settle(() => reject(error)));
+        child.on("close", (code, signal) => settle(() => {
+            try {
+                flushPendingLine(pendingStdout, onLine);
+            }
+            catch (error) {
+                reject(error);
+                return;
+            }
+            resolve({ stdout, stderr, code, signal });
+        }));
+    });
+}
+function stringValue(...values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return undefined;
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+function extractText(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => stringValue(objectValue(item)?.text, objectValue(item)?.content, item))
+            .filter((item) => Boolean(item))
+            .join("\n");
+    }
+    const obj = objectValue(value);
+    if (!obj)
+        return "";
+    return stringValue(obj.text, obj.content, obj.message, obj.result) ?? "";
+}
+function mapUsage(raw) {
+    const input = Number(raw.input_tokens ?? raw.input ?? raw.prompt_tokens ?? 0);
+    const output = Number(raw.output_tokens ?? raw.output ?? raw.completion_tokens ?? 0);
+    const cacheRead = Number(raw.cache_read_input_tokens ?? raw.cacheRead ?? 0);
+    const cacheWrite = Number(raw.cache_creation_input_tokens ?? raw.cacheWrite ?? 0);
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+    };
+}
+function normalizeToolArguments(input) {
+    return objectValue(input) ?? { input };
+}
+function normalizeToolResult(raw) {
+    const text = extractText(raw.content ?? raw.result ?? raw.output);
+    return {
+        content: text ? [{ type: "text", text }] : [],
+        isError: Boolean(raw.is_error ?? raw.isError ?? raw.error),
+    };
+}
+export function parseCursorAgentLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return { type: "ignore" };
+    let event;
+    try {
+        event = JSON.parse(trimmed);
+    }
+    catch {
+        return { type: "text", text: trimmed };
+    }
+    const type = stringValue(event.type, event.event) ?? "";
+    if (type === "error") {
+        return { type: "error", message: stringValue(event.message, event.error) ?? "cursor_agent_error" };
+    }
+    if (type === "tool_call") {
+        if (event.call_id || event.subtype || event.tool_call)
+            return { type: "ignore" };
+        const id = stringValue(event.id, event.tool_call_id) ?? `cursor_tool_${Date.now()}`;
+        const name = stringValue(event.name, event.tool_name) ?? "cursor_tool";
+        return {
+            type: "tool_call",
+            toolCall: { type: "toolCall", id, name, arguments: normalizeToolArguments(event.input ?? event.arguments) },
+        };
+    }
+    if (type === "tool_result") {
+        return {
+            type: "tool_result",
+            toolCallId: stringValue(event.tool_call_id, event.id) ?? "",
+            result: normalizeToolResult(event),
+        };
+    }
+    if (type === "result") {
+        const usage = objectValue(event.usage);
+        return usage ? { type: "usage", usage: mapUsage(usage) } : { type: "ignore" };
+    }
+    const text = extractText(event.delta ?? event.text ?? event.content ?? objectValue(event.message)?.content ?? event.message);
+    if (text)
+        return { type: "text", text };
+    const usage = objectValue(event.usage);
+    if (usage)
+        return { type: "usage", usage: mapUsage(usage) };
+    return { type: "ignore" };
+}
+function createUsage(partial) {
+    const input = partial?.input ?? 0;
+    const output = partial?.output ?? 0;
+    const cacheRead = partial?.cacheRead ?? 0;
+    const cacheWrite = partial?.cacheWrite ?? 0;
+    return {
+        ...ZERO_USAGE,
+        input,
+        output,
+        cacheRead,
+        cacheWrite,
+        totalTokens: input + output + cacheWrite,
+        cost: { ...ZERO_USAGE.cost },
+    };
+}
+function buildAssistantMessage(model, content, usage, stopReason = "stop", errorMessage) {
+    return {
+        role: "assistant",
+        content,
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        usage: createUsage(usage),
+        stopReason,
+        ...(errorMessage ? { errorMessage } : {}),
+        timestamp: Date.now(),
+    };
+}
+function emitDone(stream, message, text) {
+    stream.push({ type: "start", partial: { ...message, content: [] } });
+    if (text) {
+        stream.push({ type: "text_start", contentIndex: 0, partial: message });
+        stream.push({ type: "text_delta", contentIndex: 0, delta: text, partial: message });
+        stream.push({ type: "text_end", contentIndex: 0, content: text, partial: message });
+    }
+    message.content.forEach((block, index) => {
+        if (block.type !== "toolCall")
+            return;
+        stream.push({ type: "toolcall_start", contentIndex: index, partial: message });
+        stream.push({ type: "toolcall_end", contentIndex: index, toolCall: block, partial: message });
+    });
+    stream.push({ type: "done", reason: "stop", message });
+    stream.end(message);
+}
+function emitError(stream, model, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const output = buildAssistantMessage(model, [], undefined, "error", message);
+    stream.push({ type: "error", reason: "error", error: output });
+    stream.end(output);
+}
+export function streamViaCursorAgent(model, context, options) {
+    const stream = createAssistantMessageEventStream();
+    queueMicrotask(async () => {
+        try {
+            const cwd = options?.cwd || process.cwd();
+            const prompt = buildCursorPrompt(context);
+            const plan = buildCursorAgentRunPlan(model.id, prompt, cwd);
+            const runForTest = options?._cursorAgentRunnerForTest;
+            let text = "";
+            let usage;
+            let streamStarted = false;
+            let textStarted = false;
+            const toolCalls = new Map();
+            const content = [];
+            const partialMessage = () => {
+                const partialContent = text ? [{ type: "text", text }, ...content] : [...content];
+                return buildAssistantMessage(model, partialContent, usage);
+            };
+            const ensureStart = () => {
+                if (streamStarted)
+                    return;
+                streamStarted = true;
+                stream.push({ type: "start", partial: buildAssistantMessage(model, []) });
+            };
+            const handleLine = (line) => {
+                const parsed = parseCursorAgentLine(line);
+                if (parsed.type === "ignore")
+                    return;
+                if (parsed.type === "error")
+                    throw new Error(parsed.message);
+                if (parsed.type === "text") {
+                    ensureStart();
+                    if (!textStarted) {
+                        textStarted = true;
+                        stream.push({ type: "text_start", contentIndex: 0, partial: partialMessage() });
+                    }
+                    text += parsed.text;
+                    stream.push({ type: "text_delta", contentIndex: 0, delta: parsed.text, partial: partialMessage() });
+                    return;
+                }
+                if (parsed.type === "usage") {
+                    usage = { ...(usage ?? {}), ...parsed.usage };
+                    return;
+                }
+                if (parsed.type === "tool_call") {
+                    ensureStart();
+                    toolCalls.set(parsed.toolCall.id, parsed.toolCall);
+                    content.push(parsed.toolCall);
+                    const index = text ? content.length : content.length - 1;
+                    const partial = partialMessage();
+                    stream.push({ type: "toolcall_start", contentIndex: index, partial });
+                    stream.push({ type: "toolcall_end", contentIndex: index, toolCall: parsed.toolCall, partial });
+                    return;
+                }
+                if (parsed.type === "tool_result") {
+                    const toolCall = toolCalls.get(parsed.toolCallId);
+                    if (toolCall)
+                        toolCall.externalResult = parsed.result;
+                }
+            };
+            const result = runForTest
+                ? await runForTest(plan, options, handleLine)
+                : await runCursorAgent(plan, options, handleLine);
+            if (runForTest) {
+                for (const line of result.stdout.split(/\r?\n/))
+                    handleLine(line);
+            }
+            if (result.code !== 0) {
+                throw new Error((result.stderr || result.stdout || `cursor-agent exited with code ${result.code}`).trim());
+            }
+            const finalContent = text ? [{ type: "text", text }, ...content] : content;
+            const finalMessage = buildAssistantMessage(model, finalContent, usage);
+            if (!streamStarted) {
+                emitDone(stream, finalMessage, text);
+                return;
+            }
+            if (textStarted)
+                stream.push({ type: "text_end", contentIndex: 0, content: text, partial: finalMessage });
+            stream.push({ type: "done", reason: "stop", message: finalMessage });
+            stream.end(finalMessage);
+        }
+        catch (error) {
+            emitError(stream, model, error);
+        }
+    });
+    return stream;
+}

package/dist/resources/extensions/gsd/activity-log.js

@@ -13,6 +13,7 @@ import { join } from "node:path";
 import { GSDError, GSD_IO_ERROR } from "./errors.js";
 const SEQ_PREFIX_RE = /^(\d+)-/;
 import { gsdRoot } from "./paths.js";
+import { redactSecrets } from "./redact-secrets.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
 const activityLogState = new Map();
@@ -104,7 +105,9 @@ export function saveActivityLog(ctx, basePath, unitType, unitId) {
         const fd = openSync(filePath, "w");
         try {
             for (const entry of entries) {
-                writeSync(fd, JSON.stringify(entry) + "\n");
+                // Redact secret-shaped substrings before persisting; .gsd/ is skipped by
+                // the secret scanner, so raw LLM/tool content could otherwise leak keys.
+                writeSync(fd, redactSecrets(JSON.stringify(entry)) + "\n");
             }
         }
         finally {

package/dist/resources/extensions/gsd/artifact-verification.js

@@ -47,6 +47,10 @@ function parseRoadmapForRecovery(content) {
         return _roadmapParserFn(content);
     return parseLegacyRoadmap(content);
 }
+/** Slice count for plan-milestone verification; shared by scoped and legacy paths. */
+export function countPlanMilestoneRoadmapSlices(content) {
+    return parseRoadmapForRecovery(content).slices.length;
+}
 export function diagnoseWorktreeIntegrityFailure(basePath) {
     if (!isGsdWorktreePath(basePath))
         return null;
@@ -294,8 +298,7 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
     }
     if (unitType === "plan-milestone") {
         try {
-            const roadmap = parseRoadmapForRecovery(readFileSync(absPath, "utf-8"));
-            if (roadmap.slices.length === 0) {
+            if (countPlanMilestoneRoadmapSlices(readFileSync(absPath, "utf-8")) === 0) {
                 logWarning("recovery", `verify-fail ${unitType} ${unitId}: roadmap has zero slices at ${absPath}`);
                 return false;
             }
@@ -311,6 +314,19 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
             try {
                 let taskIds = null;
                 let dbPrimary = false;
+                const planContent = readFileSync(absPath, "utf-8");
+                let parsedTaskIds = null;
+                const getParsedTaskIds = () => {
+                    if (parsedTaskIds)
+                        return parsedTaskIds;
+                    parsedTaskIds = parseLegacyPlan(planContent).tasks.map((t) => t.id);
+                    return parsedTaskIds;
+                };
+                const tasksBlockMatch = planContent.match(/<tasks>([\s\S]*?)<\/tasks>/i);
+                const tasksBlock = tasksBlockMatch?.[1] ?? "";
+                const hasEmbeddedTaskEntries = tasksBlock.length > 0 &&
+                    (/^\s*- \[[xX ]\] \*\*T\d+/m.test(tasksBlock) ||
+                        /^\s*#{2,4}\s+T\d+\s*(?:--|—|:)/m.test(tasksBlock));
                 if (isDbAvailable()) {
                     const refreshed = refreshWorkflowDatabaseFromDisk();
                     if (refreshed) {
@@ -322,24 +338,24 @@ export function verifyExpectedArtifact(unitType, unitId, base) {
                     }
                 }
                 if (!taskIds) {
-                    const planContent = readFileSync(absPath, "utf-8");
                     const hasCheckboxTask = /^\s*- \[[xX ]\] \*\*T\d+/m.test(planContent);
                     const hasHeadingTask = /^\s*#{2,4}\s+T\d+\s*(?:--|—|:)/m.test(planContent);
                     if (!hasCheckboxTask && !hasHeadingTask) {
                         logWarning("recovery", `verify-fail ${unitType} ${unitId}: plan has no task checkbox/heading (len=${planContent.length}) at ${absPath}`);
                         return false;
                     }
-                    const plan = parseLegacyPlan(planContent);
-                    if (plan.tasks.length > 0)
-                        taskIds = plan.tasks.map((t) => t.id);
+                    const parsedIds = getParsedTaskIds();
+                    if (parsedIds.length > 0)
+                        taskIds = parsedIds;
                 }
-                if (taskIds && taskIds.length > 0) {
+                if (taskIds && taskIds.length > 0 && !hasEmbeddedTaskEntries) {
                     const tasksDir = join(dirname(absPath), "tasks");
                     if (existsSync(tasksDir)) {
                         for (const tid of taskIds) {
                             const taskPlanFile = join(tasksDir, `${tid}-PLAN.md`);
-                            if (!existsSync(taskPlanFile)) {
-                                logWarning("recovery", `verify-fail ${unitType} ${unitId}: task plan missing ${taskPlanFile}`);
+                            const taskSummaryFile = join(tasksDir, `${tid}-SUMMARY.md`);
+                            if (!existsSync(taskPlanFile) && !existsSync(taskSummaryFile)) {
+                                logWarning("recovery", `verify-fail ${unitType} ${unitId}: task artifact missing for ${tid}`);
                                 return false;
                             }
                         }

package/dist/resources/extensions/gsd/auto/closeout.js

@@ -1,12 +1,17 @@
 // Project/App: gsd-pi
 // File Purpose: Auto-loop closeout, milestone report, and merge helpers.
 import { importExtensionModule } from "@gsd/pi-coding-agent";
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { join, basename } from "node:path";
+import { readFileSync } from "node:fs";
 import { MergeConflictError } from "../git-service.js";
 import { findUnmergedCompletedMilestones } from "../unmerged-milestone-guard.js";
 import { getIsolationMode } from "../preferences.js";
 import { isDbAvailable, getMilestone } from "../gsd-db.js";
 import { refreshWorkflowDatabaseFromDisk } from "../db-workspace.js";
 import { isClosedStatus } from "../status-guards.js";
+import { PLANNING_ARTIFACT_SUFFIXES } from "../paths.js";
 import { logWarning, logError } from "../workflow-logger.js";
 import { debugLog } from "../debug-logger.js";
 import { _resolveReportBasePath } from "./phase-helpers.js";
@@ -37,62 +42,59 @@ export async function restorePreflightStashOrStop(ic, preflight, milestoneId) {
     return stopOnPostflightRecoveryNeeded(ic, result, milestoneId);
 }
 /**
- * Run a milestone merge surrounded by preflight stash + always-on postflight
- * pop. The previous code popped the stash only after a successful merge, which
- * leaked `gsd-preflight-stash:M00x:*` entries whenever `mergeAndExit` threw —
- * leaving the user's pre-merge working tree silently stashed away after a
- * merge-conflict or other merge error. This helper restores the stash on
- * every exit path, then surfaces the merge or stash failure (in priority
- * order) as the loop's stop reason.
+ * Run a milestone merge through Worktree Lifecycle's guarded merge option,
+ * which surrounds the inner merge with preflight stash + always-on postflight
+ * pop. The previous closeout code popped the stash only after a successful
+ * merge, which leaked `gsd-preflight-stash:M00x:*` entries whenever
+ * `mergeAndExit` threw — leaving the user's pre-merge working tree silently
+ * stashed away after a merge-conflict or other merge error. Lifecycle now
+ * restores the stash on every attempted merge path, then this adapter surfaces
+ * the merge or stash failure (in priority order) as the loop's stop reason.
  *
  * Returns a `break` action when auto-mode must stop, or `null` when the merge
  * succeeded and the stash (if any) was restored cleanly.
  */
 export async function _runMilestoneMergeWithStashRestore(ic, milestoneId, options = {}) {
     const { ctx, pi, s, deps } = ic;
-    const preflight = deps.preflightCleanRoot(s.originalBasePath || s.basePath, milestoneId, ctx.ui.notify.bind(ctx.ui));
-    if (preflight.blocked) {
-        const reason = preflight.blockedReason === "unmerged-conflicts"
+    // Resolve the project root once, before the merge can flip session path
+    // pointers (worktree teardown mutates s.basePath / s.scope). The guarded
+    // merge's preflight/postflight stash restore, the pre-merge ignored-markdown
+    // snapshot, the dirty-projection check, and the rebuild must all target this
+    // same tree; otherwise `.gsd` markdown restored on one tree can be silently
+    // overwritten by a rebuild on another. canonicalProjectRoot is the
+    // authoritative `.gsd`/DB writer path (see AutoSession.canonicalProjectRoot).
+    const projectRoot = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
+    const ignoredProjectionSnapshot = snapshotIgnoredGsdMarkdownProjections(projectRoot);
+    const mergeResult = deps.lifecycle.exitMilestone(milestoneId, {
+        merge: true,
+        guardedMerge: {
+            projectRoot,
+            preflightCleanRoot: deps.preflightCleanRoot,
+            postflightPopStash: deps.postflightPopStash,
+        },
+    }, ctx.ui);
+    if (mergeResult.ok) {
+        await markMilestoneMergedAndRebuild(s, projectRoot, ignoredProjectionSnapshot);
+        return null;
+    }
+    if (mergeResult.reason === "postflight-stash-restore-failed") {
+        await markMilestoneMergedAndRebuild(s, projectRoot, ignoredProjectionSnapshot);
+    }
+    if (mergeResult.reason === "preflight-dirty-overlap" || mergeResult.reason === "preflight-unmerged-conflicts") {
+        const reason = mergeResult.reason === "preflight-unmerged-conflicts"
             ? `Pre-merge unresolved Git conflicts block milestone ${milestoneId}`
             : `Pre-merge dirty working tree overlaps milestone ${milestoneId}`;
         await deps.stopAuto(ctx, pi, reason, {
             preserveCompletedMilestoneBranch: true,
             preserveCloseoutTranscript: options.preserveCloseoutTranscript,
         });
-        return {
-            action: "break",
-            reason: preflight.blockedReason === "unmerged-conflicts"
-                ? "preflight-unmerged-conflicts"
-                : "preflight-dirty-overlap",
-        };
-    }
-    let mergeError = null;
-    const exitResult = deps.lifecycle.exitMilestone(milestoneId, { merge: true }, ctx.ui);
-    if (exitResult.ok) {
-        s.milestoneMergedInPhases = true;
-        try {
-            const projectRoot = s.originalBasePath || s.canonicalProjectRoot || s.basePath;
-            const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
-            await rebuildMarkdownProjectionsFromDb(projectRoot);
-        }
-        catch (err) {
-            logWarning("engine", `markdown projection rebuild after milestone merge failed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-    }
-    else {
-        mergeError = exitResult.cause ?? new Error(`exit ${exitResult.reason}`);
-    }
-    // Always attempt to restore the stashed working tree, even on merge error.
-    // postflightPopStash itself does not throw; failures surface via the
-    // PostflightResult.needsManualRecovery flag.
-    let stashResult = null;
-    if (preflight.stashPushed) {
-        stashResult = deps.postflightPopStash(s.originalBasePath || s.basePath, milestoneId, preflight.stashMarker, ctx.ui.notify.bind(ctx.ui));
+        return { action: "break", reason: mergeResult.reason };
     }
     // Merge failure takes priority over stash recovery — the merge is the
     // authoritative gate. If the stash also needed manual recovery, the user
     // already saw the postflightPopStash notify above.
-    if (mergeError) {
+    if (mergeResult.reason === "merge-conflict") {
+        const mergeError = mergeResult.cause;
         if (mergeError instanceof MergeConflictError) {
             // A merge conflict is a recoverable human checkpoint, not an
             // infrastructure failure — the user resolves the conflict and runs
@@ -109,6 +111,9 @@ export async function _runMilestoneMergeWithStashRestore(ic, milestoneId, option
             });
             return { action: "break", reason: "merge-conflict" };
         }
+    }
+    if (mergeResult.reason === "merge-failed" || mergeResult.reason === "merge-conflict") {
+        const mergeError = mergeResult.cause;
         logError("engine", "Milestone merge failed with non-conflict error", {
             milestone: milestoneId,
             error: String(mergeError),
@@ -125,11 +130,101 @@ export async function _runMilestoneMergeWithStashRestore(ic, milestoneId, option
         });
         return { action: "break", reason: "merge-failed" };
     }
-    if (stashResult) {
-        return stopOnPostflightRecoveryNeeded(ic, stashResult, milestoneId);
+    if (mergeResult.postflight) {
+        return stopOnPostflightRecoveryNeeded(ic, mergeResult.postflight, milestoneId);
     }
     return null;
 }
+async function markMilestoneMergedAndRebuild(s, rebuildBasePath, ignoredProjectionSnapshot) {
+    s.milestoneMergedInPhases = true;
+    if (hasDirtyGsdMarkdownProjections(rebuildBasePath, ignoredProjectionSnapshot)) {
+        logWarning("engine", "skipping markdown projection rebuild after milestone merge because restored .gsd edits are dirty");
+        return;
+    }
+    try {
+        const { rebuildMarkdownProjectionsFromDb } = await import("../commands-maintenance.js");
+        await rebuildMarkdownProjectionsFromDb(rebuildBasePath);
+    }
+    catch (err) {
+        logWarning("engine", `markdown projection rebuild after milestone merge failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function hasDirtyGsdMarkdownProjections(basePath, ignoredProjectionSnapshot) {
+    try {
+        const output = execFileSync("git", ["status", "--porcelain", "-z", "--untracked-files=all", "--", ".gsd"], { cwd: basePath, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        const entries = output.split("\0").filter(Boolean);
+        for (let i = 0; i < entries.length; i++) {
+            const entry = entries[i];
+            if (entry.length <= 3)
+                continue;
+            const status = entry.slice(0, 2);
+            const path = entry.slice(3);
+            if (isGeneratedGsdMarkdownProjection(path))
+                return true;
+            if ((status === "R " || status === "C ") && i + 1 < entries.length) {
+                const dest = entries[++i];
+                if (isGeneratedGsdMarkdownProjection(dest))
+                    return true;
+            }
+        }
+    }
+    catch (err) {
+        void err;
+        // Fall through to ignored-file snapshot comparison below.
+    }
+    return ignoredGsdMarkdownProjectionSnapshotChanged(basePath, ignoredProjectionSnapshot);
+}
+function isGeneratedGsdMarkdownProjection(path) {
+    const normalized = path.replace(/\\/g, "/");
+    if (normalized === ".gsd/DECISIONS.md")
+        return true;
+    if (!normalized.startsWith(".gsd/milestones/") && !normalized.startsWith(".gsd/phases/")) {
+        return false;
+    }
+    return isGeneratedPlanningArtifactFileName(basename(normalized));
+}
+function isGeneratedPlanningArtifactFileName(fileName) {
+    if (!fileName.endsWith(".md"))
+        return false;
+    const stem = fileName.slice(0, -".md".length).toUpperCase();
+    for (const suffix of PLANNING_ARTIFACT_SUFFIXES) {
+        if (!stem.endsWith(`-${suffix}`))
+            continue;
+        const idPrefix = stem.slice(0, -suffix.length - 1);
+        return /^(?:[MST]\d+|\d{2,})(?:-[A-Z0-9]+)*$/.test(idPrefix);
+    }
+    return false;
+}
+function snapshotIgnoredGsdMarkdownProjections(basePath) {
+    try {
+        const output = execFileSync("git", ["ls-files", "--others", "--ignored", "--exclude-standard", "-z", "--", ".gsd"], { cwd: basePath, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+        const snapshot = new Map();
+        for (const path of output.split("\0")) {
+            if (!isGeneratedGsdMarkdownProjection(path))
+                continue;
+            snapshot.set(path, hashFile(join(basePath, path)));
+        }
+        return snapshot;
+    }
+    catch {
+        return null;
+    }
+}
+function hashFile(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+function ignoredGsdMarkdownProjectionSnapshotChanged(basePath, before) {
+    if (!before)
+        return true;
+    const after = snapshotIgnoredGsdMarkdownProjections(basePath);
+    if (!after || after.size !== before.size)
+        return true;
+    for (const [path, hash] of before) {
+        if (after.get(path) !== hash)
+            return true;
+    }
+    return false;
+}
 export async function _runMilestoneMergeOnceWithStashRestore(ic, milestoneId, options = {}) {
     if (ic.s.milestoneMergedInPhases) {
         debugLog("autoLoop", {