gsd-pi 2.81.0-dev.3cddbbba2 → 2.81.0-dev.72a81bdf3

package/src/resources/extensions/gsd/auto-recovery.ts

@@ -7,7 +7,6 @@
  * globals or AutoContext dependency.
  */
 
-import type { ExtensionContext } from "@gsd/pi-coding-agent";
 import { parseUnitId } from "./unit-id.js";
 import { MILESTONE_ID_RE } from "./milestone-ids.js";
 import { appendEvent } from "./workflow-events.js";
@@ -20,15 +19,6 @@ import { getErrorMessage } from "./error-utils.js";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readIntegrationBranch } from "./git-service.js";
 import { isClosedStatus } from "./status-guards.js";
-import {
-  nativeConflictFiles,
-  nativeCommit,
-  nativeCheckoutTheirs,
-  nativeAddPaths,
-  nativeMergeAbort,
-  nativeRebaseAbort,
-  nativeResetHard,
-} from "./native-git-bridge.js";
 import {
   resolveSlicePath,
   resolveSliceFile,
@@ -46,7 +36,6 @@ import {
   mkdirSync,
   readFileSync,
   writeFileSync,
-  unlinkSync,
 } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { dirname, join } from "node:path";
@@ -1001,205 +990,14 @@ export function writeBlockerPlaceholder(
 }
 
 // ─── Merge State Reconciliation ───────────────────────────────────────────────
+// Body relocated to state-reconciliation/drift/merge-state.ts (ADR-017 #5701).
+// Re-exported here for backward compatibility with existing call sites:
+// auto.ts, auto/loop-deps.ts, tests/integration/auto-recovery.test.ts.
 
-/**
- * Best-effort abort of a pending merge/squash and hard-reset to HEAD.
- * Handles both real merges (MERGE_HEAD) and squash merges (SQUASH_MSG).
- */
-function abortAndResetMerge(
-  basePath: string,
-  hasMergeHead: boolean,
-  squashMsgPath: string,
-): void {
-  if (hasMergeHead) {
-    try {
-      nativeMergeAbort(basePath);
-    } catch (err) {
-      /* best-effort */
-      logWarning("recovery", `git merge-abort failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  } else if (squashMsgPath) {
-    try {
-      unlinkSync(squashMsgPath);
-    } catch (err) {
-      /* best-effort */
-      logWarning("recovery", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`);
-    }
-  }
-  try {
-    nativeResetHard(basePath);
-  } catch (err) {
-    /* best-effort */
-    logError("recovery", `git reset failed: ${err instanceof Error ? err.message : String(err)}`);
-  }
-}
-
-export type MergeReconcileResult = "clean" | "reconciled" | "blocked";
-
-/**
- * Detect and abort other in-progress git operations left behind by a SIGKILL'd
- * worker (rebase, cherry-pick, revert). Without this, a killed worker mid-rebase
- * leaves `.git/rebase-merge/` or `.git/CHERRY_PICK_HEAD` and the worktree is
- * wedged until the user manually runs the matching `--abort`.
- *
- * Called before merge-state reconciliation because these states block any
- * subsequent merge/commit operation. (Issue #4980 HIGH-7)
- */
-function reconcileOtherInProgressGitOps(
-  basePath: string,
-  ctx: ExtensionContext,
-): "clean" | "reconciled" | "blocked" {
-  const gitDir = join(basePath, ".git");
-  const states: Array<{
-    label: string;
-    indicators: string[];
-    abort: () => void;
-  }> = [
-    {
-      label: "rebase",
-      indicators: [join(gitDir, "rebase-merge"), join(gitDir, "rebase-apply")],
-      abort: () => nativeRebaseAbort(basePath),
-    },
-    {
-      label: "cherry-pick",
-      indicators: [join(gitDir, "CHERRY_PICK_HEAD")],
-      abort: () => {
-        // No native helper; fall back to git CLI.
-        try {
-          execFileSync("git", ["cherry-pick", "--abort"], {
-            cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8",
-          });
-        } catch (err) { logWarning("recovery", `cherry-pick --abort failed: ${getErrorMessage(err)}`); }
-      },
-    },
-    {
-      label: "revert",
-      indicators: [join(gitDir, "REVERT_HEAD")],
-      abort: () => {
-        try {
-          execFileSync("git", ["revert", "--abort"], {
-            cwd: basePath, stdio: ["ignore", "pipe", "pipe"], encoding: "utf-8",
-          });
-        } catch (err) { logWarning("recovery", `revert --abort failed: ${getErrorMessage(err)}`); }
-      },
-    },
-  ];
-
-  let reconciled = false;
-  for (const s of states) {
-    const present = s.indicators.some((p) => existsSync(p));
-    if (!present) continue;
-    try {
-      s.abort();
-      ctx.ui.notify(
-        `Detected leftover ${s.label} state from prior session — aborted.`,
-        "warning",
-      );
-      reconciled = true;
-    } catch (err) {
-      logError("recovery", `${s.label} abort failed: ${getErrorMessage(err)}`);
-      ctx.ui.notify(
-        `Detected leftover ${s.label} state but auto-abort failed. ` +
-        `Run \`git ${s.label} --abort\` manually before retrying.`,
-        "error",
-      );
-      return "blocked";
-    }
-  }
-  return reconciled ? "reconciled" : "clean";
-}
-
-/**
- * Detect leftover merge state from a prior session and reconcile it.
- * If MERGE_HEAD or SQUASH_MSG exists, check whether conflicts are resolved.
- * If resolved: finalize the commit. If only .gsd conflicts remain: auto-resolve.
- * If code conflicts remain: fail safe without modifying the worktree.
- */
-export function reconcileMergeState(
-  basePath: string,
-  ctx: ExtensionContext,
-): MergeReconcileResult {
-  // First, abort any rebase/cherry-pick/revert left over from a SIGKILL'd
-  // worker. Doing this before the merge-state check unblocks any merge that
-  // would otherwise refuse with "you have unfinished operation". (HIGH-7)
-  const otherOpsResult = reconcileOtherInProgressGitOps(basePath, ctx);
-  if (otherOpsResult === "blocked") return "blocked";
-
-  const mergeHeadPath = join(basePath, ".git", "MERGE_HEAD");
-  const squashMsgPath = join(basePath, ".git", "SQUASH_MSG");
-  const hasMergeHead = existsSync(mergeHeadPath);
-  const hasSquashMsg = existsSync(squashMsgPath);
-  if (!hasMergeHead && !hasSquashMsg) {
-    // If we cleaned up another op type, return "reconciled" so the caller
-    // re-derives state from a known-good baseline.
-    return otherOpsResult === "reconciled" ? "reconciled" : "clean";
-  }
-
-  const conflictedFiles = nativeConflictFiles(basePath);
-  if (conflictedFiles.length === 0) {
-    // All conflicts resolved — finalize the merge/squash commit
-    try {
-      const commitSha = nativeCommit(basePath, "chore(gsd): reconcile merge state");
-      if (commitSha) {
-        const mode = hasMergeHead ? "merge" : "squash commit";
-        ctx.ui.notify(`Finalized leftover ${mode} from prior session.`, "info");
-      } else {
-        ctx.ui.notify("No new commit needed for leftover merge/squash state — already committed.", "info");
-      }
-    } catch (err) {
-      const errorMessage = getErrorMessage(err);
-      ctx.ui.notify(`Failed to finalize leftover merge/squash commit: ${errorMessage}`, "error");
-      return "blocked";
-    }
-  } else {
-    // Still conflicted — try auto-resolving .gsd/ state file conflicts (#530)
-    const gsdConflicts = conflictedFiles.filter((f) => f.startsWith(".gsd/"));
-    const codeConflicts = conflictedFiles.filter((f) => !f.startsWith(".gsd/"));
-
-    if (gsdConflicts.length > 0 && codeConflicts.length === 0) {
-      // All conflicts are in .gsd/ state files — auto-resolve by accepting theirs
-      let resolved = true;
-      try {
-        nativeCheckoutTheirs(basePath, gsdConflicts);
-        nativeAddPaths(basePath, gsdConflicts);
-      } catch (e) {
-        logError("recovery", `auto-resolve .gsd/ conflicts failed: ${(e as Error).message}`);
-        resolved = false;
-      }
-      if (resolved) {
-        try {
-          nativeCommit(
-            basePath,
-            "chore: auto-resolve .gsd/ state file conflicts",
-          );
-          ctx.ui.notify(
-            `Auto-resolved ${gsdConflicts.length} .gsd/ state file conflict(s) from prior merge.`,
-            "info",
-          );
-        } catch (e) {
-          logError("recovery", `auto-commit .gsd/ conflict resolution failed: ${(e as Error).message}`);
-          resolved = false;
-        }
-      }
-      if (!resolved) {
-        abortAndResetMerge(basePath, hasMergeHead, squashMsgPath);
-        ctx.ui.notify(
-          "Detected leftover merge state — auto-resolve failed, cleaned up. Re-deriving state.",
-          "warning",
-        );
-      }
-    } else {
-      // Code conflicts present — fail safe and preserve any manual resolution
-      // work instead of discarding it with merge --abort/reset --hard.
-      ctx.ui.notify(
-        "Detected leftover merge state with unresolved code conflicts. Auto-mode will pause without modifying the worktree so manual conflict resolution is preserved.",
-        "error",
-      );
-      return "blocked";
-    }
-  }
-  return "reconciled";
-}
+export {
+  reconcileMergeState,
+  type MergeReconcileResult,
+} from "./state-reconciliation/drift/merge-state.js";
 
 // ─── Loop Remediation ─────────────────────────────────────────────────────────
 

package/src/resources/extensions/gsd/auto.ts

@@ -1812,16 +1812,20 @@ export function createWiredAutoOrchestrationModule(
     stateReconciliation: {
       async reconcileBeforeDispatch() {
         const result = await reconcileBeforeDispatch(dispatchBasePath);
-        if (!result.ok) {
+        if (result.blockers.length > 0) {
           return {
             ok: false,
-            reason: result.reason,
+            reason: result.blockers[0],
             stateSnapshot: result.stateSnapshot,
           };
         }
+        const repairedKinds = result.repaired.map((d) => d.kind);
         return {
           ok: true,
-          reason: result.repaired.join(", "),
+          reason:
+            repairedKinds.length > 0
+              ? `repaired: ${repairedKinds.join(", ")}`
+              : "clean",
           stateSnapshot: result.stateSnapshot,
         };
       },

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -153,8 +153,7 @@ export function isBareClaudeCodeStreamAbortPlaceholder(lastMsg: unknown): boolea
  * Claude Code abort markers are intentionally ignored when the abort fires
  * while the session-switch is in flight: the abort is the expected side-effect
  * of the transition, not a user signal. Other branches (genuine `stopReason
- * === "aborted"` with diagnostic content/errorMessage) preserve the prior
- * behavior.
+ * === "aborted"` with explicit errorMessage) preserve the prior behavior.
  */
 export function _handleSessionSwitchAgentEnd(
   lastMsg: unknown,
@@ -178,10 +177,8 @@ export function _handleSessionSwitchAgentEnd(
   }
 
   if (m.stopReason === "aborted") {
-    const content = m.content;
-    const hasEmptyContent = Array.isArray(content) && content.length === 0;
     const hasErrorMessage = !!m.errorMessage;
-    if (!hasEmptyContent || hasErrorMessage) {
+    if (hasErrorMessage) {
       resolveCancelled(_buildAbortedPauseContext(m as { errorMessage?: unknown }));
     }
   }

package/src/resources/extensions/gsd/commands/handlers/parallel.ts

@@ -14,6 +14,7 @@ import {
 import { formatEligibilityReport } from "../../parallel-eligibility.js";
 import { formatMergeResults, mergeAllCompleted, mergeCompletedMilestone } from "../../parallel-merge.js";
 import { loadEffectiveGSDPreferences, resolveParallelConfig } from "../../preferences.js";
+import { reconcileBeforeSpawn } from "../../state-reconciliation.js";
 import { projectRoot } from "../context.js";
 function emitParallelMessage(pi: ExtensionAPI, content: string): void {
   pi.sendMessage({ customType: "gsd-parallel", content, display: true });
@@ -40,6 +41,17 @@ export async function handleParallelCommand(trimmed: string, _ctx: ExtensionComm
       emitParallelMessage(pi, `${report}\n\nNo milestones are eligible for parallel execution.`);
       return true;
     }
+    // ADR-017 #5707: reconcile before spawning so workers don't independently
+    // race on the same drift. Failures abort the spawn with an actionable
+    // user-visible message.
+    const gate = await reconcileBeforeSpawn(root);
+    if (!gate.ok) {
+      emitParallelMessage(
+        pi,
+        `${report}\n\nParallel orchestration aborted before spawn — ${gate.reason}`,
+      );
+      return true;
+    }
     const result = await startParallel(
       root,
       candidates.eligible.map((candidate) => candidate.milestoneId),

package/src/resources/extensions/gsd/gsd-db.ts

@@ -1136,33 +1136,17 @@ export function setSliceSketchFlag(milestoneId: string, sliceId: string, isSketc
 }
 
 /**
- * ADR-011 auto-heal: reconcile stale is_sketch=1 rows whose PLAN already exists.
- *
- * Callers pass a predicate that resolves whether a plan file exists for a slice.
- * The predicate MUST use the canonical path resolver (`resolveSliceFile`, etc.)
- * to keep path logic in one place — do not hand-roll the path inside the callback.
- *
- * Recovers from two scenarios:
- *   1. Crash between `gsd_plan_slice` write and the sketch flag flip.
- *   2. Flag-OFF downgrade path: when `progressive_planning` is off, the dispatch
- *      rule routes sketch slices to plan-slice, which writes PLAN.md but leaves
- *      `is_sketch=1` — the next state derivation auto-heals it to 0 here.
- *
- * Not aggressive in practice: PLAN.md is only written via the DB-backed
- * `gsd_plan_slice` tool (which also inserts tasks), so a "stale PLAN.md with
- * is_sketch=1" is extremely unlikely to indicate anything other than the two
- * recovery scenarios above.
+ * ADR-017 raw primitive: returns slice IDs in a milestone whose is_sketch flag
+ * is still 1. The stale-sketch-flag drift handler at
+ * `state-reconciliation/drift/sketch-flag.ts` composes this with PLAN.md
+ * existence checks to detect drift, then writes via `setSliceSketchFlag`.
  */
-export function autoHealSketchFlags(milestoneId: string, hasPlanFile: (sliceId: string) => boolean): void {
-  if (!currentDb) return;
+export function getSketchedSliceIds(milestoneId: string): string[] {
+  if (!currentDb) return [];
   const rows = currentDb.prepare(
     `SELECT id FROM slices WHERE milestone_id = :mid AND is_sketch = 1`,
   ).all({ ":mid": milestoneId }) as Array<{ id: string }>;
-  for (const row of rows) {
-    if (hasPlanFile(row.id)) {
-      setSliceSketchFlag(milestoneId, row.id, false);
-    }
-  }
+  return rows.map((r) => r.id);
 }
 
 export function upsertSlicePlanning(milestoneId: string, sliceId: string, planning: Partial<SlicePlanningRecord>): void {

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -920,101 +920,10 @@ export function detectStaleRenders(basePath: string): StaleEntry[] {
 }
 
 // ─── Stale Repair ─────────────────────────────────────────────────────────
-
-/**
- * Repair all stale renders detected by `detectStaleRenders()`.
- *
- * For each stale entry, calls the appropriate render function:
- * - Roadmap checkbox mismatches → renderRoadmapCheckboxes()
- * - Plan checkbox mismatches → renderPlanCheckboxes()
- * - Missing task summaries → renderTaskSummary()
- * - Missing slice summaries/UATs → renderSliceSummary()
- *
- * Idempotent: calling twice with no DB changes produces zero repairs on the second call.
- *
- * @returns the number of files repaired
- */
-export async function repairStaleRenders(basePath: string): Promise<number> {
-  const staleEntries = detectStaleRenders(basePath);
-  if (staleEntries.length === 0) return 0;
-
-  // Deduplicate: a single roadmap/plan file might appear multiple times
-  // (once per mismatched checkbox). We only need to re-render it once.
-  const repairedPaths = new Set<string>();
-  let repairCount = 0;
-
-  for (const entry of staleEntries) {
-    if (repairedPaths.has(entry.path)) continue;
-    // Normalize path separators for cross-platform regex matching
-    const normPath = entry.path.replace(/\\/g, "/");
-
-    try {
-      // Determine repair action from the reason
-      if (entry.reason.includes("in roadmap")) {
-        // Roadmap checkbox mismatch — extract milestone ID from path
-        const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
-        if (milestoneMatch) {
-          const ok = await renderRoadmapCheckboxes(basePath, milestoneMatch[1]);
-          if (ok) {
-            repairedPaths.add(entry.path);
-            repairCount++;
-          }
-        }
-      } else if (entry.reason.includes("in plan")) {
-        // Plan checkbox mismatch — extract milestone + slice IDs from path
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
-        if (pathMatch) {
-          const ok = await renderPlanCheckboxes(basePath, pathMatch[1], pathMatch[2]);
-          if (ok) {
-            repairedPaths.add(entry.path);
-            repairCount++;
-          }
-        }
-      } else if (entry.reason.includes("SUMMARY.md missing") && entry.reason.match(/^T\d+/)) {
-        // Missing task summary — extract IDs from path
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//);
-        const taskMatch = entry.reason.match(/^(T\d+)/);
-        if (pathMatch && taskMatch) {
-          const ok = await renderTaskSummary(basePath, pathMatch[1], pathMatch[2], taskMatch[1]);
-          if (ok) {
-            repairedPaths.add(entry.path);
-            repairCount++;
-          }
-        }
-      } else if (entry.reason.includes("SUMMARY.md missing") && entry.reason.match(/^S\d+/)) {
-        // Missing slice summary — extract IDs from path
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
-        if (pathMatch) {
-          const ok = await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
-          if (ok) {
-            repairedPaths.add(entry.path);
-            repairCount++;
-          }
-        }
-      } else if (entry.reason.includes("UAT.md missing")) {
-        // Missing slice UAT — renderSliceSummary handles both SUMMARY + UAT
-        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
-        if (pathMatch) {
-          const ok = await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
-          if (ok) {
-            repairedPaths.add(entry.path);
-            repairCount++;
-          }
-        }
-      }
-    } catch (err) {
-      logWarning("renderer", `repair failed for ${entry.path}: ${(err as Error).message}`);
-    }
-  }
-
-  if (repairCount > 0) {
-    process.stderr.write(
-      `markdown-renderer: repaired ${repairCount} stale render(s)\n`,
-    );
-  }
-
-  return repairCount;
-}
+// Body relocated to state-reconciliation/drift/stale-render.ts (ADR-017 #5702).
+// detectStaleRenders above stays as a useful diagnostic primitive; the
+// drift handler composes it with the per-reason renderer dispatch and the
+// reconcileBeforeDispatch lifecycle.
 
 // ─── Replan & Assessment Renderers ────────────────────────────────────────
 

package/src/resources/extensions/gsd/recovery-classification.ts

@@ -2,6 +2,7 @@
 // File Purpose: ADR-015 Recovery Classification module for runtime failure taxonomy.
 
 import { classifyError, isTransient, type ErrorClass } from "./error-classifier.js";
+import { ReconciliationFailedError } from "./state-reconciliation.js";
 
 export type RecoveryFailureKind =
   | "tool-schema"
@@ -9,6 +10,7 @@ export type RecoveryFailureKind =
   | "stale-worker"
   | "worktree-invalid"
   | "verification-drift"
+  | "reconciliation-drift"
   | "provider"
   | "runtime-unknown";
 
@@ -33,7 +35,13 @@ export interface RecoveryClassification {
 
 export function classifyFailure(input: RecoveryClassificationInput): RecoveryClassification {
   const message = errorMessage(input.error);
-  const failureKind = input.failureKind ?? inferFailureKind(message);
+  // ADR-017: ReconciliationFailedError is a typed throw from the State
+  // Reconciliation Module. Recognize it by class regardless of caller-supplied
+  // failureKind so the taxonomy stays consistent.
+  const failureKind =
+    input.error instanceof ReconciliationFailedError
+      ? "reconciliation-drift"
+      : input.failureKind ?? inferFailureKind(message);
 
   switch (failureKind) {
     case "tool-schema":
@@ -76,6 +84,15 @@ export function classifyFailure(input: RecoveryClassificationInput): RecoveryCla
         exitReason: "verification-drift",
         remediation: "Inspect the verification artifact and reconcile the state snapshot before resuming.",
       };
+    case "reconciliation-drift":
+      return {
+        failureKind,
+        action: "escalate",
+        reason: `Reconciliation drift${unitSuffix(input)}: ${message}`,
+        exitReason: "reconciliation-drift",
+        remediation:
+          "Inspect the persistent or repair-failed drift kinds reported by the State Reconciliation Module before resuming.",
+      };
     case "provider": {
       const providerClass = classifyError(message, input.retryAfterMs);
       return {

package/src/resources/extensions/gsd/session-lock.ts

@@ -597,6 +597,47 @@ export function isSessionLockProcessAlive(data: SessionLockData): boolean {
   return isPidAlive(data.pid);
 }
 
+/**
+ * ADR-017 raw primitive: remove orphaned lock artifacts (lock dir + lock file)
+ * when the recorded PID is dead or no metadata is present. Mirrors the
+ * pre-flight cleanup logic in acquireSessionLock so the stale-worker drift
+ * handler can clear the orphan proactively without going through the full
+ * acquire path. No-op when the lock is held by an alive process.
+ *
+ * Returns true when artifacts were removed (drift was present).
+ */
+export function removeStaleSessionLock(basePath: string): boolean {
+  const lp = lockPath(basePath);
+  const gsdDir = gsdRoot(basePath);
+  const lockTarget = effectiveLockTarget(gsdDir);
+  const lockDir = lockTarget + ".lock";
+
+  const existingData = readExistingLockData(lp);
+  const isOrphan =
+    !existingData ||
+    (typeof existingData.pid === "number" && !isPidAlive(existingData.pid));
+  if (!isOrphan) return false;
+
+  let removed = false;
+  if (existsSync(lockDir)) {
+    try {
+      rmSync(lockDir, { recursive: true, force: true });
+      removed = true;
+    } catch {
+      /* best-effort */
+    }
+  }
+  if (existsSync(lp)) {
+    try {
+      unlinkSync(lp);
+      removed = true;
+    } catch {
+      /* best-effort */
+    }
+  }
+  return removed;
+}
+
 /**
  * Returns true if we currently hold a session lock for the given path.
  */