gsd-pi 2.74.0 → 2.75.0-dev.2203010a0

package/dist/resources/extensions/gsd/custom-workflow-engine.js

@@ -13,7 +13,7 @@
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { readGraph, writeGraph, getNextPendingStep, markStepComplete, expandIteration, } from "./graph.js";
+import { readGraph, writeGraph, getNextPendingStep, markStepActive, markStepComplete, expandIteration, } from "./graph.js";
 import { injectContext } from "./context-injector.js";
 import { readFrozenDefinition } from "./definition-io.js";
 import { parseUnitId } from "./unit-id.js";
@@ -62,66 +62,86 @@ export class CustomWorkflowEngine {
      * - Expanded GRAPH.yaml is written to disk before dispatch — inspectable on disk.
      */
     async resolveDispatch(state, _context) {
-        let graph = state.raw;
-        let next = getNextPendingStep(graph);
-        if (!next) {
-            return {
-                action: "stop",
-                reason: "All steps complete",
-                level: "info",
-            };
-        }
-        // Check frozen DEFINITION.yaml for iterate config on this step
-        const def = readFrozenDefinition(this.runDir);
-        const stepDef = def.steps.find((s) => s.id === next.id);
-        if (stepDef?.iterate) {
-            const iterate = stepDef.iterate;
-            // Read source artifact
-            const sourcePath = join(this.runDir, iterate.source);
-            let sourceContent;
-            try {
-                sourceContent = readFileSync(sourcePath, "utf-8");
-            }
-            catch {
-                throw new Error(`Iterate source artifact not found: ${sourcePath} (step "${next.id}", source: "${iterate.source}")`);
-            }
-            // Extract items via regex with global+multiline flags.
-            // Guard against ReDoS: if matching takes too long on large inputs, bail.
-            const regex = new RegExp(iterate.pattern, "gm");
-            const items = [];
-            const matchStart = Date.now();
-            let match;
-            while ((match = regex.exec(sourceContent)) !== null) {
-                if (match[1] !== undefined)
-                    items.push(match[1]);
-                if (Date.now() - matchStart > 5_000) {
-                    throw new Error(`Iterate pattern "${iterate.pattern}" exceeded 5s timeout on step "${next.id}" — possible ReDoS`);
-                }
+        const graphPath = join(this.runDir, "GRAPH.yaml");
+        return await withFileLock(graphPath, () => {
+            let graph = readGraph(this.runDir);
+            const active = graph.steps.find((step) => step.status === "active");
+            if (active) {
+                return {
+                    action: "dispatch",
+                    step: {
+                        unitType: "custom-step",
+                        unitId: `${graph.metadata.name}/${active.id}`,
+                        prompt: injectContext(this.runDir, active.id, active.prompt),
+                    },
+                };
             }
-            // Expand the graph
-            const expandedGraph = expandIteration(graph, next.id, items, next.prompt);
-            writeGraph(this.runDir, expandedGraph);
-            graph = expandedGraph;
-            // Re-query for first instance step
-            next = getNextPendingStep(expandedGraph);
+            let next = getNextPendingStep(graph);
             if (!next) {
                 return {
                     action: "stop",
-                    reason: "Iterate expansion produced no instances",
+                    reason: "All steps complete",
                     level: "info",
                 };
             }
-        }
-        // Enrich prompt with context from prior step artifacts
-        const enrichedPrompt = injectContext(this.runDir, next.id, next.prompt);
-        return {
-            action: "dispatch",
-            step: {
-                unitType: "custom-step",
-                unitId: `${graph.metadata.name}/${next.id}`,
-                prompt: enrichedPrompt,
-            },
-        };
+            // Check frozen DEFINITION.yaml for iterate config on this step
+            const def = readFrozenDefinition(this.runDir);
+            const stepDef = def.steps.find((s) => s.id === next.id);
+            if (stepDef?.iterate) {
+                const iterate = stepDef.iterate;
+                // Read source artifact
+                const sourcePath = join(this.runDir, iterate.source);
+                let sourceContent;
+                try {
+                    sourceContent = readFileSync(sourcePath, "utf-8");
+                }
+                catch {
+                    throw new Error(`Iterate source artifact not found: ${sourcePath} (step "${next.id}", source: "${iterate.source}")`);
+                }
+                // Extract items via regex with global+multiline flags.
+                // Guard against ReDoS: if matching takes too long on large inputs, bail.
+                const regex = new RegExp(iterate.pattern, "gm");
+                const items = [];
+                const matchStart = Date.now();
+                let match;
+                while ((match = regex.exec(sourceContent)) !== null) {
+                    if (match[1] !== undefined)
+                        items.push(match[1]);
+                    if (Date.now() - matchStart > 5_000) {
+                        throw new Error(`Iterate pattern "${iterate.pattern}" exceeded 5s timeout on step "${next.id}" — possible ReDoS`);
+                    }
+                }
+                // Expand the graph
+                const expandedGraph = expandIteration(graph, next.id, items, next.prompt);
+                writeGraph(this.runDir, expandedGraph);
+                graph = expandedGraph;
+                // Re-query for first instance step
+                next = getNextPendingStep(expandedGraph);
+                if (!next) {
+                    return {
+                        action: "stop",
+                        reason: "Iterate expansion produced no instances",
+                        level: "info",
+                    };
+                }
+            }
+            const activeGraph = markStepActive(graph, next.id);
+            writeGraph(this.runDir, activeGraph);
+            const activeStep = activeGraph.steps.find((s) => s.id === next.id);
+            if (!activeStep) {
+                throw new Error(`Active step not found after GRAPH.yaml update: ${next.id}`);
+            }
+            // Enrich prompt with context from prior step artifacts
+            const enrichedPrompt = injectContext(this.runDir, activeStep.id, activeStep.prompt);
+            return {
+                action: "dispatch",
+                step: {
+                    unitType: "custom-step",
+                    unitId: `${activeGraph.metadata.name}/${activeStep.id}`,
+                    prompt: enrichedPrompt,
+                },
+            };
+        });
     }
     /**
      * Reconcile state after a step completes.

package/dist/resources/extensions/gsd/db-writer.js

@@ -301,8 +301,7 @@ export async function saveRequirementToDb(fields, basePath) {
         catch (diskErr) {
             logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveRequirementToDb', error: String(diskErr.message) });
             try {
-                const rollbackAdapter = db._getAdapter();
-                rollbackAdapter?.prepare('DELETE FROM requirements WHERE id = :id').run({ ':id': id });
+                db.deleteRequirementById(id);
             }
             catch (rollbackErr) {
                 logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveRequirementToDb', id, error: String(rollbackErr.message) });
@@ -354,6 +353,7 @@ export async function saveDecisionToDb(fields, basePath) {
                 rationale: fields.rationale,
                 revisable: fields.revisable ?? 'Yes',
                 made_by: fields.made_by ?? 'agent',
+                source: fields.source ?? 'discussion',
                 superseded_by: null,
             });
             return nextId;
@@ -405,7 +405,7 @@ export async function saveDecisionToDb(fields, basePath) {
         catch (diskErr) {
             logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveDecisionToDb', error: String(diskErr.message) });
             try {
-                adapter?.prepare('DELETE FROM decisions WHERE id = :id').run({ ':id': id });
+                db.deleteDecisionById(id);
             }
             catch (rollbackErr) {
                 logError('manifest', 'SPLIT BRAIN: disk write failed AND DB rollback failed — DB has orphaned row', { fn: 'saveDecisionToDb', id, error: String(rollbackErr.message) });
@@ -614,8 +614,7 @@ export async function saveArtifactToDb(opts, basePath) {
             }
             catch (diskErr) {
                 logError('manifest', 'disk write failed, rolling back DB row', { fn: 'saveArtifactToDb', error: String(diskErr.message) });
-                const rollbackAdapter = db._getAdapter();
-                rollbackAdapter?.prepare('DELETE FROM artifacts WHERE path = :path').run({ ':path': opts.path });
+                db.deleteArtifactByPath(opts.path);
                 throw diskErr;
             }
         }

package/dist/resources/extensions/gsd/debug-session-store.js

@@ -0,0 +1,238 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+import { gsdRoot } from "./paths.js";
+const DEFAULT_PHASE = "queued";
+const DEFAULT_STATUS = "active";
+const SESSION_FILE_SUFFIX = ".json";
+const MAX_SLUG_LENGTH = 64;
+const MAX_COLLISION_ATTEMPTS = 10_000;
+function debugRoot(basePath) {
+    return join(gsdRoot(basePath), "debug");
+}
+export function debugSessionsDir(basePath) {
+    return join(debugRoot(basePath), "sessions");
+}
+export function debugSessionArtifactPath(basePath, slug) {
+    assertValidDebugSessionSlug(slug);
+    return join(debugSessionsDir(basePath), `${slug}${SESSION_FILE_SUFFIX}`);
+}
+export function debugSessionLogPath(basePath, slug) {
+    assertValidDebugSessionSlug(slug);
+    return join(debugRoot(basePath), `${slug}.log`);
+}
+function ensureSessionsDir(basePath) {
+    const dir = debugSessionsDir(basePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export function slugifyDebugSessionIssue(issue) {
+    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) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) {
+        throw new Error(`Invalid debug session slug: ${slug}`);
+    }
+}
+function isDebugSessionStatus(value) {
+    return value === "active" || value === "paused" || value === "resolved" || value === "failed";
+}
+function isDebugCheckpointShape(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const o = value;
+    const validTypes = ["human-verify", "human-action", "decision", "root-cause-found", "inconclusive"];
+    return (validTypes.includes(o.type)
+        && typeof o.summary === "string"
+        && typeof o.awaitingResponse === "boolean"
+        && (o.userResponse === undefined || typeof o.userResponse === "string"));
+}
+function isDebugTddGateShape(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const o = value;
+    const validPhases = ["pending", "red", "green"];
+    return (typeof o.enabled === "boolean"
+        && validPhases.includes(o.phase)
+        && (o.testFile === undefined || typeof o.testFile === "string")
+        && (o.testName === undefined || typeof o.testName === "string")
+        && (o.failureOutput === undefined || typeof o.failureOutput === "string"));
+}
+function isDebugSpecialistReviewShape(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const o = value;
+    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) {
+    if (!value || typeof value !== "object")
+        return false;
+    const o = value;
+    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, raw) {
+    let parsed;
+    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) {
+    return {
+        atomicWrite: deps.atomicWrite ?? atomicWriteSync,
+        readFile: deps.readFile ?? ((filePath, encoding) => readFileSync(filePath, encoding)),
+        listDir: deps.listDir ?? ((dirPath) => readdirSync(dirPath)),
+        exists: deps.exists ?? ((filePath) => existsSync(filePath)),
+        now: deps.now ?? (() => Date.now()),
+    };
+}
+function nextSlug(basePath, baseSlug, deps) {
+    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) {
+    return JSON.stringify(session, null, 2) + "\n";
+}
+export function createDebugSession(basePath, input, deps = {}) {
+    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 = {
+        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, slug, deps = {}) {
+    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, deps = {}) {
+    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 = [];
+    const malformed = [];
+    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, slug, update, deps = {}) {
+    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 = {
+        ...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 };
+}

package/dist/resources/extensions/gsd/definition-loader.js

@@ -246,6 +246,13 @@ export function validateDefinition(parsed) {
  */
 export function loadDefinition(defsDir, name) {
     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) {
     if (!existsSync(filePath)) {
         throw new Error(`Definition file not found: ${filePath}`);
     }

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

@@ -102,6 +102,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `custom_instructions`: extra durable instructions related to skill use. For operational project knowledge (recurring rules, gotchas, patterns), use `.gsd/KNOWLEDGE.md` instead — it's injected into every agent prompt automatically and agents can append to it during execution.
 
+- `language`: preferred response language for all GSD interactions. Accepts any language name or code — `"Chinese"`, `"zh"`, `"German"`, `"de"`, `"日本語"`, etc. When set, GSD injects "Always respond in \<language\>" into every agent's system prompt, including after `/clear`. Quickest way to set it: `/gsd language <name>`. To clear: `/gsd language off`.
+
 - `models`: per-stage model selection (applies to both auto-mode and guided-flow dispatches). Keys: `research`, `planning`, `discuss`, `execution`, `execution_simple`, `completion`, `validation`, `subagent`. Values can be:
   - Simple string: `"claude-sonnet-4-6"` — single model, no fallbacks
   - Provider-qualified string: `"bedrock/claude-sonnet-4-6"` — targets a specific provider when the same model ID exists across multiple providers
@@ -128,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"`.
@@ -153,7 +155,7 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
 
 - `context_pause_threshold`: number (0-100) — context window usage percentage at which auto-mode should pause to suggest checkpointing. Set to `0` to disable. Default: `0` (disabled).
 
-- `token_profile`: `"budget"`, `"balanced"`, or `"quality"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models. See token-optimization docs.
+- `token_profile`: `"budget"`, `"balanced"`, `"quality"`, or `"burn-max"` — coordinates model selection, phase skipping, and context compression. `budget` skips research/reassessment and uses cheaper models; `balanced` (default) skips research/reassessment to reduce token burn; `quality` prefers higher-quality models; `burn-max` keeps full-context defaults, disables downgrade routing, and keeps phase skips off.
 
 - `phases`: fine-grained control over which phases run. Usually set by `token_profile`, but can be overridden. Keys:
   - `skip_research`: boolean — skip milestone-level research. Default: `false`.
@@ -191,6 +193,19 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `hooks`: boolean — enable routing hooks. Default: `true`.
   - `capability_routing`: boolean — enable capability-profile scoring for model selection within a tier. Requires `enabled: true`. Default: `false`.
 
+- `uok`: Unified Orchestration Kernel controls. Keys:
+  - `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`. 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`.
   - `observation_mask_turns`: number — keep this many recent turns verbatim (1-50). Default: `8`.

package/dist/resources/extensions/gsd/doctor-environment.js

@@ -11,6 +11,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { execSync } from "node:child_process";
 import { join } from "node:path";
+import { detectPythonExecutable } from "./python-resolver.js";
 // ── Constants ──────────────────────────────────────────────────────────────
 /** Default dev server ports to scan for conflicts. */
 const DEFAULT_DEV_PORTS = [3000, 3001, 4000, 5000, 5173, 8000, 8080, 8888];
@@ -350,7 +351,7 @@ function checkProjectTools(basePath) {
         }
         // 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/dist/resources/extensions/gsd/doctor-git-checks.js

@@ -365,8 +365,12 @@ export async function checkGitHealth(basePath, issues, fixesApplied, shouldFix,
     // 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/dist/resources/extensions/gsd/doctor-proactive.js

@@ -238,8 +238,11 @@ export async function preDispatchHealthGate(basePath) {
     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);

package/dist/resources/extensions/gsd/doctor-providers.js

@@ -11,10 +11,32 @@
  *   - Optional search/tool integrations (Brave, Tavily, Jina, Context7)
  */
 import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY } from "./key-manager.js";
+// ── Provider routing constants ────────────────────────────────────────────────
+/**
+ * Providers that use external CLI authentication (not API keys).
+ * These are always considered "found" — the host CLI handles auth.
+ */
+const CLI_AUTH_PROVIDERS = new Set([
+    "claude-code",
+    "openai-codex",
+    "google-gemini-cli",
+    "google-antigravity",
+]);
+/**
+ * Providers that can serve models normally associated with another provider.
+ * Key = the provider whose models can be served, Value = alternative providers to check.
+ * e.g. GitHub Copilot subscriptions can access Claude and GPT models.
+ */
+const PROVIDER_ROUTES = {
+    anthropic: ["github-copilot", "claude-code"],
+    openai: ["github-copilot", "openai-codex"],
+    google: ["google-gemini-cli"],
+};
 // ── Model → Provider ID mapping ───────────────────────────────────────────────
 /**
  * Infer the auth provider ID from a model string.
@@ -96,8 +118,34 @@ function collectConfiguredModelProviders() {
         providers.add("anthropic");
     return providers;
 }
+/**
+ * Map of CLI provider IDs to their binary names on disk.
+ * Used for lightweight binary-presence checks (PATH scan, no subprocess).
+ */
+const CLI_BINARY_MAP = {
+    "claude-code": "claude",
+    "openai-codex": "codex",
+    "google-gemini-cli": "gemini",
+    "google-antigravity": "antigravity",
+};
+/**
+ * Check if a CLI provider's binary exists anywhere in PATH.
+ * Fast filesystem scan — no subprocess, no network, sub-1ms.
+ */
+function isCliBinaryInPath(providerId) {
+    const binary = CLI_BINARY_MAP[providerId];
+    if (!binary)
+        return false;
+    const pathDirs = (process.env.PATH ?? "").split(":");
+    return pathDirs.some(dir => dir && existsSync(join(dir, binary)));
+}
 function resolveKey(providerId) {
     const info = PROVIDER_REGISTRY.find(p => p.id === providerId);
+    // claude-code never stores credentials in auth.json — GSD delegates entirely to
+    // the local CLI binary. Presence of the binary in PATH is the only signal.
+    if (providerId === "claude-code") {
+        return { found: isCliBinaryInPath("claude-code"), source: "env", backedOff: false };
+    }
     if (providerId === "anthropic-vertex" && process.env.ANTHROPIC_VERTEX_PROJECT_ID) {
         return { found: true, source: "env", backedOff: false };
     }
@@ -137,26 +185,6 @@ function resolveKey(providerId) {
     return { found: false, source: "none", backedOff: false };
 }
 // ── Individual check groups ────────────────────────────────────────────────────
-/**
- * Providers that can serve models normally associated with another provider.
- * Key = the provider whose models can be served, Value = alternative providers to check.
- * e.g. GitHub Copilot subscriptions can access Claude and GPT models.
- */
-const PROVIDER_ROUTES = {
-    anthropic: ["github-copilot"],
-    openai: ["github-copilot", "openai-codex"],
-    google: ["google-gemini-cli"],
-};
-/**
- * Providers that use external CLI authentication (not API keys).
- * These are always considered "ok" — the host CLI handles auth.
- */
-const CLI_AUTH_PROVIDERS = new Set([
-    "claude-code",
-    "openai-codex",
-    "google-gemini-cli",
-    "google-antigravity",
-]);
 function checkLlmProviders() {
     const required = collectConfiguredModelProviders();
     const results = [];