gsd-pi 2.31.1-dev.ffe48ad → 2.31.2-dev.2453512

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

@@ -118,7 +118,7 @@ import {
   parseSliceBranch,
   setActiveMilestoneId,
 } from "./worktree.js";
-import { GitServiceImpl, type TaskCommitContext } from "./git-service.js";
+import { createGitService, type TaskCommitContext } from "./git-service.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
 import { formatGitError } from "./git-self-heal.js";
 import {
@@ -204,8 +204,7 @@ import type { CompletedUnit, CurrentUnit, UnitRouting, StartModel, PendingVerifi
 // ─────────────────────────────────────────────────────────────────────────────
 const s = new AutoSession();
 
-/** Throttle STATE.md rebuilds — at most once per 30 seconds */
-const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
+import { STATE_REBUILD_MIN_INTERVAL_MS } from "./auto-constants.js";
 
 export function shouldUseWorktreeIsolation(): boolean {
   const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
@@ -462,7 +461,7 @@ export async function stopAuto(ctx?: ExtensionContext, pi?: ExtensionAPI, reason
       try { autoCommitCurrentBranch(s.basePath, "stop", s.currentMilestoneId); } catch (e) { debugLog("stop-auto-commit-failed", { error: e instanceof Error ? e.message : String(e) }); }
       teardownAutoWorktree(s.originalBasePath, s.currentMilestoneId, { preserveBranch: true });
       s.basePath = s.originalBasePath;
-      s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+      s.gitService = createGitService(s.basePath);
       ctx?.ui.notify("Exited auto-worktree (branch preserved for resume).", "info");
     } catch (err) {
       ctx?.ui.notify(
@@ -626,12 +625,12 @@ export async function startAuto(
         if (existingWtPath) {
           const wtPath = enterAutoWorktree(s.originalBasePath, s.currentMilestoneId);
           s.basePath = wtPath;
-          s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+          s.gitService = createGitService(s.basePath);
           ctx.ui.notify(`Re-entered auto-worktree at ${wtPath}`, "info");
         } else {
           const wtPath = createAutoWorktree(s.originalBasePath, s.currentMilestoneId);
           s.basePath = wtPath;
-          s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+          s.gitService = createGitService(s.basePath);
           ctx.ui.notify(`Recreated auto-worktree at ${wtPath}`, "info");
         }
       } catch (err) {
@@ -834,6 +833,9 @@ export async function handleAgentEnd(
     // permanently stalled with no unit running and no watchdog set.
     if (s.pendingAgentEndRetry) {
       s.pendingAgentEndRetry = false;
+      // Clear gap watchdog from the previous cycle to prevent concurrent
+      // dispatch when the deferred handleAgentEnd calls dispatchNextUnit (#1272).
+      clearDispatchGapWatchdog();
       setImmediate(() => {
         handleAgentEnd(ctx, pi).catch((err) => {
           const msg = err instanceof Error ? err.message : String(err);
@@ -976,8 +978,12 @@ async function dispatchNextUnit(
     return;
   }
 
-  // Reentrancy guard
-  if (s.dispatching && s.skipDepth === 0) {
+  // Reentrancy guard — unconditional to prevent concurrent dispatch from
+  // gap watchdog or pendingAgentEndRetry during skip chains (#1272).
+  // Previously the guard was bypassed when skipDepth > 0, but the recursive
+  // skip chain's inner finally block resets s.dispatching = false before the
+  // outer call's finally runs, opening a window for concurrent entry.
+  if (s.dispatching) {
     debugLog("dispatchNextUnit reentrancy guard — another dispatch in progress, bailing");
     return;
   }
@@ -1124,7 +1130,7 @@ async function dispatchNextUnit(
       }
 
       s.basePath = s.originalBasePath;
-      s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+      s.gitService = createGitService(s.basePath);
       invalidateAllCaches();
 
       state = await deriveState(s.basePath);
@@ -1136,7 +1142,7 @@ async function dispatchNextUnit(
         try {
           const wtPath = createAutoWorktree(s.basePath, mid);
           s.basePath = wtPath;
-          s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+          s.gitService = createGitService(s.basePath);
           ctx.ui.notify(`Created auto-worktree for ${mid} at ${wtPath}`, "info");
         } catch (err) {
           ctx.ui.notify(
@@ -1176,7 +1182,7 @@ async function dispatchNextUnit(
             const roadmapContent = readFileSync(roadmapPath, "utf-8");
             const mergeResult = mergeMilestoneToMain(s.originalBasePath, s.currentMilestoneId, roadmapContent);
             s.basePath = s.originalBasePath;
-            s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+            s.gitService = createGitService(s.basePath);
             ctx.ui.notify(
               `Milestone ${ s.currentMilestoneId } merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
               "info",
@@ -1201,7 +1207,7 @@ async function dispatchNextUnit(
             if (roadmapPath) {
               const roadmapContent = readFileSync(roadmapPath, "utf-8");
               const mergeResult = mergeMilestoneToMain(s.basePath, s.currentMilestoneId, roadmapContent);
-              s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+              s.gitService = createGitService(s.basePath);
               ctx.ui.notify(
                 `Milestone ${ s.currentMilestoneId } merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
                 "info",
@@ -1279,7 +1285,7 @@ async function dispatchNextUnit(
         const roadmapContent = readFileSync(roadmapPath, "utf-8");
         const mergeResult = mergeMilestoneToMain(s.originalBasePath, s.currentMilestoneId, roadmapContent);
         s.basePath = s.originalBasePath;
-        s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+        s.gitService = createGitService(s.basePath);
         ctx.ui.notify(
           `Milestone ${ s.currentMilestoneId } merged to main.${mergeResult.pushed ? " Pushed to remote." : ""}`,
           "info",
@@ -1303,7 +1309,7 @@ async function dispatchNextUnit(
           if (roadmapPath) {
             const roadmapContent = readFileSync(roadmapPath, "utf-8");
             const mergeResult = mergeMilestoneToMain(s.basePath, s.currentMilestoneId, roadmapContent);
-            s.gitService = new GitServiceImpl(s.basePath, loadEffectiveGSDPreferences()?.preferences?.git ?? {});
+            s.gitService = createGitService(s.basePath);
             ctx.ui.notify(
               `Milestone ${ s.currentMilestoneId } merged (branch mode).${mergeResult.pushed ? " Pushed to remote." : ""}`,
               "info",
@@ -1449,15 +1455,18 @@ async function dispatchNextUnit(
   }
 
   if (dispatchResult.action !== "dispatch") {
-    await new Promise(r => setImmediate(r));
-    await dispatchNextUnit(ctx, pi);
+    // Defer re-dispatch to next microtask so s.dispatching is released first,
+    // preventing reentrancy guard bypass during concurrent entry (#1272).
+    setImmediate(() => dispatchNextUnit(ctx, pi).catch(err => {
+      ctx.ui.notify(`Deferred dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+      pauseAuto(ctx, pi).catch(() => {});
+    }));
     return;
   }
 
   unitType = dispatchResult.unitType;
   unitId = dispatchResult.unitId;
   prompt = dispatchResult.prompt;
-  let pauseAfterUatDispatch = dispatchResult.pauseAfterDispatch ?? false;
 
   // ── Pre-dispatch hooks ──
   const preDispatchResult = runPreDispatchHooks(unitType, unitId, prompt, s.basePath);
@@ -1469,8 +1478,10 @@ async function dispatchNextUnit(
   }
   if (preDispatchResult.action === "skip") {
     ctx.ui.notify(`Skipping ${unitType} ${unitId} (pre-dispatch hook).`, "info");
-    await new Promise(r => setImmediate(r));
-    await dispatchNextUnit(ctx, pi);
+    setImmediate(() => dispatchNextUnit(ctx, pi).catch(err => {
+      ctx.ui.notify(`Deferred dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+      pauseAuto(ctx, pi).catch(() => {});
+    }));
     return;
   }
   if (preDispatchResult.action === "replace") {
@@ -1501,9 +1512,16 @@ async function dispatchNextUnit(
     if (idempotencyResult.reason === "completed" || idempotencyResult.reason === "fallback-persisted" || idempotencyResult.reason === "phantom-loop-cleared" || idempotencyResult.reason === "evicted") {
       if (!s.active) return;
       s.skipDepth++;
-      await new Promise(r => setTimeout(r, idempotencyResult.reason === "phantom-loop-cleared" ? 50 : 150));
-      await dispatchNextUnit(ctx, pi);
-      s.skipDepth = Math.max(0, s.skipDepth - 1);
+      const skipDelay = idempotencyResult.reason === "phantom-loop-cleared" ? 50 : 150;
+      // Defer re-dispatch so s.dispatching is released first (#1272).
+      setTimeout(() => {
+        dispatchNextUnit(ctx, pi).catch(err => {
+          ctx.ui.notify(`Deferred skip-dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+          pauseAuto(ctx, pi).catch(() => {});
+        }).finally(() => {
+          s.skipDepth = Math.max(0, s.skipDepth - 1);
+        });
+      }, skipDelay);
       return;
     }
   } else if (idempotencyResult.action === "stop") {
@@ -1534,8 +1552,11 @@ async function dispatchNextUnit(
     return;
   }
   if (stuckResult.action === "recovered" && stuckResult.dispatchAgain) {
-    await new Promise(r => setImmediate(r));
-    await dispatchNextUnit(ctx, pi);
+    // Defer re-dispatch so s.dispatching is released first (#1272).
+    setImmediate(() => dispatchNextUnit(ctx, pi).catch(err => {
+      ctx.ui.notify(`Deferred recovery-dispatch failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+      pauseAuto(ctx, pi).catch(() => {});
+    }));
     return;
   }
 
@@ -1712,13 +1733,6 @@ async function dispatchNextUnit(
     { triggerTurn: true },
   );
 
-  if (pauseAfterUatDispatch) {
-    ctx.ui.notify(
-      "UAT requires human execution. Auto-mode will pause after this unit writes the result file.",
-      "info",
-    );
-    await pauseAuto(ctx, pi);
-  }
   } finally {
     s.dispatching = false;
   }
@@ -1788,6 +1802,15 @@ export {
 export function _getUnitConsecutiveSkips(): Map<string, number> { return s.unitConsecutiveSkips; }
 export function _resetUnitConsecutiveSkips(): void { s.unitConsecutiveSkips.clear(); }
 
+/**
+ * Test-only: expose dispatching / skipDepth state for reentrancy guard tests.
+ * Not part of the public API.
+ */
+export function _getDispatching(): boolean { return s.dispatching; }
+export function _setDispatching(v: boolean): void { s.dispatching = v; }
+export function _getSkipDepth(): number { return s.skipDepth; }
+export function _setSkipDepth(v: number): void { s.skipDepth = v; }
+
 /**
  * Dispatch a hook unit directly, bypassing normal pre-dispatch hooks.
  * Used for manual hook triggers via /gsd run-hook.
@@ -1874,8 +1897,6 @@ export async function dispatchHookUnit(
   ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
   ctx.ui.notify(`Running post-unit hook: ${hookName}`, "info");
 
-  console.log(`[dispatchHookUnit] Sending prompt of length ${hookPrompt.length}`);
-  console.log(`[dispatchHookUnit] Prompt preview: ${hookPrompt.substring(0, 200)}...`);
   pi.sendMessage(
     { customType: "gsd-auto", content: hookPrompt, display: true },
     { triggerTurn: true },

package/dist/resources/extensions/gsd/commands-workflow-templates.ts

@@ -19,8 +19,7 @@ import {
 } from "./workflow-templates.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { GitServiceImpl, runGit } from "./git-service.js";
-import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { createGitService, runGit } from "./git-service.js";
 import { isAutoActive, isAutoPaused } from "./auto.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
@@ -423,9 +422,8 @@ export async function handleStart(
 
   // ─── Create git branch (unless isolation: none) ─────────────────────────
 
-  const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
-  const git = new GitServiceImpl(basePath, gitPrefs);
-  const skipBranch = gitPrefs.isolation === "none";
+  const git = createGitService(basePath);
+  const skipBranch = git.prefs.isolation === "none";
   const slug = slugify(description || templateId);
   const branchName = `gsd/${templateId}/${slug}`;
   let branchCreated = false;

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

@@ -13,6 +13,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
 
 import {
   detectWorktreeName,
@@ -541,6 +542,14 @@ export class GitServiceImpl {
 
 }
 
+// ─── Factory ───────────────────────────────────────────────────────────────
+
+/** Create a GitServiceImpl with the current effective git preferences. */
+export function createGitService(basePath: string): GitServiceImpl {
+  const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
+  return new GitServiceImpl(basePath, gitPrefs);
+}
+
 // ─── Commit Type Inference ─────────────────────────────────────────────────
 
 /**

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

@@ -23,13 +23,6 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { loadQueueOrder, sortByQueueOrder, saveQueueOrder } from "./queue-order.js";
 import { findMilestoneIds, nextMilestoneId } from "./milestone-ids.js";
 
-// ─── Commit Instruction Helper (local copy — avoids circular dep) ───────────
-
-/** Build commit instruction for queue prompts. .gsd/ is managed externally and always gitignored. */
-function buildDocsCommitInstruction(_message: string): string {
-  return "Do not commit planning artifacts — .gsd/ is managed externally.";
-}
-
 // ─── Queue Entry Point ──────────────────────────────────────────────────────
 
 /**
@@ -207,7 +200,7 @@ export async function showQueueAdd(
     preamble,
     existingMilestonesContext: existingContext,
     inlinedTemplates: queueInlinedTemplates,
-    commitInstruction: buildDocsCommitInstruction("docs: queue <milestone list>"),
+    commitInstruction: "Do not commit planning artifacts — .gsd/ is managed externally.",
   });
 
   pi.sendMessage(

package/dist/resources/extensions/gsd/preferences-types.ts

@@ -86,6 +86,14 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "context_selection",
 ]);
 
+/** Canonical list of all dispatch unit types. */
+export const KNOWN_UNIT_TYPES = [
+  "research-milestone", "plan-milestone", "research-slice", "plan-slice",
+  "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
+  "run-uat", "complete-milestone",
+] as const;
+export type UnitType = (typeof KNOWN_UNIT_TYPES)[number];
+
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);
 
 export interface GSDSkillRule {

package/dist/resources/extensions/gsd/preferences-validation.ts

@@ -14,6 +14,7 @@ import { normalizeStringArray } from "../shared/mod.js";
 
 import {
   KNOWN_PREFERENCE_KEYS,
+  KNOWN_UNIT_TYPES,
   SKILL_ACTIONS,
   type WorkflowMode,
   type GSDPreferences,
@@ -239,11 +240,7 @@ export function validatePreferences(preferences: GSDPreferences): {
   if (preferences.post_unit_hooks && Array.isArray(preferences.post_unit_hooks)) {
     const validHooks: PostUnitHookConfig[] = [];
     const seenNames = new Set<string>();
-    const knownUnitTypes = new Set([
-      "research-milestone", "plan-milestone", "research-slice", "plan-slice",
-      "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
-      "run-uat", "complete-milestone",
-    ]);
+    const knownUnitTypes = new Set<string>(KNOWN_UNIT_TYPES);
     for (const hook of preferences.post_unit_hooks) {
       if (!hook || typeof hook !== "object") {
         errors.push("post_unit_hooks entry must be an object");
@@ -305,11 +302,7 @@ export function validatePreferences(preferences: GSDPreferences): {
   if (preferences.pre_dispatch_hooks && Array.isArray(preferences.pre_dispatch_hooks)) {
     const validPreHooks: PreDispatchHookConfig[] = [];
     const seenPreNames = new Set<string>();
-    const knownUnitTypes = new Set([
-      "research-milestone", "plan-milestone", "research-slice", "plan-slice",
-      "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
-      "run-uat", "complete-milestone",
-    ]);
+    const knownUnitTypes = new Set<string>(KNOWN_UNIT_TYPES);
     const validActions = new Set(["modify", "skip", "replace"]);
     for (const hook of preferences.pre_dispatch_hooks) {
       if (!hook || typeof hook !== "object") {

package/dist/resources/extensions/gsd/prompts/run-uat.md

@@ -17,11 +17,8 @@ If a `GSD Skill Preferences` block is present in system context, use it to decid
 ## UAT Instructions
 
 **UAT file:** `{{uatPath}}`
-**UAT type:** `{{uatType}}`
 **Result file to write:** `{{uatResultPath}}`
 
-### If UAT type is `artifact-driven`
-
 You are the test runner. Execute every check defined in `{{uatPath}}` directly:
 
 - Run shell commands with `bash`
@@ -46,7 +43,7 @@ Write `{{uatResultPath}}` with:
 ```markdown
 ---
 sliceId: {{sliceId}}
-uatType: {{uatType}}
+uatType: artifact-driven
 verdict: PASS | FAIL | PARTIAL
 date: <ISO 8601 timestamp>
 ---
@@ -68,44 +65,6 @@ date: <ISO 8601 timestamp>
 <any additional context, errors encountered, or follow-up items>
 ```
 
-### If UAT type is NOT `artifact-driven` (type is `{{uatType}}`)
-
-This UAT type requires human execution or live-runtime observation that you cannot perform mechanically. Your role is to surface it clearly for review.
-
-Write `{{uatResultPath}}` with:
-
-```markdown
----
-sliceId: {{sliceId}}
-uatType: {{uatType}}
-verdict: surfaced-for-human-review
-date: <ISO 8601 timestamp>
----
-
-# UAT Result — {{sliceId}}
-
-## UAT Type
-
-`{{uatType}}` — requires human execution or live-runtime verification.
-
-## Status
-
-Surfaced for human review. Auto-mode will pause after this unit so the UAT can be performed manually.
-
-## UAT File
-
-See `{{uatPath}}` for the full UAT specification and acceptance criteria.
-
-## Instructions for Human Reviewer
-
-Review `{{uatPath}}`, perform the described UAT steps, then update this file with:
-- The actual verdict (PASS / FAIL / PARTIAL)
-- Results for each check
-- Date completed
-
-Once updated, run `/gsd auto` to resume auto-mode.
-```
-
 ---
 
 **You MUST write `{{uatResultPath}}` before finishing.**

package/dist/resources/extensions/gsd/quick.ts

@@ -14,8 +14,7 @@ import { existsSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
-import { GitServiceImpl, runGit } from "./git-service.js";
-import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { createGitService, runGit } from "./git-service.js";
 
 // ─── Quick Task Helpers ───────────────────────────────────────────────────────
 
@@ -103,10 +102,9 @@ export async function handleQuick(
   const date = new Date().toISOString().split("T")[0];
 
   // Create git branch for the quick task (unless isolation: none)
-  const gitPrefs = loadEffectiveGSDPreferences()?.preferences?.git ?? {};
-  const git = new GitServiceImpl(basePath, gitPrefs);
+  const git = createGitService(basePath);
   const branchName = `gsd/quick/${taskNum}-${slug}`;
-  const skipBranch = gitPrefs.isolation === "none";
+  const skipBranch = git.prefs.isolation === "none";
 
   let branchCreated = false;
   if (!skipBranch) {

package/dist/resources/extensions/gsd/tests/auto-reentrancy-guard.test.ts

@@ -0,0 +1,127 @@
+/**
+ * auto-reentrancy-guard.test.ts — Tests for the unconditional reentrancy guard.
+ *
+ * Regression for #1272: auto-mode stuck-loop where gap watchdog or
+ * pendingAgentEndRetry could enter dispatchNextUnit concurrently during
+ * recursive skip chains because the reentrancy guard was bypassed when
+ * skipDepth > 0.
+ *
+ * The fix makes the guard unconditional (`if (s.dispatching)` without
+ * `&& s.skipDepth === 0`), and defers recursive re-dispatch via
+ * setImmediate/setTimeout so s.dispatching is released first.
+ */
+
+import {
+  _getDispatching,
+  _setDispatching,
+  _getSkipDepth,
+  _setSkipDepth,
+} from "../auto.ts";
+import { createTestContext } from "./test-helpers.ts";
+
+const { assertEq, assertTrue, report } = createTestContext();
+
+async function main(): Promise<void> {
+  // ─── Test-only accessors work ───────────────────────────────────────────
+  console.log("\n=== reentrancy guard: test accessors round-trip ===");
+  {
+    _setDispatching(false);
+    assertEq(_getDispatching(), false, "dispatching starts false");
+
+    _setDispatching(true);
+    assertEq(_getDispatching(), true, "dispatching set to true");
+
+    _setDispatching(false);
+    assertEq(_getDispatching(), false, "dispatching reset to false");
+  }
+
+  // ─── skipDepth accessors ────────────────────────────────────────────────
+  console.log("\n=== reentrancy guard: skipDepth accessors round-trip ===");
+  {
+    _setSkipDepth(0);
+    assertEq(_getSkipDepth(), 0, "skipDepth starts at 0");
+
+    _setSkipDepth(3);
+    assertEq(_getSkipDepth(), 3, "skipDepth set to 3");
+
+    _setSkipDepth(0);
+    assertEq(_getSkipDepth(), 0, "skipDepth reset to 0");
+  }
+
+  // ─── Guard blocks even when skipDepth > 0 (#1272 regression) ───────────
+  console.log("\n=== reentrancy guard: blocks when dispatching=true regardless of skipDepth ===");
+  {
+    // Simulate the scenario from #1272: dispatching=true + skipDepth>0
+    // The old guard (`if (s.dispatching && s.skipDepth === 0)`) would allow
+    // concurrent entry when skipDepth > 0. The fix makes the check
+    // unconditional on skipDepth.
+    _setDispatching(true);
+    _setSkipDepth(2);
+
+    // Verify dispatching is true — guard should block regardless of skipDepth
+    assertTrue(
+      _getDispatching() === true,
+      "dispatching flag is true during skip chain"
+    );
+
+    // The actual reentrancy guard in dispatchNextUnit checks:
+    //   if (s.dispatching) { return; }
+    // We verify the state that would trigger the guard:
+    const wouldBlock = _getDispatching(); // unconditional check
+    const wouldBlockOld = _getDispatching() && _getSkipDepth() === 0; // old check
+
+    assertTrue(wouldBlock === true, "new guard blocks when dispatching=true, skipDepth=2");
+    assertTrue(wouldBlockOld === false, "old guard WOULD NOT block when dispatching=true, skipDepth=2 (the bug)");
+
+    // Clean up
+    _setDispatching(false);
+    _setSkipDepth(0);
+  }
+
+  // ─── Guard allows entry when dispatching=false ──────────────────────────
+  console.log("\n=== reentrancy guard: allows entry when dispatching=false ===");
+  {
+    _setDispatching(false);
+    _setSkipDepth(0);
+    assertTrue(!_getDispatching(), "guard allows entry when dispatching=false, skipDepth=0");
+
+    _setDispatching(false);
+    _setSkipDepth(3);
+    assertTrue(!_getDispatching(), "guard allows entry when dispatching=false, skipDepth=3");
+
+    _setSkipDepth(0);
+  }
+
+  // ─── skipDepth does not affect guard decision (the fix) ─────────────────
+  console.log("\n=== reentrancy guard: skipDepth is irrelevant to guard decision ===");
+  {
+    for (const depth of [0, 1, 2, 5]) {
+      _setDispatching(true);
+      _setSkipDepth(depth);
+      assertTrue(
+        _getDispatching() === true,
+        `guard blocks at skipDepth=${depth} when dispatching=true`
+      );
+    }
+
+    for (const depth of [0, 1, 2, 5]) {
+      _setDispatching(false);
+      _setSkipDepth(depth);
+      assertTrue(
+        _getDispatching() === false,
+        `guard allows at skipDepth=${depth} when dispatching=false`
+      );
+    }
+
+    // Clean up
+    _setDispatching(false);
+    _setSkipDepth(0);
+  }
+
+  report();
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});