gsd-pi 2.78.0 → 2.78.1-dev.2ff77b0ce

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

@@ -3,7 +3,7 @@ import { join } from "node:path";
 
 import type { DoctorIssue } from "./doctor-types.js";
 import { isDbAvailable, _getAdapter } from "./gsd-db.js";
-import { resolveMilestoneFile } from "./paths.js";
+import { resolveGsdPathContract, resolveMilestoneFile } from "./paths.js";
 import { deriveState } from "./state.js";
 import { readEvents } from "./workflow-events.js";
 import { renderAllProjections } from "./workflow-projections.js";
@@ -13,7 +13,7 @@ export async function checkEngineHealth(
   issues: DoctorIssue[],
   fixesApplied: string[],
 ): Promise<void> {
-  const dbPath = join(basePath, ".gsd", "gsd.db");
+  const dbPath = resolveGsdPathContract(basePath).projectDb;
 
   if (!isDbAvailable() && existsSync(dbPath)) {
     issues.push({

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

@@ -17,6 +17,7 @@ import { AuthStorage } from "@gsd/pi-coding-agent";
 import { getEnvApiKey } from "@gsd/pi-ai";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getAuthPath, PROVIDER_REGISTRY, type ProviderCategory } from "./key-manager.js";
+import { homedir } from "node:os";
 
 // ── Types ──────────────────────────────────────────────────────────────────────
 
@@ -194,7 +195,7 @@ function isCliBinaryInPath(providerId: string): boolean {
 }
 
 function modelsJsonPaths(): string[] {
-  const home = process.env.HOME ?? "~";
+  const home = homedir();
   return [
     join(home, ".gsd", "agent", "models.json"),
     // Keep parity with custom-provider discovery during auto bootstrap.

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

@@ -4,7 +4,7 @@ import { basename, dirname, join } from "node:path";
 import type { DoctorIssue, DoctorIssueCode } from "./doctor-types.js";
 import { cleanNumberedGsdVariants } from "./repo-identity.js";
 import { milestonesDir, gsdRoot, resolveGsdRootFile } from "./paths.js";
-import { deriveState } from "./state.js";
+import { deriveState, isGhostMilestone, isReusableGhostMilestone } 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";
@@ -12,6 +12,19 @@ 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";
+import { findMilestoneIds } from "./milestone-ids.js";
+
+const MAX_UAT_ATTEMPTS = 3;
+
+function hasAssessmentVerdict(basePath: string, mid: string, sid: string): boolean {
+  const assessmentPath = join(gsdRoot(basePath), "milestones", mid, "slices", sid, `${sid}-ASSESSMENT.md`);
+  if (!existsSync(assessmentPath)) return false;
+  try {
+    return /^\s*verdict\s*:\s*(PASS|FAIL|PARTIAL)\b/im.test(readFileSync(assessmentPath, "utf-8"));
+  } catch {
+    return false;
+  }
+}
 
 export async function checkRuntimeHealth(
   basePath: string,
@@ -190,6 +203,47 @@ export async function checkRuntimeHealth(
     // Non-fatal — hook state check failed
   }
 
+  // ── Exhausted run-uat retry counters ──────────────────────────────────
+  try {
+    const runtimeDir = join(root, "runtime");
+    if (existsSync(runtimeDir)) {
+      const uatCounterPattern = /^uat-count-(M\d+)-(S\d+)\.json$/;
+      for (const fileName of readdirSync(runtimeDir)) {
+        const match = fileName.match(uatCounterPattern);
+        if (!match) continue;
+        const [, mid, sid] = match;
+        if (!mid || !sid || hasAssessmentVerdict(basePath, mid, sid)) continue;
+
+        const filePath = join(runtimeDir, fileName);
+        let count = 0;
+        try {
+          const parsed = JSON.parse(readFileSync(filePath, "utf-8"));
+          count = typeof parsed.count === "number" ? parsed.count : 0;
+        } catch {
+          count = MAX_UAT_ATTEMPTS + 1;
+        }
+        if (count <= MAX_UAT_ATTEMPTS) continue;
+
+        issues.push({
+          severity: "warning",
+          code: "uat_retry_exhausted",
+          scope: "slice",
+          unitId: `${mid}/${sid}`,
+          message: `run-uat for ${mid}/${sid} exhausted ${count - 1} retry attempt(s) without an ASSESSMENT verdict. Reset the retry counter after fixing the underlying UAT/tool issue, then rerun /gsd auto.`,
+          file: `.gsd/runtime/${fileName}`,
+          fixable: true,
+        });
+
+        if (shouldFix("uat_retry_exhausted")) {
+          rmSync(filePath, { force: true });
+          fixesApplied.push(`reset exhausted run-uat retry counter for ${mid}/${sid}`);
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — UAT retry counter check failed
+  }
+
   // ── Activity log bloat ────────────────────────────────────────────────
   try {
     const activityDir = join(root, "activity");
@@ -593,6 +647,43 @@ export async function checkRuntimeHealth(
   } catch {
     // Non-fatal — snapshot ref check failed
   }
+
+  // ── Orphan milestone directories (#4996) ──────────────────────────────
+  // Walk every milestone ID on disk. Any dir that has no DB row, no worktree,
+  // and no content files is an orphaned stub — it skews nextMilestoneId and
+  // was likely created by ensurePreconditions or showHeadlessMilestoneCreation
+  // for a phantom forward-reference. Surface as a fixable warning.
+  try {
+    const milestoneIds = findMilestoneIds(basePath);
+    const hasDbFile = existsSync(join(root, "gsd.db"));
+    for (const mid of milestoneIds) {
+      const isOrphan = isReusableGhostMilestone(basePath, mid)
+        || (!hasDbFile && isGhostMilestone(basePath, mid));
+      if (isOrphan) {
+        issues.push({
+          severity: "warning",
+          code: "orphan_milestone_dir",
+          scope: "milestone",
+          unitId: mid,
+          message: `Orphan milestone directory: ${mid} — directory exists on disk with no DB row, no worktree, and no content files. This stub skews milestone ID generation and should be removed.`,
+          file: `.gsd/milestones/${mid}`,
+          fixable: true,
+        });
+
+        if (shouldFix("orphan_milestone_dir")) {
+          try {
+            const orphanPath = join(milestonesDir(basePath), mid);
+            rmSync(orphanPath, { recursive: true, force: true });
+            fixesApplied.push(`removed orphan milestone directory: ${mid}`);
+          } catch {
+            // Non-fatal — leave for manual cleanup
+          }
+        }
+      }
+    }
+  } catch {
+    // Non-fatal — orphan milestone directory check failed
+  }
 }
 
 /**

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

@@ -19,6 +19,7 @@ export type DoctorIssueCode =
   | "stale_parallel_session"
   | "orphaned_completed_units"
   | "stale_hook_state"
+  | "uat_retry_exhausted"
   | "activity_log_bloat"
   | "state_file_stale"
   | "state_file_missing"
@@ -80,7 +81,9 @@ export type DoctorIssueCode =
   | "db_done_task_no_summary"
   | "db_duplicate_id"
   | "db_unavailable"
-  | "projection_drift";
+  | "projection_drift"
+  // Milestone filesystem/DB drift (#4996)
+  | "orphan_milestone_dir";
 
 /**
  * Issue codes that represent global or completion-critical state.

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

@@ -59,7 +59,7 @@ const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fet
 // Context overflow errors (context window/length exceeded) should be treated as server-class
 // transient errors so auto-mode can retry with reduced budget or fall back to a larger-context model.
 // See: https://github.com/gsd-build/gsd-2/issues/4528
-const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable|context (?:window|length) exceed|context window exceed/i;
+const SERVER_RE = /internal(?: server)?[ _-]?error|500|502|503|overloaded|server_error|api_error|service.?unavailable|context (?:window|length) exceed|context window exceed/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;
 // Catch-all for V8 JSON.parse errors: all modern variants end with "in JSON at position \d+".

package/src/resources/extensions/gsd/eval-review-schema.ts

@@ -0,0 +1,243 @@
+/**
+ * EVAL-REVIEW frontmatter schema and parser.
+ *
+ * The auditor agent for `/gsd eval-review` writes a markdown file whose
+ * machine-readable contract lives entirely in YAML frontmatter. The body
+ * after the closing `---` is human-only prose and is never parsed by any
+ * consumer (the design response to a prior parser that used regex over LLM-generated
+ * prose and produced silent failures).
+ *
+ * This module owns:
+ *   - The TypeBox schema for the frontmatter (single source of truth).
+ *   - A small frontmatter extractor (locates the YAML block).
+ *   - The validated parser (`parseEvalReviewFrontmatter`).
+ *   - Pure helpers for derived fields the handler must recompute server-side
+ *     (overall score, severity counts) — we never trust LLM arithmetic.
+ *
+ * Consumers: `commands-eval-review.ts` (writer), `commands-ship.ts` (reader
+ * for the soft pre-ship warning), and a future `commands-eval-fix.ts`.
+ */
+
+import { Type, type Static, type TSchema } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { parse as parseYaml } from "yaml";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+/** Schema version literal embedded in every EVAL-REVIEW.md frontmatter. */
+export const EVAL_REVIEW_SCHEMA_VERSION = "eval-review/v1" as const;
+
+/** Verdict values, ordered from worst to best for UI display purposes. */
+export const VERDICT_VALUES = [
+  "NOT_IMPLEMENTED",
+  "SIGNIFICANT_GAPS",
+  "NEEDS_WORK",
+  "PRODUCTION_READY",
+] as const;
+
+/** Severity classifications used in `gaps[*].severity`. */
+export const SEVERITY_VALUES = ["blocker", "major", "minor"] as const;
+
+/** Eval dimensions an auditor scores. `other` is the catch-all. */
+export const DIMENSION_VALUES = [
+  "observability",
+  "guardrails",
+  "tests",
+  "metrics",
+  "datasets",
+  "other",
+] as const;
+
+/** Lower bound for any score in the schema. */
+export const MIN_SCORE = 0;
+/** Upper bound for any score in the schema. */
+export const MAX_SCORE = 100;
+/** Coverage's contribution to overall_score. See `docs/user-docs/eval-review.md` for rationale. */
+export const COVERAGE_WEIGHT = 0.6;
+/** Infrastructure's contribution to overall_score. See `docs/user-docs/eval-review.md` for rationale. */
+export const INFRASTRUCTURE_WEIGHT = 0.4;
+
+// ─── Schema ───────────────────────────────────────────────────────────────────
+
+const verdictSchema = Type.Union(VERDICT_VALUES.map((v) => Type.Literal(v)));
+const severitySchema = Type.Union(SEVERITY_VALUES.map((v) => Type.Literal(v)));
+const dimensionSchema = Type.Union(DIMENSION_VALUES.map((v) => Type.Literal(v)));
+
+/**
+ * One gap finding inside `gaps[]`. Every field is required — the prompt
+ * cannot emit a partial gap. `evidence` is mandatory; the anti-Goodhart
+ * guard depends on it.
+ */
+export const EvalReviewGap = Type.Object({
+  id: Type.String({ pattern: "^G\\d+$" }),
+  dimension: dimensionSchema,
+  severity: severitySchema,
+  description: Type.String({ minLength: 1 }),
+  evidence: Type.String({ minLength: 1 }),
+  suggested_fix: Type.String({ minLength: 1 }),
+});
+
+/** Severity histogram. The handler recomputes this from `gaps[]`. */
+export const EvalReviewCounts = Type.Object({
+  blocker: Type.Integer({ minimum: 0 }),
+  major: Type.Integer({ minimum: 0 }),
+  minor: Type.Integer({ minimum: 0 }),
+});
+
+/**
+ * The full frontmatter schema. Field order in the schema definition mirrors
+ * the order that the auditor prompt asks the LLM to emit, so a literal-eyeball
+ * comparison between this file and `prompts/eval-review.md` stays meaningful.
+ */
+export const EvalReviewFrontmatter = Type.Object({
+  schema: Type.Literal(EVAL_REVIEW_SCHEMA_VERSION),
+  verdict: verdictSchema,
+  coverage_score: Type.Integer({ minimum: MIN_SCORE, maximum: MAX_SCORE }),
+  infrastructure_score: Type.Integer({ minimum: MIN_SCORE, maximum: MAX_SCORE }),
+  overall_score: Type.Integer({ minimum: MIN_SCORE, maximum: MAX_SCORE }),
+  generated: Type.String({ pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$" }),
+  slice: Type.String({ pattern: "^S\\d+$" }),
+  milestone: Type.String({ minLength: 1 }),
+  gaps: Type.Array(EvalReviewGap),
+  counts: EvalReviewCounts,
+});
+
+/** Inferred TypeScript type for a validated frontmatter object. */
+export type EvalReviewFrontmatterT = Static<typeof EvalReviewFrontmatter>;
+/** Inferred TypeScript type for a single gap finding. */
+export type EvalReviewGapT = Static<typeof EvalReviewGap>;
+/** Inferred TypeScript type for the counts histogram. */
+export type EvalReviewCountsT = Static<typeof EvalReviewCounts>;
+/** One of the four allowed verdict literals. */
+export type Verdict = (typeof VERDICT_VALUES)[number];
+
+// ─── Frontmatter extraction ───────────────────────────────────────────────────
+
+/**
+ * Locate the YAML block between two `---` lines and return its raw text.
+ *
+ * Tolerant to CRLF line endings. Does not interpret the YAML — that's the
+ * caller's job. The extractor only enforces the markdown frontmatter shape.
+ *
+ * @param raw - Full contents of an EVAL-REVIEW.md file.
+ * @returns `{ yaml }` with the inner YAML text on success, or `{ error }`
+ *   describing why the frontmatter could not be located.
+ */
+export function extractFrontmatterRaw(
+  raw: string,
+): { yaml: string } | { error: string } {
+  const lines = raw.split(/\r?\n/);
+  if (lines[0] !== "---") {
+    return { error: "Missing opening `---` frontmatter delimiter on line 1" };
+  }
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") {
+      return { yaml: lines.slice(1, i).join("\n") };
+    }
+  }
+  return { error: "Missing closing `---` frontmatter delimiter" };
+}
+
+// ─── Parser ───────────────────────────────────────────────────────────────────
+
+/** Discriminated result type returned by the parser. */
+export type ParseResult =
+  | { ok: true; data: EvalReviewFrontmatterT }
+  | { ok: false; error: string; pointer: string };
+
+/**
+ * Parse and validate the frontmatter of an EVAL-REVIEW.md file.
+ *
+ * Failure cases are exhaustive and deterministic:
+ *   - missing/unclosed frontmatter → `pointer: "/"`, message names the cause
+ *   - YAML syntax error → `pointer: "/"`, message contains "YAML"
+ *   - schema violation → `pointer` is the JSON-Pointer path of the bad field
+ *
+ * Body content after the closing `---` is never inspected. This is an
+ * response to a prior parser that used regex over the body and silently
+ * failed on prose / tables / numbered lists.
+ *
+ * @param raw - Full contents of an EVAL-REVIEW.md file.
+ * @returns A discriminated `ParseResult`.
+ */
+export function parseEvalReviewFrontmatter(raw: string): ParseResult {
+  const fm = extractFrontmatterRaw(raw);
+  if ("error" in fm) {
+    return { ok: false, error: fm.error, pointer: "/" };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(fm.yaml, { schema: "core" });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, error: `YAML parse error: ${msg}`, pointer: "/" };
+  }
+
+  const schema: TSchema = EvalReviewFrontmatter;
+  if (!Value.Check(schema, parsed)) {
+    const errs = [...Value.Errors(schema, parsed)];
+    const first = errs[0];
+    return {
+      ok: false,
+      error: `Schema validation failed: ${first?.message ?? "unknown error"}`,
+      pointer: first?.path ?? "/",
+    };
+  }
+
+  return { ok: true, data: parsed as EvalReviewFrontmatterT };
+}
+
+// ─── Derived fields ───────────────────────────────────────────────────────────
+
+/**
+ * Compute `overall_score` from the two component scores using the rubric
+ * weights documented in `docs/user-docs/eval-review.md`.
+ *
+ * The handler always recomputes this value rather than trusting whatever the
+ * LLM emitted in `overall_score`. If the LLM-emitted value disagrees with the
+ * recomputed one, the disagreement is logged and the recomputed value wins.
+ *
+ * Clamps the result into `[MIN_SCORE, MAX_SCORE]` defensively. Schema-validated
+ * inputs are already in range, but the helper is exported and may be called
+ * from a code path that bypasses the schema (tests, future tools); the clamp
+ * keeps the contract honest in those cases.
+ *
+ * @param coverage - integer 0..100 from the auditor's coverage assessment.
+ * @param infrastructure - integer 0..100 from the auditor's infra assessment.
+ * @returns rounded integer 0..100.
+ */
+export function computeOverallScore(coverage: number, infrastructure: number): number {
+  const raw = Math.round(coverage * COVERAGE_WEIGHT + infrastructure * INFRASTRUCTURE_WEIGHT);
+  return Math.max(MIN_SCORE, Math.min(MAX_SCORE, raw));
+}
+
+/**
+ * Build the severity histogram for a list of gaps.
+ *
+ * Used by the handler to overwrite whatever the LLM put in `counts` —
+ * we recompute server-side rather than trust LLM arithmetic.
+ *
+ * @param gaps - validated gap list.
+ * @returns counts keyed by severity literal.
+ */
+export function deriveCounts(gaps: readonly EvalReviewGapT[]): EvalReviewCountsT {
+  const counts: EvalReviewCountsT = { blocker: 0, major: 0, minor: 0 };
+  for (const g of gaps) counts[g.severity]++;
+  return counts;
+}
+
+/**
+ * Map a numeric overall_score to its verdict literal using the bands from
+ * Bands per `docs/user-docs/eval-review.md`: ≥80 PRODUCTION_READY, 60..79 NEEDS_WORK, 40..59 SIGNIFICANT_GAPS,
+ * <40 NOT_IMPLEMENTED.
+ *
+ * @param overall - integer 0..100.
+ * @returns a verdict literal.
+ */
+export function verdictForScore(overall: number): Verdict {
+  if (overall >= 80) return "PRODUCTION_READY";
+  if (overall >= 60) return "NEEDS_WORK";
+  if (overall >= 40) return "SIGNIFICANT_GAPS";
+  return "NOT_IMPLEMENTED";
+}

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

@@ -12,7 +12,7 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
+import { gsdHome } from "./gsd-home.js";
 
 import { extractTrace, type ExecutionTrace } from "./session-forensics.js";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
@@ -36,6 +36,7 @@ import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPref
 import { showNextAction } from "../shared/tui.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
 import { summarizeWorktreeTelemetry, percentile, type WorktreeTelemetrySummary } from "./worktree-telemetry.js";
+import { homedir } from "node:os";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -244,8 +245,7 @@ export async function handleForensics(
   // when import.meta.url resolves to the npm-global install path (Windows).
   let gsdSourceDir = dirname(fileURLToPath(import.meta.url));
   if (!existsSync(join(gsdSourceDir, "prompts"))) {
-    const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-    const fallback = join(gsdHome, "agent", "extensions", "gsd");
+    const fallback = join(gsdHome(), "agent", "extensions", "gsd");
     if (existsSync(join(fallback, "prompts"))) gsdSourceDir = fallback;
   }
 
@@ -804,7 +804,7 @@ function detectMissingArtifacts(completedKeys: string[], basePath: string, activ
  * the forensics memory-bloat guard in forensics-journal.test.ts — per-event
  * detail stays in the journal itself where the LLM can query it on demand.
  */
-function detectWorktreeOrphans(
+export function detectWorktreeOrphans(
   summary: WorktreeTelemetrySummary,
   anomalies: ForensicAnomaly[],
 ): void {
@@ -822,7 +822,7 @@ function detectWorktreeOrphans(
         reason === "in-progress-unmerged"
           ? "Auto-mode exited without completing a milestone; live work sits on an unmerged milestone branch. Run `/gsd auto` to resume, or merge manually."
           : reason === "complete-unmerged"
-            ? "A completed milestone's branch was never merged back to main. Run `/gsd health --fix` to resolve."
+            ? "A completed milestone's branch was never merged back to main. Run `/gsd doctor fix` to resolve."
             : `Reason: ${reason}.`,
     });
   }
@@ -1299,10 +1299,21 @@ function formatReportForPrompt(report: ForensicReport): string {
 function redactForGitHub(text: string, basePath: string): string {
   let result = text;
 
+  // Build regex that matches both / and \ separator variants (Windows)
+  // Normalize to / first, escape for regex, then replace each / with [/\\]
+  const esc = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const pathRe = (p: string) =>
+    new RegExp(esc(p.replace(/\\/g, "/")).replace(/\//g, "[/\\\\]"), "gi");
+
   // Replace absolute paths
-  result = result.replaceAll(basePath, ".");
-  const home = process.env.HOME ?? process.env.USERPROFILE ?? "";
-  if (home) result = result.replaceAll(home, "~");
+  result = result.replace(pathRe(basePath), ".");
+  // Redact GSD_HOME first (when it's outside ~), then OS home.
+  // Order matters: longer path must be replaced before the shorter prefix.
+  const gsdHomePath = gsdHome();
+  if (!gsdHomePath.startsWith(homedir())) {
+    result = result.replace(pathRe(gsdHomePath), "~/.gsd");
+  }
+  result = result.replace(pathRe(homedir()), "~");
 
   // Strip API key patterns
   result = result.replace(/sk-[a-zA-Z0-9]{20,}/g, "sk-***");

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

@@ -10,7 +10,7 @@
 
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
 import { gsdRoot } from "./paths.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -38,6 +38,7 @@ import {
 } from "./native-git-bridge.js";
 import { GSDError, GSD_MERGE_CONFLICT, GSD_GIT_ERROR } from "./errors.js";
 import { getErrorMessage } from "./error-utils.js";
+import { isInfrastructureError } from "./auto/infra-errors.js";
 
 // ─── Types ─────────────────────────────────────────────────────────────────
 
@@ -146,7 +147,7 @@ export interface TaskCommitContext {
  * what was actually built), falling back to the task title (what was planned).
  */
 export function buildTaskCommitMessage(ctx: TaskCommitContext): string {
-  const description = ctx.oneLiner || ctx.taskTitle;
+  const description = sanitizeCommitSubjectDescription(ctx.oneLiner || ctx.taskTitle);
   const type = inferCommitType(ctx.taskTitle, ctx.oneLiner);
 
   // Truncate description to ~72 chars for subject line (full budget without scope)
@@ -178,6 +179,61 @@ export function buildTaskCommitMessage(ctx: TaskCommitContext): string {
   return `${subject}\n\n${bodyParts.join("\n\n")}`;
 }
 
+function sanitizeCommitSubjectDescription(value: string): string {
+  const cleaned = value
+    .replace(/[\x00-\x1F\x7F]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return cleaned || "update task";
+}
+
+function normalizeRepoRelativePath(basePath: string, filePath: string): string | null {
+  const trimmed = filePath.trim();
+  if (!trimmed || trimmed.includes("\0")) return null;
+
+  const relPath = isAbsolute(trimmed)
+    ? relative(basePath, trimmed)
+    : normalize(trimmed);
+  if (!relPath || relPath === "." || isAbsolute(relPath) || relPath.startsWith(`..${sep}`) || relPath === "..") {
+    return null;
+  }
+
+  const resolved = resolve(basePath, relPath);
+  const relFromBase = relative(basePath, resolved);
+  if (!relFromBase || relFromBase === "." || relFromBase.startsWith("..") || isAbsolute(relFromBase)) {
+    return null;
+  }
+
+  return relFromBase;
+}
+
+function pathspecToRegex(pattern: string): RegExp {
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}
+
+function isExcludedScopedPath(path: string, exclusions: readonly string[]): boolean {
+  const normalizedPath = path.replace(/\\/g, "/");
+  for (const exclusion of exclusions) {
+    const normalizedExclusion = exclusion.replace(/^:!/, "").replace(/\\/g, "/");
+    if (!normalizedExclusion) continue;
+    if (normalizedExclusion.endsWith("/")) {
+      if (normalizedPath === normalizedExclusion.slice(0, -1) || normalizedPath.startsWith(normalizedExclusion)) {
+        return true;
+      }
+      continue;
+    }
+    if (normalizedExclusion.includes("*")) {
+      if (pathspecToRegex(normalizedExclusion).test(normalizedPath)) return true;
+      continue;
+    }
+    if (normalizedPath === normalizedExclusion) return true;
+  }
+  return false;
+}
+
 /**
  * Thrown when a slice merge hits code conflicts in non-.gsd files.
  * The working tree is left in a conflicted state (no reset) so the
@@ -658,6 +714,26 @@ export class GitServiceImpl {
     nativeAddAllWithExclusions(this.basePath, allExclusions);
   }
 
+  private scopedStageTaskFiles(
+    taskContext: TaskCommitContext,
+    extraExclusions: readonly string[] = [],
+  ): boolean {
+    const keyFiles = taskContext.keyFiles ?? [];
+    if (keyFiles.length === 0) return false;
+
+    const allExclusions = [...RUNTIME_EXCLUSION_PATHS, ...extraExclusions];
+    const paths = Array.from(new Set(
+      keyFiles
+        .map(file => normalizeRepoRelativePath(this.basePath, file))
+        .filter((file): file is string => file !== null)
+        .filter(file => !isExcludedScopedPath(file, allExclusions)),
+    ));
+    if (paths.length === 0) return false;
+
+    nativeAddPaths(this.basePath, paths);
+    return true;
+  }
+
   /** Tracks whether runtime file cleanup has run this session. */
   private _runtimeFilesCleanedUp = false;
 
@@ -697,7 +773,10 @@ export class GitServiceImpl {
     // Native path uses libgit2 (single syscall), fallback spawns git.
     if (!nativeHasChanges(this.basePath)) return null;
 
-    this.smartStage(extraExclusions);
+    const scoped = taskContext
+      ? this.scopedStageTaskFiles(taskContext, extraExclusions)
+      : false;
+    if (!scoped) this.smartStage(extraExclusions);
 
     // After smart staging, check if anything was actually staged
     // (all changes might have been runtime files that got excluded)
@@ -991,6 +1070,17 @@ function buildTurnSnapshotLabel(unitType: string, unitId: string): string {
     .replace(/^[-/]+|[-/]+$/g, "") || "turn";
 }
 
+export function handleTurnGitActionError(action: TurnGitActionMode, err: unknown): TurnGitActionResult {
+  if (isInfrastructureError(err)) {
+    throw err;
+  }
+  return {
+    action,
+    status: "failed",
+    error: getErrorMessage(err),
+  };
+}
+
 export function runTurnGitAction(args: {
   basePath: string;
   action: TurnGitActionMode;
@@ -1029,11 +1119,7 @@ export function runTurnGitAction(args: {
       dirty: nativeHasChanges(args.basePath),
     };
   } catch (err) {
-    return {
-      action: args.action,
-      status: "failed",
-      error: getErrorMessage(err),
-    };
+    return handleTurnGitActionError(args.action, err);
   }
 }