gsd-pi 2.77.0-dev.c9c8932c6 → 2.77.0-dev.eaa4973bc

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

@@ -26,6 +26,9 @@ import {
   isDbAvailable,
   getMilestone,
   getMilestoneSlices,
+  closeDatabase,
+  openDatabase,
+  getDbPath,
 } from "./gsd-db.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { execFileSync } from "node:child_process";
@@ -1668,22 +1671,51 @@ export function mergeMilestoneToMain(
   const milestonesDir = join(gsdRoot(originalBasePath_), "milestones");
   const shelterDir = join(gsdRoot(originalBasePath_), ".milestone-shelter");
   const shelteredDirs: string[] = [];
+  let shelterRestored = false;
 
   // Helper: restore sheltered milestone directories (#2505).
   // Called on both success and error paths to ensure queued CONTEXT files
-  // are never permanently lost.
+  // are never permanently lost. Idempotent — the error path may fire after
+  // the success path has already restored and removed the shelter dir; a
+  // second call is a no-op instead of logging a misleading "shelter restore
+  // failed: ENOENT" error for shelter sources that were cleaned up legitimately.
   const restoreShelter = (): void => {
+    if (shelterRestored) return;
+    shelterRestored = true;
     if (shelteredDirs.length === 0) return;
+    let restoreFailed = false;
     for (const dirName of shelteredDirs) {
+      const src = join(shelterDir, dirName);
+      // If the shelter source is missing the restore cannot proceed for this
+      // entry. Distinguish "legitimately missing" (shelter dir removed by a
+      // prior successful restore or never copied) from a surprising ENOENT
+      // inside an otherwise-populated shelter.
+      if (!existsSync(src)) {
+        logWarning(
+          "worktree",
+          `shelter source missing for ${dirName}; skipping restore (shelter already cleaned or entry never staged)`,
+        );
+        continue;
+      }
       try {
         mkdirSync(milestonesDir, { recursive: true });
-        cpSync(join(shelterDir, dirName), join(milestonesDir, dirName), { recursive: true, force: true });
+        cpSync(src, join(milestonesDir, dirName), { recursive: true, force: true });
       } catch (err) { /* best-effort */
-        logError("worktree", `shelter restore failed: ${err instanceof Error ? err.message : String(err)}`);
+        restoreFailed = true;
+        logError("worktree", `shelter restore failed (${dirName}): ${err instanceof Error ? err.message : String(err)}`);
       }
     }
-    try { rmSync(shelterDir, { recursive: true, force: true }); } catch (err) { /* best-effort */
-      logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+    // Preserve the shelter if any per-entry restore failed — it is the only
+    // surviving copy of the queued milestone dirs (sources were deleted during
+    // shelter). Deleting it here would permanently lose those files (#2505).
+    if (restoreFailed) {
+      logWarning("worktree", `shelter retained at ${shelterDir} — manual recovery required for unrestored entries`);
+      return;
+    }
+    if (existsSync(shelterDir)) {
+      try { rmSync(shelterDir, { recursive: true, force: true }); } catch (err) { /* best-effort */
+        logWarning("worktree", `shelter cleanup failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
     }
   };
 
@@ -1720,6 +1752,21 @@ export function mergeMilestoneToMain(
   //     entries (e.g. a gitignored `.gsd` symlink under ADR-002) (#4573).
   //     Queued CONTEXT files under `.gsd/milestones/*` are already sheltered
   //     in step 7 above, so they won't be swept into the stash.
+  // On Windows, SQLite holds mandatory file locks on the gsd.db WAL/SHM
+  // sidecars while the connection is open. `git stash --include-untracked`
+  // walks those files and fails with EBUSY (#4704). Close the DB before
+  // stashing so Windows releases the handles; reopen after. No-op on
+  // POSIX, where advisory locks don't block git.
+  const needsDbCycle = process.platform === "win32" && isDbAvailable();
+  const dbPathToReopen = needsDbCycle ? getDbPath() : null;
+  if (needsDbCycle) {
+    try {
+      closeDatabase();
+    } catch (err) {
+      logWarning("worktree", `pre-stash db close failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
   let stashed = false;
   try {
     const status = execFileSync("git", ["status", "--porcelain"], {
@@ -1741,6 +1788,14 @@ export function mergeMilestoneToMain(
     logWarning("worktree", `git stash failed: ${err instanceof Error ? err.message : String(err)}`);
   }
 
+  if (needsDbCycle && dbPathToReopen) {
+    try {
+      openDatabase(dbPathToReopen);
+    } catch (err) {
+      logWarning("worktree", `post-stash db reopen failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
   // 7b. Clean up stale merge state before attempting squash merge (#2912).
   // A leftover MERGE_HEAD (from a previous failed merge, libgit2 native path,
   // or interrupted operation) causes `git merge --squash` to refuse with

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

@@ -485,6 +485,11 @@ export function isAutoActive(): boolean {
   return s.active;
 }
 
+/** Test-only seam for validating auto-mode guards (#4704). Do not use in production code. */
+export function _setAutoActiveForTest(active: boolean): void {
+  s.active = active;
+}
+
 export function isAutoPaused(): boolean {
   return s.paused;
 }

package/src/resources/extensions/gsd/bootstrap/provider-error-resume.ts

@@ -12,6 +12,8 @@ type AutoResumeSnapshot = Pick<AutoDashboardData, "active" | "paused" | "stepMod
 
 export interface ProviderErrorResumeDeps {
   getSnapshot(): AutoResumeSnapshot;
+  resetTransientRetryState(): void;
+  resetSessionTimeoutState(): void;
   startAuto(
     ctx: ExtensionCommandContext,
     pi: ExtensionAPI,
@@ -23,6 +25,8 @@ export interface ProviderErrorResumeDeps {
 
 const defaultDeps: ProviderErrorResumeDeps = {
   getSnapshot: () => getAutoDashboardData(),
+  resetTransientRetryState,
+  resetSessionTimeoutState,
   startAuto,
 };
 
@@ -47,8 +51,8 @@ export async function resumeAutoAfterProviderDelay(
   // Reset retry counters before restarting — without this, counters
   // accumulate across pause/resume cycles and permanently lock out
   // auto-resume after their respective MAX thresholds.
-  resetTransientRetryState();
-  resetSessionTimeoutState();
+  deps.resetTransientRetryState();
+  deps.resetSessionTimeoutState();
 
   await deps.startAuto(
     ctx as ExtensionCommandContext,

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

@@ -43,6 +43,25 @@ import {
   validateFetchedContent,
 } from "../../workflow-install.js";
 
+/**
+ * Refuses interactive commands that mutate durable .gsd/ planning state while
+ * auto-mode holds the worktree. Returns true if the command was blocked and
+ * the caller should return immediately; false if it is safe to proceed.
+ *
+ * Auto-mode's squash merge performs a pre-merge dirty-tree check; concurrent
+ * writes by interactive commands between that check and the merge itself
+ * cause __dirty_working_tree__ failures (#4704).
+ */
+function requireNotAutoActive(commandName: string, ctx: ExtensionCommandContext): boolean {
+  if (!isAutoActive()) return false;
+  ctx.ui.notify(
+    `${commandName} cannot run while auto-mode is active.\n` +
+    `Stop auto-mode first with /gsd stop, then run ${commandName}.`,
+    "error",
+  );
+  return true;
+}
+
 // ─── Custom Workflow Subcommands ─────────────────────────────────────────
 
 const RESERVED_SUBCOMMANDS = new Set([
@@ -473,12 +492,14 @@ async function handleCustomWorkflow(
 export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
   // ── /gsd do — natural language routing (must be early to route to other commands) ──
   if (trimmed === "do" || trimmed.startsWith("do ")) {
+    if (requireNotAutoActive("/gsd do", ctx)) return true;
     const { handleDo } = await import("../../commands-do.js");
     await handleDo(trimmed.replace(/^do\s*/, "").trim(), ctx, pi);
     return true;
   }
   // ── Backlog management ──
   if (trimmed === "backlog" || trimmed.startsWith("backlog ")) {
+    if (requireNotAutoActive("/gsd backlog", ctx)) return true;
     const { handleBacklog } = await import("../../commands-backlog.js");
     await handleBacklog(trimmed.replace(/^backlog\s*/, "").trim(), ctx, pi);
     return true;
@@ -490,26 +511,22 @@ export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionComma
   }
 
   if (trimmed === "queue") {
+    if (requireNotAutoActive("/gsd queue", ctx)) return true;
     await showQueue(ctx, pi, projectRoot());
     return true;
   }
   if (trimmed === "discuss") {
+    if (requireNotAutoActive("/gsd discuss", ctx)) return true;
     await showDiscuss(ctx, pi, projectRoot());
     return true;
   }
   if (trimmed === "quick" || trimmed.startsWith("quick ")) {
-    if (isAutoActive()) {
-      ctx.ui.notify(
-        "/gsd quick cannot run while auto-mode is active.\n" +
-        "Stop auto-mode first with /gsd stop, then run /gsd quick.",
-        "error",
-      );
-      return true;
-    }
+    if (requireNotAutoActive("/gsd quick", ctx)) return true;
     await handleQuick(trimmed.replace(/^quick\s*/, "").trim(), ctx, pi);
     return true;
   }
   if (trimmed === "new-milestone") {
+    if (requireNotAutoActive("/gsd new-milestone", ctx)) return true;
     const basePath = projectRoot();
     const headlessContextPath = join(gsdRoot(basePath), "runtime", "headless-context.md");
     if (existsSync(headlessContextPath)) {
@@ -531,6 +548,7 @@ export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionComma
     return true;
   }
   if (trimmed === "park" || trimmed.startsWith("park ")) {
+    if (requireNotAutoActive("/gsd park", ctx)) return true;
     const basePath = projectRoot();
     const arg = trimmed.replace(/^park\s*/, "").trim();
     let targetId = arg;
@@ -556,6 +574,7 @@ export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionComma
     return true;
   }
   if (trimmed === "unpark" || trimmed.startsWith("unpark ")) {
+    if (requireNotAutoActive("/gsd unpark", ctx)) return true;
     const basePath = projectRoot();
     const arg = trimmed.replace(/^unpark\s*/, "").trim();
     let targetId = arg;

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

@@ -1,12 +1,21 @@
 import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
 
-function _require(name: string) {
+// 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: string): any {
   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 {
@@ -15,43 +24,107 @@ function _require(name: string) {
   }
 }
 
-export function withFileLockSync<T>(filePath: string, fn: () => T): T {
+export type OnLocked = "fail" | "skip";
+
+export interface FileLockOptions {
+  /**
+   * Behavior when the lock cannot be acquired after retries (ELOCKED).
+   * - "fail" (default): rethrow the ELOCKED error so the caller can react.
+   * - "skip": run fn() unlocked. Only choose this for best-effort writes
+   *   that genuinely tolerate contention (e.g. high-frequency audit appends
+   *   where dropping one entry is acceptable). Silent unlocked execution was
+   *   the legacy behavior and is a correctness hazard for shared state.
+   */
+  onLocked?: OnLocked;
+  /** proper-lockfile retries (default 5). */
+  retries?: number;
+  /** proper-lockfile stale threshold in ms (default 10000). */
+  stale?: number;
+}
+
+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: number): void {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function acquireLockSyncWithRetry(
+  lockfile: any,
+  filePath: string,
+  retries: number,
+  stale: number,
+): () => void {
+  let lastErr: any;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      return lockfile.lockSync(filePath, { stale });
+    } catch (err: any) {
+      lastErr = err;
+      if (err?.code !== "ELOCKED") throw err;
+      if (attempt < retries) sleepSync(SYNC_RETRY_DELAY_MS);
+    }
+  }
+  throw lastErr;
+}
+
+export function withFileLockSync<T>(
+  filePath: string,
+  fn: () => T,
+  opts: FileLockOptions = {},
+): T {
   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: OnLocked = opts.onLocked ?? "fail";
+
   try {
-    const release = lockfile.lockSync(filePath, { retries: 5, stale: 10000 });
+    const release = acquireLockSyncWithRetry(lockfile, filePath, retries, stale);
     try {
       return fn();
     } finally {
       release();
     }
   } catch (err: any) {
-    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<T>(filePath: string, fn: () => Promise<T> | T): Promise<T> {
+export async function withFileLock<T>(
+  filePath: string,
+  fn: () => Promise<T> | T,
+  opts: FileLockOptions = {},
+): Promise<T> {
   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: 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();
     } finally {
       await release();
     }
   } catch (err: any) {
-    if (err.code === "ELOCKED") {
+    if (err?.code === "ELOCKED" && onLocked === "skip") {
       return await fn();
     }
     throw err;

package/src/resources/extensions/gsd/git-service.ts

@@ -210,6 +210,7 @@ export interface PreMergeCheckResult {
  */
 export const RUNTIME_EXCLUSION_PATHS: readonly string[] = [
   ".gsd/activity/",
+  ".gsd/audit/",
   ".gsd/forensics/",
   ".gsd/runtime/",
   ".gsd/worktrees/",

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

@@ -26,6 +26,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/src/resources/extensions/gsd/guided-flow-queue.ts

@@ -18,6 +18,7 @@ import {
   resolveGsdRootFile, relGsdRootFile, relSliceFile,
 } 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 { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.js";
@@ -435,5 +436,7 @@ function syncProjectMdSequence(
   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/src/resources/extensions/gsd/journal.ts

@@ -12,8 +12,18 @@
  * - 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";
@@ -84,12 +94,27 @@ export interface JournalQueryFilters {
  * Never throws — all errors are silently caught.
  */
 export function emitJournalEvent(basePath: string, entry: JournalEntry): void {
+  // 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/src/resources/extensions/gsd/milestone-actions.ts

@@ -23,6 +23,21 @@ 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: string): void {
+  if (isAutoActive()) {
+    throw new Error(
+      `${action} cannot run while auto-mode is active. Stop auto-mode first with /gsd stop.`,
+    );
+  }
+}
 
 // ─── Park ──────────────────────────────────────────────────────────────────
 
@@ -32,6 +47,7 @@ import { logWarning } from "./workflow-logger.js";
  * Returns true if successfully parked, false if milestone not found or already parked.
  */
 export function parkMilestone(basePath: string, milestoneId: string, reason: string): boolean {
+  assertNotAutoActive("park milestone");
   const mDir = resolveMilestonePath(basePath, milestoneId);
   if (!mDir || !existsSync(mDir)) return false;
 
@@ -74,6 +90,7 @@ export function parkMilestone(basePath: string, milestoneId: string, reason: str
  * Returns true if successfully unparked, false if milestone not found or not parked.
  */
 export function unparkMilestone(basePath: string, milestoneId: string): boolean {
+  assertNotAutoActive("unpark milestone");
   const mDir = resolveMilestonePath(basePath, milestoneId);
   if (!mDir || !existsSync(mDir)) return false;
 
@@ -108,6 +125,7 @@ export function unparkMilestone(basePath: string, milestoneId: string): boolean
  * Returns true if successfully discarded, false if milestone not found.
  */
 export function discardMilestone(basePath: string, milestoneId: string): boolean {
+  assertNotAutoActive("discard milestone");
   const mDir = resolveMilestonePath(basePath, milestoneId);
   if (!mDir || !existsSync(mDir)) return false;
 

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

@@ -14,8 +14,9 @@
  * Manual: /gsd export --html
  */
 
-import { writeFileSync, readFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, basename } from 'node:path';
+import { atomicWriteSync } from './atomic-write.js';
 import { gsdRoot } from './paths.js';
 import { formatCost, formatTokenCount } from './metrics.js';
 import { formatDateShort, formatDuration } from '../shared/format-utils.js';
@@ -83,7 +84,7 @@ export function loadReportsIndex(basePath: string): ReportsIndex | null {
 function saveReportsIndex(basePath: string, index: ReportsIndex): void {
   const dir = reportsDir(basePath);
   mkdirSync(dir, { recursive: true });
-  writeFileSync(reportsIndexPath(basePath), JSON.stringify(index, null, 2) + '\n', 'utf-8');
+  atomicWriteSync(reportsIndexPath(basePath), JSON.stringify(index, null, 2) + '\n', 'utf-8');
 }
 
 // ─── Write a report snapshot ──────────────────────────────────────────────────
@@ -121,7 +122,7 @@ export function writeReportSnapshot(args: WriteReportSnapshotArgs): string {
   const filename = `${prefix}-${timestamp}.html`;
   const filePath = join(dir, filename);
 
-  writeFileSync(filePath, args.html, 'utf-8');
+  atomicWriteSync(filePath, args.html, 'utf-8');
 
   // Load or init registry
   const existing = loadReportsIndex(args.basePath);
@@ -170,7 +171,7 @@ export function writeReportSnapshot(args: WriteReportSnapshotArgs): string {
 
 export function regenerateHtmlIndex(basePath: string, index: ReportsIndex): void {
   const html = buildIndexHtml(index);
-  writeFileSync(reportsHtmlIndexPath(basePath), html, 'utf-8');
+  atomicWriteSync(reportsHtmlIndexPath(basePath), html, 'utf-8');
 }
 
 function buildIndexHtml(index: ReportsIndex): string {

package/src/resources/extensions/gsd/tests/auto-loop.test.ts

@@ -10,6 +10,7 @@ import {
   autoLoop,
   detectStuck,
   _resetPendingResolve,
+  _hasPendingResolveForTest,
   _setActiveSession,
   isSessionSwitchInFlight,
   type UnitResult,
@@ -379,6 +380,7 @@ test("runUnit cancels before dispatch when provider is not request-ready (#4555)
     /Provider anthropic is not request-ready/,
   );
   assert.equal(pi.calls.length, 0, "sendMessage must not be called when provider is not ready");
+  assert.equal(_hasPendingResolveForTest(), false, "provider cancellation must clear the pending resolver");
 });
 
 test("runUnit cancels before dispatch using currentUnitModel provider when set (#4555)", async () => {
@@ -1609,9 +1611,16 @@ test("auto-timeout-recovery.ts calls resolveAgentEnd instead of dispatchNextUnit
     !src.includes("await dispatchNextUnit"),
     "auto-timeout-recovery.ts must not call dispatchNextUnit",
   );
+  // After PR #4716, advance branches go through bumpAndResolveSynthetic()
+  // (which bumps the turn epoch and calls resolveAgentEnd atomically).
+  // Either direct resolveAgentEnd() or the helper satisfies the invariant:
+  // the loop must be re-iterated on timeout recovery.
+  const reIteratesLoop =
+    src.includes("resolveAgentEnd(") ||
+    src.includes("bumpAndResolveSynthetic(");
   assert.ok(
-    src.includes("resolveAgentEnd("),
-    "auto-timeout-recovery.ts must call resolveAgentEnd to re-iterate the loop on timeout recovery",
+    reIteratesLoop,
+    "auto-timeout-recovery.ts must call resolveAgentEnd (directly or via bumpAndResolveSynthetic) to re-iterate the loop on timeout recovery",
   );
 });
 

package/src/resources/extensions/gsd/tests/auto-mode-guards.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Regression tests for auto-mode guards (#4704 Tier 2 / #4712).
+ *
+ * Validates the defense-in-depth writer asserts in milestone-actions.ts —
+ * parkMilestone, unparkMilestone, and discardMilestone must refuse to run
+ * while auto-mode is active, regardless of the calling dispatch path.
+ */
+import { describe, test, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { parkMilestone, unparkMilestone, discardMilestone } from '../milestone-actions.ts';
+import { _setAutoActiveForTest } from '../auto.ts';
+
+function createFixture(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-guard-test-'));
+  const mDir = join(base, '.gsd', 'milestones', 'M001');
+  mkdirSync(mDir, { recursive: true });
+  writeFileSync(join(mDir, 'M001-ROADMAP.md'), '# M001\n', 'utf-8');
+  return base;
+}
+
+describe('auto-mode guards (milestone-actions)', () => {
+  afterEach(() => {
+    _setAutoActiveForTest(false);
+  });
+
+  test('parkMilestone throws when auto-mode is active', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(true);
+      assert.throws(
+        () => parkMilestone(base, 'M001', 'test'),
+        /auto-mode is active/,
+      );
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('unparkMilestone throws when auto-mode is active', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(true);
+      assert.throws(
+        () => unparkMilestone(base, 'M001'),
+        /auto-mode is active/,
+      );
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('discardMilestone throws when auto-mode is active', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(true);
+      assert.throws(
+        () => discardMilestone(base, 'M001'),
+        /auto-mode is active/,
+      );
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('parkMilestone proceeds normally when auto-mode is inactive', () => {
+    const base = createFixture();
+    try {
+      _setAutoActiveForTest(false);
+      const result = parkMilestone(base, 'M001', 'baseline');
+      assert.ok(result, 'park succeeds when auto is inactive');
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+});