gsd-pi 2.78.1-dev.e9d88a536 → 2.78.1-dev.eccf86e27

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

@@ -22,8 +22,14 @@ import type { GSDState } from "./types.js";
 import {
   assessInterruptedSession,
   readPausedSessionMetadata,
+  PAUSED_SESSION_KV_KEY,
   type InterruptedSessionAssessment,
+  type PausedSessionMetadata,
 } from "./interrupted-session.js";
+import {
+  setRuntimeKv,
+  deleteRuntimeKv,
+} from "./db/runtime-kv.js";
 import { getManifestStatus } from "./files.js";
 export { inlinePriorMilestoneSummary } from "./files.js";
 import { collectSecretsFromManifest } from "../get-secrets-from-user.js";
@@ -244,6 +250,7 @@ import type {
   CurrentUnit,
   UnitRouting,
   StartModel,
+  AutoSession,
 } from "./auto/session.js";
 export {
   STUB_RECOVERY_THRESHOLD,
@@ -256,6 +263,10 @@ export type {
 } from "./auto/session.js";
 import { autoSession as s } from "./auto-runtime-state.js";
 import { gsdHome } from "./gsd-home.js";
+import { createWorkspace, scopeMilestone } from "./workspace.js";
+import { registerAutoWorker, markWorkerStopping } from "./db/auto-workers.js";
+import { releaseMilestoneLease } from "./db/milestone-leases.js";
+import { normalizeRealPath } from "./paths.js";
 
 // ── ENCAPSULATION INVARIANT ─────────────────────────────────────────────────
 // ALL mutable auto-mode state lives in the AutoSession class (auto/session.ts).
@@ -273,6 +284,28 @@ import { gsdHome } from "./gsd-home.js";
 /** Throttle STATE.md rebuilds — at most once per 30 seconds */
 const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
 
+/**
+ * Phase B — register this auto-mode process in the workers table so other
+ * workers and janitors can detect liveness via heartbeat. Best-effort: if
+ * the DB is unavailable (e.g. fresh project before init) we skip registration
+ * silently rather than blocking session start.
+ */
+function registerAutoWorkerForSession(session: AutoSession): void {
+  if (session.workerId) return; // already registered (e.g. resume re-runs)
+  try {
+    const projectRootRealpath = normalizeRealPath(
+      session.scope?.workspace.projectRoot
+        ?? (session.originalBasePath || session.basePath),
+    );
+    session.workerId = registerAutoWorker({ projectRootRealpath });
+  } catch (err) {
+    debugLog("autoLoop", {
+      phase: "register-worker-failed",
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
 function captureProjectRootEnv(projectRoot: string): void {
   if (!s.projectRootEnvCaptured) {
     s.hadProjectRootEnv = Object.prototype.hasOwnProperty.call(process.env, "GSD_PROJECT_ROOT");
@@ -324,6 +357,32 @@ function restoreMilestoneLockEnv(): void {
   s.milestoneLockEnvCaptured = false;
 }
 
+/**
+ * Rebuild s.scope from the current s.basePath / s.originalBasePath / s.currentMilestoneId.
+ *
+ * Pass the worktree path as rawPath when entering a worktree so createWorkspace
+ * can detect the worktree layout and set mode="worktree". When no worktree is
+ * active, rawPath should equal the project root.
+ *
+ * Clears s.scope when milestoneId is absent — scope is only meaningful when a
+ * milestone is active.
+ *
+ * TODO(C8): remove basePath/originalBasePath once all readers use s.scope.
+ */
+function rebuildScope(rawPath: string, milestoneId: string | null): void {
+  if (!milestoneId) {
+    s.scope = null;
+    return;
+  }
+  try {
+    const workspace = createWorkspace(rawPath);
+    s.scope = scopeMilestone(workspace, milestoneId);
+  } catch {
+    // Non-fatal — scope is additive. Existing readers still use basePath.
+    s.scope = null;
+  }
+}
+
 function normalizeSessionFilePath(raw: unknown): string | null {
   if (typeof raw !== "string") return null;
   const trimmed = raw.trim();
@@ -509,6 +568,26 @@ export function _setAutoActiveForTest(active: boolean): void {
   s.active = active;
 }
 
+/**
+ * Test-only seam: emit the missing-worktree warning exactly as the resume path
+ * does.  Allows unit tests to verify the warning is produced without
+ * bootstrapping the full auto-mode entry point.  Do not use in production code.
+ */
+export function _warnIfWorktreeMissingForTest(
+  worktreePath: string | null | undefined,
+  milestoneId: string,
+): boolean {
+  if (worktreePath && !existsSync(worktreePath)) {
+    logWarning(
+      "session",
+      `Worktree was expected at ${worktreePath} but is missing. Continuing in project-root mode. To restart with a fresh worktree, run /gsd-debug or recreate the milestone.`,
+      { file: "auto.ts", milestoneId },
+    );
+    return true;
+  }
+  return false;
+}
+
 export function isAutoPaused(): boolean {
   return s.paused;
 }
@@ -864,6 +943,21 @@ export async function stopAuto(
       debugLog("stop-cleanup-locks", { error: e instanceof Error ? e.message : String(e) });
     }
 
+    // ── Step 1b: Coordination cleanup (Phase B) ──
+    // Release any active milestone lease so other workers don't have to
+    // wait for TTL expiry, then mark this worker as stopping. Best-effort:
+    // DB unavailability or stale state must not block shutdown.
+    try {
+      if (s.workerId && s.currentMilestoneId && s.milestoneLeaseToken) {
+        releaseMilestoneLease(s.workerId, s.currentMilestoneId, s.milestoneLeaseToken);
+      }
+      if (s.workerId) {
+        markWorkerStopping(s.workerId);
+      }
+    } catch (e) {
+      debugLog("stop-cleanup-coordination", { error: e instanceof Error ? e.message : String(e) });
+    }
+
     // ── Step 1b: Flush queued follow-up messages (#3512) ──
     // Late async notifications (async_job_result, gsd-auto-wrapup) can trigger
     // extra LLM turns after stop. Flush them the same way run-unit.ts does.
@@ -1048,11 +1142,11 @@ export async function stopAuto(
     }
 
     // ── Step 12: Remove paused-session metadata (#1383) ──
+    // Phase C pt 2: deleteRuntimeKv replaces unlinkSync(paused-session.json).
     try {
-      const pausedPath = join(gsdRoot(s.originalBasePath || s.basePath), "runtime", "paused-session.json");
-      if (existsSync(pausedPath)) unlinkSync(pausedPath);
+      deleteRuntimeKv("global", "", PAUSED_SESSION_KV_KEY);
     } catch (err) { /* non-fatal */
-      logWarning("engine", `file unlink failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+      logWarning("engine", `paused-session DB delete failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
 
     // ── Step 13: Restore original model + thinking (before reset clears IDs) ──
@@ -1153,10 +1247,12 @@ export async function pauseAuto(
   s.pausedSessionFile = normalizeSessionFilePath(ctx?.sessionManager?.getSessionFile() ?? null);
 
   // Persist paused-session metadata so resume survives /exit (#1383).
-  // The fresh-start bootstrap checks for this file and restores worktree context.
+  // Phase C pt 2: persisted to runtime_kv (global scope, key
+  // PAUSED_SESSION_KV_KEY) instead of runtime/paused-session.json. The
+  // fresh-start bootstrap below reads from the same key.
   try {
-    const pausedMeta = {
-      milestoneId: s.currentMilestoneId,
+    const pausedMeta: PausedSessionMetadata = {
+      milestoneId: s.currentMilestoneId ?? undefined,
       worktreePath: isInAutoWorktree(s.basePath) ? s.basePath : null,
       originalBasePath: s.originalBasePath,
       stepMode: s.stepMode,
@@ -1164,20 +1260,15 @@ export async function pauseAuto(
       sessionFile: s.pausedSessionFile,
       unitType: s.currentUnit?.type ?? undefined,
       unitId: s.currentUnit?.id ?? undefined,
-      activeEngineId: s.activeEngineId,
+      activeEngineId: s.activeEngineId ?? undefined,
       activeRunDir: s.activeRunDir,
       autoStartTime: s.autoStartTime,
       milestoneLock: s.sessionMilestoneLock ?? undefined,
     };
-    const runtimeDir = join(gsdRoot(s.originalBasePath || s.basePath), "runtime");
-    atomicWriteSync(
-      join(runtimeDir, "paused-session.json"),
-      JSON.stringify(pausedMeta, null, 2),
-      "utf-8",
-    );
+    setRuntimeKv("global", "", PAUSED_SESSION_KV_KEY, pausedMeta);
   } catch (err) {
     // Non-fatal — resume will still work via full bootstrap, just without worktree context
-    logWarning("engine", `paused-session file write failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+    logWarning("engine", `paused-session DB write failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
   }
 
   // Close out the current unit so its runtime record doesn't stay at "dispatched"
@@ -1460,8 +1551,10 @@ export async function startAuto(
     ctx.ui.notify("Recovered unfinished migration (.gsd.migrating → .gsd).", "info");
   }
 
-  const freshStartAssessment = interruptedAssessment
-    ?? await assessInterruptedSession(base);
+  const freshStartAssessment = await (interruptedAssessment
+    ?? (() => {
+      return ensureDbOpen(base).then(() => assessInterruptedSession(base));
+    })());
 
   if (freshStartAssessment.classification === "running") {
     const pid = freshStartAssessment.lock?.pid;
@@ -1476,10 +1569,20 @@ export async function startAuto(
 
   // If resuming from paused state, just re-activate and dispatch next unit.
   // Check persisted paused-session first (#1383) — survives /exit.
+  // Phase C pt 2: persisted in runtime_kv (global scope) instead of
+  // runtime/paused-session.json. The `clearPausedSession` helper
+  // replaces every prior unlinkSync(pausedPath) call.
+  const clearPausedSession = (logTag: string): void => {
+    try {
+      deleteRuntimeKv("global", "", PAUSED_SESSION_KV_KEY);
+    } catch (err) {
+      logWarning("session", `${logTag}: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
+    }
+  };
+
   if (!s.paused) {
     try {
       const meta = freshStartAssessment.pausedSession ?? readPausedSessionMetadata(base);
-      const pausedPath = join(gsdRoot(base), "runtime", "paused-session.json");
       if (meta?.activeEngineId && meta.activeEngineId !== "dev") {
         // Custom workflow resume — restore engine state
         s.activeEngineId = meta.activeEngineId;
@@ -1489,11 +1592,6 @@ export async function startAuto(
         s.autoStartTime = meta.autoStartTime || Date.now();
         s.sessionMilestoneLock = meta.milestoneLock ?? null;
         s.paused = true;
-        try { unlinkSync(pausedPath); } catch (e) {
-          if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
-            logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" });
-          }
-        }
         ctx.ui.notify(
           `Resuming paused custom workflow${meta.activeRunDir ? ` (${meta.activeRunDir})` : ""}.`,
           "info",
@@ -1534,11 +1632,7 @@ export async function startAuto(
             }
           }
           if (!mDir || summaryIsTerminal) {
-            try { unlinkSync(pausedPath); } catch (err) {
-              if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
-                logWarning("session", `pause file cleanup failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
-              }
-            }
+            clearPausedSession("paused-session DB cleanup failed (milestone gone/complete)");
             ctx.ui.notify(
               `Paused milestone ${meta.milestoneId} is ${!mDir ? "missing" : "already complete"}. Starting fresh.`,
               "info",
@@ -1553,22 +1647,31 @@ export async function startAuto(
             s.autoStartTime = meta.autoStartTime || Date.now();
             s.sessionMilestoneLock = meta.milestoneLock ?? null;
             s.paused = true;
-            try { unlinkSync(pausedPath); } catch (e) {
-              if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
-                logWarning("session", `pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" });
+            // Build scope from persisted state. Use worktreePath when present and
+            // still on disk so mode is detected correctly; fall back to project root.
+            {
+              const persistedWorktreePath = meta.worktreePath ?? null;
+              if (persistedWorktreePath && !existsSync(persistedWorktreePath)) {
+                logWarning(
+                  "session",
+                  `Worktree was expected at ${persistedWorktreePath} but is missing. Continuing in project-root mode. To restart with a fresh worktree, run /gsd-debug or recreate the milestone.`,
+                  { file: "auto.ts", milestoneId: meta.milestoneId ?? "" },
+                );
               }
+              const rawForScope = (persistedWorktreePath && existsSync(persistedWorktreePath))
+                ? persistedWorktreePath
+                : (s.originalBasePath || base);
+              rebuildScope(rawForScope, s.currentMilestoneId);
             }
             ctx.ui.notify(
               `Resuming paused session for ${meta.milestoneId}${meta.worktreePath && existsSync(meta.worktreePath) ? ` (worktree)` : ""}.`,
               "info",
             );
           }
-        } else if (existsSync(pausedPath)) {
-          try { unlinkSync(pausedPath); } catch (e) {
-            if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
-              logWarning("session", `stale pause file cleanup failed: ${e instanceof Error ? e.message : String(e)}`, { file: "auto.ts" });
-            }
-          }
+        } else if (meta) {
+          // Stale paused-session metadata that the assessment chose not to
+          // resume — clean it up so the next bootstrap starts fresh.
+          clearPausedSession("stale paused-session DB cleanup failed");
         }
       }
     } catch (err) {
@@ -1637,10 +1740,19 @@ export async function startAuto(
     // session (e.g. isolation mode changed, detectWorktreeName differs across
     // process restarts).  We guard with existsSync so a stale or deleted
     // worktree directory safely falls back to the project root.
-    const resumeWorktreePath = freshStartAssessment.pausedSession?.worktreePath;
+    const resumeWorktreePath = freshStartAssessment.pausedSession?.worktreePath ?? null;
+    if (resumeWorktreePath && !existsSync(resumeWorktreePath)) {
+      logWarning(
+        "session",
+        `Worktree was expected at ${resumeWorktreePath} but is missing. Continuing in project-root mode. To restart with a fresh worktree, run /gsd-debug or recreate the milestone.`,
+        { file: "auto.ts", milestoneId: s.currentMilestoneId ?? "" },
+      );
+    }
     if (resumeWorktreePath && existsSync(resumeWorktreePath)) {
       s.basePath = resumeWorktreePath;
     }
+    // Rebuild scope now that s.basePath reflects the actual worktree (or project root).
+    rebuildScope(s.basePath, s.currentMilestoneId);
     // Ensure the workflow-logger audit log is pinned to the project root
     // even when auto-mode is entered via a path that bypasses the
     // bootstrap/dynamic-tools ensureDbOpen() → setLogBasePath() chain
@@ -1669,6 +1781,8 @@ export async function startAuto(
       buildResolver().enterMilestone(s.currentMilestoneId, {
         notify: ctx.ui.notify.bind(ctx.ui),
       });
+      // s.basePath may have been updated to a worktree path by enterMilestone.
+      rebuildScope(s.basePath, s.currentMilestoneId);
     }
 
     registerSigtermHandler(lockBase());
@@ -1737,19 +1851,23 @@ export async function startAuto(
       s.pausedSessionFile = null;
     }
 
+    captureProjectRootEnv(s.originalBasePath || s.basePath);
+    registerAutoWorkerForSession(s);
     updateSessionLock(
       lockBase(),
       "resuming",
       s.currentMilestoneId ?? "unknown",
     );
-    writeLock(
-      lockBase(),
-      "resuming",
-      s.currentMilestoneId ?? "unknown",
-    );
+    if (s.workerId) {
+      writeLock(
+        lockBase(),
+        "resuming",
+        s.currentMilestoneId ?? "unknown",
+      );
+      clearPausedSession("paused-session DB cleanup failed (resume activation)");
+    }
     pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", level: "progress" });
 
-    captureProjectRootEnv(s.originalBasePath || s.basePath);
     startAutoCommandPolling(s.basePath);
     await runAutoLoopWithUok({
       ctx,
@@ -1783,7 +1901,12 @@ export async function startAuto(
   );
   if (!ready) return;
 
+  // Build scope after bootstrap has populated s.basePath / s.originalBasePath /
+  // s.currentMilestoneId (including worktree setup inside bootstrapAutoSession).
+  rebuildScope(s.basePath, s.currentMilestoneId);
+
   captureProjectRootEnv(s.originalBasePath || s.basePath);
+  registerAutoWorkerForSession(s);
   try {
     pi.events.emit(CMUX_CHANNELS.SIDEBAR, { action: "sync" as const, preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, state: await deriveState(s.basePath) });
   } catch (err) {

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -115,7 +115,7 @@ export async function handleAgentEnd(
   }
 
   if (checkAutoStartAfterDiscuss()) {
-    clearDiscussionFlowState();
+    clearDiscussionFlowState(resolveAgentEndBasePath() ?? process.cwd());
     return;
   }
 

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -76,7 +76,7 @@ export function registerHooks(
       const { initHealthWidget } = await import("../health-widget.js");
       initHealthWidget(ctx);
     }
-    resetWriteGateState();
+    resetWriteGateState(process.cwd());
     resetToolCallLoopGuard();
     approvalQuestionAbortInFlight = false;
     await resetAskUserQuestionsTurnCache();
@@ -126,10 +126,10 @@ export function registerHooks(
   pi.on("session_switch", async (_event, ctx) => {
     initNotificationStore(process.cwd());
     installNotifyInterceptor(ctx);
-    resetWriteGateState();
+    resetWriteGateState(process.cwd());
     resetToolCallLoopGuard();
     await resetAskUserQuestionsTurnCache();
-    clearDiscussionFlowState();
+    clearDiscussionFlowState(process.cwd());
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
     // Skip MCP auto-prep when running inside an auto-worktree. The worktree
@@ -155,12 +155,13 @@ export function registerHooks(
     const { getEcosystemReadyPromise } = await import("../ecosystem/loader.js");
     await getEcosystemReadyPromise();
 
+    const beforeAgentBasePath = process.cwd();
     const pendingApprovalGate = getPendingGate();
     if (pendingApprovalGate && isExplicitApprovalResponse(event.prompt, pendingApprovalGate)) {
-      markApprovalGateVerified(pendingApprovalGate);
+      markApprovalGateVerified(pendingApprovalGate, beforeAgentBasePath);
       const milestoneId = extractDepthVerificationMilestoneId(pendingApprovalGate);
-      if (milestoneId) markDepthVerified(milestoneId);
-      clearPendingGate();
+      if (milestoneId) markDepthVerified(milestoneId, beforeAgentBasePath);
+      clearPendingGate(beforeAgentBasePath);
     }
 
     // GSD's own context injection (existing behavior — unchanged).
@@ -346,7 +347,7 @@ export function registerHooks(
     if (!shouldPauseForUserApprovalQuestion(unitType, [event.message])) return;
 
     const gateId = approvalGateIdForUnit(unitType, unitId);
-    if (gateId) setPendingGate(gateId);
+    if (gateId) setPendingGate(gateId, process.cwd());
 
     approvalQuestionAbortInFlight = true;
     ctx.ui.notify(
@@ -393,7 +394,7 @@ export function registerHooks(
       const questions: any[] = (event.input as any)?.questions ?? [];
       const questionId = questions.find((question) => typeof question?.id === "string" && isGateQuestionId(question.id))?.id;
       if (typeof questionId === "string") {
-        setPendingGate(questionId);
+        setPendingGate(questionId, discussionBasePath);
       }
     }
 
@@ -555,7 +556,8 @@ export function registerHooks(
     }
     const toolName = canonicalToolName(event.toolName);
     if (toolName !== "ask_user_questions") return;
-    const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
+    const basePath = process.cwd();
+    const milestoneId = await getDiscussionMilestoneIdFor(basePath);
     const queueActive = isQueuePhaseActive();
 
     const details = event.details as any;
@@ -569,8 +571,13 @@ export function registerHooks(
     const currentPendingGate = getPendingGate();
     if (currentPendingGate) {
       if (details?.cancelled || !details?.response) {
-        // Gate stays pending. Return a hard instruction as the tool result so
-        // the model cannot reinterpret a cancelled prompt as prior approval.
+        // Gate stays pending. Direct the agent to the most reliable recovery
+        // path — re-calling ask_user_questions with the same gate id — without
+        // misrepresenting the plain-text path. The plain-text path also works
+        // (isExplicitApprovalResponse on the next before_agent_start clears
+        // the gate when the user replies with an approval keyword), but the
+        // structured re-ask is more deterministic and gives the user a clear UI.
+        resetToolCallLoopGuard();
         return {
           content: [{
             type: "text" as const,
@@ -578,8 +585,8 @@ export function registerHooks(
               `HARD BLOCK: approval gate "${currentPendingGate}" is still pending.`,
               "No user response was received for the confirmation question.",
               "Do not infer approval from earlier or prior messages.",
-              "Do not proceed, write files, save artifacts, or call more tools.",
-              "Ask the user to confirm in plain chat, then stop and wait for their next message.",
+              "Do not proceed, write files, save artifacts, or call other tools.",
+              `Re-call ask_user_questions with the same gate question id ("${currentPendingGate}") and wait for the user's response.`,
             ].join(" "),
           }],
         };
@@ -588,10 +595,10 @@ export function registerHooks(
         if (pendingQuestion) {
           const answer = details.response?.answers?.[currentPendingGate];
           if (isDepthConfirmationAnswer(answer?.selected, pendingQuestion.options)) {
-            markApprovalGateVerified(currentPendingGate);
+            markApprovalGateVerified(currentPendingGate, basePath);
             const milestoneIdFromGate = extractDepthVerificationMilestoneId(currentPendingGate);
-            if (milestoneIdFromGate) markDepthVerified(milestoneIdFromGate);
-            clearPendingGate();
+            if (milestoneIdFromGate) markDepthVerified(milestoneIdFromGate, basePath);
+            clearPendingGate(basePath);
           }
         }
       }
@@ -607,9 +614,9 @@ export function registerHooks(
         const inferredMilestoneId = extractDepthVerificationMilestoneId(question.id) ?? milestoneId;
         if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
           if (currentPendingGate && question.id !== currentPendingGate) break;
-          markApprovalGateVerified(question.id);
-          markDepthVerified(inferredMilestoneId);
-          clearPendingGate();
+          markApprovalGateVerified(question.id, basePath);
+          markDepthVerified(inferredMilestoneId, basePath);
+          clearPendingGate(basePath);
         }
         break;
       }
@@ -617,8 +624,6 @@ export function registerHooks(
 
     if (!milestoneId && !queueActive) return;
     if (!milestoneId) return;
-
-    const basePath = process.cwd();
     const milestoneDir = resolveMilestonePath(basePath, milestoneId);
     if (!milestoneDir) return;
 

package/src/resources/extensions/gsd/bootstrap/tests/write-gate-basepath.test.ts

@@ -0,0 +1,103 @@
+// GSD-2 write-gate bootstrap — regression test for required basePath (commit A3)
+//
+// Verifies that persistWriteGateSnapshot / loadWriteGateSnapshot are pinned to
+// the basePath argument and do not silently fall back to process.cwd(). The
+// underlying bug: both functions defaulted `basePath = process.cwd()`, so a
+// persist in cwd-A followed by a chdir to cwd-B and a load (which also
+// defaulted to process.cwd(), now cwd-B) missed the persisted file entirely —
+// the depth-verification state became invisible across cwd boundaries.
+
+import { test, describe, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  markDepthVerified,
+  loadWriteGateSnapshot,
+  clearDiscussionFlowState,
+} from "../write-gate.js";
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function makeTempDir(): string {
+  return mkdtempSync(join(tmpdir(), "wg-basepath-test-"));
+}
+
+// Save and restore process.cwd() across tests to avoid cross-test pollution.
+let originalCwd: string;
+before(() => {
+  originalCwd = process.cwd();
+});
+after(() => {
+  if (process.cwd() !== originalCwd) {
+    process.chdir(originalCwd);
+  }
+});
+
+// ─── Scenario: persist with basePath=A, chdir, load with basePath=A ─────────
+//
+// This is the exact failure mode from the bug: persist used process.cwd() and
+// load used process.cwd(), and they resolved to different directories after a
+// chdir.  With the fix, both calls receive an explicit basePath so cwd changes
+// have no effect.
+
+describe("write-gate basePath regression", () => {
+  let baseDirA: string;
+  let baseDirB: string;
+
+  before(() => {
+    baseDirA = makeTempDir();
+    baseDirB = makeTempDir();
+  });
+
+  after(() => {
+    // Restore cwd before cleanup to avoid issues on Windows.
+    process.chdir(originalCwd);
+    rmSync(baseDirA, { recursive: true, force: true });
+    rmSync(baseDirB, { recursive: true, force: true });
+  });
+
+  test("snapshot persisted to basePath=A is readable after chdir to basePath=B", (t) => {
+    // Arrange: enable persistence (the default when env var is not set to "0"/"false").
+    const prev = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    t.after(() => {
+      if (prev === undefined) {
+        delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+      } else {
+        process.env.GSD_PERSIST_WRITE_GATE_STATE = prev;
+      }
+    });
+    process.env.GSD_PERSIST_WRITE_GATE_STATE = "1";
+
+    // Reset state and clear any stale snapshot files from both dirs.
+    clearDiscussionFlowState(baseDirA);
+    clearDiscussionFlowState(baseDirB);
+
+    // Act: persist a milestone as depth-verified into baseDirA.
+    markDepthVerified("M001", baseDirA);
+
+    // Confirm the snapshot file was written under baseDirA.
+    const snapshotPath = join(baseDirA, ".gsd", "runtime", "write-gate-state.json");
+    assert.ok(existsSync(snapshotPath), "snapshot file should exist under baseDirA");
+
+    // Simulate what happens when cwd changes to a different project root.
+    process.chdir(baseDirB);
+    assert.notEqual(process.cwd(), baseDirA, "cwd should differ from baseDirA after chdir");
+
+    // Load snapshot using the explicit baseDirA — must see the persisted state.
+    const snapshot = loadWriteGateSnapshot(baseDirA);
+    assert.ok(
+      snapshot.verifiedDepthMilestones.includes("M001"),
+      "loadWriteGateSnapshot(baseDirA) must return the persisted milestone despite cwd being baseDirB",
+    );
+
+    // Loading with baseDirB must NOT see the state from baseDirA.
+    const snapshotB = loadWriteGateSnapshot(baseDirB);
+    assert.ok(
+      !snapshotB.verifiedDepthMilestones.includes("M001"),
+      "loadWriteGateSnapshot(baseDirB) must not bleed state from baseDirA",
+    );
+  });
+});