@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.72e3af2a

package/dist/resources/extensions/gsd/tools/complete-slice.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";
@@ -458,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,13 +5,15 @@
  *
  * 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, resolveMilestonePath, resolveSlicePath } from "../paths.js";
 import { resolveCanonicalMilestoneRoot } from "../worktree-manager.js";
@@ -19,8 +21,7 @@ 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";
@@ -60,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}`);
@@ -181,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
@@ -317,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.
@@ -435,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}`);
@@ -465,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)

package/dist/resources/extensions/gsd/unit-context-composer.js

@@ -92,13 +92,27 @@ const CONTEXT_MODE_GUIDANCE_BY_LANE = {
     orchestration: "Use `gsd_resume` before resuming orchestration, `gsd_exec_search` to reuse prior runs, and `gsd_exec` for noisy coordination checks.",
     docs: "Use `gsd_resume` for prior context, `gsd_exec_search` for saved evidence, and `gsd_exec` for noisy doc validation commands.",
 };
-// Per-unit overrides win over the lane default. run-uat's tool contract
-// forbids `gsd_exec`/`gsd_exec_search` (acceptance evidence must flow through
-// `gsd_uat_exec`) and Claude Code dispatch strips the tools entirely, so the
-// shared verification-lane guidance would steer the agent into calling an
-// unavailable tool.
-const CONTEXT_MODE_GUIDANCE_BY_UNIT = {
+// Per-unit overrides win over the lane default. Some units intentionally run
+// with narrower tool contracts than their shared Context Mode lane, so their
+// guidance must name only tools the unit can actually call.
+export const CONTEXT_MODE_GUIDANCE_BY_UNIT = {
+    "discuss-milestone": "Use `ask_user_questions` to continue the milestone interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, `gsd_requirement_save`, `gsd_requirement_update`, `gsd_plan_milestone`, or `gsd_milestone_generate_id` as appropriate.",
+    "discuss-slice": "Use `ask_user_questions` to continue the slice interview, then persist outcomes with `gsd_summary_save` or `gsd_decision_save` as appropriate.",
+    "discuss-project": "Use `ask_user_questions` to continue the project interview, then persist outcomes with `gsd_summary_save`, `gsd_decision_save`, or `gsd_requirement_save` as appropriate.",
+    "discuss-requirements": "Use `ask_user_questions` to continue the requirements interview, then persist outcomes with `gsd_requirement_save` or `gsd_summary_save` as appropriate.",
+    "replan-slice": "Use `gsd_replan_slice` to persist the revised slice plan, and `gsd_decision_save` for planning decisions that need durable rationale.",
+    "reassess-roadmap": "Use `gsd_milestone_status` to inspect current milestone state, then `gsd_reassess_roadmap` to persist the roadmap reassessment.",
     "run-uat": "Use `gsd_uat_exec` for acceptance checks so evidence is typed as UAT-owned, and `gsd_resume` after compaction or resume.",
+    "research-project": "Dispatch parallel scout subagents for stack, features, architecture, and pitfalls research; each writes one file under `.gsd/research/` (`STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`).",
+    "gate-evaluate": "Use `subagent` to dispatch tester agents, then persist each gate with `gsd_save_gate_result`; rely on testers for verification evidence.",
+};
+// Per-unit guidance for the nested render mode (renderMode: "nested"), used when this
+// unit's Context Mode line is embedded into a subagent prompt — e.g. the tester prompts
+// dispatched by gate-evaluate. Must instruct the subagent on what IT should do, not
+// re-state the parent coordinator's dispatch instructions. Falls back to
+// CONTEXT_MODE_GUIDANCE_BY_UNIT then the lane default when no nested entry exists.
+export const CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT = {
+    "gate-evaluate": "Run verification checks to answer the gate question, then persist the verdict with `gsd_save_gate_result`.",
 };
 /**
  * Render the Context Mode instruction lane for a unit type. Unknown unit
@@ -112,7 +126,9 @@ export function composeContextModeInstructions(unitType, opts) {
     if (!manifest || manifest.contextMode === "none")
         return "";
     const lane = CONTEXT_MODE_LANE_LABELS[manifest.contextMode];
-    const guidance = CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType] ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
+    const guidance = (opts.renderMode === "nested" ? CONTEXT_MODE_NESTED_GUIDANCE_BY_UNIT[unitType] : undefined)
+        ?? CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType]
+        ?? CONTEXT_MODE_GUIDANCE_BY_LANE[manifest.contextMode];
     if (opts.renderMode === "nested") {
         return `Context Mode (${lane} lane): ${guidance}`;
     }

package/dist/resources/extensions/gsd/unit-registry.js

@@ -51,7 +51,13 @@ export const UNIT_REGISTRY = {
         scopeClass: "standard",
         phaseChain: ["research"],
         toolContract: {
-            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            allowedGsdTools: [
+                "gsd_summary_save",
+                "gsd_decision_save",
+                "gsd_exec",
+                "gsd_exec_search",
+                "gsd_resume",
+            ],
             requiredWorkflowTools: ["gsd_summary_save"],
         },
     },
@@ -107,7 +113,15 @@ export const UNIT_REGISTRY = {
         scopeClass: "section-close",
         phaseChain: ["validation", "planning"],
         toolContract: {
-            allowedGsdTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap", "subagent"],
+            allowedGsdTools: [
+                "gsd_milestone_status",
+                "gsd_exec",
+                "gsd_exec_search",
+                "gsd_resume",
+                "gsd_validate_milestone",
+                "gsd_reassess_roadmap",
+                "subagent",
+            ],
             requiredWorkflowTools: ["gsd_milestone_status", "gsd_validate_milestone", "gsd_reassess_roadmap"],
         },
     },
@@ -118,6 +132,9 @@ export const UNIT_REGISTRY = {
         toolContract: {
             allowedGsdTools: [
                 "gsd_milestone_status",
+                "gsd_exec",
+                "gsd_exec_search",
+                "gsd_resume",
                 "gsd_requirement_update",
                 "gsd_summary_save",
                 "gsd_complete_milestone",
@@ -197,6 +214,8 @@ export const UNIT_REGISTRY = {
             allowedGsdTools: [
                 "gsd_milestone_status",
                 "gsd_exec",
+                "gsd_exec_search",
+                "gsd_resume",
                 "gsd_slice_complete",
                 "gsd_task_reopen",
                 "gsd_replan_slice",
@@ -279,7 +298,13 @@ export const UNIT_REGISTRY = {
         scopeClass: "execute-task",
         phaseChain: ["execution"],
         toolContract: {
-            allowedGsdTools: ["gsd_task_complete", "gsd_summary_save", "gsd_decision_save"],
+            allowedGsdTools: [
+                "gsd_milestone_status",
+                "gsd_task_complete",
+                "gsd_exec",
+                "gsd_summary_save",
+                "gsd_decision_save",
+            ],
             requiredWorkflowTools: ["gsd_task_complete", "gsd_summary_save"],
         },
     },
@@ -366,12 +391,15 @@ export const UNIT_REGISTRY = {
             requiredWorkflowTools: ["ask_user_questions"],
         },
     },
+    // research-project dispatches 4 parallel scout subagents (Task calls); each scout
+    // writes one file under .gsd/research/ directly. The parent coordinator does not
+    // call gsd_summary_save or gsd_decision_save — the scouts own their own output.
     "research-project": {
         kind: "primary",
         scopeClass: "standard",
         phaseChain: ["research"],
         toolContract: {
-            allowedGsdTools: ["gsd_summary_save", "gsd_decision_save"],
+            allowedGsdTools: [],
             requiredWorkflowTools: [],
         },
     },

package/dist/resources/extensions/gsd/unmerged-milestone-guard.js

@@ -1,12 +1,12 @@
 // Project/App: gsd-pi
 // File Purpose: Block new workflow entry when completed milestone branches are still unmerged.
+import { execFileSync } from "node:child_process";
 import { nativeBranchExists, nativeDetectMainBranch, nativeDiffNumstat, nativeIsAncestor, } from "./native-git-bridge.js";
 import { autoWorktreeBranch } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { getAllMilestones } from "./gsd-db.js";
 import { resolveMilestoneIntegrationBranch } from "./git-service.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { captureRootDirtySnapshot } from "./root-write-leak-guard.js";
 import { isClosedStatus } from "./status-guards.js";
 const BLOCKED_COMMANDS = new Set([
     "auto",
@@ -49,6 +49,33 @@ const UNMERGED_SAFE_PARALLEL_SUBCOMMANDS = new Set([
 function isRuntimePath(path) {
     return path === ".gsd" || path.startsWith(".gsd/");
 }
+function captureDirtyPathStatusSnapshot(rootPath) {
+    const snapshot = new Map();
+    let status = "";
+    try {
+        status = execFileSync("git", ["status", "--porcelain", "--untracked-files=all"], {
+            cwd: rootPath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+    }
+    catch {
+        return snapshot;
+    }
+    for (const line of status.split("\n")) {
+        if (!line.trim())
+            continue;
+        const code = line.slice(0, 2);
+        const path = line.slice(3).replace(/^"|"$/g, "");
+        if (!path || isRuntimePath(path))
+            continue;
+        snapshot.set(path, {
+            path,
+            status: code.trim() || code,
+        });
+    }
+    return snapshot;
+}
 function formatCommandLabel(attemptedCommand) {
     const trimmed = attemptedCommand.trim();
     return trimmed ? `/gsd ${trimmed}` : "/gsd";
@@ -109,7 +136,7 @@ export function isUnmergedMilestoneAllowedCommand(trimmed) {
 export async function findUnmergedCompletedMilestones(base) {
     await ensureDbOpen(base);
     const blockers = [];
-    const dirtyByPath = captureRootDirtySnapshot(base);
+    let dirtyByPath = null;
     for (const milestone of getAllMilestones()) {
         if (!isClosedStatus(milestone.status))
             continue;
@@ -134,13 +161,16 @@ export async function findUnmergedCompletedMilestones(base) {
         const uniqueFiles = [...new Set(files)].sort();
         if (uniqueFiles.length === 0)
             continue;
+        if (!dirtyByPath)
+            dirtyByPath = captureDirtyPathStatusSnapshot(base);
+        const dirtySnapshot = dirtyByPath;
         blockers.push({
             milestoneId: milestone.id,
             branch,
             integrationBranch,
             files: uniqueFiles,
             dirtyOverlap: uniqueFiles
-                .map((path) => dirtyByPath.get(path))
+                .map((path) => dirtySnapshot.get(path))
                 .filter((entry) => Boolean(entry)),
         });
     }

package/dist/resources/extensions/gsd/validation-block-guard.js

@@ -5,7 +5,7 @@ import { getAutoWorktreePath, isInAutoWorktree } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
 import { refreshWorkflowDatabaseFromDisk } from "./db-workspace.js";
 import { getIsolationMode } from "./preferences.js";
-import { deriveState } from "./state.js";
+import { deriveState, invalidateStateCache } from "./state.js";
 import { detectWorktreeName } from "./worktree.js";
 const VALIDATION_BLOCK_RE = /milestone validation returned needs-(?:attention|remediation)|validation verdict is needs-(?:attention|remediation)/i;
 const VALIDATION_SAFE_DISPATCH_COMMANDS = new Set([
@@ -116,9 +116,7 @@ export function formatValidationBlockedMessage(state, attemptedCommand = "") {
         ...blockers,
     ].join("\n\n");
 }
-export async function getValidationBlockMessageForBase(base, attemptedCommand = "") {
-    await ensureDbOpen(base);
-    refreshWorkflowDatabaseFromDisk();
+async function deriveValidationBlockState(base) {
     let state = await deriveState(base);
     if (state.activeMilestone &&
         getIsolationMode(base) === "worktree" &&
@@ -129,5 +127,12 @@ export async function getValidationBlockMessageForBase(base, attemptedCommand =
             state = await deriveState(wtPath);
         }
     }
+    return state;
+}
+export async function getValidationBlockMessageForBase(base, attemptedCommand = "") {
+    await ensureDbOpen(base);
+    refreshWorkflowDatabaseFromDisk();
+    invalidateStateCache();
+    const state = await deriveValidationBlockState(base);
     return formatValidationBlockedMessage(state, attemptedCommand);
 }

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

@@ -399,15 +399,13 @@ export async function renderStateProjection(basePath) {
         logWarning("projection", `renderStateProjection failed: ${err.message}`);
     }
 }
-// ─── renderAllProjections ───────────────────────────────────────────────
+// ─── renderMilestoneShellProjections ─────────────────────────────────────
 /**
- * Regenerate all projection files for a milestone from DB state.
- * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
+ * Regenerate milestone-level projections (roadmap, top-level views, STATE.md).
+ * Does not touch slice PLAN.md or task SUMMARY.md — those have authoritative
+ * renderers in plan-slice / complete-task.
  */
-export async function renderAllProjections(basePath, milestoneId) {
-    // Delegate to the authoritative roadmap renderer — the reduced
-    // renderRoadmapProjection omits sections like ## Boundary Map and would
-    // clobber the output written by plan-milestone / reassess-roadmap.
+export async function renderMilestoneShellProjections(basePath, milestoneId) {
     try {
         await renderRoadmapFromDb(basePath, milestoneId);
     }
@@ -426,6 +424,20 @@ export async function renderAllProjections(basePath, milestoneId) {
     catch (err) {
         logWarning("projection", `renderTopLevelQueueFromDb failed: ${err.message}`);
     }
+    try {
+        await renderStateProjection(basePath);
+    }
+    catch (err) {
+        logWarning("projection", `renderStateProjection failed: ${err.message}`);
+    }
+}
+// ─── renderAllProjections ───────────────────────────────────────────────
+/**
+ * Regenerate all projection files for a milestone from DB state.
+ * All calls are wrapped in try/catch — projection failure is non-fatal per D-02.
+ */
+export async function renderAllProjections(basePath, milestoneId) {
+    await renderMilestoneShellProjections(basePath, milestoneId);
     // Query all slices for this milestone
     const sliceRows = getMilestoneSlices(milestoneId);
     for (const slice of sliceRows) {
@@ -445,13 +457,6 @@ export async function renderAllProjections(basePath, milestoneId) {
             }
         }
     }
-    // Render STATE.md
-    try {
-        await renderStateProjection(basePath);
-    }
-    catch (err) {
-        logWarning("projection", `renderStateProjection failed: ${err.message}`);
-    }
 }
 // ─── regenerateIfMissing ────────────────────────────────────────────────
 /**

package/dist/resources/extensions/gsd/workspace-git-preflight.js

@@ -4,9 +4,11 @@ import { existsSync, realpathSync } from "node:fs";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { isSafeToAutoResolve } from "./auto-worktree.js";
 import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
-import { probeGitConflictState, reconcileGitConflictsOnSignal, } from "./git-conflict-state.js";
+import { listMergeStateBlockers, probeGitConflictState, reconcileGitConflictsOnSignal, } from "./git-conflict-state.js";
 import { deriveState } from "./state.js";
 import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+const CLEAN_TARGET_CACHE_TTL_MS = 10_000;
+const cleanTargetProbeCache = new Map();
 function normalizeTargetPath(path) {
     try {
         return realpathSync(path);
@@ -77,6 +79,25 @@ function formatBlockReason(severity, conflictedPaths, targets) {
 }
 async function ensureTargetGitReady(target) {
     const fixesApplied = [];
+    const cacheKey = normalizeTargetPath(target);
+    const cachedCleanAt = cleanTargetProbeCache.get(cacheKey);
+    if (cachedCleanAt !== undefined) {
+        if (Date.now() - cachedCleanAt < CLEAN_TARGET_CACHE_TTL_MS) {
+            // Merge-state markers (MERGE_HEAD, rebase-apply, rebase-merge) are the most
+            // common way a repo transitions from clean to dirty within the TTL window,
+            // including when a non-git folder is initialized as a repo mid-TTL and a
+            // merge immediately introduces conflicts. Check them here — they are pure
+            // existsSync calls with no git subprocess — and fall through to a full probe
+            // only when markers are present.
+            if (listMergeStateBlockers(cacheKey).length === 0) {
+                return { ok: true, fixesApplied };
+            }
+            cleanTargetProbeCache.delete(cacheKey);
+        }
+        else {
+            cleanTargetProbeCache.delete(cacheKey);
+        }
+    }
     let probe = probeGitConflictState(target);
     for (let attempt = 0; attempt < 3 && probe.status === "dirty"; attempt++) {
         const beforeKey = JSON.stringify({
@@ -95,6 +116,7 @@ async function ensureTargetGitReady(target) {
             break;
     }
     if (probe.status === "unknown") {
+        cleanTargetProbeCache.delete(cacheKey);
         return {
             ok: false,
             reason: formatBlockReason("unrecoverable", [], [target]),
@@ -106,6 +128,7 @@ async function ensureTargetGitReady(target) {
     }
     const conflictedPaths = productConflictPaths(probe);
     if (conflictedPaths.length > 0 || probe.checkFailures.length > 0) {
+        cleanTargetProbeCache.delete(cacheKey);
         return {
             ok: false,
             reason: formatBlockReason("product-conflicts", conflictedPaths, [target]),
@@ -115,6 +138,12 @@ async function ensureTargetGitReady(target) {
             targets: [target],
         };
     }
+    if (probe.status === "clean") {
+        cleanTargetProbeCache.set(cacheKey, Date.now());
+    }
+    else {
+        cleanTargetProbeCache.delete(cacheKey);
+    }
     return { ok: true, fixesApplied };
 }
 /** Probe and heal a single git root (tests and headless paths). */

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

@@ -17,12 +17,12 @@
  *   3. merge()   — LLM-guided reconciliation of .gsd/ artifacts back to main
  *   4. remove()  — git worktree remove + branch cleanup
  */
-import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, unlinkSync } 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 { nativeBranchList, nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeIsAncestor, nativeLogOneline, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
+import { nativeBranchList, nativeBranchDelete, nativeBranchExists, nativeBranchForceReset, nativeCommit, nativeDetectMainBranch, nativeDiffContent, nativeDiffNameStatus, nativeDiffNumstat, nativeGetCurrentBranch, nativeIsAncestor, nativeLogOneline, nativeMergeAbort, nativeMergeSquash, nativeWorktreeAdd, nativeWorktreeList, nativeWorktreePrune, nativeWorktreeRemove, } from "./native-git-bridge.js";
 import { emitCanonicalRootRedirect } from "./worktree-telemetry.js";
 import { isGsdWorktreePath, normalizeWorktreePathForCompare, resolveWorktreeProjectRoot, } from "./worktree-root.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
@@ -37,6 +37,36 @@ function deleteBranchIfPresent(basePath, branch, warningPrefix) {
         logWarning("worktree", `${warningPrefix}: ${e.message}`);
     }
 }
+function cleanupFailedSquashMergeState(basePath) {
+    try {
+        nativeMergeAbort(basePath);
+    }
+    catch (e) {
+        // Squash conflicts may not create MERGE_HEAD; this is expected.
+        logWarning("worktree", `merge abort skipped: ${e.message}`);
+    }
+    try {
+        execFileSync("git", ["reset", "--merge"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        });
+    }
+    catch (e) {
+        logWarning("worktree", `failed squash merge reset failed: ${e.message}`);
+    }
+    const gitDir = resolveGitDir(basePath);
+    for (const marker of ["SQUASH_MSG", "MERGE_MSG", "MERGE_MODE", "MERGE_HEAD", "AUTO_MERGE"]) {
+        try {
+            const markerPath = join(gitDir, marker);
+            if (existsSync(markerPath))
+                unlinkSync(markerPath);
+        }
+        catch (e) {
+            logWarning("worktree", `failed squash merge marker cleanup failed (${marker}): ${e.message}`);
+        }
+    }
+}
 // ─── Path Helpers ──────────────────────────────────────────────────────────
 function normalizePathForComparison(path) {
     const normalized = path
@@ -903,6 +933,18 @@ export function mergeWorktreeToMain(basePath, name, commitMessage, branchOverrid
     }
     const result = nativeMergeSquash(basePath, branch);
     if (!result.success) {
+        const dirtyWorkingTree = result.conflicts.includes("__dirty_working_tree__");
+        if (!dirtyWorkingTree) {
+            cleanupFailedSquashMergeState(basePath);
+        }
+        if (!dirtyWorkingTree && branch.startsWith("milestone/")) {
+            try {
+                removeWorktree(basePath, name, { branch, deleteBranch: true, force: true });
+            }
+            catch (e) {
+                logWarning("worktree", `failed milestone branch cleanup after squash merge failure: ${e.message}`);
+            }
+        }
         throw new GSDError(GSD_MERGE_CONFLICT, `Merge conflicts detected in: ${result.conflicts.join(", ")}`);
     }
     nativeCommit(basePath, commitMessage);