gsd-pi 2.44.0 → 2.45.0-dev.1afbdaa

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

@@ -0,0 +1,411 @@
+import { join } from "node:path";
+import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
+import { readEvents, findForkPoint, appendEvent, getSessionId } from "./workflow-events.js";
+import { transaction, updateTaskStatus, updateSliceStatus, insertVerificationEvidence, upsertDecision, openDatabase, } from "./gsd-db.js";
+import { writeManifest } from "./workflow-manifest.js";
+import { atomicWriteSync } from "./atomic-write.js";
+import { acquireSyncLock, releaseSyncLock } from "./sync-lock.js";
+// ─── replayEvents ─────────────────────────────────────────────────────────────
+/**
+ * Replay a list of WorkflowEvents by dispatching each to the appropriate
+ * gsd-db function.  This replaces the old engine.replayAll() pattern with
+ * direct DB calls.
+ */
+function replayEvents(events) {
+    transaction(() => {
+        for (const event of events) {
+            const p = event.params;
+            switch (event.cmd) {
+                case "complete_task": {
+                    const milestoneId = p["milestoneId"];
+                    const sliceId = p["sliceId"];
+                    const taskId = p["taskId"];
+                    updateTaskStatus(milestoneId, sliceId, taskId, "done", event.ts);
+                    break;
+                }
+                case "start_task": {
+                    const milestoneId = p["milestoneId"];
+                    const sliceId = p["sliceId"];
+                    const taskId = p["taskId"];
+                    updateTaskStatus(milestoneId, sliceId, taskId, "in-progress", event.ts);
+                    break;
+                }
+                case "report_blocker": {
+                    // report_blocker marks the task with blocker_discovered = 1
+                    // The DB helper updateTaskStatus doesn't handle blockers,
+                    // so we just update status to "blocked" as a best-effort replay.
+                    const milestoneId = p["milestoneId"];
+                    const sliceId = p["sliceId"];
+                    const taskId = p["taskId"];
+                    updateTaskStatus(milestoneId, sliceId, taskId, "blocked");
+                    break;
+                }
+                case "record_verification": {
+                    const milestoneId = p["milestoneId"];
+                    const sliceId = p["sliceId"];
+                    const taskId = p["taskId"];
+                    insertVerificationEvidence({
+                        taskId,
+                        sliceId,
+                        milestoneId,
+                        command: p["command"] ?? "",
+                        exitCode: p["exitCode"] ?? 0,
+                        verdict: p["verdict"] ?? "",
+                        durationMs: p["durationMs"] ?? 0,
+                    });
+                    break;
+                }
+                case "complete_slice": {
+                    const milestoneId = p["milestoneId"];
+                    const sliceId = p["sliceId"];
+                    updateSliceStatus(milestoneId, sliceId, "done", event.ts);
+                    break;
+                }
+                case "plan_slice": {
+                    // plan_slice events are informational — slice should already exist.
+                    // No DB mutation needed during replay (the slice was inserted at plan time).
+                    break;
+                }
+                case "save_decision": {
+                    upsertDecision({
+                        id: p["id"] ?? `${p["scope"]}:${p["decision"]}`,
+                        when_context: p["when_context"] ?? p["whenContext"] ?? "",
+                        scope: p["scope"] ?? "",
+                        decision: p["decision"] ?? "",
+                        choice: p["choice"] ?? "",
+                        rationale: p["rationale"] ?? "",
+                        revisable: p["revisable"] ?? "yes",
+                        made_by: (p["made_by"] ?? p["madeBy"] ?? "agent"),
+                        superseded_by: p["superseded_by"] ?? p["supersededBy"] ?? null,
+                    });
+                    break;
+                }
+                default:
+                    // Unknown commands are silently skipped during replay
+                    break;
+            }
+        }
+    }); // end transaction
+}
+// ─── extractEntityKey ─────────────────────────────────────────────────────────
+/**
+ * Map a WorkflowEvent command to its affected entity type and ID.
+ * Returns null for commands that don't touch a named entity
+ * (e.g. unknown or future cmds).
+ */
+export function extractEntityKey(event) {
+    const p = event.params;
+    switch (event.cmd) {
+        case "complete_task":
+        case "start_task":
+        case "report_blocker":
+        case "record_verification":
+            return typeof p["taskId"] === "string"
+                ? { type: "task", id: p["taskId"] }
+                : null;
+        case "complete_slice":
+            return typeof p["sliceId"] === "string"
+                ? { type: "slice", id: p["sliceId"] }
+                : null;
+        case "plan_slice":
+            return typeof p["sliceId"] === "string"
+                ? { type: "slice_plan", id: p["sliceId"] }
+                : null;
+        case "save_decision":
+            if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
+                return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
+            }
+            return null;
+        default:
+            return null;
+    }
+}
+// ─── detectConflicts ──────────────────────────────────────────────────────────
+/**
+ * Compare two sets of diverged events. Returns conflict entries for any
+ * entity touched by both sides.
+ *
+ * Entity-level granularity: if both sides touched task T01 (with any cmd),
+ * that is one conflict regardless of field-level differences.
+ */
+export function detectConflicts(mainDiverged, wtDiverged) {
+    // Group each side's events by entity key
+    const mainByEntity = new Map();
+    for (const event of mainDiverged) {
+        const key = extractEntityKey(event);
+        if (!key)
+            continue;
+        const bucket = mainByEntity.get(`${key.type}:${key.id}`) ?? [];
+        bucket.push(event);
+        mainByEntity.set(`${key.type}:${key.id}`, bucket);
+    }
+    const wtByEntity = new Map();
+    for (const event of wtDiverged) {
+        const key = extractEntityKey(event);
+        if (!key)
+            continue;
+        const bucket = wtByEntity.get(`${key.type}:${key.id}`) ?? [];
+        bucket.push(event);
+        wtByEntity.set(`${key.type}:${key.id}`, bucket);
+    }
+    // Find entities touched by both sides
+    const conflicts = [];
+    for (const [entityKey, mainEvents] of mainByEntity) {
+        const wtEvents = wtByEntity.get(entityKey);
+        if (!wtEvents)
+            continue;
+        const colonIdx = entityKey.indexOf(":");
+        const entityType = entityKey.slice(0, colonIdx);
+        const entityId = entityKey.slice(colonIdx + 1);
+        conflicts.push({
+            entityType,
+            entityId,
+            mainSideEvents: mainEvents,
+            worktreeSideEvents: wtEvents,
+        });
+    }
+    return conflicts;
+}
+// ─── writeConflictsFile ───────────────────────────────────────────────────────
+/**
+ * Write a human-readable CONFLICTS.md to basePath/.gsd/CONFLICTS.md.
+ * Lists each conflict with both sides' event payloads and resolution instructions.
+ */
+export function writeConflictsFile(basePath, conflicts, worktreePath) {
+    const timestamp = new Date().toISOString();
+    const lines = [
+        `# Merge Conflicts — ${timestamp}`,
+        "",
+        `Conflicts detected merging worktree \`${worktreePath}\` into \`${basePath}\`.`,
+        `Run \`gsd resolve-conflict\` to resolve each conflict.`,
+        "",
+    ];
+    conflicts.forEach((conflict, idx) => {
+        lines.push(`## Conflict ${idx + 1}: ${conflict.entityType} ${conflict.entityId}`);
+        lines.push("");
+        lines.push("**Main side events:**");
+        for (const event of conflict.mainSideEvents) {
+            lines.push(`- ${event.cmd} at ${event.ts} (hash: ${event.hash})`);
+            lines.push(`  params: ${JSON.stringify(event.params)}`);
+        }
+        lines.push("");
+        lines.push("**Worktree side events:**");
+        for (const event of conflict.worktreeSideEvents) {
+            lines.push(`- ${event.cmd} at ${event.ts} (hash: ${event.hash})`);
+            lines.push(`  params: ${JSON.stringify(event.params)}`);
+        }
+        lines.push("");
+        lines.push(`**Resolve with:** \`gsd resolve-conflict --entity ${conflict.entityType}:${conflict.entityId} --pick [main|worktree]\``);
+        lines.push("");
+    });
+    const content = lines.join("\n");
+    const dir = join(basePath, ".gsd");
+    mkdirSync(dir, { recursive: true });
+    atomicWriteSync(join(dir, "CONFLICTS.md"), content);
+}
+// ─── reconcileWorktreeLogs ────────────────────────────────────────────────────
+/**
+ * Event-log-based reconciliation algorithm:
+ *
+ * 1. Read both event logs
+ * 2. Find fork point (last common event by hash)
+ * 3. Slice diverged sets from each side
+ * 4. If no divergence on either side → return autoMerged: 0, conflicts: []
+ * 5. detectConflicts() — if any, writeConflictsFile + return early (D-04 all-or-nothing)
+ * 6. If clean: sort merged = mainDiverged + wtDiverged by timestamp, replayAll
+ * 7. Write merged event log (base + merged in timestamp order)
+ * 8. writeManifest
+ * 9. Return { autoMerged: merged.length, conflicts: [] }
+ */
+export function reconcileWorktreeLogs(mainBasePath, worktreeBasePath) {
+    // Acquire advisory lock to prevent concurrent reconcile + append races
+    const lock = acquireSyncLock(mainBasePath);
+    if (!lock.acquired) {
+        process.stderr.write(`[gsd] reconcile: could not acquire sync lock — another reconciliation may be in progress\n`);
+        return { autoMerged: 0, conflicts: [] };
+    }
+    try {
+        return _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath);
+    }
+    finally {
+        releaseSyncLock(mainBasePath);
+    }
+}
+function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
+    // Step 1: Read both logs
+    const mainLogPath = join(mainBasePath, ".gsd", "event-log.jsonl");
+    const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+    const mainEvents = readEvents(mainLogPath);
+    const wtEvents = readEvents(wtLogPath);
+    // Step 2: Find fork point
+    const forkPoint = findForkPoint(mainEvents, wtEvents);
+    // Step 3: Slice diverged sets
+    const mainDiverged = mainEvents.slice(forkPoint + 1);
+    const wtDiverged = wtEvents.slice(forkPoint + 1);
+    // Step 4: No divergence on either side
+    if (mainDiverged.length === 0 && wtDiverged.length === 0) {
+        return { autoMerged: 0, conflicts: [] };
+    }
+    // Step 5: Detect conflicts (entity-level)
+    const conflicts = detectConflicts(mainDiverged, wtDiverged);
+    if (conflicts.length > 0) {
+        // D-04: atomic all-or-nothing — block entire merge
+        writeConflictsFile(mainBasePath, conflicts, worktreeBasePath);
+        process.stderr.write(`[gsd] reconcile: ${conflicts.length} conflict(s) detected — see ${join(mainBasePath, ".gsd", "CONFLICTS.md")}\n`);
+        return { autoMerged: 0, conflicts };
+    }
+    // Step 6: Clean merge — stable sort by timestamp (index-based tiebreaker)
+    const indexed = [...mainDiverged, ...wtDiverged].map((e, i) => ({ e, i }));
+    indexed.sort((a, b) => a.e.ts.localeCompare(b.e.ts) || a.i - b.i);
+    const merged = indexed.map(({ e }) => e);
+    // Step 7: Write merged event log FIRST (so crash recovery can re-derive DB state)
+    const baseEvents = mainEvents.slice(0, forkPoint + 1);
+    const mergedLog = baseEvents.concat(merged);
+    const logContent = mergedLog.map((e) => JSON.stringify(e)).join("\n") + (mergedLog.length > 0 ? "\n" : "");
+    mkdirSync(join(mainBasePath, ".gsd"), { recursive: true });
+    atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
+    // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
+    openDatabase(join(mainBasePath, ".gsd", "gsd.db"));
+    replayEvents(merged);
+    // Step 9: Write manifest
+    try {
+        writeManifest(mainBasePath);
+    }
+    catch (err) {
+        process.stderr.write(`[gsd] reconcile: manifest write failed (non-fatal): ${err.message}\n`);
+    }
+    return { autoMerged: merged.length, conflicts: [] };
+}
+// ─── Conflict Resolution (D-06) ─────────────────────────────────────────────
+/**
+ * Parse CONFLICTS.md and return structured ConflictEntry[].
+ * Returns empty array when CONFLICTS.md does not exist.
+ *
+ * Parses the format written by writeConflictsFile:
+ *   ## Conflict N: {entityType} {entityId}
+ *   **Main side events:**
+ *   - {cmd} at {ts} (hash: {hash})
+ *     params: {JSON}
+ *   **Worktree side events:**
+ *   - {cmd} at {ts} (hash: {hash})
+ *     params: {JSON}
+ */
+export function listConflicts(basePath) {
+    const conflictsPath = join(basePath, ".gsd", "CONFLICTS.md");
+    if (!existsSync(conflictsPath))
+        return [];
+    const content = readFileSync(conflictsPath, "utf-8");
+    const conflicts = [];
+    // Split into per-conflict sections on "## Conflict N:" headings
+    const sections = content.split(/^## Conflict \d+:/m).slice(1);
+    for (const section of sections) {
+        // Extract entity type and id from first line: " {entityType} {entityId}"
+        const headingMatch = section.match(/^\s+(\S+)\s+(\S+)/);
+        if (!headingMatch)
+            continue;
+        const entityType = headingMatch[1];
+        const entityId = headingMatch[2];
+        // Split into main/worktree blocks
+        const mainMatch = section.split("**Main side events:**")[1];
+        const wtMatch = mainMatch?.split("**Worktree side events:**");
+        const mainBlock = wtMatch?.[0] ?? "";
+        const wtBlock = wtMatch?.[1] ?? "";
+        const mainSideEvents = parseEventBlock(mainBlock);
+        const worktreeSideEvents = parseEventBlock(wtBlock);
+        conflicts.push({ entityType, entityId, mainSideEvents, worktreeSideEvents });
+    }
+    return conflicts;
+}
+/**
+ * Parse a block of event lines from CONFLICTS.md into WorkflowEvent[].
+ * Each event spans two lines:
+ *   - {cmd} at {ts} (hash: {hash})
+ *     params: {JSON}
+ */
+function parseEventBlock(block) {
+    const events = [];
+    // Find lines starting with "- " (event lines)
+    const lines = block.split("\n");
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i].trim();
+        if (line.startsWith("- ")) {
+            // Parse: - {cmd} at {ts} (hash: {hash})
+            const eventMatch = line.match(/^-\s+(\S+)\s+at\s+(\S+)\s+\(hash:\s+(\S+)\)$/);
+            if (eventMatch) {
+                const cmd = eventMatch[1];
+                const ts = eventMatch[2];
+                const hash = eventMatch[3];
+                // Next line: "  params: {JSON}"
+                let params = {};
+                const nextLine = lines[i + 1];
+                if (nextLine) {
+                    const paramsMatch = nextLine.trim().match(/^params:\s+(.+)$/);
+                    if (paramsMatch) {
+                        try {
+                            params = JSON.parse(paramsMatch[1]);
+                        }
+                        catch {
+                            // Keep empty params on parse error
+                        }
+                        i++; // consume params line
+                    }
+                }
+                events.push({ cmd, params, ts, hash, actor: "agent", session_id: getSessionId() });
+            }
+        }
+        i++;
+    }
+    return events;
+}
+/**
+ * Resolve a single conflict by picking one side's events.
+ * Replays the picked events through the DB helpers, appends them to the event log,
+ * and updates or removes CONFLICTS.md.
+ *
+ * When the last conflict is resolved, non-conflicting events from both sides
+ * are also replayed (they were blocked by the all-or-nothing D-04 rule).
+ */
+export function resolveConflict(basePath, worktreeBasePath, entityKey, // e.g. "task:T01"
+pick) {
+    const conflicts = listConflicts(basePath);
+    const colonIdx = entityKey.indexOf(":");
+    const entityType = entityKey.slice(0, colonIdx);
+    const entityId = entityKey.slice(colonIdx + 1);
+    const idx = conflicts.findIndex((c) => c.entityType === entityType && c.entityId === entityId);
+    if (idx === -1)
+        throw new Error(`No conflict found for entity ${entityKey}`);
+    const conflict = conflicts[idx];
+    const eventsToReplay = pick === "main" ? conflict.mainSideEvents : conflict.worktreeSideEvents;
+    // Replay resolved events through the DB (updates DB state)
+    openDatabase(join(basePath, ".gsd", "gsd.db"));
+    replayEvents(eventsToReplay);
+    // Append resolved events to the event log
+    for (const event of eventsToReplay) {
+        appendEvent(basePath, { cmd: event.cmd, params: event.params, ts: event.ts, actor: event.actor });
+    }
+    // Remove resolved conflict from list
+    conflicts.splice(idx, 1);
+    if (conflicts.length === 0) {
+        // All conflicts resolved — remove CONFLICTS.md and re-run reconciliation
+        // to pick up non-conflicting events that were blocked by D-04 all-or-nothing.
+        removeConflictsFile(basePath);
+        if (worktreeBasePath) {
+            reconcileWorktreeLogs(basePath, worktreeBasePath);
+        }
+    }
+    else {
+        // Re-write CONFLICTS.md with remaining conflicts
+        writeConflictsFile(basePath, conflicts, worktreeBasePath);
+    }
+}
+/**
+ * Remove CONFLICTS.md — called when all conflicts are resolved.
+ * No-op if CONFLICTS.md does not exist.
+ */
+export function removeConflictsFile(basePath) {
+    const conflictsPath = join(basePath, ".gsd", "CONFLICTS.md");
+    if (existsSync(conflictsPath)) {
+        unlinkSync(conflictsPath);
+    }
+}

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

@@ -15,8 +15,10 @@
  *   4. remove()  — git worktree remove + branch cleanup
  */
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { join, resolve, sep } from "node:path";
 import { GSDError, GSD_PARSE_ERROR, GSD_STALE_STATE, GSD_LOCK_HELD, GSD_GIT_ERROR, GSD_MERGE_CONFLICT } from "./errors.js";
+import { logWarning } from "./workflow-logger.js";
 import { nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeLogOneline, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 function normalizePathForComparison(path) {
@@ -84,7 +86,7 @@ export function createWorktree(basePath, name, opts = {}) {
         // worktree can be created in its place.
         const gitFilePath = join(wtPath, ".git");
         if (!existsSync(gitFilePath)) {
-            console.error(`[GSD] Removing stale worktree directory (no .git file): ${wtPath}`);
+            logWarning("reconcile", `Removing stale worktree directory (no .git file): ${wtPath}`, { worktree: name });
             rmSync(wtPath, { recursive: true, force: true });
         }
         else {
@@ -240,9 +242,38 @@ export function removeWorktree(basePath, name, opts = {}) {
         }
         return;
     }
-    // Remove worktree using the resolved path (force if requested, to handle dirty worktrees)
+    // Submodule safety (#2337): detect submodules with uncommitted changes
+    // before force-removing the worktree. Force removal destroys all uncommitted
+    // state, which is especially destructive for submodule directories.
+    let hasSubmoduleChanges = false;
+    const gitmodulesPath = join(resolvedWtPath, ".gitmodules");
+    if (existsSync(gitmodulesPath)) {
+        try {
+            const submoduleStatus = execFileSync("git", ["submodule", "status"], { cwd: resolvedWtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" }).trim();
+            // Lines starting with '+' indicate uncommitted submodule changes
+            hasSubmoduleChanges = submoduleStatus.split("\n").some((line) => line.startsWith("+") || line.startsWith("-"));
+            if (hasSubmoduleChanges) {
+                // Stash submodule changes so they are not lost during force removal.
+                // The stash is created in the worktree before it's torn down.
+                try {
+                    execFileSync("git", ["stash", "push", "-m", "gsd: auto-stash submodule changes before worktree teardown"], { cwd: resolvedWtPath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8" });
+                    logWarning("reconcile", `Stashed uncommitted submodule changes before worktree teardown`, { worktree: name, path: resolvedWtPath });
+                }
+                catch {
+                    // Stash failed — warn the user that submodule changes may be lost
+                    logWarning("reconcile", `Submodule changes detected — stash failed, changes may be lost during force removal`, { worktree: name, path: resolvedWtPath });
+                }
+            }
+        }
+        catch {
+            // submodule status failed — proceed with normal removal
+        }
+    }
+    // Remove worktree: try non-force first when submodules have changes,
+    // falling back to force only after submodule state has been preserved.
+    const useForce = hasSubmoduleChanges ? false : force;
     try {
-        nativeWorktreeRemove(basePath, resolvedWtPath, force);
+        nativeWorktreeRemove(basePath, resolvedWtPath, useForce);
     }
     catch { /* may fail */ }
     // If the directory is still there (e.g. locked), try harder with force

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

@@ -13,8 +13,11 @@
  * `process.chdir()` internally — this class MUST NOT double-chdir.
  */
 import { existsSync, unlinkSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { join } from "node:path";
 import { debugLog } from "./debug-logger.js";
+import { MergeConflictError } from "./git-service.js";
+import { emitJournalEvent } from "./journal.js";
 // ─── WorktreeResolver ──────────────────────────────────────────────────────
 export class WorktreeResolver {
     s;
@@ -76,6 +79,13 @@ export class WorktreeResolver {
                 skipped: true,
                 reason: "isolation-disabled",
             });
+            emitJournalEvent(this.s.originalBasePath || this.s.basePath, {
+                ts: new Date().toISOString(),
+                flowId: randomUUID(),
+                seq: 0,
+                eventType: "worktree-skip",
+                data: { milestoneId, reason: "isolation-disabled" },
+            });
             return;
         }
         const basePath = this.s.originalBasePath || this.s.basePath;
@@ -101,6 +111,13 @@ export class WorktreeResolver {
                 result: "success",
                 wtPath,
             });
+            emitJournalEvent(this.s.originalBasePath || this.s.basePath, {
+                ts: new Date().toISOString(),
+                flowId: randomUUID(),
+                seq: 0,
+                eventType: "worktree-enter",
+                data: { milestoneId, wtPath, created: !existingPath },
+            });
             ctx.notify(`Entered worktree for ${milestoneId} at ${wtPath}`, "info");
         }
         catch (err) {
@@ -111,6 +128,13 @@ export class WorktreeResolver {
                 result: "error",
                 error: msg,
             });
+            emitJournalEvent(this.s.originalBasePath || this.s.basePath, {
+                ts: new Date().toISOString(),
+                flowId: randomUUID(),
+                seq: 0,
+                eventType: "worktree-create-failed",
+                data: { milestoneId, error: msg, fallback: "project-root" },
+            });
             ctx.notify(`Auto-worktree creation for ${milestoneId} failed: ${msg}. Continuing in project root.`, "warning");
             // Do NOT update s.basePath — stay in project root
         }
@@ -193,6 +217,13 @@ export class WorktreeResolver {
             mode,
             basePath: this.s.basePath,
         });
+        emitJournalEvent(this.s.originalBasePath || this.s.basePath, {
+            ts: new Date().toISOString(),
+            flowId: randomUUID(),
+            seq: 0,
+            eventType: "worktree-merge-start",
+            data: { milestoneId, mode },
+        });
         if (mode === "none") {
             debugLog("WorktreeResolver", {
                 action: "mergeAndExit",
@@ -284,6 +315,13 @@ export class WorktreeResolver {
                 error: msg,
                 fallback: "chdir-to-project-root",
             });
+            emitJournalEvent(this.s.originalBasePath || this.s.basePath, {
+                ts: new Date().toISOString(),
+                flowId: randomUUID(),
+                seq: 0,
+                eventType: "worktree-merge-failed",
+                data: { milestoneId, error: msg },
+            });
             // Surface a clear, actionable error. The worktree and milestone branch are
             // intentionally preserved — nothing has been deleted. The user can retry
             // /gsd dispatch complete-milestone or merge manually once the underlying issue is fixed
@@ -308,6 +346,11 @@ export class WorktreeResolver {
                     /* best-effort */
                 }
             }
+            // Re-throw MergeConflictError so the auto loop can detect real code
+            // conflicts and stop instead of retrying forever (#2330).
+            if (err instanceof MergeConflictError) {
+                throw err;
+            }
         }
         // Always restore basePath and rebuild — whether merge succeeded or failed
         this.restoreToProjectRoot();

package/dist/resources/extensions/gsd/write-intercept.js

@@ -0,0 +1,84 @@
+// GSD Extension — Write Intercept for Agent State File Blocks
+// Detects agent attempts to write authoritative state files and returns
+// an error directing the agent to use the engine tool API instead.
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Patterns matching authoritative .gsd/ state files that agents must NOT write directly.
+ *
+ * Only STATE.md is blocked — it is purely engine-rendered from DB state.
+ * All other .gsd/ files are agent-authored content that agents create and
+ * update during discuss, plan, and execute phases:
+ * - REQUIREMENTS.md — agents create during discuss, read during planning
+ * - PROJECT.md — agents create during discuss, update at milestone close
+ * - ROADMAP.md / PLAN.md — agents create during planning, engine renders checkboxes
+ * - SUMMARY.md, KNOWLEDGE.md, CONTEXT.md — non-authoritative content
+ */
+const BLOCKED_PATTERNS = [
+    // STATE.md is the only purely engine-rendered file.
+    // Case-insensitive to prevent bypass on macOS (case-insensitive APFS).
+    // (^|[/\\]) matches both absolute paths (/project/.gsd/…) and bare relative
+    // paths (.gsd/STATE.md) so a path without a leading separator is also blocked.
+    /(^|[/\\])\.gsd[/\\]STATE\.md$/i,
+    // Also match resolved symlink paths under ~/.gsd/projects/ (Pitfall #6)
+    /(^|[/\\])\.gsd[/\\]projects[/\\][^/\\]+[/\\]STATE\.md$/i,
+];
+/**
+ * Bash command patterns that target STATE.md.
+ * Covers common shell write patterns: redirect, tee, cp, mv, sed -i, etc.
+ */
+const BASH_STATE_PATTERNS = [
+    // Redirect/pipe writes: > STATE.md, >> STATE.md, >| STATE.md
+    /[>|]+\s*\S*STATE\.md/i,
+    // tee to STATE.md
+    /\btee\b.*STATE\.md/i,
+    // cp/mv targeting STATE.md
+    /\b(cp|mv)\b.*STATE\.md/i,
+    // sed -i editing STATE.md
+    /\bsed\b.*-i.*STATE\.md/i,
+    // dd output to STATE.md
+    /\bdd\b.*of=\S*STATE\.md/i,
+];
+/**
+ * Tests whether the given file path matches a blocked authoritative .gsd/ state file.
+ * Resolves `..` segments via path.resolve() and attempts realpathSync for symlinks.
+ */
+export function isBlockedStateFile(filePath) {
+    // Check raw path first
+    if (matchesBlockedPattern(filePath))
+        return true;
+    // Resolve ".." segments (works even for non-existing files)
+    const resolved = resolve(filePath);
+    if (resolved !== filePath && matchesBlockedPattern(resolved))
+        return true;
+    // Also try symlink resolution — file may not exist yet, so wrap in try/catch
+    try {
+        const realpath = realpathSync(filePath);
+        if (realpath !== filePath && realpath !== resolved && matchesBlockedPattern(realpath))
+            return true;
+    }
+    catch {
+        // File doesn't exist yet — path matching above is sufficient
+    }
+    return false;
+}
+/**
+ * Tests whether a bash command appears to target STATE.md for writing.
+ */
+export function isBashWriteToStateFile(command) {
+    return BASH_STATE_PATTERNS.some((pattern) => pattern.test(command));
+}
+function matchesBlockedPattern(path) {
+    return BLOCKED_PATTERNS.some((pattern) => pattern.test(path));
+}
+/**
+ * Error message returned when an agent attempts to directly write an authoritative .gsd/ state file.
+ * Directs the agent to use engine tool calls instead.
+ */
+export const BLOCKED_WRITE_ERROR = `Direct writes to .gsd/STATE.md are blocked. Use engine tool calls instead:
+- To complete a task: call gsd_complete_task(milestone_id, slice_id, task_id, summary)
+- To complete a slice: call gsd_complete_slice(milestone_id, slice_id, summary, uat_result)
+- To save a decision: call gsd_save_decision(scope, decision, choice, rationale)
+- To start a task: call gsd_start_task(milestone_id, slice_id, task_id)
+- To record verification: call gsd_record_verification(milestone_id, slice_id, task_id, evidence)
+- To report a blocker: call gsd_report_blocker(milestone_id, slice_id, task_id, description)`;

package/dist/resources/extensions/mcp-client/index.js

@@ -162,6 +162,20 @@ function formatToolList(serverName, tools) {
     lines.push(`Call with: mcp_call(server="${serverName}", tool="<tool_name>", args={...})`);
     return lines.join("\n");
 }
+// ─── Status helper (consumed by /gsd mcp) ─────────────────────────────────────
+/**
+ * Return the live connection status for a named MCP server.
+ * Safe to call even when the server has never been connected.
+ */
+export function getConnectionStatus(name) {
+    const conn = connections.get(name);
+    const cached = toolCache.get(name);
+    return {
+        connected: !!conn,
+        tools: cached ? cached.map((t) => t.name) : [],
+        error: undefined,
+    };
+}
 // ─── Extension ────────────────────────────────────────────────────────────────
 export default function (pi) {
     // ── mcp_servers ──────────────────────────────────────────────────────────