gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.58d3d4d6c

package/dist/resources/extensions/gsd/context-store.js

@@ -180,7 +180,13 @@ export function queryProject() {
 // ─── Knowledge Query ───────────────────────────────────────────────────────
 /**
  * Filter KNOWLEDGE.md sections by keyword matching.
- * Uses H2 sections, matches keywords case-insensitively against:
+ *
+ * Structure-adaptive (issue #4719): files that organise entries as H3 items
+ * under one or more H2 topics are filtered at H3 granularity. Files with only
+ * H2 topic headers (no H3) fall back to H2-level filtering for backwards
+ * compatibility.
+ *
+ * Matches keywords case-insensitively against:
  * 1. Section header text
  * 2. First paragraph of section content (up to first blank line or next heading)
  *
@@ -189,28 +195,38 @@ export function queryProject() {
  *
  * @param content - Full KNOWLEDGE.md content
  * @param keywords - Keywords to match (case-insensitive)
- * @returns Concatenated matching sections with H2 headers, or empty string
+ * @returns Concatenated matching sections with their original heading prefix, or empty string
  */
 export async function queryKnowledge(content, keywords) {
     if (!content || keywords.length === 0)
         return '';
     // Lazy import to avoid circular dependency
     const { extractAllSections } = await import('./files.js');
-    const sections = extractAllSections(content, 2);
+    // Prefer H3 granularity when available; fall back to H2 for H2-only files.
+    // This prevents single-H2-with-many-H3 layouts from returning the entire
+    // file on a keyword match against the H2 header or its first paragraph.
+    const h3Sections = extractAllSections(content, 3);
+    const useH3 = h3Sections.size > 0;
+    const sections = useH3 ? h3Sections : extractAllSections(content, 2);
     if (sections.size === 0)
         return '';
-    // Normalize keywords for case-insensitive matching
-    const normalizedKeywords = keywords.map(k => k.toLowerCase());
+    const prefix = useH3 ? '###' : '##';
+    // Trim, lowercase, drop empties, and de-dupe so callers can pass raw
+    // user-provided strings without risking empty-string / whitespace matches.
+    const normalizedKeywords = [...new Set(keywords
+            .map(k => k.trim().toLowerCase())
+            .filter(k => k.length > 0))];
+    if (normalizedKeywords.length === 0)
+        return '';
     const matchingSections = [];
     for (const [header, body] of sections) {
         // Extract first paragraph: everything up to first blank line or next heading
         const firstParagraph = body.split(/\n\s*\n|\n#/)[0] || '';
-        // Check if any keyword matches header or first paragraph
         const headerLower = header.toLowerCase();
         const paragraphLower = firstParagraph.toLowerCase();
         const matches = normalizedKeywords.some(kw => headerLower.includes(kw) || paragraphLower.includes(kw));
         if (matches) {
-            matchingSections.push(`## ${header}\n\n${body}`);
+            matchingSections.push(`${prefix} ${header}\n\n${body}`);
         }
     }
     return matchingSections.join('\n\n');

package/dist/resources/extensions/gsd/dispatch-guard.js

@@ -5,23 +5,8 @@ import { parseUnitId } from "./unit-id.js";
 import { isDbAvailable, getMilestoneSlices, getMilestone } from "./gsd-db.js";
 import { parseRoadmap } from "./parsers-legacy.js";
 import { isClosedStatus } from "./status-guards.js";
+import { classifyMilestoneSummaryContent } from "./milestone-summary-classifier.js";
 import { readFileSync } from "node:fs";
-/**
- * Detect failure-path milestone SUMMARY content (#4663 sibling to #4658).
- * A failure SUMMARY must not let the dispatch guard treat an active
- * milestone as complete. The markers mirror those produced by
- * writeBlockerPlaceholder and the "verification FAILED" retry path.
- *
- * This is intentionally a minimal local detector so this fix does not
- * depend on PR #4660's `classifyMilestoneSummaryContent`. It can migrate
- * to the shared classifier once that lands.
- */
-function isFailureMilestoneSummary(content) {
-    return (/(?:^|\n)\s*#\s*BLOCKER\b/i.test(content) ||
-        /auto-mode recovery failed/i.test(content) ||
-        /verification\s+failed/i.test(content) ||
-        /\bnot complete\b/i.test(content));
-}
 const SLICE_DISPATCH_TYPES = new Set([
     "research-slice",
     "plan-slice",
@@ -78,7 +63,7 @@ export function getPriorSliceCompletionBlocker(base, _mainBranch, unitType, unit
                 summaryContent = readFileSync(summaryPath, "utf-8");
             }
             catch { /* ignore */ }
-            if (!summaryContent || !isFailureMilestoneSummary(summaryContent)) {
+            if (!summaryContent || classifyMilestoneSummaryContent(summaryContent) !== "failure") {
                 continue;
             }
         }

package/dist/resources/extensions/gsd/file-lock.js

@@ -1,11 +1,19 @@
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+// The file-lock module is loaded in both CJS builds and ESM sources. Under ESM
+// the bare `require` identifier is not defined, so we always go through
+// createRequire. We try the current module's resolution context first and fall
+// back to the installed gsd-pi package if we are running from a consumer
+// project that does not hoist proper-lockfile.
+const localRequire = createRequire(import.meta.url);
 function _require(name) {
     try {
-        return require(name);
+        return localRequire(name);
     }
     catch {
         try {
-            const gsdPiRequire = require("module").createRequire(require("path").join(process.cwd(), "node_modules", "gsd-pi", "index.js"));
+            const gsdPiRequire = createRequire(join(process.cwd(), "node_modules", "gsd-pi", "index.js"));
             return gsdPiRequire(name);
         }
         catch {
@@ -13,14 +21,44 @@ function _require(name) {
         }
     }
 }
-export function withFileLockSync(filePath, fn) {
+const DEFAULT_RETRIES = 5;
+const DEFAULT_STALE_MS = 10000;
+const SYNC_RETRY_DELAY_MS = 50;
+// Block the thread for `ms` milliseconds without spinning the CPU.
+// Used by the sync lock retry loop, since proper-lockfile's lockSync does not
+// accept a `retries` option (only the async `lock` does).
+function sleepSync(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function acquireLockSyncWithRetry(lockfile, filePath, retries, stale) {
+    let lastErr;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            return lockfile.lockSync(filePath, { stale });
+        }
+        catch (err) {
+            lastErr = err;
+            if (err?.code !== "ELOCKED")
+                throw err;
+            if (attempt < retries)
+                sleepSync(SYNC_RETRY_DELAY_MS);
+        }
+    }
+    throw lastErr;
+}
+export function withFileLockSync(filePath, fn, opts = {}) {
     const lockfile = _require("proper-lockfile");
     if (!lockfile)
         return fn();
     if (!existsSync(filePath))
         return fn();
+    const retries = opts.retries ?? DEFAULT_RETRIES;
+    const stale = opts.stale ?? DEFAULT_STALE_MS;
+    const onLocked = opts.onLocked ?? "fail";
     try {
-        const release = lockfile.lockSync(filePath, { retries: 5, stale: 10000 });
+        const release = acquireLockSyncWithRetry(lockfile, filePath, retries, stale);
         try {
             return fn();
         }
@@ -29,21 +67,23 @@ export function withFileLockSync(filePath, fn) {
         }
     }
     catch (err) {
-        if (err.code === "ELOCKED") {
-            // Could not get lock after retries, let's fallback to un-locked instead of crashing the whole state machine
+        if (err?.code === "ELOCKED" && onLocked === "skip") {
             return fn();
         }
         throw err;
     }
 }
-export async function withFileLock(filePath, fn) {
+export async function withFileLock(filePath, fn, opts = {}) {
     const lockfile = _require("proper-lockfile");
     if (!lockfile)
         return await fn();
     if (!existsSync(filePath))
         return await fn();
+    const retries = opts.retries ?? DEFAULT_RETRIES;
+    const stale = opts.stale ?? DEFAULT_STALE_MS;
+    const onLocked = opts.onLocked ?? "fail";
     try {
-        const release = await lockfile.lock(filePath, { retries: 5, stale: 10000 });
+        const release = await lockfile.lock(filePath, { retries, stale });
         try {
             return await fn();
         }
@@ -52,7 +92,7 @@ export async function withFileLock(filePath, fn) {
         }
     }
     catch (err) {
-        if (err.code === "ELOCKED") {
+        if (err?.code === "ELOCKED" && onLocked === "skip") {
             return await fn();
         }
         throw err;

package/dist/resources/extensions/gsd/forensics.js

@@ -29,6 +29,7 @@ import { getAutoWorktreePath } from "./auto-worktree.js";
 import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
 import { showNextAction } from "../shared/tui.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
+import { summarizeWorktreeTelemetry, percentile } from "./worktree-telemetry.js";
 // ─── Duplicate Detection ──────────────────────────────────────────────────────
 const DEDUP_PROMPT_SECTION = `
 ## Pre-Investigation: Duplicate Check (REQUIRED)
@@ -214,6 +215,16 @@ export async function buildForensicReport(basePath) {
     detectCrash(crashLock, anomalies);
     detectDoctorIssues(doctorIssues, anomalies);
     detectErrorTraces(unitTraces, anomalies);
+    // 11b. #4764 — worktree lifecycle telemetry
+    let worktreeTelemetry = null;
+    try {
+        worktreeTelemetry = summarizeWorktreeTelemetry(basePath);
+        detectWorktreeOrphans(worktreeTelemetry, anomalies);
+    }
+    catch {
+        // Telemetry is best-effort — do not let an aggregator failure block the
+        // rest of the forensic report.
+    }
     detectJournalAnomalies(journalSummary, anomalies);
     return {
         gsdVersion,
@@ -232,6 +243,7 @@ export async function buildForensicReport(basePath) {
         recentUnits,
         journalSummary,
         activityLogMeta,
+        worktreeTelemetry,
     };
 }
 // ─── Activity Log Scanner ─────────────────────────────────────────────────────
@@ -630,6 +642,45 @@ function detectMissingArtifacts(completedKeys, basePath, activeMilestone, anomal
         }
     }
 }
+/**
+ * #4764 — surface worktree lifecycle and orphan signals in the forensic report.
+ *
+ * Consumes only the aggregated summary (not raw journal events) to respect
+ * the forensics memory-bloat guard in forensics-journal.test.ts — per-event
+ * detail stays in the journal itself where the LLM can query it on demand.
+ */
+function detectWorktreeOrphans(summary, anomalies) {
+    // 1. Orphan aggregate — severity depends on reason. In-progress orphans are
+    // the #4761 consumer-side signal (live work sitting on an unmerged branch).
+    for (const [reason, count] of Object.entries(summary.orphansByReason)) {
+        if (count <= 0)
+            continue;
+        const severity = reason === "in-progress-unmerged" ? "warning" : "info";
+        anomalies.push({
+            type: "worktree-orphan",
+            severity,
+            summary: `${count} worktree orphan(s) detected (${reason})`,
+            details: reason === "in-progress-unmerged"
+                ? "Auto-mode exited without completing a milestone; live work sits on an unmerged milestone branch. Run `/gsd auto` to resume, or merge manually."
+                : reason === "complete-unmerged"
+                    ? "A completed milestone's branch was never merged back to main. Run `/gsd health --fix` to resolve."
+                    : `Reason: ${reason}.`,
+        });
+    }
+    // 2. Auto-exit producer signal — #4761's upstream cause.
+    if (summary.exitsWithUnmergedWork > 0) {
+        const reasonBreakdown = Object.entries(summary.exitsByReason)
+            .filter(([, n]) => n > 0)
+            .map(([r, n]) => `${r}=${n}`)
+            .join(", ");
+        anomalies.push({
+            type: "worktree-unmerged-exit",
+            severity: "warning",
+            summary: `${summary.exitsWithUnmergedWork} auto-exit(s) left milestone work unmerged`,
+            details: `Exit reasons: ${reasonBreakdown || "(none)"} · Producer-side signal for #4761-class orphans. Inspect .gsd/journal/*.jsonl with eventType:"auto-exit" for per-exit detail.`,
+        });
+    }
+}
 function detectCrash(crashLock, anomalies) {
     if (!crashLock)
         return;
@@ -808,6 +859,39 @@ function saveForensicReport(basePath, report, problemDescription) {
             sections.push(`- Newest: ${meta.newestFile}`);
         sections.push(``);
     }
+    // #4764 — Worktree telemetry summary
+    if (report.worktreeTelemetry) {
+        const t = report.worktreeTelemetry;
+        const p50 = percentile(t.mergeDurationsMs, 0.5);
+        const p95 = percentile(t.mergeDurationsMs, 0.95);
+        sections.push(`## Worktree Telemetry`, ``);
+        sections.push(`- Worktrees created: ${t.worktreesCreated}`);
+        sections.push(`- Worktrees merged: ${t.worktreesMerged}`);
+        sections.push(`- Orphans detected: ${t.orphansDetected}`);
+        if (t.orphansDetected > 0) {
+            const breakdown = Object.entries(t.orphansByReason)
+                .map(([r, n]) => `${r}=${n}`).join(", ");
+            sections.push(`  - By reason: ${breakdown}`);
+        }
+        sections.push(`- Merge conflicts: ${t.mergeConflicts}`);
+        if (t.mergeDurationsMs.length > 0) {
+            sections.push(`- Merge duration p50 / p95: ${p50 ?? "-"} / ${p95 ?? "-"} ms (n=${t.mergeDurationsMs.length})`);
+        }
+        sections.push(`- Auto-exits leaving unmerged work: ${t.exitsWithUnmergedWork}`);
+        if (Object.keys(t.exitsByReason).length > 0) {
+            const breakdown = Object.entries(t.exitsByReason)
+                .sort((a, b) => b[1] - a[1])
+                .map(([r, n]) => `${r}=${n}`).join(", ");
+            sections.push(`  - Exit reasons: ${breakdown}`);
+        }
+        sections.push(`- Canonical-root redirects (#4761 fix fired): ${t.canonicalRedirects}`);
+        // #4765 slice-cadence counters
+        if (t.slicesMerged + t.sliceMergeConflicts + t.milestoneResquashes > 0) {
+            sections.push(`- Slices merged: ${t.slicesMerged} · Slice merge conflicts: ${t.sliceMergeConflicts}`);
+            sections.push(`- Milestone re-squashes: ${t.milestoneResquashes}`);
+        }
+        sections.push(``);
+    }
     // Journal summary
     if (report.journalSummary) {
         const js = report.journalSummary;
@@ -940,6 +1024,28 @@ function formatReportForPrompt(report) {
         sections.push(`- Total duration: ${formatDuration(totals.duration)}`);
         sections.push("");
     }
+    // #4764 — worktree telemetry (compact prompt form)
+    if (report.worktreeTelemetry) {
+        const t = report.worktreeTelemetry;
+        const hasSignal = t.worktreesCreated + t.worktreesMerged + t.orphansDetected +
+            t.exitsWithUnmergedWork + t.canonicalRedirects +
+            t.slicesMerged + t.milestoneResquashes > 0;
+        if (hasSignal) {
+            sections.push("### Worktree Telemetry");
+            sections.push(`- Created: ${t.worktreesCreated} · Merged: ${t.worktreesMerged} · Conflicts: ${t.mergeConflicts}`);
+            sections.push(`- Orphans: ${t.orphansDetected} · Unmerged exits: ${t.exitsWithUnmergedWork} · Redirects (#4761): ${t.canonicalRedirects}`);
+            if (t.orphansDetected > 0) {
+                const breakdown = Object.entries(t.orphansByReason)
+                    .map(([r, n]) => `${r}=${n}`).join(", ");
+                sections.push(`- Orphan reasons: ${breakdown}`);
+            }
+            // #4765 — slice-cadence counters (only shown when the feature was exercised)
+            if (t.slicesMerged + t.sliceMergeConflicts + t.milestoneResquashes > 0) {
+                sections.push(`- Slices merged: ${t.slicesMerged} · Slice conflicts: ${t.sliceMergeConflicts} · Re-squashes: ${t.milestoneResquashes}`);
+            }
+            sections.push("");
+        }
+    }
     // Activity log metadata
     if (report.activityLogMeta) {
         const meta = report.activityLogMeta;

package/dist/resources/extensions/gsd/git-service.js

@@ -84,6 +84,7 @@ export class MergeConflictError extends GSDError {
  */
 export const RUNTIME_EXCLUSION_PATHS = [
     ".gsd/activity/",
+    ".gsd/audit/",
     ".gsd/forensics/",
     ".gsd/runtime/",
     ".gsd/worktrees/",

package/dist/resources/extensions/gsd/gitignore.js

@@ -24,6 +24,7 @@ import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
  */
 const GSD_RUNTIME_PATTERNS = [
     ".gsd/activity/",
+    ".gsd/audit/",
     ".gsd/forensics/",
     ".gsd/runtime/",
     ".gsd/worktrees/",

package/dist/resources/extensions/gsd/guided-flow-queue.js

@@ -13,6 +13,7 @@ import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { gsdRoot, resolveMilestoneFile, resolveGsdRootFile, relGsdRootFile, } from "./paths.js";
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { atomicWriteSync } from "./atomic-write.js";
 import { nativeAddPaths, nativeCommit } from "./native-git-bridge.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { saveQueueOrder } from "./queue-order.js";
@@ -361,5 +362,7 @@ function syncProjectMdSequence(basePath, registry, newOrder) {
     const separatorLine = lines[tableStart + 1];
     const newTable = [headerLine, separatorLine, ...newRows];
     lines.splice(tableStart, tableEnd - tableStart, ...newTable);
-    writeFileSync(projectPath, lines.join("\n"), "utf-8");
+    // Atomic write: tmp+rename avoids a torn PROJECT.md appearing dirty in
+    // another worktree's working tree during a concurrent /gsd auto merge.
+    atomicWriteSync(projectPath, lines.join("\n"), "utf-8");
 }

package/dist/resources/extensions/gsd/guided-flow.js

@@ -10,7 +10,7 @@ import { loadFile, saveFile } from "./files.js";
 import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
 import { parseRoadmapSlices } from "./roadmap-slices.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
-import { buildSkillActivationBlock } from "./auto-prompts.js";
+import { buildDiscussMilestonePrompt, buildSkillActivationBlock } from "./auto-prompts.js";
 import { deriveState } from "./state.js";
 import { invalidateAllCaches } from "./cache.js";
 import { startAutoDetached } from "./auto.js";
@@ -27,7 +27,7 @@ import { isInheritedRepo } from "./repo-identity.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { resolveUokFlags } from "./uok/flags.js";
-import { ensurePlanV2Graph } from "./uok/plan-v2.js";
+import { ensurePlanV2Graph, isMissingFinalizedContextResult } from "./uok/plan-v2.js";
 import { detectProjectState } from "./detection.js";
 import { showProjectInit, offerMigration } from "./init-wizard.js";
 import { validateDirectory } from "./validate-directory.js";
@@ -65,14 +65,17 @@ function runPlanV2Gate(ctx, basePath, state) {
     const prefs = loadEffectiveGSDPreferences()?.preferences;
     const uokFlags = resolveUokFlags(prefs);
     if (!uokFlags.planV2 || !needsPlanV2Gate(state))
-        return true;
+        return "pass";
     const compiled = ensurePlanV2Graph(basePath, state);
     if (!compiled.ok) {
+        if (isMissingFinalizedContextResult(compiled)) {
+            return "recover-missing-context";
+        }
         const reason = compiled.reason ?? "plan-v2 compilation failed";
         ctx.ui.notify(`Plan gate failed-closed: ${reason}. Complete plan/discuss artifacts before execution.\n\nIf this keeps happening, try: /gsd doctor heal`, "error");
-        return false;
+        return "block";
     }
-    return true;
+    return "pass";
 }
 // ─── Commit Instruction Helpers ──────────────────────────────────────────────
 /** Build commit instruction for planning prompts. .gsd/ is managed externally and always gitignored. */
@@ -228,7 +231,7 @@ export function checkAutoStartAfterDiscuss() {
         }
     }
     pendingAutoStartMap.delete(basePath);
-    ctx.ui.notify(`Milestone ${milestoneId} ready.`, "info");
+    ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
     startAutoDetached(ctx, pi, basePath, false, { step });
     return true;
 }
@@ -669,8 +672,13 @@ export async function showHeadlessMilestoneCreation(ctx, pi, basePath, seedConte
     const prompt = buildHeadlessDiscussPrompt(nextId, seedContext, basePath);
     // Set pending auto start (auto-mode triggers on "Milestone X ready." via checkAutoStartAfterDiscuss)
     pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId: nextId, createdAt: Date.now() });
-    // Dispatch — headless milestone creation is a planning activity
-    await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "plan-milestone");
+    // Dispatch as discuss-milestone. The LLM writes PROJECT.md, REQUIREMENTS.md,
+    // and CONTEXT.md, then calls gsd_plan_milestone — this is semantically the
+    // discuss path, just non-interactive. Using "plan-milestone" here caused
+    // model/tool routing to skip discuss-flow tool scoping and
+    // `checkAutoStartAfterDiscuss` guardrails that rely on the
+    // "discuss-"-prefixed unitType.
+    await dispatchWorkflow(pi, prompt, "gsd-run", ctx, "discuss-milestone");
 }
 // ─── Discuss Flow ─────────────────────────────────────────────────────────────
 /**
@@ -1322,7 +1330,8 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     catch (err) {
         logWarning("guided", `STATE.md rebuild failed: ${err.message}`);
     }
-    if (!runPlanV2Gate(ctx, basePath, state))
+    const planV2GateDecision = runPlanV2Gate(ctx, basePath, state);
+    if (planV2GateDecision === "block")
         return;
     if (!state.activeMilestone?.id) {
         // Guard: if a discuss session is already in flight, don't re-inject the prompt.
@@ -1397,6 +1406,11 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     }
     const milestoneId = state.activeMilestone.id;
     const milestoneTitle = state.activeMilestone.title;
+    if (planV2GateDecision === "recover-missing-context") {
+        pendingAutoStartMap.set(basePath, { ctx, pi, basePath, milestoneId, step: stepMode, createdAt: Date.now() });
+        await dispatchWorkflow(pi, await buildDiscussMilestonePrompt(milestoneId, milestoneTitle, basePath, getStructuredQuestionsAvailability(pi, ctx)), "gsd-discuss", ctx, "discuss-milestone");
+        return;
+    }
     // ── All milestones complete → New milestone ──────────────────────────
     if (state.phase === "complete") {
         const choice = await showNextAction(ctx, {

package/dist/resources/extensions/gsd/journal.js

@@ -11,8 +11,10 @@
  * - queryJournal() enables programmatic filtering by flowId, eventType, unitId, time range
  * - Silent failure: journal writes never throw — absence of events is the failure signal
  */
-import { appendFileSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { appendFileSync, closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, } from "node:fs";
 import { join } from "node:path";
+import { isStaleWrite } from "./auto/turn-epoch.js";
+import { withFileLockSync } from "./file-lock.js";
 import { gsdRoot } from "./paths.js";
 import { buildAuditEnvelope, emitUokAuditEvent } from "./uok/audit.js";
 import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
@@ -26,12 +28,25 @@ import { isUnifiedAuditEnabled } from "./uok/audit-toggle.js";
  * Never throws — all errors are silently caught.
  */
 export function emitJournalEvent(basePath, entry) {
+    // Drop writes from a turn superseded by timeout recovery / cancellation.
+    // See auto/turn-epoch.ts for the full rationale.
+    if (isStaleWrite("journal"))
+        return;
     try {
         const journalDir = join(gsdRoot(basePath), "journal");
         mkdirSync(journalDir, { recursive: true });
         const dateStr = entry.ts.slice(0, 10);
         const filePath = join(journalDir, `${dateStr}.jsonl`);
-        appendFileSync(filePath, JSON.stringify(entry) + "\n");
+        // Ensure file exists so proper-lockfile can acquire a lock against it.
+        if (!existsSync(filePath))
+            closeSync(openSync(filePath, "a"));
+        // onLocked: "skip" — journal writes are best-effort. POSIX O_APPEND
+        // atomicity still protects small entries; the lock mainly serializes
+        // larger writes and gives cross-process exclusivity on platforms where
+        // O_APPEND semantics are weaker (Windows).
+        withFileLockSync(filePath, () => {
+            appendFileSync(filePath, JSON.stringify(entry) + "\n");
+        }, { onLocked: "skip" });
     }
     catch {
         // Silent failure — journal must never break auto-mode

package/dist/resources/extensions/gsd/milestone-actions.js

@@ -18,6 +18,18 @@ import { loadQueueOrder, saveQueueOrder } from "./queue-order.js";
 import { deleteMilestone, getMilestone, isDbAvailable, updateMilestoneStatus } from "./gsd-db.js";
 import { removeWorktree } from "./worktree-manager.js";
 import { logWarning } from "./workflow-logger.js";
+import { isAutoActive } from "./auto.js";
+/**
+ * Writer-side assert for mutations that race with auto-mode's squash merge (#4704).
+ * Auto-mode is confirmed not to call parkMilestone/discardMilestone/unparkMilestone
+ * internally — these throws only surface invariant violations from new or forgotten
+ * call sites, which is the correct failure mode to catch loudly.
+ */
+function assertNotAutoActive(action) {
+    if (isAutoActive()) {
+        throw new Error(`${action} cannot run while auto-mode is active. Stop auto-mode first with /gsd stop.`);
+    }
+}
 // ─── Park ──────────────────────────────────────────────────────────────────
 /**
  * Park a milestone — creates a PARKED.md marker file with reason and timestamp.
@@ -25,6 +37,7 @@ import { logWarning } from "./workflow-logger.js";
  * Returns true if successfully parked, false if milestone not found or already parked.
  */
 export function parkMilestone(basePath, milestoneId, reason) {
+    assertNotAutoActive("park milestone");
     const mDir = resolveMilestonePath(basePath, milestoneId);
     if (!mDir || !existsSync(mDir))
         return false;
@@ -65,6 +78,7 @@ export function parkMilestone(basePath, milestoneId, reason) {
  * Returns true if successfully unparked, false if milestone not found or not parked.
  */
 export function unparkMilestone(basePath, milestoneId) {
+    assertNotAutoActive("unpark milestone");
     const mDir = resolveMilestonePath(basePath, milestoneId);
     if (!mDir || !existsSync(mDir))
         return false;
@@ -97,6 +111,7 @@ export function unparkMilestone(basePath, milestoneId) {
  * Returns true if successfully discarded, false if milestone not found.
  */
 export function discardMilestone(basePath, milestoneId) {
+    assertNotAutoActive("discard milestone");
     const mDir = resolveMilestonePath(basePath, milestoneId);
     if (!mDir || !existsSync(mDir))
         return false;

package/dist/resources/extensions/gsd/milestone-summary-classifier.js

@@ -0,0 +1,37 @@
+/**
+ * Shared milestone SUMMARY classifier.
+ *
+ * SUMMARY presence alone is not enough to prove milestone completion: recovery
+ * and blocker paths also write SUMMARY files. Keep this leaf module free of
+ * state/auto imports so state derivation, dispatch guards, and recovery can
+ * share one definition without cycles.
+ */
+import { splitFrontmatter, parseFrontmatterMap } from "../shared/frontmatter.js";
+import { isClosedStatus } from "./status-guards.js";
+export function classifyMilestoneSummaryContent(content) {
+    const [fmLines] = splitFrontmatter(content);
+    const fm = fmLines ? parseFrontmatterMap(fmLines) : null;
+    const rawStatus = typeof fm?.status === "string" ? fm.status.trim().toLowerCase() : "";
+    if (rawStatus) {
+        if (isClosedStatus(rawStatus))
+            return "success";
+        if (["active", "pending", "blocked", "failed", "failure", "incomplete"].includes(rawStatus)) {
+            return "failure";
+        }
+    }
+    const failureSignal = /(?:^|\n)\s*#\s*BLOCKER\b/i.test(content)
+        || /auto-mode recovery failed/i.test(content)
+        || /verification\s+failed/i.test(content)
+        || /(?:^|\n)\s*(?:status|verdict|outcome|result)\s*[:=-]\s*not complete\b/i.test(content);
+    if (failureSignal)
+        return "failure";
+    return "unknown";
+}
+/**
+ * Legacy-compatible terminal check for state derivation.
+ * Unknown summaries remain terminal to preserve old handwritten SUMMARY files;
+ * explicit failure summaries do not.
+ */
+export function isTerminalMilestoneSummaryContent(content) {
+    return classifyMilestoneSummaryContent(content) !== "failure";
+}

package/dist/resources/extensions/gsd/notifications.js

@@ -2,7 +2,6 @@
 // Cross-platform desktop notifications for auto-mode events.
 import { execFileSync } from "node:child_process";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/index.js";
 import { sendRemoteNotification } from "../remote-questions/notify.js";
 /**
  * Send a native desktop notification. Non-blocking, non-fatal.
@@ -20,22 +19,37 @@ export function sendDesktopNotification(title, message, level = "info", kind = "
     void sendRemoteNotification(title, message).catch(() => { });
     if (!shouldSendDesktopNotification(kind, loaded?.notifications))
         return;
-    const cmux = resolveCmuxConfig(loaded);
-    if (cmux.notifications) {
-        const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
-        if (delivered)
-            return;
-        emitOsc777Notification(title, message);
-    }
-    try {
-        const command = buildDesktopNotificationCommand(process.platform, title, message, level);
-        if (!command)
+    // cmux delivery and desktop delivery are independent — if cmux import or
+    // delivery fails, we must still attempt the native desktop notification.
+    const runCmux = async () => {
+        try {
+            const { CmuxClient, emitOsc777Notification, resolveCmuxConfig } = await import("../cmux/index.js");
+            const cmux = resolveCmuxConfig(loaded);
+            if (cmux.notifications) {
+                const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+                if (delivered)
+                    return true;
+                emitOsc777Notification(title, message);
+            }
+        }
+        catch {
+            // cmux unavailable — fall through to desktop notification
+        }
+        return false;
+    };
+    void runCmux().then((deliveredByCmux) => {
+        if (deliveredByCmux)
             return;
-        execFileSync(command.file, command.args, { timeout: 3000, stdio: "ignore" });
-    }
-    catch {
-        // Non-fatal — desktop notifications are best-effort
-    }
+        try {
+            const command = buildDesktopNotificationCommand(process.platform, title, message, level);
+            if (!command)
+                return;
+            execFileSync(command.file, command.args, { timeout: 3000, stdio: "ignore" });
+        }
+        catch {
+            // Non-fatal — desktop notifications are best-effort
+        }
+    }).catch(() => { });
 }
 export function shouldSendDesktopNotification(kind, preferences = loadEffectiveGSDPreferences()?.preferences.notifications) {
     if (preferences?.enabled === false)