gsd-pi 2.75.0-dev.063e5a3 → 2.75.0-dev.96d4bb599

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

@@ -369,9 +369,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);

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

@@ -37,6 +37,30 @@ export interface ProviderCheckResult {
   required: boolean;
 }
 
+// ── 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: Record<string, string[]> = {
+  anthropic: ["github-copilot", "claude-code"],
+  openai: ["github-copilot", "openai-codex"],
+  google: ["google-gemini-cli"],
+};
+
 // ── Model → Provider ID mapping ───────────────────────────────────────────────
 
 /**
@@ -125,9 +149,37 @@ interface KeyLookup {
   backedOff: boolean;
 }
 
+/**
+ * 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: Record<string, string> = {
+  "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: string): boolean {
+  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: string): KeyLookup {
   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 };
   }
@@ -174,28 +226,6 @@ function resolveKey(providerId: string): KeyLookup {
 
 // ── 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: Record<string, string[]> = {
-  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(): ProviderCheckResult[] {
   const required = collectConfiguredModelProviders();
   const results: ProviderCheckResult[] = [];

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

@@ -8,9 +8,10 @@ import { deriveState } from "./state.js";
 import { saveFile } from "./files.js";
 import { nativeIsRepo, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
 import { readCrashLock, isLockProcessAlive, clearLock } from "./crash-recovery.js";
-import { ensureGitignore } from "./gitignore.js";
+import { ensureGitignore, isGsdGitignored } from "./gitignore.js";
 import { readAllSessionStatuses, isSessionStale, removeSessionStatus } from "./session-status-io.js";
 import { recoverFailedMigration } from "./migrate-external.js";
+import { splitCompletedKey } from "./forensics.js";
 
 export async function checkRuntimeHealth(
   basePath: string,
@@ -118,9 +119,6 @@ export async function checkRuntimeHealth(
       const orphaned: string[] = [];
 
       for (const key of keys) {
-        // Key format: "unitType/unitId" e.g. "execute-task/M001/S01/T01"
-        // Hook units have compound types: "hook/<hookName>/unitId"
-        const { splitCompletedKey } = await import("./forensics.js");
         const parsed = splitCompletedKey(key);
         if (!parsed) continue;
         const { unitType, unitId } = parsed;
@@ -383,6 +381,27 @@ export async function checkRuntimeHealth(
             fixable: false,
           });
         }
+
+        // ── Symlinked .gsd without .gitignore entry (#4423) ──
+        // When `.gsd` is a symlink AND not gitignored, `git add -A -- :!.gsd/...`
+        // pathspecs fail with "beyond a symbolic link". Without self-heal this
+        // silently drops new user files during auto-commit.
+        if (nativeIsRepo(basePath) && !isGsdGitignored(basePath)) {
+          issues.push({
+            severity: "warning",
+            code: "symlinked_gsd_unignored",
+            scope: "project",
+            unitId: "project",
+            message: ".gsd is a symlink to external state but is not listed in .gitignore. This causes git pathspec exclusions to fail and can lead to silently dropped new files during auto-commit. Add `.gsd` to .gitignore.",
+            file: ".gitignore",
+            fixable: true,
+          });
+
+          if (shouldFix("symlinked_gsd_unignored")) {
+            const modified = ensureGitignore(basePath);
+            if (modified) fixesApplied.push("added .gsd to .gitignore (symlinked external state)");
+          }
+        }
       }
     }
   } catch {

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

@@ -23,6 +23,7 @@ export type DoctorIssueCode =
   | "state_file_stale"
   | "state_file_missing"
   | "gitignore_missing_patterns"
+  | "symlinked_gsd_unignored"
   | "unresolvable_dependency"
   | "failed_migration"
   | "broken_symlink"

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

@@ -172,8 +172,14 @@ function auditRequirements(content: string | null): DoctorIssue[] {
     const notes = block.match(/^-\s+Notes:\s+(.+)$/m)?.[1]?.trim().toLowerCase() ?? "";
 
     if (status === "active" && (!owner || owner === "none" || owner === "none yet")) {
+      // #4414: Downgrade to warning. A newly-created requirement has
+      // primary_owner='' by default until the planning agent wires it to
+      // a slice via gsd_requirement_update. Flagging this as an error
+      // during normal planning is noisy — the real failure mode is when
+      // it persists past milestone completion, which is covered by other
+      // audits. Keep the signal but don't treat it as a blocker.
       issues.push({
-        severity: "error",
+        severity: "warning",
         code: "active_requirement_missing_owner",
         scope: "project",
         unitId: requirementId,

package/src/resources/extensions/gsd/error-classifier.ts

@@ -43,11 +43,14 @@ export function resetRetryState(state: RetryState): void {
 // ── Classification ──────────────────────────────────────────────────────────
 
 const PERMANENT_RE = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|billing|quota exceeded|account/i;
-const RATE_LIMIT_RE = /rate.?limit|too many requests|429/i;
+// Include provider-specific quota-window phrasing like:
+// - "You've hit your limit"
+// - "usage limit" / "quota reached"
+const RATE_LIMIT_RE = /rate.?limit|too many requests|429|hit your limit|usage limit|quota (?:reached|hit)|limit.*resets?/i;
 // OpenRouter affordability-style quota errors should be treated as transient
 // so core retry logic can lower maxTokens and continue in-session.
 const AFFORDABILITY_RE = /requires more credits|can only afford|insufficient credits|not enough credits|fewer max_tokens/i;
-const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns/i;
+const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns|unexpected eof/i;
 const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i;
 // ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
 const CONNECTION_RE = /terminated|connection.?(?:refused|error)|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
@@ -61,7 +64,7 @@ const RESET_DELAY_RE = /reset in (\d+)s/i;
  *
  * Classification order:
  *  1. Permanent (auth/billing/quota) — unless also rate-limited
- *  2. Rate limit (429, rate.?limit, too many requests)
+ *  2. Rate limit (429, rate.?limit, too many requests, hit-your-limit/quota-window phrasing)
  *  3. Network (ECONNRESET, ETIMEDOUT, socket hang up, fetch failed, dns)
  *  4. Stream truncation (malformed JSON from mid-stream cut)
  *  5. Server (500/502/503, overloaded, server_error)