gsd-pi 2.75.0 → 2.76.0-dev.b072ebb73

package/src/resources/extensions/gsd/debug-session-store.ts

@@ -0,0 +1,377 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync, type AtomicWriteSyncOps } from "./atomic-write.js";
+import { gsdRoot } from "./paths.js";
+
+export type DebugSessionStatus = "active" | "paused" | "resolved" | "failed";
+
+export interface DebugCheckpoint {
+  type: "human-verify" | "human-action" | "decision" | "root-cause-found" | "inconclusive";
+  summary: string;
+  awaitingResponse: boolean;
+  userResponse?: string;
+}
+
+export interface DebugTddGate {
+  enabled: boolean;
+  phase: "pending" | "red" | "green";
+  testFile?: string;
+  testName?: string;
+  failureOutput?: string;
+}
+
+export interface DebugSpecialistReview {
+  hint: string;
+  skill: string | null;
+  verdict: string;
+  detail: string;
+  reviewedAt: number;
+}
+
+export interface DebugSessionArtifact {
+  version: 1;
+  mode: "debug" | "diagnose";
+  slug: string;
+  issue: string;
+  status: DebugSessionStatus;
+  phase: string;
+  createdAt: number;
+  updatedAt: number;
+  logPath: string;
+  lastError: string | null;
+  checkpoint?: DebugCheckpoint | null;
+  tddGate?: DebugTddGate | null;
+  specialistReview?: DebugSpecialistReview | null;
+}
+
+export interface DebugSessionRecord {
+  artifactPath: string;
+  session: DebugSessionArtifact;
+}
+
+export interface DebugMalformedSessionArtifact {
+  artifactPath: string;
+  message: string;
+}
+
+export interface DebugSessionListResult {
+  sessions: DebugSessionRecord[];
+  malformed: DebugMalformedSessionArtifact[];
+}
+
+export interface CreateDebugSessionInput {
+  issue: string;
+  mode?: "debug" | "diagnose";
+  status?: DebugSessionStatus;
+  phase?: string;
+  createdAt?: number;
+}
+
+export interface UpdateDebugSessionInput {
+  status?: DebugSessionStatus;
+  phase?: string;
+  issue?: string;
+  lastError?: string | null;
+  updatedAt?: number;
+  checkpoint?: DebugCheckpoint | null;
+  tddGate?: DebugTddGate | null;
+  specialistReview?: DebugSpecialistReview | null;
+}
+
+export interface DebugSessionStoreDeps {
+  atomicWrite?: (filePath: string, content: string, encoding?: BufferEncoding) => void;
+  readFile?: (filePath: string, encoding: BufferEncoding) => string;
+  listDir?: (dirPath: string) => string[];
+  exists?: (filePath: string) => boolean;
+  now?: () => number;
+}
+
+const DEFAULT_PHASE = "queued";
+const DEFAULT_STATUS: DebugSessionStatus = "active";
+const SESSION_FILE_SUFFIX = ".json";
+const MAX_SLUG_LENGTH = 64;
+const MAX_COLLISION_ATTEMPTS = 10_000;
+
+function debugRoot(basePath: string): string {
+  return join(gsdRoot(basePath), "debug");
+}
+
+export function debugSessionsDir(basePath: string): string {
+  return join(debugRoot(basePath), "sessions");
+}
+
+export function debugSessionArtifactPath(basePath: string, slug: string): string {
+  assertValidDebugSessionSlug(slug);
+  return join(debugSessionsDir(basePath), `${slug}${SESSION_FILE_SUFFIX}`);
+}
+
+export function debugSessionLogPath(basePath: string, slug: string): string {
+  assertValidDebugSessionSlug(slug);
+  return join(debugRoot(basePath), `${slug}.log`);
+}
+
+function ensureSessionsDir(basePath: string): string {
+  const dir = debugSessionsDir(basePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function slugifyDebugSessionIssue(issue: string): string {
+  const normalized = issue
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-")
+    .slice(0, MAX_SLUG_LENGTH)
+    .replace(/-+$/g, "");
+
+  if (!normalized) {
+    throw new Error("Issue text must contain at least one alphanumeric character.");
+  }
+  return normalized;
+}
+
+export function assertValidDebugSessionSlug(slug: string): void {
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) {
+    throw new Error(`Invalid debug session slug: ${slug}`);
+  }
+}
+
+function isDebugSessionStatus(value: unknown): value is DebugSessionStatus {
+  return value === "active" || value === "paused" || value === "resolved" || value === "failed";
+}
+
+function isDebugCheckpointShape(value: unknown): value is DebugCheckpoint {
+  if (!value || typeof value !== "object") return false;
+  const o = value as Record<string, unknown>;
+  const validTypes = ["human-verify", "human-action", "decision", "root-cause-found", "inconclusive"];
+  return (
+    validTypes.includes(o.type as string)
+    && typeof o.summary === "string"
+    && typeof o.awaitingResponse === "boolean"
+    && (o.userResponse === undefined || typeof o.userResponse === "string")
+  );
+}
+
+function isDebugTddGateShape(value: unknown): value is DebugTddGate {
+  if (!value || typeof value !== "object") return false;
+  const o = value as Record<string, unknown>;
+  const validPhases = ["pending", "red", "green"];
+  return (
+    typeof o.enabled === "boolean"
+    && validPhases.includes(o.phase as string)
+    && (o.testFile === undefined || typeof o.testFile === "string")
+    && (o.testName === undefined || typeof o.testName === "string")
+    && (o.failureOutput === undefined || typeof o.failureOutput === "string")
+  );
+}
+
+function isDebugSpecialistReviewShape(value: unknown): value is DebugSpecialistReview {
+  if (!value || typeof value !== "object") return false;
+  const o = value as Record<string, unknown>;
+  return (
+    typeof o.hint === "string"
+    && (typeof o.skill === "string" || o.skill === null)
+    && typeof o.verdict === "string"
+    && typeof o.detail === "string"
+    && typeof o.reviewedAt === "number"
+  );
+}
+
+function isDebugSessionArtifact(value: unknown): value is DebugSessionArtifact {
+  if (!value || typeof value !== "object") return false;
+  const o = value as Record<string, unknown>;
+  return (
+    o.version === 1
+    && (o.mode === "debug" || o.mode === "diagnose")
+    && typeof o.slug === "string"
+    && typeof o.issue === "string"
+    && isDebugSessionStatus(o.status)
+    && typeof o.phase === "string"
+    && typeof o.createdAt === "number"
+    && typeof o.updatedAt === "number"
+    && typeof o.logPath === "string"
+    && (typeof o.lastError === "string" || o.lastError === null)
+    && (o.checkpoint === undefined || o.checkpoint === null || isDebugCheckpointShape(o.checkpoint))
+    && (o.tddGate === undefined || o.tddGate === null || isDebugTddGateShape(o.tddGate))
+    && (o.specialistReview === undefined || o.specialistReview === null || isDebugSpecialistReviewShape(o.specialistReview))
+  );
+}
+
+function parseDebugSessionArtifact(filePath: string, raw: string): DebugSessionArtifact {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse debug session artifact ${filePath}: ${message}`);
+  }
+
+  if (!isDebugSessionArtifact(parsed)) {
+    throw new Error(`Malformed debug session artifact ${filePath}: schema validation failed`);
+  }
+  return parsed;
+}
+
+function defaultDeps(deps: DebugSessionStoreDeps) {
+  return {
+    atomicWrite: deps.atomicWrite ?? atomicWriteSync,
+    readFile: deps.readFile ?? ((filePath: string, encoding: BufferEncoding) => readFileSync(filePath, encoding)),
+    listDir: deps.listDir ?? ((dirPath: string) => readdirSync(dirPath)),
+    exists: deps.exists ?? ((filePath: string) => existsSync(filePath)),
+    now: deps.now ?? (() => Date.now()),
+  };
+}
+
+function nextSlug(basePath: string, baseSlug: string, deps: ReturnType<typeof defaultDeps>): string {
+  const baseArtifactPath = debugSessionArtifactPath(basePath, baseSlug);
+  if (!deps.exists(baseArtifactPath)) return baseSlug;
+
+  for (let n = 2; n < MAX_COLLISION_ATTEMPTS; n++) {
+    const candidate = `${baseSlug}-${n}`;
+    const candidatePath = debugSessionArtifactPath(basePath, candidate);
+    if (!deps.exists(candidatePath)) return candidate;
+  }
+
+  throw new Error(`Unable to allocate unique debug session slug for '${baseSlug}'`);
+}
+
+function serializeArtifact(session: DebugSessionArtifact): string {
+  return JSON.stringify(session, null, 2) + "\n";
+}
+
+export function createDebugSession(
+  basePath: string,
+  input: CreateDebugSessionInput,
+  deps: DebugSessionStoreDeps = {},
+): DebugSessionRecord {
+  const d = defaultDeps(deps);
+  const issue = input.issue?.trim() ?? "";
+  if (!issue) {
+    throw new Error("Issue text is required to create a debug session.");
+  }
+
+  ensureSessionsDir(basePath);
+
+  const baseSlug = slugifyDebugSessionIssue(issue);
+  const slug = nextSlug(basePath, baseSlug, d);
+  const now = input.createdAt ?? d.now();
+  const session: DebugSessionArtifact = {
+    version: 1,
+    mode: input.mode ?? "debug",
+    slug,
+    issue,
+    status: input.status ?? DEFAULT_STATUS,
+    phase: input.phase ?? DEFAULT_PHASE,
+    createdAt: now,
+    updatedAt: now,
+    logPath: debugSessionLogPath(basePath, slug),
+    lastError: null,
+  };
+
+  const artifactPath = debugSessionArtifactPath(basePath, slug);
+  d.atomicWrite(artifactPath, serializeArtifact(session), "utf-8");
+
+  return { artifactPath, session };
+}
+
+export function loadDebugSession(
+  basePath: string,
+  slug: string,
+  deps: DebugSessionStoreDeps = {},
+): DebugSessionRecord | null {
+  assertValidDebugSessionSlug(slug);
+  const d = defaultDeps(deps);
+
+  const artifactPath = debugSessionArtifactPath(basePath, slug);
+  if (!d.exists(artifactPath)) return null;
+
+  const raw = d.readFile(artifactPath, "utf-8");
+  const session = parseDebugSessionArtifact(artifactPath, raw);
+  return { artifactPath, session };
+}
+
+export function listDebugSessions(
+  basePath: string,
+  deps: DebugSessionStoreDeps = {},
+): DebugSessionListResult {
+  const d = defaultDeps(deps);
+  const dir = debugSessionsDir(basePath);
+  if (!d.exists(dir)) return { sessions: [], malformed: [] };
+
+  const entries = d.listDir(dir)
+    .filter(entry => entry.endsWith(SESSION_FILE_SUFFIX))
+    .sort((a, b) => a.localeCompare(b));
+
+  const sessions: DebugSessionRecord[] = [];
+  const malformed: DebugMalformedSessionArtifact[] = [];
+
+  for (const entry of entries) {
+    const artifactPath = join(dir, entry);
+    try {
+      const raw = d.readFile(artifactPath, "utf-8");
+      const session = parseDebugSessionArtifact(artifactPath, raw);
+      sessions.push({ artifactPath, session });
+    } catch (error) {
+      malformed.push({
+        artifactPath,
+        message: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  sessions.sort((a, b) => {
+    if (a.session.updatedAt !== b.session.updatedAt) {
+      return b.session.updatedAt - a.session.updatedAt;
+    }
+    if (a.session.createdAt !== b.session.createdAt) {
+      return b.session.createdAt - a.session.createdAt;
+    }
+    return a.session.slug.localeCompare(b.session.slug);
+  });
+
+  return { sessions, malformed };
+}
+
+export function updateDebugSession(
+  basePath: string,
+  slug: string,
+  update: UpdateDebugSessionInput,
+  deps: DebugSessionStoreDeps = {},
+): DebugSessionRecord {
+  const d = defaultDeps(deps);
+  const loaded = loadDebugSession(basePath, slug, d);
+  if (!loaded) {
+    throw new Error(`Debug session not found for slug: ${slug}`);
+  }
+
+  const nextIssue = update.issue?.trim() ?? loaded.session.issue;
+  if (!nextIssue) {
+    throw new Error("Issue text cannot be empty.");
+  }
+
+  const nextStatus = update.status ?? loaded.session.status;
+  if (!isDebugSessionStatus(nextStatus)) {
+    throw new Error(`Invalid debug session status: ${String(update.status)}`);
+  }
+
+  const nextUpdatedAt = update.updatedAt ?? d.now();
+  const session: DebugSessionArtifact = {
+    ...loaded.session,
+    issue: nextIssue,
+    status: nextStatus,
+    phase: update.phase ?? loaded.session.phase,
+    lastError: update.lastError === undefined ? loaded.session.lastError : update.lastError,
+    checkpoint: update.checkpoint === undefined ? loaded.session.checkpoint : update.checkpoint,
+    tddGate: update.tddGate === undefined ? loaded.session.tddGate : update.tddGate,
+    specialistReview: update.specialistReview === undefined ? loaded.session.specialistReview : update.specialistReview,
+    updatedAt: nextUpdatedAt,
+  };
+
+  d.atomicWrite(loaded.artifactPath, serializeArtifact(session), "utf-8");
+  return { artifactPath: loaded.artifactPath, session };
+}
+
+// Keep this exported for focused fault-injection tests around rename retry behavior.
+export type { AtomicWriteSyncOps };

package/src/resources/extensions/gsd/definition-loader.ts

@@ -331,7 +331,14 @@ export function validateDefinition(parsed: unknown): { valid: boolean; errors: s
  */
 export function loadDefinition(defsDir: string, name: string): WorkflowDefinition {
   const filePath = join(defsDir, `${name}.yaml`);
+  return loadDefinitionFromFile(filePath);
+}
 
+/**
+ * Load and validate a YAML workflow definition from an absolute file path.
+ * Accepts both `.yaml` and `.yml` extensions.
+ */
+export function loadDefinitionFromFile(filePath: string): WorkflowDefinition {
   if (!existsSync(filePath)) {
     throw new Error(`Definition file not found: ${filePath}`);
   }

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -130,7 +130,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `auto_push`: boolean — automatically push commits to the remote after committing. Default: `false`.
   - `push_branches`: boolean — push the milestone branch to the remote after commits. Default: `false`.
   - `remote`: string — git remote name to push to. Default: `"origin"`.
-  - `snapshots`: boolean — create snapshot commits (WIP saves) during long-running tasks. Default: `true`.
+  - `snapshots`: boolean — create WIP snapshot commits (e.g. pre-dispatch and stale-uncommitted-changes safety commits emitted by the doctor). Set to `false` to suppress all doctor-initiated `gsd snapshot:` commits. Default: `true`.
   - `pre_merge_check`: boolean or `"auto"` — run pre-merge checks before merging a worktree back to the integration branch. `true` always runs, `false` never runs, `"auto"` runs when CI is detected. Default: `"auto"`.
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
@@ -197,14 +197,14 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `enabled`: boolean — enable kernel wrappers and contract observers. Default: `true`.
   - `legacy_fallback.enabled`: boolean — emergency release fallback that forces legacy orchestration behavior even when `uok.enabled` is `true`. Default: `false`.
     - Runtime override: set `GSD_UOK_FORCE_LEGACY=1` (or `GSD_UOK_LEGACY_FALLBACK=1`) to force legacy behavior for the current process.
-  - `gates.enabled`: boolean — route checks through the unified gate runner and persist `gate_runs`.
-  - `model_policy.enabled`: boolean — enforce policy filtering before model capability scoring.
-  - `execution_graph.enabled`: boolean — enable DAG scheduler facade/adapters for execution.
-  - `gitops.enabled`: boolean — persist turn-level git transaction records.
-  - `gitops.turn_action`: `"commit"` | `"snapshot"` | `"status-only"` — turn transaction mode.
-  - `gitops.turn_push`: boolean — whether turn transactions should include push intent metadata.
-  - `audit_unified.enabled`: boolean — dual-write unified audit envelope events.
-  - `plan_v2.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow.
+  - `gates.enabled`: boolean — route checks through the unified gate runner and persist `gate_runs`. Default: `true`.
+  - `model_policy.enabled`: boolean — enforce policy filtering before model capability scoring. Default: `true`.
+  - `execution_graph.enabled`: boolean — enable DAG scheduler facade/adapters for execution. Default: `true`.
+  - `gitops.enabled`: boolean — persist turn-level git transaction records. Default: `true`.
+  - `gitops.turn_action`: `"commit"` | `"snapshot"` | `"status-only"` — turn transaction mode. Default: `"commit"` (per-task atomic commits).
+  - `gitops.turn_push`: boolean — whether turn transactions should include push intent metadata. Default: `false`.
+  - `audit_unified.enabled`: boolean — dual-write unified audit envelope events. Default: `true`.
+  - `plan_v2.enabled`: boolean — enable bounded clarify/research/draft/compile planning flow. Default: `true`.
 
 - `context_management`: configures context hygiene for auto-mode sessions. Keys:
   - `observation_masking`: boolean — mask old tool results to reduce context bloat. Default: `true`.

package/src/resources/extensions/gsd/doctor-environment.ts

@@ -14,6 +14,7 @@ import { execSync } from "node:child_process";
 import { join } from "node:path";
 
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
+import { detectPythonExecutable } from "./python-resolver.js";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -402,7 +403,7 @@ function checkProjectTools(basePath: string): EnvironmentCheckResult[] {
 
     // Check for Python if pyproject.toml or requirements.txt exists
     if (existsSync(join(basePath, "pyproject.toml")) || existsSync(join(basePath, "requirements.txt"))) {
-      if (!commandExists("python3", basePath) && !commandExists("python", basePath)) {
+      if (detectPythonExecutable() === null) {
         results.push({
           name: "python",
           status: "warning",

package/src/resources/extensions/gsd/doctor-git-checks.ts

@@ -4,7 +4,7 @@ import { join, sep } from "node:path";
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { loadFile } from "./files.js";
 import { parseRoadmap as parseLegacyRoadmap } from "./parsers-legacy.js";
-import { isDbAvailable, getMilestoneSlices } from "./gsd-db.js";
+import { isDbAvailable, getMilestone } from "./gsd-db.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { deriveState, isMilestoneComplete } from "./state.js";
 import { listWorktrees, resolveGitDir, worktreesDir } from "./worktree-manager.js";
@@ -36,6 +36,38 @@ function isDoctorArtifactOnly(dirPath: string): boolean {
   }
 }
 
+function normalizePathForComparison(path: string): string {
+  const resolved = existsSync(path) ? realpathSync(path) : path;
+  const normalized = resolved
+    .replaceAll("\\", "/")
+    .replace(/^\/\/\?\//, "")
+    .replace(/\/+$/, "");
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+function isSameOrNestedPath(candidate: string, container: string): boolean {
+  const normalizedCandidate = normalizePathForComparison(candidate);
+  const normalizedContainer = normalizePathForComparison(container);
+  return normalizedCandidate === normalizedContainer ||
+    normalizedCandidate.startsWith(`${normalizedContainer}/`);
+}
+
+async function isCompletedMilestoneTerminal(basePath: string, milestoneId: string): Promise<boolean> {
+  const summaryPath = resolveMilestoneFile(basePath, milestoneId, "SUMMARY");
+  if (!summaryPath) return false;
+
+  if (isDbAvailable()) {
+    const milestone = getMilestone(milestoneId);
+    return !!milestone && milestone.status === "complete";
+  }
+
+  const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
+  const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+  if (!roadmapContent) return false;
+  const roadmap = parseLegacyRoadmap(roadmapContent);
+  return isMilestoneComplete(roadmap);
+}
+
 export async function checkGitHealth(
   basePath: string,
   issues: DoctorIssue[],
@@ -65,23 +97,9 @@ export async function checkGitHealth(
       // Extract milestone ID from branch name "milestone/M001" → "M001"
       const milestoneId = wt.branch.replace(/^milestone\//, "");
       const milestoneEntry = state.registry.find(m => m.id === milestoneId);
-
-      // Check if milestone is complete via roadmap
-      let isComplete = false;
-      if (milestoneEntry) {
-        if (isDbAvailable()) {
-          const dbSlices = getMilestoneSlices(milestoneId);
-          isComplete = dbSlices.length > 0 && dbSlices.every(s => s.status === "complete");
-        } else {
-          const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
-          const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-          if (roadmapContent) {
-            const roadmap = parseLegacyRoadmap(roadmapContent);
-            isComplete = isMilestoneComplete(roadmap);
-          }
-        }
-        // When DB unavailable and no roadmap, isComplete stays false
-      }
+      const isComplete = milestoneEntry
+        ? await isCompletedMilestoneTerminal(basePath, milestoneId)
+        : false;
 
       if (isComplete) {
         issues.push({
@@ -98,8 +116,13 @@ export async function checkGitHealth(
           // pattern in removeWorktree() (#1946). Without this, git cannot
           // remove the worktree and the doctor enters a deadlock where it
           // detects the orphan every run but never cleans it up.
-          const cwd = process.cwd();
-          if (wt.path === cwd || cwd.startsWith(wt.path + sep)) {
+          let cwd = basePath;
+          try {
+            cwd = process.cwd();
+          } catch {
+            cwd = basePath;
+          }
+          if (isSameOrNestedPath(cwd, wt.path)) {
             try {
               process.chdir(basePath);
             } catch {
@@ -130,15 +153,9 @@ export async function checkGitHealth(
           const milestoneId = branch.replace(/^milestone\//, "");
           const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
           let branchMilestoneComplete = false;
-          if (isDbAvailable()) {
-            const dbSlices = getMilestoneSlices(milestoneId);
-            branchMilestoneComplete = dbSlices.length > 0 && dbSlices.every(s => s.status === "complete");
-          } else {
-            const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
-            if (!roadmapContent) continue;
-            const roadmap = parseLegacyRoadmap(roadmapContent);
-            branchMilestoneComplete = isMilestoneComplete(roadmap);
-          }
+          const roadmapContent = roadmapPath ? await loadFile(roadmapPath) : null;
+          if (!roadmapContent) continue;
+          branchMilestoneComplete = await isCompletedMilestoneTerminal(basePath, milestoneId);
           if (branchMilestoneComplete) {
             issues.push({
               severity: "info",
@@ -369,9 +386,13 @@ export async function checkGitHealth(
   // auto-commit a safety snapshot so work isn't lost.
   try {
     const prefs = loadEffectiveGSDPreferences()?.preferences ?? {};
+    // `git.snapshots: false` is the canonical toggle that disables WIP
+    // snapshot commits — honour it here as well so both the proactive gate
+    // and the doctor-run path stay consistent (#4420).
+    const snapshotsEnabled = prefs.git?.snapshots !== false;
     const thresholdMinutes = prefs.stale_commit_threshold_minutes ?? 30;
 
-    if (thresholdMinutes > 0) {
+    if (snapshotsEnabled && thresholdMinutes > 0) {
       const dirty = nativeHasChanges(basePath);
       if (dirty) {
         const branch = nativeGetCurrentBranch(basePath);

package/src/resources/extensions/gsd/doctor-proactive.ts

@@ -301,9 +301,12 @@ export async function preDispatchHealthGate(basePath: string): Promise<PreDispat
   try {
     if (nativeIsRepo(basePath)) {
       const prefs = loadEffectiveGSDPreferences()?.preferences ?? {};
+      // `git.snapshots: false` is the canonical toggle that disables WIP
+      // snapshot commits — honour it before touching the threshold path (#4420).
+      const snapshotsEnabled = prefs.git?.snapshots !== false;
       const thresholdMinutes = prefs.stale_commit_threshold_minutes ?? 30;
 
-      if (thresholdMinutes > 0 && nativeHasChanges(basePath)) {
+      if (snapshotsEnabled && thresholdMinutes > 0 && nativeHasChanges(basePath)) {
         const branch = nativeGetCurrentBranch(basePath);
         const lastEpoch = nativeLastCommitEpoch(basePath, branch || "HEAD");
         const nowEpoch = Math.floor(Date.now() / 1000);