gsd-pi 2.77.0-dev.538325aea → 2.77.0-dev.eaa4973bc

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/guided-flow.ts

@@ -286,7 +286,7 @@ export function checkAutoStartAfterDiscuss(): boolean {
   }
 
   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;
 }

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/notifications.ts

@@ -4,7 +4,6 @@
 import { execFileSync } from "node:child_process";
 import type { NotificationPreferences } from "./types.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/index.js";
 import { sendRemoteNotification } from "../remote-questions/notify.js";
 
 export type NotifyLevel = "info" | "success" | "warning" | "error";
@@ -39,20 +38,33 @@ export function sendDesktopNotification(
 
   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) return;
-    execFileSync(command.file, command.args, { timeout: 3000, stdio: "ignore" });
-  } catch {
-    // Non-fatal — desktop notifications are best-effort
-  }
+  // 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;
+    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(

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 });
+    }
+  });
+});

package/src/resources/extensions/gsd/tests/cmux.test.ts

@@ -14,7 +14,7 @@ import {
   shouldPromptToEnableCmux,
 } from "../../cmux/index.ts";
 import { autoEnableCmuxPreferences } from "../commands-cmux.ts";
-import type { GSDState } from "../types.ts";
+import type { CmuxStateInput } from "../../shared/cmux-events.ts";
 
 test("detectCmuxEnvironment requires workspace, surface, and socket", () => {
   const detected = detectCmuxEnvironment(
@@ -146,15 +146,11 @@ describe("autoEnableCmuxPreferences", () => {
 });
 
 test("buildCmuxStatusLabel and progress prefer deepest active unit", () => {
-  const state: GSDState = {
-    activeMilestone: { id: "M001", title: "Milestone" },
-    activeSlice: { id: "S02", title: "Slice" },
-    activeTask: { id: "T03", title: "Task" },
+  const state: CmuxStateInput = {
+    activeMilestone: { id: "M001" },
+    activeSlice: { id: "S02" },
+    activeTask: { id: "T03" },
     phase: "executing",
-    recentDecisions: [],
-    blockers: [],
-    nextAction: "Keep going",
-    registry: [],
     progress: {
       milestones: { done: 0, total: 1 },
       slices: { done: 1, total: 3 },

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

@@ -52,7 +52,7 @@ test("withFileLock: executes callback when file does not exist", async () => {
   }
 });
 
-test("withFileLockSync: falls back to unlocked callback on ELOCKED", () => {
+test("withFileLockSync: throws ELOCKED by default (no silent fallback)", () => {
   if (!hasProperLockfile() || process.platform === "win32") {
     return;
   }
@@ -65,19 +65,56 @@ test("withFileLockSync: falls back to unlocked callback on ELOCKED", () => {
   const release = lockfile.lockSync(filePath, { retries: 0, stale: 10000 });
   try {
     let called = 0;
-    const result = withFileLockSync(filePath, () => {
-      called++;
-      return "fallback-ok";
-    });
+    assert.throws(
+      () => {
+        withFileLockSync(
+          filePath,
+          () => {
+            called++;
+            return "should-not-return";
+          },
+          { retries: 0 },
+        );
+      },
+      (err: any) => err?.code === "ELOCKED",
+    );
+    assert.equal(called, 0, "callback must not run when lock cannot be acquired");
+  } finally {
+    release();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("withFileLockSync: onLocked=\"skip\" runs callback unlocked on ELOCKED", () => {
+  if (!hasProperLockfile() || process.platform === "win32") {
+    return;
+  }
+
+  const lockfile = require("proper-lockfile");
+  const dir = mkdtempSync(join(tmpdir(), "gsd-file-lock-test-"));
+  const filePath = join(dir, "locked.jsonl");
+  writeFileSync(filePath, "{}\n", "utf-8");
+
+  const release = lockfile.lockSync(filePath, { retries: 0, stale: 10000 });
+  try {
+    let called = 0;
+    const result = withFileLockSync(
+      filePath,
+      () => {
+        called++;
+        return "fallback-ok";
+      },
+      { retries: 0, onLocked: "skip" },
+    );
     assert.equal(result, "fallback-ok");
-    assert.equal(called, 1, "callback should run even when lock acquisition fails");
+    assert.equal(called, 1, "callback should run when onLocked is skip");
   } finally {
     release();
     rmSync(dir, { recursive: true, force: true });
   }
 });
 
-test("withFileLock: falls back to unlocked callback on ELOCKED", async () => {
+test("withFileLock: throws ELOCKED by default (no silent fallback)", async () => {
   if (!hasProperLockfile() || process.platform === "win32") {
     return;
   }
@@ -90,12 +127,49 @@ test("withFileLock: falls back to unlocked callback on ELOCKED", async () => {
   const release = await lockfile.lock(filePath, { retries: 0, stale: 10000 });
   try {
     let called = 0;
-    const result = await withFileLock(filePath, async () => {
-      called++;
-      return "fallback-ok";
-    });
+    await assert.rejects(
+      async () => {
+        await withFileLock(
+          filePath,
+          async () => {
+            called++;
+            return "should-not-return";
+          },
+          { retries: 0 },
+        );
+      },
+      (err: any) => err?.code === "ELOCKED",
+    );
+    assert.equal(called, 0, "callback must not run when lock cannot be acquired");
+  } finally {
+    await release();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("withFileLock: onLocked=\"skip\" runs callback unlocked on ELOCKED", async () => {
+  if (!hasProperLockfile() || process.platform === "win32") {
+    return;
+  }
+
+  const lockfile = require("proper-lockfile");
+  const dir = mkdtempSync(join(tmpdir(), "gsd-file-lock-test-"));
+  const filePath = join(dir, "locked.jsonl");
+  writeFileSync(filePath, "{}\n", "utf-8");
+
+  const release = await lockfile.lock(filePath, { retries: 0, stale: 10000 });
+  try {
+    let called = 0;
+    const result = await withFileLock(
+      filePath,
+      async () => {
+        called++;
+        return "fallback-ok";
+      },
+      { retries: 0, onLocked: "skip" },
+    );
     assert.equal(result, "fallback-ok");
-    assert.equal(called, 1, "callback should run even when lock acquisition fails");
+    assert.equal(called, 1, "callback should run when onLocked is skip");
   } finally {
     await release();
     rmSync(dir, { recursive: true, force: true });