gsd-pi 2.81.0 → 2.82.0

package/dist/resources/extensions/gsd/state-reconciliation/drift/merge-state.js

@@ -0,0 +1,247 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 unmerged-merge-state drift handler. Relocated from
+// auto-recovery.ts as part of issue #5701. Owns:
+//   - rebase/cherry-pick/revert leftover cleanup (#4980 HIGH-7)
+//   - MERGE_HEAD / SQUASH_MSG reconciliation with auto-resolve of .gsd/
+//     conflicts (#530, #2542)
+import { execFileSync } from "node:child_process";
+import { existsSync, unlinkSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { getErrorMessage } from "../../error-utils.js";
+import { nativeAddPaths, nativeCheckoutTheirs, nativeCommit, nativeConflictFiles, nativeMergeAbort, nativeRebaseAbort, nativeResetHard, } from "../../native-git-bridge.js";
+import { logError, logWarning } from "../../workflow-logger.js";
+const SILENT_NOTIFY = () => { };
+function resolveGitDir(basePath) {
+    try {
+        const gitDir = execFileSync("git", ["rev-parse", "--git-dir"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+        }).trim();
+        if (gitDir.length > 0) {
+            return isAbsolute(gitDir) ? gitDir : resolve(basePath, gitDir);
+        }
+    }
+    catch (err) {
+        logWarning("recovery", `gitdir resolution failed: ${getErrorMessage(err)}`);
+    }
+    return join(basePath, ".git");
+}
+/**
+ * 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, hasMergeHead, squashMsgPath) {
+    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)}`);
+    }
+}
+/**
+ * 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. (#4980 HIGH-7)
+ */
+function reconcileOtherInProgressGitOps(basePath, notify) {
+    const gitDir = resolveGitDir(basePath);
+    const states = [
+        {
+            label: "rebase",
+            indicators: [join(gitDir, "rebase-merge"), join(gitDir, "rebase-apply")],
+            abort: () => nativeRebaseAbort(basePath),
+        },
+        {
+            label: "cherry-pick",
+            indicators: [join(gitDir, "CHERRY_PICK_HEAD")],
+            abort: () => {
+                try {
+                    execFileSync("git", ["cherry-pick", "--abort"], {
+                        cwd: basePath,
+                        stdio: ["ignore", "pipe", "pipe"],
+                        encoding: "utf-8",
+                    });
+                }
+                catch (err) {
+                    throw new Error(`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) {
+                    throw new Error(`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();
+            notify(`Detected leftover ${s.label} state from prior session — aborted.`, "warning");
+            reconciled = true;
+        }
+        catch (err) {
+            logError("recovery", `${s.label} abort failed: ${getErrorMessage(err)}`);
+            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";
+}
+/**
+ * Core: detect leftover merge state and reconcile it. Takes a NotifyFn so the
+ * legacy reconcileMergeState(basePath, ctx) wrapper and the drift handler can
+ * both call it — the drift handler uses SILENT_NOTIFY.
+ */
+function reconcileMergeStateCore(basePath, notify) {
+    // 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, notify);
+    if (otherOpsResult === "blocked")
+        return "blocked";
+    const gitDir = resolveGitDir(basePath);
+    const mergeHeadPath = join(gitDir, "MERGE_HEAD");
+    const squashMsgPath = join(gitDir, "SQUASH_MSG");
+    const hasMergeHead = existsSync(mergeHeadPath);
+    const hasSquashMsg = existsSync(squashMsgPath);
+    if (!hasMergeHead && !hasSquashMsg) {
+        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";
+                notify(`Finalized leftover ${mode} from prior session.`, "info");
+            }
+            else {
+                notify("No new commit needed for leftover merge/squash state — already committed.", "info");
+            }
+        }
+        catch (err) {
+            const errorMessage = getErrorMessage(err);
+            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) {
+            let resolved = true;
+            try {
+                nativeCheckoutTheirs(basePath, gsdConflicts);
+                nativeAddPaths(basePath, gsdConflicts);
+            }
+            catch (e) {
+                logError("recovery", `auto-resolve .gsd/ conflicts failed: ${e.message}`);
+                resolved = false;
+            }
+            if (resolved) {
+                try {
+                    nativeCommit(basePath, "chore: auto-resolve .gsd/ state file conflicts");
+                    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.message}`);
+                    resolved = false;
+                }
+            }
+            if (!resolved) {
+                abortAndResetMerge(basePath, hasMergeHead, squashMsgPath);
+                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.
+            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";
+}
+/**
+ * Legacy entry point preserved for existing callers (auto.ts, auto/phases.ts
+ * via loop-deps, integration tests). New code prefers the drift handler.
+ */
+export function reconcileMergeState(basePath, ctx) {
+    return reconcileMergeStateCore(basePath, (message, severity) => ctx.ui.notify(message, severity));
+}
+function hasMergeStateLeftovers(basePath) {
+    const gitDir = resolveGitDir(basePath);
+    return (existsSync(join(gitDir, "MERGE_HEAD")) ||
+        existsSync(join(gitDir, "SQUASH_MSG")) ||
+        existsSync(join(gitDir, "rebase-merge")) ||
+        existsSync(join(gitDir, "rebase-apply")) ||
+        existsSync(join(gitDir, "CHERRY_PICK_HEAD")) ||
+        existsSync(join(gitDir, "REVERT_HEAD")));
+}
+export function detectMergeStateDrift(_state, ctx) {
+    if (hasMergeStateLeftovers(ctx.basePath)) {
+        return [{ kind: "unmerged-merge-state", basePath: ctx.basePath }];
+    }
+    return [];
+}
+/**
+ * Repair: invoke the reconciliation core with a silent notify. If the
+ * underlying reconciliation reports "blocked" (e.g., unresolved code
+ * conflicts present), throw so reconcileBeforeDispatch surfaces the drift
+ * via ReconciliationFailedError.
+ */
+export function repairMergeStateDrift(record) {
+    const result = reconcileMergeStateCore(record.basePath, SILENT_NOTIFY);
+    if (result === "blocked") {
+        throw new Error(`Merge state reconciliation blocked for ${record.basePath} — likely unresolved code conflicts. Manual intervention required.`);
+    }
+}
+export const mergeStateHandler = {
+    kind: "unmerged-merge-state",
+    detect: detectMergeStateDrift,
+    repair: (record) => {
+        repairMergeStateDrift(record);
+    },
+};

package/dist/resources/extensions/gsd/state-reconciliation/drift/project-md.js

@@ -0,0 +1,50 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 unregistered-milestone drift handler. Detects
+// milestones whose on-disk directory has meaningful content (ROADMAP/
+// CONTEXT/SUMMARY) but no DB row, then runs the markdown importer to
+// reconcile. PROJECT.md is the human-facing index — the importer's source
+// of truth is the .gsd/milestones/ directory tree.
+import { existsSync } from "node:fs";
+import { getMilestone, isDbAvailable } from "../../gsd-db.js";
+import { migrateHierarchyToDb } from "../../md-importer.js";
+import { findMilestoneIds } from "../../milestone-ids.js";
+import { resolveMilestoneFile } from "../../paths.js";
+function milestoneHasContent(basePath, milestoneId) {
+    const roadmap = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    const context = resolveMilestoneFile(basePath, milestoneId, "CONTEXT");
+    const summary = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
+    return ((roadmap !== null && existsSync(roadmap)) ||
+        (context !== null && existsSync(context)) ||
+        (summary !== null && existsSync(summary)));
+}
+export function detectUnregisteredMilestoneDrift(_state, ctx) {
+    if (!isDbAvailable())
+        return [];
+    const drifts = [];
+    for (const milestoneId of findMilestoneIds(ctx.basePath)) {
+        if (getMilestone(milestoneId))
+            continue;
+        if (!milestoneHasContent(ctx.basePath, milestoneId))
+            continue;
+        drifts.push({ kind: "unregistered-milestone", milestoneId });
+    }
+    return drifts;
+}
+/**
+ * Repair: invoke the markdown importer. migrateHierarchyToDb walks the same
+ * findMilestoneIds list the detector uses and INSERTs OR IGNOREs every
+ * missing milestone (and its slices/tasks) — idempotent under cap=2 retry.
+ *
+ * Note: even though we receive one record at a time, the importer is a
+ * project-wide operation. Repeated invocation across multiple drift records
+ * in the same pass is wasteful but safe; a future optimization could
+ * coalesce by checking whether the importer has already run this pass.
+ */
+export function repairUnregisteredMilestone(_record, ctx) {
+    migrateHierarchyToDb(ctx.basePath);
+}
+export const unregisteredMilestoneHandler = {
+    kind: "unregistered-milestone",
+    detect: detectUnregisteredMilestoneDrift,
+    repair: repairUnregisteredMilestone,
+};

package/dist/resources/extensions/gsd/state-reconciliation/drift/roadmap.js

@@ -0,0 +1,87 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 roadmap-divergence drift handler. Detects mismatches
+// between ROADMAP.md (parsed slice sequence + depends declarations) and the
+// DB slice rows for that milestone, then reconciles via the markdown
+// importer plus an explicit junction-table sync.
+import { existsSync, readFileSync } from "node:fs";
+import { getMilestone, getMilestoneSlices, isDbAvailable, syncSliceDependencies, } from "../../gsd-db.js";
+import { migrateHierarchyToDb } from "../../md-importer.js";
+import { findMilestoneIds } from "../../milestone-ids.js";
+import { parseRoadmap } from "../../parsers-legacy.js";
+import { resolveMilestoneFile } from "../../paths.js";
+function arraysEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+function milestoneHasDivergence(basePath, milestoneId) {
+    const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+    if (!roadmapPath || !existsSync(roadmapPath))
+        return false;
+    let roadmap;
+    try {
+        roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
+    }
+    catch {
+        return false;
+    }
+    const dbSlices = getMilestoneSlices(milestoneId);
+    const dbSliceMap = new Map(dbSlices.map((s) => [s.id, s]));
+    for (let i = 0; i < roadmap.slices.length; i++) {
+        const roadmapSlice = roadmap.slices[i];
+        const expectedSequence = i + 1;
+        const dbSlice = dbSliceMap.get(roadmapSlice.id);
+        if (!dbSlice)
+            return true; // Roadmap has a slice the DB doesn't.
+        if (dbSlice.sequence !== expectedSequence)
+            return true;
+        if (!arraysEqual(dbSlice.depends, roadmapSlice.depends))
+            return true;
+    }
+    return false;
+}
+export function detectRoadmapDivergenceDrift(_state, ctx) {
+    if (!isDbAvailable())
+        return [];
+    const drifts = [];
+    for (const milestoneId of findMilestoneIds(ctx.basePath)) {
+        // Skip milestones that don't yet have a DB row — that's the
+        // unregistered-milestone drift handler's responsibility.
+        if (!getMilestone(milestoneId))
+            continue;
+        if (milestoneHasDivergence(ctx.basePath, milestoneId)) {
+            drifts.push({ kind: "roadmap-divergence", milestoneId });
+        }
+    }
+    return drifts;
+}
+/**
+ * Repair a milestone's roadmap divergence:
+ *   1. migrateHierarchyToDb upserts slice rows (sequence + depends JSON
+ *      update via ON CONFLICT DO UPDATE).
+ *   2. syncSliceDependencies updates the junction table per slice — the
+ *      importer only writes the JSON column, not the relational view.
+ */
+export function repairRoadmapDivergence(record, ctx) {
+    migrateHierarchyToDb(ctx.basePath);
+    const roadmapPath = resolveMilestoneFile(ctx.basePath, record.milestoneId, "ROADMAP");
+    if (!roadmapPath || !existsSync(roadmapPath))
+        return;
+    try {
+        const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
+        for (const slice of roadmap.slices) {
+            syncSliceDependencies(record.milestoneId, slice.id, slice.depends);
+        }
+    }
+    catch {
+        /* parse failure: detector will fire again next pass */
+    }
+}
+export const roadmapDivergenceHandler = {
+    kind: "roadmap-divergence",
+    detect: detectRoadmapDivergenceDrift,
+    repair: repairRoadmapDivergence,
+};

package/dist/resources/extensions/gsd/state-reconciliation/drift/sketch-flag.js

@@ -0,0 +1,50 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-sketch-flag drift handler. Relocated from
+// gsd-db.ts where autoHealSketchFlags previously lived with zero callers.
+//
+// Recovers from two scenarios (per ADR-011):
+//   1. Crash between gsd_plan_slice's PLAN.md write and the sketch flag flip.
+//   2. Flag-OFF downgrade: when progressive_planning is off, dispatch routes
+//      sketch slices to plan-slice, which writes PLAN.md but leaves
+//      is_sketch=1 — the next reconciliation pass clears it.
+import { existsSync } from "node:fs";
+import { getSketchedSliceIds, isDbAvailable, setSliceSketchFlag, } from "../../gsd-db.js";
+import { resolveSliceFile } from "../../paths.js";
+export function detectStaleSketchFlags(state, ctx) {
+    if (!isDbAvailable())
+        return [];
+    const mid = state.activeMilestone?.id;
+    if (!mid)
+        return [];
+    const sliceIds = getSketchedSliceIds(mid);
+    return sliceIds
+        .filter((sid) => {
+        const planPath = resolveSliceFile(ctx.basePath, mid, sid, "PLAN");
+        return planPath !== null && existsSync(planPath);
+    })
+        .map((sid) => ({ kind: "stale-sketch-flag", mid, sid }));
+}
+export function repairStaleSketchFlag(record) {
+    setSliceSketchFlag(record.mid, record.sid, false);
+}
+export const sketchFlagHandler = {
+    kind: "stale-sketch-flag",
+    detect: detectStaleSketchFlags,
+    repair: (record) => {
+        repairStaleSketchFlag(record);
+    },
+};
+/**
+ * Legacy entry point preserved for callers that supply a custom hasPlanFile
+ * predicate. Prefer the drift handler (sketchFlagHandler) for new code.
+ */
+export function autoHealSketchFlags(milestoneId, hasPlanFile) {
+    if (!isDbAvailable())
+        return;
+    const sliceIds = getSketchedSliceIds(milestoneId);
+    for (const sid of sliceIds) {
+        if (hasPlanFile(sid)) {
+            setSliceSketchFlag(milestoneId, sid, false);
+        }
+    }
+}

package/dist/resources/extensions/gsd/state-reconciliation/drift/stale-render.js

@@ -0,0 +1,124 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-render drift handler. Relocated from
+// markdown-renderer.ts as part of issue #5702. detectStaleRenders stays in
+// markdown-renderer.ts (it's a useful diagnostic primitive on its own); only
+// the detect+repair composition moves here. The previous repairStaleRenders
+// had zero callers in production code — wiring it through
+// reconcileBeforeDispatch closes that gap.
+import { detectStaleRenders, renderPlanCheckboxes, renderRoadmapCheckboxes, renderSliceSummary, renderTaskSummary, } from "../../markdown-renderer.js";
+import { logWarning } from "../../workflow-logger.js";
+// ─── Core (basePath-only — usable by both drift API and legacy wrapper) ──────
+function detectStaleRenderDriftFromBasePath(basePath) {
+    const entries = detectStaleRenders(basePath);
+    if (entries.length === 0)
+        return [];
+    // detectStaleRenders may emit multiple entries for the same path (one per
+    // mismatched checkbox). Dedupe by path; the repair re-renders the whole
+    // file in a single call. Prefer a reason the repair dispatcher can handle.
+    const seen = new Map();
+    for (const entry of entries) {
+        const currentReason = seen.get(entry.path);
+        if (currentReason === undefined ||
+            (!isRepairableStaleRenderReason(currentReason) && isRepairableStaleRenderReason(entry.reason))) {
+            seen.set(entry.path, entry.reason);
+        }
+    }
+    return Array.from(seen.entries()).map(([renderPath, reason]) => ({
+        kind: "stale-render",
+        renderPath,
+        reason,
+    }));
+}
+function isRepairableStaleRenderReason(reason) {
+    return (reason.includes("in roadmap") ||
+        reason.includes("in plan") ||
+        (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) ||
+        (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) ||
+        reason.includes("UAT.md missing"));
+}
+async function repairStaleRenderFromBasePath(record, basePath) {
+    const normPath = record.renderPath.replace(/\\/g, "/");
+    const reason = record.reason;
+    if (reason.includes("in roadmap")) {
+        const milestoneMatch = normPath.match(/milestones\/([^/]+)\//);
+        if (!milestoneMatch) {
+            throw new Error(`stale-render drift: roadmap path missing milestone segment: ${record.renderPath}`);
+        }
+        await renderRoadmapCheckboxes(basePath, milestoneMatch[1]);
+        return;
+    }
+    if (reason.includes("in plan")) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        if (!pathMatch) {
+            throw new Error(`stale-render drift: plan path missing milestone/slice segments: ${record.renderPath}`);
+        }
+        await renderPlanCheckboxes(basePath, pathMatch[1], pathMatch[2]);
+        return;
+    }
+    if (reason.includes("SUMMARY.md missing") && /^T\d+/.test(reason)) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\/tasks\//);
+        const taskMatch = reason.match(/^(T\d+)/);
+        if (!pathMatch || !taskMatch) {
+            throw new Error(`stale-render drift: task summary path/reason malformed: ${record.renderPath} reason=${reason}`);
+        }
+        await renderTaskSummary(basePath, pathMatch[1], pathMatch[2], taskMatch[1]);
+        return;
+    }
+    if (reason.includes("SUMMARY.md missing") && /^S\d+/.test(reason)) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        if (!pathMatch) {
+            throw new Error(`stale-render drift: slice summary path missing milestone/slice segments: ${record.renderPath}`);
+        }
+        await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
+        return;
+    }
+    if (reason.includes("UAT.md missing")) {
+        const pathMatch = normPath.match(/milestones\/([^/]+)\/slices\/([^/]+)\//);
+        if (!pathMatch) {
+            throw new Error(`stale-render drift: UAT path missing milestone/slice segments: ${record.renderPath}`);
+        }
+        // renderSliceSummary handles both SUMMARY and UAT.
+        await renderSliceSummary(basePath, pathMatch[1], pathMatch[2]);
+        return;
+    }
+    throw new Error(`stale-render drift: detector emitted unknown reason "${reason}" for ${record.renderPath}`);
+}
+// ─── Drift Handler API ───────────────────────────────────────────────────────
+export function detectStaleRenderDrift(_state, ctx) {
+    return detectStaleRenderDriftFromBasePath(ctx.basePath);
+}
+export async function repairStaleRender(record, ctx) {
+    await repairStaleRenderFromBasePath(record, ctx.basePath);
+}
+export const staleRenderHandler = {
+    kind: "stale-render",
+    detect: detectStaleRenderDrift,
+    repair: repairStaleRender,
+};
+// ─── Legacy entry point ──────────────────────────────────────────────────────
+/**
+ * Legacy bulk entry preserved for existing tests
+ * (tests/markdown-renderer.test.ts, tests/integration/integration-proof.test.ts).
+ * New code prefers the drift handler via `reconcileBeforeDispatch`. Matches the
+ * pre-ADR-017 behavior: silent per-entry error handling, returns the count of
+ * successful repairs.
+ */
+export async function repairStaleRenders(basePath) {
+    const drifts = detectStaleRenderDriftFromBasePath(basePath);
+    if (drifts.length === 0)
+        return 0;
+    let repaired = 0;
+    for (const drift of drifts) {
+        try {
+            await repairStaleRenderFromBasePath(drift, basePath);
+            repaired++;
+        }
+        catch (err) {
+            logWarning("renderer", `repair failed for ${drift.renderPath}: ${err.message}`);
+        }
+    }
+    if (repaired > 0) {
+        process.stderr.write(`markdown-renderer: repaired ${repaired} stale render(s)\n`);
+    }
+    return repaired;
+}

package/dist/resources/extensions/gsd/state-reconciliation/drift/stale-worker.js

@@ -0,0 +1,32 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 stale-worker drift handler. Detects session-lock
+// artifacts whose owning PID is no longer alive (typical after SIGKILL or
+// laptop sleep where the heartbeat wasn't released cleanly), and clears them
+// before the next dispatch attempts to acquire the lock.
+import { effectiveLockFile, isSessionLockProcessAlive, readSessionLockData, removeStaleSessionLock, } from "../../session-lock.js";
+export function detectStaleWorkerDrift(_state, ctx) {
+    const data = readSessionLockData(ctx.basePath);
+    if (!data)
+        return [];
+    if (typeof data.pid !== "number")
+        return [];
+    if (isSessionLockProcessAlive(data))
+        return [];
+    return [
+        {
+            kind: "stale-worker",
+            lockPath: effectiveLockFile(),
+            pid: data.pid,
+        },
+    ];
+}
+export function repairStaleWorker(_record, ctx) {
+    // removeStaleSessionLock is idempotent: it re-reads lock state and is a
+    // no-op when the lock is held by an alive process. Safe under cap=2 retry.
+    removeStaleSessionLock(ctx.basePath);
+}
+export const staleWorkerHandler = {
+    kind: "stale-worker",
+    detect: detectStaleWorkerDrift,
+    repair: repairStaleWorker,
+};

package/dist/resources/extensions/gsd/state-reconciliation/errors.js

@@ -0,0 +1,41 @@
+// Project/App: GSD-2
+// File Purpose: ADR-017 typed reconciliation failure for Recovery Classification.
+/**
+ * Thrown by reconcileBeforeDispatch when:
+ *   - one or more repair functions throw within a pass (`failures` populated), or
+ *   - drift persists after the cap=2 lifecycle (`persistentDrift` populated).
+ *
+ * Recovery Classification recognizes this error via instanceof and maps it to
+ * failureKind "reconciliation-drift" with action "escalate".
+ */
+export class ReconciliationFailedError extends Error {
+    failures;
+    detectionFailures;
+    persistentDrift;
+    pass;
+    constructor(opts) {
+        super(formatMessage(opts));
+        this.name = "ReconciliationFailedError";
+        this.failures = opts.failures ?? [];
+        this.detectionFailures = opts.detectionFailures ?? [];
+        this.persistentDrift = opts.persistentDrift ?? [];
+        this.pass = opts.pass;
+    }
+}
+function formatMessage(opts) {
+    if (opts.detectionFailures && opts.detectionFailures.length > 0) {
+        const kinds = opts.detectionFailures.map((f) => f.handlerKind).join(", ");
+        const passSuffix = opts.pass !== undefined ? ` in pass ${opts.pass}` : "";
+        return `Reconciliation detect failed${passSuffix} for handlers: ${kinds}`;
+    }
+    if (opts.failures && opts.failures.length > 0) {
+        const kinds = opts.failures.map((f) => f.drift.kind).join(", ");
+        const passSuffix = opts.pass !== undefined ? ` in pass ${opts.pass}` : "";
+        return `Reconciliation repair failed${passSuffix} for drift kinds: ${kinds}`;
+    }
+    if (opts.persistentDrift && opts.persistentDrift.length > 0) {
+        const kinds = opts.persistentDrift.map((d) => d.kind).join(", ");
+        return `Reconciliation drift persisted after cap=2 passes: ${kinds}`;
+    }
+    return "Reconciliation failed";
+}